feat(appservice): @mosaicstack/appservice — Matrix AS core (M4a, agent-comms#9)

First phase of mosaic-as per agent-comms docs/design/M4-MOSAIC-AS.md: - TransactionHandler: AS transactions endpoint logic with timing-safe hs_token verification (Bearer + legacy access_token), bounded txnId dedupe (documented at-least-once limitation), handler error isolation - AppserviceIntent: virtual user registration (m.login.application_service), user_id impersonation, invite-then-join fallback, thread-aware sends (m.thread + is_falling_back), typing, display names, uuid txn ids - Registration builder + hardened YAML serializer (control-char rejection, quote escaping) for the Synapse mosaic-as.yaml - bridge.dto.ts validators for the agent-comms daemon bridge API Zero runtime deps; strict ESM/NodeNext; 14 vitest tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
fix(pi): reduce startup skill-token overhead (#527 )
2026-06-10 16:09:11 -05:00 · 2026-06-05 18:36:42 +00:00 · 2026-05-26 20:56:09 +00:00
39 changed files with 1548 additions and 140 deletions
--- a/.woodpecker/ci.yml
+++ b/.woodpecker/ci.yml
@@ -46,18 +46,28 @@ steps:
  test:
    image: *node_image
    environment:
-      DATABASE_URL: postgresql://mosaic:mosaic@postgres:5432/mosaic
+      # Avoid the namespace-level Woodpecker DB service named "postgres".
+      # The Kubernetes backend exposes service containers by step name.
+      DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
    commands:
      - *enable_pnpm
      # Install postgresql-client for pg_isready
      - apk add --no-cache postgresql-client
-      # Wait up to 30s for postgres to be ready
+      # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
      - |
-        for i in $(seq 1 30); do
-          pg_isready -h postgres -p 5432 -U mosaic && break
-          echo "Waiting for postgres ($i/30)..."
+        ready=0
+        for i in $(seq 1 60); do
+          if pg_isready -h ci-postgres -p 5432 -U mosaic; then
+            ready=1
+            break
+          fi
+          echo "Waiting for ci-postgres ($i/60)..."
          sleep 1
        done
+        if [ "$ready" -ne 1 ]; then
+          echo "ci-postgres did not become ready" >&2
+          exit 1
+        fi
      # Run migrations (DATABASE_URL is set in environment above)
      - pnpm --filter @mosaicstack/db run db:migrate
      # Run all tests
@@ -66,7 +76,7 @@ steps:
      - typecheck

 services:
-  postgres:
+  ci-postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: mosaic
--- a/README.md
+++ b/README.md
@@ -58,6 +58,8 @@ mosaic yolo pi               # Pi in yolo mode

 The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md` standards into the runtime, and forwards all arguments.

+Pi launches default to a token-lean skill posture: `mosaic pi` passes `--no-skills` so Pi does not preload every global skill description into the system prompt. Use `MOSAIC_PI_SKILL_MODE=all mosaic pi` for the legacy all-skills catalog, or `MOSAIC_PI_SKILL_MODE=discover mosaic pi` to let Pi use its native settings/project skill discovery.
+
 ### TUI & Gateway

 ```bash
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -23,7 +23,7 @@
 These are MVP-level checks that don't belong to any single workstream. Updated by the orchestrator at each session.

 | id         | status      | description                                                                                              | notes                                                                                                                         |
-| ------- | ----------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| ---------- | ----------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | MVP-T01    | done        | Author MVP-level manifest at `docs/MISSION-MANIFEST.md`                                                  | This session (2026-04-19); PR pending                                                                                         |
 | MVP-T02    | done        | Archive install-ux-v2 mission state to `docs/archive/missions/install-ux-v2-20260405/`                   | IUV-M03 retroactively closed (shipped via PR #446 + releases 0.0.27→0.0.29)                                                   |
 | MVP-T03    | done        | Land federation v1 planning artifacts on `main`                                                          | PR #468 merged 2026-04-19 (commit `66512550`)                                                                                 |
--- a/docs/scratchpads/git-wrapper-rollup-20260526.md
+++ b/docs/scratchpads/git-wrapper-rollup-20260526.md
@@ -0,0 +1,33 @@
+# Git Wrapper Rollup — 2026-05-26
+
+## Objective
+
+Consolidate pending Mosaic wrapper fixes after `mosaic update` reported the local framework package was already current (`@mosaicstack/mosaic 0.0.30`) but the installed `~/.config/mosaic/tools` wrappers still lacked the open Gitea/Woodpecker wrapper patches.
+
+## Scope
+
+Roll up the open wrapper-related Gitea PR branches into one integration branch:
+
+- PR #513: `pr-ci-wait.sh` stdin collision fix.
+- PR #518: Gitea PR metadata/merge preflight hardening.
+- PR #521: Gitea merge fallback + unsafe PR-number rejection.
+- PR #522: Woodpecker credential/pagination fixes and CI Postgres service collision fix.
+- PR #523: explicit Gitea repo/login args and `eval` removal for PR/issue creation.
+
+## Conflict resolutions
+
+- Kept array-based command construction where possible instead of reintroducing `eval`.
+- Kept explicit `--repo OWNER/REPO --login mosaicstack` Gitea arguments for `tea` calls.
+- Combined PR merge API fallback behavior from metadata hardening and empty-identity fallback branches.
+- Preserved numeric PR-number validation for `pr-merge.sh`.
+
+## Verification checklist
+
+- `bash -n` on changed shell scripts.
+- Wrapper smoke checks from a clean worktree.
+- Gitea PR verification after push.
+- CI status checked through Gitea/Woodpecker.
+
+## Notes
+
+`mosaic update` did not install these fixes because the package registry still reports `@mosaicstack/mosaic 0.0.30` as current. The source patches must merge/release before normal framework update will carry them.
--- a/docs/scratchpads/t-a292e96f-gitea-pr-metadata.md
+++ b/docs/scratchpads/t-a292e96f-gitea-pr-metadata.md
@@ -49,5 +49,5 @@ This repository currently has no root `CHANGELOG.md`; the scratchpad and `docs/T
 - Merge preflight dry runs from installed wrappers:
  - PR #1905: `Dry run: would merge PR #1905 on git.uscllc.com with authenticated Gitea API fallback (base=main, method=squash).`
  - PR #1908: `Dry run: would merge PR #1908 on git.uscllc.com with authenticated Gitea API fallback (base=main, method=squash).`
- PR: `https://git.mosaicstack.dev/mosaicstack/stack/pulls/518`, branch `fix/t-a292e96f-gitea-pr-metadata`, head `006d3f375ee9ed9e8e5ce301105d14c4e22f93e2`.
- CI: PR pipeline #1096 and manual rerun #1097 failed before clone/test execution due Woodpecker/Kubernetes PVC API timeout: `dial tcp 10.43.0.1:443: i/o timeout`. No repository test step executed in CI; local targeted verification above remains clean.
+- PR: `https://git.mosaicstack.dev/mosaicstack/stack/pulls/518`, branch `fix/t-a292e96f-gitea-pr-metadata`.
+- CI: Recent PR/push pipelines failed before clone/test execution due Woodpecker/Kubernetes PVC API timeout: `dial tcp 10.43.0.1:443: i/o timeout`. No repository test step executed in CI; local targeted verification above remains clean.
--- a/docs/scratchpads/t_301e4e3b-pr-merge-gitea-empty-uid.md
+++ b/docs/scratchpads/t_301e4e3b-pr-merge-gitea-empty-uid.md
@@ -0,0 +1,31 @@
+# Scratchpad: t_301e4e3b pr-merge.sh Gitea empty-uid fallback
+
+## Task
+
+Implement a narrow hardening in `packages/mosaic/framework/tools/git/pr-merge.sh` so Gitea merges recover from the known non-interactive `tea pr merge` identity failure: `user does not exist [uid: 0, name: ]`.
+
+## Constraints
+
+- Preserve Mosaic policy gates: squash-only, base branch `main`, queue guard unless explicitly skipped.
+- Preserve the existing authenticated Gitea API fallback when no tea login exists.
+- Do not fallback on arbitrary tea failures.
+- Do not expose tokens or credential-bearing remotes.
+- Scope is limited to the merge wrapper plus focused test/support/scratchpad files.
+
+## External issue
+
+- Gitea issue #520: Harden pr-merge.sh Gitea empty-uid fallback
+
+## Plan
+
+1. Add a focused shell regression harness with mocked `tea` and `curl` proving the known empty uid/name failure must fall back to Gitea API.
+2. Watch the harness fail on current code.
+3. Implement helper functions in `pr-merge.sh` for redacted command display, known failure classification, and authenticated Gitea API merge fallback.
+4. Keep unknown `tea` failures blocking by replaying stderr and exiting non-zero.
+5. Run syntax, shellcheck if available, focused regression, and repo quality gates before push/PR.
+
+## Session log
+
+- 2026-05-22: Read Kanban context, Mosaic global/repo instructions, created isolated branch `fix/t_301e4e3b-pr-merge-gitea-empty-uid`, and opened Gitea issue #520 using the Mosaic issue wrapper/API fallback.
+- 2026-05-22: Added regression harness and watched it fail on current behavior with `user does not exist [uid: 0, name: ]`; implemented narrow fallback and verified known-empty-identity fallback, arbitrary tea failure blocking, and no-tea-login API fallback paths.
+- 2026-05-22: Validation passed for `bash -n`, `shellcheck -x`, focused shell harness, `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, and `pnpm --filter @mosaicstack/mosaic test`. Full `pnpm test` exposed an out-of-scope gateway DB setup failure (`relation "messages" does not exist`) in `apps/gateway/src/__tests__/cross-user-isolation.test.ts`.
--- a/docs/scratchpads/t_5aab9cc8-pr-merge-eval-injection.md
+++ b/docs/scratchpads/t_5aab9cc8-pr-merge-eval-injection.md
@@ -0,0 +1,48 @@
+# t_5aab9cc8 — pr-merge.sh eval injection remediation
+
+## Objective
+
+Remediate PR #521 review blocker: `packages/mosaic/framework/tools/git/pr-merge.sh` must reject non-numeric PR numbers before metadata lookup/merge and must not use `eval` for GitHub merge execution.
+
+## Scope
+
+- Shell wrapper only: `packages/mosaic/framework/tools/git/pr-merge.sh`
+- Focused regression harness: `packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
+- No API/frontend/infra surfaces.
+
+## Acceptance Criteria
+
+- AC1: `PR_NUMBER` is validated as digits-only immediately after required-argument parsing, before metadata lookup.
+- AC2: GitHub merge path uses a quoted argv array, not command-string construction plus `eval`.
+- AC3: Focused tests prove PR-number metacharacters are rejected and cannot execute injected shell commands on GitHub path.
+- AC4: Focused tests prove PR-number metacharacters are rejected on Gitea path before tea/curl merge calls.
+- AC5: Existing Gitea empty-uid fallback behavior remains green.
+- AC6: Syntax, shellcheck where available, focused harness, and relevant repo gates are rerun or absence documented.
+
+## Plan
+
+1. Add failing regression tests for GitHub eval injection and Gitea invalid PR rejection.
+2. Implement fail-closed PR number validation before metadata lookup.
+3. Replace GitHub `eval` command with argv array execution.
+4. Run required validation and update this scratchpad with evidence.
+5. Commit, queue-guard, push branch, update PR #521.
+
+## TDD Log
+
+- RED: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh` failed on vulnerable code with `Expected GitHub metacharacter PR number to be rejected` and showed the injected PR number reached the GitHub merge path.
+- GREEN: Added digits-only validation before metadata lookup and replaced GitHub `eval` with an argv array. The focused harness now passes and verifies invalid PR numbers are rejected before GitHub `gh` calls and before Gitea `tea`/`curl` calls.
+
+## Validation Evidence
+
+- PASS: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash -n packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
+- PASS: `shellcheck -x packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
+- PASS: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
+- PASS: `pnpm --filter @mosaicstack/mosaic... build`
+- PASS: `pnpm --filter @mosaicstack/mosaic lint`
+- PASS: `pnpm --filter @mosaicstack/mosaic typecheck`
+- PASS: `pnpm --filter @mosaicstack/mosaic test` — 32 files / 291 tests passed.
+- REVIEW: `/home/hermes/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` could not run due Codex 401 Unauthorized. Independent delegate review completed read-only with PASS / no blockers; non-blocking suggestion to assert GitHub mock log remains empty was applied.
+
+## Risks / Blockers
+
+- No active blockers.
--- a/packages/appservice/package.json
+++ b/packages/appservice/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "@mosaicstack/appservice",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
+    "directory": "packages/appservice"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ]
+}
--- a/packages/appservice/src/tests/appservice.test.ts
+++ b/packages/appservice/src/tests/appservice.test.ts
@@ -0,0 +1,230 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { validateBridgeMessage, validateBridgeTyping } from '../bridge.dto.js';
+import { AppserviceIntent, MatrixApiError } from '../intent.js';
+import { buildRegistration, registrationToYaml } from '../registration.js';
+import { TransactionHandler } from '../transactions.js';
+import type { AppserviceConfig, MatrixEvent } from '../types.js';
+
+const cfg: AppserviceConfig = {
+  homeserverUrl: 'https://hs.example',
+  domain: 'hs.example',
+  asToken: 'as-secret',
+  hsToken: 'hs-secret',
+};
+
+const jsonResponse = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+
+describe('TransactionHandler', () => {
+  const makeHandler = (onEvent = vi.fn()) => ({
+    onEvent,
+    handler: new TransactionHandler({ hsToken: 'hs-secret', onEvent }),
+  });
+
+  it('rejects a bad hs_token with M_FORBIDDEN', async () => {
+    const { handler, onEvent } = makeHandler();
+    const res = await handler.handle(
+      't1',
+      { events: [{ type: 'm.room.message' }] },
+      { authorizationHeader: 'Bearer wrong' },
+    );
+    expect(res.status).toBe(403);
+    expect(res.body.errcode).toBe('M_FORBIDDEN');
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+
+  it('accepts Bearer auth and legacy access_token param', async () => {
+    const { handler } = makeHandler();
+    expect(
+      (await handler.handle('t1', { events: [] }, { authorizationHeader: 'Bearer hs-secret' }))
+        .status,
+    ).toBe(200);
+    expect(
+      (await handler.handle('t2', { events: [] }, { accessTokenParam: 'hs-secret' })).status,
+    ).toBe(200);
+  });
+
+  it('processes events once per txnId (idempotent retries)', async () => {
+    const { handler, onEvent } = makeHandler();
+    const body = { events: [{ type: 'm.room.message', event_id: '$e1' }] };
+    await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
+    const retry = await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
+    expect(retry.status).toBe(200);
+    expect(onEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it('a throwing event handler does not fail the transaction', async () => {
+    const onError = vi.fn();
+    const handler = new TransactionHandler({
+      hsToken: 'hs-secret',
+      onEvent: () => {
+        throw new Error('boom');
+      },
+      onError,
+    });
+    const res = await handler.handle(
+      't1',
+      { events: [{ type: 'x' }, { type: 'y' }] },
+      { authorizationHeader: 'Bearer hs-secret' },
+    );
+    expect(res.status).toBe(200);
+    expect(onError).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('AppserviceIntent', () => {
+  it('derives namespaced user ids and rejects bad slugs', () => {
+    const intent = new AppserviceIntent(cfg);
+    expect(intent.agentUserId('pi0-web1')).toBe('@agent-pi0-web1:hs.example');
+    expect(intent.agentUserId('Pi0-Web1')).toBe('@agent-pi0-web1:hs.example');
+    expect(() => intent.agentUserId('../evil')).toThrow();
+    expect(() => intent.agentUserId('')).toThrow();
+  });
+
+  it('uses uuid transaction ids', async () => {
+    const calls: string[] = [];
+    const fetchMock = vi.fn(async (input: URL | string) => {
+      calls.push(new URL(String(input)).pathname);
+      return jsonResponse(200, {});
+    });
+    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
+    await intent.sendAsAgent({ roomId: '!r:hs.example', agent: 'pi0', body: 'x' });
+    const send = calls.find((p) => p.includes('/send/m.room.message/'));
+    expect(send).toMatch(/mosaic-as-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  it('registers once, impersonates via user_id, threads replies', async () => {
+    const calls: Array<{ url: URL; init: RequestInit }> = [];
+    const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
+      calls.push({ url: new URL(String(input)), init: init ?? {} });
+      return jsonResponse(200, { event_id: '$sent' });
+    });
+    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
+
+    const eventId = await intent.sendAsAgent({
+      roomId: '!room:hs.example',
+      agent: 'pi0-web1',
+      body: 'hello',
+      threadRoot: '$req',
+    });
+    await intent.sendAsAgent({ roomId: '!room:hs.example', agent: 'pi0-web1', body: 'again' });
+
+    expect(eventId).toBe('$sent');
+    const paths = calls.map((c) => c.url.pathname);
+    expect(paths.filter((p) => p.endsWith('/register'))).toHaveLength(1); // cached
+    expect(paths.filter((p) => p.includes('/join'))).toHaveLength(1); // cached
+
+    const send = calls.find((c) => c.url.pathname.includes('/send/m.room.message/'));
+    expect(send).toBeDefined();
+    expect(send!.url.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
+    const content = JSON.parse(String(send!.init.body)) as Record<string, unknown>;
+    const rel = content['m.relates_to'] as Record<string, unknown>;
+    expect(rel.rel_type).toBe('m.thread');
+    expect(rel.event_id).toBe('$req');
+    expect(rel.is_falling_back).toBe(true);
+    expect(
+      calls.every(
+        (c) => (c.init.headers as Record<string, string>).Authorization === 'Bearer as-secret',
+      ),
+    ).toBe(true);
+  });
+
+  it('tolerates M_USER_IN_USE and surfaces other register errors', async () => {
+    const inUse = vi.fn(async () =>
+      jsonResponse(400, { errcode: 'M_USER_IN_USE', error: 'taken' }),
+    );
+    const intent = new AppserviceIntent(cfg, inUse as unknown as typeof fetch);
+    await expect(intent.ensureRegistered('pi0-web1')).resolves.toBe('@agent-pi0-web1:hs.example');
+
+    const denied = vi.fn(async () =>
+      jsonResponse(401, { errcode: 'M_UNKNOWN_TOKEN', error: 'nope' }),
+    );
+    const intent2 = new AppserviceIntent(cfg, denied as unknown as typeof fetch);
+    await expect(intent2.ensureRegistered('pi0-web1')).rejects.toThrow(MatrixApiError);
+  });
+
+  it('invites then joins on M_FORBIDDEN join', async () => {
+    const paths: string[] = [];
+    const fetchMock = vi.fn(async (input: URL | string) => {
+      const url = new URL(String(input));
+      paths.push(url.pathname);
+      if (url.pathname.endsWith('/join') && paths.filter((p) => p.endsWith('/join')).length === 1) {
+        return jsonResponse(403, { errcode: 'M_FORBIDDEN', error: 'not invited' });
+      }
+      return jsonResponse(200, {});
+    });
+    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
+    await intent.ensureJoined('!room:hs.example', 'pi0-web1');
+    expect(paths.filter((p) => p.endsWith('/invite'))).toHaveLength(1);
+    expect(paths.filter((p) => p.endsWith('/join'))).toHaveLength(2);
+  });
+});
+
+describe('registration', () => {
+  it('builds an exclusive escaped user namespace', () => {
+    const reg = buildRegistration(cfg, { url: 'http://mosaic-as:8008' });
+    expect(reg.namespaces.users[0]).toEqual({
+      regex: '@agent-.*:hs\\.example',
+      exclusive: true,
+    });
+    expect(reg.rate_limited).toBe(false);
+    const yaml = registrationToYaml(reg);
+    expect(yaml).toContain("sender_localpart: 'mosaic-as'");
+    expect(yaml).toContain("as_token: 'as-secret'");
+    expect(yaml).toContain('exclusive: true');
+  });
+});
+
+describe('registration hardening', () => {
+  it('rejects control characters in registration values', () => {
+    const reg = buildRegistration(
+      { ...cfg, asToken: 'abc\nhttp_injected: true' },
+      { url: 'http://mosaic-as:8008' },
+    );
+    expect(() => registrationToYaml(reg)).toThrow(/control characters/);
+  });
+
+  it('escapes single quotes in token values', () => {
+    const reg = buildRegistration({ ...cfg, asToken: "it's" }, { url: 'http://mosaic-as:8008' });
+    expect(registrationToYaml(reg)).toContain("as_token: 'it''s'");
+  });
+});
+
+describe('bridge DTOs', () => {
+  it('validates message and typing payloads', () => {
+    expect(() =>
+      validateBridgeMessage({ room_id: '!r:hs', agent: 'pi0', body: 'x' }),
+    ).not.toThrow();
+    expect(() => validateBridgeMessage({ room_id: 'bad', agent: 'pi0', body: 'x' })).toThrow();
+    expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '', body: 'x' })).toThrow();
+    expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '../evil', body: 'x' })).toThrow(
+      /agent must match/,
+    );
+    expect(() =>
+      validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: true }),
+    ).not.toThrow();
+    expect(() => validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: 'yes' })).toThrow();
+  });
+});
+
+describe('event shape', () => {
+  it('transaction events flow through to the handler', async () => {
+    const seen: MatrixEvent[] = [];
+    const handler = new TransactionHandler({
+      hsToken: 'hs-secret',
+      onEvent: (e) => void seen.push(e),
+    });
+    await handler.handle(
+      't1',
+      {
+        events: [
+          { type: 'm.room.message', room_id: '!r:hs', sender: '@u:hs', content: { body: 'hi' } },
+        ],
+      },
+      { authorizationHeader: 'Bearer hs-secret' },
+    );
+    expect(seen).toHaveLength(1);
+    expect(seen[0]!.content?.body).toBe('hi');
+  });
+});
--- a/packages/appservice/src/bridge.dto.ts
+++ b/packages/appservice/src/bridge.dto.ts
@@ -0,0 +1,52 @@
+/** DTOs for the internal bridge API consumed by agent-comms host daemons. */
+
+export interface BridgeMessageDto {
+  room_id: string;
+  /** Agent slug (localpart suffix), e.g. "pi0-web1". */
+  agent: string;
+  body: string;
+  thread_root?: string;
+  msgtype?: string;
+  /** Optional protocol payload merged into content (e.g. org.uscllc.agent). */
+  extra_content?: Record<string, unknown>;
+}
+
+export interface BridgeTypingDto {
+  room_id: string;
+  agent: string;
+  typing: boolean;
+}
+
+const AGENT_SLUG_RE = /^[a-z0-9][a-z0-9_.-]*$/;
+
+const assertAgentSlug = (agent: unknown): void => {
+  if (typeof agent !== 'string' || !AGENT_SLUG_RE.test(agent.toLowerCase())) {
+    throw new Error('agent must match [a-z0-9][a-z0-9_.-]*');
+  }
+};
+
+export function validateBridgeMessage(input: unknown): asserts input is BridgeMessageDto {
+  const o = input as Partial<BridgeMessageDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
+    throw new Error('room_id must be a Matrix room id');
+  assertAgentSlug(o.agent);
+  if (typeof o.body !== 'string') throw new Error('body must be a string');
+  if (o.thread_root !== undefined && typeof o.thread_root !== 'string')
+    throw new Error('thread_root must be a string');
+  if (
+    o.extra_content !== undefined &&
+    (typeof o.extra_content !== 'object' || o.extra_content === null)
+  ) {
+    throw new Error('extra_content must be an object');
+  }
+}
+
+export function validateBridgeTyping(input: unknown): asserts input is BridgeTypingDto {
+  const o = input as Partial<BridgeTypingDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
+    throw new Error('room_id must be a Matrix room id');
+  assertAgentSlug(o.agent);
+  if (typeof o.typing !== 'boolean') throw new Error('typing must be a boolean');
+}
--- a/packages/appservice/src/index.ts
+++ b/packages/appservice/src/index.ts
@@ -0,0 +1,15 @@
+export { AppserviceIntent, MatrixApiError } from './intent.js';
+export type { SendMessageOptions } from './intent.js';
+export { TransactionHandler } from './transactions.js';
+export type { TransactionHandlerOptions } from './transactions.js';
+export { buildRegistration, registrationToYaml } from './registration.js';
+export type { RegistrationOptions } from './registration.js';
+export { validateBridgeMessage, validateBridgeTyping } from './bridge.dto.js';
+export type { BridgeMessageDto, BridgeTypingDto } from './bridge.dto.js';
+export type {
+  AppserviceConfig,
+  EventHandler,
+  HandlerResult,
+  MatrixEvent,
+  Transaction,
+} from './types.js';
--- a/packages/appservice/src/intent.ts
+++ b/packages/appservice/src/intent.ts
@@ -0,0 +1,184 @@
+import crypto from 'node:crypto';
+
+import type { AppserviceConfig } from './types.js';
+
+export interface SendMessageOptions {
+  roomId: string;
+  /** Agent slug, e.g. "pi0-web1" -> @agent-pi0-web1:domain */
+  agent: string;
+  body: string;
+  /** Request event id to thread off (m.thread, spec v1.4). */
+  threadRoot?: string;
+  msgtype?: string;
+  /** Extra content keys merged into the message content (e.g. org.uscllc.agent). */
+  extraContent?: Record<string, unknown>;
+}
+
+export class MatrixApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly errcode: string | undefined,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'MatrixApiError';
+  }
+}
+
+type FetchLike = typeof fetch;
+
+/**
+ * Acts on the homeserver as appservice-namespaced virtual users
+ * (Application Service API: as_token auth + user_id impersonation).
+ */
+export class AppserviceIntent {
+  private readonly registered = new Set<string>();
+  private readonly joined = new Set<string>();
+  private readonly fetchImpl: FetchLike;
+
+  constructor(
+    private readonly cfg: AppserviceConfig,
+    fetchImpl?: FetchLike,
+  ) {
+    this.fetchImpl = fetchImpl ?? fetch;
+  }
+
+  get userPrefix(): string {
+    return this.cfg.userPrefix ?? 'agent-';
+  }
+
+  get senderUserId(): string {
+    return `@${this.cfg.senderLocalpart ?? 'mosaic-as'}:${this.cfg.domain}`;
+  }
+
+  agentLocalpart(agent: string): string {
+    const slug = agent.toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_.-]*$/.test(slug)) {
+      throw new Error(`invalid agent slug: ${agent}`);
+    }
+    return `${this.userPrefix}${slug}`;
+  }
+
+  agentUserId(agent: string): string {
+    return `@${this.agentLocalpart(agent)}:${this.cfg.domain}`;
+  }
+
+  private async request(
+    method: string,
+    path: string,
+    options: { userId?: string; body?: unknown } = {},
+  ): Promise<Record<string, unknown>> {
+    const url = new URL(this.cfg.homeserverUrl.replace(/\/$/, '') + path);
+    if (options.userId) {
+      url.searchParams.set('user_id', options.userId);
+    }
+    const res = await this.fetchImpl(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.cfg.asToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    });
+    const text = await res.text();
+    const data = (text ? JSON.parse(text) : {}) as Record<string, unknown>;
+    if (!res.ok) {
+      throw new MatrixApiError(
+        res.status,
+        typeof data.errcode === 'string' ? data.errcode : undefined,
+        `${method} ${path} -> ${res.status}: ${text.slice(0, 300)}`,
+      );
+    }
+    return data;
+  }
+
+  /** Register the virtual user if it does not exist yet. Idempotent. */
+  async ensureRegistered(agent: string): Promise<string> {
+    const localpart = this.agentLocalpart(agent);
+    const userId = this.agentUserId(agent);
+    if (this.registered.has(userId)) return userId;
+    try {
+      await this.request('POST', '/_matrix/client/v3/register', {
+        body: { type: 'm.login.application_service', username: localpart },
+      });
+    } catch (err) {
+      if (!(err instanceof MatrixApiError && err.errcode === 'M_USER_IN_USE')) {
+        throw err;
+      }
+    }
+    this.registered.add(userId);
+    return userId;
+  }
+
+  /** Join the agent to a room; on invite-only rooms the AS sender invites first. */
+  async ensureJoined(roomId: string, agent: string): Promise<void> {
+    const userId = await this.ensureRegistered(agent);
+    const key = `${userId} ${roomId}`;
+    if (this.joined.has(key)) return;
+    const room = encodeURIComponent(roomId);
+    try {
+      await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
+    } catch (err) {
+      if (!(err instanceof MatrixApiError && err.errcode === 'M_FORBIDDEN')) throw err;
+      await this.request('POST', `/_matrix/client/v3/rooms/${room}/invite`, {
+        userId: this.senderUserId,
+        body: { user_id: userId },
+      });
+      await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
+    }
+    this.joined.add(key);
+  }
+
+  /** Send a message AS the agent's virtual user. */
+  async sendAsAgent(options: SendMessageOptions): Promise<string | undefined> {
+    const userId = this.agentUserId(options.agent);
+    await this.ensureJoined(options.roomId, options.agent);
+    const content: Record<string, unknown> = {
+      msgtype: options.msgtype ?? 'm.text',
+      body: options.body,
+      ...options.extraContent,
+    };
+    if (options.threadRoot) {
+      content['m.relates_to'] = {
+        rel_type: 'm.thread',
+        event_id: options.threadRoot,
+        is_falling_back: true,
+        'm.in_reply_to': { event_id: options.threadRoot },
+      };
+    }
+    const txn = `mosaic-as-${crypto.randomUUID()}`;
+    const room = encodeURIComponent(options.roomId);
+    const res = await this.request(
+      'PUT',
+      `/_matrix/client/v3/rooms/${room}/send/m.room.message/${txn}`,
+      { userId, body: content },
+    );
+    return typeof res.event_id === 'string' ? res.event_id : undefined;
+  }
+
+  /** Set the agent's typing indicator in a room. */
+  async setTyping(
+    roomId: string,
+    agent: string,
+    typing: boolean,
+    timeoutMs = 30000,
+  ): Promise<void> {
+    const userId = await this.ensureRegistered(agent);
+    const room = encodeURIComponent(roomId);
+    const user = encodeURIComponent(userId);
+    await this.request('PUT', `/_matrix/client/v3/rooms/${room}/typing/${user}`, {
+      userId,
+      body: typing ? { typing: true, timeout: timeoutMs } : { typing: false },
+    });
+  }
+
+  /** Set display name for an agent's virtual user. */
+  async setDisplayName(agent: string, displayName: string): Promise<void> {
+    const userId = await this.ensureRegistered(agent);
+    const user = encodeURIComponent(userId);
+    await this.request('PUT', `/_matrix/client/v3/profile/${user}/displayname`, {
+      userId,
+      body: { displayname: displayName },
+    });
+  }
+}
--- a/packages/appservice/src/registration.ts
+++ b/packages/appservice/src/registration.ts
@@ -0,0 +1,76 @@
+import type { AppserviceConfig } from './types.js';
+
+export interface RegistrationOptions {
+  /** Unique appservice id in Synapse. Default: "mosaic-as". */
+  id?: string;
+  /** URL where Synapse reaches the appservice, e.g. http://mosaic-as:8008 */
+  url: string;
+  /** Alias namespace regex prefix. Default: "#mosaic-". */
+  aliasPrefix?: string;
+}
+
+const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Build the Synapse appservice registration document (mosaic-as.yaml).
+ * Deployment (infrastructure repo) serializes this to YAML and mounts it via
+ * app_service_config_files.
+ */
+export function buildRegistration(cfg: AppserviceConfig, options: RegistrationOptions) {
+  const prefix = cfg.userPrefix ?? 'agent-';
+  return {
+    id: options.id ?? 'mosaic-as',
+    url: options.url,
+    as_token: cfg.asToken,
+    hs_token: cfg.hsToken,
+    sender_localpart: cfg.senderLocalpart ?? 'mosaic-as',
+    rate_limited: false,
+    namespaces: {
+      users: [
+        {
+          regex: `@${escapeRegex(prefix)}.*:${escapeRegex(cfg.domain)}`,
+          exclusive: true,
+        },
+      ],
+      aliases: [
+        {
+          regex: `${escapeRegex(options.aliasPrefix ?? '#mosaic-')}.*:${escapeRegex(cfg.domain)}`,
+          exclusive: false,
+        },
+      ],
+      rooms: [],
+    },
+  };
+}
+
+const assertYamlSafe = (field: string, value: string): string => {
+  // Tokens/urls/ids are single-line opaque strings; control characters would
+  // let a crafted value terminate the scalar and inject YAML keys.
+  if (/[\r\n\x00-\x08\x0b-\x1f]/.test(value)) {
+    throw new Error(`registration field ${field} contains control characters`);
+  }
+  return value.replace(/'/g, "''");
+};
+
+/** Minimal YAML serialization for the flat registration document. */
+export function registrationToYaml(registration: ReturnType<typeof buildRegistration>): string {
+  const ns = registration.namespaces;
+  const nsBlock = (entries: Array<{ regex: string; exclusive: boolean }>): string =>
+    entries.length === 0
+      ? ' []'
+      : '\n' +
+        entries.map((e) => `    - regex: '${e.regex}'\n      exclusive: ${e.exclusive}`).join('\n');
+  return [
+    `id: '${assertYamlSafe('id', registration.id)}'`,
+    `url: '${assertYamlSafe('url', registration.url)}'`,
+    `as_token: '${assertYamlSafe('as_token', registration.as_token)}'`,
+    `hs_token: '${assertYamlSafe('hs_token', registration.hs_token)}'`,
+    `sender_localpart: '${assertYamlSafe('sender_localpart', registration.sender_localpart)}'`,
+    `rate_limited: ${registration.rate_limited}`,
+    'namespaces:',
+    `  users:${nsBlock(ns.users)}`,
+    `  aliases:${nsBlock(ns.aliases)}`,
+    `  rooms:${nsBlock(ns.rooms)}`,
+    '',
+  ].join('\n');
+}
--- a/packages/appservice/src/transactions.ts
+++ b/packages/appservice/src/transactions.ts
@@ -0,0 +1,89 @@
+import { timingSafeEqual } from 'node:crypto';
+
+import type { EventHandler, HandlerResult, Transaction } from './types.js';
+
+const MAX_SEEN_TXN_IDS = 1000;
+
+function safeTokenCompare(presented: string | undefined, expected: string): boolean {
+  if (presented === undefined) return false;
+  const a = Buffer.from(presented);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) {
+    // Compare against a same-length dummy so length is not a timing oracle.
+    timingSafeEqual(a, Buffer.alloc(a.length));
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+
+export interface TransactionHandlerOptions {
+  hsToken: string;
+  onEvent: EventHandler;
+  /** Called for handler errors; events are at-most-once, errors must not 500. */
+  onError?: (error: unknown, txnId: string) => void;
+}
+
+/**
+ * Framework-agnostic handler for the Application Service transactions API
+ * (PUT /_matrix/app/v1/transactions/{txnId}). Host apps (Fastify/Nest) wrap
+ * this in a route.
+ *
+ * Spec requirements covered: hs_token verification (Authorization: Bearer,
+ * with legacy ?access_token fallback), txnId idempotency, always-200 on
+ * accepted transactions (homeserver retries on any other status).
+ *
+ * KNOWN LIMITATION: the txnId dedupe ring is in-process memory only. After a
+ * restart the homeserver may redeliver pending transactions — event handlers
+ * must be idempotent (delivery is at-least-once across process lifetimes).
+ */
+export class TransactionHandler {
+  private readonly seen: string[] = [];
+  private readonly seenSet = new Set<string>();
+
+  constructor(private readonly options: TransactionHandlerOptions) {}
+
+  authorized(
+    authorizationHeader: string | undefined,
+    accessTokenParam: string | undefined,
+  ): boolean {
+    const bearer = authorizationHeader?.startsWith('Bearer ')
+      ? authorizationHeader.slice('Bearer '.length)
+      : undefined;
+    const presented = bearer ?? accessTokenParam;
+    return safeTokenCompare(presented, this.options.hsToken);
+  }
+
+  async handle(
+    txnId: string,
+    body: unknown,
+    auth: { authorizationHeader?: string; accessTokenParam?: string },
+  ): Promise<HandlerResult> {
+    if (!this.authorized(auth.authorizationHeader, auth.accessTokenParam)) {
+      return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad hs_token' } };
+    }
+    if (this.seenSet.has(txnId)) {
+      return { status: 200, body: {} };
+    }
+    this.markSeen(txnId);
+    const txn = (body ?? {}) as Partial<Transaction>;
+    for (const event of txn.events ?? []) {
+      try {
+        await this.options.onEvent(event);
+      } catch (error) {
+        // A failing handler must not fail the transaction: the homeserver
+        // would retry the whole batch forever.
+        this.options.onError?.(error, txnId);
+      }
+    }
+    return { status: 200, body: {} };
+  }
+
+  private markSeen(txnId: string): void {
+    this.seen.push(txnId);
+    this.seenSet.add(txnId);
+    while (this.seen.length > MAX_SEEN_TXN_IDS) {
+      const evicted = this.seen.shift();
+      if (evicted !== undefined) this.seenSet.delete(evicted);
+    }
+  }
+}
--- a/packages/appservice/src/types.ts
+++ b/packages/appservice/src/types.ts
@@ -0,0 +1,35 @@
+export interface AppserviceConfig {
+  /** Homeserver client-server API base, e.g. https://chat.uscllc.com */
+  homeserverUrl: string;
+  /** Server name used in user IDs, e.g. chat.uscllc.com */
+  domain: string;
+  /** Token the appservice presents to the homeserver (as_token). */
+  asToken: string;
+  /** Token the homeserver presents to the appservice (hs_token). */
+  hsToken: string;
+  /** Localpart prefix owned by this appservice. Default: "agent-". */
+  userPrefix?: string;
+  /** The appservice's own sender user localpart. Default: "mosaic-as". */
+  senderLocalpart?: string;
+}
+
+export interface MatrixEvent {
+  type: string;
+  event_id?: string;
+  room_id?: string;
+  sender?: string;
+  state_key?: string;
+  content?: Record<string, unknown>;
+  origin_server_ts?: number;
+}
+
+export interface Transaction {
+  events: MatrixEvent[];
+}
+
+export type EventHandler = (event: MatrixEvent) => void | Promise<void>;
+
+export interface HandlerResult {
+  status: number;
+  body: Record<string, unknown>;
+}
--- a/packages/appservice/tsconfig.json
+++ b/packages/appservice/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
--- a/packages/mosaic/framework/tools/_lib/credentials.sh
+++ b/packages/mosaic/framework/tools/_lib/credentials.sh
@@ -52,6 +52,20 @@ _mosaic_sync_woodpecker_env() {
  printf '%s\n' "$expected" > "$env_file"
 }

+# Load legacy flat Woodpecker credentials (.woodpecker.url / .woodpecker.token).
+# Some environments export WOODPECKER_INSTANCE=mosaic, but the current
+# credentials.json may still use the legacy flat schema. Treat "mosaic" as the
+# default flat instance when a nested .woodpecker.mosaic object is absent.
+_mosaic_load_woodpecker_legacy() {
+  export WOODPECKER_URL="$(_mosaic_read_cred '.woodpecker.url')"
+  export WOODPECKER_TOKEN="$(_mosaic_read_cred '.woodpecker.token')"
+  export WOODPECKER_INSTANCE="${WOODPECKER_INSTANCE:-mosaic}"
+  WOODPECKER_URL="${WOODPECKER_URL%/}"
+  [[ -n "$WOODPECKER_URL" ]] || { echo "Error: woodpecker.url not found" >&2; return 1; }
+  [[ -n "$WOODPECKER_TOKEN" ]] || { echo "Error: woodpecker.token not found" >&2; return 1; }
+  _mosaic_sync_woodpecker_env "$WOODPECKER_INSTANCE" "$WOODPECKER_URL" "$WOODPECKER_TOKEN"
+}
+
 load_credentials() {
  local service="$1"

@@ -155,7 +169,14 @@ EOF
      ;;
    woodpecker-*)
      local wp_instance="${service#woodpecker-}"
-      # credentials.json is authoritative — always read from it, ignore env
+      # credentials.json is authoritative — always read from it, ignore env.
+      # Backward compatibility: the default Mosaic Woodpecker instance may be
+      # stored in the legacy flat schema (.woodpecker.url/.token) instead of
+      # .woodpecker.mosaic.url/.token.
+      if [[ "$wp_instance" == "mosaic" ]] && [[ -z "$(_mosaic_read_cred '.woodpecker.mosaic.url')" ]] && [[ -n "$(_mosaic_read_cred '.woodpecker.url')" ]]; then
+        WOODPECKER_INSTANCE="mosaic" _mosaic_load_woodpecker_legacy
+        return $?
+      fi
      export WOODPECKER_URL="$(_mosaic_read_cred ".woodpecker.${wp_instance}.url")"
      export WOODPECKER_TOKEN="$(_mosaic_read_cred ".woodpecker.${wp_instance}.token")"
      export WOODPECKER_INSTANCE="$wp_instance"
@@ -166,7 +187,10 @@ EOF
      _mosaic_sync_woodpecker_env "$wp_instance" "$WOODPECKER_URL" "$WOODPECKER_TOKEN"
      ;;
    woodpecker)
-      # Resolve default instance, then load it
+      # Resolve default instance, then load it. If WOODPECKER_INSTANCE is set to
+      # "mosaic" by a shell/profile but credentials.json still uses the legacy
+      # flat .woodpecker.url/.token schema, load the flat credentials instead of
+      # failing with "woodpecker.mosaic.url not found".
      local wp_default
      wp_default="${WOODPECKER_INSTANCE:-$(_mosaic_read_cred '.woodpecker.default')}"
      if [[ -z "$wp_default" ]]; then
@@ -174,19 +198,19 @@ EOF
        local legacy_url
        legacy_url="$(_mosaic_read_cred '.woodpecker.url')"
        if [[ -n "$legacy_url" ]]; then
-          export WOODPECKER_URL="${WOODPECKER_URL:-$legacy_url}"
-          export WOODPECKER_TOKEN="${WOODPECKER_TOKEN:-$(_mosaic_read_cred '.woodpecker.token')}"
-          WOODPECKER_URL="${WOODPECKER_URL%/}"
-          [[ -n "$WOODPECKER_URL" ]] || { echo "Error: woodpecker.url not found" >&2; return 1; }
-          [[ -n "$WOODPECKER_TOKEN" ]] || { echo "Error: woodpecker.token not found" >&2; return 1; }
+          _mosaic_load_woodpecker_legacy
        else
          echo "Error: woodpecker.default not set and no WOODPECKER_INSTANCE env var" >&2
          echo "Available instances: $(jq -r '.woodpecker | keys | join(", ")' "$MOSAIC_CREDENTIALS_FILE" 2>/dev/null)" >&2
          return 1
        fi
+      else
+        if [[ "$wp_default" == "mosaic" ]] && [[ -z "$(_mosaic_read_cred '.woodpecker.mosaic.url')" ]] && [[ -n "$(_mosaic_read_cred '.woodpecker.url')" ]]; then
+          WOODPECKER_INSTANCE="mosaic" _mosaic_load_woodpecker_legacy
        else
          load_credentials "woodpecker-${wp_default}"
        fi
+      fi
      ;;
    cloudflare-*)
      local cf_instance="${service#cloudflare-}"
