release(mosaic): bump @mosaicstack/mosaic 0.0.30 -> 0.0.31 (#534)

Fresh `mosaic gateway install` (npm) left the gateway DB schema empty —
sign-in 500'd with `relation "users" does not exist`, and every entry
point (auth, bootstrap setup) failed because they all query the users
table first. Five stacked bugs on the local (PGlite) tier:

1. `packages/db/package.json` `files: ["dist"]` excluded the `drizzle/`
   SQL migrations from the published tarball.
2. `runMigrations()` only supports postgres-js — unusable for embedded
   PGlite.
3. `apps/gateway/src/database/database.module.ts` never invoked
   migrations at startup.
4. `createPgliteDb` didn't load pgvector, so migration 0001's
   `CREATE EXTENSION vector` failed.
5. Drizzle's PG migrator wraps every migration in one outer
   transaction, which trips Postgres' `check_safe_enum_use` on
   migration 0009 (`ALTER TYPE ADD VALUE 'pending'` → `SET DEFAULT
   'pending'` in the same tx).

Changes:
- Ship `drizzle/` in the published tarball.
- `createPgliteDb` loads `@electric-sql/pglite/vector`.
- New `runPgliteMigrations(handle)` walks the Drizzle journal and
  runs each statement-breakpoint chunk through PGlite's `client.exec()`
  (autocommit per statement). Records into `drizzle.__drizzle_migrations`
  for interop with the postgres-js path. Per-statement try/catch
  surfaces which statement of which migration failed.
- `DatabaseModule` runs migrations in `OnModuleInit` before
  `app.listen()`. Local tier: explicit `runPgliteMigrations` then
  `storageAdapter.migrate()`. Postgres tier: just `storageAdapter.migrate()`,
  which already calls `runMigrations(url)` internally — no double-call.
- Removed `packages/storage/src/test-utils/pglite-with-vector.ts`. The
  "intentionally not exported" rationale is moot now that migration
  0001 forces pgvector load anyway. The integration test uses
  `createPgliteDb` + `runPgliteMigrations` from `@mosaicstack/db`.

Tests: BetterAuth tables exist after migrate; idempotent (re-runs 0009);
partial-failure surfaces statement-level context and leaves no ledger row.

QA on a fresh PGlite install:
- `Applying PGlite schema migrations...` then `Initializing storage
  adapter (pglite)...` in startup log.
- `GET /api/bootstrap/status` → `{"needsSetup":true}` HTTP 200 (was 500).
- `POST /api/bootstrap/setup` reaches Zod validator (was 500).

Scope: this PR fixes the local (PGlite) tier. Postgres-tier first
install still has the outer-transaction problem and a journal ordering
bug (0009's `when` < 0008's). Documented inline as TODO and in the
scratchpad — needs a separate change with real-Postgres validation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.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

.woodpecker/publish.yml

@@ -114,6 +114,31 @@ steps:
     depends_on:
       - build
 
+  build-appservice:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      REGISTRY_USER:
+        from_secret: gitea_username
+      REGISTRY_PASS:
+        from_secret: gitea_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
+    commands:
+      - mkdir -p /kaniko/.docker
+      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
+      - |
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/appservice:sha-${CI_COMMIT_SHA:0:7}"
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:latest"
+        fi
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:$CI_COMMIT_TAG"
+        fi
+        /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
+    depends_on:
+      - build
+
   build-web:
     image: gcr.io/kaniko-project/executor:debug
     environment:

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

apps/appservice/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mosaicstack/mosaic-as",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
+    "directory": "apps/appservice"
+  },
+  "main": "dist/main.js",
+  "bin": {
+    "mosaic-as": "dist/main.js",
+    "mosaic-as-registration": "dist/registration-main.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "dev": "tsx watch src/main.ts"
+  },
+  "dependencies": {
+    "@mosaicstack/appservice": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^2.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

apps/appservice/src/__tests__/server.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { AppserviceDaemon } from '../server.js';
+import type { DaemonConfig, DaemonRequest } from '../server.js';
+
+const cfg: DaemonConfig = {
+  homeserverUrl: 'https://hs.example',
+  domain: 'hs.example',
+  asToken: 'as-secret',
+  hsToken: 'hs-secret',
+  bridgeTokens: ['bridge-secret'],
+};
+
+const jsonResponse = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+
+const request = (overrides: Partial<DaemonRequest>): DaemonRequest => ({
+  method: 'GET',
+  path: '/',
+  searchParams: new URLSearchParams(),
+  body: undefined,
+  ...overrides,
+});
+
+const makeDaemon = () => {
+  const fetchMock = vi.fn(async (_input: URL | string) => jsonResponse(200, { event_id: '$sent' }));
+  const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+  return { daemon, fetchMock };
+};
+
+describe('AppserviceDaemon routing', () => {
+  it('serves health unauthenticated', async () => {
+    const { daemon } = makeDaemon();
+    expect((await daemon.handle(request({ path: '/health' }))).status).toBe(200);
+  });
+
+  it('404s unknown paths', async () => {
+    const { daemon } = makeDaemon();
+    expect((await daemon.handle(request({ path: '/nope' }))).status).toBe(404);
+  });
+
+  it('transactions require the hs_token', async () => {
+    const { daemon } = makeDaemon();
+    const bad = await daemon.handle(
+      request({
+        method: 'PUT',
+        path: '/_matrix/app/v1/transactions/t1',
+        authorizationHeader: 'Bearer wrong',
+        body: { events: [] },
+      }),
+    );
+    expect(bad.status).toBe(403);
+    const ok = await daemon.handle(
+      request({
+        method: 'PUT',
+        path: '/_matrix/app/v1/transactions/t1',
+        authorizationHeader: 'Bearer hs-secret',
+        body: { events: [{ type: 'm.room.message', event_id: '$e' }] },
+      }),
+    );
+    expect(ok.status).toBe(200);
+  });
+
+  it('bridge requires a bridge token (hs/as tokens do not work)', async () => {
+    const { daemon } = makeDaemon();
+    for (const token of [undefined, 'Bearer hs-secret', 'Bearer as-secret', 'Bearer nope']) {
+      const res = await daemon.handle(
+        request({
+          method: 'POST',
+          path: '/bridge/v1/messages',
+          authorizationHeader: token,
+          body: {},
+        }),
+      );
+      expect(res.status).toBe(403);
+    }
+  });
+
+  it('bridge message sends as the agent and returns the event id', async () => {
+    const { daemon, fetchMock } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', body: 'hi', thread_root: '$req' },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.event_id).toBe('$sent');
+    const sendCall = fetchMock.mock.calls
+      .map((c) => new URL(String(c[0])))
+      .find((u) => u.pathname.includes('/send/m.room.message/'));
+    expect(sendCall).toBeDefined();
+    expect(sendCall!.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
+  });
+
+  it('bridge rejects invalid payloads with 400', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: 'bad', agent: 'pi0', body: 'x' },
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('bridge typing endpoint works', async () => {
+    const { daemon, fetchMock } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/typing',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', typing: true },
+      }),
+    );
+    expect(res.status).toBe(200);
+    const typingCall = fetchMock.mock.calls
+      .map((c) => new URL(String(c[0])))
+      .find((u) => u.pathname.includes('/typing/'));
+    expect(typingCall).toBeDefined();
+  });
+
+  it('authenticated unknown bridge sub-paths return 405, never fall through', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'GET',
+        path: '/bridge/v1/unknown',
+        authorizationHeader: 'Bearer bridge-secret',
+      }),
+    );
+    expect(res.status).toBe(405);
+  });
+
+  it('provisions a room as the AS sender with space linking', async () => {
+    const calls: Array<{ url: URL; body: unknown }> = [];
+    const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
+      const url = new URL(String(input));
+      calls.push({ url, body: init?.body ? JSON.parse(String(init.body)) : undefined });
+      if (url.pathname.endsWith('/createRoom'))
+        return jsonResponse(200, { room_id: '!new:hs.example' });
+      return jsonResponse(200, {});
+    });
+    const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: {
+          name: 'proj-x',
+          alias: 'mosaic-proj-x',
+          invite: ['@jason.woltje:hs.example'],
+          space_id: '!space:hs.example',
+        },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.room_id).toBe('!new:hs.example');
+    expect(res.body.space_linked).toBe(true);
+    const create = calls.find((c) => c.url.pathname.endsWith('/createRoom'));
+    expect(create!.url.searchParams.get('user_id')).toBe('@mosaic-as:hs.example');
+    const body = create!.body as Record<string, unknown>;
+    expect(body.room_alias_name).toBe('mosaic-proj-x');
+    expect((body.power_level_content_override as Record<string, unknown>).users).toEqual({
+      '@mosaic-as:hs.example': 100,
+    });
+    expect(calls.some((c) => c.url.pathname.includes('/state/m.space.child/'))).toBe(true);
+    expect(calls.some((c) => c.url.pathname.includes('/state/m.space.parent/'))).toBe(true);
+  });
+
+  it('space-link failure still returns the room id (no orphan)', async () => {
+    const fetchMock = vi.fn(async (input: URL | string) => {
+      const url = new URL(String(input));
+      if (url.pathname.endsWith('/createRoom'))
+        return jsonResponse(200, { room_id: '!new:hs.example' });
+      if (url.pathname.includes('/state/m.space.child/'))
+        return jsonResponse(403, { errcode: 'M_FORBIDDEN', error: 'no PL in space' });
+      return jsonResponse(200, {});
+    });
+    const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { name: 'proj-x', space_id: '!space:hs.example' },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.room_id).toBe('!new:hs.example');
+    expect(res.body.space_linked).toBe(false);
+    expect(String(res.body.space_error)).toContain('403');
+  });
+
+  it('invite list cap enforced', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { name: 'x', invite: Array.from({ length: 51 }, (_, i) => `@u${i}:hs`) },
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('provision rejects bad payloads and requires auth', async () => {
+    const { daemon } = makeDaemon();
+    const noAuth = await daemon.handle(
+      request({ method: 'POST', path: '/bridge/v1/provision/rooms', body: { name: 'x' } }),
+    );
+    expect(noAuth.status).toBe(403);
+    const bad = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { name: '', alias: 'BAD ALIAS' },
+      }),
+    );
+    expect(bad.status).toBe(400);
+  });
+
+  it('empty bridge token list denies everything', async () => {
+    const daemon = new AppserviceDaemon({ ...cfg, bridgeTokens: [] }, undefined, () => {});
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/typing',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: {},
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+});

apps/appservice/src/config.ts

@@ -0,0 +1,23 @@
+import type { DaemonConfig } from './server.js';
+
+const required = (name: string): string => {
+  const value = process.env[name];
+  if (!value) throw new Error(`missing required env var ${name}`);
+  return value;
+};
+
+export function configFromEnv(): DaemonConfig & { port: number } {
+  return {
+    homeserverUrl: required('MOSAIC_AS_HOMESERVER_URL'),
+    domain: required('MOSAIC_AS_DOMAIN'),
+    asToken: required('MOSAIC_AS_TOKEN'),
+    hsToken: required('MOSAIC_HS_TOKEN'),
+    userPrefix: process.env.MOSAIC_AS_USER_PREFIX ?? 'agent-',
+    senderLocalpart: process.env.MOSAIC_AS_SENDER_LOCALPART ?? 'mosaic-as',
+    bridgeTokens: (process.env.MOSAIC_AS_BRIDGE_TOKENS ?? '')
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean),
+    port: Number(process.env.MOSAIC_AS_PORT ?? 8008),
+  };
+}

apps/appservice/src/main.ts

@@ -0,0 +1,67 @@
+import http from 'node:http';
+
+import { configFromEnv } from './config.js';
+import { AppserviceDaemon } from './server.js';
+
+const cfg = configFromEnv();
+const daemon = new AppserviceDaemon(cfg);
+
+const MAX_BODY_BYTES = 1024 * 1024;
+
+const server = http.createServer((req, res) => {
+  const chunks: Buffer[] = [];
+  let received = 0;
+  let rejected = false;
+  req.on('data', (chunk: Buffer) => {
+    received += chunk.length;
+    if (received > MAX_BODY_BYTES) {
+      rejected = true;
+      res.writeHead(413, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ errcode: 'M_TOO_LARGE', error: 'request body too large' }));
+      req.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+  req.on('end', () => {
+    if (rejected) return;
+    void (async () => {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      let body: unknown;
+      try {
+        const raw = Buffer.concat(chunks).toString();
+        body = raw ? JSON.parse(raw) : undefined;
+      } catch {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ errcode: 'M_NOT_JSON', error: 'invalid json' }));
+        return;
+      }
+      const result = await daemon.handle({
+        method: req.method ?? 'GET',
+        path: url.pathname,
+        searchParams: url.searchParams,
+        authorizationHeader: req.headers.authorization,
+        body,
+      });
+      res.writeHead(result.status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(result.body));
+    })().catch((error: unknown) => {
+      console.error('request failed:', error);
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'internal error' }));
+    });
+  });
+});
+
+server.listen(cfg.port, () => {
+  console.log(
+    `mosaic-as listening on :${cfg.port} (homeserver ${cfg.homeserverUrl}, domain ${cfg.domain})`,
+  );
+  if (cfg.bridgeTokens.length === 0) {
+    console.warn('WARNING: MOSAIC_AS_BRIDGE_TOKENS is empty — bridge API will deny all requests');
+  }
+});

apps/appservice/src/registration-main.ts

@@ -0,0 +1,10 @@
+import { buildRegistration, registrationToYaml } from '@mosaicstack/appservice';
+
+import { configFromEnv } from './config.js';
+
+// Prints the Synapse registration YAML (mosaic-as.yaml) for the current env.
+// Usage: MOSAIC_AS_URL=http://mosaic-as:8008 mosaic-as-registration > mosaic-as.yaml
+const cfg = configFromEnv();
+const url = process.env.MOSAIC_AS_URL;
+if (!url) throw new Error('missing required env var MOSAIC_AS_URL');
+process.stdout.write(registrationToYaml(buildRegistration(cfg, { url })));

apps/appservice/src/server.ts

@@ -0,0 +1,146 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+import {
+  AppserviceIntent,
+  TransactionHandler,
+  validateBridgeMessage,
+  validateBridgeTyping,
+  validateProvisionRoom,
+} from '@mosaicstack/appservice';
+import type { AppserviceConfig, MatrixEvent } from '@mosaicstack/appservice';
+
+export interface DaemonConfig extends AppserviceConfig {
+  /** Bearer tokens accepted on /bridge/v1/* (one per agent-comms host daemon). */
+  bridgeTokens: string[];
+}
+
+export interface DaemonRequest {
+  method: string;
+  /** URL path without query string. */
+  path: string;
+  searchParams: URLSearchParams;
+  authorizationHeader?: string;
+  body: unknown;
+}
+
+export interface DaemonResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+// Compare equal-length HMAC digests so neither content nor LENGTH of the
+// stored secret is observable through timing.
+const HMAC_KEY = randomBytes(32);
+const digest = (value: string): Buffer => createHmac('sha256', HMAC_KEY).update(value).digest();
+
+const safeEqual = (a: string, b: string): boolean => timingSafeEqual(digest(a), digest(b));
+
+const TXN_PATH = /^\/_matrix\/app\/v1\/transactions\/([^/]+)$/;
+
+/**
+ * HTTP-framework-agnostic request router for the mosaic-as daemon: the
+ * Application Service transactions endpoint (Synapse-facing) plus the
+ * internal bridge API v1 (agent-comms daemon-facing). main.ts binds this to
+ * node:http; tests drive it directly.
+ */
+export class AppserviceDaemon {
+  readonly intent: AppserviceIntent;
+  private readonly transactions: TransactionHandler;
+
+  constructor(
+    private readonly cfg: DaemonConfig,
+    fetchImpl?: typeof fetch,
+    private readonly log: (line: string) => void = (line) => console.log(line),
+  ) {
+    this.intent = new AppserviceIntent(cfg, fetchImpl);
+    this.transactions = new TransactionHandler({
+      hsToken: cfg.hsToken,
+      onEvent: (event) => this.onEvent(event),
+      onError: (error, txnId) => this.log(`txn ${txnId} handler error: ${String(error)}`),
+    });
+  }
+
+  /** v1: the daemon only observes; room logic lives in the agent-comms daemons. */
+  private onEvent(event: MatrixEvent): void {
+    if (event.type === 'm.room.message') {
+      this.log(
+        `event ${event.event_id ?? '?'} in ${event.room_id ?? '?'} from ${event.sender ?? '?'}`,
+      );
+    }
+  }
+
+  private bridgeAuthorized(authorizationHeader: string | undefined): boolean {
+    if (!authorizationHeader?.startsWith('Bearer ')) return false;
+    const presented = authorizationHeader.slice('Bearer '.length);
+    return this.cfg.bridgeTokens.some((token) => safeEqual(presented, token));
+  }
+
+  async handle(req: DaemonRequest): Promise<DaemonResponse> {
+    if (req.method === 'GET' && req.path === '/health') {
+      return { status: 200, body: { ok: true } };
+    }
+
+    const txnMatch = req.method === 'PUT' ? TXN_PATH.exec(req.path) : null;
+    if (txnMatch?.[1] !== undefined) {
+      return this.transactions.handle(txnMatch[1], req.body, {
+        authorizationHeader: req.authorizationHeader,
+        accessTokenParam: req.searchParams.get('access_token') ?? undefined,
+      });
+    }
+
+    if (req.path.startsWith('/bridge/v1/')) {
+      if (!this.bridgeAuthorized(req.authorizationHeader)) {
+        return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad bridge token' } };
+      }
+      try {
+        if (req.method === 'POST' && req.path === '/bridge/v1/messages') {
+          validateBridgeMessage(req.body);
+          const eventId = await this.intent.sendAsAgent({
+            roomId: req.body.room_id,
+            agent: req.body.agent,
+            body: req.body.body,
+            threadRoot: req.body.thread_root,
+            msgtype: req.body.msgtype,
+            extraContent: req.body.extra_content,
+          });
+          return { status: 200, body: { event_id: eventId ?? null } };
+        }
+        if (req.method === 'POST' && req.path === '/bridge/v1/typing') {
+          validateBridgeTyping(req.body);
+          await this.intent.setTyping(req.body.room_id, req.body.agent, req.body.typing);
+          return { status: 200, body: {} };
+        }
+        if (req.method === 'POST' && req.path === '/bridge/v1/provision/rooms') {
+          validateProvisionRoom(req.body);
+          const result = await this.intent.createRoom({
+            name: req.body.name,
+            alias: req.body.alias,
+            topic: req.body.topic,
+            invite: req.body.invite,
+            spaceId: req.body.space_id,
+          });
+          this.log(
+            `provisioned room ${result.roomId} (${req.body.name}) space_linked=${result.spaceLinked}`,
+          );
+          return {
+            status: 200,
+            body: {
+              room_id: result.roomId,
+              space_linked: result.spaceLinked,
+              ...(result.spaceError ? { space_error: result.spaceError } : {}),
+            },
+          };
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.log(`bridge error ${req.method} ${req.path}: ${message}`);
+        return { status: 400, body: { error: message } };
+      }
+      // Explicit: never fall out of the authenticated bridge block, so future
+      // sub-paths cannot accidentally route around the auth guard above.
+      return { status: 405, body: { error: 'unsupported bridge method/path' } };
+    }
+
+    return { status: 404, body: { error: 'not found' } };
+  }
+}

apps/appservice/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

apps/gateway/package.json

@@ -73,6 +73,7 @@
     "rxjs": "^7.8.0",
     "socket.io": "^4.8.0",
     "uuid": "^11.0.0",
+    "undici": "^7.24.6",
     "zod": "^4.3.6"
   },
   "devDependencies": {

apps/gateway/src/database/database.module.ts

@@ -1,8 +1,21 @@
 import { mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { Global, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
-import { createDb, createPgliteDb, type Db, type DbHandle } from '@mosaicstack/db';
+import {
+  Global,
+  Inject,
+  Logger,
+  Module,
+  type OnApplicationShutdown,
+  type OnModuleInit,
+} from '@nestjs/common';
+import {
+  createDb,
+  createPgliteDb,
+  runPgliteMigrations,
+  type Db,
+  type DbHandle,
+} from '@mosaicstack/db';
 import { createStorageAdapter, type StorageAdapter } from '@mosaicstack/storage';
 import type { MosaicConfig } from '@mosaicstack/config';
 import { MOSAIC_CONFIG } from '../config/config.module.js';
@@ -39,12 +52,37 @@ export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
   ],
   exports: [DB, STORAGE_ADAPTER],
 })
-export class DatabaseModule implements OnApplicationShutdown {
+export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
+  private readonly logger = new Logger(DatabaseModule.name);
+
   constructor(
     @Inject(DB_HANDLE) private readonly handle: DbHandle,
     @Inject(STORAGE_ADAPTER) private readonly storageAdapter: StorageAdapter,
+    @Inject(MOSAIC_CONFIG) private readonly config: MosaicConfig,
   ) {}
 
+  // Migrations must complete before any module that injects DB starts serving
+  // requests. NestJS awaits onModuleInit before app.listen(), and modules that
+  // inject DB are initialized after this one — so all DB-dependent code sees a
+  // populated schema before the first HTTP request lands.
+  //
+  // Local (PGlite) tier: we run gateway-DB migrations explicitly here. The
+  // storage adapter writes to a separate PGlite directory and only manages its
+  // own KV tables, so we still call its migrate() afterwards.
+  //
+  // Postgres tier: PostgresAdapter.migrate() already calls runMigrations() on
+  // the same DATABASE_URL, so a single call covers both the gateway DB and
+  // the storage tables. We deliberately do NOT call runMigrations() here to
+  // avoid opening a second short-lived connection and doubling startup cost.
+  async onModuleInit(): Promise<void> {
+    if (this.config.tier === 'local') {
+      this.logger.log('Applying PGlite schema migrations...');
+      await runPgliteMigrations(this.handle);
+    }
+    this.logger.log(`Initializing storage adapter (${this.storageAdapter.name})...`);
+    await this.storageAdapter.migrate();
+  }
+
   async onApplicationShutdown(): Promise<void> {
     await Promise.all([this.handle.close(), this.storageAdapter.close()]);
   }

apps/gateway/src/federation/client/__tests__/federation-client.service.spec.ts

@@ -0,0 +1,553 @@
+/**
+ * Unit tests for FederationClientService (FED-M3-08).
+ *
+ * HTTP mocking strategy:
+ *   undici MockAgent is used to intercept outbound HTTP requests.  The service
+ *   uses `undici.fetch` with a `dispatcher` option, so MockAgent is set as the
+ *   global dispatcher and all requests flow through it.
+ *
+ *   Because the service builds one `undici.Agent` per peer and passes it as
+ *   the dispatcher on every fetch call, we cannot intercept at the Agent level
+ *   in unit tests without significant refactoring.  Instead, we set the global
+ *   dispatcher to a MockAgent and override the service's `doRequest` indirection
+ *   by spying on the internal fetch call.
+ *
+ *   For the cert/key wiring, we use the real `sealClientKey` function from
+ *   peer-key.util.ts with a test secret — no stubs.
+ *
+ * Sealed-key setup:
+ *   Each test (or beforeAll) calls `sealClientKey(TEST_PRIVATE_KEY_PEM)` with
+ *   BETTER_AUTH_SECRET set to a deterministic test value so that
+ *   `unsealClientKey` in the service recovers the original PEM.
+ */
+
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
+import { MockAgent, setGlobalDispatcher, getGlobalDispatcher } from 'undici';
+import type { Dispatcher } from 'undici';
+import { writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Db } from '@mosaicstack/db';
+import { FederationClientService, FederationClientError } from '../federation-client.service.js';
+import { sealClientKey } from '../../peer-key.util.js';
+
+// ---------------------------------------------------------------------------
+// Test constants
+// ---------------------------------------------------------------------------
+
+const TEST_SECRET = 'test-secret-for-federation-client-spec-only';
+const PEER_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+const ENDPOINT = 'https://peer.example.com';
+
+// Minimal valid RSA/EC private key PEM — does NOT need to be a real key for
+// unit tests because we only verify it round-trips through seal/unseal, not
+// that it actually negotiates TLS (MockAgent handles that).
+const TEST_PRIVATE_KEY_PEM = `-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDummyKeyForTests
+-----END PRIVATE KEY-----`;
+
+// Minimal self-signed cert PEM (dummy — only used for mTLS Agent construction)
+const TEST_CERT_PEM = `-----BEGIN CERTIFICATE-----
+MIIBdummyCertForFederationClientTests==
+-----END CERTIFICATE-----`;
+
+const TEST_CERT_SERIAL = 'ABCDEF1234567890';
+
+// ---------------------------------------------------------------------------
+// Sealed key (computed once in beforeAll)
+// ---------------------------------------------------------------------------
+
+let SEALED_KEY: string;
+
+// Path to a stub Step-CA root cert file written in beforeAll. The cert is never
+// actually used to negotiate TLS in unit tests (MockAgent + spy on resolveEntry
+// short-circuit the network), but loadStepCaRoot() requires the file to exist.
+const STUB_CA_PEM_PATH = join(tmpdir(), 'federation-client-spec-ca.pem');
+const STUB_CA_PEM = `-----BEGIN CERTIFICATE-----
+MIIBdummyCAforFederationClientSpecOnly==
+-----END CERTIFICATE-----
+`;
+
+// ---------------------------------------------------------------------------
+// Peer row factory
+// ---------------------------------------------------------------------------
+
+function makePeerRow(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    id: PEER_ID,
+    commonName: 'peer-example-com',
+    displayName: 'Test Peer',
+    certPem: TEST_CERT_PEM,
+    certSerial: TEST_CERT_SERIAL,
+    certNotAfter: new Date('2030-01-01T00:00:00Z'),
+    clientKeyPem: SEALED_KEY,
+    state: 'active' as const,
+    endpointUrl: ENDPOINT,
+    lastSeenAt: null,
+    createdAt: new Date('2026-01-01T00:00:00Z'),
+    revokedAt: null,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mock DB builder
+// ---------------------------------------------------------------------------
+
+function makeDb(selectRows: unknown[] = [makePeerRow()]): Db {
+  const limitSelect = vi.fn().mockResolvedValue(selectRows);
+  const whereSelect = vi.fn().mockReturnValue({ limit: limitSelect });
+  const fromSelect = vi.fn().mockReturnValue({ where: whereSelect });
+  const selectMock = vi.fn().mockReturnValue({ from: fromSelect });
+
+  return {
+    select: selectMock,
+    insert: vi.fn(),
+    update: vi.fn(),
+    delete: vi.fn(),
+    transaction: vi.fn(),
+  } as unknown as Db;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers for MockAgent HTTP interception
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a MockAgent + MockPool for the peer endpoint, set it as the global
+ * dispatcher, and return both for per-test configuration.
+ */
+function makeMockAgent() {
+  const mockAgent = new MockAgent({ connections: 1 });
+  mockAgent.disableNetConnect();
+  setGlobalDispatcher(mockAgent);
+  const pool = mockAgent.get(ENDPOINT);
+  return { mockAgent, pool };
+}
+
+/**
+ * Build a FederationClientService with a mock DB and a spy on the internal
+ * fetch so we can intercept at the HTTP layer via MockAgent.
+ *
+ * The service calls `fetch(url, { dispatcher: agent })` where `agent` is the
+ * mTLS undici.Agent built from the peer's cert+key.  To make MockAgent work,
+ * we need the fetch dispatcher to be the MockAgent, not the per-peer Agent.
+ *
+ * Strategy: we replace the private `resolveEntry` result's `agent` field with
+ * the MockAgent's pool, so fetch uses our interceptor.  We do this by spying
+ * on `resolveEntry` and returning a controlled entry.
+ */
+function makeService(db: Db, mockPool: Dispatcher): FederationClientService {
+  const svc = new FederationClientService(db);
+
+  // Override resolveEntry to inject MockAgent pool as the dispatcher
+  vi.spyOn(
+    svc as unknown as { resolveEntry: (peerId: string) => Promise<unknown> },
+    'resolveEntry',
+  ).mockImplementation(async (_peerId: string) => {
+    // Still call DB (via the real logic) to exercise peer validation,
+    // but return mock pool as the agent.
+    // For simplicity in unit tests, directly return a controlled entry.
+    return {
+      agent: mockPool,
+      endpointUrl: ENDPOINT,
+      certPem: TEST_CERT_PEM,
+      certSerial: TEST_CERT_SERIAL,
+    };
+  });
+
+  return svc;
+}
+
+// ---------------------------------------------------------------------------
+// Test setup
+// ---------------------------------------------------------------------------
+
+let originalDispatcher: Dispatcher;
+
+beforeAll(() => {
+  // Seal the test key once — requires BETTER_AUTH_SECRET
+  const saved = process.env['BETTER_AUTH_SECRET'];
+  process.env['BETTER_AUTH_SECRET'] = TEST_SECRET;
+  try {
+    SEALED_KEY = sealClientKey(TEST_PRIVATE_KEY_PEM);
+  } finally {
+    if (saved === undefined) {
+      delete process.env['BETTER_AUTH_SECRET'];
+    } else {
+      process.env['BETTER_AUTH_SECRET'] = saved;
+    }
+  }
+  writeFileSync(STUB_CA_PEM_PATH, STUB_CA_PEM, 'utf8');
+});
+
+afterAll(() => {
+  try {
+    unlinkSync(STUB_CA_PEM_PATH);
+  } catch {
+    // best-effort cleanup
+  }
+});
+
+beforeEach(() => {
+  originalDispatcher = getGlobalDispatcher();
+  process.env['BETTER_AUTH_SECRET'] = TEST_SECRET;
+  process.env['STEP_CA_ROOT_CERT_PATH'] = STUB_CA_PEM_PATH;
+});
+
+afterEach(() => {
+  setGlobalDispatcher(originalDispatcher);
+  vi.restoreAllMocks();
+  delete process.env['BETTER_AUTH_SECRET'];
+  delete process.env['STEP_CA_ROOT_CERT_PATH'];
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Successful list response body */
+const LIST_BODY = {
+  items: [{ id: '1', title: 'Task One' }],
+  nextCursor: undefined,
+  _partial: false,
+};
+
+/** Successful get response body */
+const GET_BODY = {
+  item: { id: '1', title: 'Task One' },
+  _partial: false,
+};
+
+/** Successful capabilities response body */
+const CAP_BODY = {
+  resources: ['tasks'],
+  excluded_resources: [],
+  max_rows_per_query: 100,
+  supported_verbs: ['list', 'get', 'capabilities'] as const,
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('FederationClientService', () => {
+  // ─── Successful verb calls ─────────────────────────────────────────────────
+
+  describe('list()', () => {
+    it('returns parsed typed response on success', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      pool
+        .intercept({
+          path: '/api/federation/v1/list/tasks',
+          method: 'POST',
+        })
+        .reply(200, LIST_BODY, { headers: { 'content-type': 'application/json' } });
+
+      const result = await svc.list(PEER_ID, 'tasks', {});
+
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0]).toMatchObject({ id: '1', title: 'Task One' });
+
+      await mockAgent.close();
+    });
+  });
+
+  describe('get()', () => {
+    it('returns parsed typed response on success', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      pool
+        .intercept({
+          path: '/api/federation/v1/get/tasks/1',
+          method: 'POST',
+        })
+        .reply(200, GET_BODY, { headers: { 'content-type': 'application/json' } });
+
+      const result = await svc.get(PEER_ID, 'tasks', '1', {});
+
+      expect(result.item).toMatchObject({ id: '1', title: 'Task One' });
+
+      await mockAgent.close();
+    });
+  });
+
+  describe('capabilities()', () => {
+    it('returns parsed capabilities response on success', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      pool
+        .intercept({
+          path: '/api/federation/v1/capabilities',
+          method: 'GET',
+        })
+        .reply(200, CAP_BODY, { headers: { 'content-type': 'application/json' } });
+
+      const result = await svc.capabilities(PEER_ID);
+
+      expect(result.resources).toContain('tasks');
+      expect(result.max_rows_per_query).toBe(100);
+
+      await mockAgent.close();
+    });
+  });
+
+  // ─── HTTP error surfaces ──────────────────────────────────────────────────
+
+  describe('non-2xx responses', () => {
+    it('surfaces 403 as FederationClientError({ status: 403, code: "FORBIDDEN" })', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      pool.intercept({ path: '/api/federation/v1/list/tasks', method: 'POST' }).reply(
+        403,
+        { error: { code: 'forbidden', message: 'Access denied' } },
+        {
+          headers: { 'content-type': 'application/json' },
+        },
+      );
+
+      await expect(svc.list(PEER_ID, 'tasks', {})).rejects.toMatchObject({
+        status: 403,
+        code: 'FORBIDDEN',
+        peerId: PEER_ID,
+      });
+
+      await mockAgent.close();
+    });
+
+    it('surfaces 404 as FederationClientError({ status: 404, code: "HTTP_404" })', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      pool.intercept({ path: '/api/federation/v1/get/tasks/999', method: 'POST' }).reply(
+        404,
+        { error: { code: 'not_found', message: 'Not found' } },
+        {
+          headers: { 'content-type': 'application/json' },
+        },
+      );
+
+      await expect(svc.get(PEER_ID, 'tasks', '999', {})).rejects.toMatchObject({
+        status: 404,
+        code: 'HTTP_404',
+        peerId: PEER_ID,
+      });
+
+      await mockAgent.close();
+    });
+  });
+
+  // ─── Network error ─────────────────────────────────────────────────────────
+
+  describe('network errors', () => {
+    it('surfaces network error as FederationClientError({ code: "NETWORK" })', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      pool
+        .intercept({ path: '/api/federation/v1/capabilities', method: 'GET' })
+        .replyWithError(new Error('ECONNREFUSED'));
+
+      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
+        code: 'NETWORK',
+        peerId: PEER_ID,
+      });
+
+      await mockAgent.close();
+    });
+  });
+
+  // ─── Invalid response body ─────────────────────────────────────────────────
+
+  describe('invalid response body', () => {
+    it('surfaces as FederationClientError({ code: "INVALID_RESPONSE" }) when body shape is wrong', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      // capabilities returns wrong shape (missing required fields)
+      pool
+        .intercept({ path: '/api/federation/v1/capabilities', method: 'GET' })
+        .reply(200, { totally: 'wrong' }, { headers: { 'content-type': 'application/json' } });
+
+      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
+        code: 'INVALID_RESPONSE',
+        peerId: PEER_ID,
+      });
+
+      await mockAgent.close();
+    });
+  });
+
+  // ─── Peer DB validation ────────────────────────────────────────────────────
+
+  describe('peer validation (without resolveEntry spy)', () => {
+    /**
+     * These tests exercise the real `resolveEntry` path — no spy on resolveEntry.
+     */
+
+    it('throws PEER_NOT_FOUND when peer is not in DB', async () => {
+      // DB returns empty array (peer not found)
+      const db = makeDb([]);
+      const svc = new FederationClientService(db);
+
+      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
+        code: 'PEER_NOT_FOUND',
+        peerId: PEER_ID,
+      });
+    });
+
+    it('throws PEER_INACTIVE when peer state is not "active"', async () => {
+      const db = makeDb([makePeerRow({ state: 'suspended' })]);
+      const svc = new FederationClientService(db);
+
+      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
+        code: 'PEER_INACTIVE',
+        peerId: PEER_ID,
+      });
+    });
+  });
+
+  // ─── Cache behaviour ───────────────────────────────────────────────────────
+
+  describe('cache behaviour', () => {
+    it('hits cache on second call — only one DB lookup happens', async () => {
+      // Verify cache by calling the private resolveEntry directly twice and
+      // asserting the DB was queried only once. This avoids the HTTP layer,
+      // which would require either a real network or per-peer Agent rewiring
+      // that the cache invariant doesn't depend on.
+      const db = makeDb();
+      const selectSpy = vi.spyOn(db, 'select');
+      const svc = new FederationClientService(db);
+      const resolveEntry = (
+        svc as unknown as { resolveEntry: (peerId: string) => Promise<unknown> }
+      ).resolveEntry.bind(svc);
+
+      const first = await resolveEntry(PEER_ID);
+      const second = await resolveEntry(PEER_ID);
+
+      expect(first).toBe(second);
+      expect(selectSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('serializes concurrent resolveEntry calls — only one DB lookup', async () => {
+      const db = makeDb();
+      const selectSpy = vi.spyOn(db, 'select');
+      const svc = new FederationClientService(db);
+      const resolveEntry = (
+        svc as unknown as {
+          resolveEntry: (peerId: string) => Promise<unknown>;
+        }
+      ).resolveEntry.bind(svc);
+
+      const [a, b] = await Promise.all([resolveEntry(PEER_ID), resolveEntry(PEER_ID)]);
+      expect(a).toBe(b);
+      expect(selectSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('flushPeer destroys the evicted Agent so old TLS connections close', async () => {
+      const db = makeDb();
+      const svc = new FederationClientService(db);
+      const resolveEntry = (
+        svc as unknown as {
+          resolveEntry: (peerId: string) => Promise<{ agent: { destroy: () => Promise<void> } }>;
+        }
+      ).resolveEntry.bind(svc);
+
+      const entry = await resolveEntry(PEER_ID);
+      const destroySpy = vi.spyOn(entry.agent, 'destroy').mockResolvedValue();
+
+      svc.flushPeer(PEER_ID);
+      expect(destroySpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('flushPeer() invalidates cache — next call re-reads DB', async () => {
+      const db = makeDb();
+      const { mockAgent, pool } = makeMockAgent();
+      const svc = makeService(db, pool);
+
+      pool
+        .intercept({ path: '/api/federation/v1/capabilities', method: 'GET' })
+        .reply(200, CAP_BODY, { headers: { 'content-type': 'application/json' } })
+        .times(2);
+
+      // First call — populates cache (via mock resolveEntry)
+      await svc.capabilities(PEER_ID);
+
+      // Flush the cache
+      svc.flushPeer(PEER_ID);
+
+      // The spy on resolveEntry is still active — check it's called again after flush
+      const resolveEntrySpy = vi.spyOn(
+        svc as unknown as { resolveEntry: (peerId: string) => Promise<unknown> },
+        'resolveEntry',
+      );
+
+      // Second call after flush — should call resolveEntry again
+      await svc.capabilities(PEER_ID);
+
+      // resolveEntry should have been called once after we started spying (post-flush)
+      expect(resolveEntrySpy).toHaveBeenCalledTimes(1);
+
+      await mockAgent.close();
+    });
+  });
+
+  // ─── loadStepCaRoot env-var guard ─────────────────────────────────────────
+
+  describe('loadStepCaRoot() env-var guard', () => {
+    it('throws PEER_MISCONFIGURED when STEP_CA_ROOT_CERT_PATH is not set', async () => {
+      delete process.env['STEP_CA_ROOT_CERT_PATH'];
+      const db = makeDb();
+      const svc = new FederationClientService(db);
+      const resolveEntry = (
+        svc as unknown as {
+          resolveEntry: (peerId: string) => Promise<unknown>;
+        }
+      ).resolveEntry.bind(svc);
+
+      await expect(resolveEntry(PEER_ID)).rejects.toMatchObject({
+        code: 'PEER_MISCONFIGURED',
+      });
+    });
+  });
+
+  // ─── FederationClientError class ──────────────────────────────────────────
+
+  describe('FederationClientError', () => {
+    it('is instanceof Error and FederationClientError', () => {
+      const err = new FederationClientError({
+        code: 'PEER_NOT_FOUND',
+        message: 'test',
+        peerId: PEER_ID,
+      });
+      expect(err).toBeInstanceOf(Error);
+      expect(err).toBeInstanceOf(FederationClientError);
+      expect(err.name).toBe('FederationClientError');
+    });
+
+    it('carries status, code, and peerId', () => {
+      const err = new FederationClientError({
+        status: 403,
+        code: 'FORBIDDEN',
+        message: 'forbidden',
+        peerId: PEER_ID,
+      });
+      expect(err.status).toBe(403);
+      expect(err.code).toBe('FORBIDDEN');
+      expect(err.peerId).toBe(PEER_ID);
+    });
+  });
+});

apps/gateway/src/federation/client/federation-client.service.ts

@@ -0,0 +1,500 @@
+/**
+ * FederationClientService — outbound mTLS client for federation requests (FED-M3-08).
+ *
+ * Dials peer gateways over mTLS using the cert+sealed-key stored in `federation_peers`,
+ * invokes federation verbs (list / get / capabilities), and surfaces all failure modes
+ * as typed `FederationClientError` instances.
+ *
+ * ## Error code taxonomy
+ *
+ * | Code               | When                                                          |
+ * | ------------------ | ------------------------------------------------------------- |
+ * | PEER_NOT_FOUND     | No row in federation_peers for the given peerId               |
+ * | PEER_INACTIVE      | Peer row exists but state !== 'active'                        |
+ * | PEER_MISCONFIGURED | Peer row is active but missing endpointUrl or clientKeyPem    |
+ * | NETWORK            | undici threw a connection / TLS / timeout error               |
+ * | HTTP_{status}      | Peer returned a non-2xx response (e.g. HTTP_403, HTTP_404)    |
+ * | FORBIDDEN          | Peer returned 403 (convenience alias alongside HTTP_403)      |
+ * | INVALID_RESPONSE   | Response body failed Zod schema validation                    |
+ *
+ * ## Cache strategy
+ *
+ * Per-peer `undici.Agent` instances are cached in a `Map<peerId, AgentCacheEntry>` for
+ * the lifetime of the service instance.  The cache is keyed on peerId (UUID).
+ *
+ * Cache invalidation:
+ *  - `flushPeer(peerId)` — removes the entry immediately.  M5/M6 MUST call this on
+ *    cert rotation or peer revocation events so the next request re-reads the DB and
+ *    builds a fresh TLS Agent with the new cert material.
+ *  - On cache miss: re-reads the DB, checks state === 'active', rebuilds Agent.
+ *
+ * Cache does NOT auto-expire.  The service is expected to be a singleton scoped to the
+ * NestJS application lifecycle; flushing on revocation/rotation is the only invalidation
+ * path by design (avoids redundant DB round-trips on the hot path).
+ */
+
+import { Injectable, Inject, Logger } from '@nestjs/common';
+import { readFileSync } from 'node:fs';
+import { Agent, fetch as undiciFetch } from 'undici';
+import type { Dispatcher } from 'undici';
+import { z } from 'zod';
+import { type Db, eq, federationPeers } from '@mosaicstack/db';
+import {
+  FederationListResponseSchema,
+  FederationGetResponseSchema,
+  FederationCapabilitiesResponseSchema,
+  FederationErrorEnvelopeSchema,
+  type FederationListResponse,
+  type FederationGetResponse,
+  type FederationCapabilitiesResponse,
+} from '@mosaicstack/types';
+import { DB } from '../../database/database.module.js';
+import { unsealClientKey } from '../peer-key.util.js';
+
+// ---------------------------------------------------------------------------
+// Error taxonomy
+// ---------------------------------------------------------------------------
+
+/**
+ * Client-side error code set.  Distinct from the server-side `FederationErrorCode`
+ * (which lives in `@mosaicstack/types`) because the client has additional failure
+ * modes (PEER_NOT_FOUND, PEER_INACTIVE, PEER_MISCONFIGURED, NETWORK) that the
+ * server never emits.
+ */
+export type FederationClientErrorCode =
+  | 'PEER_NOT_FOUND'
+  | 'PEER_INACTIVE'
+  | 'PEER_MISCONFIGURED'
+  | 'NETWORK'
+  | 'FORBIDDEN'
+  | 'INVALID_RESPONSE'
+  | `HTTP_${number}`;
+
+export interface FederationClientErrorOptions {
+  status?: number;
+  code: FederationClientErrorCode;
+  message: string;
+  peerId: string;
+  cause?: unknown;
+}
+
+/**
+ * Thrown by FederationClientService on every failure path.
+ * Callers can dispatch on `error.code` for programmatic handling.
+ */
+export class FederationClientError extends Error {
+  readonly status?: number;
+  readonly code: FederationClientErrorCode;
+  readonly peerId: string;
+  readonly cause?: unknown;
+
+  constructor(opts: FederationClientErrorOptions) {
+    super(opts.message);
+    this.name = 'FederationClientError';
+    this.status = opts.status;
+    this.code = opts.code;
+    this.peerId = opts.peerId;
+    this.cause = opts.cause;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal cache types
+// ---------------------------------------------------------------------------
+
+interface AgentCacheEntry {
+  agent: Agent;
+  endpointUrl: string;
+  certPem: string;
+  certSerial: string;
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+@Injectable()
+export class FederationClientService {
+  private readonly logger = new Logger(FederationClientService.name);
+
+  /**
+   * Per-peer undici Agent cache.
+   * Key = peerId (UUID string).
+   *
+   * Values are either a resolved `AgentCacheEntry` or an in-flight
+   * `Promise<AgentCacheEntry>` (promise-cache pattern).  Storing the promise
+   * prevents duplicate DB lookups and duplicate key-unseal operations when two
+   * requests for the same peer arrive before the first build completes.
+   *
+   * Flush via `flushPeer(peerId)` on cert rotation / peer revocation (M5/M6).
+   */
+  private readonly cache = new Map<string, AgentCacheEntry | Promise<AgentCacheEntry>>();
+
+  /**
+   * Step-CA root cert PEM, loaded once from `STEP_CA_ROOT_CERT_PATH`.
+   * Used as the trust anchor for peer server certificates so federation TLS is
+   * pinned to our PKI, not the public trust store. Lazily loaded on first use
+   * so unit tests that don't exercise the agent path can run without the env var.
+   */
+  private cachedCaPem: string | null = null;
+
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  // -------------------------------------------------------------------------
+  // Public verb API
+  // -------------------------------------------------------------------------
+
+  /**
+   * Invoke the `list` verb on a remote peer.
+   *
+   * @param peerId   UUID of the peer row in `federation_peers`.
+   * @param resource Resource path, e.g. "tasks".
+   * @param request  Free-form body sent as JSON in the POST body.
+   * @returns Parsed `FederationListResponse<T>`.
+   */
+  async list<T>(
+    peerId: string,
+    resource: string,
+    request: Record<string, unknown>,
+  ): Promise<FederationListResponse<T>> {
+    const { endpointUrl, agent } = await this.resolveEntry(peerId);
+    const url = `${endpointUrl}/api/federation/v1/list/${encodeURIComponent(resource)}`;
+    const body = await this.doPost(peerId, url, agent, request);
+    return this.parseWith<FederationListResponse<T>>(
+      peerId,
+      body,
+      FederationListResponseSchema(z.unknown()),
+    );
+  }
+
+  /**
+   * Invoke the `get` verb on a remote peer.
+   *
+   * @param peerId   UUID of the peer row in `federation_peers`.
+   * @param resource Resource path, e.g. "tasks".
+   * @param id       Resource identifier.
+   * @param request  Free-form body sent as JSON in the POST body.
+   * @returns Parsed `FederationGetResponse<T>`.
+   */
+  async get<T>(
+    peerId: string,
+    resource: string,
+    id: string,
+    request: Record<string, unknown>,
+  ): Promise<FederationGetResponse<T>> {
+    const { endpointUrl, agent } = await this.resolveEntry(peerId);
+    const url = `${endpointUrl}/api/federation/v1/get/${encodeURIComponent(resource)}/${encodeURIComponent(id)}`;
+    const body = await this.doPost(peerId, url, agent, request);
+    return this.parseWith<FederationGetResponse<T>>(
+      peerId,
+      body,
+      FederationGetResponseSchema(z.unknown()),
+    );
+  }
+
+  /**
+   * Invoke the `capabilities` verb on a remote peer.
+   *
+   * @param peerId UUID of the peer row in `federation_peers`.
+   * @returns Parsed `FederationCapabilitiesResponse`.
+   */
+  async capabilities(peerId: string): Promise<FederationCapabilitiesResponse> {
+    const { endpointUrl, agent } = await this.resolveEntry(peerId);
+    const url = `${endpointUrl}/api/federation/v1/capabilities`;
+    const body = await this.doGet(peerId, url, agent);
+    return this.parseWith<FederationCapabilitiesResponse>(
+      peerId,
+      body,
+      FederationCapabilitiesResponseSchema,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Cache management
+  // -------------------------------------------------------------------------
+
+  /**
+   * Flush the cached Agent for a specific peer.
+   *
+   * M5/M6 MUST call this on:
+   *  - cert rotation events (so new cert material is picked up)
+   *  - peer revocation events (so future requests fail at PEER_INACTIVE)
+   *
+   * After flushing, the next call to `list`, `get`, or `capabilities` for
+   * this peer will re-read the DB and rebuild the Agent.
+   */
+  flushPeer(peerId: string): void {
+    const entry = this.cache.get(peerId);
+    if (entry === undefined) {
+      return;
+    }
+    this.cache.delete(peerId);
+    if (!(entry instanceof Promise)) {
+      // best-effort destroy; promise-cached entries skip destroy because
+      // the in-flight build owns its own Agent which will be GC'd when the
+      // owning request handles the rejection from the cache miss
+      entry.agent.destroy().catch(() => {
+        // intentionally ignored — destroy errors are not actionable
+      });
+    }
+    this.logger.log(`Cache flushed for peer ${peerId}`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Load and cache the Step-CA root cert PEM from `STEP_CA_ROOT_CERT_PATH`.
+   * Throws `FederationClientError` if the env var is unset or the file cannot
+   * be read — mTLS to a peer without a pinned trust anchor would silently
+   * fall back to the public trust store.
+   */
+  private loadStepCaRoot(): string {
+    if (this.cachedCaPem !== null) {
+      return this.cachedCaPem;
+    }
+    const path = process.env['STEP_CA_ROOT_CERT_PATH'];
+    if (!path) {
+      throw new FederationClientError({
+        code: 'PEER_MISCONFIGURED',
+        message: 'STEP_CA_ROOT_CERT_PATH is not set; refusing to dial peer without pinned CA trust',
+        peerId: '',
+      });
+    }
+    try {
+      const pem = readFileSync(path, 'utf8');
+      this.cachedCaPem = pem;
+      return pem;
+    } catch (err) {
+      throw new FederationClientError({
+        code: 'PEER_MISCONFIGURED',
+        message: `Failed to read STEP_CA_ROOT_CERT_PATH (${path})`,
+        peerId: '',
+        cause: err,
+      });
+    }
+  }
+
+  /**
+   * Resolve the cache entry for a peer, reading DB on miss.
+   *
+   * Uses a promise-cache pattern: concurrent callers for the same uncached
+   * `peerId` all `await` the same in-flight `Promise<AgentCacheEntry>` so
+   * only one DB lookup and one key-unseal ever runs per peer per cache miss.
+   * The promise is replaced with the concrete entry on success, or deleted on
+   * rejection so a transient error does not poison the cache permanently.
+   *
+   * Throws `FederationClientError` with appropriate code if the peer is not
+   * found, is inactive, or is missing required fields.
+   */
+  private async resolveEntry(peerId: string): Promise<AgentCacheEntry> {
+    const cached = this.cache.get(peerId);
+    if (cached) {
+      return cached; // Promise or concrete entry — both are awaitable
+    }
+
+    const inflight = this.buildEntry(peerId).then(
+      (entry) => {
+        this.cache.set(peerId, entry); // replace promise with concrete value
+        return entry;
+      },
+      (err: unknown) => {
+        this.cache.delete(peerId); // don't poison the cache with a rejected promise
+        throw err;
+      },
+    );
+
+    this.cache.set(peerId, inflight);
+    return inflight;
+  }
+
+  /**
+   * Build the `AgentCacheEntry` for a peer by reading the DB, validating the
+   * peer's state, unsealing the private key, and constructing the mTLS Agent.
+   *
+   * Throws `FederationClientError` with appropriate code if the peer is not
+   * found, is inactive, or is missing required fields.
+   */
+  private async buildEntry(peerId: string): Promise<AgentCacheEntry> {
+    // DB lookup
+    const [peer] = await this.db
+      .select()
+      .from(federationPeers)
+      .where(eq(federationPeers.id, peerId))
+      .limit(1);
+
+    if (!peer) {
+      throw new FederationClientError({
+        code: 'PEER_NOT_FOUND',
+        message: `Federation peer ${peerId} not found`,
+        peerId,
+      });
+    }
+
+    if (peer.state !== 'active') {
+      throw new FederationClientError({
+        code: 'PEER_INACTIVE',
+        message: `Federation peer ${peerId} is not active (state: ${peer.state})`,
+        peerId,
+      });
+    }
+
+    if (!peer.endpointUrl || !peer.clientKeyPem) {
+      throw new FederationClientError({
+        code: 'PEER_MISCONFIGURED',
+        message: `Federation peer ${peerId} is missing endpointUrl or clientKeyPem`,
+        peerId,
+      });
+    }
+
+    // Unseal the private key
+    let privateKeyPem: string;
+    try {
+      privateKeyPem = unsealClientKey(peer.clientKeyPem);
+    } catch (err) {
+      throw new FederationClientError({
+        code: 'PEER_MISCONFIGURED',
+        message: `Failed to unseal client key for peer ${peerId}`,
+        peerId,
+        cause: err,
+      });
+    }
+
+    // Build mTLS agent — pin trust to Step-CA root so we never accept
+    // a peer cert signed by a public CA (defense against MITM with a
+    // publicly-trusted DV cert for the peer's hostname).
+    const agent = new Agent({
+      connect: {
+        cert: peer.certPem,
+        key: privateKeyPem,
+        ca: this.loadStepCaRoot(),
+        // rejectUnauthorized: true is the undici default for HTTPS
+      },
+    });
+
+    const entry: AgentCacheEntry = {
+      agent,
+      endpointUrl: peer.endpointUrl,
+      certPem: peer.certPem,
+      certSerial: peer.certSerial,
+    };
+
+    this.logger.log(`Agent cached for peer ${peerId} (serial: ${peer.certSerial})`);
+
+    return entry;
+  }
+
+  /**
+   * Execute a POST request with a JSON body.
+   * Returns the parsed response body as an unknown value.
+   * Throws `FederationClientError` on network errors and non-2xx responses.
+   */
+  private async doPost(
+    peerId: string,
+    url: string,
+    agent: Dispatcher,
+    body: Record<string, unknown>,
+  ): Promise<unknown> {
+    return this.doRequest(peerId, url, agent, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Execute a GET request.
+   * Returns the parsed response body as an unknown value.
+   * Throws `FederationClientError` on network errors and non-2xx responses.
+   */
+  private async doGet(peerId: string, url: string, agent: Dispatcher): Promise<unknown> {
+    return this.doRequest(peerId, url, agent, { method: 'GET' });
+  }
+
+  private async doRequest(
+    peerId: string,
+    url: string,
+    agent: Dispatcher,
+    init: { method: string; headers?: Record<string, string>; body?: string },
+  ): Promise<unknown> {
+    let response: Awaited<ReturnType<typeof undiciFetch>>;
+
+    try {
+      response = await undiciFetch(url, {
+        ...init,
+        dispatcher: agent,
+      });
+    } catch (err) {
+      throw new FederationClientError({
+        code: 'NETWORK',
+        message: `Network error calling peer ${peerId} at ${url}: ${err instanceof Error ? err.message : String(err)}`,
+        peerId,
+        cause: err,
+      });
+    }
+
+    const rawBody = await response.text().catch(() => '');
+
+    if (!response.ok) {
+      const status = response.status;
+
+      // Attempt to parse as federation error envelope
+      let serverMessage = `HTTP ${status}`;
+      try {
+        const json: unknown = JSON.parse(rawBody);
+        const result = FederationErrorEnvelopeSchema.safeParse(json);
+        if (result.success) {
+          serverMessage = result.data.error.message;
+        }
+      } catch {
+        // Not valid JSON or not a federation envelope — use generic message
+      }
+
+      // Specific code for 403 (most actionable for callers); generic HTTP_{n} for others
+      const code: FederationClientErrorCode = status === 403 ? 'FORBIDDEN' : `HTTP_${status}`;
+
+      throw new FederationClientError({
+        status,
+        code,
+        message: `Peer ${peerId} returned ${status}: ${serverMessage}`,
+        peerId,
+      });
+    }
+
+    try {
+      return JSON.parse(rawBody) as unknown;
+    } catch (err) {
+      throw new FederationClientError({
+        code: 'INVALID_RESPONSE',
+        message: `Peer ${peerId} returned non-JSON body`,
+        peerId,
+        cause: err,
+      });
+    }
+  }
+
+  /**
+   * Parse and validate a response body against a Zod schema.
+   *
+   * For list/get, callers pass the result of `FederationListResponseSchema(z.unknown())`
+   * so that the envelope structure is validated without requiring a concrete item schema
+   * at the client level.  The generic `T` provides compile-time typing.
+   *
+   * Throws `FederationClientError({ code: 'INVALID_RESPONSE' })` on parse failure.
+   */
+  private parseWith<T>(peerId: string, body: unknown, schema: z.ZodTypeAny): T {
+    const result = schema.safeParse(body);
+    if (!result.success) {
+      const issues = result.error.issues
+        .map((e: z.ZodIssue) => `[${e.path.join('.') || 'root'}] ${e.message}`)
+        .join('; ');
+      throw new FederationClientError({
+        code: 'INVALID_RESPONSE',
+        message: `Peer ${peerId} returned invalid response shape: ${issues}`,
+        peerId,
+      });
+    }
+    return result.data as T;
+  }
+}

apps/gateway/src/federation/client/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Federation client barrel — re-exports for FederationModule consumers.
+ *
+ * M3-09 (QuerySourceService) and future milestones should import from here,
+ * not directly from the implementation file.
+ */
+
+export {
+  FederationClientService,
+  FederationClientError,
+  type FederationClientErrorCode,
+  type FederationClientErrorOptions,
+} from './federation-client.service.js';

apps/gateway/src/federation/federation.module.ts

@@ -5,10 +5,25 @@ import { EnrollmentController } from './enrollment.controller.js';
 import { EnrollmentService } from './enrollment.service.js';
 import { FederationController } from './federation.controller.js';
 import { GrantsService } from './grants.service.js';
+import { FederationClientService } from './client/index.js';
+import { FederationAuthGuard } from './server/index.js';
 
 @Module({
   controllers: [EnrollmentController, FederationController],
-  providers: [AdminGuard, CaService, EnrollmentService, GrantsService],
-  exports: [CaService, EnrollmentService, GrantsService],
+  providers: [
+    AdminGuard,
+    CaService,
+    EnrollmentService,
+    GrantsService,
+    FederationClientService,
+    FederationAuthGuard,
+  ],
+  exports: [
+    CaService,
+    EnrollmentService,
+    GrantsService,
+    FederationClientService,
+    FederationAuthGuard,
+  ],
 })
 export class FederationModule {}

apps/gateway/src/federation/grants.service.ts

@@ -10,12 +10,14 @@
  */
 
 import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
-import { type Db, and, eq, federationGrants } from '@mosaicstack/db';
+import { type Db, and, eq, federationGrants, federationPeers } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import { parseFederationScope } from './scope-schema.js';
 import type { CreateGrantDto, ListGrantsDto } from './grants.dto.js';
 
 export type Grant = typeof federationGrants.$inferSelect;
+export type Peer = typeof federationPeers.$inferSelect;
+export type GrantWithPeer = Grant & { peer: Peer };
 
 @Injectable()
 export class GrantsService {
@@ -60,6 +62,33 @@ export class GrantsService {
     return grant;
   }
 
+  /**
+   * Fetch a single grant by ID, joined with its associated peer row.
+   * Used by FederationAuthGuard to perform grant status + cert serial checks
+   * in a single DB round-trip.
+   *
+   * Throws NotFoundException if the grant does not exist.
+   * Throws NotFoundException if the associated peer row is missing (data integrity issue).
+   */
+  async getGrantWithPeer(id: string): Promise<GrantWithPeer> {
+    const rows = await this.db
+      .select()
+      .from(federationGrants)
+      .innerJoin(federationPeers, eq(federationGrants.peerId, federationPeers.id))
+      .where(eq(federationGrants.id, id))
+      .limit(1);
+
+    const row = rows[0];
+    if (!row) {
+      throw new NotFoundException(`Grant ${id} not found`);
+    }
+
+    return {
+      ...row.federation_grants,
+      peer: row.federation_peers,
+    };
+  }
+
   /**
    * List grants with optional filters for peerId, subjectUserId, and status.
    */

apps/gateway/src/federation/oid.util.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared OID extraction helpers for Mosaic federation certificates.
+ *
+ * Custom OID registry (PRD §6, docs/federation/SETUP.md):
+ *   1.3.6.1.4.1.99999.1  — mosaic_grant_id
+ *   1.3.6.1.4.1.99999.2  — mosaic_subject_user_id
+ *
+ * The encoding convention: each extension value is an OCTET STRING wrapping
+ * an ASN.1 UTF8String TLV:
+ *   0x0C (tag) + 1-byte length + UTF-8 bytes
+ *
+ * CaService encodes values this way via encodeUtf8String(), and this module
+ * decodes them with the corresponding `.slice(2)` to skip tag + length byte.
+ *
+ * This module is intentionally pure — no NestJS, no DB, no network I/O.
+ */
+
+import { X509Certificate } from '@peculiar/x509';
+
+// ---------------------------------------------------------------------------
+// OID constants
+// ---------------------------------------------------------------------------
+
+export const OID_MOSAIC_GRANT_ID = '1.3.6.1.4.1.99999.1';
+export const OID_MOSAIC_SUBJECT_USER_ID = '1.3.6.1.4.1.99999.2';
+
+// ---------------------------------------------------------------------------
+// Extraction result types
+// ---------------------------------------------------------------------------
+
+export interface MosaicOids {
+  grantId: string;
+  subjectUserId: string;
+}
+
+export type OidExtractionResult =
+  | { ok: true; value: MosaicOids }
+  | {
+      ok: false;
+      error: 'MISSING_GRANT_ID' | 'MISSING_SUBJECT_USER_ID' | 'PARSE_ERROR';
+      detail?: string;
+    };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const decoder = new TextDecoder();
+
+/**
+ * Decode an extension value encoded as ASN.1 UTF8String TLV
+ * (tag 0x0C + 1-byte length + UTF-8 bytes).
+ * Validates tag, length byte, and buffer bounds before decoding.
+ * Throws a descriptive Error on malformed input; caller wraps in try/catch.
+ */
+function decodeUtf8StringTlv(value: ArrayBuffer): string {
+  const bytes = new Uint8Array(value);
+
+  // Need at least tag + length bytes
+  if (bytes.length < 2) {
+    throw new Error(`UTF8String TLV too short: expected at least 2 bytes, got ${bytes.length}`);
+  }
+
+  // Tag byte must be 0x0C (ASN.1 UTF8String)
+  if (bytes[0] !== 0x0c) {
+    throw new Error(
+      `UTF8String TLV tag mismatch: expected 0x0C, got 0x${bytes[0]!.toString(16).toUpperCase()}`,
+    );
+  }
+
+  // Only single-byte length form is supported (values 0–127); long form not needed
+  // for OID strings of this length.
+  const declaredLength = bytes[1]!;
+  if (declaredLength > 127) {
+    throw new Error(
+      `UTF8String TLV uses long-form length (0x${declaredLength.toString(16).toUpperCase()}), which is not supported`,
+    );
+  }
+
+  // Declared length must match actual remaining bytes
+  if (declaredLength !== bytes.length - 2) {
+    throw new Error(
+      `UTF8String TLV length mismatch: declared ${declaredLength}, actual ${bytes.length - 2}`,
+    );
+  }
+
+  // Skip: tag (1 byte) + length (1 byte)
+  return decoder.decode(bytes.slice(2));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract Mosaic custom OIDs (grantId, subjectUserId) from an X.509 certificate
+ * already parsed via @peculiar/x509.
+ *
+ * Returns `{ ok: true, value: MosaicOids }` on success, or
+ * `{ ok: false, error: <code>, detail? }` on any failure — never throws.
+ */
+export function extractMosaicOids(cert: X509Certificate): OidExtractionResult {
+  try {
+    const grantIdExt = cert.getExtension(OID_MOSAIC_GRANT_ID);
+    if (!grantIdExt) {
+      return { ok: false, error: 'MISSING_GRANT_ID' };
+    }
+
+    const subjectUserIdExt = cert.getExtension(OID_MOSAIC_SUBJECT_USER_ID);
+    if (!subjectUserIdExt) {
+      return { ok: false, error: 'MISSING_SUBJECT_USER_ID' };
+    }
+
+    const grantId = decodeUtf8StringTlv(grantIdExt.value);
+    const subjectUserId = decodeUtf8StringTlv(subjectUserIdExt.value);
+
+    return {
+      ok: true,
+      value: { grantId, subjectUserId },
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: 'PARSE_ERROR',
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Parse a PEM-encoded certificate and extract Mosaic OIDs.
+ * Returns an OidExtractionResult — never throws.
+ */
+export function extractMosaicOidsFromPem(certPem: string): OidExtractionResult {
+  let cert: X509Certificate;
+  try {
+    cert = new X509Certificate(certPem);
+  } catch (err) {
+    return {
+      ok: false,
+      error: 'PARSE_ERROR',
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+  return extractMosaicOids(cert);
+}

apps/gateway/src/federation/server/__tests__/federation-auth.guard.spec.ts

@@ -0,0 +1,521 @@
+/**
+ * Unit tests for FederationAuthGuard (FED-M3-03).
+ *
+ * Coverage:
+ *  - Missing cert (no TLS socket / no getPeerCertificate) → 401
+ *  - Cert parse failure (corrupt DER raw bytes) → 401
+ *  - Missing grantId OID → 401
+ *  - Missing subjectUserId OID → 401
+ *  - Grant not found (GrantsService throws NotFoundException) → 403
+ *  - Grant in `pending` status → 403
+ *  - Grant in `revoked` status → 403
+ *  - Grant in `expired` status → 403
+ *  - Cert serial mismatch → 403
+ *  - Happy path: active grant + matching cert serial → context attached, returns true
+ */
+
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ExecutionContext } from '@nestjs/common';
+import { NotFoundException } from '@nestjs/common';
+import { FederationAuthGuard } from '../federation-auth.guard.js';
+import { makeMosaicIssuedCert } from '../../__tests__/helpers/test-cert.js';
+import type { GrantsService, GrantWithPeer } from '../../grants.service.js';
+
+// ---------------------------------------------------------------------------
+// Test constants
+// ---------------------------------------------------------------------------
+
+const GRANT_ID = 'a1111111-1111-1111-1111-111111111111';
+const USER_ID = 'b2222222-2222-2222-2222-222222222222';
+const PEER_ID = 'c3333333-3333-3333-3333-333333333333';
+
+// Node.js TLS serialNumber is uppercase hex (no colons)
+const CERT_SERIAL_HEX = '01';
+
+const VALID_SCOPE = { resources: ['tasks'], max_rows_per_query: 100 };
+
+// ---------------------------------------------------------------------------
+// Mock builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a minimal GrantWithPeer-shaped mock.
+ */
+function makeGrantWithPeer(overrides: Partial<GrantWithPeer> = {}): GrantWithPeer {
+  return {
+    id: GRANT_ID,
+    peerId: PEER_ID,
+    subjectUserId: USER_ID,
+    scope: VALID_SCOPE,
+    status: 'active',
+    expiresAt: null,
+    createdAt: new Date('2026-01-01T00:00:00Z'),
+    revokedAt: null,
+    revokedReason: null,
+    peer: {
+      id: PEER_ID,
+      commonName: 'test-peer',
+      displayName: 'Test Peer',
+      certPem: '',
+      certSerial: CERT_SERIAL_HEX,
+      certNotAfter: new Date(Date.now() + 86_400_000),
+      clientKeyPem: null,
+      state: 'active',
+      endpointUrl: null,
+      lastSeenAt: null,
+      createdAt: new Date('2026-01-01T00:00:00Z'),
+      revokedAt: null,
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Build a mock ExecutionContext with a pre-built TLS peer certificate.
+ *
+ * `certPem` — PEM string to present as the raw DER cert (converted to Buffer).
+ *             Pass null to simulate "no cert presented".
+ * `certSerialHex` — serialNumber string returned by the TLS socket.
+ *                   Node.js returns uppercase hex.
+ * `hasTlsSocket` — if false, raw.socket has no getPeerCertificate (plain HTTP).
+ */
+function makeContext(opts: {
+  certPem: string | null;
+  certSerialHex?: string;
+  hasTlsSocket?: boolean;
+}): {
+  ctx: ExecutionContext;
+  statusMock: ReturnType<typeof vi.fn>;
+  sendMock: ReturnType<typeof vi.fn>;
+} {
+  const { certPem, certSerialHex = CERT_SERIAL_HEX, hasTlsSocket = true } = opts;
+
+  // Build peerCert object that Node.js TLS socket.getPeerCertificate() returns
+  let peerCert: Record<string, unknown>;
+  if (certPem === null) {
+    // Simulate no cert: Node.js returns object with empty string fields
+    peerCert = { raw: null, serialNumber: '' };
+  } else {
+    // Convert PEM to DER Buffer (strip headers + base64 decode)
+    const b64 = certPem
+      .replace(/-----BEGIN CERTIFICATE-----/, '')
+      .replace(/-----END CERTIFICATE-----/, '')
+      .replace(/\s+/g, '');
+    const raw = Buffer.from(b64, 'base64');
+    peerCert = { raw, serialNumber: certSerialHex };
+  }
+
+  const getPeerCertificate = vi.fn().mockReturnValue(peerCert);
+
+  const socket = hasTlsSocket ? { getPeerCertificate } : {}; // No getPeerCertificate → non-TLS
+
+  // Fastify reply mocks
+  const sendMock = vi.fn().mockReturnValue(undefined);
+  const headerMock = vi.fn().mockReturnValue({ send: sendMock });
+  const statusMock = vi.fn().mockReturnValue({ header: headerMock });
+
+  const request = {
+    raw: {
+      socket,
+    },
+  };
+
+  const reply = {
+    status: statusMock,
+  };
+
+  const ctx = {
+    switchToHttp: () => ({
+      getRequest: () => request,
+      getResponse: () => reply,
+    }),
+  } as unknown as ExecutionContext;
+
+  return { ctx, statusMock, sendMock };
+}
+
+/**
+ * Build a mock GrantsService.
+ */
+function makeGrantsService(
+  overrides: Partial<Pick<GrantsService, 'getGrantWithPeer'>> = {},
+): GrantsService {
+  return {
+    getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer()),
+    ...overrides,
+  } as unknown as GrantsService;
+}
+
+// ---------------------------------------------------------------------------
+// Test suite
+// ---------------------------------------------------------------------------
+
+describe('FederationAuthGuard', () => {
+  let certPem: string;
+
+  beforeEach(async () => {
+    // Generate a real Mosaic-issued cert with the standard OIDs
+    certPem = await makeMosaicIssuedCert({ grantId: GRANT_ID, subjectUserId: USER_ID });
+  });
+
+  // ── 401: No TLS socket ────────────────────────────────────────────────────
+
+  it('returns 401 when there is no TLS socket (plain HTTP connection)', async () => {
+    const { ctx, statusMock, sendMock } = makeContext({
+      certPem: certPem,
+      hasTlsSocket: false,
+    });
+
+    const guard = new FederationAuthGuard(makeGrantsService());
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(401);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
+      }),
+    );
+  });
+
+  // ── 401: Cert not presented ───────────────────────────────────────────────
+
+  it('returns 401 when the peer did not present a certificate', async () => {
+    const { ctx, statusMock, sendMock } = makeContext({ certPem: null });
+
+    const guard = new FederationAuthGuard(makeGrantsService());
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(401);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
+      }),
+    );
+  });
+
+  // ── 401: Cert parse failure ───────────────────────────────────────────────
+
+  it('returns 401 when the certificate DER bytes are corrupt', async () => {
+    // Build context with a cert that has garbage DER bytes
+    const corruptPem = '-----BEGIN CERTIFICATE-----\naW52YWxpZA==\n-----END CERTIFICATE-----';
+    const { ctx, statusMock, sendMock } = makeContext({ certPem: corruptPem });
+
+    const guard = new FederationAuthGuard(makeGrantsService());
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(401);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
+      }),
+    );
+  });
+
+  // ── 401: Missing grantId OID ─────────────────────────────────────────────
+
+  it('returns 401 when the cert is missing the grantId OID', async () => {
+    // makeSelfSignedCert produces a cert without any Mosaic OIDs
+    const { makeSelfSignedCert } = await import('../../__tests__/helpers/test-cert.js');
+    const plainCert = await makeSelfSignedCert();
+    const { ctx, statusMock, sendMock } = makeContext({ certPem: plainCert });
+
+    const guard = new FederationAuthGuard(makeGrantsService());
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(401);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
+      }),
+    );
+  });
+
+  // ── 401: Missing subjectUserId OID ───────────────────────────────────────
+
+  it('returns 401 when the cert has grantId OID but is missing subjectUserId OID', async () => {
+    // Build a cert with only the grantId OID by importing cert generator internals
+    const { webcrypto } = await import('node:crypto');
+    const {
+      X509CertificateGenerator,
+      Extension,
+      KeyUsagesExtension,
+      KeyUsageFlags,
+      BasicConstraintsExtension,
+      cryptoProvider,
+    } = await import('@peculiar/x509');
+
+    cryptoProvider.set(webcrypto as unknown as Parameters<typeof cryptoProvider.set>[0]);
+
+    const alg = { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' } as const;
+    const keys = await webcrypto.subtle.generateKey(alg, false, ['sign', 'verify']);
+    const now = new Date();
+    const tomorrow = new Date(now.getTime() + 86_400_000);
+
+    // Encode grantId only — missing subjectUserId extension
+    const utf8 = new TextEncoder().encode(GRANT_ID);
+    const encoded = new Uint8Array(2 + utf8.length);
+    encoded[0] = 0x0c;
+    encoded[1] = utf8.length;
+    encoded.set(utf8, 2);
+
+    const cert = await X509CertificateGenerator.createSelfSigned({
+      serialNumber: '01',
+      name: 'CN=partial-oid-test',
+      notBefore: now,
+      notAfter: tomorrow,
+      signingAlgorithm: alg,
+      keys,
+      extensions: [
+        new BasicConstraintsExtension(false),
+        new KeyUsagesExtension(KeyUsageFlags.digitalSignature),
+        new Extension('1.3.6.1.4.1.99999.1', false, encoded), // grantId only
+      ],
+    });
+
+    const { ctx, statusMock, sendMock } = makeContext({ certPem: cert.toString('pem') });
+
+    const guard = new FederationAuthGuard(makeGrantsService());
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(401);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
+      }),
+    );
+  });
+
+  // ── 403: Grant not found ─────────────────────────────────────────────────
+
+  it('returns 403 when the grantId from the cert does not exist in DB', async () => {
+    const grantsService = makeGrantsService({
+      getGrantWithPeer: vi
+        .fn()
+        .mockRejectedValue(new NotFoundException(`Grant ${GRANT_ID} not found`)),
+    });
+
+    const { ctx, statusMock, sendMock } = makeContext({ certPem });
+
+    const guard = new FederationAuthGuard(grantsService);
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(403);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
+      }),
+    );
+  });
+
+  // ── 403: Grant in `pending` status ───────────────────────────────────────
+
+  it('returns 403 when the grant is in pending status', async () => {
+    const grantsService = makeGrantsService({
+      getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer({ status: 'pending' })),
+    });
+
+    const { ctx, statusMock, sendMock } = makeContext({ certPem });
+
+    const guard = new FederationAuthGuard(grantsService);
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(403);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
+      }),
+    );
+  });
+
+  // ── 403: Grant in `revoked` status ───────────────────────────────────────
+
+  it('returns 403 when the grant is in revoked status', async () => {
+    const grantsService = makeGrantsService({
+      getGrantWithPeer: vi
+        .fn()
+        .mockResolvedValue(makeGrantWithPeer({ status: 'revoked', revokedAt: new Date() })),
+    });
+
+    const { ctx, statusMock, sendMock } = makeContext({ certPem });
+
+    const guard = new FederationAuthGuard(grantsService);
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(403);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
+      }),
+    );
+  });
+
+  // ── 403: Grant in `expired` status ───────────────────────────────────────
+
+  it('returns 403 when the grant is in expired status', async () => {
+    const grantsService = makeGrantsService({
+      getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer({ status: 'expired' })),
+    });
+
+    const { ctx, statusMock, sendMock } = makeContext({ certPem });
+
+    const guard = new FederationAuthGuard(grantsService);
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(403);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
+      }),
+    );
+  });
+
+  // ── 403: Cert serial mismatch ─────────────────────────────────────────────
+
+  it('returns 403 when the cert serial does not match the registered peer cert serial', async () => {
+    // Return a grant whose peer has a different stored serial
+    const grantsService = makeGrantsService({
+      getGrantWithPeer: vi.fn().mockResolvedValue(
+        makeGrantWithPeer({
+          peer: {
+            id: PEER_ID,
+            commonName: 'test-peer',
+            displayName: 'Test Peer',
+            certPem: '',
+            certSerial: 'DEADBEEF', // different from CERT_SERIAL_HEX='01'
+            certNotAfter: new Date(Date.now() + 86_400_000),
+            clientKeyPem: null,
+            state: 'active',
+            endpointUrl: null,
+            lastSeenAt: null,
+            createdAt: new Date('2026-01-01T00:00:00Z'),
+            revokedAt: null,
+          },
+        }),
+      ),
+    });
+
+    // Context presents cert with serial '01' but DB has 'DEADBEEF'
+    const { ctx, statusMock, sendMock } = makeContext({ certPem, certSerialHex: '01' });
+
+    const guard = new FederationAuthGuard(grantsService);
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(403);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
+      }),
+    );
+  });
+
+  // ── 403: subjectUserId cert/DB mismatch (CRIT-1 regression test) ─────────
+
+  it('returns 403 when the cert subjectUserId does not match the DB grant subjectUserId', async () => {
+    // Build a cert that claims an attacker's subjectUserId
+    const attackerSubjectUserId = 'attacker-user-id';
+    const attackerCertPem = await makeMosaicIssuedCert({
+      grantId: GRANT_ID,
+      subjectUserId: attackerSubjectUserId,
+    });
+
+    // DB returns a grant with the legitimate USER_ID
+    const grantsService = makeGrantsService({
+      getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer({ subjectUserId: USER_ID })),
+    });
+
+    // Cert presents attacker-user-id but DB has USER_ID — should be rejected
+    const { ctx, statusMock, sendMock } = makeContext({
+      certPem: attackerCertPem,
+      certSerialHex: CERT_SERIAL_HEX,
+    });
+
+    const guard = new FederationAuthGuard(grantsService);
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(false);
+    expect(statusMock).toHaveBeenCalledWith(403);
+    expect(sendMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
+      }),
+    );
+  });
+
+  // ── Happy path ────────────────────────────────────────────────────────────
+
+  it('returns true and attaches federationContext on happy path', async () => {
+    const grant = makeGrantWithPeer({
+      status: 'active',
+      peer: {
+        id: PEER_ID,
+        commonName: 'test-peer',
+        displayName: 'Test Peer',
+        certPem: '',
+        certSerial: CERT_SERIAL_HEX,
+        certNotAfter: new Date(Date.now() + 86_400_000),
+        clientKeyPem: null,
+        state: 'active',
+        endpointUrl: null,
+        lastSeenAt: null,
+        createdAt: new Date('2026-01-01T00:00:00Z'),
+        revokedAt: null,
+      },
+    });
+
+    const grantsService = makeGrantsService({
+      getGrantWithPeer: vi.fn().mockResolvedValue(grant),
+    });
+
+    // Build context manually to capture what gets set on request.federationContext
+    const b64 = certPem
+      .replace(/-----BEGIN CERTIFICATE-----/, '')
+      .replace(/-----END CERTIFICATE-----/, '')
+      .replace(/\s+/g, '');
+    const raw = Buffer.from(b64, 'base64');
+    const peerCert = { raw, serialNumber: CERT_SERIAL_HEX };
+
+    const sendMock = vi.fn().mockReturnValue(undefined);
+    const headerMock = vi.fn().mockReturnValue({ send: sendMock });
+    const statusMock = vi.fn().mockReturnValue({ header: headerMock });
+
+    const request: Record<string, unknown> = {
+      raw: {
+        socket: { getPeerCertificate: vi.fn().mockReturnValue(peerCert) },
+      },
+    };
+
+    const reply = { status: statusMock };
+
+    const ctx = {
+      switchToHttp: () => ({
+        getRequest: () => request,
+        getResponse: () => reply,
+      }),
+    } as unknown as ExecutionContext;
+
+    const guard = new FederationAuthGuard(grantsService);
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(true);
+    expect(statusMock).not.toHaveBeenCalled();
+
+    // Verify the context was attached correctly
+    expect(request['federationContext']).toEqual({
+      grantId: GRANT_ID,
+      subjectUserId: USER_ID,
+      peerId: PEER_ID,
+      scope: VALID_SCOPE,
+    });
+  });
+});

apps/gateway/src/federation/server/federation-auth.guard.ts

@@ -0,0 +1,212 @@
+/**
+ * FederationAuthGuard — NestJS CanActivate guard for inbound federation requests.
+ *
+ * Validates the mTLS client certificate presented by a peer gateway, extracts
+ * custom OIDs to identify the grant + subject user, loads the grant from DB,
+ * asserts it is active, and verifies the cert serial against the registered peer
+ * cert serial as a defense-in-depth measure.
+ *
+ * On success, attaches `request.federationContext` for downstream verb controllers.
+ * On failure, responds with the federation wire-format error envelope (not raw
+ * NestJS exception JSON) to match the federation protocol contract.
+ *
+ * ## Cert-serial check decision
+ * The guard validates that the inbound client cert's serial number matches the
+ * `certSerial` stored on the associated `federation_peers` row. This is a
+ * defense-in-depth measure: even if the mTLS handshake is compromised at the
+ * transport layer (e.g. misconfigured TLS terminator that forwards arbitrary
+ * client certs), an attacker cannot replay a cert with a different serial than
+ * what was registered during enrollment. This check is NOT loosened because:
+ *  1. It is O(1) — no additional DB round-trip (peerId is on the grant row,
+ *     so we join to federationPeers in the same query).
+ *  2. Cert renewal MUST update the stored serial — enforced by M6 scheduler.
+ *  3. The OID-only path (without serial check) would allow any cert from the
+ *     same CA bearing the same grantId OID to succeed after cert compromise.
+ *
+ * ## FastifyRequest typing path
+ * NestJS + Fastify wraps the raw Node.js IncomingMessage in a FastifyRequest.
+ * The underlying TLS socket is accessed via `request.raw.socket`, which is a
+ * `tls.TLSSocket` when the server is listening on HTTPS. In development/test
+ * the gateway may run over plain HTTP, in which case `getPeerCertificate` is
+ * not available. The guard safely handles both cases by checking for the
+ * method's existence before calling it.
+ *
+ * Note: The guard reads the peer certificate from the *already-completed*
+ * TLS handshake via `socket.getPeerCertificate(detailed=true)`. This relies
+ * on the server being configured with `requestCert: true` at the TLS level
+ * so Fastify/Node.js requests the client cert during the handshake.
+ * The guard does NOT verify the cert chain itself — that is handled by the
+ * TLS layer (Node.js `rejectUnauthorized: true` with the CA cert pinned).
+ */
+
+import {
+  type CanActivate,
+  type ExecutionContext,
+  Inject,
+  Injectable,
+  Logger,
+} from '@nestjs/common';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import * as tls from 'node:tls';
+import { X509Certificate } from '@peculiar/x509';
+import { FederationForbiddenError, FederationUnauthorizedError } from '@mosaicstack/types';
+import { extractMosaicOids } from '../oid.util.js';
+import { GrantsService } from '../grants.service.js';
+import type { FederationContext } from './federation-context.js';
+import './federation-context.js'; // side-effect import: applies FastifyRequest module augmentation
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a federation wire-format error response directly on the Fastify reply.
+ * Returns false — callers return this value from canActivate.
+ */
+function sendFederationError(
+  reply: FastifyReply,
+  error: FederationUnauthorizedError | FederationForbiddenError,
+): boolean {
+  const statusCode = error.code === 'unauthorized' ? 401 : 403;
+  void reply.status(statusCode).header('content-type', 'application/json').send(error.toEnvelope());
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Guard
+// ---------------------------------------------------------------------------
+
+@Injectable()
+export class FederationAuthGuard implements CanActivate {
+  private readonly logger = new Logger(FederationAuthGuard.name);
+
+  constructor(@Inject(GrantsService) private readonly grantsService: GrantsService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const http = context.switchToHttp();
+    const request = http.getRequest<FastifyRequest>();
+    const reply = http.getResponse<FastifyReply>();
+
+    // ── Step 1: Extract peer certificate from TLS socket ────────────────────
+    const rawSocket = request.raw.socket;
+
+    // Check TLS socket: getPeerCertificate is only available on TLS connections.
+    if (
+      !rawSocket ||
+      typeof (rawSocket as Partial<tls.TLSSocket>).getPeerCertificate !== 'function'
+    ) {
+      this.logger.warn('No TLS socket — client cert unavailable (non-mTLS connection)');
+      return sendFederationError(
+        reply,
+        new FederationUnauthorizedError('Client certificate required'),
+      );
+    }
+
+    const tlsSocket = rawSocket as tls.TLSSocket;
+    const peerCert = tlsSocket.getPeerCertificate(true);
+
+    // Node.js returns an object with empty string fields when no cert was presented.
+    if (!peerCert || !peerCert.raw) {
+      this.logger.warn('Peer certificate not presented (mTLS handshake did not supply cert)');
+      return sendFederationError(
+        reply,
+        new FederationUnauthorizedError('Client certificate required'),
+      );
+    }
+
+    // ── Step 2: Parse the DER-encoded certificate via @peculiar/x509 ────────
+    let cert: X509Certificate;
+    try {
+      // peerCert.raw is a Buffer containing the DER-encoded cert
+      cert = new X509Certificate(peerCert.raw);
+    } catch (err) {
+      this.logger.warn(
+        `Failed to parse peer certificate: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return sendFederationError(
+        reply,
+        new FederationUnauthorizedError('Client certificate could not be parsed'),
+      );
+    }
+
+    // ── Step 3: Extract Mosaic custom OIDs ──────────────────────────────────
+    const oidResult = extractMosaicOids(cert);
+
+    if (!oidResult.ok) {
+      const message =
+        oidResult.error === 'MISSING_GRANT_ID'
+          ? 'Client certificate is missing required OID: mosaic_grant_id (1.3.6.1.4.1.99999.1)'
+          : oidResult.error === 'MISSING_SUBJECT_USER_ID'
+            ? 'Client certificate is missing required OID: mosaic_subject_user_id (1.3.6.1.4.1.99999.2)'
+            : `Client certificate OID extraction failed: ${oidResult.detail ?? 'unknown error'}`;
+      this.logger.warn(`OID extraction failure [${oidResult.error}]: ${message}`);
+      return sendFederationError(reply, new FederationUnauthorizedError(message));
+    }
+
+    const { grantId, subjectUserId } = oidResult.value;
+
+    // ── Step 4: Load grant from DB ───────────────────────────────────────────
+    let grant: Awaited<ReturnType<GrantsService['getGrantWithPeer']>>;
+    try {
+      grant = await this.grantsService.getGrantWithPeer(grantId);
+    } catch {
+      // getGrantWithPeer throws NotFoundException when not found
+      this.logger.warn(`Grant not found: ${grantId}`);
+      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
+    }
+
+    // ── Step 5: Assert grant is active ──────────────────────────────────────
+    if (grant.status !== 'active') {
+      this.logger.warn(`Grant ${grantId} is not active — status=${grant.status}`);
+      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
+    }
+
+    // ── Step 5b: Validate cert-extracted subjectUserId against DB (CRIT-1) ──
+    // The cert claim is untrusted input; the DB row is authoritative.
+    if (subjectUserId !== grant.subjectUserId) {
+      this.logger.warn(`subjectUserId mismatch for grant ${grantId}`);
+      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
+    }
+
+    // ── Step 6: Defense-in-depth — cert serial must match registered peer ───
+    // The serial number from Node.js TLS is upper-case hex without colons.
+    // The @peculiar/x509 serialNumber is decimal. We compare using the native
+    // Node.js crypto cert serial which is uppercase hex, matching DB storage.
+    // Both are derived from the peerCert.serialNumber Node.js provides.
+    const inboundSerial: string = peerCert.serialNumber ?? '';
+
+    if (!grant.peer.certSerial) {
+      // Peer row exists but has no stored serial — something is wrong with enrollment
+      this.logger.error(`Peer ${grant.peerId} has no stored certSerial — enrollment incomplete`);
+      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
+    }
+
+    // Normalize both to uppercase for comparison (Node.js serialNumber is
+    // already uppercase hex; DB value was stored from extractSerial() which
+    // returns crypto.X509Certificate.serialNumber — also uppercase hex).
+    if (inboundSerial.toUpperCase() !== grant.peer.certSerial.toUpperCase()) {
+      this.logger.warn(
+        `Cert serial mismatch for grant ${grantId}: ` +
+          `inbound=${inboundSerial} registered=${grant.peer.certSerial}`,
+      );
+      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
+    }
+
+    // ── Step 7: Attach FederationContext to request ──────────────────────────
+    // Use grant.subjectUserId from DB (authoritative) — not the cert-extracted value.
+    const federationContext: FederationContext = {
+      grantId,
+      subjectUserId: grant.subjectUserId,
+      peerId: grant.peerId,
+      scope: grant.scope as Record<string, unknown>,
+    };
+
+    request.federationContext = federationContext;
+
+    this.logger.debug(
+      `Federation auth OK — grantId=${grantId} peerId=${grant.peerId} subjectUserId=${grant.subjectUserId}`,
+    );
+
+    return true;
+  }
+}

apps/gateway/src/federation/server/federation-context.ts

@@ -0,0 +1,39 @@
+/**
+ * FederationContext — attached to inbound federation requests after successful
+ * mTLS + grant validation by FederationAuthGuard.
+ *
+ * Downstream verb controllers access this via `request.federationContext`.
+ */
+
+/**
+ * Augment FastifyRequest so TypeScript knows about the federation context
+ * property that FederationAuthGuard attaches on success.
+ */
+declare module 'fastify' {
+  interface FastifyRequest {
+    federationContext?: FederationContext;
+  }
+}
+
+/**
+ * Typed context object attached to the request by FederationAuthGuard.
+ * Carries all data extracted from the mTLS cert + grant DB row needed
+ * by downstream federation verb handlers.
+ */
+export interface FederationContext {
+  /** The federation grant ID extracted from OID 1.3.6.1.4.1.99999.1 */
+  grantId: string;
+
+  /** The local subject user whose data is accessible under this grant */
+  subjectUserId: string;
+
+  /** The peer gateway ID (from the grant's peerId FK) */
+  peerId: string;
+
+  /**
+   * Grant scope — determines which resources the peer may query.
+   * Typed as Record<string, unknown> because the full scope schema lives in
+   * scope-schema.ts; downstream handlers should narrow via parseFederationScope.
+   */
+  scope: Record<string, unknown>;
+}

apps/gateway/src/federation/server/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Federation server-side barrel — inbound request handling.
+ *
+ * Exports the mTLS auth guard and the FederationContext interface
+ * for use by verb controllers (M3-05/06/07).
+ *
+ * Usage:
+ *   import { FederationAuthGuard } from './server/index.js';
+ *   @UseGuards(FederationAuthGuard)
+ */
+
+export { FederationAuthGuard } from './federation-auth.guard.js';
+export type { FederationContext } from './federation-context.js';

docker/appservice.Dockerfile

@@ -0,0 +1,28 @@
+FROM node:22-alpine AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+
+FROM base AS builder
+WORKDIR /app
+# Copy workspace manifests first for layer-cached install
+COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
+COPY apps/appservice/package.json ./apps/appservice/
+COPY packages/ ./packages/
+COPY plugins/ ./plugins/
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm turbo run build --filter @mosaicstack/mosaic-as...
+RUN pnpm --filter @mosaicstack/mosaic-as --prod deploy --legacy /deploy
+
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /deploy/node_modules ./node_modules
+COPY --from=builder /deploy/package.json ./package.json
+COPY --from=builder /app/apps/appservice/dist ./dist
+USER node
+EXPOSE 8008
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=5 \
+  CMD ["node", "-e", "require('http').get('http://127.0.0.1:8008/health',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
+CMD ["node", "dist/main.js"]

docs/TASKS.md

@@ -22,14 +22,15 @@
 
 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`)                                           |
-| MVP-T04 | not-started | Sync `.mosaic/orchestrator/mission.json` MVP slot with this manifest (milestone enumeration, etc.)       | Coord state file; consider whether to repopulate via `mosaic coord` or accept hand-edit |
-| MVP-T05 | in-progress | Kick off W1 / FED-M1 — federated tier infrastructure                                                     | Session 16 (2026-04-19): FED-M1-01 in-progress on `feat/federation-m1-tier-config`      |
-| MVP-T06 | not-started | Declare additional workstreams (web dashboard, TUI/CLI parity, remote control, etc.) as scope solidifies | Track each new workstream by adding a row to the Workstream Rollup                      |
+| 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`)                                                                                 |
+| MVP-T04    | not-started | Sync `.mosaic/orchestrator/mission.json` MVP slot with this manifest (milestone enumeration, etc.)       | Coord state file; consider whether to repopulate via `mosaic coord` or accept hand-edit                                       |
+| MVP-T05    | in-progress | Kick off W1 / FED-M1 — federated tier infrastructure                                                     | Session 16 (2026-04-19): FED-M1-01 in-progress on `feat/federation-m1-tier-config`                                            |
+| MVP-T06    | not-started | Declare additional workstreams (web dashboard, TUI/CLI parity, remote control, etc.) as scope solidifies | Track each new workstream by adding a row to the Workstream Rollup                                                            |
+| T-A292E96F | in-progress | Fix Mosaic Gitea PR metadata/login wrapper regression for U-Connect merge preflight                      | Kanban `t_a292e96f`; branch `fix/t-a292e96f-gitea-pr-metadata`; scratchpad `docs/scratchpads/t-a292e96f-gitea-pr-metadata.md` |
 
 ## Pointer to Active Workstream
 
@@ -38,3 +39,9 @@ Active workstream is **W1 — Federation v1**. Workers should:
 1. Read [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) for workstream scope
 2. Read [docs/federation/TASKS.md](./federation/TASKS.md) for the next pending task
 3. Follow per-task agent + tier guidance from the workstream manifest
+
+## Thin-core prompt diet (#528) — feat/contract-thin-core
+
+- Status: PR open, awaiting maintainer merge ratification (fleet-governing change).
+- Cut always-injected contract AGENTS+TOOLS+RUNTIME 8,827→4,122 tok (−53%); all 12 hard gates intact.
+- Validation: deterministic gate-checklist PASS; headless A/B thin 7/9 vs monolith 5/9. Detail: scratchpads/contract-thin-core.md.

docs/mission-control/BOARD.md

@@ -0,0 +1,101 @@
+# Mission Control Plane — Feature Board
+
+> Discussion board for the combined PRD / mission / Kanban workflow.
+> Use this to decide scope before implementation.
+
+## Board Legend
+
+- **Must-have** — required for the first usable version
+- **Should-have** — strongly preferred, but can ship after the core path
+- **Could-have** — valuable later if time permits
+- **Won't-have** — explicitly deferred
+
+---
+
+## Feature Board
+
+| Feature Card                   | Need                                                          | Priority    | Decision / Notes                                                            |
+| ------------------------------ | ------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- |
+| Canonical mission manifest     | One durable root object for goal, PRD, board, session         | Must-have   | Mission manifest becomes the anchor for all downstream state                |
+| PRD generator integration      | PRD should be generated from a feature idea and saved in docs | Must-have   | Use Mosaic PRDy format and keep the file human-reviewable                   |
+| Board atomization              | Break PRD into assignable tasks with dependencies             | Must-have   | Each user story should map to one or more tasks                             |
+| Short-cycle detector           | Detect compaction churn and repeated tool loops               | Must-have   | Coordinator should track churn score per session                            |
+| Handoff packet                 | Preserve actionable context across rotations                  | Must-have   | Use a compact structured summary, not a raw transcript                      |
+| Auto-resume workers            | Let new sessions read mission + board on start                | Should-have | Makes overnight autonomy realistic                                          |
+| Mission status view            | Show current phase, blockers, and active session              | Should-have | Expose through CLI first, dashboard later                                   |
+| Worktree root convention       | Keep worktrees off `/tmp` and on the larger persistent drive  | Should-have | Prefer `/src/<repo>-worktrees` for repo worktrees and long-lived agent work |
+| Review gate                    | Prevent autonomous work from shipping unreviewed              | Should-have | Use reviewer tasks before mission close                                     |
+| Rotation policy config         | Configure thresholds per mission/profile                      | Could-have  | Keep v1 simple, add tuning later                                            |
+| Goal decomposition suggestions | Suggest sub-goals from the PRD                                | Could-have  | Good for planning, not necessary for core path                              |
+| Cross-channel continuity       | Continue a mission across CLI/gateway/remote channels         | Could-have  | Important later, not required for MVP                                       |
+| Automatic board sync           | Mirror git docs into DB and back                              | Could-have  | Nice-to-have after the file-first flow stabilizes                           |
+| Fully autonomous closeout      | Let mission finish without human intervention                 | Won't-have  | Keep an operator-visible review step                                        |
+
+---
+
+## Needs Discussion
+
+### 1) Canonical source of truth
+
+**Question:** Should the PRD, mission manifest, and board all live in git, or should one be the database source of truth?
+
+**Proposed answer:** Keep the human-readable artifacts in git and sync the mission runtime state to the database.
+
+### 2) Scope of automation
+
+**Question:** Should the first version auto-create the board from the PRD, or require a human/orchestrator to approve the split?
+
+**Proposed answer:** Auto-create a draft board, then let the orchestrator approve or adjust it.
+
+### 3) Rotation triggers
+
+**Question:** What should trigger a forced session rotation?
+
+**Candidate signals:**
+
+- repeated compaction
+- repeated prompts for permission
+- identical tool loops
+- no new file/task state after several turns
+- task blocked on a missing prerequisite
+
+**Proposed answer:** Use a weighted churn score with a small hard cap on repeated compactions.
+
+### 4) Handoff format
+
+**Question:** What should the next session receive?
+
+**Proposed answer:**
+
+- Mission ID
+- PRD path
+- Active board task
+- Completed work
+- Blockers
+- Next 3 actions
+- Non-negotiable constraints
+
+### 5) Operator control
+
+**Question:** Should the operator be able to force a rotation or pause the mission?
+
+**Proposed answer:** Yes. Human override should win.
+
+---
+
+## Draft Decisions
+
+1. File-first artifacts, DB-backed runtime state.
+2. PRD-first planning, board-second execution.
+3. Auto-rotation on churn, but human override remains available.
+4. Structured handoff packets required on every rotation.
+5. Mission close requires a reviewer task.
+
+---
+
+## Open Questions
+
+- What exact data fields belong in the mission manifest?
+- Should rotation thresholds vary by agent profile?
+- What is the minimum viable status surface for v1?
+- Should the board support milestones in addition to tasks?

docs/mission-control/MISSION-MANIFEST.md

@@ -0,0 +1,95 @@
+# Mission Manifest — Mosaic Mission Control Plane
+
+> Persistent document tracking scope, status, and handoff history for the combined PRD / mission / Kanban workflow.
+
+## Mission
+
+**ID:** mission-control-plane-20260506
+
+**Statement:** Combine Mosaic PRDy, coord, and Kanban into one durable workflow so an agent can move from feature idea to PRD to mission to task board and keep working across session rotation, compaction, and restarts with minimal context loss.
+
+**Phase:** planning — MC-01 complete, MC-02 next
+
+**Current Milestone:** MC-02
+
+**Progress:** 1 / 6 milestones
+
+**Status:** active
+
+**Last Updated:** 2026-05-06
+
+**Parent Mission:** None — new mission
+
+---
+
+## Context
+
+This mission exists because overnight autonomy breaks when the working session short-cycles. The system needs durable artifacts and a mechanical coordinator that can:
+
+1. keep a canonical PRD,
+2. atomize the PRD into board tasks,
+3. track mission state separately from the chat session,
+4. detect churn or compaction pressure,
+5. rotate to a fresh session, and
+6. re-enter from a structured handoff.
+
+Operational convention: repo worktrees and long-lived working directories should use `/src/<repo>-worktrees` instead of `/tmp`.
+
+Design references:
+
+- `docs/mission-control/PRD.md` — product requirements
+- `docs/mission-control/BOARD.md` — feature discussion board
+- `docs/mission-control/TASKS.md` — atomized execution plan
+
+---
+
+## Success Criteria
+
+- [ ] AC-1: A feature idea can be converted into a PRD, mission, and task board.
+- [ ] AC-2: The coordinator can load a mission and its board from durable storage.
+- [ ] AC-3: The coordinator can detect short-cycling and rotate sessions automatically.
+- [ ] AC-4: A rotated session can resume from a handoff packet without manual re-prompting.
+- [ ] AC-5: The board remains traceable back to the PRD user stories.
+- [ ] AC-6: Operators can inspect mission state, task state, and latest handoff from one place.
+- [ ] AC-7: The system can run overnight without losing the mission goal.
+
+---
+
+## Milestones
+
+| #   | ID    | Name                                     | Status      | Branch                  | Started    | Completed |
+| --- | ----- | ---------------------------------------- | ----------- | ----------------------- | ---------- | --------- |
+| 1   | MC-01 | PRD + mission schema foundation          | in-progress | docs/mission-control-\* | 2026-05-06 | —         |
+| 2   | MC-02 | Mission runtime model                    | not-started | —                       | —          | —         |
+| 3   | MC-03 | Board atomization and task linkage       | not-started | —                       | —          | —         |
+| 4   | MC-04 | Short-cycle detector and rotation engine | not-started | —                       | —          | —         |
+| 5   | MC-05 | Handoff generation and re-entry          | not-started | —                       | —          | —         |
+| 6   | MC-06 | Operator surface and E2E validation      | not-started | —                       | —          | —         |
+
+---
+
+## Budget
+
+| Milestone | Est. tokens | Parallelizable?    |
+| --------- | ----------- | ------------------ |
+| MC-01     | 16K         | No                 |
+| MC-02     | 20K         | No                 |
+| MC-03     | 24K         | Mostly after MC-01 |
+| MC-04     | 20K         | After MC-02        |
+| MC-05     | 18K         | After MC-04        |
+| MC-06     | 26K         | After MC-04/05     |
+| **Total** | **~124K**   |                    |
+
+---
+
+## Session History
+
+| Session | Date       | Runtime | Outcome                                                                  |
+| ------- | ---------- | ------- | ------------------------------------------------------------------------ |
+| S1      | 2026-05-06 | hermes  | PRD, board, task plan, mission manifest, and worktree convention drafted |
+
+---
+
+## Next Step
+
+Kick off MC-02: implement the durable mission runtime model and wire the mission state into the coordinator.

docs/mission-control/PRD.md

@@ -0,0 +1,205 @@
+# PRD: Mosaic Mission Control Plane
+
+## Metadata
+
+- **Owner:** Jason Woltje
+- **Date:** 2026-05-06
+- **Status:** draft
+- **Framework:** Mosaic PRDy + coord + Kanban
+- **Target Repo:** `git.mosaicstack.dev/mosaic/mosaic-stack`
+- **Primary Modules:** `packages/prdy`, `packages/coord`, `packages/queue`, `apps/gateway`, `packages/brain`, `packages/cli`
+
+---
+
+## Problem Statement
+
+Mosaic already has the ingredients for durable agent work: PRD generation (`prdy`), mission coordination (`coord`), and task execution boards (`Kanban` / `TASKS.md`). Today those systems can still drift apart:
+
+- A PRD can exist without a mission record.
+- A mission can exist without a machine-readable execution board.
+- Agents can short-cycle or compact repeatedly without a durable handoff.
+- The next session may know the goal, but not the exact next step.
+
+The result is brittle overnight autonomy: work continues only as long as a single session remains healthy.
+
+This feature unifies those layers into one durable workflow so a mission can survive session rotation, compaction, and restarts with minimal state loss.
+
+---
+
+## Goals
+
+1. Create one canonical pipeline from idea → PRD → mission → board → execution.
+2. Let `prdy` generate a PRD that is immediately usable as a mission input.
+3. Let `coord` own mission state, handoffs, and session rotation.
+4. Let the board hold atomized tasks with dependencies and assignees.
+5. Let agents read the mission and board to learn the next action without extra prompting.
+6. Detect short-cycling and rotate sessions before quality degrades.
+7. Preserve useful context across handoffs with a structured summary packet.
+8. Give operators a single place to see mission status, task state, and the current session.
+
+---
+
+## Non-Goals
+
+1. Replacing the Mosaic agent runtime or gateway architecture.
+2. Rewriting `prdy` or `coord` from scratch.
+3. Turning the board into a general project-management system.
+4. Building a full Gantt/charting product.
+5. Removing human review or approval gates.
+6. Allowing agents to create arbitrary mission state without schema.
+
+---
+
+## User Stories
+
+### US-001: Create a mission from a feature idea
+
+**Description:** As an orchestrator, I want to turn a feature idea into a PRD and mission so that agents can work from a durable spec instead of a chat transcript.
+
+**Acceptance Criteria:**
+
+- [ ] `prdy` can emit a PRD with goals, non-goals, and requirements.
+- [ ] The PRD is linked to a mission ID.
+- [ ] The mission manifest references the PRD path.
+- [ ] The mission is readable by downstream agent sessions.
+
+### US-002: Atomize work into a board
+
+**Description:** As an orchestrator, I want to split a PRD into board tasks so that work can be assigned to specialists.
+
+**Acceptance Criteria:**
+
+- [ ] Each user story can become one or more tasks.
+- [ ] Tasks have assignees, dependencies, and estimates.
+- [ ] Tasks are machine-readable and durable.
+- [ ] The board can be regenerated from the PRD without ambiguity.
+
+### US-003: Rotate sessions without losing the mission
+
+**Description:** As a coordinator, I want to restart or rotate a session when it short-cycles so that the mission continues with minimal loss.
+
+**Acceptance Criteria:**
+
+- [ ] The coordinator detects compaction pressure or repeated loops.
+- [ ] The coordinator writes a handoff summary before rotation.
+- [ ] A new session can resume from the handoff packet.
+- [ ] The mission state remains intact across the rotation.
+
+### US-004: Let workers read the next step automatically
+
+**Description:** As a worker agent, I want to read the mission and board at startup so I can do the next useful thing without waiting for a human prompt.
+
+**Acceptance Criteria:**
+
+- [ ] Startup loads the active mission manifest.
+- [ ] Startup loads the current board/task row.
+- [ ] Startup exposes the next action clearly in the prompt.
+- [ ] The agent can continue after compaction using the same mission context.
+
+### US-005: Observe mission health from one place
+
+**Description:** As an operator, I want a single view of mission health so that I can see progress, blocked tasks, and session churn.
+
+**Acceptance Criteria:**
+
+- [ ] Mission state shows current phase and progress.
+- [ ] Board state shows task status by assignee.
+- [ ] Short-cycle/rotation events are visible.
+- [ ] Handoffs are inspectable.
+
+---
+
+## Functional Requirements
+
+FR-1. The system must represent a mission as a durable object with an ID, goal, current phase, PRD path, board path, and active session ID.
+
+FR-2. The system must represent a PRD as a markdown document with goals, user stories, functional requirements, non-goals, technical considerations, and success metrics.
+
+FR-3. The system must represent execution work as a board of atomized tasks with status, assignee, dependency, and estimate fields.
+
+FR-4. The coordinator must be able to derive a task board from a PRD.
+
+FR-5. The coordinator must be able to write a handoff packet that includes goal, current state, completed work, blocked work, next steps, and constraints.
+
+FR-6. The coordinator must detect short-cycling signals such as repeated compactions, repeated tool loops, repeated approval prompts, or no progress across several turns.
+
+FR-7. The coordinator must rotate the session when the short-cycle threshold is exceeded.
+
+FR-8. The coordinator must preserve mission continuity across session rotation.
+
+FR-9. The worker session must read the mission state and board state at startup.
+
+FR-10. The worker session must be able to resume from the last handoff summary without the operator rewriting the goal manually.
+
+FR-11. The operator must be able to inspect the mission state, PRD, board, and latest handoff from one place.
+
+FR-12. The mission system must keep a traceable link between PRD requirements and board tasks.
+
+FR-13. The system must not allow a task to become active without a valid mission context.
+
+FR-14. The system must keep durable history for rotation and handoff events.
+
+---
+
+## Board Discussion: Features and Needs
+
+This is the feature discussion board that should drive the mission design.
+
+| Card                     | Need                                         | Why it matters                               | Proposed decision                                            |
+| ------------------------ | -------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
+| Canonical mission record | One source of truth for goal/state           | Prevents drift between chat, docs, and queue | Make mission manifest the durable root object                |
+| PRD → board derivation   | Break feature ideas into executable work     | Lets the plan be assigned and tracked        | Keep PRD as the spec, generate board tasks from user stories |
+| Session watchdog         | Detect churn/short-cycling                   | Keeps overnight runs productive              | Add short-cycle scoring and forced rotation                  |
+| Structured handoff       | Preserve context across session changes      | Minimizes restart loss                       | Use a compact JSON/MD handoff packet                         |
+| Worker auto-read         | Let agents resume without human re-prompting | Reduces operator overhead                    | Load mission + board on session start                        |
+| Status surface           | Show progress and blockers clearly           | Operators need confidence                    | Expose mission state via CLI and dashboard                   |
+| Review gate              | Keep quality high on autonomous work         | Prevents silent regressions                  | Require review tasks before close                            |
+| Recoverability           | Resume after failure or restart              | Mission should outlive a process             | Persist session and handoff history                          |
+
+---
+
+## Design Considerations
+
+1. The PRD should stay human-readable markdown, because the board and mission references need to be reviewable in git.
+2. The board should be machine-readable enough for automation but still readable by humans.
+3. The mission manifest should point to the PRD and board, not duplicate them.
+4. Handoff packets should be compact and structured so they can be injected into a new session with minimal token cost.
+5. The coordinator should prefer rotation over forced context growth once the session is near the compaction threshold.
+6. Existing Mosaic commands should be extended, not replaced, wherever possible.
+7. The same mission should be resumable across CLI, gateway, and remote channels.
+
+---
+
+## Technical Considerations
+
+- Likely storage split:
+  - PRD/board/manifest in git-backed docs
+  - mission/session state in the Mosaic data layer
+  - runtime health in queue/session state
+- Worktrees and long-lived agent working directories should live under `/src/<repo>-worktrees` rather than `/tmp` so they sit on the larger persistent drive and survive longer-running missions.
+- The coordinator needs a stable session identity, even if the active session changes.
+- Task dependencies must be enforced so workers do not start early.
+- The handoff packet should include the top 3 immediate actions and the strongest constraints.
+- Rotation triggers should be configurable per profile or per mission.
+- The initial version can be file-first, with dashboard sync added later.
+
+---
+
+## Success Metrics
+
+- A mission can rotate sessions without losing the active goal.
+- A new session can resume from the latest handoff in under one turn.
+- Board tasks remain aligned to PRD user stories.
+- Short-cycling sessions are replaced before repeated compaction harms quality.
+- Operators can find mission state without spelunking across multiple chat logs.
+
+---
+
+## Open Questions
+
+1. What should the canonical mission ID format be?
+2. Should the board live only in git, or also in the database?
+3. Should rotation be automatic by default, or opt-in per mission?
+4. What should the short-cycle threshold be initially?
+5. Should handoffs be pure text, structured JSON, or both?
+6. Which CLI command should be the primary mission entrypoint: `mosaic mission`, `mosaic coord`, or `mosaic prdy`?

docs/mission-control/TASKS.md

@@ -0,0 +1,113 @@
+# Tasks — Mosaic Mission Control Plane
+
+> Single-writer: orchestrator only. Workers read but never modify.
+>
+> **Mission:** mission-control-plane-20260506
+> **Schema:** `| id | status | description | issue | agent | branch | depends_on | estimate | notes |`
+> **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa`
+> **Agent values:** `codex` | `glm-5.1` | `haiku` | `sonnet` | `opus` | `—` (auto)
+>
+> Scope: this file decomposes the combined PRD / mission / board workflow into atomized tasks.
+
+---
+
+## Milestone 1 — PRD + mission schema foundation
+
+Goal: create the durable doc structure and the minimal mission metadata needed to keep PRD, board, and mission aligned.
+
+| id       | status      | description                                                                                              | issue | agent  | branch                        | depends_on         | estimate | notes                                       |
+| -------- | ----------- | -------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------------- | ------------------ | -------- | ------------------------------------------- |
+| MC-01-01 | not-started | Write `docs/mission-control/PRD.md` with goals, non-goals, functional requirements, and success metrics. | —     | sonnet | docs/mission-control-prd      | —                  | 5K       | Human-readable PRD becomes the spec anchor. |
+| MC-01-02 | not-started | Write `docs/mission-control/BOARD.md` as a decision board for scope, priority, and open questions.       | —     | haiku  | docs/mission-control-board    | MC-01-01           | 3K       | Keeps discussion separate from the spec.    |
+| MC-01-03 | not-started | Write `docs/mission-control/MISSION-MANIFEST.md` linking PRD, board, tasks, and mission identity.        | —     | sonnet | docs/mission-control-manifest | MC-01-01, MC-01-02 | 4K       | Durable mission root object.                |
+| MC-01-04 | not-started | Write `docs/mission-control/TASKS.md` with the atomized execution plan and dependency graph.             | —     | sonnet | docs/mission-control-tasks    | MC-01-03           | 4K       | Board-backed execution plan.                |
+
+**Milestone 1 estimate:** ~16K tokens
+
+---
+
+## Milestone 2 — Mission runtime model
+
+Goal: make missions first-class runtime objects that can survive session restarts and compaction.
+
+| id       | status      | description                                                                                                                               | issue                                                                                                                                  | agent | branch                                 | depends_on                         | estimate | notes                                      |
+| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------- | ---------------------------------- | -------- | ------------------------------------------ | ---------------------------------------------------- |
+| MC-02-01 | not-started | Define mission schema in the data layer: mission ID, goal, phase, PRD path, board path, active session ID, last handoff, and churn score. | —                                                                                                                                      | codex | feat/mission-control-schema            | MC-01-03                           | 6K       | This is the durable root state.            |
+| MC-02-02 | not-started | Add mission read/write services to `packages/coord` so the coordinator can load and persist mission state.                                | —                                                                                                                                      | codex | feat/mission-control-coord-store       | MC-02-01                           | 6K       | Keep storage simple and explicit.          |
+| MC-02-03 | not-started | Add mission status reporting to `mosaic mission` and `mosaic coord status`.                                                               | —                                                                                                                                      | codex | feat/mission-control-status-cli        | MC-02-02                           | 4K       | Operators need one obvious status command. |
+| MC-02-04 | not-started | Add tests for mission persistence and recovery after restart.                                                                             | —                                                                                                                                      | haiku | feat/mission-control-persistence-tests | MC-02-02                           | 4K       | Verify mission survives process churn.     |
+|          | MC-02-05    | done                                                                                                                                      | Add a worktree-root convention to the mission runtime notes and startup guidance so agents prefer `/src/<repo>-worktrees` over `/tmp`. | —     | haiku                                  | docs/mission-control-worktree-root | MC-01-03 | 3K                                         | Keep long-lived work on the larger persistent drive. |
+
+**Milestone 2 estimate:** ~20K tokens
+
+---
+
+## Milestone 3 — Board atomization and task linkage
+
+Goal: derive assignable tasks from the PRD and keep them linked to mission state.
+
+| id       | status      | description                                                                                 | issue | agent  | branch                           | depends_on         | estimate | notes                                       |
+| -------- | ----------- | ------------------------------------------------------------------------------------------- | ----- | ------ | -------------------------------- | ------------------ | -------- | ------------------------------------------- |
+| MC-03-01 | not-started | Add a PRD-to-task decomposition rule set: every user story maps to one or more board tasks. | —     | sonnet | feat/mission-control-decompose   | MC-01-01           | 5K       | Start simple and deterministic.             |
+| MC-03-02 | not-started | Implement board generation from the PRD in a machine-readable format.                       | —     | codex  | feat/mission-control-board-gen   | MC-03-01           | 6K       | Output should be usable by the coordinator. |
+| MC-03-03 | not-started | Add dependency validation so tasks cannot start before parent tasks complete.               | —     | codex  | feat/mission-control-deps        | MC-03-02           | 5K       | Enforces ordering.                          |
+| MC-03-04 | not-started | Add review-task support so a mission cannot close without a reviewer step.                  | —     | sonnet | feat/mission-control-review-gate | MC-03-03           | 4K       | Preserves quality.                          |
+| MC-03-05 | not-started | Add tests proving the board stays traceable back to the PRD user stories.                   | —     | haiku  | feat/mission-control-trace-tests | MC-03-02, MC-03-03 | 4K       | Traceability is the point.                  |
+
+**Milestone 3 estimate:** ~24K tokens
+
+---
+
+## Milestone 4 — Short-cycle detector and rotation engine
+
+Goal: detect when a session is stuck and rotate to a fresh session before quality falls off.
+
+| id       | status      | description                                                                                                                         | issue | agent  | branch                              | depends_on | estimate | notes                                          |
+| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------------------- | ---------- | -------- | ---------------------------------------------- |
+| MC-04-01 | not-started | Define churn signals: repeated compaction, identical tool loops, repeated permission prompts, and no progress across several turns. | —     | sonnet | feat/mission-control-churn-signals  | MC-02-01   | 4K       | Keep the rules explicit.                       |
+| MC-04-02 | not-started | Implement churn scoring in the coordinator with configurable thresholds.                                                            | —     | codex  | feat/mission-control-churn-score    | MC-04-01   | 6K       | Weighted score makes tuning easier.            |
+| MC-04-03 | not-started | Implement automatic session rotation when churn crosses the threshold.                                                              | —     | codex  | feat/mission-control-rotate-session | MC-04-02   | 6K       | The session is disposable; the mission is not. |
+| MC-04-04 | not-started | Add tests for rotation triggers and for avoiding premature rotation.                                                                | —     | haiku  | feat/mission-control-rotation-tests | MC-04-03   | 4K       | Prevent flapping.                              |
+
+**Milestone 4 estimate:** ~20K tokens
+
+---
+
+## Milestone 5 — Handoff generation and re-entry
+
+Goal: preserve the best context from the old session and inject it into the new session cleanly.
+
+| id       | status      | description                                                                                                          | issue | agent  | branch                              | depends_on         | estimate | notes                                    |
+| -------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------------------- | ------------------ | -------- | ---------------------------------------- |
+| MC-05-01 | not-started | Define the handoff packet schema: mission ID, session ID, completed work, blockers, next 3 actions, and constraints. | —     | sonnet | feat/mission-control-handoff-schema | MC-02-01           | 4K       | Keep it compact and structured.          |
+| MC-05-02 | not-started | Implement handoff packet writing during rotation.                                                                    | —     | codex  | feat/mission-control-handoff-write  | MC-05-01, MC-04-03 | 5K       | Persist before the old session exits.    |
+| MC-05-03 | not-started | Implement handoff packet loading at session startup.                                                                 | —     | codex  | feat/mission-control-handoff-load   | MC-05-01, MC-04-03 | 5K       | New session should know the next action. |
+| MC-05-04 | not-started | Add tests proving a rotated session can continue the mission without manual re-prompting.                            | —     | haiku  | feat/mission-control-handoff-tests  | MC-05-02, MC-05-03 | 4K       | Resume quality is the key metric.        |
+
+**Milestone 5 estimate:** ~18K tokens
+
+---
+
+## Milestone 6 — Operator surface and E2E validation
+
+Goal: expose the whole workflow through commands and verify it end-to-end.
+
+| id       | status      | description                                                                                               | issue | agent  | branch                           | depends_on         | estimate | notes                                        |
+| -------- | ----------- | --------------------------------------------------------------------------------------------------------- | ----- | ------ | -------------------------------- | ------------------ | -------- | -------------------------------------------- |
+| MC-06-01 | not-started | Add a CLI command to inspect the active mission, PRD path, board path, task statuses, and latest handoff. | —     | codex  | feat/mission-control-inspect-cli | MC-02-03, MC-05-03 | 5K       | One place to inspect the whole stack.        |
+| MC-06-02 | not-started | Add a compact dashboard or TUI summary view for mission health.                                           | —     | codex  | feat/mission-control-summary-ui  | MC-06-01           | 6K       | Nice to have, but not before the core works. |
+| MC-06-03 | not-started | Build an E2E harness that simulates compaction / rotation and verifies the mission can continue.          | —     | sonnet | feat/mission-control-e2e-harness | MC-04-03, MC-05-03 | 8K       | This is the proof that the design works.     |
+| MC-06-04 | not-started | Add final docs for operators explaining how PRD, mission, and board fit together.                         | —     | haiku  | feat/mission-control-ops-docs    | MC-06-03           | 4K       | Make it usable by humans.                    |
+| MC-06-05 | not-started | Consolidate review findings and close the mission with a release note.                                    | —     | sonnet | chore/mission-control-close      | MC-06-04           | 3K       | Only after the E2E passes.                   |
+
+**Milestone 6 estimate:** ~26K tokens
+
+---
+
+## Execution Notes
+
+- `sonnet` is best for planning, decomposition, and the review-gate tasks.
+- `codex` is best for schema, coordinator, and CLI implementation.
+- `haiku` is best for validation, traceability checks, and docs.
+- The first implementation pass should stay file-first and keep the runtime state thin.
+- The mission should not close until the PRD, board, mission manifest, and E2E harness all agree.

docs/plans/2026-05-06-hermes-mosaic-alignment.md

@@ -0,0 +1,238 @@
+# Hermes-Mosaic Alignment Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** Package Mosaic's mechanical coordination primitives as a native Hermes toolset so any Hermes profile gets mission management, task decomposition, handoff, and session continuity without depending on the Mosaic gateway or OpenClaw runtime.
+
+**Architecture:** Extract the coordination logic from Mosaic's `packages/coord` (TypeScript, file-first) into a Hermes Python toolset that wraps the same file conventions. The Mosaic Stack repo remains the canonical upstream for the file formats (TASKS.md schema, mission.json schema, handoff packet schema). Hermes implements native Python tools that read/write those same files, plus tool-calls for churn detection and handoff generation that have no Mosaic equivalent today.
+
+**Tech Stack:** Python (Hermes toolset), SQLite (Hermes Kanban), JSON + Markdown (Mosaic file conventions)
+
+---
+
+## Alignment Map
+
+### What Mosaic has that Hermes needs
+
+| Mosaic Component                 | What it does                                              | Natural Hermes home                          | Why                                                                                                                                                                              |
+| -------------------------------- | --------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `packages/coord` (mission.ts)    | Mission CRUD, session tracking, milestone state           | **Hermes toolset: `mission`**                | Mission state is session-scoped, not gateway-scoped. Hermes sessions already have identity, process tracking, and context windows.                                               |
+| `packages/coord` (tasks-file.ts) | Parse/write TASKS.md tables                               | **Hermes toolset: `mission`** (same)         | Hermes already reads/writes files. The TASKS.md parser is ~300 lines of pure string manipulation — trivial Python port.                                                          |
+| `packages/coord` (runner.ts)     | Spawn claude/codex workers with continuation prompts      | **Already covered by `delegate_task`**       | Hermes delegate_task already does isolated subagent spawning with restricted toolsets. The runner's "find next task and build continuation prompt" logic moves into a tool-call. |
+| `packages/coord` (status.ts)     | Mission health, task progress, next task                  | **Hermes toolset: `mission`** (same)         | Status readout fits naturally as a tool-call. No gateway needed.                                                                                                                 |
+| `packages/prdy`                  | PRD generation wizard                                     | **Hermes skill: `prdy`**                     | PRD generation is a prompt + template problem, not infrastructure. A Hermes skill with templates is the right fit.                                                               |
+| `plugins/mosaic-framework`       | before_agent_start + subagent_spawning hooks              | **Hermes system prompt injection**           | Hermes already injects system context via skills and config. The framework preamble and worktree rules become standard Hermes skills loaded by the orchestrator profile.         |
+| `plugins/macp`                   | OpenClaw ACP bridge (spawn codex/claude)                  | **Already covered by `delegate_task` + ACP** | Hermes already has ACP support and delegate_task. The MACP bridge is redundant when running natively in Hermes.                                                                  |
+| Churn detection (planned)        | Detect compaction loops, repeated tool calls, no progress | **Hermes middleware**                        | This needs to live inside Hermes's turn loop where it can observe tool-call patterns. Mosaic can't see this from outside.                                                        |
+| Handoff packet (planned)         | Structured context summary for session rotation           | **Hermes toolset: `mission`**                | Handoff is a serialization of mission + session state. Hermes owns the session, so it should own the handoff.                                                                    |
+
+### What Hermes already has that replaces Mosaic infrastructure
+
+| Mosaic concept       | Hermes equivalent                     | Notes                                                                                                    |
+| -------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Gateway (NestJS)     | Hermes gateway                        | Hermes already has a gateway with WebSocket, Discord, Telegram, CLI. No need for a second one.           |
+| Pi SDK agent runtime | Hermes agent loop                     | Hermes IS the agent runtime. OpenClaw's Pi SDK is a different runtime that Mosaic targets.               |
+| MACP ACP bridge      | `delegate_task` + ACP tools           | Same capability, already native.                                                                         |
+| Session identity     | Hermes session IDs + process_registry | Hermes already tracks session identity, PIDs, and background processes.                                  |
+| Task execution board | Hermes Kanban                         | Fully functional SQLite-backed Kanban with dispatcher, triage, events, comments.                         |
+| Worker spawning      | Hermes dispatcher + cron              | Kanban dispatcher + cron already handle this.                                                            |
+| Context injection    | Hermes skills + system prompt         | Skills are loaded at session start and injected into context. Exactly what mosaic-framework plugin does. |
+| File checkpoints     | Hermes checkpoint_manager             | Already tracks file mutations with shadow git.                                                           |
+
+### What Mosaic keeps as its own entity
+
+| Component             | Why it stays in Mosaic                              |
+| --------------------- | --------------------------------------------------- |
+| `apps/gateway`        | NestJS API surface — Mosaic's web platform offering |
+| `apps/web`            | Next.js dashboard — Mosaic's UI offering            |
+| `packages/types`      | Shared TS contracts for Mosaic gateway plugins      |
+| `packages/db`         | Drizzle ORM + PG — Mosaic's data layer              |
+| `packages/auth`       | BetterAuth — Mosaic's auth system                   |
+| `packages/brain`      | PG-backed data layer for Mosaic web app             |
+| `packages/queue`      | Valkey task queue for Mosaic gateway                |
+| `plugins/discord`     | OpenClaw Discord plugin                             |
+| `plugins/telegram`    | OpenClaw Telegram plugin                            |
+| `packages/mosaic` CLI | The `mosaic` CLI — Mosaic's own command surface     |
+
+---
+
+## Architecture: `mission` Toolset for Hermes
+
+### New files under `/opt/hermes/tools/`
+
+```
+mission_tools.py      — Tool-call surface (mission_create, mission_status,
+                         mission_next_task, mission_update_task, mission_handoff,
+                         mission_resume)
+mission_state.py       — State management (read/write mission.json, parse TASKS.md,
+                         parse MISSION-MANIFEST.md)
+mission_churn.py       — Churn detection (tool-loop counter, compaction counter,
+                         progress scorer)
+mission_handoff.py     — Handoff packet generation and loading
+```
+
+### Tool-calls exposed to the agent
+
+| Tool                  | What it does                                                                      | When the agent calls it                     |
+| --------------------- | --------------------------------------------------------------------------------- | ------------------------------------------- |
+| `mission_create`      | Initialize mission.json + TASKS.md + MISSION-MANIFEST.md in a project dir         | When starting a new mission                 |
+| `mission_status`      | Read current mission state, milestone progress, next task, active session         | At session start, or when checking progress |
+| `mission_next_task`   | Find the next `not-started` task whose dependencies are met, return its full spec | When the agent needs work to do             |
+| `mission_update_task` | Update a task row status in TASKS.md                                              | When completing or blocking a task          |
+| `mission_handoff`     | Generate a handoff packet from current session context + mission state            | Before session rotation or at session end   |
+| `mission_resume`      | Load a handoff packet and inject it as context for the new session                | At session start after rotation             |
+
+### Toolset registration
+
+The `mission` toolset follows the same pattern as `kanban`:
+
+1. **Gating**: Tools are available when:
+   - The profile has `mission` in its toolsets config, OR
+   - A `HERMES_MISSION_DIR` env var is set (cron/dispatcher spawned workers)
+2. **File conventions**: The toolset reads/writes the same file formats as Mosaic `packages/coord`:
+   - `.mosaic/orchestrator/mission.json` — mission state
+   - `docs/TASKS.md` — task table
+   - `docs/MISSION-MANIFEST.md` — mission manifest
+   - `docs/scratchpads/<id>.md` — session scratchpad
+
+3. **Kanban bridge**: Optional bidirectional sync between mission TASKS.md rows and Kanban task cards, so the dashboard sees mission tasks.
+
+### Churn detection (middleware)
+
+Churn detection lives in Hermes's turn loop, NOT as a tool-call. It observes:
+
+- Repeated compaction events (context window pressure)
+- Identical tool-call sequences (loop detection)
+- No file state changes across N turns
+- Repeated permission denials
+
+When churn score exceeds threshold:
+
+1. `mission_handoff` is called automatically
+2. Session is rotated (fresh context window)
+3. `mission_resume` is called in the new session
+
+This is new infrastructure that only Hermes can provide (Mosaic runs outside the agent loop).
+
+---
+
+## Implementation Tasks
+
+### Phase 1: Core state management (Python port of coord)
+
+| Task                                               | Files                         | Estimate |
+| -------------------------------------------------- | ----------------------------- | -------- |
+| 1.1 Port mission.json read/write to Python         | `mission_state.py`            | 2h       |
+| 1.2 Port TASKS.md parser to Python                 | `mission_state.py`            | 2h       |
+| 1.3 Port MISSION-MANIFEST.md reader to Python      | `mission_state.py`            | 1h       |
+| 1.4 Implement `mission_create` tool-call           | `mission_tools.py`            | 1h       |
+| 1.5 Implement `mission_status` tool-call           | `mission_tools.py`            | 1h       |
+| 1.6 Implement `mission_next_task` tool-call        | `mission_tools.py`            | 1h       |
+| 1.7 Implement `mission_update_task` tool-call      | `mission_tools.py`            | 1h       |
+| 1.8 Register `mission` toolset in Hermes registry  | `tools/registry.py`           | 30m      |
+| 1.9 Add `mission` to orchestrator profile toolsets | `config.yaml`                 | 10m      |
+| 1.10 Write unit tests for mission_state            | `tests/test_mission_state.py` | 2h       |
+| 1.11 Write unit tests for TASKS.md parser          | `tests/test_tasks_parser.py`  | 1h       |
+
+**Phase 1 estimate:** ~13h
+
+### Phase 2: Handoff and session continuity
+
+| Task                                              | Files                                    | Estimate |
+| ------------------------------------------------- | ---------------------------------------- | -------- |
+| 2.1 Define handoff packet schema (JSON)           | `mission_handoff.py`                     | 1h       |
+| 2.2 Implement `mission_handoff` tool-call         | `mission_handoff.py`, `mission_tools.py` | 2h       |
+| 2.3 Implement `mission_resume` tool-call          | `mission_handoff.py`, `mission_tools.py` | 2h       |
+| 2.4 Wire handoff into session start (auto-resume) | agent loop hook                          | 2h       |
+| 2.5 Write tests for handoff round-trip            | `tests/test_mission_handoff.py`          | 1h       |
+
+**Phase 2 estimate:** ~8h
+
+### Phase 3: Churn detection
+
+| Task                                                           | Files                         | Estimate |
+| -------------------------------------------------------------- | ----------------------------- | -------- |
+| 3.1 Define churn signal weights and thresholds                 | `mission_churn.py`            | 1h       |
+| 3.2 Implement tool-loop detector (consecutive identical calls) | `mission_churn.py`            | 2h       |
+| 3.3 Implement compaction pressure detector                     | `mission_churn.py`            | 1h       |
+| 3.4 Implement progress scorer (file state delta)               | `mission_churn.py`            | 2h       |
+| 3.5 Wire churn scoring into agent turn loop                    | agent loop middleware         | 2h       |
+| 3.6 Implement auto-rotation trigger                            | agent loop + handoff          | 2h       |
+| 3.7 Write tests for churn scoring                              | `tests/test_mission_churn.py` | 1h       |
+
+**Phase 3 estimate:** ~11h
+
+### Phase 4: Kanban bridge + CLI surface
+
+| Task                                                 | Files                    | Estimate |
+| ---------------------------------------------------- | ------------------------ | -------- |
+| 4.1 Implement TASKS.md → Kanban sync (one-way first) | `mission_kanban_sync.py` | 2h       |
+| 4.2 Add `hermes mission` CLI subcommand              | `mission_cli.py`         | 2h       |
+| 4.3 Add `hermes mission status` command              | `mission_cli.py`         | 1h       |
+| 4.4 Add `hermes mission init` command                | `mission_cli.py`         | 1h       |
+| 4.5 Add `hermes mission handoff` command             | `mission_cli.py`         | 1h       |
+| 4.6 Add `hermes mission resume` command              | `mission_cli.py`         | 1h       |
+
+**Phase 4 estimate:** ~8h
+
+---
+
+## File Format Compatibility
+
+The Python implementation MUST read and write the exact same file formats as Mosaic's TypeScript `packages/coord`. This means:
+
+1. **mission.json** schema is identical to `Mission` type in `packages/coord/src/types.ts`
+2. **TASKS.md** table format is identical to what `packages/coord/src/tasks-file.ts` parses
+3. **MISSION-MANIFEST.md** is free-form markdown (no parser needed — just read the file)
+4. **Handoff packets** are a new JSON format defined in this toolset (Mosaic doesn't have them yet)
+
+This way a project can use Hermes mission tools OR Mosaic `mosaic coord` commands interchangeably. The files are the contract.
+
+---
+
+## Relationship Diagram
+
+```
+Mosaic Stack (TypeScript)          Hermes Agent (Python)
+┌─────────────────────────┐        ┌─────────────────────────┐
+│  packages/coord          │        │  tools/mission_tools.py  │
+│  ├─ mission.ts           │◄──────►│  ├─ mission_state.py     │
+│  ├─ tasks-file.ts        │  same  │  ├─ mission_handoff.py   │
+│  ├─ status.ts            │  files │  ├─ mission_churn.py     │
+│  └─ runner.ts            │        │  └─ mission_tools.py     │
+│                          │        │                          │
+│  packages/prdy           │        │  skills/prdy/            │
+│  └─ templates, wizard    │◄──────►│  └─ SKILL.md + templates │
+│                          │        │                          │
+│  plugins/mosaic-framework│        │  skills/ (existing)      │
+│  └─ context injection    │◄──────►│  └─ kanban-orchestrator  │
+│                          │        │     + mosaic-coding-*     │
+│  plugins/macp            │        │  tools/delegate_task.py  │
+│  └─ ACP bridge           │◄──────►│  └─ already covers this  │
+│                          │        │                          │
+│  (stays in Mosaic)       │        │  tools/kanban_tools.py   │
+│  apps/gateway            │        │  └─ Hermes Kanban DB     │
+│  apps/web                │        │                          │
+│  packages/db             │        │  tools/cronjob_tools.py  │
+│  packages/queue          │        │  └─ already covers cron  │
+└─────────────────────────┘        └─────────────────────────┘
+```
+
+---
+
+## Open Questions
+
+1. **Should the `mission` toolset ship with Hermes core, or as a plugin?**
+   - Recommendation: ship as a **built-in toolset** (like `kanban`) since mission coordination is a core agent capability, not an optional integration. The file formats are stable and the code is small.
+
+2. **Should churn detection be per-profile configurable?**
+   - Recommendation: yes. Add `mission.churn_threshold` and `mission.churn_weights` to profile config.yaml. Default threshold = 5 consecutive no-progress turns.
+
+3. **Should handoff packets live in the project dir or in Hermes home?**
+   - Recommendation: **project dir** (`.mosaic/handoffs/<session-id>.json`). This keeps them version-controlled and accessible regardless of which agent runtime picks up the project.
+
+4. **Bidirectional Kanban sync?**
+   - Recommendation: **one-way first** (TASKS.md → Kanban). Bidirectional adds conflict resolution complexity. Ship one-way, add reverse sync in v2 if needed.
+
+5. **PRD generation — skill or tool-call?**
+   - Recommendation: **skill** (`prdy`). PRD generation is a prompt engineering problem with templates. Skills already handle this pattern perfectly.

docs/plans/2026-05-07-coordination-resilience.md

@@ -0,0 +1,236 @@
+# Mosaic Stack ↔ Hermes Coordination Resilience
+
+> Purpose: document the self-healing coordination patterns that emerged while implementing the Hermes mission toolset, distress-card protocol, and auto-heal watchers, so the same mechanics can be reimplemented in Mosaic Stack or any similar agent platform.
+
+## Summary
+
+The coordination layer should be treated as a system of mechanical recovery loops rather than a single interactive agent session.
+
+## SIBKISS operational summary
+
+- mission on
+- heartbeat always
+- resume from packet
+- block with `[BLOCKED]`
+- reassign
+- keep tasks tiny
+- auto-heal dead workers
+
+The design has four parts:
+
+1. Atomic task decomposition — workers operate only within a small, explicit scope.
+2. Distress signaling — workers create a standardized `[BLOCKED]` card when they encounter a blocker outside their scope.
+3. Mechanical fallback — if the worker cannot phone home because of rate limits or dead context, a cron-style watcher synthesizes the distress card for them.
+4. Auto-heal / reassignment — stale workers are reaped, crash-loops are reset, and rate-limited work is reassigned to a different profile/provider.
+
+## Why this exists
+
+Observed failure modes:
+
+- Scope creep: a worker completes the target fix, then spends the rest of its budget chasing downstream cascade work.
+- Silent failure / dead worker: the worker PID is gone, but the task remains running or blocked.
+- Rate-limited worker: the worker is too constrained to create a help card itself, so it spins or fails without a clean handoff.
+
+The answer is not to raise iteration caps or ask the worker to keep trying longer. The answer is to make the coordination layer self-healing and the work items atomic.
+
+## Core workflow
+
+### 1) Atomic task boundaries
+
+Every task should have:
+
+- one concern
+- explicit files/packages in scope
+- explicit files/packages out of scope
+- a maximum file count if possible
+- a stated expected iteration budget
+
+When a worker discovers work outside scope, it must stop fixing it and hand off.
+
+### 2) Worker-authored distress card
+
+If the worker can still report status, it creates a card like:
+
+- Title: `[BLOCKED] t_<source_id> <blocker_type>`
+- Assignee: `tuesday` / orchestrator role
+- Status: `ready`
+- Body: standardized distress template with source task, blocker type, completed work, cannot-touch scope, and needed action
+
+The orchestrator receives the card, acts on it, and closes the loop.
+
+## Routing rules
+
+### Distress card routing
+
+- Title: `[BLOCKED] t_<source_id> <blocker_type>`
+- Assignee: `tuesday` / orchestrator role
+- Status: `ready`
+- Body: standardized distress template with source task, blocker type, completed work, cannot-touch scope, and needed action
+- Source task stays linked to the distress card so the recovery trail is auditable
+
+The orchestrator receives the card, acts on it, and closes the loop.
+
+### 3) Mechanical fallback for rate-limited workers
+
+If the worker is too rate-limited or unstable to create the distress card itself, a no-agent watcher must synthesize the card from the task row and failure metadata.
+
+That watcher should:
+
+- inspect running / blocked tasks
+- detect repeated 429 / 503 / overload errors
+- create the same standardized `[BLOCKED]` card on behalf of the worker
+- link the distress card to the source task
+- add a comment to the source task
+- allow the dispatcher to pick up the new card immediately
+
+This is the key fix for the logic issue: the worker does not need to be able to phone home if the watcher can do it mechanically.
+
+### 4) Auto-heal for dead workers
+
+A separate no-agent watcher should:
+
+- reap dead PIDs stuck in `running`
+- reset crash-loops whose failures are infrastructure-related
+- escalate tasks that have been reset too many times
+
+This watcher prevents stale tasks from clogging the board and keeps the dispatch queue moving.
+
+## Distress card contract
+
+### Canonical title
+
+```text
+[BLOCKED] t_<source_task_id> <blocker_type>
+```
+
+### Canonical blocker types
+
+- `scope_boundary`
+- `env_blocker`
+- `credential_failure`
+- `dependency`
+- `iteration_budget`
+- `rate_limited`
+
+### Canonical body
+
+```markdown
+## Distress Signal
+
+- Blocked task: t_xxx
+- Worker: <profile_name>
+- Branch: <git_branch_name>
+- Workspace: <path>
+- Blocker type: <type>
+- Completed: <what was done>
+- Cannot touch: <out-of-scope packages/files>
+- Needs: <what the orchestrator should do>
+- State: committed | uncommitted | stashed(<stash_name>)
+
+## Scope Guard
+
+DO NOT touch: anything outside diagnosing and remediating the blocker described above
+Only fix: assign, split, reassign, or unblock the source task
+```
+
+## Routing rules
+
+### Distress card routing
+
+- `[BLOCKED]` title prefix should bypass normal triage.
+- The card should go directly to the orchestration profile.
+- The orchestrator should start from a clean session each time.
+
+### Rate-limit fallback
+
+When the source task is rate-limited:
+
+- do not keep retrying in the worker
+- let the watcher synthesize the distress card
+- have the orchestrator reassign the source task to a different profile/provider combo
+
+### Provider fallback principle
+
+Never reassign rate-limited work back to the same provider if the failure was provider pressure. Use a different provider when possible.
+
+### Suggested fallback order
+
+1. Keep the current task body and scope guards intact.
+2. Reassign to a different profile on a different provider.
+3. If that is impossible, reassign to a different profile on the same provider only for non-rate-limit blockers.
+4. If repeated failures continue, split the task into a narrower atomic card.
+
+## Related recovery docs
+
+- Mission packet recovery contract: `/opt/hermes/docs/mission-toolset-heartbeat.md`
+- Hermes mission implementation plan: `/opt/hermes/docs/plans/mission-toolset-implementation.md`
+- The same packet-first resume rule applies: inspect the latest packet before re-reading mission files.
+- New-session trigger: when a profile config changes, start a fresh session or `/reset` so the updated toolset is actually loaded.
+
+## Watchers to implement
+
+### Auto-heal watcher
+
+Responsibilities:
+
+- reap stale workers
+- reset dead-PID crash loops
+- track reset counts
+- escalate after repeated resets
+
+### Distress synthesizer watcher
+
+Responsibilities:
+
+- detect rate-limited / stuck workers
+- create `[BLOCKED]` cards mechanically
+- link the card to the source task
+- leave a comment for traceability
+
+### Iteration-budget watcher
+
+Responsibilities:
+
+- detect long-running tasks and repeated failure patterns
+- recommend splits when a task is clearly over-scoped
+- report tasks that need human review after multiple resets
+
+## Operational principle
+
+If a task cannot cleanly finish within its atomic scope, the right response is to surface a smaller coordination problem, not to keep burning context.
+
+This is what makes the system robust across compaction, rate limits, and dead workers.
+
+## Suggested implementation order
+
+1. Atomic task metadata in task bodies
+2. Worker-authored distress card protocol
+3. Mechanical distress synthesizer watcher
+4. Auto-heal watcher for dead workers
+5. Orchestrator routing rules for `[BLOCKED]`
+6. Rate-limit fallback / model reassignment table
+
+## Where this fits in Hermes
+
+- Kanban = durable work graph and status engine
+- Watchers = mechanical healing and distress synthesis
+- Orchestrator = split / reassign / unblock decision-maker
+- Workers = execution inside atomic task boundaries
+
+## Where this fits in Mosaic Stack
+
+- PRD / coordination infra should encode the same patterns
+- Mosaic can use the same distress-card contract and watcher logic
+- The coordination model should be runtime-agnostic: any agent system can use it if it can write a task card and react to a ready queue
+
+## Cross-project takeaway
+
+The important pattern is not the specific tool names. It is the mechanical feedback loop:
+
+- detect failure without requiring the failing worker to succeed
+- create a standardized help artifact
+- route that artifact to a fresh orchestrator context
+- repair the assignment graph
+- continue the mission
+
+That pattern is reusable anywhere.

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.

docs/scratchpads/t-a292e96f-gitea-pr-metadata.md

@@ -0,0 +1,53 @@
+# t_a292e96f — Gitea PR metadata wrapper fix
+
+## Objective
+
+Repair Mosaic git wrappers so Gitea PR metadata and merge preflight work for U-Connect PRs on `git.uscllc.com` without selecting the unrelated `git.mosaicstack.dev` tea login.
+
+## Findings
+
+- Reproduced the failure from `/src/uconnect-worktrees/t_39ce717c-authentik-smoke-gate` with the current `pr-metadata.sh`:
+  - PR #1905 returned JSON with `number=null`, `baseRefName=""`, `headRefName=""`.
+  - PR #1908 returned JSON with `number=null`, `baseRefName=""`, `headRefName=""`.
+- Root cause: the wrapper treated HTTP/API error payloads as PR payloads and normalized missing fields to empty strings.
+- The credential loader can return a non-working `git.uscllc.com` API token in this environment, while host-specific `~/.git-credentials` basic auth succeeds. The wrapper now falls back by host before normalization.
+- `tea login list` has only `git.mosaicstack.dev` configured here; `pr-merge.sh` previously forced `--login mosaicstack`, which is invalid for `git.uscllc.com` and caused `Login name mosaicstack does not exist`.
+
+## Changes
+
+- `packages/mosaic/framework/tools/git/detect-platform.sh`
+  - Added `get_gitea_basic_auth <host>` to retrieve host-specific HTTPS credentials from `~/.git-credentials` without printing secrets.
+- `packages/mosaic/framework/tools/git/pr-metadata.sh`
+  - Uses strict bash mode.
+  - Checks Gitea HTTP status and fails nonzero on API errors/non-JSON instead of emitting empty branch fields.
+  - Falls back from token auth to host-specific basic auth.
+  - Normalizes standard `head.ref`/`base.ref` and fallback branch fields.
+  - Requires non-empty `headRefName` and `baseRefName`.
+  - Preserves GitHub `gh pr view` behavior.
+- `packages/mosaic/framework/tools/git/pr-merge.sh`
+  - Reads metadata once for base-branch policy preflight.
+  - Selects a `tea` login only when its configured URL matches the repo host.
+  - Falls back to authenticated Gitea merge API when no matching `tea` login exists, avoiding the wrong `mosaicstack` login for USC repos.
+  - Keeps squash-only and main-only merge policy.
+- `packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`
+  - Added fixture-based regression harness for standard Gitea fields, fallback branch fields, `refs/pull/<n>/head` plus `head.label` normalization, and API error payloads.
+
+## Documentation / changelog note
+
+This repository currently has no root `CHANGELOG.md`; the scratchpad and `docs/TASKS.md` carry the task-level change record for this wrapper fix.
+
+## Verification log
+
+- Red regression check: copied the new `test-pr-metadata-gitea.sh` harness next to `origin/main` wrapper scripts and ran it with `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-gitea-red`; it failed as expected with `headRefName=''` and `baseRefName=''` on the fixture API-error path.
+- `bash -n packages/mosaic/framework/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh,test-pr-metadata-gitea.sh}`: passed.
+- `shellcheck -x -P . -e SC1090 packages/mosaic/framework/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh,test-pr-metadata-gitea.sh}`: passed.
+- `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-gitea packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`: passed; verifies standard Gitea fields, fallback branch fields, `refs/pull/<n>/head` label normalization, and nonzero API-error handling.
+- Installed wrapper parity: `/home/hermes/.config/mosaic/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh}` byte-match the PR source copies after validation, so active U-Connect wrapper invocations use the same fix while source PR review runs.
+- Live sanitized U-Connect metadata from `/src/uconnect` with `MOSAIC_CREDENTIALS_FILE=/src/jarvis-brain/credentials.json`:
+  - PR #1905: `number=1905`, `baseRefName=main`, `headRefName=edith/t_39ce717c-authentik-smoke-gate`, `state=open`, `host=git.uscllc.com`.
+  - PR #1908: `number=1908`, `baseRefName=main`, `headRefName=fix/t_23fa9e1d-portal-health-backend`, `state=closed`, `host=git.uscllc.com`.
+- 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`.
+- 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.

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`.

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.

eslint.config.mjs

@@ -30,6 +30,7 @@ export default tseslint.config(
             'apps/gateway/vitest.config.ts',
             'packages/storage/vitest.config.ts',
             'packages/mosaic/__tests__/*.ts',
+            'tools/federation-harness/*.ts',
           ],
         },
       },

guides/BOOTSTRAP.md

@@ -453,6 +453,26 @@ Initialize standard labels and the first pre-MVP milestone:
 
 ---
 
+## Secrets Bootstrap (Required for Every New App)
+
+Every new application MUST complete the following secrets bootstrap before deploying to any non-local environment. This is a hard gate — deployment without completed secrets bootstrap is forbidden.
+
+### Secrets bootstrap checklist
+
+- [ ] Vault path created: `vault kv put secret/k3s/<app>/ ...` with all required secret fields
+- [ ] Required secrets listed in project README under a "Secrets architecture" section, including:
+  - Vault path(s) used
+  - All required secret keys and their purpose
+  - Whether the app uses ESO bridge (default) or Direct-Vault (opt-in, with justification)
+- [ ] `external-secret.yaml` manifest committed to repo's `deploy/` or `k8s/` directory
+- [ ] Deployment YAML references the synced k8s Secret via `secretKeyRef` (not raw env vars or `.env` files)
+- [ ] App startup has schema-based validation for all required env vars (zod / pydantic / envconfig equivalent) that exits non-zero on missing required values
+- [ ] Direct-Vault opt-in (if applicable): justification documented in README + AppRole provisioned + bootstrap credentials stored in Vault and synced via a separate `ExternalSecret`
+
+See `~/.config/mosaic/guides/VAULT-SECRETS.md` for full worked examples of the ESO bridge pattern, the Direct-Vault opt-in pattern, and the forbidden antipatterns.
+
+---
+
 ## Checklist
 
 After bootstrapping, verify:

guides/VAULT-SECRETS.md

@@ -203,3 +203,374 @@ Error: token expired
 3. **Audit logging** - All access is logged; act accordingly
 4. **No local copies** - Don't store secrets in files or env vars long-term
 5. **Rotate on compromise** - Immediately rotate any exposed secrets
+
+---
+
+## Secrets Architecture Decision Matrix
+
+Use this table to choose between the ESO bridge (default) and Direct-Vault (opt-in) patterns for every new app or integration.
+
+| Factor                      | ESO Bridge (default)                                                          | Direct-Vault (opt-in)                                                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **Use-case**                | All static secrets (DB creds, API keys, signing keys, OAuth secrets)          | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
+| **App code change**         | None — reads standard env vars via `secretKeyRef`                             | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code                                           |
+| **Secret rotation**         | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process                                                         |
+| **Audit granularity**       | Access logged at Vault when ESO syncs; no per-request app audit               | Every app request to Vault is a separate audit log entry                                                                |
+| **Operational burden**      | Low — ESO handles polling, sync, and k8s Secret lifecycle                     | Higher — app must handle auth, lease renewal, error paths, and token rotation                                           |
+| **Justification required?** | No — this is the default                                                      | Yes — document in project README under "Secrets architecture"                                                           |
+| **Example use cases**       | Web app DB password, OAuth client secret, JWT signing key, API token          | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs                    |
+
+**Decision rule:** If you are unsure, use ESO. Only justify Direct-Vault when the secret cannot be safely stored in a k8s Secret (too short-lived, per-request TTL required, or mid-lifecycle renewal needed).
+
+---
+
+## ESO Bridge Pattern (Default)
+
+This is the required default for all k8s workloads. Follow this exact pattern unless a documented dynamic-secrets requirement justifies Direct-Vault.
+
+### 1. Provision Vault path
+
+```bash
+# Write the secrets for the app (run once; use IaC/Terraform for repeatable provisioning)
+vault kv put secret/k3s/<app> \
+  db_password="..." \
+  api_key="..." \
+  jwt_secret="..."
+```
+
+Use the canonical path structure: `secret/k3s/<app>` for k3s cluster workloads.
+
+### 2. ExternalSecret manifest
+
+Commit this to the repo's `deploy/` or `k8s/` directory:
+
+```yaml
+# deploy/external-secret.yaml
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: <app>-secrets
+  namespace: <namespace>
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: vault-backend # ClusterSecretStore name — verify with cluster admin
+    kind: ClusterSecretStore
+  target:
+    name: <app>-secrets # k8s Secret name that will be created
+    creationPolicy: Owner
+  data:
+    - secretKey: DB_PASSWORD # key in the k8s Secret
+      remoteRef:
+        key: secret/k3s/<app> # Vault path
+        property: db_password # field within the Vault secret
+    - secretKey: API_KEY
+      remoteRef:
+        key: secret/k3s/<app>
+        property: api_key
+    - secretKey: JWT_SECRET
+      remoteRef:
+        key: secret/k3s/<app>
+        property: jwt_secret
+```
+
+### 3. Deployment manifest — reference synced k8s Secret
+
+```yaml
+# deploy/deployment.yaml (env section)
+env:
+  - name: DB_PASSWORD
+    valueFrom:
+      secretKeyRef:
+        name: <app>-secrets # matches ExternalSecret target.name
+        key: DB_PASSWORD
+  - name: API_KEY
+    valueFrom:
+      secretKeyRef:
+        name: <app>-secrets
+        key: API_KEY
+  - name: JWT_SECRET
+    valueFrom:
+      secretKeyRef:
+        name: <app>-secrets
+        key: JWT_SECRET
+  - name: PORT
+    value: '3000' # safe-default: non-secret, no Vault needed
+```
+
+### 4. App-side schema validation — TypeScript (zod)
+
+Validate all required env vars at startup. Exit non-zero on missing values.
+
+```typescript
+// src/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  DB_PASSWORD: z.string().min(1, 'DB_PASSWORD is required'),
+  API_KEY: z.string().min(1, 'API_KEY is required'),
+  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 chars'),
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),
+});
+
+const result = envSchema.safeParse(process.env);
+if (!result.success) {
+  console.error('Missing or invalid environment variables:');
+  console.error(result.error.flatten().fieldErrors);
+  process.exit(1);
+}
+
+export const env = result.data;
+```
+
+### 4b. App-side schema validation — Python (pydantic)
+
+```python
+# src/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    db_password: str
+    api_key: str
+    jwt_secret: str
+    port: int = 3000
+    node_env: str = "production"
+
+    model_config = SettingsConfigDict(env_file=None)  # no .env in prod
+
+try:
+    settings = Settings()
+except Exception as e:
+    import sys
+    print(f"Missing or invalid environment variables: {e}", file=sys.stderr)
+    sys.exit(1)
+```
+
+### 4c. App-side schema validation — Go (envconfig)
+
+```go
+// config/config.go
+package config
+
+import (
+    "fmt"
+    "github.com/kelseyhightower/envconfig"
+)
+
+type Config struct {
+    DBPassword string `envconfig:"DB_PASSWORD" required:"true"`
+    APIKey     string `envconfig:"API_KEY" required:"true"`
+    JWTSecret  string `envconfig:"JWT_SECRET" required:"true"`
+    Port       int    `envconfig:"PORT" default:"3000"`
+}
+
+func Load() (*Config, error) {
+    var cfg Config
+    if err := envconfig.Process("", &cfg); err != nil {
+        return nil, fmt.Errorf("invalid environment: %w", err)
+    }
+    return &cfg, nil
+}
+```
+
+In your `main.go`:
+
+```go
+cfg, err := config.Load()
+if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    os.Exit(1)
+}
+```
+
+---
+
+## Direct-Vault Opt-In Pattern
+
+Use this pattern ONLY when a documented dynamic-secrets requirement applies (DB rotation with short TTLs, AWS STS, PKI, per-request audit). Document the justification in the project README under "Secrets architecture" before implementing.
+
+### When it is justified
+
+- Vault DB secrets engine with lease TTLs shorter than a typical pod lifecycle (< 1 hour)
+- AWS STS assume-role tokens generated per-request
+- Vault PKI short-lived certificates (< 24 hours) that must be renewed within a running pod
+- Per-request audit trail requirement (each app call must appear separately in Vault audit log)
+
+### Provision an AppRole for the app
+
+```bash
+# Enable AppRole auth (if not already enabled)
+vault auth enable approle
+
+# Create a Vault policy for the app
+# Note: KV v2 paths require both the exact path (for the top-level secret) and the
+# wildcard (for sub-paths). Always include both to avoid permission denied errors.
+vault policy write <app>-policy - <<EOF
+path "secret/data/k3s/<app>" {
+  capabilities = ["read"]
+}
+path "secret/data/k3s/<app>/*" {
+  capabilities = ["read"]
+}
+path "database/creds/<app>-role" {
+  capabilities = ["read"]
+}
+EOF
+
+# Create the AppRole
+vault write auth/approle/role/<app>-role \
+  token_policies="<app>-policy" \
+  token_ttl=1h \
+  token_max_ttl=4h \
+  secret_id_ttl=0
+
+# Retrieve role-id and secret-id
+vault read auth/approle/role/<app>-role/role-id
+vault write -f auth/approle/role/<app>-role/secret-id
+```
+
+### Bootstrap AppRole credentials via ESO (solving the chicken-and-egg problem)
+
+The AppRole `role-id` and `secret-id` are themselves secrets. Store them in Vault at a bootstrap path, then use ESO to sync them into a k8s Secret. The app reads that k8s Secret at startup to authenticate with Vault directly.
+
+```bash
+# Store the bootstrap credentials in Vault
+vault kv put secret/k3s/<app>-bootstrap \
+  role_id="<role-id>" \
+  secret_id="<secret-id>"
+```
+
+```yaml
+# deploy/external-secret-bootstrap.yaml
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: <app>-vault-auth
+  namespace: <namespace>
+spec:
+  refreshInterval: 24h
+  secretStoreRef:
+    name: vault-backend
+    kind: ClusterSecretStore
+  target:
+    name: <app>-vault-auth
+    creationPolicy: Owner
+  data:
+    - secretKey: VAULT_ROLE_ID
+      remoteRef:
+        key: secret/k3s/<app>-bootstrap
+        property: role_id
+    - secretKey: VAULT_SECRET_ID
+      remoteRef:
+        key: secret/k3s/<app>-bootstrap
+        property: secret_id
+```
+
+```yaml
+# deploy/deployment.yaml (env section for Direct-Vault app)
+env:
+  - name: VAULT_ADDR
+    value: 'https://vault.example.com' # safe-default: non-secret cluster address
+  - name: VAULT_ROLE_ID
+    valueFrom:
+      secretKeyRef:
+        name: <app>-vault-auth
+        key: VAULT_ROLE_ID
+  - name: VAULT_SECRET_ID
+    valueFrom:
+      secretKeyRef:
+        name: <app>-vault-auth
+        key: VAULT_SECRET_ID
+```
+
+### App-side Vault client pattern
+
+```typescript
+// src/vault-client.ts — only exists in Direct-Vault apps
+import vault from 'node-vault';
+import { z } from 'zod';
+
+const bootstrapSchema = z.object({
+  VAULT_ADDR: z.string().url(),
+  VAULT_ROLE_ID: z.string().min(1),
+  VAULT_SECRET_ID: z.string().min(1),
+});
+
+const bootstrap = bootstrapSchema.parse(process.env);
+
+const client = vault({ endpoint: bootstrap.VAULT_ADDR });
+
+export async function getVaultClient() {
+  const { auth } = await client.approleLogin({
+    role_id: bootstrap.VAULT_ROLE_ID,
+    secret_id: bootstrap.VAULT_SECRET_ID,
+  });
+  client.token = auth.client_token;
+  return client;
+}
+```
+
+Document in README under "Secrets architecture": the Vault path, why Direct-Vault is required, and the lease/renewal strategy.
+
+---
+
+## Forbidden Patterns (CI Lint Targets)
+
+The following patterns are forbidden in all Mosaic projects. CI lint SHOULD catch these automatically (implementation tracked separately). Agents MUST NOT introduce these patterns.
+
+### 1. Untagged fallback defaults for required values
+
+```yaml
+# FORBIDDEN — required secret with silent fallback
+environment:
+  - DB_PASSWORD=${DB_PASSWORD:-changeme}
+  - API_KEY=${API_KEY:-}
+
+# REQUIRED — fast-fail on missing required values
+environment:
+  - DB_PASSWORD=${DB_PASSWORD:?DB_PASSWORD is required}
+  - API_KEY=${API_KEY:?API_KEY is required}
+
+# ALLOWED — true convenience default, tagged
+environment:
+  - PORT=${PORT:-3000}  # safe-default: non-secret, app works at any port
+```
+
+This applies to: `docker-compose.yml`, k8s manifests, Helm `values.yaml`, any env file committed to git.
+
+### 2. Vault KV calls in application source code (ESO-default projects)
+
+```python
+# FORBIDDEN in ESO-default apps — direct Vault client in app source
+import hvac
+client = hvac.Client(url=os.environ['VAULT_ADDR'])
+secret = client.secrets.kv.v2.read_secret_version(path='myapp/db')
+```
+
+ESO-default apps read env vars only. Direct-Vault clients belong only in apps with a documented dynamic-secrets justification in README.
+
+### 3. Hardcoded secrets or API keys in committed files
+
+```python
+# FORBIDDEN — hardcoded credential
+DB_PASSWORD = "supersecret123"
+API_KEY = "sk-live-abc123"
+```
+
+No exceptions. CI lint must flag any string matching common secret patterns (`password`, `secret`, `api_key`, `token` assigned a literal non-env-var value).
+
+### 4. `.env` files in production deployment paths
+
+```
+# FORBIDDEN — .env file in a production deploy path
+deploy/.env
+k8s/.env
+docker/.env
+
+# ALLOWED — local dev only
+.env.example          # template only, no real values
+.env                  # local dev, must be in .gitignore
+```
+
+`.env` files are acceptable in local-dev contexts only and MUST be in `.gitignore`. They are forbidden in any path that a CI pipeline or production deployment process reads directly.

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"
+  ]
+}

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');
+  });
+});

packages/appservice/src/bridge.dto.ts

@@ -0,0 +1,83 @@
+/** 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');
+}
+
+export interface ProvisionRoomDto {
+  name: string;
+  alias?: string;
+  topic?: string;
+  invite?: string[];
+  space_id?: string;
+}
+
+export function validateProvisionRoom(input: unknown): asserts input is ProvisionRoomDto {
+  const o = input as Partial<ProvisionRoomDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.name !== 'string' || o.name.length === 0) throw new Error('name is required');
+  if (o.alias !== undefined && (!/^[a-z0-9_.-]+$/.test(o.alias) || o.alias.length > 200)) {
+    throw new Error('alias must match [a-z0-9_.-]+ (max 200 chars)');
+  }
+  if (o.invite !== undefined) {
+    if (
+      !Array.isArray(o.invite) ||
+      o.invite.some((u) => typeof u !== 'string' || !u.startsWith('@'))
+    ) {
+      throw new Error('invite must be a list of Matrix user ids');
+    }
+    if (o.invite.length > 50) {
+      throw new Error('invite list exceeds maximum of 50');
+    }
+  }
+  if (o.space_id !== undefined && (typeof o.space_id !== 'string' || !o.space_id.startsWith('!'))) {
+    throw new Error('space_id must be a Matrix room id');
+  }
+}

packages/appservice/src/index.ts

@@ -0,0 +1,19 @@
+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,
+  validateProvisionRoom,
+} from './bridge.dto.js';
+export type { BridgeMessageDto, BridgeTypingDto, ProvisionRoomDto } from './bridge.dto.js';
+export type {
+  AppserviceConfig,
+  EventHandler,
+  HandlerResult,
+  MatrixEvent,
+  Transaction,
+} from './types.js';

packages/appservice/src/intent.ts

@@ -0,0 +1,236 @@
+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 },
+    });
+  }
+
+  /** Create a room as the AS sender: agents get PL 50 by namespace via the
+   * sender (PL 100); humans invited at default PL. Optionally link into a
+   * space (m.space.child + m.space.parent). Returns the room id. */
+  async createRoom(options: {
+    name: string;
+    alias?: string;
+    topic?: string;
+    invite?: string[];
+    spaceId?: string;
+  }): Promise<{ roomId: string; spaceLinked: boolean; spaceError?: string }> {
+    const body: Record<string, unknown> = {
+      name: options.name,
+      preset: 'private_chat',
+      invite: options.invite ?? [],
+      power_level_content_override: {
+        users: { [this.senderUserId]: 100 },
+        // state_default 50 stays; the AS sender can grant agents as needed.
+      },
+    };
+    if (options.alias) body.room_alias_name = options.alias;
+    if (options.topic) body.topic = options.topic;
+    const res = await this.request('POST', '/_matrix/client/v3/createRoom', {
+      userId: this.senderUserId,
+      body,
+    });
+    const roomId = res.room_id;
+    if (typeof roomId !== 'string') throw new Error('createRoom returned no room_id');
+    if (!options.spaceId) {
+      return { roomId, spaceLinked: false };
+    }
+    // Space-link failures must NOT throw: the room already exists, and an
+    // exception would hide the room_id (orphaned room, no recovery path).
+    const encodedSpaceId = encodeURIComponent(options.spaceId);
+    const encodedRoomId = encodeURIComponent(roomId);
+    try {
+      await this.request(
+        'PUT',
+        `/_matrix/client/v3/rooms/${encodedSpaceId}/state/m.space.child/${encodedRoomId}`,
+        { userId: this.senderUserId, body: { via: [this.cfg.domain], suggested: true } },
+      );
+      await this.request(
+        'PUT',
+        `/_matrix/client/v3/rooms/${encodedRoomId}/state/m.space.parent/${encodedSpaceId}`,
+        { userId: this.senderUserId, body: { via: [this.cfg.domain], canonical: true } },
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { roomId, spaceLinked: false, spaceError: message };
+    }
+    return { roomId, spaceLinked: true };
+  }
+
+  /** 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 },
+    });
+  }
+}

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');
+}

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);
+    }
+  }
+}

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>;
+}

packages/appservice/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

packages/db/package.json

@@ -42,6 +42,7 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "drizzle"
   ]
 }

packages/db/src/client-pglite.ts

@@ -1,10 +1,12 @@
 import { PGlite } from '@electric-sql/pglite';
+import { vector } from '@electric-sql/pglite/vector';
 import { drizzle } from 'drizzle-orm/pglite';
 import * as schema from './schema.js';
 import type { DbHandle } from './client.js';
 
 export function createPgliteDb(dataDir: string): DbHandle {
-  const client = new PGlite(dataDir);
+  // pgvector extension is required by migration 0001 (insights.embedding column).
+  const client = new PGlite(dataDir, { extensions: { vector } });
   const db = drizzle(client, { schema });
   return {
     db: db as unknown as DbHandle['db'],

packages/db/src/index.ts

@@ -1,6 +1,6 @@
 export { createDb, type Db, type DbHandle } from './client.js';
 export { createPgliteDb } from './client-pglite.js';
-export { runMigrations } from './migrate.js';
+export { runMigrations, runPgliteMigrations } from './migrate.js';
 export * from './schema.js';
 export * from './federation.js';
 export {

packages/db/src/migrate.test.ts

@@ -0,0 +1,70 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sql } from 'drizzle-orm';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createPgliteDb } from './client-pglite.js';
+import { runPgliteMigrations } from './migrate.js';
+import type { DbHandle } from './client.js';
+
+interface PgliteExec {
+  exec(query: string): Promise<unknown>;
+}
+
+describe('runPgliteMigrations', () => {
+  let dataDir: string;
+  let handle: DbHandle;
+
+  beforeEach(() => {
+    dataDir = mkdtempSync(join(tmpdir(), 'mosaic-db-migrate-test-'));
+    handle = createPgliteDb(dataDir);
+  });
+
+  afterEach(async () => {
+    await handle.close();
+    rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('creates the BetterAuth tables required by the gateway', async () => {
+    await runPgliteMigrations(handle);
+
+    const result = (await handle.db.execute(sql`
+      SELECT table_name FROM information_schema.tables
+      WHERE table_schema = 'public'
+      ORDER BY table_name
+    `)) as unknown as { rows: Array<{ table_name: string }> };
+
+    const tables = result.rows.map((r) => r.table_name);
+
+    // Auth tables — required for sign-in / bootstrap to function.
+    expect(tables).toContain('users');
+    expect(tables).toContain('sessions');
+    expect(tables).toContain('accounts');
+    expect(tables).toContain('verifications');
+
+    // Schema sanity check — admin token table consumed by mosaic gateway config.
+    expect(tables).toContain('admin_tokens');
+  });
+
+  it('is idempotent — running twice does not error', async () => {
+    await runPgliteMigrations(handle);
+    await expect(runPgliteMigrations(handle)).resolves.toBeUndefined();
+  });
+
+  it('surfaces statement-level error context on failure and leaves no ledger row', async () => {
+    // Pre-create a `users` table that conflicts with migration 0000's CREATE TABLE,
+    // forcing it to fail without IF NOT EXISTS.
+    const client = (handle.db as unknown as { $client: PgliteExec }).$client;
+    await client.exec('CREATE TABLE users (sentinel text)');
+
+    await expect(runPgliteMigrations(handle)).rejects.toThrow(
+      /migration hash=[a-f0-9]+ statement #\d+ failed/,
+    );
+
+    // Ledger should be empty — partial application must not pretend to be complete.
+    const ledger = (await handle.db.execute(
+      sql`SELECT count(*)::int AS count FROM drizzle.__drizzle_migrations`,
+    )) as unknown as { rows: Array<{ count: number }> };
+    expect(ledger.rows[0]?.count).toBe(0);
+  });
+});

packages/db/src/migrate.ts

@@ -1,18 +1,109 @@
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { drizzle } from 'drizzle-orm/postgres-js';
-import { migrate } from 'drizzle-orm/postgres-js/migrator';
+import { sql } from 'drizzle-orm';
+import { drizzle as drizzlePostgres } from 'drizzle-orm/postgres-js';
+import { migrate as migratePostgres } from 'drizzle-orm/postgres-js/migrator';
+import { readMigrationFiles } from 'drizzle-orm/migrator';
 import postgres from 'postgres';
 import { DEFAULT_DATABASE_URL } from './defaults.js';
+import type { DbHandle } from './client.js';
+
+interface PgliteExecutor {
+  exec(query: string): Promise<unknown>;
+}
+
+interface ExecuteRows<T> {
+  rows: T[];
+}
+
+function migrationsFolder(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '../drizzle');
+}
 
 export async function runMigrations(url?: string): Promise<void> {
   const connectionString = url ?? process.env['DATABASE_URL'] ?? DEFAULT_DATABASE_URL;
-  const sql = postgres(connectionString, { max: 1 });
-  const db = drizzle(sql);
-  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const sqlClient = postgres(connectionString, { max: 1 });
+  const db = drizzlePostgres(sqlClient);
   try {
-    await migrate(db, { migrationsFolder: resolve(__dirname, '../drizzle') });
+    // TODO: postgres-tier first-install also fails because (a) Drizzle wraps every
+    // migration in one transaction (breaks 0009's ALTER TYPE ADD VALUE → SET DEFAULT
+    // sequence) and (b) drizzle/meta/_journal.json has 0009 ordered before 0008,
+    // which the postgres-js migrator skips by `created_at < folderMillis`. The
+    // PGlite path below sidesteps both. A follow-up should either share the
+    // per-statement loop (see runPgliteMigrations) or fix the journal ordering.
+    await migratePostgres(db, { migrationsFolder: migrationsFolder() });
   } finally {
-    await sql.end();
+    await sqlClient.end();
+  }
+}
+
+// Apply Drizzle migrations against an embedded PGlite database.
+//
+// We don't reuse drizzle's pglite migrator because it wraps ALL migrations in
+// one outer transaction, which breaks Postgres' `check_safe_enum_use` rule —
+// e.g. migration 0009 does `ALTER TYPE ADD VALUE 'pending'` then references
+// `'pending'` as a default in the same tx. PGlite's `exec()` runs each
+// statement under the Simple Query protocol, autocommitting between them.
+//
+// We still write to the standard `drizzle.__drizzle_migrations` ledger so the
+// result is interoperable with `runMigrations()` on a postgres-backed deploy
+// (modulo the journal-ordering bug noted above).
+//
+// We skip-by-hash rather than skip-by-folderMillis (which is what Drizzle's
+// postgres-js migrator does). That's deliberate — out-of-order timestamps in
+// `_journal.json` won't silently drop migrations.
+//
+// Failure model: each statement autocommits, and the ledger row is written
+// only after all statements in a migration succeed. A crash mid-migration
+// leaves the prefix applied with no ledger entry, so the next boot will
+// replay those statements and fail loudly on "already exists". Recovery:
+// drop the partially-applied objects, or insert the migration's hash into
+// `drizzle.__drizzle_migrations` manually. The error log identifies which
+// statement of which migration was the culprit.
+export async function runPgliteMigrations(handle: DbHandle): Promise<void> {
+  const client = (handle.db as unknown as { $client?: PgliteExecutor }).$client;
+  if (!client || typeof client.exec !== 'function') {
+    throw new Error('runPgliteMigrations: handle.db is not backed by a PGlite client');
+  }
+
+  await client.exec('CREATE SCHEMA IF NOT EXISTS drizzle');
+  await client.exec(`
+    CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
+      id SERIAL PRIMARY KEY,
+      hash text NOT NULL,
+      created_at bigint
+    )
+  `);
+
+  const appliedRows = (await handle.db.execute(
+    sql`SELECT hash FROM drizzle.__drizzle_migrations`,
+  )) as unknown as ExecuteRows<{ hash: string }>;
+  const applied = new Set(appliedRows.rows.map((r) => r.hash));
+
+  const migrations = readMigrationFiles({ migrationsFolder: migrationsFolder() });
+  for (const migration of migrations) {
+    if (applied.has(migration.hash)) continue;
+
+    // Run each statement-breakpoint chunk in its own exec() call so PGlite
+    // commits between statements — this is what lets `ALTER TYPE ADD VALUE`
+    // become visible before a subsequent statement references the new value.
+    for (const [stmtIdx, stmt] of migration.sql.entries()) {
+      const trimmed = stmt.trim();
+      if (!trimmed) continue;
+      try {
+        await client.exec(trimmed);
+      } catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `runPgliteMigrations: migration hash=${migration.hash} statement #${stmtIdx} failed: ${cause}\n` +
+            `Statement: ${trimmed.slice(0, 200)}${trimmed.length > 200 ? '…' : ''}`,
+          { cause: err },
+        );
+      }
+    }
+    await handle.db.execute(
+      sql`INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES (${migration.hash}, ${migration.folderMillis})`,
+    );
   }
 }

packages/mosaic/framework/defaults/AGENTS.md

@@ -1,28 +1,24 @@
 # Mosaic Global Agent Contract
 
-Canonical file: `~/.config/mosaic/AGENTS.md`
+Canonical file: `~/.config/mosaic/AGENTS.md`. Mandatory behavior for all Mosaic agent runtimes.
 
-This file defines the mandatory behavior for all Mosaic agent runtimes.
+This is the THIN CORE — the launcher injects it (plus USER.md, the TOOLS index, and the runtime
+contract) into every session. It carries only what must be resident to avoid violating a gate.
+Depth lives in guides, read on demand (see Conditional Guide Loading).
 
-## MANDATORY Load Order (No Exceptions)
+## Session Start — Load Order
 
-Before responding to any user message, you MUST read these files in order:
+The core contract is ALREADY in your context (injected by `mosaic` launch). Do not re-read it.
+At session start, additionally:
 
-1. `~/.config/mosaic/SOUL.md`
-2. `~/.config/mosaic/USER.md`
-3. `~/.config/mosaic/STANDARDS.md`
-4. `~/.config/mosaic/AGENTS.md`
-5. `~/.config/mosaic/TOOLS.md`
-6. `~/.config/mosaic/guides/E2E-DELIVERY.md`
-7. `~/.config/mosaic/guides/MEMORY.md`
-8. Project-local `AGENTS.md` (if present)
-9. Runtime-specific reference:
-   - Pi: `~/.config/mosaic/runtime/pi/RUNTIME.md`
-   - Claude: `~/.config/mosaic/runtime/claude/RUNTIME.md`
-   - Codex: `~/.config/mosaic/runtime/codex/RUNTIME.md`
-   - OpenCode: `~/.config/mosaic/runtime/opencode/RUNTIME.md`
-
-If any required file is missing, you MUST stop and report the missing file.
+1. Read `~/.config/mosaic/SOUL.md` (agent identity — small, once).
+2. Read project-local `AGENTS.md` / `CLAUDE.md` if present.
+3. Read guides ONLY as triggered by the Conditional Guide Loading table below. Do NOT pre-load
+   guides you do not need — role-relevant detail is pulled on demand, not up front.
+4. When you begin implementation work, read `~/.config/mosaic/guides/E2E-DELIVERY.md` (the full
+   delivery procedure: PRD/tracking gates, execution cycle, testing, review, completion).
+5. `~/.config/mosaic/STANDARDS.md` is available for reference; load it only if the task requires
+   standards validation (do NOT halt if missing).
 
 ## CRITICAL HARD GATES (Read First)
 
@@ -37,56 +33,39 @@ If any required file is missing, you MUST stop and report the missing file.
 9. Do NOT stop at "PR created". Do NOT ask "should I merge?" Do NOT ask "should I close the issue?".
 10. Manual `docker build` / `docker push` for deployment is FORBIDDEN when CI/CD pipelines exist in the repository. CI is the ONLY canonical build path for container images.
 11. Before ANY build or deployment action, you MUST check for existing CI/CD pipeline configuration (`.woodpecker/`, `.woodpecker.yml`, `.github/workflows/`, etc.). If pipelines exist, use them — do not build locally.
-12. The mandatory load order and intake procedure are NOT conditional on perceived task complexity. A "simple" commit-push-deploy task has the same procedural requirements as a multi-file feature. Skipping intake because a task "seems simple" is the most common framework violation.
+12. The mandatory intake procedure is NOT conditional on perceived task complexity. A "simple" commit-push-deploy task has the same procedural requirements as a multi-file feature. Skipping intake because a task "seems simple" is the most common framework violation.
 
-## Non-Negotiable Operating Rules
+## Non-Negotiable Operating Rules (condensed — full detail in `guides/E2E-DELIVERY.md`)
 
-1. You MUST create and maintain a task-specific scratchpad for every non-trivial task.
-2. You MUST follow the end-to-end procedure in `E2E-DELIVERY.md`.
-3. You MUST execute this cycle for implementation work: `plan -> code -> test -> review -> remediate -> review -> commit -> push -> greenfield situational test -> repeat`.
-4. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist and be treated as the source of requirements.
-5. The main agent MUST prepare or update the PRD using user objectives, constraints, and available project context before implementation starts.
-6. In steered autonomy mode, the agent MUST make best-guess PRD decisions when needed, mark each with `ASSUMPTION:` and rationale, and continue without waiting for routine user approval.
-7. You MUST run baseline tests before claiming completion.
-8. Situational testing is the PRIMARY validation gate. You MUST run situational tests based on the change surface.
-9. TDD is risk-based and REQUIRED for bug fixes, security/auth/permission logic, and critical business logic/data mutations (see `~/.config/mosaic/guides/QA-TESTING.md`).
-10. If you modify source code, you MUST run an independent code review before completion.
-11. You MUST update required documentation for code/API/auth/infra changes per `~/.config/mosaic/guides/DOCUMENTATION.md`.
-12. You MUST provide verification evidence before completion claims.
-13. You MUST NOT use workarounds that bypass quality gates.
-14. You MUST NOT hardcode secrets.
-15. You MUST NOT use deprecated or unsupported dependencies.
-16. When a milestone is completed, you MUST create and push a release tag and publish a repository release.
-17. For every non-trivial implementation task, you MUST create or update `docs/TASKS.md` before coding and keep it current through completion.
-18. You MUST keep `docs/` root clean and place reports/artifacts in scoped folders per `~/.config/mosaic/guides/DOCUMENTATION.md`.
-19. For TypeScript codebases, DTO files are REQUIRED for module/API boundaries (`*.dto.ts`).
-20. You MUST honor user plan/token budgets: monitor estimated vs used tokens and adjust execution strategy to stay within limits.
-21. You MUST use trunk merge strategy: branch from `main`, merge to `main` via PR only, never push directly to `main`, and use squash merge only.
-22. You MUST own project execution end-to-end: planning, coding, testing, review, remediation, PR/repo operations, release/tag, and deployment when in scope.
-23. Human intervention is escalation-only; do not ask the human to perform routine coding, review, or repository management work.
-24. Deployment ownership is REQUIRED when deployment is in scope and target access is configured.
-25. For container deployments, you MUST use immutable image tags (`sha-*`, `vX.Y.Z-rc.N`) with digest-first promotion; `latest` is forbidden as a deployment reference.
-26. If an external git provider is available (Gitea/GitHub/GitLab), you MUST create or update issue(s) and link them in `docs/TASKS.md` before coding; if unavailable, use `TASKS:<id>` internal refs in `docs/TASKS.md`.
-27. For provider operations (issue/PR/milestone), you MUST detect platform first and use `~/.config/mosaic/tools/git/*.sh` wrappers before any raw provider CLI/API calls.
-28. Direct `gh`/`tea`/`glab` commands are forbidden as first choice when a Mosaic wrapper exists; use raw commands only as documented fallback.
-29. If the mission is orchestration-oriented (contains "orchestrate", issue/milestone coordination, or multi-task execution), you MUST load and follow `~/.config/mosaic/guides/ORCHESTRATOR.md` before taking action.
-30. At session start, you MUST declare the operating mode in your first response before any tool calls or implementation steps.
-31. For orchestration-oriented missions, the first line MUST be exactly: `Now initiating Orchestrator mode...`
-32. For non-orchestrator implementation missions, the first line MUST be exactly: `Now initiating Delivery mode...`
-33. For explicit review-only missions, the first line MUST be exactly: `Now initiating Review mode...`
-34. For source-code delivery through PR workflow, completion is forbidden until the PR is merged to `main`, CI/pipeline status is terminal green, and linked issue/internal task is closed.
-35. If merge/CI/issue-closure operations fail, you MUST report a blocker with the exact failed wrapper command and stop instead of declaring completion.
-36. Before push or PR merge, you MUST run CI queue guard and wait if the project has running/queued pipelines: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge`.
-37. When an active mission is detected at session start (MISSION-MANIFEST.md, TASKS.md, or scratchpads/ present), you MUST load `~/.config/mosaic/guides/ORCHESTRATOR-PROTOCOL.md` and follow the Session Resume Protocol before taking any action.
+- **Source of requirements:** `docs/PRD.md`/`docs/PRD.json` MUST exist before coding. In steered autonomy, make best-guess PRD decisions, mark each `ASSUMPTION:` with rationale, continue. (`guides/PRD.md`)
+- **Tracking:** create/maintain a scratchpad and `docs/TASKS.md` for every non-trivial task; keep current through completion.
+- **Execution cycle:** `plan → code → test → review → remediate → review → commit → push → greenfield situational test → repeat`. On failure, remediate and re-run from the failed step.
+- **Testing:** run baseline tests before any completion claim. Situational testing is the PRIMARY gate. Risk-based TDD is REQUIRED for bug fixes, security/auth/permission logic, and critical data mutations. (`guides/QA-TESTING.md`)
+- **Review:** if you modify source code, an independent code review MUST pass before completion. (`guides/CODE-REVIEW.md`)
+- **Evidence:** provide explicit verification evidence before any completion claim. Never use workarounds that bypass quality gates.
+- **Secrets & deps:** never hardcode secrets (`guides/VAULT-SECRETS.md`); never use deprecated/unsupported dependencies.
+- **Git strategy:** trunk-based — branch from `main`, merge to `main` via PR only (squash merge), never push directly to `main`.
+- **Provider work:** detect platform first, then use `~/.config/mosaic/tools/git/*.sh` wrappers before any raw `gh`/`tea`/`glab`. Create/link issue(s) in `docs/TASKS.md` before coding; if no provider, use `TASKS:<id>` refs.
+- **Deployment:** own it when in scope and access is configured. Use immutable image tags (`sha-*`, `vX.Y.Z-rc.N`) with digest-first promotion; `latest` is forbidden as a deployment reference. (`guides/INFRASTRUCTURE.md`)
+- **Release:** on milestone completion, create + push a release tag and publish a repository release.
+- **Documentation:** update required docs for code/API/auth/infra changes; keep `docs/` root clean (scoped folders). (`guides/DOCUMENTATION.md`)
+- **TypeScript:** DTO files (`*.dto.ts`) REQUIRED for module/API boundaries. (`guides/TYPESCRIPT.md`)
+- **Ownership:** own execution end-to-end (plan→deploy). Human intervention is escalation-only — do not ask the human to do routine coding, review, or repo work.
+- **Budget:** honor user plan/token budgets; adjust execution strategy to stay within limits.
 
 ## Mode Declaration Protocol (Hard Rule)
 
-At session start, declare one mode before any actions:
+At session start, declare exactly one mode as the first line, before any tool call or step:
 
 1. Orchestration mission: `Now initiating Orchestrator mode...`
 2. Implementation mission: `Now initiating Delivery mode...`
 3. Review-only mission: `Now initiating Review mode...`
 
+Orchestration-oriented = contains "orchestrate", issue/milestone coordination, or multi-task
+execution → also load `guides/ORCHESTRATOR.md` before acting. If an active mission is detected at
+session start (MISSION-MANIFEST.md, TASKS.md, or scratchpads/ present) → load
+`guides/ORCHESTRATOR-PROTOCOL.md` and follow the Session Resume Protocol before any action.
+
 ## Steered Autonomy Escalation Triggers
 
 Only interrupt the human when one of these is true:
@@ -97,136 +76,69 @@ Only interrupt the human when one of these is true:
 4. Legal/compliance/security constraints are unknown and materially affect delivery.
 5. Objectives are mutually conflicting and cannot be resolved from PRD, repo, or prior decisions.
 
-## Conditional Guide Loading
+## Conditional Guide Loading (role/task-driven — load only what the task needs)
 
-Load additional guides when the task requires them.
+| Task                                               | Guide                              |
+| -------------------------------------------------- | ---------------------------------- |
+| Project bootstrap                                  | `guides/BOOTSTRAP.md`              |
+| PRD creation / requirements                        | `guides/PRD.md`                    |
+| Orchestration flow                                 | `guides/ORCHESTRATOR.md`           |
+| Mission lifecycle / multi-session orchestration    | `guides/ORCHESTRATOR-PROTOCOL.md`  |
+| Orchestrator estimation heuristics                 | `guides/ORCHESTRATOR-LEARNINGS.md` |
+| Frontend changes                                   | `guides/FRONTEND.md`               |
+| Backend/API changes                                | `guides/BACKEND.md`                |
+| Auth/authorization                                 | `guides/AUTHENTICATION.md`         |
+| CI/CD changes                                      | `guides/CI-CD-PIPELINES.md`        |
+| Infrastructure/DevOps/deployment                   | `guides/INFRASTRUCTURE.md`         |
+| Code review work                                   | `guides/CODE-REVIEW.md`            |
+| TypeScript strict typing                           | `guides/TYPESCRIPT.md`             |
+| QA / test strategy                                 | `guides/QA-TESTING.md`             |
+| Documentation (any code/API/auth/infra change)     | `guides/DOCUMENTATION.md`          |
+| Secrets / vault usage                              | `guides/VAULT-SECRETS.md`          |
+| Tool/credential reference (service CLIs, wrappers) | `guides/TOOLS-REFERENCE.md`        |
+| Memory protocol (OpenBrain capture/recall)         | `guides/MEMORY.md`                 |
 
-| Task                                                    | Required Guide                                      |
-| ------------------------------------------------------- | --------------------------------------------------- |
-| Project bootstrap                                       | `~/.config/mosaic/guides/BOOTSTRAP.md`              |
-| PRD creation and requirements definition                | `~/.config/mosaic/guides/PRD.md`                    |
-| Orchestration flow                                      | `~/.config/mosaic/guides/ORCHESTRATOR.md`           |
-| Frontend changes                                        | `~/.config/mosaic/guides/FRONTEND.md`               |
-| Backend/API changes                                     | `~/.config/mosaic/guides/BACKEND.md`                |
-| Documentation changes or any code/API/auth/infra change | `~/.config/mosaic/guides/DOCUMENTATION.md`          |
-| Authentication/authorization                            | `~/.config/mosaic/guides/AUTHENTICATION.md`         |
-| CI/CD changes                                           | `~/.config/mosaic/guides/CI-CD-PIPELINES.md`        |
-| Infrastructure/DevOps                                   | `~/.config/mosaic/guides/INFRASTRUCTURE.md`         |
-| Code review work                                        | `~/.config/mosaic/guides/CODE-REVIEW.md`            |
-| TypeScript strict typing                                | `~/.config/mosaic/guides/TYPESCRIPT.md`             |
-| QA and test strategy                                    | `~/.config/mosaic/guides/QA-TESTING.md`             |
-| Secrets and vault usage                                 | `~/.config/mosaic/guides/VAULT-SECRETS.md`          |
-| Orchestrator estimation heuristics                      | `~/.config/mosaic/guides/ORCHESTRATOR-LEARNINGS.md` |
-| Mission lifecycle / multi-session orchestration         | `~/.config/mosaic/guides/ORCHESTRATOR-PROTOCOL.md`  |
+## Subagent Model Selection (Cost — Hard Rule)
 
-## Embedded Delivery Cycle (Hard Rule)
+Select the cheapest model capable of the task; do NOT default to the most expensive. Omitting the
+tier defaults to the parent (usually opus) and wastes budget.
 
-- Implementation work MUST follow the embedded execution cycle:
-  - `plan -> code -> test -> review -> remediate -> review -> commit -> push -> greenfield situational test -> repeat`
-- If a step fails, you MUST remediate and re-run from the relevant step before proceeding.
+- **haiku** — search/grep/glob, codebase exploration, status/health checks, one-line mechanical fixes.
+- **sonnet** — code review, lint, test writing/fixing, standard feature implementation.
+- **opus** — complex architecture / multi-file refactors, security/auth logic, ambiguous design decisions.
 
-## Sequential-Thinking MCP (Hard Requirement)
-
-- `sequential-thinking` MCP server is REQUIRED for Mosaic operation.
-- Installation and configuration are managed by Mosaic bootstrap and runtime linking.
-- If sequential-thinking is unavailable, you MUST report the failure and stop planning-intensive execution.
-
-## Subagent Model Selection (Cost Optimization — Hard Rule)
-
-When delegating work to subagents, you MUST select the cheapest model capable of completing the task. Do NOT default to the most expensive model for every delegation.
-
-| Task Type                                     | Model Tier | Rationale                                               |
-| --------------------------------------------- | ---------- | ------------------------------------------------------- |
-| File search, grep, glob, codebase exploration | **haiku**  | Read-only, pattern matching, no reasoning depth needed  |
-| Status checks, health monitoring, heartbeat   | **haiku**  | Structured API calls, pass/fail output                  |
-| Simple code fixes (typos, rename, one-liner)  | **haiku**  | Minimal reasoning, mechanical changes                   |
-| Code review, lint, style checks               | **sonnet** | Needs judgment but not deep architectural reasoning     |
-| Test writing, test fixes                      | **sonnet** | Pattern-based, moderate complexity                      |
-| Standard feature implementation               | **sonnet** | Good balance of capability and cost for most coding     |
-| Complex architecture, multi-file refactors    | **opus**   | Requires deep reasoning, large context, design judgment |
-| Security review, auth logic                   | **opus**   | High-stakes reasoning where mistakes are costly         |
-| Ambiguous requirements, design decisions      | **opus**   | Needs nuanced judgment and tradeoff analysis            |
-
-**Decision rule**: Start with the cheapest viable tier. Only escalate if the task genuinely requires deeper reasoning — not as a safety default. Most coding tasks are sonnet-tier. Reserve opus for work where wrong answers are expensive.
-
-**Runtime-specific syntax**: See the runtime reference for how to specify model tier when spawning subagents (e.g., Claude Code Task tool `model` parameter).
+Start cheapest; escalate only when the task genuinely needs deeper reasoning. Runtime syntax for
+specifying tier is in the runtime contract.
 
 ## Superpowers Enforcement (Hard Rule)
 
-Mosaic provides capabilities beyond basic code editing: **skills**, **hooks**, **MCP tools**, and **plugins**. These are not optional extras — they are force multipliers that agents MUST actively use when applicable. Under-utilization of superpowers is a framework violation.
+Skills, hooks, MCP tools, and plugins are force multipliers you MUST use when applicable;
+under-utilization is a framework violation.
 
-### Skills
+- **Skills:** before implementation, scan `~/.config/mosaic/skills/` and load any matching the task
+  domain (e.g. `nestjs-best-practices` for NestJS). Include skill loading in worker kickstarts. Do
+  not load unrelated skills.
+- **Hooks:** never bypass or suppress hook output; treat hook failures like failing tests and fix
+  them. If a hook is wrong, report it as a framework issue — do not work around it.
+- **MCP:** sequential-thinking is REQUIRED for planning/architecture/multi-step reasoning. OpenBrain
+  (`capture`/`search`/`recent`) is the cross-agent memory layer — search at session start, capture
+  what you learn. Use web/browser/research MCP tools instead of asking the user to look things up.
+- **Plugins:** use code-review / pr-review / architecture plugins proactively after significant
+  changes and before opening a PR — do not wait to be asked.
+- **Self-evolution:** capture recurring patterns (`framework-improvement`), missing tooling
+  (`tooling-gap`), and value-less friction (`framework-friction`) to OpenBrain.
 
-Skills are domain-specific instruction sets in `~/.config/mosaic/skills/` that encode best practices, patterns, and guardrails. They are loaded into agents via the runtime's skill mechanism (e.g., Claude Code slash commands, Pi `--skill` flag).
+## Other Hard Rules
 
-**Rules:**
+- **Sequential-thinking MCP** is REQUIRED. If unavailable, report the failure and stop planning-intensive execution.
+- **Missing core file:** if `AGENTS.md`, `SOUL.md`, or the runtime contract is missing, stop and report it.
 
-1. Before starting implementation, scan available skills (`ls ~/.config/mosaic/skills/`) and load any that match the task domain.
-2. When a skill exists for the technology being used (e.g., `nestjs-best-practices` for NestJS work), you MUST load it.
-3. When spawning workers, include skill loading in the kickstart prompt.
-4. If you complete a task without loading a relevant available skill, that is a quality gap.
+## Session Closure
 
-### Hooks
-
-Hooks provide automated quality gates (lint, format, typecheck) that fire on file edits. They are configured in the runtime settings and run automatically.
-
-**Rules:**
-
-1. Do NOT bypass or suppress hook output. If a hook reports errors, fix them before proceeding.
-2. Hook failures are immediate feedback — treat them like failing tests.
-3. If a hook is consistently failing on valid code, report it as a framework issue rather than working around it.
-
-### MCP Tools
-
-MCP servers extend agent capabilities with external integrations (sequential-thinking, web search, memory, browser automation, etc.). Available MCP tools are listed at session start.
-
-**Rules:**
-
-1. **sequential-thinking** is REQUIRED for planning, architecture, and multi-step reasoning. Use it — do not skip structured thinking for complex decisions.
-2. **OpenBrain** (`capture`, `search`, `recent`) is the cross-agent memory layer. Capture discoveries and search for prior context at session start.
-3. When a task involves web research, browser testing, or external data, use the available MCP tools (web-search, chrome-devtools, web-reader) rather than asking the user to look things up.
-4. Check available MCP tools at session start and use them proactively throughout the session.
-
-### Plugins (Runtime-Specific)
-
-Runtime plugins (e.g., Claude Code's `feature-dev`, `pr-review-toolkit`, `code-review`) provide specialized agent capabilities like code review, architecture analysis, and test coverage analysis.
-
-**Rules:**
-
-1. After completing a significant code change, use code review plugins proactively — do not wait for the user to ask.
-2. Before creating a PR, use PR review plugins to catch issues early.
-3. When designing architecture, use planning/architecture plugins for structured analysis.
-
-### Self-Evolution
-
-The Mosaic framework should improve over time based on usage patterns:
-
-1. When you discover a recurring pattern that should be codified, capture it to OpenBrain with `type: "framework-improvement"`.
-2. When a hook, skill, or tool is missing for a common task, capture the gap to OpenBrain with `type: "tooling-gap"`.
-3. When a framework rule causes friction without adding value, capture the observation to OpenBrain with `type: "framework-friction"`.
-
-These captures feed the framework's continuous improvement cycle.
-
-## Skills Policy
-
-- Load skills that match the active task domain before starting implementation.
-- Do not load unrelated skills.
-- Follow skill trigger rules from the active runtime instruction layer.
-- Actively check `~/.config/mosaic/skills/` for applicable skills rather than passively waiting for them to be mentioned.
-
-## Session Closure Requirement
-
-Before closing any implementation task:
-
-1. Confirm required tests passed.
-2. Confirm situational tests passed (primary gate).
-3. Confirm implementation is aligned to the active `docs/PRD.md` or `docs/PRD.json`.
-4. Confirm acceptance criteria are mapped to verification evidence.
-5. If source code changed, confirm independent code review passed.
-6. Confirm required documentation updates were completed and reviewed.
-7. Update scratchpad with decisions, results, and open risks.
-8. Provide explicit completion evidence.
-9. If source code changed and external provider is available, confirm merged PR number and merge commit on `main`.
-10. Confirm CI/pipeline status is terminal green for the merged change (or merged PR head when equivalent).
-11. Confirm linked issue is closed (or internal `docs/TASKS.md` equivalent is closed when no provider exists).
-12. If any of items 9-11 are blocked by access/tooling failure, return `blocked` status with exact failed wrapper command and do not claim completion.
+Before closing an implementation task, confirm: required + situational tests passed (primary gate);
+aligned to `docs/PRD.md`; acceptance criteria mapped to evidence; independent code review passed (if
+code changed); required docs updated; scratchpad updated with decisions/results/risks; explicit
+completion evidence provided. For PR-workflow delivery: confirm merged PR number + merge commit on
+`main`, terminal-green CI, and linked issue closed (or `docs/TASKS.md` equivalent). If any of those
+are blocked by access/tooling failure, return `blocked` with the exact failed wrapper command — do
+not claim completion. Full checklist: `guides/E2E-DELIVERY.md`.

packages/mosaic/framework/defaults/STANDARDS.md

@@ -27,6 +27,16 @@ Master/slave model:
 - Do not perform destructive git/file actions without explicit instruction.
 - Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.
 
+### Secrets handling (HARD RULE)
+
+- Vault is the canonical source-of-truth for every secret in every environment. No exceptions.
+- For k8s workloads, the default read path is **External Secrets Operator → k8s Secret → env var** (`secretKeyRef`). The app reads standard env vars; no Vault client in app code.
+- Direct-Vault clients in application code are **opt-in only**, justified per-app by a documented dynamic-secrets requirement (e.g., DB rotation, AWS STS). Default to ESO. Document the justification in the project's README under "Secrets architecture".
+- `${VAR:-default}` fallback syntax in any deployment configuration (compose, k8s manifests, Helm values, env files committed to git) is **forbidden** for required values. Use `${VAR:?VAR is required}` to fast-fail. Defaults are allowed only for true conveniences (e.g. `${PORT:-3000}`) and MUST be tagged `# safe-default: <reason>` so a reviewer can confirm the intent.
+- `.env` files in production deployment paths are **forbidden**. `.env.example` and `.env` in local-dev paths are fine.
+- App startup MUST validate required secrets against a schema (zod / pydantic / equivalent) and exit non-zero on missing required values. Never run with defaulted weak fallbacks.
+- New apps: bootstrap checklist (see `~/.config/mosaic/guides/BOOTSTRAP.md`) MUST include Vault path provisioning + `ExternalSecret` manifest + README declaring the Vault path and required keys.
+
 ## Session Lifecycle Contract
 
 - Start: `scripts/agent/session-start.sh`

packages/mosaic/framework/defaults/TOOLS.md

@@ -1,257 +1,58 @@
-# Machine-Level Tool Reference
+# Machine Tools — Index
 
-Centralized reference for tools, credentials, and CLI patterns available across all projects.
+Tool suites live at `~/.config/mosaic/tools/<suite>/`. This is the index only.
+**Full CLI signatures, flags, and examples: `~/.config/mosaic/guides/TOOLS-REFERENCE.md`** —
+read it (or the relevant service guide) when your task actually touches that service.
 Project-specific tooling belongs in the project's `AGENTS.md`, not here.
 
-All tool suites are located at `~/.config/mosaic/tools/`.
-
-## Tool Suites
-
-### Git Wrappers (Use First)
-
-Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
-
-```bash
-# Issues
-~/.config/mosaic/tools/git/issue-create.sh
-~/.config/mosaic/tools/git/issue-close.sh
-
-# PRs
-~/.config/mosaic/tools/git/pr-create.sh
-~/.config/mosaic/tools/git/pr-merge.sh
-
-# Milestones
-~/.config/mosaic/tools/git/milestone-create.sh
-
-# CI queue guard (required before push/merge)
-~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
-```
-
-### Code Review (Codex)
-
-```bash
-~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
-~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
-```
-
-### Infrastructure — Portainer
-
-```bash
-~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
-~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name>
-~/.config/mosaic/tools/portainer/stack-list.sh
-~/.config/mosaic/tools/portainer/endpoint-list.sh
-```
-
-### Infrastructure — Coolify (DEPRECATED)
-
-> Coolify has been superseded by Portainer Docker Swarm in this stack.
-> Tools remain for reference but should not be used for new deployments.
-
-```bash
-# DEPRECATED — do not use for new deployments
-~/.config/mosaic/tools/coolify/project-list.sh
-~/.config/mosaic/tools/coolify/service-list.sh
-~/.config/mosaic/tools/coolify/service-status.sh -u <uuid>
-~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>
-~/.config/mosaic/tools/coolify/env-set.sh -u <uuid> -k KEY -v VALUE
-```
-
-### Identity — Authentik
-
-```bash
-~/.config/mosaic/tools/authentik/user-list.sh
-~/.config/mosaic/tools/authentik/user-create.sh -u <username> -n <name> -e <email>
-~/.config/mosaic/tools/authentik/group-list.sh
-~/.config/mosaic/tools/authentik/app-list.sh
-~/.config/mosaic/tools/authentik/flow-list.sh
-~/.config/mosaic/tools/authentik/admin-status.sh
-```
-
-### CI/CD — Woodpecker
-
-Multi-instance support: `-a <instance>` selects a named instance. Omit `-a` to use the default from `woodpecker.default` in credentials.json.
-
-| Instance           | URL                | Serves                             |
-| ------------------ | ------------------ | ---------------------------------- |
-| `mosaic` (default) | ci.mosaicstack.dev | Mosaic repos (git.mosaicstack.dev) |
-| `usc`              | ci.uscllc.com      | USC repos (git.uscllc.com)         |
-
-```bash
-# List recent pipelines
-~/.config/mosaic/tools/woodpecker/pipeline-list.sh [-r owner/repo] [-a instance]
-
-# Check latest or specific pipeline status
-~/.config/mosaic/tools/woodpecker/pipeline-status.sh [-r owner/repo] [-n number] [-a instance]
-
-# Trigger a build
-~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh [-r owner/repo] [-b branch] [-a instance]
-```
-
-Instance selection rule: match `-a` to the git remote host of the target repo. If the repo is on `git.uscllc.com`, use `-a usc`. If on `git.mosaicstack.dev`, use `-a mosaic` (or omit, since it's the default).
-
-### DNS — Cloudflare
-
-Multi-instance support: `-a <instance>` selects a named instance (e.g. `personal`, `work`). Omit `-a` to use the default from `cloudflare.default` in credentials.json.
-
-```bash
-# List zones (domains)
-~/.config/mosaic/tools/cloudflare/zone-list.sh [-a instance]
-
-# List DNS records (zone by name or ID)
-~/.config/mosaic/tools/cloudflare/record-list.sh -z <zone> [-a instance] [-t type] [-n name]
-
-# Create DNS record
-~/.config/mosaic/tools/cloudflare/record-create.sh -z <zone> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl] [-P priority]
-
-# Update DNS record
-~/.config/mosaic/tools/cloudflare/record-update.sh -z <zone> -r <record-id> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl]
-
-# Delete DNS record
-~/.config/mosaic/tools/cloudflare/record-delete.sh -z <zone> -r <record-id> [-a instance]
-```
-
-### IT Service — GLPI
-
-```bash
-~/.config/mosaic/tools/glpi/ticket-list.sh
-~/.config/mosaic/tools/glpi/ticket-create.sh -t <title> -c <content>
-~/.config/mosaic/tools/glpi/computer-list.sh
-~/.config/mosaic/tools/glpi/user-list.sh
-```
-
-### Health Check
-
-```bash
-# Check all configured services
-~/.config/mosaic/tools/health/stack-health.sh
-
-# Check a specific service
-~/.config/mosaic/tools/health/stack-health.sh -s portainer
-
-# JSON output for automation
-~/.config/mosaic/tools/health/stack-health.sh -f json
-```
-
-### Shared Credential Loader
-
-```bash
-# Source in any script to load service credentials
-source ~/.config/mosaic/tools/_lib/credentials.sh
-load_credentials <service-name>
-# Supported: portainer, coolify, authentik, glpi, github, gitea-mosaicstack, gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain
-```
-
-### OpenBrain — Semantic Memory (PRIMARY)
-
-Self-hosted semantic brain backed by pgvector. Primary shared memory layer for all agents across all sessions and harnesses. Stores and retrieves decisions, context, and observations via semantic search.
-
-**MANDATORY jarvis-brain rule:** When working in `~/src/jarvis-brain`, NEVER capture project data, meeting notes, status updates, timeline decisions, or task completions to OpenBrain. The flat files (`data/projects/*.json`, `data/tasks/*.json`) are the SSOT — use `tools/brain.py` and direct JSON edits. OpenBrain is for agent meta-observations ONLY (tooling gotchas, framework learnings, cross-project patterns). Violating this creates duplicate, divergent data.
-
-**Credentials:** `load_credentials openbrain` → exports `OPENBRAIN_URL`, `OPENBRAIN_TOKEN`
-
-Configure in your credentials.json:
-
-```json
-"openbrain": {
-  "url": "https://<your-openbrain-host>",
-  "api_key": "<your-api-key>"
-}
-```
-
-**REST API** (any language, any harness):
-
-```bash
-source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials openbrain
-
-# Search by meaning
-curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
-  -d '{"query": "your search", "limit": 5}' "$OPENBRAIN_URL/v1/search"
-
-# Capture a thought
-curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
-  -d '{"content": "...", "source": "agent-name", "metadata": {}}' "$OPENBRAIN_URL/v1/thoughts"
-
-# Recent activity
-curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/recent?limit=5"
-
-# Stats
-curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/stats"
-```
-
-**Python client** (if jarvis-brain is available on PYTHONPATH):
-
-```bash
-python tools/openbrain_client.py search "topic"
-python tools/openbrain_client.py capture "decision or observation" --source agent-name
-python tools/openbrain_client.py recent --limit 5
-python tools/openbrain_client.py stats
-```
-
-**MCP (Claude Code sessions):** When connected, `mcp__openbrain__capture/search/recent/stats` tools are available natively — prefer those over CLI when in a Claude session.
-
-**Rule: capture when you LEARN something. Never when you DO something.**
-
-| Trigger                                   | Action                                    | Retention             |
-| ----------------------------------------- | ----------------------------------------- | --------------------- |
-| Session start                             | `search` + `recent` to load prior context | —                     |
-| Architectural or tooling decision made    | Capture with rationale                    | `long` or `permanent` |
-| Gotcha or non-obvious behavior discovered | Capture immediately                       | `medium`              |
-| User preference stated or confirmed       | Capture                                   | `permanent`           |
-| Cross-project pattern identified          | Capture                                   | `permanent`           |
-| Prior decision superseded                 | UPDATE existing thought                   | (keep tier)           |
-
-**Never capture:** task started, commit pushed, PR opened, test results, file edits, CI status.
-
-Full protocol and cleanup tools: `~/.config/mosaic/guides/MEMORY.md`
-Smart capture wrapper (enforces schema + dedup): `~/.config/mosaic/tools/openbrain/capture.sh`
-
-### Excalidraw — Diagram Export (MCP)
-
-Headless `.excalidraw` → SVG export via `@excalidraw/excalidraw`. Available as MCP tools in Claude Code sessions.
-
-**MCP tools (when connected):**
-
-| Tool                                      | Input                                         | Output                                               |
-| ----------------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
-| `mcp__excalidraw__excalidraw_to_svg`      | `elements` JSON string + optional `app_state` | SVG string                                           |
-| `mcp__excalidraw__excalidraw_file_to_svg` | `file_path` to `.excalidraw`                  | SVG string + writes `.svg` alongside                 |
-| `mcp__excalidraw__list_diagrams`          | (none)                                        | Available templates (requires `EXCALIDRAW_GEN_PATH`) |
-| `mcp__excalidraw__generate_diagram`       | `name`, optional `output_path`                | Path to generated `.excalidraw`                      |
-| `mcp__excalidraw__generate_and_export`    | `name`, optional `output_path`                | Paths to `.excalidraw` and `.svg`                    |
-
-**Diagram generation** (`list_diagrams`, `generate_diagram`, `generate_and_export`) requires `EXCALIDRAW_GEN_PATH` env var pointing to `excalidraw_gen.py`. Set in environment or shell profile:
-
-```bash
-export EXCALIDRAW_GEN_PATH="$HOME/src/jarvis-brain/tools/excalidraw_export/excalidraw_gen.py"
-```
-
-**Manual registration:**
-
-```bash
-mosaic-ensure-excalidraw           # install deps + register with Claude
-mosaic-ensure-excalidraw --check   # verify registration
-```
-
-## Git Providers
-
-| Instance                      | URL | CLI | Purpose |
-| ----------------------------- | --- | --- | ------- |
-| (add your git providers here) |     |     |         |
+## Suites (use wrappers first)
+
+| Suite      | Path                                             | Purpose                                                                  |
+| ---------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
+| git        | `tools/git/*.sh`                                 | issues, PRs, milestones, CI queue guard (platform-auto-detected)         |
+| woodpecker | `tools/woodpecker/*.sh`                          | CI pipelines (`-a mosaic`\|`usc`; match git remote host)                 |
+| portainer  | `tools/portainer/*.sh`                           | Docker Swarm stacks (status/redeploy/list)                               |
+| coolify    | `tools/coolify/*.sh`                             | **DEPRECATED** — superseded by Portainer; do not use for new deployments |
+| authentik  | `tools/authentik/*.sh`                           | identity (users/groups/apps/flows)                                       |
+| cloudflare | `tools/cloudflare/*.sh`                          | DNS (zones/records; `-a` instance)                                       |
+| glpi       | `tools/glpi/*.sh`                                | IT tickets/computers/users                                               |
+| health     | `tools/health/stack-health.sh`                   | service health checks                                                    |
+| codex      | `tools/codex/*.sh`                               | code/security review (`--uncommitted`)                                   |
+| openbrain  | `tools/openbrain/*`, `tools/openbrain_client.py` | semantic memory (see below)                                              |
+| excalidraw | MCP `mcp__excalidraw__*`                         | diagram export/generation                                                |
+
+Git wrappers are MANDATORY-first for issue/PR/milestone ops (see AGENTS.md hard gates 6–8).
+Queue guard before push/merge: `tools/git/ci-queue-wait.sh --purpose push|merge`.
 
 ## Credentials
 
-**Location:** (configure your credential file path)
-**Loader:** `source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>`
+`source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>`
+Supported: portainer, coolify (deprecated), authentik, glpi, github, gitea-mosaicstack,
+gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain. Never expose or commit values.
 
-**Never expose actual values. Never commit credential files.**
+## OpenBrain — Semantic Memory (PRIMARY) — capture when you LEARN, never when you DO
 
-## CLI Gotchas
+Primary cross-agent memory (pgvector). Capture decisions/gotchas/preferences/patterns; never task
+starts, commits, PRs, test results, or file edits. At session start, `search` + `recent` to load
+prior context. MCP (`mcp__openbrain__capture/search/recent/stats`) preferred when connected; else
+REST/`tools/openbrain_client.py`. Full protocol: `guides/MEMORY.md`.
 
-(Add platform-specific CLI gotchas as you discover them.)
+**MANDATORY jarvis-brain rule:** when working in `~/src/jarvis-brain`, NEVER capture project data,
+meeting notes, status, timelines, or task completions to OpenBrain — the flat files
+(`data/projects/*.json`, `data/tasks/*.json`) are the SSOT (use `tools/brain.py` + direct JSON
+edits). OpenBrain there is for agent meta-observations ONLY (tooling gotchas, framework learnings,
+cross-project patterns). Violating this creates duplicate, divergent data.
+
+## Git Providers
+
+| Host                | Instance         | CI                               |
+| ------------------- | ---------------- | -------------------------------- |
+| git.mosaicstack.dev | mosaic (default) | ci.mosaicstack.dev (`-a mosaic`) |
+| git.uscllc.com      | usc              | ci.uscllc.com (`-a usc`)         |
+
+Match Woodpecker `-a` and credential instance to the target repo's git remote host.
 
 ## Safety Defaults
 
-- Prefer `trash` over `rm` when available — recoverable beats gone forever
-- Never run destructive commands without explicit instruction
-- Write it down — "mental notes" don't survive session restarts; files do
+- Prefer `trash` over `rm` when available — recoverable beats gone forever.
+- Never run destructive commands without explicit instruction.

packages/mosaic/framework/guides/BOOTSTRAP.md

@@ -453,6 +453,26 @@ Initialize standard labels and the first pre-MVP milestone:
 
 ---
 
+## Secrets Bootstrap (Required for Every New App)
+
+Every new application MUST complete the following secrets bootstrap before deploying to any non-local environment. This is a hard gate — deployment without completed secrets bootstrap is forbidden.
+
+### Secrets bootstrap checklist
+
+- [ ] Vault path created: `vault kv put secret/k3s/<app>/ ...` with all required secret fields
+- [ ] Required secrets listed in project README under a "Secrets architecture" section, including:
+  - Vault path(s) used
+  - All required secret keys and their purpose
+  - Whether the app uses ESO bridge (default) or Direct-Vault (opt-in, with justification)
+- [ ] `external-secret.yaml` manifest committed to repo's `deploy/` or `k8s/` directory
+- [ ] Deployment YAML references the synced k8s Secret via `secretKeyRef` (not raw env vars or `.env` files)
+- [ ] App startup has schema-based validation for all required env vars (zod / pydantic / envconfig equivalent) that exits non-zero on missing required values
+- [ ] Direct-Vault opt-in (if applicable): justification documented in README + AppRole provisioned + bootstrap credentials stored in Vault and synced via a separate `ExternalSecret`
+
+See `~/.config/mosaic/guides/VAULT-SECRETS.md` for full worked examples of the ESO bridge pattern, the Direct-Vault opt-in pattern, and the forbidden antipatterns.
+
+---
+
 ## Checklist
 
 After bootstrapping, verify:

packages/mosaic/framework/guides/TOOLS-REFERENCE.md

@@ -0,0 +1,257 @@
+# Machine-Level Tool Reference
+
+Centralized reference for tools, credentials, and CLI patterns available across all projects.
+Project-specific tooling belongs in the project's `AGENTS.md`, not here.
+
+All tool suites are located at `~/.config/mosaic/tools/`.
+
+## Tool Suites
+
+### Git Wrappers (Use First)
+
+Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
+
+```bash
+# Issues
+~/.config/mosaic/tools/git/issue-create.sh
+~/.config/mosaic/tools/git/issue-close.sh
+
+# PRs
+~/.config/mosaic/tools/git/pr-create.sh
+~/.config/mosaic/tools/git/pr-merge.sh
+
+# Milestones
+~/.config/mosaic/tools/git/milestone-create.sh
+
+# CI queue guard (required before push/merge)
+~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
+```
+
+### Code Review (Codex)
+
+```bash
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
+```
+
+### Infrastructure — Portainer
+
+```bash
+~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
+~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name>
+~/.config/mosaic/tools/portainer/stack-list.sh
+~/.config/mosaic/tools/portainer/endpoint-list.sh
+```
+
+### Infrastructure — Coolify (DEPRECATED)
+
+> Coolify has been superseded by Portainer Docker Swarm in this stack.
+> Tools remain for reference but should not be used for new deployments.
+
+```bash
+# DEPRECATED — do not use for new deployments
+~/.config/mosaic/tools/coolify/project-list.sh
+~/.config/mosaic/tools/coolify/service-list.sh
+~/.config/mosaic/tools/coolify/service-status.sh -u <uuid>
+~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>
+~/.config/mosaic/tools/coolify/env-set.sh -u <uuid> -k KEY -v VALUE
+```
+
+### Identity — Authentik
+
+```bash
+~/.config/mosaic/tools/authentik/user-list.sh
+~/.config/mosaic/tools/authentik/user-create.sh -u <username> -n <name> -e <email>
+~/.config/mosaic/tools/authentik/group-list.sh
+~/.config/mosaic/tools/authentik/app-list.sh
+~/.config/mosaic/tools/authentik/flow-list.sh
+~/.config/mosaic/tools/authentik/admin-status.sh
+```
+
+### CI/CD — Woodpecker
+
+Multi-instance support: `-a <instance>` selects a named instance. Omit `-a` to use the default from `woodpecker.default` in credentials.json.
+
+| Instance           | URL                | Serves                             |
+| ------------------ | ------------------ | ---------------------------------- |
+| `mosaic` (default) | ci.mosaicstack.dev | Mosaic repos (git.mosaicstack.dev) |
+| `usc`              | ci.uscllc.com      | USC repos (git.uscllc.com)         |
+
+```bash
+# List recent pipelines
+~/.config/mosaic/tools/woodpecker/pipeline-list.sh [-r owner/repo] [-a instance]
+
+# Check latest or specific pipeline status
+~/.config/mosaic/tools/woodpecker/pipeline-status.sh [-r owner/repo] [-n number] [-a instance]
+
+# Trigger a build
+~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh [-r owner/repo] [-b branch] [-a instance]
+```
+
+Instance selection rule: match `-a` to the git remote host of the target repo. If the repo is on `git.uscllc.com`, use `-a usc`. If on `git.mosaicstack.dev`, use `-a mosaic` (or omit, since it's the default).
+
+### DNS — Cloudflare
+
+Multi-instance support: `-a <instance>` selects a named instance (e.g. `personal`, `work`). Omit `-a` to use the default from `cloudflare.default` in credentials.json.
+
+```bash
+# List zones (domains)
+~/.config/mosaic/tools/cloudflare/zone-list.sh [-a instance]
+
+# List DNS records (zone by name or ID)
+~/.config/mosaic/tools/cloudflare/record-list.sh -z <zone> [-a instance] [-t type] [-n name]
+
+# Create DNS record
+~/.config/mosaic/tools/cloudflare/record-create.sh -z <zone> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl] [-P priority]
+
+# Update DNS record
+~/.config/mosaic/tools/cloudflare/record-update.sh -z <zone> -r <record-id> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl]
+
+# Delete DNS record
+~/.config/mosaic/tools/cloudflare/record-delete.sh -z <zone> -r <record-id> [-a instance]
+```
+
+### IT Service — GLPI
+
+```bash
+~/.config/mosaic/tools/glpi/ticket-list.sh
+~/.config/mosaic/tools/glpi/ticket-create.sh -t <title> -c <content>
+~/.config/mosaic/tools/glpi/computer-list.sh
+~/.config/mosaic/tools/glpi/user-list.sh
+```
+
+### Health Check
+
+```bash
+# Check all configured services
+~/.config/mosaic/tools/health/stack-health.sh
+
+# Check a specific service
+~/.config/mosaic/tools/health/stack-health.sh -s portainer
+
+# JSON output for automation
+~/.config/mosaic/tools/health/stack-health.sh -f json
+```
+
+### Shared Credential Loader
+
+```bash
+# Source in any script to load service credentials
+source ~/.config/mosaic/tools/_lib/credentials.sh
+load_credentials <service-name>
+# Supported: portainer, coolify, authentik, glpi, github, gitea-mosaicstack, gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain
+```
+
+### OpenBrain — Semantic Memory (PRIMARY)
+
+Self-hosted semantic brain backed by pgvector. Primary shared memory layer for all agents across all sessions and harnesses. Stores and retrieves decisions, context, and observations via semantic search.
+
+**MANDATORY jarvis-brain rule:** When working in `~/src/jarvis-brain`, NEVER capture project data, meeting notes, status updates, timeline decisions, or task completions to OpenBrain. The flat files (`data/projects/*.json`, `data/tasks/*.json`) are the SSOT — use `tools/brain.py` and direct JSON edits. OpenBrain is for agent meta-observations ONLY (tooling gotchas, framework learnings, cross-project patterns). Violating this creates duplicate, divergent data.
+
+**Credentials:** `load_credentials openbrain` → exports `OPENBRAIN_URL`, `OPENBRAIN_TOKEN`
+
+Configure in your credentials.json:
+
+```json
+"openbrain": {
+  "url": "https://<your-openbrain-host>",
+  "api_key": "<your-api-key>"
+}
+```
+
+**REST API** (any language, any harness):
+
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials openbrain
+
+# Search by meaning
+curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"query": "your search", "limit": 5}' "$OPENBRAIN_URL/v1/search"
+
+# Capture a thought
+curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"content": "...", "source": "agent-name", "metadata": {}}' "$OPENBRAIN_URL/v1/thoughts"
+
+# Recent activity
+curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/recent?limit=5"
+
+# Stats
+curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/stats"
+```
+
+**Python client** (if jarvis-brain is available on PYTHONPATH):
+
+```bash
+python tools/openbrain_client.py search "topic"
+python tools/openbrain_client.py capture "decision or observation" --source agent-name
+python tools/openbrain_client.py recent --limit 5
+python tools/openbrain_client.py stats
+```
+
+**MCP (Claude Code sessions):** When connected, `mcp__openbrain__capture/search/recent/stats` tools are available natively — prefer those over CLI when in a Claude session.
+
+**Rule: capture when you LEARN something. Never when you DO something.**
+
+| Trigger                                   | Action                                    | Retention             |
+| ----------------------------------------- | ----------------------------------------- | --------------------- |
+| Session start                             | `search` + `recent` to load prior context | —                     |
+| Architectural or tooling decision made    | Capture with rationale                    | `long` or `permanent` |
+| Gotcha or non-obvious behavior discovered | Capture immediately                       | `medium`              |
+| User preference stated or confirmed       | Capture                                   | `permanent`           |
+| Cross-project pattern identified          | Capture                                   | `permanent`           |
+| Prior decision superseded                 | UPDATE existing thought                   | (keep tier)           |
+
+**Never capture:** task started, commit pushed, PR opened, test results, file edits, CI status.
+
+Full protocol and cleanup tools: `~/.config/mosaic/guides/MEMORY.md`
+Smart capture wrapper (enforces schema + dedup): `~/.config/mosaic/tools/openbrain/capture.sh`
+
+### Excalidraw — Diagram Export (MCP)
+
+Headless `.excalidraw` → SVG export via `@excalidraw/excalidraw`. Available as MCP tools in Claude Code sessions.
+
+**MCP tools (when connected):**
+
+| Tool                                      | Input                                         | Output                                               |
+| ----------------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
+| `mcp__excalidraw__excalidraw_to_svg`      | `elements` JSON string + optional `app_state` | SVG string                                           |
+| `mcp__excalidraw__excalidraw_file_to_svg` | `file_path` to `.excalidraw`                  | SVG string + writes `.svg` alongside                 |
+| `mcp__excalidraw__list_diagrams`          | (none)                                        | Available templates (requires `EXCALIDRAW_GEN_PATH`) |
+| `mcp__excalidraw__generate_diagram`       | `name`, optional `output_path`                | Path to generated `.excalidraw`                      |
+| `mcp__excalidraw__generate_and_export`    | `name`, optional `output_path`                | Paths to `.excalidraw` and `.svg`                    |
+
+**Diagram generation** (`list_diagrams`, `generate_diagram`, `generate_and_export`) requires `EXCALIDRAW_GEN_PATH` env var pointing to `excalidraw_gen.py`. Set in environment or shell profile:
+
+```bash
+export EXCALIDRAW_GEN_PATH="$HOME/src/jarvis-brain/tools/excalidraw_export/excalidraw_gen.py"
+```
+
+**Manual registration:**
+
+```bash
+mosaic-ensure-excalidraw           # install deps + register with Claude
+mosaic-ensure-excalidraw --check   # verify registration
+```
+
+## Git Providers
+
+| Instance                      | URL | CLI | Purpose |
+| ----------------------------- | --- | --- | ------- |
+| (add your git providers here) |     |     |         |
+
+## Credentials
+
+**Location:** (configure your credential file path)
+**Loader:** `source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>`
+
+**Never expose actual values. Never commit credential files.**
+
+## CLI Gotchas
+
+(Add platform-specific CLI gotchas as you discover them.)
+
+## Safety Defaults
+
+- Prefer `trash` over `rm` when available — recoverable beats gone forever
+- Never run destructive commands without explicit instruction
+- Write it down — "mental notes" don't survive session restarts; files do

packages/mosaic/framework/guides/VAULT-SECRETS.md

@@ -203,3 +203,374 @@ Error: token expired
 3. **Audit logging** - All access is logged; act accordingly
 4. **No local copies** - Don't store secrets in files or env vars long-term
 5. **Rotate on compromise** - Immediately rotate any exposed secrets
+
+---
+
+## Secrets Architecture Decision Matrix
+
+Use this table to choose between the ESO bridge (default) and Direct-Vault (opt-in) patterns for every new app or integration.
+
+| Factor                      | ESO Bridge (default)                                                          | Direct-Vault (opt-in)                                                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **Use-case**                | All static secrets (DB creds, API keys, signing keys, OAuth secrets)          | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
+| **App code change**         | None — reads standard env vars via `secretKeyRef`                             | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code                                           |
+| **Secret rotation**         | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process                                                         |
+| **Audit granularity**       | Access logged at Vault when ESO syncs; no per-request app audit               | Every app request to Vault is a separate audit log entry                                                                |
+| **Operational burden**      | Low — ESO handles polling, sync, and k8s Secret lifecycle                     | Higher — app must handle auth, lease renewal, error paths, and token rotation                                           |
+| **Justification required?** | No — this is the default                                                      | Yes — document in project README under "Secrets architecture"                                                           |
+| **Example use cases**       | Web app DB password, OAuth client secret, JWT signing key, API token          | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs                    |
+
+**Decision rule:** If you are unsure, use ESO. Only justify Direct-Vault when the secret cannot be safely stored in a k8s Secret (too short-lived, per-request TTL required, or mid-lifecycle renewal needed).
+
+---
+
+## ESO Bridge Pattern (Default)
+
+This is the required default for all k8s workloads. Follow this exact pattern unless a documented dynamic-secrets requirement justifies Direct-Vault.
+
+### 1. Provision Vault path
+
+```bash
+# Write the secrets for the app (run once; use IaC/Terraform for repeatable provisioning)
+vault kv put secret/k3s/<app> \
+  db_password="..." \
+  api_key="..." \
+  jwt_secret="..."
+```
+
+Use the canonical path structure: `secret/k3s/<app>` for k3s cluster workloads.
+
+### 2. ExternalSecret manifest
+
+Commit this to the repo's `deploy/` or `k8s/` directory:
+
+```yaml
+# deploy/external-secret.yaml
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: <app>-secrets
+  namespace: <namespace>
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: vault-backend # ClusterSecretStore name — verify with cluster admin
+    kind: ClusterSecretStore
+  target:
+    name: <app>-secrets # k8s Secret name that will be created
+    creationPolicy: Owner
+  data:
+    - secretKey: DB_PASSWORD # key in the k8s Secret
+      remoteRef:
+        key: secret/k3s/<app> # Vault path
+        property: db_password # field within the Vault secret
+    - secretKey: API_KEY
+      remoteRef:
+        key: secret/k3s/<app>
+        property: api_key
+    - secretKey: JWT_SECRET
+      remoteRef:
+        key: secret/k3s/<app>
+        property: jwt_secret
+```
+
+### 3. Deployment manifest — reference synced k8s Secret
+
+```yaml
+# deploy/deployment.yaml (env section)
+env:
+  - name: DB_PASSWORD
+    valueFrom:
+      secretKeyRef:
+        name: <app>-secrets # matches ExternalSecret target.name
+        key: DB_PASSWORD
+  - name: API_KEY
+    valueFrom:
+      secretKeyRef:
+        name: <app>-secrets
+        key: API_KEY
+  - name: JWT_SECRET
+    valueFrom:
+      secretKeyRef:
+        name: <app>-secrets
+        key: JWT_SECRET
+  - name: PORT
+    value: '3000' # safe-default: non-secret, no Vault needed
+```
+
+### 4. App-side schema validation — TypeScript (zod)
+
+Validate all required env vars at startup. Exit non-zero on missing values.
+
+```typescript
+// src/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  DB_PASSWORD: z.string().min(1, 'DB_PASSWORD is required'),
+  API_KEY: z.string().min(1, 'API_KEY is required'),
+  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 chars'),
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),
+});
+
+const result = envSchema.safeParse(process.env);
+if (!result.success) {
+  console.error('Missing or invalid environment variables:');
+  console.error(result.error.flatten().fieldErrors);
+  process.exit(1);
+}
+
+export const env = result.data;
+```
+
+### 4b. App-side schema validation — Python (pydantic)
+
+```python
+# src/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    db_password: str
+    api_key: str
+    jwt_secret: str
+    port: int = 3000
+    node_env: str = "production"
+
+    model_config = SettingsConfigDict(env_file=None)  # no .env in prod
+
+try:
+    settings = Settings()
+except Exception as e:
+    import sys
+    print(f"Missing or invalid environment variables: {e}", file=sys.stderr)
+    sys.exit(1)
+```
+
+### 4c. App-side schema validation — Go (envconfig)
+
+```go
+// config/config.go
+package config
+
+import (
+    "fmt"
+    "github.com/kelseyhightower/envconfig"
+)
+
+type Config struct {
+    DBPassword string `envconfig:"DB_PASSWORD" required:"true"`
+    APIKey     string `envconfig:"API_KEY" required:"true"`
+    JWTSecret  string `envconfig:"JWT_SECRET" required:"true"`
+    Port       int    `envconfig:"PORT" default:"3000"`
+}
+
+func Load() (*Config, error) {
+    var cfg Config
+    if err := envconfig.Process("", &cfg); err != nil {
+        return nil, fmt.Errorf("invalid environment: %w", err)
+    }
+    return &cfg, nil
+}
+```
+
+In your `main.go`:
+
+```go
+cfg, err := config.Load()
+if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    os.Exit(1)
+}
+```
+
+---
+
+## Direct-Vault Opt-In Pattern
+
+Use this pattern ONLY when a documented dynamic-secrets requirement applies (DB rotation with short TTLs, AWS STS, PKI, per-request audit). Document the justification in the project README under "Secrets architecture" before implementing.
+
+### When it is justified
+
+- Vault DB secrets engine with lease TTLs shorter than a typical pod lifecycle (< 1 hour)
+- AWS STS assume-role tokens generated per-request
+- Vault PKI short-lived certificates (< 24 hours) that must be renewed within a running pod
+- Per-request audit trail requirement (each app call must appear separately in Vault audit log)
+
+### Provision an AppRole for the app
+
+```bash
+# Enable AppRole auth (if not already enabled)
+vault auth enable approle
+
+# Create a Vault policy for the app
+# Note: KV v2 paths require both the exact path (for the top-level secret) and the
+# wildcard (for sub-paths). Always include both to avoid permission denied errors.
+vault policy write <app>-policy - <<EOF
+path "secret/data/k3s/<app>" {
+  capabilities = ["read"]
+}
+path "secret/data/k3s/<app>/*" {
+  capabilities = ["read"]
+}
+path "database/creds/<app>-role" {
+  capabilities = ["read"]
+}
+EOF
+
+# Create the AppRole
+vault write auth/approle/role/<app>-role \
+  token_policies="<app>-policy" \
+  token_ttl=1h \
+  token_max_ttl=4h \
+  secret_id_ttl=0
+
+# Retrieve role-id and secret-id
+vault read auth/approle/role/<app>-role/role-id
+vault write -f auth/approle/role/<app>-role/secret-id
+```
+
+### Bootstrap AppRole credentials via ESO (solving the chicken-and-egg problem)
+
+The AppRole `role-id` and `secret-id` are themselves secrets. Store them in Vault at a bootstrap path, then use ESO to sync them into a k8s Secret. The app reads that k8s Secret at startup to authenticate with Vault directly.
+
+```bash
+# Store the bootstrap credentials in Vault
+vault kv put secret/k3s/<app>-bootstrap \
+  role_id="<role-id>" \
+  secret_id="<secret-id>"
+```
+
+```yaml
+# deploy/external-secret-bootstrap.yaml
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: <app>-vault-auth
+  namespace: <namespace>
+spec:
+  refreshInterval: 24h
+  secretStoreRef:
+    name: vault-backend
+    kind: ClusterSecretStore
+  target:
+    name: <app>-vault-auth
+    creationPolicy: Owner
+  data:
+    - secretKey: VAULT_ROLE_ID
+      remoteRef:
+        key: secret/k3s/<app>-bootstrap
+        property: role_id
+    - secretKey: VAULT_SECRET_ID
+      remoteRef:
+        key: secret/k3s/<app>-bootstrap
+        property: secret_id
+```
+
+```yaml
+# deploy/deployment.yaml (env section for Direct-Vault app)
+env:
+  - name: VAULT_ADDR
+    value: 'https://vault.example.com' # safe-default: non-secret cluster address
+  - name: VAULT_ROLE_ID
+    valueFrom:
+      secretKeyRef:
+        name: <app>-vault-auth
+        key: VAULT_ROLE_ID
+  - name: VAULT_SECRET_ID
+    valueFrom:
+      secretKeyRef:
+        name: <app>-vault-auth
+        key: VAULT_SECRET_ID
+```
+
+### App-side Vault client pattern
+
+```typescript
+// src/vault-client.ts — only exists in Direct-Vault apps
+import vault from 'node-vault';
+import { z } from 'zod';
+
+const bootstrapSchema = z.object({
+  VAULT_ADDR: z.string().url(),
+  VAULT_ROLE_ID: z.string().min(1),
+  VAULT_SECRET_ID: z.string().min(1),
+});
+
+const bootstrap = bootstrapSchema.parse(process.env);
+
+const client = vault({ endpoint: bootstrap.VAULT_ADDR });
+
+export async function getVaultClient() {
+  const { auth } = await client.approleLogin({
+    role_id: bootstrap.VAULT_ROLE_ID,
+    secret_id: bootstrap.VAULT_SECRET_ID,
+  });
+  client.token = auth.client_token;
+  return client;
+}
+```
+
+Document in README under "Secrets architecture": the Vault path, why Direct-Vault is required, and the lease/renewal strategy.
+
+---
+
+## Forbidden Patterns (CI Lint Targets)
+
+The following patterns are forbidden in all Mosaic projects. CI lint SHOULD catch these automatically (implementation tracked separately). Agents MUST NOT introduce these patterns.
+
+### 1. Untagged fallback defaults for required values
+
+```yaml
+# FORBIDDEN — required secret with silent fallback
+environment:
+  - DB_PASSWORD=${DB_PASSWORD:-changeme}
+  - API_KEY=${API_KEY:-}
+
+# REQUIRED — fast-fail on missing required values
+environment:
+  - DB_PASSWORD=${DB_PASSWORD:?DB_PASSWORD is required}
+  - API_KEY=${API_KEY:?API_KEY is required}
+
+# ALLOWED — true convenience default, tagged
+environment:
+  - PORT=${PORT:-3000}  # safe-default: non-secret, app works at any port
+```
+
+This applies to: `docker-compose.yml`, k8s manifests, Helm `values.yaml`, any env file committed to git.
+
+### 2. Vault KV calls in application source code (ESO-default projects)
+
+```python
+# FORBIDDEN in ESO-default apps — direct Vault client in app source
+import hvac
+client = hvac.Client(url=os.environ['VAULT_ADDR'])
+secret = client.secrets.kv.v2.read_secret_version(path='myapp/db')
+```
+
+ESO-default apps read env vars only. Direct-Vault clients belong only in apps with a documented dynamic-secrets justification in README.
+
+### 3. Hardcoded secrets or API keys in committed files
+
+```python
+# FORBIDDEN — hardcoded credential
+DB_PASSWORD = "supersecret123"
+API_KEY = "sk-live-abc123"
+```
+
+No exceptions. CI lint must flag any string matching common secret patterns (`password`, `secret`, `api_key`, `token` assigned a literal non-env-var value).
+
+### 4. `.env` files in production deployment paths
+
+```
+# FORBIDDEN — .env file in a production deploy path
+deploy/.env
+k8s/.env
+docker/.env
+
+# ALLOWED — local dev only
+.env.example          # template only, no real values
+.env                  # local dev, must be in .gitignore
+```
+
+`.env` files are acceptable in local-dev contexts only and MUST be in `.gitignore`. They are forbidden in any path that a CI pipeline or production deployment process reads directly.

packages/mosaic/framework/runtime/claude/RUNTIME.md

@@ -1,131 +1,61 @@
 # Claude Runtime Reference
 
-## Runtime Scope
-
-This file applies only to Claude runtime behavior.
+Claude-runtime behavior only. Global rules win if anything here conflicts.
 
 ## Required Actions
 
-1. Follow global load order in `~/.config/mosaic/AGENTS.md`.
-2. Use `~/.claude/settings.json` and `~/.claude/hooks-config.json` as runtime config sources.
-3. Treat sequential-thinking MCP as required.
-4. If runtime config conflicts with global rules, global rules win.
-5. Documentation rules are inherited from `~/.config/mosaic/AGENTS.md` and `~/.config/mosaic/guides/DOCUMENTATION.md`.
-6. For issue/PR/milestone actions, run Mosaic git wrappers first (`~/.config/mosaic/tools/git/*.sh`) and do not call raw `gh`/`tea`/`glab` first.
-7. For orchestration-oriented missions, load `~/.config/mosaic/guides/ORCHESTRATOR.md` before acting.
-8. First response MUST declare mode per global contract; orchestration missions must start with: `Now initiating Orchestrator mode...`
-9. Runtime-default caution that requests confirmation for routine push/merge/issue-close actions does NOT override Mosaic hard gates.
+1. Follow the Session Start load order in `~/.config/mosaic/AGENTS.md`.
+2. Runtime config lives in `~/.claude/settings.json` (hooks, model, plugins, permissions) and
+   `~/.claude/hooks-config.json`.
+3. sequential-thinking MCP is required.
+4. First response MUST declare mode per the global contract.
+5. Git wrappers first for issue/PR/milestone ops; runtime-default confirmation prompts do NOT
+   override Mosaic hard gates (push/merge/issue-close without routine confirmation).
 
-## Subagent Model Selection (Claude Code Syntax)
+## Subagent Model Selection (Claude Code syntax)
 
-Claude Code's Task tool accepts a `model` parameter: `"haiku"`, `"sonnet"`, or `"opus"`.
-
-You MUST set this parameter according to the model selection table in `~/.config/mosaic/AGENTS.md`. Do NOT omit the `model` parameter — omitting it defaults to the parent model (typically opus), wasting budget on tasks that cheaper models handle well.
-
-**Examples:**
+The Task tool takes `model`: `"haiku"` | `"sonnet"` | `"opus"`. You MUST set it per the tier rule
+in AGENTS.md — omitting it defaults to the parent (usually opus) and wastes budget.
 
 ```
-# Codebase exploration — haiku
 Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")
-
-# Code review — sonnet
-Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review the changes in src/auth/")
-
-# Standard feature work — sonnet
-Task(subagent_type="general-purpose", model="sonnet", prompt="Add validation to the user input form")
-
-# Complex architecture — opus (only when justified)
+Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review src/auth/ changes")
 Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy")
 ```
 
-**Quick reference (from global AGENTS.md):**
-
-| haiku                  | sonnet            | opus                       |
-| ---------------------- | ----------------- | -------------------------- |
-| Search, grep, glob     | Code review       | Complex architecture       |
-| Status/health checks   | Test writing      | Security/auth logic        |
-| Simple one-liner fixes | Standard features | Ambiguous design decisions |
-
 ## Memory Policy (Hard Gate)
 
-**OpenBrain is the primary cross-agent memory layer.** All agent learnings, gotchas, decisions, and project state MUST be captured to OpenBrain via the `capture` MCP tool or REST API.
+OpenBrain is the primary cross-agent memory layer — capture learnings/gotchas/decisions there
+(`capture` MCP tool or REST). `~/.claude/projects/*/memory/MEMORY.md` is **write-blocked** by the
+`prevent-memory-write.sh` PreToolUse hook (the rule alone proved insufficient — the hook is the
+hard gate). At session start, `search(topic)` + `recent()` to load prior context. Full protocol:
+`~/.config/mosaic/guides/MEMORY.md`.
 
-`~/.claude/projects/*/memory/MEMORY.md` files are **write-blocked by PreToolUse hook** (`prevent-memory-write.sh`). Any attempt to write agent learnings there will be rejected with an error directing you to OpenBrain.
-
-### What belongs where
-
-| Content                                         | Location                                                               |
-| ----------------------------------------------- | ---------------------------------------------------------------------- |
-| Discoveries, gotchas, decisions, observations   | OpenBrain `capture` — searchable by all agents                         |
-| Active task state                               | `docs/TASKS.md` or `docs/scratchpads/`                                 |
-| Behavioral guardrails that MUST be in load-path | `MEMORY.md` (read-mostly; write only for genuine behavioral overrides) |
-| Mosaic framework technical notes                | `~/.config/mosaic/memory/`                                             |
-
-### Using OpenBrain
-
-At session start, load prior context:
-
-```
-search("topic or project name")   # semantic search
-recent(limit=5)                    # what's been happening
-```
-
-When you discover something:
-
-```
-capture("The thing you learned", source="project/context", metadata={"type": "gotcha", ...})
-```
-
-### Why the hook exists
-
-Instructions in RUNTIME.md, CLAUDE.md, and MEMORY.md are insufficient — agents default to writing local MEMORY.md regardless of written rules. The PreToolUse hook is a hard technical gate that makes the correct behavior the only possible behavior.
+Quick placement: discoveries/decisions → OpenBrain; active task state → `docs/TASKS.md` or
+`docs/scratchpads/`; Mosaic framework notes → `~/.config/mosaic/memory/`.
 
 ## MCP Configuration
 
-**MCPs are configured in `~/.claude.json` — NOT `~/.claude/settings.json`.**
-
-`settings.json` controls hooks, model, plugins, and allowed commands.
-`~/.claude.json` is the global Claude Code state file where `mcpServers` lives.
-
-To register an MCP server that persists across all sessions:
+MCP servers are configured in `~/.claude.json` (key `mcpServers`) — NOT `~/.claude/settings.json`,
+where that key is ignored. `settings.json` controls hooks/model/plugins/permissions.
 
 ```bash
-# HTTP MCP (e.g. OpenBrain)
 claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
-
-# stdio MCP
-claude mcp add --scope user <name> -- npx -y <package>
+claude mcp add --scope user <name> -- npx -y <package>   # stdio
 ```
 
-`--scope user` = writes to `~/.claude.json` (global, all projects).
-`--scope project` = writes to `.claude/settings.json` in project root.
-`--scope local` = default, local-only (not committed).
+`--scope user` → `~/.claude.json` (global); `project` → `.claude/settings.json`; `local` (default)
+→ not committed.
 
-Do NOT add `mcpServers` to `~/.claude/settings.json` — that key is ignored for MCP loading.
+## Required Settings (launcher-audited, advisory)
 
-## Required Claude Code Settings (Enforced by Launcher)
+`mosaic claude` warns if `~/.claude/settings.json` is missing these (session still launches):
 
-The `mosaic claude` launcher validates that `~/.claude/settings.json` contains the required Mosaic configuration. Missing or outdated settings trigger a warning at launch.
+- **Hooks** — PreToolUse `prevent-memory-write.sh` (Write|Edit|MultiEdit); PostToolUse
+  `qa-hook-stdin.sh` + `typecheck-hook.sh` (Edit|MultiEdit|Write).
+- **Plugins** — `feature-dev`, `pr-review-toolkit`, `code-review`.
+- **Settings** — `enableAllMcpTools: true`; `model: "opus"` (orchestrator default; workers use
+  tiered models via the Task `model` param).
 
-**Required hooks:**
-
-| Event       | Matcher                  | Script                    | Purpose                                        |
-| ----------- | ------------------------ | ------------------------- | ---------------------------------------------- |
-| PreToolUse  | `Write\|Edit\|MultiEdit` | `prevent-memory-write.sh` | Block writes to `~/.claude/projects/*/memory/` |
-| PostToolUse | `Edit\|MultiEdit\|Write` | `qa-hook-stdin.sh`        | QA report generation after code edits          |
-| PostToolUse | `Edit\|MultiEdit\|Write` | `typecheck-hook.sh`       | Inline TypeScript type checking                |
-
-**Required plugins:**
-
-| Plugin              | Purpose                                                                                                  |
-| ------------------- | -------------------------------------------------------------------------------------------------------- |
-| `feature-dev`       | Subagent architecture: code-reviewer, code-architect, code-explorer                                      |
-| `pr-review-toolkit` | PR review: code-simplifier, comment-analyzer, test-analyzer, silent-failure-hunter, type-design-analyzer |
-| `code-review`       | Standalone code review capabilities                                                                      |
-
-**Required settings:**
-
-- `enableAllMcpTools: true` — Allow all configured MCP tools without per-tool approval
-- `model: "opus"` — Default to opus for orchestrator-level sessions (workers use tiered models via Task tool)
-
-If `mosaic claude` detects missing hooks or plugins, it will print a warning with the exact settings to add. The session will still launch — enforcement is advisory, not blocking — but agents operating without these settings are running degraded.
+Note: PostToolUse hook plain stdout on exit 0 goes to the debug log, not model context — only
+`hookSpecificOutput.additionalContext` (or exit-2 stderr) enters context.

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,18 +198,18 @@ 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
-        load_credentials "woodpecker-${wp_default}"
+        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-*)

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

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)
@@ -103,16 +113,28 @@ get_gitea_token() {
     if [[ -f "$cred_loader" ]]; then
         local token
         token=$(
+            # shellcheck source=/dev/null
             source "$cred_loader"
+            # Host-specific wrapper resolution must not inherit caller/global GITEA_*.
+            # load_credentials intentionally preserves existing env vars for interactive use,
+            # but metadata/merge wrappers need credentials matching the remote host.
+            unset GITEA_TOKEN GITEA_URL
             case "$host" in
                 git.mosaicstack.dev) load_credentials gitea-mosaicstack 2>/dev/null ;;
                 git.uscllc.com)      load_credentials gitea-usc 2>/dev/null ;;
                 *)
+                    local matched=false
                     for svc in gitea-mosaicstack gitea-usc; do
-                        load_credentials "$svc" 2>/dev/null || continue
-                        [[ "${GITEA_URL:-}" == *"$host"* ]] && break
                         unset GITEA_TOKEN GITEA_URL
+                        load_credentials "$svc" 2>/dev/null || continue
+                        if [[ "${GITEA_URL:-}" == "https://$host" || "${GITEA_URL:-}" == "http://$host" || "${GITEA_URL:-}" == *"//$host" ]]; then
+                            matched=true
+                            break
+                        fi
                     done
+                    if [[ "$matched" != true ]]; then
+                        unset GITEA_TOKEN GITEA_URL
+                    fi
                     ;;
             esac
             echo "${GITEA_TOKEN:-}"
@@ -123,10 +145,12 @@ get_gitea_token() {
         fi
     fi
 
-    # 2. GITEA_TOKEN env var (may be set by caller)
+    # 2. GITEA_TOKEN env var (only when GITEA_URL, if present, matches the remote host)
     if [[ -n "${GITEA_TOKEN:-}" ]]; then
-        echo "$GITEA_TOKEN"
-        return 0
+        if [[ -z "${GITEA_URL:-}" || "${GITEA_URL:-}" == "https://$host" || "${GITEA_URL:-}" == "http://$host" || "${GITEA_URL:-}" == *"//$host" ]]; then
+            echo "$GITEA_TOKEN"
+            return 0
+        fi
     fi
 
     # 3. ~/.git-credentials file
@@ -143,6 +167,37 @@ get_gitea_token() {
     return 1
 }
 
+# Resolve HTTPS basic auth credentials for a Gitea host from ~/.git-credentials.
+# Prints "username:password" for direct curl -u consumption. Callers must not log it.
+get_gitea_basic_auth() {
+    local host="$1"
+    local creds="$HOME/.git-credentials"
+    if [[ ! -f "$creds" ]]; then
+        return 1
+    fi
+
+    python3 - "$host" "$creds" <<'PY'
+import sys
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+host = sys.argv[1]
+creds = Path(sys.argv[2])
+
+for line in creds.read_text(encoding="utf-8").splitlines():
+    parsed = urlparse(line.strip())
+    if parsed.hostname != host:
+        continue
+    username = unquote(parsed.username or "")
+    password = unquote(parsed.password or "")
+    if username and password:
+        print(f"{username}:{password}")
+        raise SystemExit(0)
+
+raise SystemExit(1)
+PY
+}
+
 # If script is run directly (not sourced), output the platform
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
     detect_platform

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"

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

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
 
-PLATFORM=$(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
 
 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

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"

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

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
 
-detect_platform > /dev/null
+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

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"

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

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
 
-detect_platform > /dev/null
+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
+
+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
     if [[ -n "$OUTPUT_FILE" ]]; then
-        gh pr diff "$PR_NUMBER" > "$OUTPUT_FILE"
+        gh pr diff "$PR_NUMBER" --repo "$REPO_INFO" > "$OUTPUT_FILE"
     else
-        gh pr diff "$PR_NUMBER"
+        gh pr diff "$PR_NUMBER" --repo "$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)
+    HOST=$(get_remote_host 2>/dev/null || echo "git.mosaicstack.dev")
 
-    # 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
-        exit 1
-    fi
-
-    DIFF_URL="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}.diff"
+    DIFF_URL="https://${HOST}/api/v1/repos/${REPO_INFO}/pulls/${PR_NUMBER}.diff"
 
     GITEA_API_TOKEN=$(get_gitea_token "$HOST" || true)
 

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
 
-PLATFORM=$(detect_platform)
+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

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -2,9 +2,10 @@
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
 # Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--skip-queue-guard]
 
-set -e
+set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=packages/mosaic/framework/tools/git/detect-platform.sh
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Default values
@@ -12,6 +13,7 @@ PR_NUMBER=""
 MERGE_METHOD="squash"
 DELETE_BRANCH=false
 SKIP_QUEUE_GUARD=false
+DRY_RUN=false
 
 usage() {
     cat <<EOF
@@ -24,6 +26,7 @@ Options:
     -m, --method METHOD     Merge method: squash only (default: squash)
     -d, --delete-branch     Delete the head branch after merge
         --skip-queue-guard  Skip CI queue guard wait before merge
+        --dry-run           Run metadata/login preflight without merging
     -h, --help              Show this help message
 
 Examples:
@@ -54,6 +57,11 @@ while [[ $# -gt 0 ]]; do
             SKIP_QUEUE_GUARD=true
             shift
             ;;
+        --dry-run)
+            DRY_RUN=true
+            SKIP_QUEUE_GUARD=true
+            shift
+            ;;
         -h|--help)
             usage
             ;;
@@ -69,12 +77,18 @@ 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
 fi
 
-BASE_BRANCH="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
+PR_METADATA="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER")"
+BASE_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
 if [[ "$BASE_BRANCH" != "main" ]]; then
     echo "Error: Mosaic policy allows merges only for PRs targeting 'main' (found '$BASE_BRANCH')." >&2
     exit 1
@@ -92,21 +106,163 @@ PLATFORM=$(detect_platform)
 OWNER=$(get_repo_owner)
 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'
+import json
+import os
+import sys
+
+host = sys.argv[1]
+try:
+    logins = json.loads(os.environ.get("TEA_LOGINS_JSON", "[]"))
+except Exception:
+    raise SystemExit(1)
+
+for login in logins if isinstance(logins, list) else []:
+    url = str(login.get("url") or login.get("URL") or "")
+    name = str(login.get("name") or login.get("Name") or "")
+    if url.rstrip("/").endswith(host) and name:
+        print(name)
+        raise SystemExit(0)
+
+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
+    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)
+    if [[ -n "$token" ]]; then
+        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
+            -X POST \
+            -H "Authorization: token $token" \
+            -H 'Content-Type: application/json' \
+            -d "$payload" \
+            "$api_url" || true)
+        if [[ "$raw_code" =~ ^2 ]]; then
+            rm -f "$body_file"
+            return 0
+        fi
+    fi
+
+    basic_auth=$(get_gitea_basic_auth "$host" || true)
+    if [[ -n "$basic_auth" ]]; then
+        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
+            -X POST \
+            -u "$basic_auth" \
+            -H 'Content-Type: application/json' \
+            -d "$payload" \
+            "$api_url" || true)
+        if [[ "$raw_code" =~ ^2 ]]; then
+            rm -f "$body_file"
+            return 0
+        fi
+    fi
+
+    python3 - "${raw_code:-000}" "$body_file" <<'PY' >&2
+import json
+import sys
+code, path = sys.argv[1], sys.argv[2]
+try:
+    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:
+    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"
+    return 1
+}
+
+if [[ "$DRY_RUN" == true ]]; then
+    if [[ "$PLATFORM" == "gitea" ]]; then
+        HOST=$(get_remote_host) || {
+            echo "Error: Cannot determine host from origin remote URL" >&2
+            exit 1
+        }
+        TEA_LOGIN="${GITEA_LOGIN:-$(find_tea_login_for_host "$HOST" || true)}"
+        if [[ -n "$TEA_LOGIN" ]]; then
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with tea login '$TEA_LOGIN' (base=$BASE_BRANCH, method=squash)."
+        else
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with authenticated Gitea API fallback (base=$BASE_BRANCH, method=squash)."
+        fi
+    else
+        echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."
+    fi
+    exit 0
+fi
+
 case "$PLATFORM" in
     github)
-        CMD="gh pr merge $PR_NUMBER --squash"
-        [[ "$DELETE_BRANCH" == true ]] && CMD="$CMD --delete-branch"
-        eval "$CMD"
+        cmd=(gh pr merge "$PR_NUMBER" --squash)
+        [[ "$DELETE_BRANCH" == true ]] && cmd+=(--delete-branch)
+        "${cmd[@]}"
         ;;
     gitea)
-        CMD="tea pr merge $PR_NUMBER --style squash --repo $OWNER/$REPO --login ${GITEA_LOGIN:-mosaicstack}"
+        HOST=$(get_remote_host) || {
+            echo "Error: Cannot determine host from origin remote URL" >&2
+            exit 1
+        }
+        TEA_LOGIN="${GITEA_LOGIN:-$(find_tea_login_for_host "$HOST" || true)}"
+
+        if [[ -n "$TEA_LOGIN" ]]; then
+            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"
+        fi
 
         # Delete branch after merge if requested
         if [[ "$DELETE_BRANCH" == true ]]; then
             echo "Note: Branch deletion after merge may need to be done separately with tea" >&2
         fi
-
-        eval "$CMD"
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

packages/mosaic/framework/tools/git/pr-metadata.sh

@@ -2,9 +2,10 @@
 # pr-metadata.sh - Get PR metadata as JSON on GitHub or Gitea
 # Usage: pr-metadata.sh -n <pr_number> [-o <output_file>]
 
-set -e
+set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=packages/mosaic/framework/tools/git/detect-platform.sh
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
@@ -31,7 +32,7 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
+            echo "Unknown option: $1" >&2
             exit 1
             ;;
     esac
@@ -42,56 +43,168 @@ if [[ -z "$PR_NUMBER" ]]; then
     exit 1
 fi
 
+write_metadata() {
+    local metadata="$1"
+    if [[ -n "$OUTPUT_FILE" ]]; then
+        printf '%s\n' "$metadata" > "$OUTPUT_FILE"
+    else
+        printf '%s\n' "$metadata"
+    fi
+}
+
+curl_gitea_pull() {
+    local api_url="$1"
+    local token basic_auth raw_code body_file http_code
+    body_file=$(mktemp)
+
+    token=$(get_gitea_token "$HOST" || true)
+    if [[ -n "$token" ]]; then
+        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" -H "Authorization: token $token" "$api_url" || true)
+        if [[ "$raw_code" =~ ^2 ]]; then
+            cat "$body_file"
+            rm -f "$body_file"
+            return 0
+        fi
+        http_code="$raw_code"
+    fi
+
+    basic_auth=$(get_gitea_basic_auth "$HOST" || true)
+    if [[ -n "$basic_auth" ]]; then
+        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" -u "$basic_auth" "$api_url" || true)
+        if [[ "$raw_code" =~ ^2 ]]; then
+            cat "$body_file"
+            rm -f "$body_file"
+            return 0
+        fi
+        http_code="$raw_code"
+    fi
+
+    if [[ -z "${http_code:-}" ]]; then
+        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" "$api_url" || true)
+        http_code="$raw_code"
+    fi
+
+    python3 - "$http_code" "$body_file" <<'PY' >&2
+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"
+except Exception:
+    message = open(path, encoding="utf-8", errors="replace").read()[:200] or "empty response"
+print(f"Error: Gitea pull request API request failed with HTTP {code}: {message}")
+PY
+    rm -f "$body_file"
+    return 1
+}
+
 detect_platform > /dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
     METADATA=$(gh pr view "$PR_NUMBER" --json number,title,body,state,author,headRefName,baseRefName,files,labels,assignees,milestone,createdAt,updatedAt,url,isDraft)
-
-    if [[ -n "$OUTPUT_FILE" ]]; then
-        echo "$METADATA" > "$OUTPUT_FILE"
-    else
-        echo "$METADATA"
-    fi
+    write_metadata "$METADATA"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     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
+    HOST=$(get_remote_host) || {
+        echo "Error: Cannot determine host from origin remote URL" >&2
         exit 1
-    fi
+    }
 
     API_URL="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}"
-
-    GITEA_API_TOKEN=$(get_gitea_token "$HOST" || true)
-
-    if [[ -n "$GITEA_API_TOKEN" ]]; then
-        RAW=$(curl -sS -H "Authorization: token $GITEA_API_TOKEN" "$API_URL")
+    if [[ -n "${MOSAIC_GITEA_PR_METADATA_RAW_FILE:-}" ]]; then
+        RAW=$(cat "$MOSAIC_GITEA_PR_METADATA_RAW_FILE")
     else
-        RAW=$(curl -sS "$API_URL")
+        RAW=$(curl_gitea_pull "$API_URL")
     fi
 
-    # Normalize Gitea response to match our expected schema
-    METADATA=$(echo "$RAW" | python3 -c "
-import json, sys
-data = json.load(sys.stdin)
+    # Normalize Gitea response to match GitHub's expected metadata schema.
+    METADATA=$(printf '%s' "$RAW" | python3 -c "
+import json
+import sys
+
+def first_non_empty(*values):
+    for value in values:
+        if value is None:
+            continue
+        if isinstance(value, str):
+            value = value.strip()
+        if value:
+            return value
+    return ''
+
+def nested(data, *keys):
+    current = data
+    for key in keys:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(key)
+    return current
+
+try:
+    data = json.load(sys.stdin)
+except json.JSONDecodeError as exc:
+    print(f'Error: Gitea API returned non-JSON response: {exc}', file=sys.stderr)
+    sys.exit(1)
+
+if not isinstance(data, dict):
+    print('Error: Gitea API returned an unexpected non-object response', file=sys.stderr)
+    sys.exit(1)
+
+if data.get('message') and not data.get('number'):
+    print(f\"Error: Gitea API error: {data.get('message')}\", file=sys.stderr)
+    sys.exit(1)
+
+head_ref = first_non_empty(
+    nested(data, 'head', 'ref'),
+    nested(data, 'head', 'name'),
+    nested(data, 'head', 'branch'),
+    data.get('head_branch'),
+    data.get('head_ref'),
+    nested(data, 'head', 'label'),
+    data.get('head_label'),
+)
+if isinstance(head_ref, str) and head_ref.startswith('refs/pull/'):
+    head_ref = first_non_empty(
+        nested(data, 'head', 'label'),
+        data.get('head_label'),
+        nested(data, 'head', 'name'),
+        nested(data, 'head', 'branch'),
+        data.get('head_branch'),
+        data.get('head_ref'),
+        head_ref,
+    )
+base_ref = first_non_empty(
+    nested(data, 'base', 'ref'),
+    nested(data, 'base', 'name'),
+    nested(data, 'base', 'branch'),
+    data.get('base_branch'),
+    data.get('base_ref'),
+    data.get('base_label'),
+)
+
+if not head_ref or not base_ref:
+    available = ', '.join(sorted(data.keys()))
+    print(
+        'Error: Unable to resolve non-empty Gitea PR head/base refs '
+        f'(headRefName={head_ref!r}, baseRefName={base_ref!r}; keys={available})',
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
 normalized = {
     'number': data.get('number'),
     'title': data.get('title'),
     'body': data.get('body', ''),
     'state': data.get('state'),
-    'author': data.get('user', {}).get('login', ''),
-    'headRefName': data.get('head', {}).get('ref', ''),
-    'baseRefName': data.get('base', {}).get('ref', ''),
-    'labels': [l.get('name', '') for l in data.get('labels', [])],
-    'assignees': [a.get('login', '') for a in data.get('assignees', [])],
-    'milestone': data.get('milestone', {}).get('title', '') if data.get('milestone') else '',
+    'author': nested(data, 'user', 'login') or '',
+    'headRefName': head_ref,
+    'baseRefName': base_ref,
+    'labels': [l.get('name', '') for l in data.get('labels', []) if isinstance(l, dict)],
+    'assignees': [a.get('login', '') for a in data.get('assignees', []) if isinstance(a, dict)],
+    'milestone': nested(data, 'milestone', 'title') or '',
     'createdAt': data.get('created_at', ''),
     'updatedAt': data.get('updated_at', ''),
     'url': data.get('html_url', ''),
@@ -102,11 +215,7 @@ normalized = {
 json.dump(normalized, sys.stdout, indent=2)
 ")
 
-    if [[ -n "$OUTPUT_FILE" ]]; then
-        echo "$METADATA" > "$OUTPUT_FILE"
-    else
-        echo "$METADATA"
-    fi
+    write_metadata "$METADATA"
 else
     echo "Error: Unknown platform" >&2
     exit 1

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"
             ;;
         *)

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

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"

packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Regression harness for Gitea PR metadata normalization.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-metadata-gitea}"
+REPO_DIR="$WORK_DIR/repo"
+FIXTURE_DIR="$WORK_DIR/fixtures"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$REPO_DIR" "$FIXTURE_DIR"
+
+git -C "$REPO_DIR" init -q
+git -C "$REPO_DIR" remote add origin https://git.uscllc.com/USC/uconnect.git
+
+cat > "$FIXTURE_DIR/gitea-standard.json" <<'JSON'
+{
+  "number": 1905,
+  "title": "Smoke gate fix",
+  "state": "open",
+  "user": {"login": "edith"},
+  "head": {"ref": "edith/t_39ce717c-authentik-smoke-gate"},
+  "base": {"ref": "main"},
+  "labels": [{"name": "ci"}],
+  "assignees": [{"login": "edith"}],
+  "html_url": "https://git.uscllc.com/USC/uconnect/pulls/1905"
+}
+JSON
+
+cat > "$FIXTURE_DIR/gitea-fallback.json" <<'JSON'
+{
+  "number": 1908,
+  "title": "Fallback branch fields",
+  "state": "open",
+  "user": {"login": "edith"},
+  "head_branch": "fix/fallback-head",
+  "base_branch": "main",
+  "html_url": "https://git.uscllc.com/USC/uconnect/pulls/1908"
+}
+JSON
+
+cat > "$FIXTURE_DIR/gitea-refs-pull-label.json" <<'JSON'
+{
+  "number": 1908,
+  "title": "Closed merged PR with synthetic pull ref",
+  "state": "closed",
+  "user": {"login": "edith"},
+  "head": {"ref": "refs/pull/1908/head", "label": "fix/t_23fa9e1d-portal-health-backend"},
+  "base": {"ref": "main"},
+  "html_url": "https://git.uscllc.com/USC/uconnect/pulls/1908"
+}
+JSON
+
+cat > "$FIXTURE_DIR/gitea-error.json" <<'JSON'
+{"message": "user does not exist [uid: 0, name: ]", "url": "https://git.uscllc.com/api/swagger"}
+JSON
+
+run_case() {
+    local fixture="$1" expected_number="$2" expected_head="$3"
+    local output
+    output=$(cd "$REPO_DIR" && MOSAIC_GITEA_PR_METADATA_RAW_FILE="$fixture" "$SCRIPT_DIR/pr-metadata.sh" -n "$expected_number")
+    PR_METADATA_OUTPUT="$output" python3 - "$expected_number" "$expected_head" <<'PY'
+import json
+import os
+import sys
+
+data = json.loads(os.environ["PR_METADATA_OUTPUT"])
+expected_number = int(sys.argv[1])
+expected_head = sys.argv[2]
+assert data["number"] == expected_number, data
+assert data["baseRefName"] == "main", data
+assert data["headRefName"] == expected_head, data
+PY
+}
+
+run_case "$FIXTURE_DIR/gitea-standard.json" 1905 edith/t_39ce717c-authentik-smoke-gate
+run_case "$FIXTURE_DIR/gitea-fallback.json" 1908 fix/fallback-head
+run_case "$FIXTURE_DIR/gitea-refs-pull-label.json" 1908 fix/t_23fa9e1d-portal-health-backend
+
+if cd "$REPO_DIR" && MOSAIC_GITEA_PR_METADATA_RAW_FILE="$FIXTURE_DIR/gitea-error.json" "$SCRIPT_DIR/pr-metadata.sh" -n 1909 >/dev/null 2>"$WORK_DIR/error.log"; then
+    echo "Expected API error fixture to fail" >&2
+    exit 1
+fi
+grep -q "Gitea API error" "$WORK_DIR/error.log"
+
+echo "Gitea PR metadata regression harness passed"

packages/mosaic/framework/tools/tmux/README.md

@@ -0,0 +1,78 @@
+# Inter-Agent tmux Comms — Standard & Tooling
+
+Reliable, self-identifying messaging between Mosaic agents running in tmux panes
+(Claude Code / Codex / OpenCode REPLs), across hosts.
+
+## The addressing standard (required)
+
+Every cross-agent tmux message MUST begin with an addressing preamble:
+
+```
+[<src_host>:<src_session> -> <dst_host>:<dst_session>] <message>
+```
+
+- `host` = `hostname -s` of the machine the agent runs on (e.g. `web1`, `sb-it-mgr-0-lt`).
+- `session` = the tmux session name (e.g. `mos-claude`, `rev0-4`, `installer-1`).
+- **Replies FLIP the preamble**: the recipient answers with `[<dst> -> <src>] ...`.
+
+Why: a fresh or context-wiped agent always knows who sent a message and to whom.
+No ambiguity about origin or lane after a tmux wipe / session restart.
+
+Example exchange:
+
+```
+[web1:mos-claude -> sb-it-mgr-0-lt:installer-1] status on #29?
+[sb-it-mgr-0-lt:installer-1 -> web1:mos-claude] Q2 done, opening PR #34.
+```
+
+## The helper: `agent-send.sh`
+
+Prepends the preamble automatically (auto-detecting your own `host:session`) and
+delivers reliably to local OR remote panes.
+
+```bash
+# Local target (same host)
+agent-send.sh -s <dst_session> -m "message"
+
+# Remote target (over ssh)
+agent-send.sh -H user@host -s <dst_session> -m "message"
+
+# From a file / stdin
+agent-send.sh -H user@host -s <dst_session> -f msg.txt
+echo "msg" | agent-send.sh -s <dst_session>
+```
+
+Key flags: `-s` dst session (required) · `-H` ssh target for remote · `-n` dst
+hostname for the preamble (else auto-resolved) · `-m`/`-f`/stdin body · `-S`
+override source label · `-v` verbose · `-r N` Enter-flush attempts.
+
+## Why a helper exists (the submission gotcha)
+
+Pasting into an interactive REPL via raw `tmux send-keys` is unreliable: a
+trailing `Enter` is frequently swallowed and the message sits as an **unsubmitted
+draft** ("Press up to edit queued messages"). Over an `ssh -> nested tmux` hop the
+plain `Enter` keyname often does not register at all — `C-m` is needed.
+
+`send-message.sh` solves this for a **local** pane: bracketed-paste the body
+(so multi-line content doesn't submit early), pause, then send `Enter` as its own
+keystroke and flush with a second, verifying against a draft heuristic.
+
+`agent-send.sh` solves the **remote** case by _shipping `send-message.sh` over ssh_
+(`ssh host bash -s -- ... < send-message.sh`) and running it local to the target
+pane — so the reliable send-keys always happens on the pane's own host. The remote
+needs only `bash` + `tmux` + `base64`; **no mosaic install required there**. The
+message crosses the wire as base64 (`-b`) to avoid all shell-quoting hazards.
+
+## Files
+
+- `agent-send.sh` — inter-agent wrapper (preamble + local/remote dispatch).
+- `send-message.sh` — low-level reliable single-pane submitter (`-b` base64 input).
+
+## Distribution
+
+These live in the installed framework copy at
+`~/.config/mosaic/tools/tmux/`. `install.sh` rsyncs the framework **source tree**
+to each host, so to propagate permanently, land both files in the framework
+source repo and re-run the installer on each host. Until then, `agent-send.sh`
+already works against any reachable host because it ships `send-message.sh` over
+ssh per-send — no pre-install on the target host is needed to _send to_ it.

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# agent-send.sh — standard inter-agent tmux messaging for the Mosaic stack.
+#
+# WHAT IT DOES
+#   Sends a message to another agent's tmux pane (local or on a remote host)
+#   with the canonical addressing preamble prepended:
+#
+#       [<src_host>:<src_session> -> <dst_host>:<dst_session>] <message>
+#
+#   The preamble makes every inter-agent message self-identifying, so a fresh
+#   or context-wiped agent always knows who sent a message and to whom — no
+#   ambiguity about lanes or origin. Recipients replying should FLIP the
+#   preamble: [<dst> -> <src>] ... (this tool sends; it does not auto-reply).
+#
+# WHY A WRAPPER
+#   Reliable submission into an interactive REPL (Claude Code / Codex) is fiddly:
+#   a trailing Enter is often swallowed and the message sits as an unsubmitted
+#   DRAFT. tools/tmux/send-message.sh already solves that for a LOCAL pane via
+#   bracketed-paste + Enter-flush + draft-detection. For REMOTE targets this
+#   wrapper SHIPS send-message.sh over ssh (stdin) and runs it there, so the
+#   reliable send-keys happens local to the target pane — sidestepping the
+#   ssh->nested-tmux Enter/C-m swallow entirely. No mosaic install needed on
+#   the remote host; only bash + tmux + base64 (standard).
+#
+# USAGE
+#   agent-send.sh -s <dst_session> -m "message"                 # local target
+#   agent-send.sh -H user@host -s <dst_session> -m "message"    # remote target
+#   agent-send.sh -H user@host -n <dst_hostname> -s <sess> -f msg.txt
+#   echo "msg" | agent-send.sh -H user@host -s <dst_session>
+#
+# OPTIONS
+#   -s DST_SESSION  target tmux session (or session:window.pane)   [required]
+#   -H SSH_TARGET   ssh target (user@host) for a remote pane; omit for local
+#   -n DST_HOST     hostname to show in the preamble for the target.
+#                   Default: local hostname, or (remote) resolved via one ssh.
+#   -m MESSAGE      message text (single- or multi-line)
+#   -f FILE         read message from FILE instead of -m
+#   -S SRC_LABEL    override source label "<host>:<session>" (default: auto)
+#   -r N            Enter-flush attempts passed through (default 2)
+#   -v              verbose: print pane tail after delivery
+#   -h              help
+#
+# EXIT CODES  (passed through from send-message.sh)
+#   0 delivered/queued · 1 target not found · 2 still draft · 3 usage error
+set -uo pipefail
+
+SELF_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+SENDER="$SELF_DIR/send-message.sh"
+
+DST_SESSION=""; SSH_TARGET=""; DST_HOST=""; MSG=""; FILE=""
+SRC_LABEL=""; RETRIES=2; VERBOSE=0
+usage() { sed -n '2,44p' "$0"; exit "${1:-3}"; }
+
+while getopts "s:H:n:m:f:S:r:vh" o; do
+  case "$o" in
+    s) DST_SESSION=$OPTARG ;; H) SSH_TARGET=$OPTARG ;; n) DST_HOST=$OPTARG ;;
+    m) MSG=$OPTARG ;; f) FILE=$OPTARG ;; S) SRC_LABEL=$OPTARG ;;
+    r) RETRIES=$OPTARG ;; v) VERBOSE=1 ;; h) usage 0 ;; *) usage 3 ;;
+  esac
+done
+
+[ -n "$DST_SESSION" ] || { echo "ERROR: -s DST_SESSION is required" >&2; usage 3; }
+[ -x "$SENDER" ] || { echo "ERROR: send-message.sh not found beside this script" >&2; exit 3; }
+
+# Message body from -f / -m / stdin.
+if   [ -n "$FILE" ]; then [ -r "$FILE" ] || { echo "ERROR: cannot read $FILE" >&2; exit 3; }; MSG=$(cat -- "$FILE")
+elif [ -z "$MSG" ] && [ ! -t 0 ]; then MSG=$(cat)
+fi
+[ -n "$MSG" ] || { echo "ERROR: empty message (use -m, -f, or stdin)" >&2; exit 3; }
+
+# Source label: this agent's host:session (auto-detected, overridable).
+if [ -z "$SRC_LABEL" ]; then
+  src_host=$(hostname -s 2>/dev/null || echo "?")
+  src_sess=$(tmux display-message -p '#S' 2>/dev/null || echo "?")
+  SRC_LABEL="${src_host}:${src_sess}"
+fi
+
+# Destination host label for the preamble.
+if [ -z "$DST_HOST" ]; then
+  if [ -n "$SSH_TARGET" ]; then
+    DST_HOST=$(ssh -o ConnectTimeout=8 -o BatchMode=yes "$SSH_TARGET" 'hostname -s' 2>/dev/null || echo "${SSH_TARGET#*@}")
+  else
+    DST_HOST=$(hostname -s 2>/dev/null || echo "local")
+  fi
+fi
+
+PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}]"
+FULL="${PREAMBLE} ${MSG}"
+B64=$(printf '%s' "$FULL" | base64 -w0)
+
+vflag=""; [ "$VERBOSE" = 1 ] && vflag="-v"
+
+if [ -z "$SSH_TARGET" ]; then
+  # Local pane: call the canonical sender directly.
+  exec "$SENDER" -t "$DST_SESSION" -b "$B64" -r "$RETRIES" $vflag
+else
+  # Remote pane: ship the sender over ssh and run it local to the target.
+  ssh -o ConnectTimeout=10 "$SSH_TARGET" \
+      "bash -s -- -t '$DST_SESSION' -b '$B64' -r '$RETRIES' $vflag" < "$SENDER"
+fi

packages/mosaic/framework/tools/tmux/send-message.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# send-message.sh — reliably deliver a message to a tmux pane running an
+# interactive REPL (e.g. a Claude Code / Codex agent).
+#
+# WHY THIS EXISTS
+#   Pasting multi-line text into an interactive agent REPL via `tmux send-keys`
+#   is unreliable: the text lands in the input box but a single trailing Enter
+#   in the same keystroke stream is frequently swallowed, so the message sits as
+#   an UNSUBMITTED DRAFT ("Press up to edit queued messages") and the agent never
+#   sees it. The mechanical fix is: paste as a bracketed paste (so embedded
+#   newlines don't submit early), pause, then send Enter as its OWN keystroke,
+#   pause, and send Enter again to flush. An extra Enter on an empty prompt is a
+#   no-op in Claude Code, so the double-Enter is safe.
+#
+# USAGE
+#   send-message.sh -t <target> -m "message"
+#   send-message.sh -t <target> -f <file>
+#   echo "message" | send-message.sh -t <target>
+#   ssh host bash -s -- -t <target> -b "$(base64 -w0 <<<msg)" < send-message.sh
+#
+# OPTIONS
+#   -t TARGET   tmux target: session, or session:window.pane  [required]
+#   -m MESSAGE  message text (single- or multi-line)
+#   -f FILE     read message from FILE instead of -m
+#   -b BASE64   message as base64 (ssh-safe transport; decoded internally)
+#   -r N        Enter-flush attempts (default 2)
+#   -v          verbose: print a short tail of the pane after delivery
+#   -h          help
+#
+# EXIT CODES
+#   0  delivered (submitted) or queued (agent busy; will process when free)
+#   1  tmux target not found
+#   2  message still appears to be an unsubmitted draft after retries
+#   3  usage error
+set -uo pipefail
+
+TARGET=""; MSG=""; FILE=""; B64=""; RETRIES=2; VERBOSE=0
+usage() { sed -n '2,34p' "$0"; exit "${1:-3}"; }
+
+while getopts "t:m:f:b:r:vh" o; do
+  case "$o" in
+    t) TARGET=$OPTARG ;; m) MSG=$OPTARG ;; f) FILE=$OPTARG ;; b) B64=$OPTARG ;;
+    r) RETRIES=$OPTARG ;; v) VERBOSE=1 ;; h) usage 0 ;; *) usage 3 ;;
+  esac
+done
+
+[ -n "$TARGET" ] || { echo "ERROR: -t TARGET is required" >&2; usage 3; }
+if   [ -n "$B64" ];  then MSG=$(printf '%s' "$B64" | base64 -d) || { echo "ERROR: bad -b base64" >&2; exit 3; }
+elif [ -n "$FILE" ]; then [ -r "$FILE" ] || { echo "ERROR: cannot read $FILE" >&2; exit 3; }; MSG=$(cat -- "$FILE")
+elif [ -z "$MSG" ] && [ ! -t 0 ]; then MSG=$(cat)
+fi
+[ -n "$MSG" ] || { echo "ERROR: empty message (use -m, -f, or stdin)" >&2; exit 3; }
+
+# Target must resolve to a live pane.
+if ! tmux list-panes -t "$TARGET" >/dev/null 2>&1; then
+  echo "ERROR: tmux target not found: $TARGET" >&2; exit 1
+fi
+
+QUEUED_RE='Press up to edit queued messages'
+# A distinctive tail of the message to spot an unsubmitted draft on the input line.
+snippet=$(printf '%s' "$MSG" | tr '\n' ' ' | tr -s ' ' | sed 's/[^[:print:]]//g' | tail -c 32)
+
+# 1) Paste the body as a bracketed paste so multi-line content does not submit
+#    line-by-line. load-buffer/paste-buffer is far safer than `send-keys -l`.
+printf '%s' "$MSG" | tmux load-buffer -b __mosaic_send -
+# -p = bracketed paste when the client supports it; fall back if not.
+tmux paste-buffer -d -p -b __mosaic_send -t "$TARGET" 2>/dev/null \
+  || tmux paste-buffer -d -b __mosaic_send -t "$TARGET"
+sleep 0.5
+
+# 2) Submit, then verify; flush with another Enter if it is still a draft.
+status="sent"
+for attempt in $(seq 1 $((RETRIES + 1))); do
+  tmux send-keys -t "$TARGET" Enter
+  sleep 1.2
+  pane=$(tmux capture-pane -t "$TARGET" -p 2>/dev/null)
+
+  if printf '%s' "$pane" | grep -qF "$QUEUED_RE"; then
+    status="queued"; break
+  fi
+  # Draft heuristic: the prompt glyph line still carries our message tail.
+  # (Submitted messages scroll up into history; a draft stays on the ❯ line.)
+  promptline=$(printf '%s' "$pane" | grep -E '❯|^>|│ >' | tail -1)
+  if [ -n "$snippet" ] && printf '%s' "$promptline" | grep -qF "$snippet"; then
+    status="draft"; continue
+  fi
+  status="delivered"; break
+done
+
+[ "$VERBOSE" = 1 ] && { echo "--- pane tail ($TARGET) ---"; printf '%s\n' "$pane" | tail -4; echo "---"; }
+
+case "$status" in
+  delivered) echo "✓ delivered to $TARGET"; exit 0 ;;
+  queued)    echo "✓ queued to $TARGET (agent busy — will process when it returns to prompt)"; exit 0 ;;
+  draft)     echo "✗ still an unsubmitted draft on $TARGET after $RETRIES flush attempts" >&2; exit 2 ;;
+  *)         echo "✓ sent to $TARGET (submission state indeterminate; verify with -v)"; exit 0 ;;
+esac

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')

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

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

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');
+    },
+  );
+});

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>;

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);

packages/storage/src/migrate-tier.integration.test.ts

@@ -16,8 +16,15 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-import { users, teams, teamMembers, conversations, messages } from '@mosaicstack/db';
-import { createPgliteDbWithVector, runPgliteMigrations } from './test-utils/pglite-with-vector.js';
+import {
+  users,
+  teams,
+  teamMembers,
+  conversations,
+  messages,
+  createPgliteDb,
+  runPgliteMigrations,
+} from '@mosaicstack/db';
 
 import postgres from 'postgres';
 import { afterAll, describe, expect, it } from 'vitest';
@@ -102,11 +109,8 @@ describe.skipIf(!run)('migrate-tier — PGlite → federated PG', () => {
     /* ---- 1. Create a temp PGlite db ---------------------------------- */
 
     pgliteDataDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fed-m1-08-'));
-    const handle = createPgliteDbWithVector(pgliteDataDir);
-
-    // Run Drizzle migrations against PGlite.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    await runPgliteMigrations(handle.db as any);
+    const handle = createPgliteDb(pgliteDataDir);
+    await runPgliteMigrations(handle);
 
     /* ---- 2. Seed representative data --------------------------------- */
 

packages/storage/src/test-utils/pglite-with-vector.ts

@@ -1,52 +0,0 @@
-/**
- * Test-only helpers for creating a PGlite database with the pgvector extension
- * and running Drizzle migrations against it.
- *
- * These are intentionally NOT exported from @mosaicstack/db to avoid pulling
- * the WASM vector bundle into the public API surface.
- */
-
-import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
-
-import { PGlite } from '@electric-sql/pglite';
-import { vector } from '@electric-sql/pglite/vector';
-import { drizzle } from 'drizzle-orm/pglite';
-import { migrate as migratePglite } from 'drizzle-orm/pglite/migrator';
-import type { PgliteDatabase } from 'drizzle-orm/pglite';
-import * as schema from '@mosaicstack/db';
-import type { DbHandle } from '@mosaicstack/db';
-
-/**
- * Create a PGlite DB handle with the pgvector extension loaded.
- * Required for running Drizzle migrations that include `CREATE EXTENSION vector`.
- */
-export function createPgliteDbWithVector(dataDir: string): DbHandle {
-  const client = new PGlite(dataDir, { extensions: { vector } });
-  const db = drizzle(client, { schema });
-  return {
-    db: db as unknown as DbHandle['db'],
-    close: async () => {
-      await client.close();
-    },
-  };
-}
-
-/**
- * Run Drizzle migrations against an already-open PGlite database handle.
- * Resolves the migrations folder from @mosaicstack/db's installed location.
- *
- * @param db  A PgliteDatabase instance (from drizzle-orm/pglite).
- */
-export async function runPgliteMigrations(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  db: PgliteDatabase<any>,
-): Promise<void> {
-  // Resolve @mosaicstack/db package root to locate its drizzle migrations folder.
-  const _require = createRequire(import.meta.url);
-  const dbPkgMain = _require.resolve('@mosaicstack/db');
-  // dbPkgMain → …/packages/db/dist/index.js  →  dirname = dist/
-  // go up one level from dist/ to find the sibling drizzle/ folder
-  const migrationsFolder = resolve(dirname(dbPkgMain), '../drizzle');
-  await migratePglite(db, { migrationsFolder });
-}

pnpm-lock.yaml

@@ -39,6 +39,25 @@ 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)
 
+  apps/appservice:
+    dependencies:
+      '@mosaicstack/appservice':
+        specifier: workspace:*
+        version: link:../../packages/appservice
+    devDependencies:
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.15
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      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)
+
   apps/gateway:
     dependencies:
       '@anthropic-ai/sdk':
@@ -179,6 +198,9 @@ importers:
       socket.io:
         specifier: ^4.8.0
         version: 4.8.3
+      undici:
+        specifier: ^7.24.6
+        version: 7.24.6
       uuid:
         specifier: ^11.0.0
         version: 11.1.0
@@ -294,6 +316,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':
@@ -713,10 +747,10 @@ importers:
     dependencies:
       '@mariozechner/pi-agent-core':
         specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
       '@mariozechner/pi-ai':
         specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
       '@sinclair/typebox':
         specifier: ^0.34.41
         version: 0.34.48
@@ -6993,10 +7027,6 @@ packages:
     resolution: {integrity: sha512-gBLkYIlEnSp8pFbT64yFgGE6UIB9tAkhukC23PmMDCe5Nd+cRqKxSjw5y54MK2AZMgZfJWMaNE4nYUHgi1XEOw==}
     engines: {node: '>=18.17'}
 
-  undici@7.24.3:
-    resolution: {integrity: sha512-eJdUmK/Wrx2d+mnWWmwwLRyA7OQCkLap60sk3dOK4ViZR7DKwwptwuIvFBg2HaiP9ESaEdhtpSymQPvytpmkCA==}
-    engines: {node: '>=20.18.1'}
-
   undici@7.24.6:
     resolution: {integrity: sha512-Xi4agocCbRzt0yYMZGMA6ApD7gvtUFaxm4ZmeacWI4cZxaF6C+8I8QfofC20NAePiB/IcvZmzkJ7XPa471AEtA==}
     engines: {node: '>=20.18.1'}
@@ -7329,12 +7359,6 @@ snapshots:
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
 
-  '@anthropic-ai/sdk@0.73.0(zod@3.25.76)':
-    dependencies:
-      json-schema-to-ts: 3.1.1
-    optionalDependencies:
-      zod: 3.25.76
-
   '@anthropic-ai/sdk@0.73.0(zod@4.3.6)':
     dependencies:
       json-schema-to-ts: 3.1.1
@@ -8676,18 +8700,6 @@ snapshots:
       - ws
       - zod
 
-  '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
-    dependencies:
-      '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
-    transitivePeerDependencies:
-      - '@modelcontextprotocol/sdk'
-      - aws-crt
-      - bufferutil
-      - supports-color
-      - utf-8-validate
-      - ws
-      - zod
-
   '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
     dependencies:
       '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
@@ -8736,30 +8748,6 @@ snapshots:
       - ws
       - zod
 
-  '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
-    dependencies:
-      '@anthropic-ai/sdk': 0.73.0(zod@3.25.76)
-      '@aws-sdk/client-bedrock-runtime': 3.1008.0
-      '@google/genai': 1.45.0(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))
-      '@mistralai/mistralai': 1.14.1
-      '@sinclair/typebox': 0.34.48
-      ajv: 8.18.0
-      ajv-formats: 3.0.1(ajv@8.18.0)
-      chalk: 5.6.2
-      openai: 6.26.0(ws@8.20.0)(zod@3.25.76)
-      partial-json: 0.1.7
-      proxy-agent: 6.5.0
-      undici: 7.24.3
-      zod-to-json-schema: 3.25.1(zod@3.25.76)
-    transitivePeerDependencies:
-      - '@modelcontextprotocol/sdk'
-      - aws-crt
-      - bufferutil
-      - supports-color
-      - utf-8-validate
-      - ws
-      - zod
-
   '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
     dependencies:
       '@anthropic-ai/sdk': 0.73.0(zod@4.3.6)
@@ -8773,7 +8761,7 @@ snapshots:
       openai: 6.26.0(ws@8.20.0)(zod@4.3.6)
       partial-json: 0.1.7
       proxy-agent: 6.5.0
-      undici: 7.24.3
+      undici: 7.24.6
       zod-to-json-schema: 3.25.1(zod@4.3.6)
     transitivePeerDependencies:
       - '@modelcontextprotocol/sdk'
@@ -12632,7 +12620,7 @@ snapshots:
       saxes: 6.0.0
       symbol-tree: 3.2.4
       tough-cookie: 6.0.1
-      undici: 7.24.3
+      undici: 7.24.6
       w3c-xmlserializer: 5.0.0
       webidl-conversions: 8.0.1
       whatwg-mimetype: 5.0.0
@@ -13352,11 +13340,6 @@ snapshots:
     dependencies:
       mimic-function: 5.0.1
 
-  openai@6.26.0(ws@8.20.0)(zod@3.25.76):
-    optionalDependencies:
-      ws: 8.20.0
-      zod: 3.25.76
-
   openai@6.26.0(ws@8.20.0)(zod@4.3.6):
     optionalDependencies:
       ws: 8.20.0
@@ -14488,8 +14471,6 @@ snapshots:
 
   undici@6.21.3: {}
 
-  undici@7.24.3: {}
-
   undici@7.24.6: {}
 
   unhomoglyph@1.0.6: {}

scratchpads/contract-thin-core.md

@@ -0,0 +1,35 @@
+# Scratchpad — Thin-core prompt diet (#528)
+
+**Branch:** `feat/contract-thin-core` · **Issue:** #528 · **Mode:** Delivery
+
+## Objective
+
+Cut the always-injected contract (`defaults/AGENTS.md` + `defaults/TOOLS.md` + `runtime/claude/RUNTIME.md`, inlined every turn by the launcher) without losing any hard gate. Restore the original "thin core + on-demand guides" intent.
+
+## Change
+
+- `defaults/AGENTS.md` → thin core: 12 hard gates verbatim, 37 operating rules condensed to ~15 bullets (detail already in `guides/E2E-DELIVERY.md`), Superpowers condensed, load order made on-demand (no halt-on-missing for STANDARDS), conditional guide-loading index retained.
+- `defaults/TOOLS.md` → index; full catalog moved to new `guides/TOOLS-REFERENCE.md` (read on demand).
+- `runtime/claude/RUNTIME.md` → slimmed (dedup tier table, terser pointers).
+
+## Method (autoresearch-style validation)
+
+1. Built a 9-probe role battery (backend/deploy/review/orchestrate/secrets/docs/simple-trap/no-stop-at-PR/agent-work) + a deterministic 18-signature gate-checklist.
+2. Headless interactive runs (Claude Max **subscription**, tmux — no API), scored by per-probe rubric.
+3. Keep-or-discard hill-climb (token cost gated by per-probe fidelity) proved the method; final design re-derived against THIS repo's content (diet-only, no drifted-deployment content imported).
+
+## Validation evidence
+
+- Gate-checklist: ALL gates + critical rules + mode lines + sequential-thinking + OpenBrain + Superpowers present.
+- A/B on real repo content: **thin 7/9 vs monolith 5/9** probes; strictly better on deploy/review/simple-task; composed **8,827 → 4,122 tok (−53%)**.
+- p11 (don't-stop-at-PR): 3→2/3 on one rubric line — verified a scorer/phrasing artifact (answer correctly cites gates §5/§9 + close-issue; gate verbatim-present). Variance: thin 2/2/3, v0 3/3/3.
+
+## Decisions / risks
+
+- **Diet-only** vs repo content (user decision). Did NOT import web1's Gate 13-15 / federated memory / OpenViking — canonical repo is behind those deployments; flagged for separate reconciliation.
+- AGENTS/TOOLS are shared across runtimes → diet benefits codex/pi/opencode too; RUNTIME change is claude-only.
+- p11 accepted as-is (user decision) — not gaming the rubric.
+
+## Status
+
+PR open, paused for maintainer merge ratification (fleet-governing change). `mosaic upgrade` will propagate on merge.

scratchpads/fix-db-bootstrap-migrations.md

@@ -0,0 +1,125 @@
+# fix(db): bootstrap migrations on local-tier gateway startup
+
+## Problem
+
+Fresh `mosaic gateway install` (npm-installed) leaves the gateway DB schema empty:
+
+```
+relation "users" does not exist
+```
+
+Sign-in 500s, `auth users create` says "Not signed in", `admin/bootstrap setup`
+also fails — every entry point queries `users` before doing anything else.
+
+## Scope
+
+This PR fixes the **local (PGlite) tier** end-to-end. The postgres-tier path
+has additional pre-existing bugs (see "Known issues, out of scope" below) and
+needs a separate change with real Postgres validation.
+
+## Root causes addressed (5 stacked bugs on the local-tier path)
+
+1. **`packages/db/package.json` `files: ["dist"]`** — the `drizzle/` SQL
+   migrations folder is excluded from the published tarball. Even if a
+   migrate runner existed, it would have nothing to apply.
+
+2. **`packages/db/src/migrate.ts`** only supports `postgres-js`. Local-tier
+   gateways use embedded PGlite, which can't be reached over a postgres wire
+   protocol — so `runMigrations()` is unusable for the local tier.
+
+3. **`apps/gateway/src/database/database.module.ts`** never invokes
+   migrations at startup. The module creates the DB handle and storage
+   adapter, but no consumer calls `.migrate()` on either. `mosaic storage
+migrate` CLI even claims "pglite runs schema setup automatically on first
+   connection via `adapter.migrate()`" — but `adapter.migrate()` is only
+   called by tests, never at runtime.
+
+4. **`createPgliteDb` does not load the pgvector extension.** Migration 0001
+   declares `CREATE EXTENSION IF NOT EXISTS vector;` for the
+   `insights.embedding` column. Bare PGlite has no pgvector — the migration
+   fails on extension control file lookup.
+
+5. **Drizzle's PG migrator wraps every migration in one outer transaction.**
+   Migration 0009 does `ALTER TYPE grant_status ADD VALUE 'pending'` and then
+   `ALTER TABLE federation_grants ALTER COLUMN status SET DEFAULT 'pending'`.
+   Postgres' `check_safe_enum_use` rejects the second statement because the
+   new enum value isn't committed yet. Splitting the migration into two
+   files doesn't help — drizzle batches all migrations into one outer tx.
+
+## Fix
+
+- `packages/db/package.json` — ship `drizzle/` in `files`.
+- `packages/db/src/client-pglite.ts` — load `@electric-sql/pglite/vector`.
+- `packages/db/src/migrate.ts` — add `runPgliteMigrations(handle)`. Walks the
+  Drizzle journal and runs each statement-breakpoint chunk through PGlite's
+  `client.exec()` (Simple Query protocol → autocommit per statement). Writes
+  to the standard `drizzle.__drizzle_migrations` ledger so the result is
+  interoperable with `runMigrations()` on a postgres-backed deployment.
+  Per-statement try/catch surfaces which statement of which migration failed
+  and the ledger row is only written on full success.
+- `packages/db/src/index.ts` — re-export.
+- `apps/gateway/src/database/database.module.ts` — implement `OnModuleInit`:
+  - Local tier → `runPgliteMigrations(handle)`, then `storageAdapter.migrate()`
+    (the local storage adapter has its own kv tables in a separate PGlite dir).
+  - Postgres tier → `storageAdapter.migrate()` only, since
+    `PostgresAdapter.migrate()` already calls `runMigrations(url)` against
+    the same DATABASE_URL — we deliberately don't double-call.
+
+  NestJS awaits `onModuleInit` before `app.listen()`, so DB-dependent modules
+  see a populated schema before any HTTP traffic is accepted.
+
+- `packages/storage/src/test-utils/pglite-with-vector.ts` — **deleted**.
+  The "intentionally not exported" rationale is moot now that migration 0001
+  forces pgvector load anyway. `migrate-tier.integration.test.ts` switched
+  to `createPgliteDb` + `runPgliteMigrations` from `@mosaicstack/db`.
+
+## Tests
+
+`packages/db/src/migrate.test.ts`:
+
+- Verifies `runPgliteMigrations` creates the BetterAuth tables (the original
+  failure mode).
+- Idempotence (transitively re-runs migration 0009).
+- Partial-failure: pre-creates a conflicting `users` table, asserts the
+  thrown error includes statement context (`hash=… statement #N failed`)
+  and that no ledger row was written.
+
+## QA evidence
+
+End-to-end on a fresh PGlite install:
+
+- `[DatabaseModule] Applying PGlite schema migrations...` then
+  `Initializing storage adapter (pglite)...` in startup log.
+- `GET /api/bootstrap/status` → `{"needsSetup":true}` HTTP 200 (was 500
+  with `relation "users" does not exist`).
+- `POST /api/bootstrap/setup` with empty body → HTTP 400 with Zod
+  validation error (was 500), confirming the request reached the
+  validator past the table-existence check.
+
+## Known issues, out of scope (file separately)
+
+- **Postgres-tier first install is still broken.** `runMigrations()` uses
+  Drizzle's `migratePostgres`, which has the same outer-transaction problem
+  as PGlite's migrator. A fresh standalone-tier install would also fail at
+  migration 0009. Inline TODO in `migrate.ts:31-35` flags this. Fixing it
+  needs either (a) a shared per-statement loop reused for both drivers, or
+  (b) splitting migration 0009.
+- **`drizzle/meta/_journal.json` has 0009 ordered before 0008** (`when`
+  values `1745280000000` < `1776822435828`). `migratePostgres` skips by
+  `created_at < folderMillis`, so on a postgres deployment that already
+  applied 0008, 0009 would be skipped forever. Our hash-based skip in the
+  PGlite path sidesteps this.
+- **No advisory lock around the migration loop.** Two gateway processes
+  pointed at the same DATABASE_URL would race. PGlite is single-process by
+  file lock so the local tier is fine; postgres-tier deployments should add
+  `pg_advisory_lock(<deterministic-id>)` around the loop in a follow-up.
+- **`mosaic storage migrate` CLI message is misleading** — it claims
+  "automatic on first connection via adapter.migrate()" but the adapter
+  doesn't self-migrate. With this PR the gateway invokes it explicitly, but
+  the CLI message could still be tightened.
+- **Crash mid-migration leaves a partial-state PGlite DB without a ledger
+  row.** Detected loudly on next boot (the replay errors on "already
+  exists"), but recovery is manual (drop the partially-applied objects or
+  insert the migration hash into `drizzle.__drizzle_migrations`). A robust
+  fix would add a "started_at" column to a sidecar table to detect
+  half-applied state and refuse to start with actionable guidance.

tools/federation-harness/README.md

@@ -0,0 +1,254 @@
+# Federation Test Harness
+
+Local two-gateway federation test infrastructure for Mosaic Stack M3+.
+
+This harness boots two real gateway instances (`gateway-a`, `gateway-b`) on a
+shared Docker bridge network, each backed by its own Postgres (pgvector) +
+Valkey, sharing a single Step-CA. It is the test bed for all M3+ federation
+E2E tests.
+
+## Prerequisites
+
+- Docker with Compose v2 (`docker compose version` ≥ 2.20)
+- pnpm (for running via repo scripts)
+- `infra/step-ca/dev-password` must exist (copy from `infra/step-ca/dev-password.example`)
+
+## Network Topology
+
+```
+Host machine
+├── localhost:14001  →  gateway-a   (Server A — home / requesting)
+├── localhost:14002  →  gateway-b   (Server B — work / serving)
+├── localhost:15432  →  postgres-a
+├── localhost:15433  →  postgres-b
+├── localhost:16379  →  valkey-a
+├── localhost:16380  →  valkey-b
+└── localhost:19000  →  step-ca     (shared CA)
+
+Docker network: fed-test-net (bridge)
+  gateway-a ←──── mTLS ────→ gateway-b
+             ↘             ↗
+               step-ca
+```
+
+Ports are chosen to avoid collision with the base dev stack (5433, 6380, 14242, 9000).
+
+## Starting the Harness
+
+```bash
+# From repo root
+docker compose -f tools/federation-harness/docker-compose.two-gateways.yml up -d
+
+# Wait for all services to be healthy (~60-90s on first boot due to NestJS cold start)
+docker compose -f tools/federation-harness/docker-compose.two-gateways.yml ps
+```
+
+## Seeding Test Data
+
+The seed script provisions three grant scope variants (A, B, C) and walks the
+full enrollment flow so Server A ends up with active peers pointing at Server B.
+
+```bash
+# Assumes stack is already running
+pnpm tsx tools/federation-harness/seed.ts
+
+# Or boot + seed in one step
+pnpm tsx tools/federation-harness/seed.ts --boot
+```
+
+### Scope Variants
+
+| Variant | Resources          | Filters                            | Excluded    | Purpose                         |
+| ------- | ------------------ | ---------------------------------- | ----------- | ------------------------------- |
+| A       | tasks, notes       | include_personal: true             | (none)      | Personal data federation        |
+| B       | tasks              | include_teams: ['T1'], no personal | (none)      | Team-scoped, no personal        |
+| C       | tasks, credentials | include_personal: true             | credentials | Sanity: excluded wins over list |
+
+## Using from Vitest
+
+```ts
+import {
+  bootHarness,
+  tearDownHarness,
+  serverA,
+  serverB,
+  seed,
+} from '../../tools/federation-harness/harness.js';
+import type { HarnessHandle } from '../../tools/federation-harness/harness.js';
+
+let handle: HarnessHandle;
+
+beforeAll(async () => {
+  handle = await bootHarness();
+}, 180_000); // allow 3 min for Docker pull + NestJS cold start
+
+afterAll(async () => {
+  await tearDownHarness(handle);
+});
+
+test('variant A: list tasks returns personal tasks', async () => {
+  // NOTE: Only 'all' is supported for now — per-variant narrowing is M3-11.
+  const seedResult = await seed(handle, 'all');
+  const a = serverA(handle);
+
+  const res = await fetch(`${a.baseUrl}/api/federation/tasks`, {
+    headers: { 'x-federation-grant': seedResult.grants.variantA.id },
+  });
+  expect(res.status).toBe(200);
+});
+```
+
+> **Note:** `seed()` bootstraps a fresh admin user on each gateway via
+> `POST /api/bootstrap/setup`. Both gateways must have zero users (pristine DB).
+> If either gateway already has users, `seed()` throws with a clear error.
+> Reset state with `docker compose down -v`.
+
+The `bootHarness()` function is **idempotent**: if both gateways are already
+healthy, it reuses the running stack and returns `ownedStack: false`. Tests
+should not call `tearDownHarness` when `ownedStack` is false unless they
+explicitly want to shut down a shared stack.
+
+## Vitest Config (pnpm test:federation)
+
+Add to `vitest.config.ts` at repo root (or a dedicated config):
+
+```ts
+// vitest.federation.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['**/*.federation.test.ts'],
+    testTimeout: 60_000,
+    hookTimeout: 180_000,
+    reporters: ['verbose'],
+  },
+});
+```
+
+Then add to root `package.json`:
+
+```json
+"test:federation": "vitest run --config vitest.federation.config.ts"
+```
+
+## Nuking State
+
+```bash
+# Remove containers AND volumes (ephemeral state — CA keys, DBs, everything)
+docker compose -f tools/federation-harness/docker-compose.two-gateways.yml down -v
+```
+
+On next `up`, Step-CA re-initialises from scratch and generates new CA keys.
+
+## Step-CA Root Certificate
+
+The CA root lives in the `fed-harness-step-ca` Docker volume at
+`/home/step/certs/root_ca.crt`. To extract it to the host:
+
+```bash
+docker run --rm \
+  -v fed-harness-step-ca:/home/step \
+  alpine cat /home/step/certs/root_ca.crt > /tmp/fed-harness-root-ca.crt
+```
+
+## Troubleshooting
+
+### Port conflicts
+
+Default host ports: 14001, 14002, 15432, 15433, 16379, 16380, 19000.
+Override via environment variables before `docker compose up`:
+
+```bash
+GATEWAY_A_HOST_PORT=14101 GATEWAY_B_HOST_PORT=14102 \
+  docker compose -f tools/federation-harness/docker-compose.two-gateways.yml up -d
+```
+
+### Image pull failures
+
+The gateway image is digest-pinned to:
+
+```
+git.mosaicstack.dev/mosaicstack/stack/gateway@sha256:1069117740e00ccfeba357cae38c43f3729fe5ae702740ce474f6512414d7c02
+```
+
+(sha-9f1a081, post-#491 IMG-FIX)
+
+If the registry is unreachable, Docker will use the locally cached image if
+present. If no local image exists, the compose up will fail with a pull error.
+In that case:
+
+1. Ensure you can reach `git.mosaicstack.dev` (VPN, DNS, etc.).
+2. Log in: `docker login git.mosaicstack.dev`
+3. Pull manually: `docker pull git.mosaicstack.dev/mosaicstack/stack/gateway@sha256:1069117740e00ccfeba357cae38c43f3729fe5ae702740ce474f6512414d7c02`
+
+### NestJS cold start
+
+Gateway containers take 40–60 seconds to become healthy on first boot (Node.js
+module resolution + NestJS DI bootstrap). The `start_period: 60s` in the
+compose healthcheck covers this. `bootHarness()` polls for up to 3 minutes.
+
+### Step-CA startup
+
+Step-CA initialises on first boot (generates CA keys). This takes ~5-10s.
+The `start_period: 30s` in the healthcheck covers it. Both gateways wait for
+Step-CA to be healthy before starting (`depends_on: step-ca: condition: service_healthy`).
+
+### dev-password missing
+
+The Step-CA container requires `infra/step-ca/dev-password` to be mounted.
+Copy the example and set a local password:
+
+```bash
+cp infra/step-ca/dev-password.example infra/step-ca/dev-password
+# Edit the file to set your preferred dev CA password
+```
+
+The file is `.gitignore`d — do not commit it.
+
+## Image Digest Note
+
+The gateway image is pinned to `sha256:1069117740e00ccfeba357cae38c43f3729fe5ae702740ce474f6512414d7c02`
+(sha-9f1a081). This is the digest promoted by PR #491 (IMG-FIX). The `latest`
+tag is forbidden per Mosaic image policy. When a new gateway build is promoted,
+update the digest in `docker-compose.two-gateways.yml` and in this file.
+
+## Known Limitations
+
+### BETTER_AUTH_URL enrollment URL bug (upstream production code — not yet fixed)
+
+`apps/gateway/src/federation/federation.controller.ts:145` constructs the
+enrollment URL using `process.env['BETTER_AUTH_URL'] ?? 'http://localhost:14242'`.
+This is an upstream bug: `BETTER_AUTH_URL` is the Better Auth origin (typically
+the web app), not the gateway's own base URL. In non-harness deployments this
+produces an enrollment URL pointing to the wrong host or port.
+
+**How the harness handles this:**
+
+1. **In-cluster calls (container-to-container):** The compose file sets
+   `BETTER_AUTH_URL: 'http://gateway-b:3000'` so the enrollment URL returned by
+   the gateway uses the Docker internal hostname. This lets other containers in the
+   `fed-test-net` network resolve and reach Server B's enrollment endpoint.
+
+2. **Host-side URL rewrite (seed script):** The `seed.ts` script runs on the host
+   machine where `gateway-b` is not a resolvable hostname. Before calling
+   `fetch(enrollmentUrl, ...)`, the seed script rewrites the URL: it extracts only
+   the token path segment from `enrollmentUrl` and reassembles the URL using the
+   host-accessible `serverBUrl` (default: `http://localhost:14002`). This lets the
+   seed script redeem enrollment tokens from the host without being affected by the
+   in-cluster hostname in the returned URL.
+
+**TODO:** Fix `federation.controller.ts` to derive the enrollment URL from its own
+listening address (e.g. `GATEWAY_BASE_URL` env var or a dedicated
+`FEDERATION_ENROLLMENT_BASE_URL` env var) rather than reusing `BETTER_AUTH_URL`.
+Tracked as a follow-up to PR #505 — do not bundle with harness changes.
+
+## Permanent Infrastructure
+
+This harness is designed to outlive M3 and be reused by M4+ milestone tests.
+It is not a throwaway scaffold — treat it as production test infrastructure:
+
+- Keep it idempotent.
+- Do not hardcode test assumptions in the harness layer (put them in tests).
+- Update the seed script when new scope variants are needed.
+- The README and harness should be kept in sync as the federation API evolves.

tools/federation-harness/docker-compose.two-gateways.yml

@@ -0,0 +1,247 @@
+# tools/federation-harness/docker-compose.two-gateways.yml
+#
+# Two-gateway federation test harness — local-only, no Portainer/Swarm needed.
+#
+# USAGE (manual):
+#   docker compose -f tools/federation-harness/docker-compose.two-gateways.yml up -d
+#   docker compose -f tools/federation-harness/docker-compose.two-gateways.yml down -v
+#
+# USAGE (from harness.ts):
+#   const handle = await bootHarness();
+#   ...
+#   await tearDownHarness(handle);
+#
+# TOPOLOGY:
+#   gateway-a  — "home" instance (Server A, the requesting side)
+#     └── postgres-a  (pgvector/pg17, port 15432)
+#     └── valkey-a    (port 16379)
+#   gateway-b  — "work" instance (Server B, the serving side)
+#     └── postgres-b  (pgvector/pg17, port 15433)
+#     └── valkey-b    (port 16380)
+#   step-ca    — shared CA for both gateways (port 19000)
+#
+# All services share the `fed-test-net` bridge network.
+# Host port ranges (15432-15433, 16379-16380, 14001-14002, 19000) are chosen
+# to avoid collision with the base dev stack (5433, 6380, 14242, 9000).
+#
+# IMAGE:
+#   Pinned to the immutable digest sha256:1069117740e00ccfeba357cae38c43f3729fe5ae702740ce474f6512414d7c02
+#   (sha-9f1a081, post-#491 IMG-FIX, smoke-tested locally).
+#   Update this digest only after a new CI build is promoted to the registry.
+#
+# STEP-CA:
+#   Single shared Step-CA instance. Both gateways connect to it.
+#   CA volume is ephemeral per `docker compose down -v`; regenerated on next up.
+#   The harness seed script provisions the CA roots cross-trust after first boot.
+
+services:
+  # ─── Shared Certificate Authority ────────────────────────────────────────────
+  step-ca:
+    image: smallstep/step-ca:0.27.4
+    container_name: fed-harness-step-ca
+    restart: unless-stopped
+    ports:
+      - '${STEP_CA_HOST_PORT:-19000}:9000'
+    volumes:
+      - step_ca_data:/home/step
+      - ../../infra/step-ca/init.sh:/usr/local/bin/mosaic-step-ca-init.sh:ro
+      - ../../infra/step-ca/templates:/etc/step-ca-templates:ro
+      - ../../infra/step-ca/dev-password:/run/secrets/ca_password:ro
+    entrypoint: ['/bin/sh', '/usr/local/bin/mosaic-step-ca-init.sh']
+    networks:
+      - fed-test-net
+    healthcheck:
+      test:
+        [
+          'CMD',
+          'step',
+          'ca',
+          'health',
+          '--ca-url',
+          'https://localhost:9000',
+          '--root',
+          '/home/step/certs/root_ca.crt',
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  # ─── Server A — Home / Requesting Gateway ────────────────────────────────────
+  postgres-a:
+    image: pgvector/pgvector:pg17
+    container_name: fed-harness-postgres-a
+    restart: unless-stopped
+    ports:
+      - '${PG_A_HOST_PORT:-15432}:5432'
+    environment:
+      POSTGRES_USER: mosaic
+      POSTGRES_PASSWORD: mosaic
+      POSTGRES_DB: mosaic
+    volumes:
+      - pg_a_data:/var/lib/postgresql/data
+      - ../../infra/pg-init:/docker-entrypoint-initdb.d:ro
+    networks:
+      - fed-test-net
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U mosaic']
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  valkey-a:
+    image: valkey/valkey:8-alpine
+    container_name: fed-harness-valkey-a
+    restart: unless-stopped
+    ports:
+      - '${VALKEY_A_HOST_PORT:-16379}:6379'
+    volumes:
+      - valkey_a_data:/data
+    networks:
+      - fed-test-net
+    healthcheck:
+      test: ['CMD', 'valkey-cli', 'ping']
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  gateway-a:
+    image: git.mosaicstack.dev/mosaicstack/stack/gateway@sha256:1069117740e00ccfeba357cae38c43f3729fe5ae702740ce474f6512414d7c02
+    # Tag for human reference: sha-9f1a081 (post-#491 IMG-FIX; smoke-tested locally)
+    container_name: fed-harness-gateway-a
+    restart: unless-stopped
+    ports:
+      - '${GATEWAY_A_HOST_PORT:-14001}:3000'
+    environment:
+      MOSAIC_TIER: federated
+      DATABASE_URL: postgres://mosaic:mosaic@postgres-a:5432/mosaic
+      VALKEY_URL: redis://valkey-a:6379
+      GATEWAY_PORT: '3000'
+      GATEWAY_CORS_ORIGIN: 'http://localhost:14001'
+      BETTER_AUTH_SECRET: harness-secret-server-a-do-not-use-in-prod
+      BETTER_AUTH_URL: 'http://gateway-a:3000'
+      STEP_CA_URL: 'https://step-ca:9000'
+      FEDERATION_PEER_HOSTNAME: gateway-a
+      # Bootstrap password for POST /api/bootstrap/setup — used by seed.ts to create
+      # the first admin user. Only valid on a pristine (zero-user) database.
+      # Not the same as ADMIN_API_KEY — there is no static API key in the gateway.
+      ADMIN_BOOTSTRAP_PASSWORD: harness-admin-password-a
+    depends_on:
+      postgres-a:
+        condition: service_healthy
+      valkey-a:
+        condition: service_healthy
+      step-ca:
+        condition: service_healthy
+    networks:
+      - fed-test-net
+    healthcheck:
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('http').get('http://127.0.0.1:3000/api/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+
+  # ─── Server B — Work / Serving Gateway ──────────────────────────────────────
+  postgres-b:
+    image: pgvector/pgvector:pg17
+    container_name: fed-harness-postgres-b
+    restart: unless-stopped
+    ports:
+      - '${PG_B_HOST_PORT:-15433}:5432'
+    environment:
+      POSTGRES_USER: mosaic
+      POSTGRES_PASSWORD: mosaic
+      POSTGRES_DB: mosaic
+    volumes:
+      - pg_b_data:/var/lib/postgresql/data
+      - ../../infra/pg-init:/docker-entrypoint-initdb.d:ro
+    networks:
+      - fed-test-net
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U mosaic']
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  valkey-b:
+    image: valkey/valkey:8-alpine
+    container_name: fed-harness-valkey-b
+    restart: unless-stopped
+    ports:
+      - '${VALKEY_B_HOST_PORT:-16380}:6379'
+    volumes:
+      - valkey_b_data:/data
+    networks:
+      - fed-test-net
+    healthcheck:
+      test: ['CMD', 'valkey-cli', 'ping']
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  gateway-b:
+    image: git.mosaicstack.dev/mosaicstack/stack/gateway@sha256:1069117740e00ccfeba357cae38c43f3729fe5ae702740ce474f6512414d7c02
+    # Tag for human reference: sha-9f1a081 (post-#491 IMG-FIX; smoke-tested locally)
+    container_name: fed-harness-gateway-b
+    restart: unless-stopped
+    ports:
+      - '${GATEWAY_B_HOST_PORT:-14002}:3000'
+    environment:
+      MOSAIC_TIER: federated
+      DATABASE_URL: postgres://mosaic:mosaic@postgres-b:5432/mosaic
+      VALKEY_URL: redis://valkey-b:6379
+      GATEWAY_PORT: '3000'
+      GATEWAY_CORS_ORIGIN: 'http://localhost:14002'
+      BETTER_AUTH_SECRET: harness-secret-server-b-do-not-use-in-prod
+      BETTER_AUTH_URL: 'http://gateway-b:3000'
+      STEP_CA_URL: 'https://step-ca:9000'
+      FEDERATION_PEER_HOSTNAME: gateway-b
+      # Bootstrap password for POST /api/bootstrap/setup — used by seed.ts to create
+      # the first admin user. Only valid on a pristine (zero-user) database.
+      # Not the same as ADMIN_API_KEY — there is no static API key in the gateway.
+      ADMIN_BOOTSTRAP_PASSWORD: harness-admin-password-b
+    depends_on:
+      postgres-b:
+        condition: service_healthy
+      valkey-b:
+        condition: service_healthy
+      step-ca:
+        condition: service_healthy
+    networks:
+      - fed-test-net
+    healthcheck:
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('http').get('http://127.0.0.1:3000/api/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+
+networks:
+  fed-test-net:
+    name: fed-test-net
+    driver: bridge
+
+volumes:
+  step_ca_data:
+    name: fed-harness-step-ca
+  pg_a_data:
+    name: fed-harness-pg-a
+  valkey_a_data:
+    name: fed-harness-valkey-a
+  pg_b_data:
+    name: fed-harness-pg-b
+  valkey_b_data:
+    name: fed-harness-valkey-b

tools/federation-harness/harness.ts

@@ -0,0 +1,290 @@
+/**
+ * tools/federation-harness/harness.ts
+ *
+ * Vitest-consumable helpers for the two-gateway federation harness.
+ *
+ * USAGE (in a vitest test file):
+ *
+ *   import { bootHarness, tearDownHarness, serverA, serverB, seed } from
+ *     '../../tools/federation-harness/harness.js';
+ *
+ *   let handle: HarnessHandle;
+ *
+ *   beforeAll(async () => {
+ *     handle = await bootHarness();
+ *   }, 180_000);
+ *
+ *   afterAll(async () => {
+ *     await tearDownHarness(handle);
+ *   });
+ *
+ *   test('variant A — list tasks', async () => {
+ *     const seedResult = await seed(handle, 'all');
+ *     const a = serverA(handle);
+ *     const res = await fetch(`${a.baseUrl}/api/federation/list/tasks`, {
+ *       headers: { Authorization: `Bearer ${seedResult.adminTokenA}` },
+ *     });
+ *     expect(res.status).toBe(200);
+ *   });
+ *
+ * NOTE: The `seed()` helper currently only supports scenario='all'. Passing any
+ * other value throws immediately. Per-variant narrowing is deferred to M3-11.
+ *
+ * ESM / NodeNext: all imports use .js extensions.
+ */
+
+import { execSync, execFileSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runSeed, type SeedResult } from './seed.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface GatewayAccessor {
+  /** Base URL reachable from the host machine, e.g. http://localhost:14001 */
+  baseUrl: string;
+  /** Bootstrap password used for POST /api/bootstrap/setup on a pristine gateway */
+  bootstrapPassword: string;
+  /** Internal Docker network hostname (for container-to-container calls) */
+  internalHostname: string;
+}
+
+export interface HarnessHandle {
+  /** Server A accessor */
+  a: GatewayAccessor;
+  /** Server B accessor */
+  b: GatewayAccessor;
+  /** Absolute path to the docker-compose file */
+  composeFile: string;
+  /** Whether this instance booted the stack (vs. reusing an existing one) */
+  ownedStack: boolean;
+  /** Optional seed result if seed() was called */
+  seedResult?: SeedResult;
+}
+
+/**
+ * Scenario to seed. Currently only 'all' is implemented; per-variant narrowing
+ * is tracked as M3-11. Passing any other value throws immediately with a clear
+ * error rather than silently over-seeding.
+ */
+export type SeedScenario = 'variantA' | 'variantB' | 'variantC' | 'all';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const COMPOSE_FILE = resolve(__dirname, 'docker-compose.two-gateways.yml');
+
+const GATEWAY_A_URL = process.env['GATEWAY_A_URL'] ?? 'http://localhost:14001';
+const GATEWAY_B_URL = process.env['GATEWAY_B_URL'] ?? 'http://localhost:14002';
+const ADMIN_BOOTSTRAP_PASSWORD_A =
+  process.env['ADMIN_BOOTSTRAP_PASSWORD_A'] ?? 'harness-admin-password-a';
+const ADMIN_BOOTSTRAP_PASSWORD_B =
+  process.env['ADMIN_BOOTSTRAP_PASSWORD_B'] ?? 'harness-admin-password-b';
+
+const READINESS_TIMEOUT_MS = 180_000;
+const READINESS_POLL_MS = 3_000;
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+async function isGatewayHealthy(baseUrl: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(5_000) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Poll both gateways in parallel until both are healthy or the shared deadline
+ * expires. Polling in parallel (rather than sequentially) avoids the bug where
+ * a slow gateway-a consumes all of the readiness budget before gateway-b is
+ * checked.
+ */
+async function waitForStack(handle: HarnessHandle): Promise<void> {
+  const gateways: Array<{ label: string; url: string }> = [
+    { label: 'gateway-a', url: handle.a.baseUrl },
+    { label: 'gateway-b', url: handle.b.baseUrl },
+  ];
+
+  await Promise.all(
+    gateways.map(async (gw) => {
+      // Each gateway gets its own independent deadline.
+      const deadline = Date.now() + READINESS_TIMEOUT_MS;
+      process.stdout.write(`[harness] Waiting for ${gw.label}...`);
+
+      while (Date.now() < deadline) {
+        if (await isGatewayHealthy(gw.url)) {
+          process.stdout.write(` ready\n`);
+          return;
+        }
+        if (Date.now() + READINESS_POLL_MS > deadline) {
+          throw new Error(
+            `[harness] ${gw.label} did not become healthy within ${READINESS_TIMEOUT_MS.toString()}ms`,
+          );
+        }
+        await new Promise((r) => setTimeout(r, READINESS_POLL_MS));
+        process.stdout.write('.');
+      }
+
+      throw new Error(
+        `[harness] ${gw.label} did not become healthy within ${READINESS_TIMEOUT_MS.toString()}ms`,
+      );
+    }),
+  );
+}
+
+function isStackRunning(): boolean {
+  try {
+    const output = execFileSync(
+      'docker',
+      ['compose', '-f', COMPOSE_FILE, 'ps', '--format', 'json'],
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+
+    if (!output.trim()) return false;
+
+    // Parse JSON lines — each running service emits a JSON object per line
+    const lines = output.trim().split('\n').filter(Boolean);
+    const runningServices = lines.filter((line) => {
+      try {
+        const obj = JSON.parse(line) as { State?: string };
+        return obj.State === 'running';
+      } catch {
+        return false;
+      }
+    });
+
+    // Expect at least gateway-a and gateway-b running
+    return runningServices.length >= 2;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Boot the harness stack.
+ *
+ * Idempotent: if the stack is already running and both gateways are healthy,
+ * this function reuses the existing stack and returns a handle with
+ * `ownedStack: false`. Callers that set `ownedStack: false` should NOT call
+ * `tearDownHarness` unless they explicitly want to tear down a pre-existing stack.
+ *
+ * If the stack is not running, it starts it with `docker compose up -d` and
+ * waits for both gateways to pass their /api/health probe.
+ */
+export async function bootHarness(): Promise<HarnessHandle> {
+  const handle: HarnessHandle = {
+    a: {
+      baseUrl: GATEWAY_A_URL,
+      bootstrapPassword: ADMIN_BOOTSTRAP_PASSWORD_A,
+      internalHostname: 'gateway-a',
+    },
+    b: {
+      baseUrl: GATEWAY_B_URL,
+      bootstrapPassword: ADMIN_BOOTSTRAP_PASSWORD_B,
+      internalHostname: 'gateway-b',
+    },
+    composeFile: COMPOSE_FILE,
+    ownedStack: false,
+  };
+
+  // Check if both gateways are already healthy
+  const [aHealthy, bHealthy] = await Promise.all([
+    isGatewayHealthy(handle.a.baseUrl),
+    isGatewayHealthy(handle.b.baseUrl),
+  ]);
+
+  if (aHealthy && bHealthy) {
+    console.log('[harness] Stack already running — reusing existing stack.');
+    handle.ownedStack = false;
+    return handle;
+  }
+
+  console.log('[harness] Starting federation harness stack...');
+  execSync(`docker compose -f "${COMPOSE_FILE}" up -d`, { stdio: 'inherit' });
+  handle.ownedStack = true;
+
+  await waitForStack(handle);
+  console.log('[harness] Stack is ready.');
+
+  return handle;
+}
+
+/**
+ * Tear down the harness stack.
+ *
+ * Runs `docker compose down -v` to remove containers AND volumes (ephemeral state).
+ * Only tears down if `handle.ownedStack` is true unless `force` is set.
+ */
+export async function tearDownHarness(
+  handle: HarnessHandle,
+  opts?: { force?: boolean },
+): Promise<void> {
+  if (!handle.ownedStack && !opts?.force) {
+    console.log(
+      '[harness] Stack not owned by this handle — skipping teardown (pass force: true to override).',
+    );
+    return;
+  }
+
+  console.log('[harness] Tearing down federation harness stack...');
+  execSync(`docker compose -f "${handle.composeFile}" down -v`, { stdio: 'inherit' });
+  console.log('[harness] Stack torn down.');
+}
+
+/**
+ * Return the Server A accessor from a harness handle.
+ * Convenience wrapper for test readability.
+ */
+export function serverA(handle: HarnessHandle): GatewayAccessor {
+  return handle.a;
+}
+
+/**
+ * Return the Server B accessor from a harness handle.
+ * Convenience wrapper for test readability.
+ */
+export function serverB(handle: HarnessHandle): GatewayAccessor {
+  return handle.b;
+}
+
+/**
+ * Seed the harness with test data for one or more scenarios.
+ *
+ * @param handle   The harness handle returned by bootHarness().
+ * @param scenario Which scope variants to provision. Currently only 'all' is
+ *                 supported — passing any other value throws immediately with a
+ *                 clear error. Per-variant narrowing is tracked as M3-11.
+ *
+ * Returns a SeedResult with grant IDs, peer IDs, and admin tokens for each
+ * gateway, which test assertions can reference.
+ *
+ * IMPORTANT: The harness assumes a pristine database on both gateways. The seed
+ * bootstraps an admin user on each gateway via POST /api/bootstrap/setup. If
+ * either gateway already has users, seed() throws with a clear error message.
+ * Run 'docker compose down -v' to reset state.
+ */
+export async function seed(
+  handle: HarnessHandle,
+  scenario: SeedScenario = 'all',
+): Promise<SeedResult> {
+  if (scenario !== 'all') {
+    throw new Error(
+      `seed: scenario narrowing not yet implemented; pass "all" for now. ` +
+        `Got: "${scenario}". Per-variant narrowing is tracked as M3-11.`,
+    );
+  }
+
+  const result = await runSeed({
+    serverAUrl: handle.a.baseUrl,
+    serverBUrl: handle.b.baseUrl,
+    adminBootstrapPasswordA: handle.a.bootstrapPassword,
+    adminBootstrapPasswordB: handle.b.bootstrapPassword,
+  });
+
+  handle.seedResult = result;
+  return result;
+}

tools/federation-harness/seed.ts

@@ -0,0 +1,603 @@
+#!/usr/bin/env tsx
+/**
+ * tools/federation-harness/seed.ts
+ *
+ * Provisions test data for the two-gateway federation harness.
+ * Run via: tsx tools/federation-harness/seed.ts
+ *
+ * What this script does:
+ *  1. (Optional) Boots the compose stack if --boot flag is passed.
+ *  2. Waits for both gateways to be healthy.
+ *  3. Bootstraps an admin user + token on each gateway via POST /api/bootstrap/setup.
+ *  4. Creates three grants on Server B matching the M3 acceptance test scenarios:
+ *     - Scope variant A: tasks + notes, include_personal: true
+ *     - Scope variant B: tasks only, include_teams: ['T1'], exclude T2
+ *     - Scope variant C: tasks + credentials in resources, credentials excluded (sanity)
+ *  5. For each grant, walks the full enrollment flow:
+ *       a. Server B creates a peer keypair (represents the requesting side).
+ *       b. Server B creates the grant referencing that peer.
+ *       c. Server B issues an enrollment token.
+ *       d. Server A creates its own peer keypair (represents its view of B).
+ *       e. Server A redeems the enrollment token at Server B's enrollment endpoint,
+ *          submitting A's CSR → receives signed cert back.
+ *       f. Server A stores the cert on its peer record → peer becomes active.
+ *  6. Inserts representative test tasks/notes/credentials on Server B.
+ *
+ * IMPORTANT: This script uses the real admin REST API — no direct DB writes.
+ * It exercises the full enrollment flow as M3 acceptance tests will.
+ *
+ * ESM / NodeNext: all imports use .js extensions.
+ */
+
+import { execSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const COMPOSE_FILE = resolve(__dirname, 'docker-compose.two-gateways.yml');
+
+/** Base URLs as seen from the host machine (mapped host ports). */
+const SERVER_A_URL = process.env['GATEWAY_A_URL'] ?? 'http://localhost:14001';
+const SERVER_B_URL = process.env['GATEWAY_B_URL'] ?? 'http://localhost:14002';
+
+/**
+ * Bootstrap passwords used when calling POST /api/bootstrap/setup on each
+ * gateway. Each gateway starts with zero users and requires a one-time setup
+ * call before any admin-guarded endpoints can be used.
+ */
+const ADMIN_BOOTSTRAP_PASSWORD_A =
+  process.env['ADMIN_BOOTSTRAP_PASSWORD_A'] ?? 'harness-admin-password-a';
+const ADMIN_BOOTSTRAP_PASSWORD_B =
+  process.env['ADMIN_BOOTSTRAP_PASSWORD_B'] ?? 'harness-admin-password-b';
+
+const READINESS_TIMEOUT_MS = 120_000;
+const READINESS_POLL_MS = 3_000;
+
+// ─── Scope variant definitions (for M3 acceptance tests) ─────────────────────
+
+/** Scope variant A — tasks + notes, personal data included. */
+export const SCOPE_VARIANT_A = {
+  resources: ['tasks', 'notes'],
+  filters: {
+    tasks: { include_personal: true },
+    notes: { include_personal: true },
+  },
+  excluded_resources: [] as string[],
+  max_rows_per_query: 500,
+};
+
+/** Scope variant B — tasks only, team T1 only, no personal. */
+export const SCOPE_VARIANT_B = {
+  resources: ['tasks'],
+  filters: {
+    tasks: { include_teams: ['T1'], include_personal: false },
+  },
+  excluded_resources: [] as string[],
+  max_rows_per_query: 500,
+};
+
+/**
+ * Scope variant C — tasks + credentials in resources list, but credentials
+ * explicitly in excluded_resources. Sanity test: credentials must still be
+ * inaccessible even though they appear in resources.
+ */
+export const SCOPE_VARIANT_C = {
+  resources: ['tasks', 'credentials'],
+  filters: {
+    tasks: { include_personal: true },
+  },
+  excluded_resources: ['credentials'],
+  max_rows_per_query: 500,
+};
+
+// ─── Inline types (no import from packages/types — M3-01 branch not yet merged) ─
+
+interface AdminFetchOptions {
+  method?: string;
+  body?: unknown;
+  adminToken: string;
+}
+
+interface PeerRecord {
+  peerId: string;
+  csrPem: string;
+}
+
+interface GrantRecord {
+  id: string;
+  status: string;
+  scope: unknown;
+}
+
+interface EnrollmentTokenResult {
+  token: string;
+  expiresAt: string;
+  enrollmentUrl: string;
+}
+
+interface EnrollmentRedeemResult {
+  certPem: string;
+  certChainPem: string;
+}
+
+interface BootstrapResult {
+  adminUserId: string;
+  adminToken: string;
+}
+
+export interface SeedResult {
+  serverAUrl: string;
+  serverBUrl: string;
+  adminTokenA: string;
+  adminTokenB: string;
+  adminUserIdA: string;
+  adminUserIdB: string;
+  grants: {
+    variantA: GrantRecord;
+    variantB: GrantRecord;
+    variantC: GrantRecord;
+  };
+  peers: {
+    variantA: PeerRecord & { grantId: string };
+    variantB: PeerRecord & { grantId: string };
+    variantC: PeerRecord & { grantId: string };
+  };
+}
+
+// ─── HTTP helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Authenticated admin fetch. Sends `Authorization: Bearer <adminToken>` which
+ * is the only path supported by AdminGuard (DB-backed sha256 token lookup).
+ * No `x-admin-key` header path exists in the gateway.
+ */
+async function adminFetch<T>(baseUrl: string, path: string, opts: AdminFetchOptions): Promise<T> {
+  const url = `${baseUrl}${path}`;
+  const res = await fetch(url, {
+    method: opts.method ?? 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${opts.adminToken}`,
+    },
+    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '(no body)');
+    throw new Error(`${opts.method ?? 'GET'} ${url} → ${res.status}: ${text}`);
+  }
+
+  return res.json() as Promise<T>;
+}
+
+// ─── Admin bootstrap ──────────────────────────────────────────────────────────
+
+/**
+ * Bootstrap an admin user on a pristine gateway.
+ *
+ * Steps:
+ *  1. GET /api/bootstrap/status — confirms needsSetup === true.
+ *  2. POST /api/bootstrap/setup with { name, email, password } — returns
+ *     { user, token: { plaintext } }.
+ *
+ * The harness assumes a fresh DB. If needsSetup is false the harness fails
+ * fast with a clear error rather than proceeding with an unknown token.
+ */
+async function bootstrapAdmin(
+  baseUrl: string,
+  label: string,
+  password: string,
+): Promise<BootstrapResult> {
+  console.log(`[seed] Bootstrapping admin on ${label} (${baseUrl})...`);
+
+  // 1. Check status
+  const statusRes = await fetch(`${baseUrl}/api/bootstrap/status`);
+  if (!statusRes.ok) {
+    throw new Error(`[seed] GET ${baseUrl}/api/bootstrap/status → ${statusRes.status.toString()}`);
+  }
+  const status = (await statusRes.json()) as { needsSetup: boolean };
+
+  if (!status.needsSetup) {
+    throw new Error(
+      `[seed] ${label} at ${baseUrl} already has users (needsSetup=false). ` +
+        `The harness requires a pristine database. Run 'docker compose down -v' to reset.`,
+    );
+  }
+
+  // 2. Bootstrap
+  const setupRes = await fetch(`${baseUrl}/api/bootstrap/setup`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name: `Harness Admin (${label})`,
+      email: `harness-admin-${label.toLowerCase().replace(/\s+/g, '-')}@example.invalid`,
+      password,
+    }),
+  });
+
+  if (!setupRes.ok) {
+    const body = await setupRes.text().catch(() => '(no body)');
+    throw new Error(
+      `[seed] POST ${baseUrl}/api/bootstrap/setup → ${setupRes.status.toString()}: ${body}`,
+    );
+  }
+
+  const result = (await setupRes.json()) as {
+    user: { id: string };
+    token: { plaintext: string };
+  };
+
+  console.log(`[seed]   ${label} admin user: ${result.user.id}`);
+  console.log(`[seed]   ${label} admin token: ${result.token.plaintext.slice(0, 8)}...`);
+
+  return {
+    adminUserId: result.user.id,
+    adminToken: result.token.plaintext,
+  };
+}
+
+// ─── Readiness probe ──────────────────────────────────────────────────────────
+
+async function waitForGateway(baseUrl: string, label: string): Promise<void> {
+  const deadline = Date.now() + READINESS_TIMEOUT_MS;
+  let lastError: string = '';
+
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(5_000) });
+      if (res.ok) {
+        console.log(`[seed] ${label} is ready (${baseUrl})`);
+        return;
+      }
+      lastError = `HTTP ${res.status.toString()}`;
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+    await new Promise((r) => setTimeout(r, READINESS_POLL_MS));
+  }
+
+  throw new Error(
+    `[seed] ${label} did not become ready within ${READINESS_TIMEOUT_MS.toString()}ms — last error: ${lastError}`,
+  );
+}
+
+// ─── Enrollment flow ──────────────────────────────────────────────────────────
+
+/**
+ * Walk the full enrollment flow for one grant.
+ *
+ * The correct two-sided flow (matching the data model's FK semantics):
+ *
+ *  1. On Server B: POST /api/admin/federation/peers/keypair
+ *       → peerId_B (Server B's peer record representing the requesting side)
+ *  2. On Server B: POST /api/admin/federation/grants with peerId: peerId_B
+ *       → grant (FK to Server B's own federation_peers table — no violation)
+ *  3. On Server B: POST /api/admin/federation/grants/:id/tokens
+ *       → enrollmentUrl pointing back to Server B
+ *  4. On Server A: POST /api/admin/federation/peers/keypair
+ *       → peerId_A + csrPem_A (Server A's local record of Server B)
+ *  5. Server A → Server B: POST enrollmentUrl with { csrPem: csrPem_A }
+ *       → certPem signed by Server B's CA
+ *  6. On Server A: PATCH /api/admin/federation/peers/:peerId_A/cert with certPem
+ *       → Server A's peer record transitions to active
+ *
+ * Returns the activated grant (from Server B) and Server A's peer record.
+ */
+async function enrollGrant(opts: {
+  label: string;
+  subjectUserId: string;
+  scope: unknown;
+  adminTokenA: string;
+  adminTokenB: string;
+  serverAUrl: string;
+  serverBUrl: string;
+}): Promise<{ grant: GrantRecord; peer: PeerRecord & { grantId: string } }> {
+  const { label, subjectUserId, scope, adminTokenA, adminTokenB, serverAUrl, serverBUrl } = opts;
+  console.log(`\n[seed] Enrolling grant for scope variant ${label}...`);
+
+  // 1. Create peer keypair on Server B (represents the requesting peer from B's perspective)
+  const peerB = await adminFetch<PeerRecord>(serverBUrl, '/api/admin/federation/peers/keypair', {
+    method: 'POST',
+    adminToken: adminTokenB,
+    body: {
+      commonName: `harness-peer-${label.toLowerCase()}-from-b`,
+      displayName: `Harness Peer ${label} (Server A as seen from B)`,
+      endpointUrl: serverAUrl,
+    },
+  });
+  console.log(`[seed]   Created peer on B: ${peerB.peerId}`);
+
+  // 2. Create grant on Server B referencing B's own peer record
+  const grant = await adminFetch<GrantRecord>(serverBUrl, '/api/admin/federation/grants', {
+    method: 'POST',
+    adminToken: adminTokenB,
+    body: {
+      peerId: peerB.peerId,
+      subjectUserId,
+      scope,
+    },
+  });
+  console.log(`[seed]   Created grant on B: ${grant.id} (status: ${grant.status})`);
+
+  // 3. Generate enrollment token on Server B
+  const tokenResult = await adminFetch<EnrollmentTokenResult>(
+    serverBUrl,
+    `/api/admin/federation/grants/${grant.id}/tokens`,
+    { method: 'POST', adminToken: adminTokenB, body: { ttlSeconds: 900 } },
+  );
+  console.log(`[seed]   Enrollment token: ${tokenResult.token.slice(0, 8)}...`);
+  console.log(`[seed]   Enrollment URL: ${tokenResult.enrollmentUrl}`);
+
+  // 4. Create peer keypair on Server A (Server A's local record of Server B)
+  const peerA = await adminFetch<PeerRecord>(serverAUrl, '/api/admin/federation/peers/keypair', {
+    method: 'POST',
+    adminToken: adminTokenA,
+    body: {
+      commonName: `harness-peer-${label.toLowerCase()}-from-a`,
+      displayName: `Harness Peer ${label} (Server B as seen from A)`,
+      endpointUrl: serverBUrl,
+    },
+  });
+  console.log(`[seed]   Created peer on A: ${peerA.peerId}`);
+
+  // 5. Redeem token at Server B's enrollment endpoint with A's CSR.
+  //    The enrollment endpoint is not admin-guarded — the one-time token IS the credential.
+  //
+  //    The enrollmentUrl returned by the gateway is built using BETTER_AUTH_URL which
+  //    resolves to the in-cluster Docker hostname (gateway-b:3000). That URL is only
+  //    reachable from other containers, not from the host machine running this script.
+  //    We rewrite the host portion to use the host-accessible serverBUrl so the
+  //    seed script can reach the endpoint from the host.
+  const parsedEnrollment = new URL(tokenResult.enrollmentUrl);
+  const tokenSegment = parsedEnrollment.pathname.split('/').pop()!;
+  const redeemUrl = `${serverBUrl}/api/federation/enrollment/${tokenSegment}`;
+  console.log(`[seed]   Rewritten redeem URL (host-accessible): ${redeemUrl}`);
+  const redeemRes = await fetch(redeemUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ csrPem: peerA.csrPem }),
+  });
+
+  if (!redeemRes.ok) {
+    const body = await redeemRes.text().catch(() => '(no body)');
+    throw new Error(`Enrollment redemption failed: ${redeemRes.status.toString()} — ${body}`);
+  }
+
+  const redeemResult = (await redeemRes.json()) as EnrollmentRedeemResult;
+  console.log(`[seed]   Cert issued (${redeemResult.certPem.length.toString()} bytes)`);
+
+  // 6. Store cert on Server A's peer record → transitions to active
+  await adminFetch<unknown>(serverAUrl, `/api/admin/federation/peers/${peerA.peerId}/cert`, {
+    method: 'PATCH',
+    adminToken: adminTokenA,
+    body: { certPem: redeemResult.certPem },
+  });
+  console.log(`[seed]   Cert stored on A — peer ${peerA.peerId} is now active`);
+
+  // Verify grant flipped to active on B
+  const activeGrant = await adminFetch<GrantRecord>(
+    serverBUrl,
+    `/api/admin/federation/grants/${grant.id}`,
+    { adminToken: adminTokenB },
+  );
+  console.log(`[seed]   Grant status on B: ${activeGrant.status}`);
+
+  return { grant: activeGrant, peer: { ...peerA, grantId: grant.id } };
+}
+
+// ─── Test data insertion ──────────────────────────────────────────────────────
+
+/**
+ * Insert representative test data on Server B via its admin APIs.
+ *
+ * NOTE: The gateway's task/note/credential APIs require an authenticated user
+ * session. For the harness, we seed via admin-level endpoints if available,
+ * or document the gap here for M3-11 to fill in with proper user session seeding.
+ *
+ * ASSUMPTION: Server B exposes POST /api/admin/tasks (or similar) for test data.
+ * If that endpoint does not yet exist, this function logs a warning and skips
+ * without failing — M3-11 will add the session-based seeding path.
+ */
+async function seedTestData(
+  subjectUserId: string,
+  scopeLabel: string,
+  serverBUrl: string,
+  adminTokenB: string,
+): Promise<void> {
+  console.log(`\n[seed] Seeding test data on Server B for ${scopeLabel}...`);
+
+  const testTasks = [
+    {
+      title: `${scopeLabel} Task 1`,
+      description: 'Federation harness test task',
+      userId: subjectUserId,
+    },
+    {
+      title: `${scopeLabel} Task 2`,
+      description: 'Team-scoped test task',
+      userId: subjectUserId,
+      teamId: 'T1',
+    },
+  ];
+
+  const testNotes = [
+    {
+      title: `${scopeLabel} Note 1`,
+      content: 'Personal note for federation test',
+      userId: subjectUserId,
+    },
+  ];
+
+  // Attempt to insert — tolerate 404 (endpoint not yet implemented)
+  for (const task of testTasks) {
+    try {
+      await adminFetch<unknown>(serverBUrl, '/api/admin/tasks', {
+        method: 'POST',
+        adminToken: adminTokenB,
+        body: task,
+      });
+      console.log(`[seed]   Inserted task: "${task.title}"`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('404') || msg.includes('Cannot POST')) {
+        console.warn(
+          `[seed]   WARN: /api/admin/tasks not found — skipping task insertion (expected until M3-11)`,
+        );
+        break;
+      }
+      throw err;
+    }
+  }
+
+  for (const note of testNotes) {
+    try {
+      await adminFetch<unknown>(serverBUrl, '/api/admin/notes', {
+        method: 'POST',
+        adminToken: adminTokenB,
+        body: note,
+      });
+      console.log(`[seed]   Inserted note: "${note.title}"`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('404') || msg.includes('Cannot POST')) {
+        console.warn(
+          `[seed]   WARN: /api/admin/notes not found — skipping note insertion (expected until M3-11)`,
+        );
+        break;
+      }
+      throw err;
+    }
+  }
+
+  console.log(`[seed] Test data seeding for ${scopeLabel} complete.`);
+}
+
+// ─── Main entrypoint ──────────────────────────────────────────────────────────
+
+export async function runSeed(opts?: {
+  serverAUrl?: string;
+  serverBUrl?: string;
+  adminBootstrapPasswordA?: string;
+  adminBootstrapPasswordB?: string;
+  subjectUserIds?: { variantA: string; variantB: string; variantC: string };
+}): Promise<SeedResult> {
+  const aUrl = opts?.serverAUrl ?? SERVER_A_URL;
+  const bUrl = opts?.serverBUrl ?? SERVER_B_URL;
+  const passwordA = opts?.adminBootstrapPasswordA ?? ADMIN_BOOTSTRAP_PASSWORD_A;
+  const passwordB = opts?.adminBootstrapPasswordB ?? ADMIN_BOOTSTRAP_PASSWORD_B;
+
+  // Use provided or default subject user IDs.
+  // In a real run these would be real user UUIDs from Server B's DB.
+  // For the harness, the admin bootstrap user on Server B is used as the subject.
+  // These are overridden after bootstrap if opts.subjectUserIds is not provided.
+  const subjectIds = opts?.subjectUserIds;
+
+  console.log('[seed] Waiting for gateways to be ready...');
+  await Promise.all([waitForGateway(aUrl, 'Server A'), waitForGateway(bUrl, 'Server B')]);
+
+  // Bootstrap admin users on both gateways (requires pristine DBs).
+  console.log('\n[seed] Bootstrapping admin accounts...');
+  const [bootstrapA, bootstrapB] = await Promise.all([
+    bootstrapAdmin(aUrl, 'Server A', passwordA),
+    bootstrapAdmin(bUrl, 'Server B', passwordB),
+  ]);
+
+  // Default subject user IDs to the admin user on Server B (guaranteed to exist).
+  const resolvedSubjectIds = subjectIds ?? {
+    variantA: bootstrapB.adminUserId,
+    variantB: bootstrapB.adminUserId,
+    variantC: bootstrapB.adminUserId,
+  };
+
+  // Enroll all three scope variants sequentially to avoid race conditions on
+  // the step-ca signing queue. Parallel enrollment would work too but
+  // sequential is easier to debug when something goes wrong.
+  console.log('\n[seed] Enrolling scope variants...');
+  const resultA = await enrollGrant({
+    label: 'A',
+    subjectUserId: resolvedSubjectIds.variantA,
+    scope: SCOPE_VARIANT_A,
+    adminTokenA: bootstrapA.adminToken,
+    adminTokenB: bootstrapB.adminToken,
+    serverAUrl: aUrl,
+    serverBUrl: bUrl,
+  });
+  const resultB = await enrollGrant({
+    label: 'B',
+    subjectUserId: resolvedSubjectIds.variantB,
+    scope: SCOPE_VARIANT_B,
+    adminTokenA: bootstrapA.adminToken,
+    adminTokenB: bootstrapB.adminToken,
+    serverAUrl: aUrl,
+    serverBUrl: bUrl,
+  });
+  const resultC = await enrollGrant({
+    label: 'C',
+    subjectUserId: resolvedSubjectIds.variantC,
+    scope: SCOPE_VARIANT_C,
+    adminTokenA: bootstrapA.adminToken,
+    adminTokenB: bootstrapB.adminToken,
+    serverAUrl: aUrl,
+    serverBUrl: bUrl,
+  });
+
+  // Seed test data on Server B for each scope variant
+  await Promise.all([
+    seedTestData(resolvedSubjectIds.variantA, 'A', bUrl, bootstrapB.adminToken),
+    seedTestData(resolvedSubjectIds.variantB, 'B', bUrl, bootstrapB.adminToken),
+    seedTestData(resolvedSubjectIds.variantC, 'C', bUrl, bootstrapB.adminToken),
+  ]);
+
+  const result: SeedResult = {
+    serverAUrl: aUrl,
+    serverBUrl: bUrl,
+    adminTokenA: bootstrapA.adminToken,
+    adminTokenB: bootstrapB.adminToken,
+    adminUserIdA: bootstrapA.adminUserId,
+    adminUserIdB: bootstrapB.adminUserId,
+    grants: {
+      variantA: resultA.grant,
+      variantB: resultB.grant,
+      variantC: resultC.grant,
+    },
+    peers: {
+      variantA: resultA.peer,
+      variantB: resultB.peer,
+      variantC: resultC.peer,
+    },
+  };
+
+  console.log('\n[seed] Seed complete.');
+  console.log('[seed] Summary:');
+  console.log(`  Variant A grant: ${result.grants.variantA.id} (${result.grants.variantA.status})`);
+  console.log(`  Variant B grant: ${result.grants.variantB.id} (${result.grants.variantB.status})`);
+  console.log(`  Variant C grant: ${result.grants.variantC.id} (${result.grants.variantC.status})`);
+
+  return result;
+}
+
+// ─── CLI entry ────────────────────────────────────────────────────────────────
+
+const isCli =
+  process.argv[1] != null &&
+  fileURLToPath(import.meta.url).endsWith(process.argv[1]!.split('/').pop()!);
+
+if (isCli) {
+  const shouldBoot = process.argv.includes('--boot');
+
+  if (shouldBoot) {
+    console.log('[seed] --boot flag detected — starting compose stack...');
+    execSync(`docker compose -f "${COMPOSE_FILE}" up -d`, { stdio: 'inherit' });
+  }
+
+  runSeed()
+    .then(() => {
+      process.exit(0);
+    })
+    .catch((err) => {
+      console.error('[seed] Fatal:', err);
+      process.exit(1);
+    });
+}