--- a/packages/mosaic/framework/tools/git/ci-queue-wait.sh
+++ b/packages/mosaic/framework/tools/git/ci-queue-wait.sh
@@ -137,7 +137,7 @@ gitea_get_branch_head_sha() {
    local branch="$3"
    local token="$4"
    local url="https://${host}/api/v1/repos/${repo}/branches/${branch}"
-    curl -fsS -H "Authorization: token ${token}" "$url" | python3 -c '
+    curl -fsSL -H "Authorization: token ${token}" "$url" | python3 -c '
 import json, sys
 data = json.load(sys.stdin)
 commit = data.get("commit") or {}
@@ -151,7 +151,7 @@ gitea_get_commit_status_json() {
    local sha="$3"
    local token="$4"
    local url="https://${host}/api/v1/repos/${repo}/commits/${sha}/status"
-    curl -fsS -H "Authorization: token ${token}" "$url"
+    curl -fsSL -H "Authorization: token ${token}" "$url"
 }

 while [[ $# -gt 0 ]]; do
--- a/packages/mosaic/framework/tools/git/detect-platform.sh
+++ b/packages/mosaic/framework/tools/git/detect-platform.sh
@@ -74,6 +74,16 @@ get_repo_name() {
    echo "${repo_info##*/}"
 }

+get_repo_slug() {
+    get_repo_info
+}
+
+get_gitea_repo_args() {
+    local repo
+    repo=$(get_repo_slug) || return 1
+    printf -- '--repo %q --login %q' "$repo" "${GITEA_LOGIN:-mosaicstack}"
+}
+
 get_remote_host() {
    local remote_url
    remote_url=$(git remote get-url origin 2>/dev/null || true)
--- a/packages/mosaic/framework/tools/git/issue-comment.sh
+++ b/packages/mosaic/framework/tools/git/issue-comment.sh
@@ -53,7 +53,7 @@ if [[ "$PLATFORM" == "github" ]]; then
    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
    echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    tea issue comment "$ISSUE_NUMBER" "$COMMENT"
+    tea issue comment "$ISSUE_NUMBER" "$COMMENT" $(get_gitea_repo_args)
    echo "Added comment to Gitea issue #$ISSUE_NUMBER"
 else
    echo "Error: Unknown platform"
--- a/packages/mosaic/framework/tools/git/issue-create.sh
+++ b/packages/mosaic/framework/tools/git/issue-create.sh
@@ -112,20 +112,22 @@ PLATFORM=$(detect_platform)

 case "$PLATFORM" in
    github)
-        CMD="gh issue create --title \"$TITLE\""
-        [[ -n "$BODY" ]] && CMD="$CMD --body \"$BODY\""
-        [[ -n "$LABELS" ]] && CMD="$CMD --label \"$LABELS\""
-        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-        eval "$CMD"
+        CMD=(gh issue create --title "$TITLE")
+        [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
+        [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
+        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+        "${CMD[@]}"
        ;;
    gitea)
        if command -v tea >/dev/null 2>&1; then
-            CMD="tea issue create --title \"$TITLE\""
-            [[ -n "$BODY" ]] && CMD="$CMD --description \"$BODY\""
-            [[ -n "$LABELS" ]] && CMD="$CMD --labels \"$LABELS\""
+            REPO_SLUG=$(get_repo_slug)
+            REPO_ARGS=(--repo "$REPO_SLUG" --login "${GITEA_LOGIN:-mosaicstack}")
+            CMD=(tea issue create "${REPO_ARGS[@]}" --title "$TITLE")
+            [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
+            [[ -n "$LABELS" ]] && CMD+=(--labels "$LABELS")
            # tea accepts milestone by name directly (verified 2026-02-05)
-            [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-            if eval "$CMD"; then
+            [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+            if "${CMD[@]}"; then
                exit 0
            fi
            echo "Warning: tea issue create failed, trying Gitea API fallback..." >&2
--- a/packages/mosaic/framework/tools/git/issue-list.sh
+++ b/packages/mosaic/framework/tools/git/issue-list.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # issue-list.sh - List issues on Gitea or GitHub
-# Usage: issue-list.sh [-s state] [-l label] [-m milestone] [-a assignee]
+# Usage: issue-list.sh [-r owner/repo] [-s state] [-l label] [-m milestone] [-a assignee]

 set -e

@@ -13,6 +13,7 @@ LABEL=""
 MILESTONE=""
 ASSIGNEE=""
 LIMIT=100
+REPO_OVERRIDE=""

 usage() {
    cat <<EOF
@@ -26,12 +27,14 @@ Options:
    -m, --milestone NAME    Filter by milestone name
    -a, --assignee USER     Filter by assignee
    -n, --limit N           Maximum issues to show (default: 100)
+    -r, --repo OWNER/REPO   Repository slug (default: infer from git origin)
    -h, --help              Show this help message

 Examples:
    $(basename "$0")                          # List open issues
    $(basename "$0") -s all -l bug            # All issues with 'bug' label
    $(basename "$0") -m "0.2.0"               # Issues in milestone 0.2.0
+    $(basename "$0") --repo ddk/ai-bma         # List issues from anywhere
 EOF
    exit 1
 }
@@ -59,6 +62,10 @@ while [[ $# -gt 0 ]]; do
            LIMIT="$2"
            shift 2
            ;;
+        -r|--repo)
+            REPO_OVERRIDE="$2"
+            shift 2
+            ;;
        -h|--help)
            usage
            ;;
@@ -69,25 +76,34 @@ while [[ $# -gt 0 ]]; do
    esac
 done

+if [[ -n "$REPO_OVERRIDE" ]]; then
+    REPO_INFO="$REPO_OVERRIDE"
+    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
+else
    PLATFORM=$(detect_platform)
+    REPO_INFO=$(get_repo_info)
+fi
+
+if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
+    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
+    exit 1
+fi

 case "$PLATFORM" in
    github)
-        CMD="gh issue list --state $STATE --limit $LIMIT"
-        [[ -n "$LABEL" ]] && CMD="$CMD --label \"$LABEL\""
-        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-        [[ -n "$ASSIGNEE" ]] && CMD="$CMD --assignee \"$ASSIGNEE\""
-        eval "$CMD"
+        CMD=(gh issue list --repo "$REPO_INFO" --state "$STATE" --limit "$LIMIT")
+        [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
+        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+        [[ -n "$ASSIGNEE" ]] && CMD+=(--assignee "$ASSIGNEE")
+        "${CMD[@]}"
        ;;
    gitea)
-        CMD="tea issues list --state $STATE --limit $LIMIT"
-        [[ -n "$LABEL" ]] && CMD="$CMD --labels \"$LABEL\""
-        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestones \"$MILESTONE\""
-        # Note: tea may not support assignee filter directly
-        eval "$CMD"
-        if [[ -n "$ASSIGNEE" ]]; then
-            echo "Note: Assignee filtering may require manual review for Gitea" >&2
-        fi
+        CMD=(tea issues list --repo "$REPO_INFO" --login "${GITEA_LOGIN:-mosaicstack}" --state "$STATE" --limit "$LIMIT")
+        [[ -n "$LABEL" ]] && CMD+=(--labels "$LABEL")
+        [[ -n "$MILESTONE" ]] && CMD+=(--milestones "$MILESTONE")
+        # Note: tea may not support assignee filter directly in all versions.
+        [[ -n "$ASSIGNEE" ]] && echo "Note: Assignee filtering may require manual review for Gitea" >&2
+        "${CMD[@]}"
        ;;
    *)
        echo "Error: Could not detect git platform" >&2
--- a/packages/mosaic/framework/tools/git/issue-reopen.sh
+++ b/packages/mosaic/framework/tools/git/issue-reopen.sh
@@ -52,9 +52,9 @@ if [[ "$PLATFORM" == "github" ]]; then
    echo "Reopened GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    if [[ -n "$COMMENT" ]]; then
-        tea issue comment "$ISSUE_NUMBER" "$COMMENT"
+        tea issue comment "$ISSUE_NUMBER" "$COMMENT" $(get_gitea_repo_args)
    fi
-    tea issue reopen "$ISSUE_NUMBER"
+    tea issue reopen "$ISSUE_NUMBER" $(get_gitea_repo_args)
    echo "Reopened Gitea issue #$ISSUE_NUMBER"
 else
    echo "Error: Unknown platform"
--- a/packages/mosaic/framework/tools/git/issue-view.sh
+++ b/packages/mosaic/framework/tools/git/issue-view.sh
@@ -67,7 +67,7 @@ if [[ "$PLATFORM" == "github" ]]; then
    gh issue view "$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    if command -v tea >/dev/null 2>&1; then
-        if tea issue "$ISSUE_NUMBER"; then
+        if tea issue "$ISSUE_NUMBER" $(get_gitea_repo_args); then
            exit 0
        fi
        echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
--- a/packages/mosaic/framework/tools/git/pr-ci-wait.sh
+++ b/packages/mosaic/framework/tools/git/pr-ci-wait.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-ci-wait.sh - Wait for PR CI status to reach terminal state (GitHub/Gitea)
-# Usage: pr-ci-wait.sh -n <pr_number> [-t timeout_sec] [-i interval_sec]
+# Usage: pr-ci-wait.sh -n <pr_number> [-r owner/repo] [-t timeout_sec] [-i interval_sec]

 set -euo pipefail

@@ -10,6 +10,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 TIMEOUT_SEC=1800
 INTERVAL_SEC=15
+REPO_OVERRIDE=""

 usage() {
    cat <<EOF
@@ -17,12 +18,14 @@ Usage: $(basename "$0") -n <pr_number> [-t timeout_sec] [-i interval_sec]

 Options:
  -n, --number NUMBER      PR number (required)
+  -r, --repo OWNER/REPO    Repository slug (default: infer from git origin)
  -t, --timeout SECONDS    Max wait time in seconds (default: 1800)
  -i, --interval SECONDS   Poll interval in seconds (default: 15)
  -h, --help               Show this help

 Examples:
  $(basename "$0") -n 643
+  $(basename "$0") -n 643 --repo ddk/ai-bma
  $(basename "$0") -n 643 -t 900 -i 10
 EOF
 }
@@ -30,12 +33,19 @@ EOF
 # get_remote_host and get_gitea_token are provided by detect-platform.sh

 extract_state_from_status_json() {
-    python3 - <<'PY'
+    # Capture piped JSON BEFORE invoking `python3 - <<PY`. The heredoc binds
+    # stdin to the Python program text — so json.load(sys.stdin) inside would
+    # try to re-read stdin after `-` already consumed it for the program,
+    # yielding EOF and returning "unknown" every time. Pass payload via env.
+    local payload
+    payload=$(cat)
+    PR_CI_STATUS_JSON="$payload" python3 - <<'PY'
 import json
+import os
 import sys

 try:
-    payload = json.load(sys.stdin)
+    payload = json.loads(os.environ.get("PR_CI_STATUS_JSON", ""))
 except Exception:
    print("unknown")
    raise SystemExit(0)
@@ -66,12 +76,16 @@ PY
 }

 print_status_summary() {
-    python3 - <<'PY'
+    # Same stdin-collision fix as extract_state_from_status_json above.
+    local payload
+    payload=$(cat)
+    PR_CI_STATUS_JSON="$payload" python3 - <<'PY'
 import json
+import os
 import sys

 try:
-    payload = json.load(sys.stdin)
+    payload = json.loads(os.environ.get("PR_CI_STATUS_JSON", ""))
 except Exception:
    print("[pr-ci-wait] status payload unavailable")
    raise SystemExit(0)
@@ -95,7 +109,7 @@ PY
 }

 github_get_pr_head_sha() {
-    gh pr view "$PR_NUMBER" --json headRefOid --jq '.headRefOid'
+    gh pr view "$PR_NUMBER" --repo "$OWNER/$REPO" --json headRefOid --jq '.headRefOid'
 }

 github_get_commit_status_json() {
@@ -110,7 +124,7 @@ gitea_get_pr_head_sha() {
    local repo="$2"
    local token="$3"
    local url="https://${host}/api/v1/repos/${repo}/pulls/${PR_NUMBER}"
-    curl -fsS -H "Authorization: token ${token}" "$url" | python3 -c '
+    curl -fsSL -H "Authorization: token ${token}" "$url" | python3 -c '
 import json, sys
 data = json.load(sys.stdin)
 print((data.get("head") or {}).get("sha", ""))
@@ -123,7 +137,7 @@ gitea_get_commit_status_json() {
    local token="$3"
    local sha="$4"
    local url="https://${host}/api/v1/repos/${repo}/commits/${sha}/status"
-    curl -fsS -H "Authorization: token ${token}" "$url"
+    curl -fsSL -H "Authorization: token ${token}" "$url"
 }

 while [[ $# -gt 0 ]]; do
@@ -132,6 +146,10 @@ while [[ $# -gt 0 ]]; do
            PR_NUMBER="$2"
            shift 2
            ;;
+        -r|--repo)
+            REPO_OVERRIDE="$2"
+            shift 2
+            ;;
        -t|--timeout)
            TIMEOUT_SEC="$2"
            shift 2
@@ -163,10 +181,21 @@ if ! [[ "$TIMEOUT_SEC" =~ ^[0-9]+$ ]] || ! [[ "$INTERVAL_SEC" =~ ^[0-9]+$ ]]; th
    exit 1
 fi

+if [[ -n "$REPO_OVERRIDE" ]]; then
+    REPO_INFO="$REPO_OVERRIDE"
+    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
+else
    detect_platform > /dev/null
+    REPO_INFO=$(get_repo_info)
+fi

-OWNER=$(get_repo_owner)
-REPO=$(get_repo_name)
+if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* || "$REPO_INFO" != */* ]]; then
+    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo owner/repo." >&2
+    exit 1
+fi
+
+OWNER=${REPO_INFO%%/*}
+REPO=${REPO_INFO##*/}
 START_TS=$(date +%s)
 DEADLINE_TS=$((START_TS + TIMEOUT_SEC))

@@ -182,10 +211,7 @@ if [[ "$PLATFORM" == "github" ]]; then
    fi
    echo "[pr-ci-wait] Platform=github PR=#${PR_NUMBER} head_sha=${HEAD_SHA}"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    HOST=$(get_remote_host) || {
-        echo "Error: Could not determine remote host." >&2
-        exit 1
-    }
+    HOST=$(get_remote_host 2>/dev/null || echo "git.mosaicstack.dev")
    TOKEN=$(get_gitea_token "$HOST") || {
        echo "Error: Gitea token not found. Set GITEA_TOKEN or configure ~/.git-credentials." >&2
        exit 1
@@ -195,7 +221,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
        echo "Error: Could not resolve head SHA for PR #$PR_NUMBER." >&2
        exit 1
    fi
-    echo "[pr-ci-wait] Platform=gitea host=${HOST} PR=#${PR_NUMBER} head_sha=${HEAD_SHA}"
+    echo "[pr-ci-wait] Platform=gitea host=${HOST} repo=${OWNER}/${REPO} PR=#${PR_NUMBER} head_sha=${HEAD_SHA}"
 else
    echo "Error: Unsupported platform '${PLATFORM}'." >&2
    exit 1
--- a/packages/mosaic/framework/tools/git/pr-close.sh
+++ b/packages/mosaic/framework/tools/git/pr-close.sh
@@ -52,9 +52,9 @@ if [[ "$PLATFORM" == "github" ]]; then
    echo "Closed GitHub PR #$PR_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    if [[ -n "$COMMENT" ]]; then
-        tea pr comment "$PR_NUMBER" "$COMMENT"
+        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
    fi
-    tea pr close "$PR_NUMBER"
+    tea pr close "$PR_NUMBER" $(get_gitea_repo_args)
    echo "Closed Gitea PR #$PR_NUMBER"
 else
    echo "Error: Unknown platform"
--- a/packages/mosaic/framework/tools/git/pr-create.sh
+++ b/packages/mosaic/framework/tools/git/pr-create.sh
@@ -17,6 +17,51 @@ MILESTONE=""
 DRAFT=false
 ISSUE=""

+# get_remote_host, get_gitea_token, get_repo_info, and get_gitea_repo_args are provided by detect-platform.sh
+
+gitea_pr_create_api() {
+    local host repo token url payload
+    host=$(get_remote_host) || {
+        echo "Error: could not determine remote host for API fallback" >&2
+        return 1
+    }
+    repo=$(get_repo_info) || {
+        echo "Error: could not determine repo owner/name for API fallback" >&2
+        return 1
+    }
+    token=$(get_gitea_token "$host") || {
+        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
+        return 1
+    }
+
+    if [[ -n "$LABELS" || -n "$MILESTONE" || "$DRAFT" == true ]]; then
+        echo "Warning: API fallback applies title/body/head/base only; labels/milestone/draft require authenticated tea setup." >&2
+    fi
+
+    payload=$(TITLE="$TITLE" BODY="$BODY" HEAD_BRANCH="$HEAD_BRANCH" BASE_BRANCH="$BASE_BRANCH" python3 - <<'PY'
+import json
+import os
+
+payload = {
+    "title": os.environ["TITLE"],
+    "head": os.environ["HEAD_BRANCH"],
+    "base": os.environ["BASE_BRANCH"] or "main",
+}
+body = os.environ.get("BODY", "")
+if body:
+    payload["body"] = body
+print(json.dumps(payload))
+PY
+)
+
+    url="https://${host}/api/v1/repos/${repo}/pulls"
+    curl -fsS -X POST \
+      -H "Authorization: token ${token}" \
+      -H "Content-Type: application/json" \
+      -d "$payload" \
+      "$url"
+}
+
 usage() {
    cat <<EOF
 Usage: $(basename "$0") [OPTIONS]
@@ -118,33 +163,37 @@ PLATFORM=$(detect_platform)

 case "$PLATFORM" in
    github)
-        CMD="gh pr create --title \"$TITLE\""
-        [[ -n "$BODY" ]] && CMD="$CMD --body \"$BODY\""
-        [[ -n "$BASE_BRANCH" ]] && CMD="$CMD --base \"$BASE_BRANCH\""
-        [[ -n "$HEAD_BRANCH" ]] && CMD="$CMD --head \"$HEAD_BRANCH\""
-        [[ -n "$LABELS" ]] && CMD="$CMD --label \"$LABELS\""
-        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-        [[ "$DRAFT" == true ]] && CMD="$CMD --draft"
-        eval "$CMD"
+        CMD=(gh pr create --title "$TITLE")
+        [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
+        [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
+        [[ -n "$HEAD_BRANCH" ]] && CMD+=(--head "$HEAD_BRANCH")
+        [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
+        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+        [[ "$DRAFT" == true ]] && CMD+=(--draft)
+        "${CMD[@]}"
        ;;
    gitea)
-        # tea pull create syntax
-        CMD="tea pr create --title \"$TITLE\""
-        [[ -n "$BODY" ]] && CMD="$CMD --description \"$BODY\""
-        [[ -n "$BASE_BRANCH" ]] && CMD="$CMD --base \"$BASE_BRANCH\""
-        [[ -n "$HEAD_BRANCH" ]] && CMD="$CMD --head \"$HEAD_BRANCH\""
+        # tea pull create syntax. Always pass --repo because tea repo inference
+        # is unreliable in Mosaic worktrees/profile shells. Use arrays instead
+        # of eval so markdown backticks/body content are not shell-executed.
+        REPO_SLUG=$(get_repo_slug)
+        REPO_ARGS=(--repo "$REPO_SLUG" --login "${GITEA_LOGIN:-mosaicstack}")
+        CMD=(tea pr create "${REPO_ARGS[@]}" --title "$TITLE")
+        [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
+        [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
+        [[ -n "$HEAD_BRANCH" ]] && CMD+=(--head "$HEAD_BRANCH")

        # Handle labels for tea
        if [[ -n "$LABELS" ]]; then
            # tea may use --labels flag
-            CMD="$CMD --labels \"$LABELS\""
+            CMD+=(--labels "$LABELS")
        fi

        # Handle milestone for tea
        if [[ -n "$MILESTONE" ]]; then
-            MILESTONE_ID=$(tea milestones list 2>/dev/null | grep -E "^\s*[0-9]+" | grep "$MILESTONE" | awk '{print $1}' | head -1)
+            MILESTONE_ID=$(tea milestones list "${REPO_ARGS[@]}" 2>/dev/null | grep -E "^\s*[0-9]+" | grep "$MILESTONE" | awk '{print $1}' | head -1)
            if [[ -n "$MILESTONE_ID" ]]; then
-                CMD="$CMD --milestone $MILESTONE_ID"
+                CMD+=(--milestone "$MILESTONE_ID")
            else
                echo "Warning: Could not find milestone '$MILESTONE', creating without milestone" >&2
            fi
@@ -155,7 +204,11 @@ case "$PLATFORM" in
            echo "Note: Draft PR may not be supported by your tea version" >&2
        fi

-        eval "$CMD"
+        if "${CMD[@]}"; then
+            exit 0
+        fi
+        echo "Warning: tea pr create failed, trying Gitea API fallback..." >&2
+        gitea_pr_create_api
        ;;
    *)
        echo "Error: Could not detect git platform" >&2
--- a/packages/mosaic/framework/tools/git/pr-diff.sh
+++ b/packages/mosaic/framework/tools/git/pr-diff.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-diff.sh - Get the diff for a pull request on GitHub or Gitea
-# Usage: pr-diff.sh -n <pr_number> [-o <output_file>]
+# Usage: pr-diff.sh -n <pr_number> [-r owner/repo] [-o <output_file>]

 set -e

@@ -10,6 +10,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 PR_NUMBER=""
 OUTPUT_FILE=""
+REPO_OVERRIDE=""

 while [[ $# -gt 0 ]]; do
    case $1 in
@@ -21,11 +22,16 @@ while [[ $# -gt 0 ]]; do
            OUTPUT_FILE="$2"
            shift 2
            ;;
+        -r|--repo)
+            REPO_OVERRIDE="$2"
+            shift 2
+            ;;
        -h|--help)
-            echo "Usage: pr-diff.sh -n <pr_number> [-o <output_file>]"
+            echo "Usage: pr-diff.sh -n <pr_number> [-r owner/repo] [-o <output_file>]"
            echo ""
            echo "Options:"
            echo "  -n, --number   PR number (required)"
+            echo "  -r, --repo     Repository slug (default: infer from git origin)"
            echo "  -o, --output   Output file (optional, prints to stdout if omitted)"
            echo "  -h, --help     Show this help"
            exit 0
@@ -42,31 +48,30 @@ if [[ -z "$PR_NUMBER" ]]; then
    exit 1
 fi

+if [[ -n "$REPO_OVERRIDE" ]]; then
+    REPO_INFO="$REPO_OVERRIDE"
+    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
+else
    detect_platform > /dev/null
-
-if [[ "$PLATFORM" == "github" ]]; then
-    if [[ -n "$OUTPUT_FILE" ]]; then
-        gh pr diff "$PR_NUMBER" > "$OUTPUT_FILE"
-    else
-        gh pr diff "$PR_NUMBER"
+    REPO_INFO=$(get_repo_info)
 fi
-elif [[ "$PLATFORM" == "gitea" ]]; then
-    # tea doesn't have a direct diff command — use the API
-    OWNER=$(get_repo_owner)
-    REPO=$(get_repo_name)
-    REMOTE_URL=$(git remote get-url origin 2>/dev/null)

-    # Extract host from remote URL
-    if [[ "$REMOTE_URL" == https://* ]]; then
-        HOST=$(echo "$REMOTE_URL" | sed -E 's|https://([^/]+)/.*|\1|')
-    elif [[ "$REMOTE_URL" == git@* ]]; then
-        HOST=$(echo "$REMOTE_URL" | sed -E 's|git@([^:]+):.*|\1|')
-    else
-        echo "Error: Cannot determine host from remote URL" >&2
+if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
+    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
    exit 1
 fi

-    DIFF_URL="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}.diff"
+if [[ "$PLATFORM" == "github" ]]; then
+    if [[ -n "$OUTPUT_FILE" ]]; then
+        gh pr diff "$PR_NUMBER" --repo "$REPO_INFO" > "$OUTPUT_FILE"
+    else
+        gh pr diff "$PR_NUMBER" --repo "$REPO_INFO"
+    fi
+elif [[ "$PLATFORM" == "gitea" ]]; then
+    # tea doesn't have a direct diff command — use the API
+    HOST=$(get_remote_host 2>/dev/null || echo "git.mosaicstack.dev")
+
+    DIFF_URL="https://${HOST}/api/v1/repos/${REPO_INFO}/pulls/${PR_NUMBER}.diff"

    GITEA_API_TOKEN=$(get_gitea_token "$HOST" || true)

--- a/packages/mosaic/framework/tools/git/pr-list.sh
+++ b/packages/mosaic/framework/tools/git/pr-list.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-list.sh - List pull requests on Gitea or GitHub
-# Usage: pr-list.sh [-s state] [-l label] [-a author]
+# Usage: pr-list.sh [-r owner/repo] [-s state] [-l label] [-a author]

 set -e

@@ -12,6 +12,7 @@ STATE="open"
 LABEL=""
 AUTHOR=""
 LIMIT=100
+REPO_OVERRIDE=""

 usage() {
    cat <<EOF
@@ -24,12 +25,14 @@ Options:
    -l, --label LABEL       Filter by label
    -a, --author USER       Filter by author
    -n, --limit N           Maximum PRs to show (default: 100)
+    -r, --repo OWNER/REPO   Repository slug (default: infer from git origin)
    -h, --help              Show this help message

 Examples:
    $(basename "$0")                          # List open PRs
    $(basename "$0") -s all                   # All PRs
    $(basename "$0") -s merged -a username    # Merged PRs by user
+    $(basename "$0") --repo ddk/ai-bma         # List PRs from anywhere
 EOF
    exit 1
 }
@@ -53,6 +56,10 @@ while [[ $# -gt 0 ]]; do
            LIMIT="$2"
            shift 2
            ;;
+        -r|--repo)
+            REPO_OVERRIDE="$2"
+            shift 2
+            ;;
        -h|--help)
            usage
            ;;
@@ -63,18 +70,30 @@ while [[ $# -gt 0 ]]; do
    esac
 done

+if [[ -n "$REPO_OVERRIDE" ]]; then
+    REPO_INFO="$REPO_OVERRIDE"
+    # Explicit --repo is primarily for Gitea wrappers; if a git origin is present,
+    # still honor GitHub detection for cross-platform behavior.
+    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
+else
    PLATFORM=$(detect_platform)
+    REPO_INFO=$(get_repo_info)
+fi
+
+if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
+    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
+    exit 1
+fi

 case "$PLATFORM" in
    github)
-        CMD="gh pr list --state $STATE --limit $LIMIT"
-        [[ -n "$LABEL" ]] && CMD="$CMD --label \"$LABEL\""
-        [[ -n "$AUTHOR" ]] && CMD="$CMD --author \"$AUTHOR\""
-        eval "$CMD"
+        CMD=(gh pr list --repo "$REPO_INFO" --state "$STATE" --limit "$LIMIT")
+        [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
+        [[ -n "$AUTHOR" ]] && CMD+=(--author "$AUTHOR")
+        "${CMD[@]}"
        ;;
    gitea)
-        # tea pr list - note: tea uses 'pulls' subcommand in some versions
-        CMD="tea pr list --state $STATE --limit $LIMIT"
+        CMD=(tea pr list --repo "$REPO_INFO" --login "${GITEA_LOGIN:-mosaicstack}" --state "$STATE" --limit "$LIMIT")

        # tea filtering may be limited
        if [[ -n "$LABEL" ]]; then
@@ -84,7 +103,7 @@ case "$PLATFORM" in
            echo "Note: Author filtering may require manual review for Gitea" >&2
        fi

-        eval "$CMD"
+        "${CMD[@]}"
        ;;
    *)
        echo "Error: Could not detect git platform" >&2
--- a/packages/mosaic/framework/tools/git/pr-merge.sh
+++ b/packages/mosaic/framework/tools/git/pr-merge.sh
@@ -77,6 +77,11 @@ if [[ -z "$PR_NUMBER" ]]; then
    usage
 fi

+if [[ ! "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
+    echo "Error: Invalid PR number '$PR_NUMBER'. PR number must contain digits only." >&2
+    exit 1
+fi
+
 if [[ "$MERGE_METHOD" != "squash" ]]; then
    echo "Error: Mosaic policy enforces squash merge only. Received '$MERGE_METHOD'." >&2
    exit 1
@@ -104,6 +109,7 @@ REPO=$(get_repo_name)
 find_tea_login_for_host() {
    local host="$1"
    local logins_json
+
    command -v tea >/dev/null 2>&1 || return 1
    logins_json=$(tea login list --output json 2>/dev/null) || return 1
    TEA_LOGINS_JSON="$logins_json" python3 - "$host" <<'PY'
@@ -128,9 +134,30 @@ raise SystemExit(1)
 PY
 }

+is_known_tea_empty_identity_failure() {
+    local error_file="$1"
+
+    python3 - "$error_file" <<'PY'
+import re
+import sys
+
+with open(sys.argv[1], encoding="utf-8", errors="replace") as handle:
+    error = handle.read()
+
+known_empty_identity = re.search(
+    r"user does not exist.*\[.*uid:\s*0,\s*name:\s*\]",
+    error,
+    flags=re.IGNORECASE | re.DOTALL,
+)
+raise SystemExit(0 if known_empty_identity else 1)
+PY
+}
+
 merge_gitea_with_api() {
    local host="$1" api_url token basic_auth body_file raw_code payload
-    body_file=$(mktemp)
+    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
+    mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+    body_file=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/agent-work}/pr-merge-api-response.XXXXXX")
    payload='{"Do":"squash"}'

    token=$(get_gitea_token "$host" || true)
@@ -166,10 +193,15 @@ import json
 import sys
 code, path = sys.argv[1], sys.argv[2]
 try:
-    data = json.load(open(path, encoding="utf-8"))
-    message = data.get("message") or data.get("error") or "unknown API error"
+    with open(path, encoding="utf-8", errors="replace") as handle:
+        raw = handle.read(500)
+    data = json.loads(raw) if raw else {}
+    message = data.get("message") or data.get("error") or raw or "empty response"
 except Exception:
-    message = open(path, encoding="utf-8", errors="replace").read()[:200] or "empty response"
+    try:
+        message = open(path, encoding="utf-8", errors="replace").read(500) or "empty response"
+    except Exception:
+        message = "unreadable response"
 print(f"Error: Gitea API merge failed with HTTP {code}: {message}")
 PY
    rm -f "$body_file"
@@ -196,9 +228,9 @@ fi

 case "$PLATFORM" in
    github)
-        GH_ARGS=(pr merge "$PR_NUMBER" --squash)
-        [[ "$DELETE_BRANCH" == true ]] && GH_ARGS+=(--delete-branch)
-        gh "${GH_ARGS[@]}"
+        cmd=(gh pr merge "$PR_NUMBER" --squash)
+        [[ "$DELETE_BRANCH" == true ]] && cmd+=(--delete-branch)
+        "${cmd[@]}"
        ;;
    gitea)
        HOST=$(get_remote_host) || {
@@ -206,11 +238,25 @@ case "$PLATFORM" in
            exit 1
        }
        TEA_LOGIN="${GITEA_LOGIN:-$(find_tea_login_for_host "$HOST" || true)}"
+
        if [[ -n "$TEA_LOGIN" ]]; then
-            tea pr merge "$PR_NUMBER" --style squash --repo "$OWNER/$REPO" --login "$TEA_LOGIN"
+            mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+            TEA_ERROR_FILE=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/agent-work}/pr-merge-tea-error.XXXXXX")
+            if tea pr merge "$PR_NUMBER" --style squash --repo "$OWNER/$REPO" --login "$TEA_LOGIN" 2> "$TEA_ERROR_FILE"; then
+                rm -f "$TEA_ERROR_FILE"
+            elif is_known_tea_empty_identity_failure "$TEA_ERROR_FILE"; then
+                cat "$TEA_ERROR_FILE" >&2
+                echo "Known tea empty identity failure detected; using authenticated Gitea API merge fallback." >&2
+                rm -f "$TEA_ERROR_FILE"
+                merge_gitea_with_api "$HOST"
+            else
+                cat "$TEA_ERROR_FILE" >&2
+                rm -f "$TEA_ERROR_FILE"
+                exit 1
+            fi
        else
            echo "No tea login configured for $HOST; using authenticated Gitea API merge fallback." >&2
-            merge_gitea_with_api "$HOST" "https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
+            merge_gitea_with_api "$HOST"
        fi

        # Delete branch after merge if requested
--- a/packages/mosaic/framework/tools/git/pr-review.sh
+++ b/packages/mosaic/framework/tools/git/pr-review.sh
@@ -85,7 +85,7 @@ if [[ "$PLATFORM" == "github" ]]; then
 elif [[ "$PLATFORM" == "gitea" ]]; then
    case $ACTION in
        approve)
-            tea pr approve "$PR_NUMBER" ${COMMENT:+--comment "$COMMENT"}
+            tea pr approve "$PR_NUMBER" $(get_gitea_repo_args) ${COMMENT:+--comment "$COMMENT"}
            echo "Approved Gitea PR #$PR_NUMBER"
            ;;
        request-changes)
@@ -93,7 +93,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                echo "Error: Comment required for request-changes"
                exit 1
            fi
-            tea pr reject "$PR_NUMBER" --comment "$COMMENT"
+            tea pr reject "$PR_NUMBER" $(get_gitea_repo_args) --comment "$COMMENT"
            echo "Requested changes on Gitea PR #$PR_NUMBER"
            ;;
        comment)
@@ -101,7 +101,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                echo "Error: Comment required"
                exit 1
            fi
-            tea pr comment "$PR_NUMBER" "$COMMENT"
+            tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
            echo "Added comment to Gitea PR #$PR_NUMBER"
            ;;
        *)
--- a/packages/mosaic/framework/tools/git/pr-view.sh
+++ b/packages/mosaic/framework/tools/git/pr-view.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-view.sh - View pull request details on GitHub or Gitea
-# Usage: pr-view.sh -n <pr_number>
+# Usage: pr-view.sh -n <pr_number> [-r owner/repo]

 set -e

@@ -9,6 +9,7 @@ source "$SCRIPT_DIR/detect-platform.sh"

 # Parse arguments
 PR_NUMBER=""
+REPO_OVERRIDE=""

 while [[ $# -gt 0 ]]; do
    case $1 in
@@ -16,11 +17,16 @@ while [[ $# -gt 0 ]]; do
            PR_NUMBER="$2"
            shift 2
            ;;
+        -r|--repo)
+            REPO_OVERRIDE="$2"
+            shift 2
+            ;;
        -h|--help)
-            echo "Usage: pr-view.sh -n <pr_number>"
+            echo "Usage: pr-view.sh -n <pr_number> [-r owner/repo]"
            echo ""
            echo "Options:"
            echo "  -n, --number   PR number (required)"
+            echo "  -r, --repo     Repository slug (default: infer from git origin)"
            echo "  -h, --help     Show this help"
            exit 0
            ;;
@@ -36,12 +42,23 @@ if [[ -z "$PR_NUMBER" ]]; then
    exit 1
 fi

-detect_platform
+if [[ -n "$REPO_OVERRIDE" ]]; then
+    REPO_INFO="$REPO_OVERRIDE"
+    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
+else
+    PLATFORM=$(detect_platform)
+    REPO_INFO=$(get_repo_info)
+fi
+
+if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
+    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
+    exit 1
+fi

 if [[ "$PLATFORM" == "github" ]]; then
-    gh pr view "$PR_NUMBER"
+    gh pr view "$PR_NUMBER" --repo "$REPO_INFO"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    tea pr "$PR_NUMBER"
+    tea pr "$PR_NUMBER" --repo "$REPO_INFO" --login "${GITEA_LOGIN:-mosaicstack}"
 else
    echo "Error: Unknown platform"
    exit 1
--- a/packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh
+++ b/packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh
@@ -0,0 +1,254 @@
+#!/bin/bash
+# Regression harness for pr-merge.sh Gitea non-interactive tea empty identity fallback.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_ROOT="${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+SANDBOX="$WORK_ROOT/pr-merge-empty-uid-test-$$"
+MOCK_BIN="$SANDBOX/bin"
+REPO_DIR="$SANDBOX/repo"
+LOG_FILE="$SANDBOX/mock.log"
+
+cleanup() {
+    rm -rf "$SANDBOX"
+}
+trap cleanup EXIT
+
+mkdir -p "$MOCK_BIN" "$REPO_DIR"
+: > "$LOG_FILE"
+
+cat > "$MOCK_BIN/tea" <<'EOF'
+#!/bin/bash
+set -euo pipefail
+printf 'tea %q ' "$@" >> "$PR_MERGE_TEST_LOG"
+printf '\n' >> "$PR_MERGE_TEST_LOG"
+if [[ "$*" == *"pr merge"* ]]; then
+    echo 'user does not exist [uid: 0, name: ]' >&2
+    exit 1
+fi
+exit 0
+EOF
+chmod +x "$MOCK_BIN/tea"
+
+cat > "$MOCK_BIN/curl" <<'EOF'
+#!/bin/bash
+set -euo pipefail
+printf 'curl %q ' "$@" >> "$PR_MERGE_TEST_LOG"
+printf '\n' >> "$PR_MERGE_TEST_LOG"
+args=" $* "
+out_file=""
+write_code=false
+post_data=""
+prev=""
+for arg in "$@"; do
+    if [[ "$prev" == "-o" ]]; then
+        out_file="$arg"
+        prev=""
+        continue
+    fi
+    if [[ "$prev" == "-d" ]]; then
+        post_data="$arg"
+        prev=""
+        continue
+    fi
+    if [[ "$arg" == "-o" ]]; then
+        prev="-o"
+        continue
+    fi
+    if [[ "$arg" == "-d" ]]; then
+        prev="-d"
+        continue
+    fi
+    if [[ "$arg" == "-w" ]]; then
+        write_code=true
+    fi
+done
+emit_response() {
+    local body="$1"
+    if [[ -n "$out_file" ]]; then
+        printf '%s' "$body" > "$out_file"
+    else
+        printf '%s' "$body"
+    fi
+    if [[ "$write_code" == true ]]; then
+        printf '200'
+    fi
+}
+if [[ "$args" == *"/api/v1/repos/mosaicstack/stack/pulls/123"* && "$args" != *"/api/v1/repos/mosaicstack/stack/pulls/123/merge"* ]]; then
+    emit_response '{"number":123,"title":"mock","state":"open","user":{"login":"tester"},"head":{"ref":"feature/mock"},"base":{"ref":"main"},"labels":[],"assignees":[],"html_url":"https://git.mosaicstack.dev/mosaicstack/stack/pulls/123","mergeable":true}'
+    exit 0
+fi
+if [[ "$args" == *"-X POST"* && "$args" == *"/api/v1/repos/mosaicstack/stack/pulls/123/merge"* ]]; then
+    if [[ "$post_data" != '{"Do":"squash"}' ]]; then
+        echo "unexpected merge payload: $post_data" >&2
+        exit 96
+    fi
+    emit_response '{"merged":true,"message":"mock merge complete"}'
+    exit 0
+fi
+echo "unexpected curl invocation: $*" >&2
+exit 97
+EOF
+chmod +x "$MOCK_BIN/curl"
+
+cd "$REPO_DIR"
+git init -q
+git remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
+
+export PATH="$MOCK_BIN:$PATH"
+export PR_MERGE_TEST_LOG="$LOG_FILE"
+export GITEA_LOGIN="git.mosaicstack.dev"
+export GITEA_TOKEN="redacted-test-token"
+
+OUTPUT="$SANDBOX/output.log"
+if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
+    echo "Expected pr-merge.sh to recover via Gitea API fallback." >&2
+    echo "--- output ---" >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
+    echo "--- mock log ---" >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
+    exit 1
+fi
+
+if ! grep -q '/api/v1/repos/mosaicstack/stack/pulls/123/merge' "$LOG_FILE"; then
+    echo "Expected authenticated Gitea merge API endpoint to be called." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
+    exit 1
+fi
+
+if grep -q 'redacted-test-token' "$OUTPUT"; then
+    echo "Token leaked to pr-merge.sh output." >&2
+    exit 1
+fi
+
+cat > "$MOCK_BIN/tea" <<'EOF'
+#!/bin/bash
+set -euo pipefail
+printf 'tea %q ' "$@" >> "$PR_MERGE_TEST_LOG"
+printf '\n' >> "$PR_MERGE_TEST_LOG"
+if [[ "$*" == *"pr merge"* ]]; then
+    echo 'tea network timeout' >&2
+    exit 2
+fi
+exit 0
+EOF
+chmod +x "$MOCK_BIN/tea"
+: > "$LOG_FILE"
+if "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
+    echo "Expected arbitrary tea failure to remain blocking." >&2
+    exit 1
+fi
+if grep -q '/api/v1/repos/mosaicstack/stack/pulls/123/merge' "$LOG_FILE"; then
+    echo "Arbitrary tea failure unexpectedly used Gitea API merge fallback." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
+    exit 1
+fi
+if ! grep -q 'tea network timeout' "$OUTPUT"; then
+    echo "Expected arbitrary tea error to be preserved in output." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
+    exit 1
+fi
+
+cat > "$MOCK_BIN/tea" <<'EOF'
+#!/bin/bash
+set -euo pipefail
+printf 'tea %q ' "$@" >> "$PR_MERGE_TEST_LOG"
+printf '\n' >> "$PR_MERGE_TEST_LOG"
+if [[ "$*" == *"login list"* ]]; then
+    echo '[]'
+    exit 0
+fi
+if [[ "$*" == *"pr merge"* ]]; then
+    echo 'tea merge should not run without a configured host login' >&2
+    exit 99
+fi
+exit 0
+EOF
+chmod +x "$MOCK_BIN/tea"
+unset GITEA_LOGIN
+: > "$LOG_FILE"
+if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
+    echo "Expected missing tea login to use authenticated Gitea API fallback." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
+    exit 1
+fi
+if ! grep -q '/api/v1/repos/mosaicstack/stack/pulls/123/merge' "$LOG_FILE"; then
+    echo "Expected missing tea login path to call Gitea API merge endpoint." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
+    exit 1
+fi
+
+SENTINEL="$SANDBOX/injected-sentinel"
+INJECTION="123; touch $SENTINEL #"
+
+cat > "$MOCK_BIN/gh" <<'EOF'
+#!/bin/bash
+set -euo pipefail
+printf 'gh %q ' "$@" >> "$PR_MERGE_TEST_LOG"
+printf '\n' >> "$PR_MERGE_TEST_LOG"
+if [[ "$*" == *"pr view"* ]]; then
+    cat <<'JSON'
+{"number":123,"title":"mock","baseRefName":"main","headRefName":"feature/mock"}
+JSON
+    exit 0
+fi
+if [[ "$*" == *"pr merge"* ]]; then
+    exit 0
+fi
+echo "unexpected gh invocation: $*" >&2
+exit 98
+EOF
+chmod +x "$MOCK_BIN/gh"
+
+cd "$REPO_DIR"
+git remote set-url origin https://github.com/mosaicstack/stack.git
+: > "$LOG_FILE"
+rm -f "$SENTINEL"
+if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
+    echo "Expected GitHub metacharacter PR number to be rejected." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
+    exit 1
+fi
+if [[ -e "$SENTINEL" ]]; then
+    echo "GitHub metacharacter PR number executed injected shell command." >&2
+    exit 1
+fi
+if [[ -s "$LOG_FILE" ]]; then
+    echo "GitHub metacharacter PR number should be rejected before gh calls." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
+    exit 1
+fi
+if ! grep -q 'Invalid PR number' "$OUTPUT"; then
+    echo "Expected invalid PR number error for GitHub metacharacter input." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
+    exit 1
+fi
+
+cd "$REPO_DIR"
+git remote set-url origin https://git.mosaicstack.dev/mosaicstack/stack.git
+export GITEA_LOGIN="git.mosaicstack.dev"
+: > "$LOG_FILE"
+rm -f "$SENTINEL"
+if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
+    echo "Expected Gitea metacharacter PR number to be rejected." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
+    exit 1
+fi
+if [[ -e "$SENTINEL" ]]; then
+    echo "Gitea metacharacter PR number executed injected shell command." >&2
+    exit 1
+fi
+if [[ -s "$LOG_FILE" ]]; then
+    echo "Gitea metacharacter PR number should be rejected before tea/curl calls." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
+    exit 1
+fi
+if ! grep -q 'Invalid PR number' "$OUTPUT"; then
+    echo "Expected invalid PR number error for Gitea metacharacter input." >&2
+    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
+    exit 1
+fi
+
+echo "pr-merge.sh Gitea fallback regression passed"
--- a/packages/mosaic/framework/tools/woodpecker/pipeline-list.sh
+++ b/packages/mosaic/framework/tools/woodpecker/pipeline-list.sh
@@ -50,7 +50,7 @@ REPO_ID=$(wp_resolve_repo_id "$REPO") || exit 1

 response=$(curl -sk -w "\n%{http_code}" \
  -H "Authorization: Bearer $WOODPECKER_TOKEN" \
-  "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?per_page=${LIMIT}")
+  "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?perPage=${LIMIT}")

 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')
--- a/packages/mosaic/framework/tools/woodpecker/pipeline-status.sh
+++ b/packages/mosaic/framework/tools/woodpecker/pipeline-status.sh
@@ -64,7 +64,7 @@ _wp_fetch() {

 if [[ -z "$NUMBER" ]]; then
  # Get latest pipeline number from list, then fetch full detail
-  list_body=$(_wp_fetch "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?per_page=1") || exit 1
+  list_body=$(_wp_fetch "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?perPage=1") || exit 1
  NUMBER=$(echo "$list_body" | jq -r '.[0].number // empty')
  if [[ -z "$NUMBER" ]]; then
    echo "Error: No pipelines found" >&2
--- a/packages/mosaic/src/commands/git-wrapper-redirects.spec.ts
+++ b/packages/mosaic/src/commands/git-wrapper-redirects.spec.ts
@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const packageRoot = join(import.meta.dirname, '..', '..');
+const gitToolsDir = join(packageRoot, 'framework', 'tools', 'git');
+
+function readGitTool(scriptName: string): string {
+  return readFileSync(join(gitToolsDir, scriptName), 'utf-8');
+}
+
+describe('Gitea git wrapper API calls', () => {
+  it.each(['ci-queue-wait.sh', 'pr-ci-wait.sh'])(
+    '%s follows Gitea API redirects before parsing JSON',
+    (scriptName) => {
+      const script = readGitTool(scriptName);
+
+      expect(script).not.toContain('curl -fsS -H "Authorization: token');
+      expect(script).toContain('curl -fsSL -H "Authorization: token');
+    },
+  );
+});
--- a/packages/mosaic/src/commands/launch.spec.ts
+++ b/packages/mosaic/src/commands/launch.spec.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
 import { Command } from 'commander';
-import { registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
+import { buildPiSkillArgs, registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';

 /**
 * Tests for the commander wiring between `mosaic <runtime>` / `mosaic yolo <runtime>`
@@ -22,6 +22,8 @@ function buildProgram(handler: RuntimeLaunchHandler): Command {
  return program;
 }

+const fakeSkills = ['--skill', '/skills/test-driven-development', '--skill', '/skills/pdf'];
+
 // `process.exit` returns `never`, so vi.spyOn demands a replacement with the
 // same signature. We throw from the mock to short-circuit into test-land.
 const exitThrows = (): never => {
@@ -63,6 +65,30 @@ describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
  });
 });

+describe('buildPiSkillArgs', () => {
+  it('defaults to disabling Pi skill discovery to keep startup context small', () => {
+    expect(buildPiSkillArgs([], {}, fakeSkills)).toEqual(['--no-skills']);
+  });
+
+  it('keeps explicit user skills while disabling automatic discovery', () => {
+    expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills)).toEqual(['--no-skills']);
+  });
+
+  it('supports legacy all-skills mode without double-loading settings skills', () => {
+    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills)).toEqual([
+      '--no-skills',
+      '--skill',
+      '/skills/test-driven-development',
+      '--skill',
+      '/skills/pdf',
+    ]);
+  });
+
+  it('supports native Pi discovery when explicitly requested', () => {
+    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills)).toEqual([]);
+  });
+});
+
 describe('registerRuntimeLaunchers — yolo <runtime>', () => {
  let mockExit: MockInstance<typeof process.exit>;
  let mockError: MockInstance<typeof console.error>;
--- a/packages/mosaic/src/commands/launch.ts
+++ b/packages/mosaic/src/commands/launch.ts
@@ -447,6 +447,32 @@ function discoverPiSkills(): string[] {
  return args;
 }

+type PiSkillMode = 'none' | 'all' | 'discover';
+
+function normalizePiSkillMode(env: NodeJS.ProcessEnv): PiSkillMode {
+  const value = env['MOSAIC_PI_SKILL_MODE']?.trim().toLowerCase();
+  if (value === 'all' || value === 'discover') return value;
+  return 'none';
+}
+
+export function buildPiSkillArgs(
+  _runtimeArgs: string[],
+  env: NodeJS.ProcessEnv = process.env,
+  discoveredSkillArgs: string[] = discoverPiSkills(),
+): string[] {
+  const mode = normalizePiSkillMode(env);
+
+  if (mode === 'discover') {
+    return [];
+  }
+
+  if (mode === 'all') {
+    return ['--no-skills', ...discoveredSkillArgs];
+  }
+
+  return ['--no-skills'];
+}
+
 function discoverPiExtension(): string[] {
  const ext = join(MOSAIC_HOME, 'runtime', 'pi', 'mosaic-extension.ts');
  return existsSync(ext) ? ['--extension', ext] : [];
@@ -523,7 +549,7 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
    case 'pi': {
      const prompt = buildRuntimePrompt('pi');
      const cliArgs = ['--append-system-prompt', prompt];
-      cliArgs.push(...discoverPiSkills());
+      cliArgs.push(...buildPiSkillArgs(args));
      cliArgs.push(...discoverPiExtension());
      if (hasMissionNoArgs) {
        cliArgs.push(missionPrompt);
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -297,6 +297,18 @@ importers:
        specifier: ^2.0.0
        version: 2.1.9(@types/node@24.12.0)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)

+  packages/appservice:
+    devDependencies:
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.15
+      typescript:
+        specifier: ^5.8.0
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.0
+        version: 2.1.9(@types/node@22.19.15)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)
+
  packages/auth:
    dependencies:
      '@mosaicstack/db':
Author	SHA1	Message	Date
Jason Woltje	8b9d19347f	feat(appservice): @mosaicstack/appservice — Matrix AS core (M4a, agent-comms#9) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details First phase of mosaic-as per agent-comms docs/design/M4-MOSAIC-AS.md: - TransactionHandler: AS transactions endpoint logic with timing-safe hs_token verification (Bearer + legacy access_token), bounded txnId dedupe (documented at-least-once limitation), handler error isolation - AppserviceIntent: virtual user registration (m.login.application_service), user_id impersonation, invite-then-join fallback, thread-aware sends (m.thread + is_falling_back), typing, display names, uuid txn ids - Registration builder + hardened YAML serializer (control-char rejection, quote escaping) for the Synapse mosaic-as.yaml - bridge.dto.ts validators for the agent-comms daemon bridge API Zero runtime deps; strict ESM/NodeNext; 14 vitest tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-06-10 16:09:11 -05:00
jason.woltje	dde95a59b3	fix(pi): reduce startup skill-token overhead (#527 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-06-05 18:36:42 +00:00
jason.woltje	821e19dcbb	fix(mosaic-tools): roll up Gitea and Woodpecker wrapper fixes (#524 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-05-26 20:56:09 +00:00