Merge pull request 'P2 — web SPA data layer + same-origin auth' (#1144) from feat/webui-p2-data-auth into next

First increment of the approved Phase P RFC (webui-mission). Adds a Vite + React
Router SPA scaffold coexisting with the Next app: index.html with the theme
anti-flash script, src/main.tsx entry, the v1 parity route table under Guest/Auth
guard shells, and a dev proxy (/api, /socket.io ws) to the gateway on 14242 so the
SPA is same-origin in dev. vitest bumped to v3 (vite 8 pairing); existing specs
pass unchanged. Next remains the served app until the P5 cutover.

Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01ESFAnh2t9HmLwng8oW95St

.gitignore

@@ -8,6 +8,7 @@ coverage
 .env.local
 *.tsbuildinfo
 .pnpm-store
+__pycache__/
 docs/reports/
 
 # Step-CA dev password — real file is gitignored; commit only the .example

.husky/pre-push

@@ -1 +1 @@
-pnpm typecheck && pnpm lint && pnpm format:check
+pnpm preflight && pnpm typecheck && pnpm lint && pnpm format:check

.npmrc

@@ -1,5 +1,5 @@
 @mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
-# Pin the pnpm store to the same path the ci-base image warms (Dockerfile.ci),
-# so the pipeline `pnpm install --prefer-offline` consumes the baked store
-# instead of repopulating a fresh one.
-store-dir=/root/.local/share/pnpm/store
+# HOME resolves to /root in the ci-base image, preserving its warmed-store path.
+# Non-root checkouts use their own HOME. Override without editing this file via
+# NPM_CONFIG_STORE_DIR (pnpm's environment form of the store-dir setting).
+store-dir=${HOME}/.local/share/pnpm/store

.prettierignore

@@ -4,6 +4,15 @@ pnpm-lock.yaml
 **/node_modules
 **/drizzle
 **/.next
+# Python build/test artifacts — same category as node_modules/dist/.next above.
+# Prettier must never scan generated trees; without these a local venv poisons
+# `pnpm format:check` with thousands of third-party files.
+**/venv
+**/__pycache__
+**/.mypy_cache
+**/.pytest_cache
+**/htmlcov
 .claude/
 docs/tess/TASKS.md
 docs/scratchpads/
+packages/mosaic/src/fleet/testdata/documentation-publication-v1/inline-migration-v1.json

.woodpecker/ci.yml

@@ -41,6 +41,11 @@ steps:
       # (Constitution + dispatcher + each RUNTIME.md slice). See DESIGN §7 / R9.
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
+      # Test-membership guard (#1017): also first link of test:framework-shell.
+      # Invoked from BOTH surfaces it audits (F2, PR #1018) — the guard is link
+      # [0] of the pnpm chain, so severing that chain would silence it together
+      # with everything it guards; this direct line keeps one instrument running.
+      - bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh
 
   # Blocking gate (#791): a framework upgrade must never write or delete an
   # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
@@ -98,6 +103,12 @@ steps:
       DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
     commands:
       - *enable_pnpm
+      # openssl (#912) is the wake HMAC signer: the digest H1/H2, beacon B12,
+      # and install I8 legs hard-require it in CI. It is baked into ci-base via
+      # Dockerfile.ci, but ci-base only rebuilds on push-to-main/tag — this
+      # `apk add` guarantees openssl is present on PR pipelines too (and is a
+      # fast no-op once the rebuilt image already ships it).
+      - apk add --no-cache openssl
       # postgresql-client (pg_isready) is baked into ci-base.
       # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
       - |

.woodpecker/publish.yml

@@ -1,5 +1,5 @@
 # Build, publish npm packages, and push Docker images
-# Runs only on main branch push/tag
+# Runs on main for stable publishes and on next for integration-line prereleases/images
 
 variables:
   # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
@@ -23,9 +23,21 @@ variables:
           - 'docs/**'
           - '**/*.md'
           - '.woodpecker/**'
+    - event: [push, manual]
+      branch: next
+  - &main_image_build_when
+    - event: tag
+    - event: [push, manual]
+      branch: main
+      path:
+        exclude:
+          - 'packages/mosaic/**'
+          - 'docs/**'
+          - '**/*.md'
+          - '.woodpecker/**'
 
 when:
-  - branch: [main]
+  - branch: [main, next]
     event: [push, manual, tag]
 
 steps:
@@ -103,6 +115,84 @@ steps:
     depends_on:
       - build
 
+  publish-next-npm:
+    image: *node_image
+    # Durable @next integration-line publish. Runs only on next; never writes
+    # the latest dist-tag and never commits the computed prerelease versions.
+    when:
+      - event: [push, manual]
+        branch: next
+    environment:
+      NPM_TOKEN:
+        from_secret: gitea_token
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_PIPELINE_NUMBER: ${CI_PIPELINE_NUMBER}
+    commands:
+      - *enable_pnpm
+      - |
+        if [ "$CI_COMMIT_BRANCH" != "next" ]; then
+          echo "[publish-next] FATAL: publish-next-npm may only run on next (got '$CI_COMMIT_BRANCH')" >&2
+          exit 1
+        fi
+        if [ -z "$CI_PIPELINE_NUMBER" ]; then
+          echo "[publish-next] FATAL: CI_PIPELINE_NUMBER is required for prerelease versioning" >&2
+          exit 1
+        fi
+        echo "//git.mosaicstack.dev/api/packages/mosaicstack/npm/:_authToken=$NPM_TOKEN" > ~/.npmrc
+        echo "@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/" >> ~/.npmrc
+        DIST_TAGS_JSON="$(npm view @mosaicstack/mosaic dist-tags --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/ --json)"
+        DIST_TAGS_JSON="$DIST_TAGS_JSON" node -e 'const tags = JSON.parse(process.env.DIST_TAGS_JSON || "{}"); if (!tags || typeof tags !== "object" || !Object.hasOwn(tags, "latest")) { throw new Error("Gitea npm registry did not return a usable dist-tags object"); } console.log("[publish-next] registry dist-tags OK: latest=" + tags.latest);'
+        node <<'NODE'
+        const fs = require('node:fs');
+        const path = require('node:path');
+
+        const pipelineNumber = process.env.CI_PIPELINE_NUMBER;
+        const roots = ['apps', 'packages', 'plugins'];
+        const updated = [];
+
+        function walk(dir) {
+          if (!fs.existsSync(dir)) return;
+          for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.turbo') continue;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              const packagePath = path.join(fullPath, 'package.json');
+              if (fs.existsSync(packagePath)) updatePackage(packagePath);
+              walk(fullPath);
+            }
+          }
+        }
+
+        function updatePackage(packagePath) {
+          const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+          if (!manifest.name?.startsWith('@mosaicstack/') || manifest.private) return;
+          const stableMatch = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(manifest.version);
+          if (!stableMatch) {
+            throw new Error(manifest.name + " has unsupported semver version '" + manifest.version + "'");
+          }
+          const [, major, minor, patch] = stableMatch;
+          const oldVersion = manifest.version;
+          manifest.version = major + '.' + minor + '.' + (Number(patch) + 1) + '-next.' + pipelineNumber;
+          fs.writeFileSync(packagePath, JSON.stringify(manifest, null, 2) + '\n');
+          updated.push(manifest.name + ' ' + oldVersion + ' -> ' + manifest.version);
+        }
+
+        for (const root of roots) walk(root);
+        if (updated.length === 0) throw new Error('No publishable @mosaicstack/* packages found');
+        console.log('[publish-next] computed prerelease versions for ' + updated.length + ' packages:');
+        for (const line of updated) console.log('[publish-next] ' + line);
+        NODE
+        pnpm --filter "@mosaicstack/*" --filter "!@mosaicstack/web" --filter "!@mosaicstack/mosaic-as" publish --no-git-checks --access public --tag next
+        EXPECTED_VERSION="$(node -p "require('./packages/mosaic/package.json').version")"
+        RESOLVED_VERSION="$(npm view @mosaicstack/mosaic@next version --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/)"
+        if [ "$RESOLVED_VERSION" != "$EXPECTED_VERSION" ]; then
+          echo "[publish-next] FATAL: @mosaicstack/mosaic@next resolved '$RESOLVED_VERSION', expected '$EXPECTED_VERSION'" >&2
+          exit 1
+        fi
+        echo "[publish-next] @mosaicstack/mosaic@next resolves to $RESOLVED_VERSION"
+    depends_on:
+      - build
+
   # TODO: Uncomment when ready to publish to npmjs.org
   # publish-npmjs:
   #   image: *node_image
@@ -134,8 +224,17 @@ steps:
       - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
       - |
         DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+        if [ "$CI_COMMIT_BRANCH" = "next" ]; then
+          if [ -n "$CI_COMMIT_TAG" ]; then
+            echo "[publish] FATAL: next gateway publish must be sha-only; refusing tag '$CI_COMMIT_TAG'" >&2
+            exit 1
+          fi
+          echo "[publish] next gateway publish is sha-only"
+        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
           DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:latest"
+        elif [ -z "$CI_COMMIT_TAG" ]; then
+          echo "[publish] FATAL: gateway image publish may only run for main, next, or tag events" >&2
+          exit 1
         fi
         if [ -n "$CI_COMMIT_TAG" ]; then
           DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:$CI_COMMIT_TAG"
@@ -146,7 +245,7 @@ steps:
 
   build-appservice:
     image: gcr.io/kaniko-project/executor:debug
-    when: *image_build_when
+    when: *main_image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username
@@ -172,7 +271,7 @@ steps:
 
   build-web:
     image: gcr.io/kaniko-project/executor:debug
-    when: *image_build_when
+    when: *main_image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username

Dockerfile.ci

@@ -25,7 +25,10 @@ FROM node:24-alpine
 # postgresql-client used by the test step's pg_isready readiness probe. `bash`,
 # `git`, and `jq` are baked here too — framework shell tests and the shipped
 # Codex review wrappers require them without per-run installation in ci.yml.
-RUN apk add --no-cache python3 make g++ postgresql-client bash git jq
+# `openssl` (#912) is the non-circular HMAC signer for the wake trust layer:
+# the digest H1/H2, beacon B12, and install I8 legs hard-require it in CI so the
+# §4 G6 evidence comes from an actually-run HMAC leg, not a skipped one.
+RUN apk add --no-cache python3 make g++ postgresql-client bash git jq openssl
 
 # Pin pnpm to the repo's packageManager version via corepack.
 RUN corepack enable && corepack prepare [email protected] --activate

README.md

@@ -30,6 +30,16 @@ This installs both components:
 | **Framework**           | Bash launcher, guides, runtime configs, tools, skills            | `~/.config/mosaic/`  |
 | **@mosaicstack/mosaic** | Unified `mosaic` CLI — TUI, gateway client, wizard, auto-updater | `~/.npm-global/bin/` |
 
+### Install lanes
+
+| Lane                     | Command                               | Use when                                              | Source                                                                  |
+| ------------------------ | ------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------- |
+| Stable                   | `bash tools/install.sh`               | You want the released Mosaic CLI/framework            | npm registry `@mosaicstack/mosaic@latest` + framework archive at `main` |
+| Prerelease integration   | `bash tools/install.sh --next`        | You want the current `next` integration branch        | Build-from-source at `next`                                             |
+| Contributor/source build | `bash tools/install.sh --dev --ref X` | You are testing a branch before release; `--ref` wins | Build-from-source at the requested ref                                  |
+
+`--next` is shorthand for the prerelease integration lane: it enables source-build mode and uses `next` unless an explicit `--ref` or `MOSAIC_REF` is provided.
+
 After install, the wizard runs automatically or you can invoke it manually:
 
 ```bash
@@ -201,8 +211,21 @@ git clone [email protected]:mosaicstack/stack.git
 cd stack
 
 # Install dependencies. The local tier uses in-process PGlite; leave DATABASE_URL unset.
+# The pnpm store defaults to $HOME/.local/share/pnpm/store. Override it without
+# editing the checkout with NPM_CONFIG_STORE_DIR=$HOME/another-store if needed.
 pnpm install
 
+# Verify dependencies and generated state before running source-quality gates.
+# Missing dependencies exit 42; stale/foreign apps/web/.next state exits 43.
+# The web build certifies its exact standalone symlink manifest; added, removed,
+# retargeted, or manifest-only-tampered generated links also exit 43. This detects
+# accidental, independent, stale, and foreign-residue mutation—the class exposed by
+# a five-month-stale .next that produced 19 phantom TS2307 errors.
+# It does NOT defend against a same-UID actor that can rewrite both manifest and
+# marker consistently (CWE-345). RM-59 tracks the required executor/spine-side
+# trust anchor outside worktree authority.
+pnpm preflight
+
 # Optional local queue service only. This does not start PostgreSQL.
 docker compose up -d valkey
 
@@ -230,6 +253,7 @@ Gateway start command until KBN-101-02 makes that state fail closed.
 ### Quality Gates
 
 ```bash
+pnpm preflight               # Checkout/dependency/generated-state validation
 pnpm typecheck               # TypeScript type checking (all packages)
 pnpm lint                    # ESLint (all packages)
 pnpm test                    # Vitest (all packages)
@@ -347,7 +371,9 @@ The CLI also performs a background update check on every invocation (cached for
 bash tools/install.sh --check           # Version check only
 bash tools/install.sh --framework       # Framework only (skip npm CLI)
 bash tools/install.sh --cli             # npm CLI only (skip framework)
-bash tools/install.sh --ref v1.0        # Install from a specific git ref
+bash tools/install.sh --next            # Prerelease lane: source build from next
+bash tools/install.sh --dev             # Contributor lane: source build at --ref/main
+bash tools/install.sh --ref v1.0        # Install from a specific git ref (--ref wins over --next)
 bash tools/install.sh --yes             # Non-interactive, accept all defaults
 bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```

apps/gateway/src/__tests__/integration/federation-m3-list.integration.test.ts

@@ -0,0 +1,519 @@
+/**
+ * Federation M3 single-gateway integration tests (FED-M3-10).
+ *
+ * Covers MILESTONES.md M3 acceptance:
+ *  - #6: malformed certificate OIDs fail with 401; valid cert + revoked grant fails with 403.
+ *  - #7: max_rows_per_query caps list results.
+ *
+ * Strategy:
+ *  - Real PostgreSQL via @mosaicstack/db.
+ *  - Mocked TLS context/Fastify request shim for FederationAuthGuard.
+ *  - Direct controller calls using the real POST /api/federation/v1/list/:resource contract.
+ *
+ * Run:
+ *   FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test -- \
+ *     src/__tests__/integration/federation-m3-list.integration.test.ts
+ */
+
+import 'reflect-metadata';
+import * as crypto from 'node:crypto';
+import type { ExecutionContext } from '@nestjs/common';
+import { Test, type TestingModule } from '@nestjs/testing';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import {
+  and,
+  createDb,
+  eq,
+  federationGrants,
+  federationPeers,
+  inArray,
+  missionTasks,
+  missions,
+  projects,
+  tasks,
+  teamMembers,
+  teams,
+  type Db,
+  type DbHandle,
+  users,
+} from '@mosaicstack/db';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { DB } from '../../database/database.module.js';
+import { GrantsService } from '../../federation/grants.service.js';
+import { FederationAuthGuard } from '../../federation/server/federation-auth.guard.js';
+import { FederationScopeService } from '../../federation/server/scope.service.js';
+import { FederationListQueryService } from '../../federation/server/verbs/list-query.service.js';
+import { ListController } from '../../federation/server/verbs/list.controller.js';
+import {
+  makeMosaicIssuedCert,
+  makeSelfSignedCert,
+} from '../../federation/__tests__/helpers/test-cert.js';
+
+const run = process.env['FEDERATED_INTEGRATION'] === '1';
+const PG_URL = process.env['DATABASE_URL'] ?? 'postgresql://mosaic:mosaic@localhost:5433/mosaic';
+const RUN_ID = `fed-m3-10-${crypto.randomUUID()}`;
+const CERT_SERIAL_HEX = crypto.randomUUID().replace(/-/g, '').toUpperCase();
+
+interface TestIds {
+  readonly subjectUserId: string;
+  readonly otherUserId: string;
+  readonly peerId: string;
+  readonly revokedPeerId: string;
+  readonly activeGrantId: string;
+  readonly revokedGrantId: string;
+  readonly subjectProjectId: string;
+  readonly subjectMissionId: string;
+  readonly otherProjectId: string;
+  readonly teamId: string;
+  readonly unauthorizedTeamId: string;
+  readonly teamProjectId: string;
+  readonly taskIds: readonly string[];
+  readonly excludedTaskIds: readonly string[];
+  readonly subjectNoteId: string;
+  readonly otherUserNoteId: string;
+}
+
+function pemToDer(pem: string): Buffer {
+  return Buffer.from(
+    pem
+      .replace(/-----BEGIN CERTIFICATE-----/, '')
+      .replace(/-----END CERTIFICATE-----/, '')
+      .replace(/\s+/g, ''),
+    'base64',
+  );
+}
+
+function makeFederationRequest(certPem: string): FastifyRequest {
+  return {
+    raw: {
+      socket: {
+        getPeerCertificate: () => ({
+          raw: pemToDer(certPem),
+          serialNumber: CERT_SERIAL_HEX,
+        }),
+      },
+    },
+  } as unknown as FastifyRequest;
+}
+
+function makeGuardContext(request: FastifyRequest): {
+  readonly context: ExecutionContext;
+  readonly sent: { statusCode?: number; payload?: unknown };
+} {
+  const sent: { statusCode?: number; payload?: unknown } = {};
+  const reply = {
+    status: (statusCode: number) => {
+      sent.statusCode = statusCode;
+      return {
+        header: () => ({
+          send: (payload: unknown) => {
+            sent.payload = payload;
+          },
+        }),
+      };
+    },
+  } as unknown as FastifyReply;
+
+  const context = {
+    switchToHttp: () => ({
+      getRequest: () => request,
+      getResponse: () => reply,
+    }),
+  } as unknown as ExecutionContext;
+
+  return { context, sent };
+}
+
+async function insertUser(db: Db, id: string, label: string): Promise<void> {
+  await db.insert(users).values({
+    id,
+    name: `${RUN_ID}-${label}`,
+    email: `${RUN_ID}-${label}@federation-test.invalid`,
+    emailVerified: false,
+  });
+}
+
+async function seedFixtures(db: Db): Promise<TestIds> {
+  const subjectUserId = `${RUN_ID}-subject`;
+  const otherUserId = `${RUN_ID}-other`;
+  const peerId = crypto.randomUUID();
+  const revokedPeerId = crypto.randomUUID();
+  const activeGrantId = crypto.randomUUID();
+  const revokedGrantId = crypto.randomUUID();
+  const subjectProjectId = crypto.randomUUID();
+  const subjectMissionId = crypto.randomUUID();
+  const otherProjectId = crypto.randomUUID();
+  const teamId = crypto.randomUUID();
+  const unauthorizedTeamId = crypto.randomUUID();
+  const teamProjectId = crypto.randomUUID();
+  const taskIds = [crypto.randomUUID(), crypto.randomUUID(), crypto.randomUUID()] as const;
+  const excludedTaskIds = [crypto.randomUUID(), crypto.randomUUID()] as const;
+  const subjectNoteId = crypto.randomUUID();
+  const otherUserNoteId = crypto.randomUUID();
+
+  await insertUser(db, subjectUserId, 'subject');
+  await insertUser(db, otherUserId, 'other');
+
+  await db.insert(teams).values([
+    {
+      id: teamId,
+      name: `${RUN_ID} allowed team`,
+      slug: `${RUN_ID}-allowed-team`,
+      ownerId: subjectUserId,
+      managerId: subjectUserId,
+    },
+    {
+      id: unauthorizedTeamId,
+      name: `${RUN_ID} unauthorized team`,
+      slug: `${RUN_ID}-unauthorized-team`,
+      ownerId: otherUserId,
+      managerId: otherUserId,
+    },
+  ]);
+
+  await db.insert(teamMembers).values([
+    { teamId, userId: subjectUserId, role: 'member' },
+    { teamId: unauthorizedTeamId, userId: subjectUserId, role: 'member' },
+  ]);
+
+  await db.insert(projects).values([
+    {
+      id: subjectProjectId,
+      name: `${RUN_ID} subject personal project`,
+      ownerType: 'user',
+      ownerId: subjectUserId,
+    },
+    {
+      id: otherProjectId,
+      name: `${RUN_ID} other personal project`,
+      ownerType: 'user',
+      ownerId: otherUserId,
+    },
+    {
+      id: teamProjectId,
+      name: `${RUN_ID} unauthorized team project`,
+      ownerType: 'team',
+      teamId: unauthorizedTeamId,
+    },
+  ]);
+
+  await db.insert(missions).values({
+    id: subjectMissionId,
+    name: `${RUN_ID} subject mission`,
+    projectId: subjectProjectId,
+    userId: subjectUserId,
+  });
+
+  await db.insert(tasks).values([
+    {
+      id: taskIds[0],
+      title: `${RUN_ID} visible task 1`,
+      missionId: subjectMissionId,
+      createdAt: new Date('2026-06-25T03:00:00.000Z'),
+      updatedAt: new Date('2026-06-25T03:00:00.000Z'),
+    },
+    {
+      id: taskIds[1],
+      title: `${RUN_ID} visible task 2`,
+      projectId: subjectProjectId,
+      createdAt: new Date('2026-06-25T02:00:00.000Z'),
+      updatedAt: new Date('2026-06-25T02:00:00.000Z'),
+    },
+    {
+      id: taskIds[2],
+      title: `${RUN_ID} visible task 3`,
+      projectId: subjectProjectId,
+      createdAt: new Date('2026-06-25T01:00:00.000Z'),
+      updatedAt: new Date('2026-06-25T01:00:00.000Z'),
+    },
+    {
+      id: excludedTaskIds[0],
+      title: `${RUN_ID} other user task`,
+      projectId: otherProjectId,
+      createdAt: new Date('2026-06-25T04:00:00.000Z'),
+      updatedAt: new Date('2026-06-25T04:00:00.000Z'),
+    },
+    {
+      id: excludedTaskIds[1],
+      title: `${RUN_ID} unauthorized team task`,
+      projectId: teamProjectId,
+      createdAt: new Date('2026-06-25T05:00:00.000Z'),
+      updatedAt: new Date('2026-06-25T05:00:00.000Z'),
+    },
+  ]);
+
+  await db.insert(missionTasks).values([
+    {
+      id: subjectNoteId,
+      missionId: subjectMissionId,
+      userId: subjectUserId,
+      notes: `${RUN_ID} subject visible note`,
+      createdAt: new Date('2026-06-25T03:30:00.000Z'),
+      updatedAt: new Date('2026-06-25T03:30:00.000Z'),
+    },
+    {
+      id: otherUserNoteId,
+      missionId: subjectMissionId,
+      userId: otherUserId,
+      notes: `${RUN_ID} other user note on subject mission`,
+      createdAt: new Date('2026-06-25T04:30:00.000Z'),
+      updatedAt: new Date('2026-06-25T04:30:00.000Z'),
+    },
+  ]);
+
+  await db.insert(federationPeers).values([
+    {
+      id: peerId,
+      commonName: `${RUN_ID}-active-peer`,
+      displayName: `${RUN_ID} Active Peer`,
+      certPem: '-----BEGIN CERTIFICATE-----\nMOCK\n-----END CERTIFICATE-----\n',
+      certSerial: CERT_SERIAL_HEX,
+      certNotAfter: new Date(Date.now() + 86_400_000),
+      state: 'active',
+    },
+    {
+      id: revokedPeerId,
+      commonName: `${RUN_ID}-revoked-peer`,
+      displayName: `${RUN_ID} Revoked Peer`,
+      certPem: '-----BEGIN CERTIFICATE-----\nMOCK\n-----END CERTIFICATE-----\n',
+      certSerial: `${CERT_SERIAL_HEX}${RUN_ID.replace(/-/g, '').slice(0, 8).toUpperCase()}`,
+      certNotAfter: new Date(Date.now() + 86_400_000),
+      state: 'active',
+    },
+  ]);
+
+  await db.insert(federationGrants).values([
+    {
+      id: activeGrantId,
+      peerId,
+      subjectUserId,
+      status: 'active',
+      scope: {
+        resources: ['tasks', 'notes'],
+        excluded_resources: [],
+        filters: {
+          tasks: { include_personal: true, include_teams: [] },
+          notes: { include_personal: true, include_teams: [] },
+        },
+        max_rows_per_query: 2,
+      },
+    },
+    {
+      id: revokedGrantId,
+      peerId,
+      subjectUserId,
+      status: 'revoked',
+      revokedAt: new Date(),
+      revokedReason: `${RUN_ID} revoked grant fixture`,
+      scope: {
+        resources: ['tasks'],
+        excluded_resources: [],
+        max_rows_per_query: 2,
+      },
+    },
+  ]);
+
+  return {
+    subjectUserId,
+    otherUserId,
+    peerId,
+    revokedPeerId,
+    activeGrantId,
+    revokedGrantId,
+    subjectProjectId,
+    subjectMissionId,
+    otherProjectId,
+    teamId,
+    unauthorizedTeamId,
+    teamProjectId,
+    taskIds,
+    excludedTaskIds,
+    subjectNoteId,
+    otherUserNoteId,
+  };
+}
+
+async function cleanupFixtures(db: Db, ids: TestIds | undefined): Promise<void> {
+  if (!ids) {
+    return;
+  }
+
+  await db
+    .delete(missionTasks)
+    .where(inArray(missionTasks.id, [ids.subjectNoteId, ids.otherUserNoteId]))
+    .catch(() => {});
+  await db
+    .delete(tasks)
+    .where(inArray(tasks.id, [...ids.taskIds, ...ids.excludedTaskIds]))
+    .catch(() => {});
+  await db
+    .delete(missions)
+    .where(eq(missions.id, ids.subjectMissionId))
+    .catch(() => {});
+  await db
+    .delete(projects)
+    .where(inArray(projects.id, [ids.subjectProjectId, ids.otherProjectId, ids.teamProjectId]))
+    .catch(() => {});
+  await db
+    .delete(teamMembers)
+    .where(
+      and(
+        eq(teamMembers.userId, ids.subjectUserId),
+        inArray(teamMembers.teamId, [ids.teamId, ids.unauthorizedTeamId]),
+      ),
+    )
+    .catch(() => {});
+  await db
+    .delete(teams)
+    .where(inArray(teams.id, [ids.teamId, ids.unauthorizedTeamId]))
+    .catch(() => {});
+  await db
+    .delete(federationGrants)
+    .where(inArray(federationGrants.id, [ids.activeGrantId, ids.revokedGrantId]))
+    .catch(() => {});
+  await db
+    .delete(federationPeers)
+    .where(inArray(federationPeers.id, [ids.peerId, ids.revokedPeerId]))
+    .catch(() => {});
+  await db
+    .delete(users)
+    .where(inArray(users.id, [ids.subjectUserId, ids.otherUserId]))
+    .catch(() => {});
+}
+
+describe.skipIf(!run)('federation M3 list verb — single-gateway integration', () => {
+  let handle: DbHandle;
+  let db: Db;
+  let moduleRef: TestingModule;
+  let guard: FederationAuthGuard;
+  let listController: ListController;
+  let ids: TestIds | undefined;
+
+  beforeAll(async () => {
+    handle = createDb(PG_URL);
+    db = handle.db;
+    ids = await seedFixtures(db);
+
+    moduleRef = await Test.createTestingModule({
+      controllers: [ListController],
+      providers: [
+        { provide: DB, useValue: db },
+        GrantsService,
+        FederationAuthGuard,
+        FederationScopeService,
+        FederationListQueryService,
+      ],
+    }).compile();
+
+    guard = moduleRef.get(FederationAuthGuard);
+    listController = moduleRef.get(ListController);
+  }, 30_000);
+
+  afterAll(async () => {
+    await moduleRef?.close().catch((e: unknown) => console.error('[fed-m3-10 cleanup]', e));
+    await cleanupFixtures(db, ids).catch((e: unknown) => console.error('[fed-m3-10 cleanup]', e));
+    await handle?.close().catch((e: unknown) => console.error('[fed-m3-10 cleanup]', e));
+  });
+
+  it('#6 — rejects a client cert with malformed/missing Mosaic OIDs with 401', async () => {
+    const malformedOidCert = await makeSelfSignedCert();
+    const request = makeFederationRequest(malformedOidCert);
+    const { context, sent } = makeGuardContext(request);
+
+    await expect(guard.canActivate(context)).resolves.toBe(false);
+    expect(sent.statusCode).toBe(401);
+    expect(sent.payload).toMatchObject({
+      error: {
+        code: 'unauthorized',
+        message: expect.stringContaining('missing required OID'),
+      },
+    });
+    expect(request.federationContext).toBeUndefined();
+  });
+
+  it('#6 — rejects a valid client cert when its grant is revoked with 403', async () => {
+    expect(ids).toBeDefined();
+    const revokedCert = await makeMosaicIssuedCert({
+      grantId: ids!.revokedGrantId,
+      subjectUserId: ids!.subjectUserId,
+    });
+    const request = makeFederationRequest(revokedCert);
+    const { context, sent } = makeGuardContext(request);
+
+    await expect(guard.canActivate(context)).resolves.toBe(false);
+    expect(sent.statusCode).toBe(403);
+    expect(sent.payload).toMatchObject({
+      error: {
+        code: 'forbidden',
+        message: 'Federation access denied',
+      },
+    });
+    expect(request.federationContext).toBeUndefined();
+  });
+
+  it('#7 — enforces max_rows_per_query on POST /api/federation/v1/list/:resource', async () => {
+    expect(ids).toBeDefined();
+    const activeCert = await makeMosaicIssuedCert({
+      grantId: ids!.activeGrantId,
+      subjectUserId: ids!.subjectUserId,
+    });
+    const request = makeFederationRequest(activeCert);
+    const { context } = makeGuardContext(request);
+
+    await expect(guard.canActivate(context)).resolves.toBe(true);
+
+    const response = await listController.list('tasks', request, { limit: 100 });
+    const returnedIds = response.items.map((item) => item['id']);
+
+    expect(response.items).toHaveLength(2);
+    expect(response._truncated).toBe(true);
+    expect(response.nextCursor).toEqual(expect.any(String));
+    expect(returnedIds).toEqual([ids!.taskIds[0], ids!.taskIds[1]]);
+    expect(returnedIds).not.toContain(ids!.taskIds[2]);
+    for (const excludedId of ids!.excludedTaskIds) {
+      expect(returnedIds).not.toContain(excludedId);
+    }
+    expect(response.items.every((item) => item._source === 'local')).toBe(true);
+  });
+
+  it('excludes another user mission task notes on the same authorized mission', async () => {
+    expect(ids).toBeDefined();
+    const activeCert = await makeMosaicIssuedCert({
+      grantId: ids!.activeGrantId,
+      subjectUserId: ids!.subjectUserId,
+    });
+    const request = makeFederationRequest(activeCert);
+    const { context } = makeGuardContext(request);
+
+    await expect(guard.canActivate(context)).resolves.toBe(true);
+
+    const response = await listController.list('notes', request, { limit: 10 });
+    const returnedIds = response.items.map((item) => item['id']);
+
+    expect(returnedIds).toEqual([ids!.subjectNoteId]);
+    expect(returnedIds).not.toContain(ids!.otherUserNoteId);
+    expect(response.items.every((item) => item._source === 'local')).toBe(true);
+  });
+
+  it('fails closed for unsupported list resources', async () => {
+    expect(ids).toBeDefined();
+    const activeCert = await makeMosaicIssuedCert({
+      grantId: ids!.activeGrantId,
+      subjectUserId: ids!.subjectUserId,
+    });
+    const request = makeFederationRequest(activeCert);
+    const { context } = makeGuardContext(request);
+
+    await expect(guard.canActivate(context)).resolves.toBe(true);
+
+    await expect(listController.list('widgets', request, {})).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'scope_violation',
+          message: 'Requested federation resource is not supported',
+        },
+      },
+      status: 403,
+    });
+  });
+});

apps/gateway/src/admin/admin-health.controller.ts

@@ -1,9 +1,11 @@
-import { Controller, Get, Inject, UseGuards } from '@nestjs/common';
+import { Controller, Get, Inject, Optional, UseGuards } from '@nestjs/common';
 import { sql, type Db } from '@mosaicstack/db';
 import { createQueue } from '@mosaicstack/queue';
+import type { MosaicConfig } from '@mosaicstack/config';
 import { DB } from '../database/database.module.js';
 import { AgentService } from '../agent/agent.service.js';
 import { ProviderService } from '../agent/provider.service.js';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { AdminGuard } from './admin.guard.js';
 import type { HealthStatusDto, ServiceStatusDto } from './admin.dto.js';
 
@@ -14,6 +16,9 @@ export class AdminHealthController {
     @Inject(DB) private readonly db: Db,
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(ProviderService) private readonly providerService: ProviderService,
+    @Optional()
+    @Inject(MOSAIC_CONFIG)
+    private readonly mosaicConfig: MosaicConfig | null,
   ) {}
 
   @Get()
@@ -55,6 +60,14 @@ export class AdminHealthController {
   }
 
   private async checkCache(): Promise<ServiceStatusDto> {
+    // On Local tier there is no Redis. The cache is intentionally absent, which
+    // is a healthy state for this tier — report 'ok' rather than opening a new
+    // ioredis connection on every admin health check (which would spam
+    // ECONNREFUSED and create/destroy a connection per request). latencyMs 0
+    // signals "no cache backend to measure" for this tier.
+    if (this.mosaicConfig?.queue?.type === 'local') {
+      return { status: 'ok', latencyMs: 0 };
+    }
     const start = Date.now();
     const handle = createQueue();
     try {

apps/gateway/src/commands/command-executor-p8012.spec.ts

@@ -72,13 +72,13 @@ const mockChatGateway = {
   broadcastSessionInfo: vi.fn(),
 };
 
-function buildService(): CommandExecutorService {
+function buildService(redis: typeof mockRedis | null = mockRedis): CommandExecutorService {
   return new CommandExecutorService(
     mockRegistry as never,
     mockAgentService as never,
     mockSystemOverride as never,
     mockSessionGC as never,
-    mockRedis as never,
+    redis as never,
     mockBrain as never,
     null,
     mockChatGateway as never,
@@ -131,6 +131,22 @@ describe('CommandExecutorService — P8-012 commands', () => {
     expect(ttl).toBe(300);
   });
 
+  it('/provider login remains available without Redis on the local tier', async () => {
+    const localService = buildService(null);
+    const payload: SlashCommandPayload = {
+      command: 'provider',
+      args: 'login anthropic',
+      conversationId,
+    };
+
+    const result = await localService.execute(payload, userScope);
+
+    expect(result.success).toBe(true);
+    expect(result.message).not.toContain('token=');
+    expect(result.data).toEqual({ provider: 'anthropic' });
+    expect(mockRedis.set).not.toHaveBeenCalled();
+  });
+
   // /provider with no args — returns usage
   it('/provider with no args returns usage message', async () => {
     const payload: SlashCommandPayload = { command: 'provider', conversationId };

apps/gateway/src/commands/command-executor.service.ts

@@ -23,7 +23,10 @@ export class CommandExecutorService {
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(SystemOverrideService) private readonly systemOverride: SystemOverrideService,
     @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
-    @Inject(COMMANDS_REDIS) private readonly redis: QueueHandle['redis'],
+    // On Local tier COMMANDS_REDIS is null — provider login caching is skipped.
+    @Optional()
+    @Inject(COMMANDS_REDIS)
+    private readonly redis: QueueHandle['redis'] | null,
     @Inject(BRAIN) private readonly brain: Brain,
     @Optional()
     @Inject(forwardRef(() => ReloadService))
@@ -443,14 +446,16 @@ export class CommandExecutorService {
           byte.toString(16).padStart(2, '0'),
         ).join('');
         const key = `mosaic:auth:poll:${tokenHash}`;
-        // Persist only a short-lived token digest. The raw token is delivered only by
-        // the authenticated dashboard flow, never in chat output or command metadata.
-        await this.redis.set(
-          key,
-          JSON.stringify({ status: 'pending', provider: providerName, userId }),
-          'EX',
-          300,
-        );
+        if (this.redis) {
+          // Persist only a short-lived token digest. The raw token is delivered only by
+          // the authenticated dashboard flow, never in chat output or command metadata.
+          await this.redis.set(
+            key,
+            JSON.stringify({ status: 'pending', provider: providerName, userId }),
+            'EX',
+            300,
+          );
+        }
         return {
           command: 'provider',
           success: true,

apps/gateway/src/commands/commands.module.ts

@@ -1,5 +1,7 @@
-import { forwardRef, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
+import { forwardRef, Inject, Module, Optional, type OnApplicationShutdown } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
+import type { MosaicConfig } from '@mosaicstack/config';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { ChatModule } from '../chat/chat.module.js';
 import { GCModule } from '../gc/gc.module.js';
 import { ReloadModule } from '../reload/reload.module.js';
@@ -16,13 +18,17 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
   providers: [
     {
       provide: COMMANDS_QUEUE_HANDLE,
-      useFactory: (): QueueHandle => {
+      useFactory: (config: MosaicConfig | null): QueueHandle | null => {
+        // On Local tier there is no Redis — skip the ioredis connection.
+        // CommandExecutorService falls back to no-cache for /provider login on local.
+        if (config?.queue?.type === 'local') return null;
         return createQueue();
       },
+      inject: [MOSAIC_CONFIG],
     },
     {
       provide: COMMANDS_REDIS,
-      useFactory: (handle: QueueHandle) => handle.redis,
+      useFactory: (handle: QueueHandle | null) => handle?.redis ?? null,
       inject: [COMMANDS_QUEUE_HANDLE],
     },
     CommandRegistryService,
@@ -38,9 +44,13 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
   ],
 })
 export class CommandsModule implements OnApplicationShutdown {
-  constructor(@Inject(COMMANDS_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
+  constructor(
+    @Optional()
+    @Inject(COMMANDS_QUEUE_HANDLE)
+    private readonly handle: QueueHandle | null,
+  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await this.handle.close().catch(() => {});
+    await this.handle?.close().catch(() => {});
   }
 }

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

@@ -5,6 +5,8 @@ import { EnrollmentController } from './enrollment.controller.js';
 import { EnrollmentService } from './enrollment.service.js';
 import { FederationController } from './federation.controller.js';
 import { CapabilitiesController } from './server/verbs/capabilities.controller.js';
+import { GetController } from './server/verbs/get.controller.js';
+import { FederationGetQueryService } from './server/verbs/get-query.service.js';
 import { GrantsService } from './grants.service.js';
 import { FederationClientService, QuerySourceService } from './client/index.js';
 import { FederationAuthGuard, FederationScopeService } from './server/index.js';
@@ -12,7 +14,13 @@ import { ListController } from './server/verbs/list.controller.js';
 import { FederationListQueryService } from './server/verbs/list-query.service.js';
 
 @Module({
-  controllers: [EnrollmentController, FederationController, CapabilitiesController, ListController],
+  controllers: [
+    EnrollmentController,
+    FederationController,
+    CapabilitiesController,
+    ListController,
+    GetController,
+  ],
   providers: [
     AdminGuard,
     CaService,
@@ -23,6 +31,7 @@ import { FederationListQueryService } from './server/verbs/list-query.service.js
     FederationAuthGuard,
     FederationScopeService,
     FederationListQueryService,
+    FederationGetQueryService,
   ],
   exports: [
     CaService,
@@ -33,6 +42,7 @@ import { FederationListQueryService } from './server/verbs/list-query.service.js
     FederationAuthGuard,
     FederationScopeService,
     FederationListQueryService,
+    FederationGetQueryService,
   ],
 })
 export class FederationModule {}

apps/gateway/src/federation/server/verbs/__tests__/get-query.service.spec.ts

@@ -0,0 +1,348 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import {
+  createPgliteDb,
+  missionTasks,
+  missions,
+  projects,
+  runPgliteMigrations,
+  teams,
+  users,
+  type Db,
+  type DbHandle,
+} from '@mosaicstack/db';
+import type { FederationScopeQueryFilter } from '../../scope.service.js';
+import { FederationGetQueryService } from '../get-query.service.js';
+
+const CREDENTIAL_FILTER: FederationScopeQueryFilter = {
+  resource: 'credentials',
+  subjectUserId: 'user-1',
+  includePersonal: true,
+  teamIds: [],
+  limit: 1,
+  maxRowsPerQuery: 25,
+};
+
+const SUBJECT_USER_ID = 'fed-m3-06-subject';
+const OTHER_USER_ID = 'fed-m3-06-other';
+const TEAM_ID = '06000000-0000-4000-8000-000000000001';
+const UNAUTHORIZED_TEAM_ID = '06000000-0000-4000-8000-000000000002';
+const PERSONAL_PROJECT_ID = '06000000-0000-4000-8000-000000000101';
+const TEAM_PROJECT_ID = '06000000-0000-4000-8000-000000000102';
+const UNAUTHORIZED_PROJECT_ID = '06000000-0000-4000-8000-000000000103';
+const PERSONAL_MISSION_ID = '06000000-0000-4000-8000-000000000201';
+const TEAM_MISSION_ID = '06000000-0000-4000-8000-000000000202';
+const UNAUTHORIZED_MISSION_ID = '06000000-0000-4000-8000-000000000203';
+const SUBJECT_TEAM_NOTE_ID = '06000000-0000-4000-8000-000000000301';
+const OTHER_TEAM_NOTE_ID = '06000000-0000-4000-8000-000000000302';
+const SUBJECT_PERSONAL_NOTE_ID = '06000000-0000-4000-8000-000000000303';
+const SUBJECT_UNAUTHORIZED_NOTE_ID = '06000000-0000-4000-8000-000000000304';
+
+let dbHandle: DbHandle | undefined;
+
+function makeService() {
+  return new FederationGetQueryService({} as Db);
+}
+
+function makeDbService() {
+  if (!dbHandle) {
+    throw new Error('test DB not initialized');
+  }
+  return new FederationGetQueryService(dbHandle.db);
+}
+
+async function seedNotesFixture() {
+  if (!dbHandle) {
+    throw new Error('test DB not initialized');
+  }
+
+  await dbHandle.db.insert(users).values([
+    {
+      id: SUBJECT_USER_ID,
+      name: 'Federation Subject',
+      email: `${SUBJECT_USER_ID}@example.test`,
+      emailVerified: false,
+    },
+    {
+      id: OTHER_USER_ID,
+      name: 'Federation Other',
+      email: `${OTHER_USER_ID}@example.test`,
+      emailVerified: false,
+    },
+  ]);
+
+  await dbHandle.db.insert(teams).values([
+    {
+      id: TEAM_ID,
+      name: 'FED-M3-06 Team',
+      slug: 'fed-m3-06-team',
+      ownerId: SUBJECT_USER_ID,
+      managerId: SUBJECT_USER_ID,
+    },
+    {
+      id: UNAUTHORIZED_TEAM_ID,
+      name: 'FED-M3-06 Unauthorized Team',
+      slug: 'fed-m3-06-unauthorized-team',
+      ownerId: OTHER_USER_ID,
+      managerId: OTHER_USER_ID,
+    },
+  ]);
+
+  await dbHandle.db.insert(projects).values([
+    {
+      id: PERSONAL_PROJECT_ID,
+      name: 'FED-M3-06 Personal Project',
+      ownerId: SUBJECT_USER_ID,
+      ownerType: 'user',
+    },
+    {
+      id: TEAM_PROJECT_ID,
+      name: 'FED-M3-06 Team Project',
+      teamId: TEAM_ID,
+      ownerType: 'team',
+    },
+    {
+      id: UNAUTHORIZED_PROJECT_ID,
+      name: 'FED-M3-06 Unauthorized Project',
+      teamId: UNAUTHORIZED_TEAM_ID,
+      ownerType: 'team',
+    },
+  ]);
+
+  await dbHandle.db.insert(missions).values([
+    {
+      id: PERSONAL_MISSION_ID,
+      name: 'FED-M3-06 Personal Mission',
+      projectId: PERSONAL_PROJECT_ID,
+      userId: SUBJECT_USER_ID,
+    },
+    {
+      id: TEAM_MISSION_ID,
+      name: 'FED-M3-06 Team Mission',
+      projectId: TEAM_PROJECT_ID,
+      userId: SUBJECT_USER_ID,
+    },
+    {
+      id: UNAUTHORIZED_MISSION_ID,
+      name: 'FED-M3-06 Unauthorized Mission',
+      projectId: UNAUTHORIZED_PROJECT_ID,
+      userId: SUBJECT_USER_ID,
+    },
+  ]);
+
+  await dbHandle.db.insert(missionTasks).values([
+    {
+      id: SUBJECT_TEAM_NOTE_ID,
+      missionId: TEAM_MISSION_ID,
+      userId: SUBJECT_USER_ID,
+      notes: 'subject note on team mission',
+      createdAt: new Date('2026-06-24T03:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T03:00:00.000Z'),
+    },
+    {
+      id: OTHER_TEAM_NOTE_ID,
+      missionId: TEAM_MISSION_ID,
+      userId: OTHER_USER_ID,
+      notes: 'other user note on team mission',
+      createdAt: new Date('2026-06-24T02:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T02:00:00.000Z'),
+    },
+    {
+      id: SUBJECT_PERSONAL_NOTE_ID,
+      missionId: PERSONAL_MISSION_ID,
+      userId: SUBJECT_USER_ID,
+      notes: 'subject note on personal mission',
+      createdAt: new Date('2026-06-24T01:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T01:00:00.000Z'),
+    },
+    {
+      id: SUBJECT_UNAUTHORIZED_NOTE_ID,
+      missionId: UNAUTHORIZED_MISSION_ID,
+      userId: SUBJECT_USER_ID,
+      notes: 'subject note outside grant-visible missions',
+      createdAt: new Date('2026-06-24T04:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T04:00:00.000Z'),
+    },
+  ]);
+}
+
+describe('FederationGetQueryService', () => {
+  beforeAll(async () => {
+    dbHandle = createPgliteDb(`memory://fed-m3-06-get-${Date.now()}`);
+    await runPgliteMigrations(dbHandle);
+    await seedNotesFixture();
+  });
+
+  afterAll(async () => {
+    await dbHandle?.close();
+    dbHandle = undefined;
+  });
+
+  it('denies sensitive resources in native RBAC for M3 get reads', async () => {
+    const service = makeService();
+
+    await expect(
+      service.evaluateReadAccess({
+        grantId: 'grant-1',
+        peerId: 'peer-1',
+        subjectUserId: 'user-1',
+        resource: 'credentials',
+      }),
+    ).resolves.toMatchObject({
+      allowed: false,
+      reason: 'credentials federation get access is not implemented in M3',
+    });
+  });
+
+  it('allows personal memory reads without requiring team lookup', async () => {
+    const service = makeService();
+
+    await expect(
+      service.evaluateReadAccess({
+        grantId: 'grant-1',
+        peerId: 'peer-1',
+        subjectUserId: 'user-1',
+        resource: 'memory',
+      }),
+    ).resolves.toEqual({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+  });
+
+  it('uses subject team membership as the native RBAC upper bound for task and note reads', async () => {
+    const service = makeService();
+    const listSubjectTeamIds = vi.fn().mockResolvedValue(['team-1', 'team-2']);
+    (
+      service as unknown as {
+        listSubjectTeamIds: (subjectUserId: string) => Promise<string[]>;
+      }
+    ).listSubjectTeamIds = listSubjectTeamIds;
+
+    await expect(
+      service.evaluateReadAccess({
+        grantId: 'grant-1',
+        peerId: 'peer-1',
+        subjectUserId: 'user-1',
+        resource: 'tasks',
+      }),
+    ).resolves.toEqual({
+      allowed: true,
+      access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
+    });
+    expect(listSubjectTeamIds).toHaveBeenCalledWith('user-1');
+  });
+
+  it('does not query storage for sensitive get resources even if scope allowed them', async () => {
+    const service = makeService();
+
+    await expect(service.get({ filter: CREDENTIAL_FILTER, id: 'cred-1' })).resolves.toEqual({
+      status: 'denied',
+      reason: 'credentials federation get is not implemented',
+    });
+  });
+
+  it('fails closed for unsupported resources instead of returning undefined', async () => {
+    const service = makeService();
+
+    await expect(
+      service.get({
+        filter: {
+          ...CREDENTIAL_FILTER,
+          resource: 'unknown-resource' as FederationScopeQueryFilter['resource'],
+        },
+        id: 'row-1',
+      }),
+    ).resolves.toEqual({
+      status: 'denied',
+      reason: 'Unsupported federation get resource: unknown-resource',
+    });
+  });
+
+  it('does not leak another user mission task note through team-scoped get reads', async () => {
+    const service = makeDbService();
+
+    await expect(
+      service.get({
+        filter: {
+          resource: 'notes',
+          subjectUserId: SUBJECT_USER_ID,
+          includePersonal: false,
+          teamIds: [TEAM_ID],
+          limit: 1,
+          maxRowsPerQuery: 10,
+        },
+        id: OTHER_TEAM_NOTE_ID,
+      }),
+    ).resolves.toEqual({
+      status: 'denied',
+      reason: 'Note is outside the federated scope',
+    });
+  });
+
+  it('does not return subject notes from missions outside the grant-visible project set', async () => {
+    const service = makeDbService();
+
+    await expect(
+      service.get({
+        filter: {
+          resource: 'notes',
+          subjectUserId: SUBJECT_USER_ID,
+          includePersonal: true,
+          teamIds: [TEAM_ID],
+          limit: 1,
+          maxRowsPerQuery: 10,
+        },
+        id: SUBJECT_UNAUTHORIZED_NOTE_ID,
+      }),
+    ).resolves.toEqual({
+      status: 'denied',
+      reason: 'Note is outside the federated scope',
+    });
+  });
+
+  it('returns a subject note only when subject ownership and authorized mission intersect', async () => {
+    const service = makeDbService();
+
+    await expect(
+      service.get({
+        filter: {
+          resource: 'notes',
+          subjectUserId: SUBJECT_USER_ID,
+          includePersonal: false,
+          teamIds: [TEAM_ID],
+          limit: 1,
+          maxRowsPerQuery: 10,
+        },
+        id: SUBJECT_TEAM_NOTE_ID,
+      }),
+    ).resolves.toMatchObject({
+      status: 'found',
+      item: {
+        id: SUBJECT_TEAM_NOTE_ID,
+        missionId: TEAM_MISSION_ID,
+        content: 'subject note on team mission',
+      },
+    });
+  });
+
+  it('does not return subject personal notes when includePersonal is false', async () => {
+    const service = makeDbService();
+
+    await expect(
+      service.get({
+        filter: {
+          resource: 'notes',
+          subjectUserId: SUBJECT_USER_ID,
+          includePersonal: false,
+          teamIds: [TEAM_ID],
+          limit: 1,
+          maxRowsPerQuery: 10,
+        },
+        id: SUBJECT_PERSONAL_NOTE_ID,
+      }),
+    ).resolves.toEqual({
+      status: 'denied',
+      reason: 'Note is outside the federated scope',
+    });
+  });
+});

apps/gateway/src/federation/server/verbs/__tests__/get.controller.spec.ts

@@ -0,0 +1,207 @@
+import 'reflect-metadata';
+import { RequestMethod } from '@nestjs/common';
+import type { FastifyRequest } from 'fastify';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FederationAuthGuard } from '../../federation-auth.guard.js';
+import type {
+  FederationScopeEvaluationResult,
+  FederationScopeQueryFilter,
+} from '../../scope.service.js';
+import { GetController } from '../get.controller.js';
+import type { FederationGetQueryResult } from '../get-query.service.js';
+
+const FEDERATION_CONTEXT = {
+  grantId: 'grant-1',
+  peerId: 'peer-1',
+  subjectUserId: 'user-1',
+  scope: { resources: ['tasks'], max_rows_per_query: 25 },
+};
+
+const TASK_FILTER: FederationScopeQueryFilter = {
+  resource: 'tasks',
+  subjectUserId: 'user-1',
+  includePersonal: true,
+  teamIds: ['team-1'],
+  limit: 1,
+  maxRowsPerQuery: 25,
+};
+
+function makeRequest(): FastifyRequest {
+  return { federationContext: FEDERATION_CONTEXT } as unknown as FastifyRequest;
+}
+
+function allowedScope(
+  filter: FederationScopeQueryFilter = TASK_FILTER,
+): FederationScopeEvaluationResult {
+  return { allowed: true, filter };
+}
+
+function makeController(opts?: {
+  scopeResult?: FederationScopeEvaluationResult;
+  queryResult?: FederationGetQueryResult;
+}) {
+  const scope = {
+    evaluateAccess: vi.fn().mockResolvedValue(opts?.scopeResult ?? allowedScope()),
+  };
+  const query = {
+    evaluateReadAccess: vi.fn(),
+    get: vi.fn().mockResolvedValue(
+      opts?.queryResult ?? {
+        status: 'found',
+        item: {
+          id: 'task-1',
+          title: 'Federated task',
+          createdAt: new Date('2026-06-24T00:00:00.000Z'),
+        },
+      },
+    ),
+  };
+
+  return {
+    controller: new GetController(scope as never, query as never),
+    scope,
+    query,
+  };
+}
+
+describe('GetController', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('declares POST /api/federation/v1/get/:resource/:id protected only by FederationAuthGuard', () => {
+    expect(Reflect.getMetadata('path', GetController)).toBe('api/federation/v1/get');
+    expect(Reflect.getMetadata('path', GetController.prototype.get)).toBe(':resource/:id');
+    expect(Reflect.getMetadata('method', GetController.prototype.get)).toBe(RequestMethod.POST);
+    expect(Reflect.getMetadata('__guards__', GetController)).toEqual([FederationAuthGuard]);
+  });
+
+  it('runs AuthGuard context through ScopeService and returns one local-source tagged row', async () => {
+    const { controller, scope, query } = makeController();
+
+    const response = await controller.get('tasks', 'task-1', makeRequest());
+
+    expect(scope.evaluateAccess).toHaveBeenCalledWith({
+      context: FEDERATION_CONTEXT,
+      resource: 'tasks',
+      requestedLimit: 1,
+      nativeRbac: query,
+    });
+    expect(query.get).toHaveBeenCalledWith({ filter: TASK_FILTER, id: 'task-1' });
+    expect(response).toEqual({
+      item: {
+        id: 'task-1',
+        title: 'Federated task',
+        createdAt: new Date('2026-06-24T00:00:00.000Z'),
+        _source: 'local',
+      },
+    });
+  });
+
+  it('returns a federation error envelope when auth guard context is missing', async () => {
+    const { controller, scope, query } = makeController();
+
+    await expect(
+      controller.get('tasks', 'task-1', {} as unknown as FastifyRequest),
+    ).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'unauthorized',
+          message: 'Federation context missing',
+        },
+      },
+      status: 401,
+    });
+    expect(scope.evaluateAccess).not.toHaveBeenCalled();
+    expect(query.get).not.toHaveBeenCalled();
+  });
+
+  it('returns a federation error envelope when scope evaluation denies access', async () => {
+    const { controller, query } = makeController({
+      scopeResult: {
+        allowed: false,
+        deny: {
+          code: 'resource_excluded',
+          stage: 'resource_exclusion',
+          statusCode: 403,
+          message: 'Requested federation resource is explicitly excluded by grant scope',
+          grantId: 'grant-1',
+          peerId: 'peer-1',
+          subjectUserId: 'user-1',
+          resource: 'credentials',
+        },
+      },
+    });
+
+    await expect(controller.get('credentials', 'cred-1', makeRequest())).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'scope_violation',
+          message: 'Requested federation resource is explicitly excluded by grant scope',
+        },
+      },
+      status: 403,
+    });
+    expect(query.get).not.toHaveBeenCalled();
+  });
+
+  it('returns 404 when the scoped query layer cannot find the resource id', async () => {
+    const { controller } = makeController({ queryResult: { status: 'not_found' } });
+
+    await expect(controller.get('tasks', 'missing-task', makeRequest())).rejects.toMatchObject({
+      response: { error: { code: 'not_found' } },
+      status: 404,
+    });
+  });
+
+  it('returns 403 when the resource exists outside the RBAC/scope intersection', async () => {
+    const { controller } = makeController({
+      queryResult: { status: 'denied', reason: 'Task is outside the federated scope' },
+    });
+
+    await expect(controller.get('tasks', 'task-2', makeRequest())).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'scope_violation',
+          message: 'Task is outside the federated scope',
+        },
+      },
+      status: 403,
+    });
+  });
+
+  it('fails closed when the query layer denies an unsupported resource', async () => {
+    const unsupportedFilter: FederationScopeQueryFilter = {
+      ...TASK_FILTER,
+      resource: 'unknown-resource' as FederationScopeQueryFilter['resource'],
+    };
+    const { controller } = makeController({
+      scopeResult: allowedScope(unsupportedFilter),
+      queryResult: {
+        status: 'denied',
+        reason: 'Unsupported federation get resource: unknown-resource',
+      },
+    });
+
+    await expect(controller.get('unknown-resource', 'row-1', makeRequest())).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'scope_violation',
+          message: 'Unsupported federation get resource: unknown-resource',
+        },
+      },
+      status: 403,
+    });
+  });
+
+  it('rejects empty ids before evaluating scope', async () => {
+    const { controller, scope, query } = makeController();
+
+    await expect(controller.get('tasks', '   ', makeRequest())).rejects.toMatchObject({
+      response: { error: { code: 'invalid_request' } },
+      status: 400,
+    });
+    expect(scope.evaluateAccess).not.toHaveBeenCalled();
+    expect(query.get).not.toHaveBeenCalled();
+  });
+});

apps/gateway/src/federation/server/verbs/get-query.service.ts

@@ -0,0 +1,311 @@
+/**
+ * Federation get query layer (FED-M3-06).
+ *
+ * Read-only DB adapter used by GetController after FederationAuthGuard and
+ * FederationScopeService have established the subject user, allowed resource,
+ * native-RBAC intersection, and row cap. Audit writes are intentionally
+ * deferred to M4.
+ */
+
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  eq,
+  inArray,
+  insights,
+  or,
+  missionTasks,
+  missions,
+  preferences,
+  projects,
+  tasks,
+  teamMembers,
+  type Db,
+} from '@mosaicstack/db';
+import { DB } from '../../../database/database.module.js';
+import type {
+  FederationNativeRbacEvaluator,
+  FederationNativeRbacRequest,
+  FederationNativeRbacResult,
+  FederationScopeQueryFilter,
+} from '../scope.service.js';
+
+export interface FederationGetQueryRequest {
+  readonly filter: FederationScopeQueryFilter;
+  readonly id: string;
+}
+
+export interface FederationGetQueryFoundResult<T extends object = Record<string, unknown>> {
+  readonly status: 'found';
+  readonly item: T;
+}
+
+export interface FederationGetQueryNotFoundResult {
+  readonly status: 'not_found';
+}
+
+export interface FederationGetQueryDeniedResult {
+  readonly status: 'denied';
+  readonly reason: string;
+}
+
+export type FederationGetQueryResult<T extends object = Record<string, unknown>> =
+  | FederationGetQueryFoundResult<T>
+  | FederationGetQueryNotFoundResult
+  | FederationGetQueryDeniedResult;
+
+type RowObject = Record<string, unknown>;
+
+function firstRow<T>(rows: T[]): T | undefined {
+  return rows[0];
+}
+
+function rowBelongsToAccessibleProjectOrMission(
+  row: { projectId?: string | null; missionId?: string | null },
+  projectIds: readonly string[],
+  missionIds: readonly string[],
+): boolean {
+  return (
+    (typeof row.projectId === 'string' && projectIds.includes(row.projectId)) ||
+    (typeof row.missionId === 'string' && missionIds.includes(row.missionId))
+  );
+}
+
+@Injectable()
+export class FederationGetQueryService implements FederationNativeRbacEvaluator {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async evaluateReadAccess(
+    request: FederationNativeRbacRequest,
+  ): Promise<FederationNativeRbacResult> {
+    if (request.resource === 'credentials' || request.resource === 'api_keys') {
+      return {
+        allowed: false,
+        reason: `${request.resource} federation get access is not implemented in M3`,
+        details: { resource: request.resource },
+      };
+    }
+
+    if (request.resource === 'memory') {
+      return { allowed: true, access: { includePersonal: true, teamIds: [] } };
+    }
+
+    const teamIds = await this.listSubjectTeamIds(request.subjectUserId);
+    return { allowed: true, access: { includePersonal: true, teamIds } };
+  }
+
+  async get<T extends RowObject = RowObject>(
+    request: FederationGetQueryRequest,
+  ): Promise<FederationGetQueryResult<T>> {
+    return this.getByResource(request.filter, request.id) as Promise<FederationGetQueryResult<T>>;
+  }
+
+  private async getByResource(
+    filter: FederationScopeQueryFilter,
+    id: string,
+  ): Promise<FederationGetQueryResult> {
+    switch (filter.resource) {
+      case 'tasks':
+        return this.getTask(filter, id);
+      case 'notes':
+        return this.getNote(filter, id);
+      case 'memory':
+        return this.getMemory(filter, id);
+      case 'credentials':
+      case 'api_keys':
+        return { status: 'denied', reason: `${filter.resource} federation get is not implemented` };
+      default:
+        return {
+          status: 'denied',
+          reason: `Unsupported federation get resource: ${String(filter.resource)}`,
+        };
+    }
+  }
+
+  private async listSubjectTeamIds(subjectUserId: string): Promise<string[]> {
+    const rows = await this.db
+      .select({ teamId: teamMembers.teamId })
+      .from(teamMembers)
+      .where(eq(teamMembers.userId, subjectUserId));
+
+    return rows.map((row) => row.teamId);
+  }
+
+  private async listAccessibleProjectIds(filter: FederationScopeQueryFilter): Promise<string[]> {
+    const clauses = [];
+    if (filter.includePersonal) {
+      clauses.push(and(eq(projects.ownerType, 'user'), eq(projects.ownerId, filter.subjectUserId)));
+    }
+    if (filter.teamIds.length > 0) {
+      // Project team ownership follows TeamsService.canAccessProject: team-owned
+      // rows are authorized through projects.teamId, while ownerId remains the
+      // user who created/bootstrapped the project.
+      clauses.push(
+        and(eq(projects.ownerType, 'team'), inArray(projects.teamId, [...filter.teamIds])),
+      );
+    }
+
+    if (clauses.length === 0) {
+      return [];
+    }
+
+    const rows = await this.db
+      .select({ id: projects.id })
+      .from(projects)
+      .where(clauses.length === 1 ? clauses[0] : or(...clauses));
+
+    return rows.map((row) => row.id);
+  }
+
+  private async listMissionIds(projectIds: readonly string[]): Promise<string[]> {
+    if (projectIds.length === 0) {
+      return [];
+    }
+
+    const rows = await this.db
+      .select({ id: missions.id })
+      .from(missions)
+      .where(inArray(missions.projectId, [...projectIds]));
+
+    return rows.map((row) => row.id);
+  }
+
+  private async getTask(
+    filter: FederationScopeQueryFilter,
+    id: string,
+  ): Promise<FederationGetQueryResult> {
+    const row = firstRow(
+      await this.db
+        .select({
+          id: tasks.id,
+          title: tasks.title,
+          description: tasks.description,
+          status: tasks.status,
+          priority: tasks.priority,
+          projectId: tasks.projectId,
+          missionId: tasks.missionId,
+          assignee: tasks.assignee,
+          tags: tasks.tags,
+          dueDate: tasks.dueDate,
+          metadata: tasks.metadata,
+          createdAt: tasks.createdAt,
+          updatedAt: tasks.updatedAt,
+        })
+        .from(tasks)
+        .where(eq(tasks.id, id))
+        .limit(1),
+    );
+
+    if (!row) {
+      return { status: 'not_found' };
+    }
+
+    const projectIds = await this.listAccessibleProjectIds(filter);
+    const missionIds = await this.listMissionIds(projectIds);
+    if (!rowBelongsToAccessibleProjectOrMission(row, projectIds, missionIds)) {
+      return { status: 'denied', reason: 'Task is outside the federated scope' };
+    }
+
+    return { status: 'found', item: row as RowObject };
+  }
+
+  private async getNote(
+    filter: FederationScopeQueryFilter,
+    id: string,
+  ): Promise<FederationGetQueryResult> {
+    const row = firstRow(
+      await this.db
+        .select({
+          id: missionTasks.id,
+          missionId: missionTasks.missionId,
+          taskId: missionTasks.taskId,
+          userId: missionTasks.userId,
+          status: missionTasks.status,
+          content: missionTasks.notes,
+          createdAt: missionTasks.createdAt,
+          updatedAt: missionTasks.updatedAt,
+        })
+        .from(missionTasks)
+        .where(eq(missionTasks.id, id))
+        .limit(1),
+    );
+
+    if (!row || row.content === null || row.content === '') {
+      return { status: 'not_found' };
+    }
+
+    const projectIds = await this.listAccessibleProjectIds(filter);
+    const missionIds = await this.listMissionIds(projectIds);
+
+    // mission_tasks rows are user-scoped even when the mission belongs to a team.
+    // Scope-visible missions must intersect with subject ownership; team scope
+    // narrows mission IDs but never widens note reads to another user's rows.
+    if (row.userId !== filter.subjectUserId || !missionIds.includes(row.missionId)) {
+      return { status: 'denied', reason: 'Note is outside the federated scope' };
+    }
+
+    const item = { ...row } as RowObject;
+    delete item['userId'];
+    return { status: 'found', item };
+  }
+
+  private async getMemory(
+    filter: FederationScopeQueryFilter,
+    id: string,
+  ): Promise<FederationGetQueryResult> {
+    const [insightRow, preferenceRow] = await Promise.all([
+      this.db
+        .select({
+          id: insights.id,
+          userId: insights.userId,
+          kind: insights.source,
+          content: insights.content,
+          category: insights.category,
+          relevanceScore: insights.relevanceScore,
+          metadata: insights.metadata,
+          createdAt: insights.createdAt,
+          updatedAt: insights.updatedAt,
+        })
+        .from(insights)
+        .where(eq(insights.id, id))
+        .limit(1)
+        .then(firstRow),
+      this.db
+        .select({
+          id: preferences.id,
+          userId: preferences.userId,
+          kind: preferences.category,
+          key: preferences.key,
+          value: preferences.value,
+          source: preferences.source,
+          mutable: preferences.mutable,
+          createdAt: preferences.createdAt,
+          updatedAt: preferences.updatedAt,
+        })
+        .from(preferences)
+        .where(eq(preferences.id, id))
+        .limit(1)
+        .then(firstRow),
+    ]);
+
+    const candidates = [insightRow, preferenceRow].filter(
+      (row): row is NonNullable<typeof row> => row !== undefined,
+    );
+    if (candidates.length === 0) {
+      return { status: 'not_found' };
+    }
+
+    if (!filter.includePersonal) {
+      return { status: 'denied', reason: 'Memory personal rows are outside the federated scope' };
+    }
+
+    const accessible = candidates.find((row) => row.userId === filter.subjectUserId);
+    if (!accessible) {
+      return { status: 'denied', reason: 'Memory row belongs to another subject user' };
+    }
+
+    const item = { ...accessible } as RowObject;
+    delete item['userId'];
+    return { status: 'found', item };
+  }
+}

apps/gateway/src/federation/server/verbs/get.controller.ts

@@ -0,0 +1,100 @@
+/**
+ * Federation get verb (FED-M3-06).
+ *
+ * POST /api/federation/v1/get/:resource/:id
+ *
+ * Pipeline: FederationAuthGuard attaches the active grant context, then
+ * FederationScopeService enforces grant scope + native RBAC intersection, then
+ * the read-only query layer fetches one local row and tags it with `_source`.
+ * Read audit-log writes are deferred to M4; this controller does not persist
+ * request or response bodies.
+ */
+
+import { Controller, HttpException, Inject, Param, Post, Req, UseGuards } from '@nestjs/common';
+import type { FastifyRequest } from 'fastify';
+import {
+  FederationInvalidRequestError,
+  FederationNotFoundError,
+  FederationScopeViolationError,
+  FederationUnauthorizedError,
+  SOURCE_LOCAL,
+  type FederationGetResponse,
+  type SourceTag,
+} from '@mosaicstack/types';
+import { FederationAuthGuard } from '../federation-auth.guard.js';
+import '../federation-context.js';
+import { FederationScopeService } from '../scope.service.js';
+import { FederationGetQueryService } from './get-query.service.js';
+
+type FederatedRow = Record<string, unknown> & SourceTag;
+
+function scopeDenyToHttpException(deny: {
+  readonly statusCode: 400 | 403;
+  readonly message: string;
+}): HttpException {
+  const ErrorClass =
+    deny.statusCode === 400 ? FederationInvalidRequestError : FederationScopeViolationError;
+  return new HttpException(new ErrorClass(deny.message, deny).toEnvelope(), deny.statusCode);
+}
+
+@Controller('api/federation/v1/get')
+@UseGuards(FederationAuthGuard)
+export class GetController {
+  constructor(
+    @Inject(FederationScopeService) private readonly scope: FederationScopeService,
+    @Inject(FederationGetQueryService) private readonly query: FederationGetQueryService,
+  ) {}
+
+  @Post(':resource/:id')
+  async get(
+    @Param('resource') resource: string,
+    @Param('id') id: string,
+    @Req() request: FastifyRequest,
+  ): Promise<FederationGetResponse<FederatedRow>> {
+    if (!request.federationContext) {
+      throw new HttpException(
+        new FederationUnauthorizedError('Federation context missing').toEnvelope(),
+        401,
+      );
+    }
+    if (id.trim().length === 0) {
+      throw new HttpException(
+        new FederationInvalidRequestError('Federation get id must not be empty').toEnvelope(),
+        400,
+      );
+    }
+
+    const scopeResult = await this.scope.evaluateAccess({
+      context: request.federationContext,
+      resource,
+      requestedLimit: 1,
+      nativeRbac: this.query,
+    });
+
+    if (!scopeResult.allowed) {
+      throw scopeDenyToHttpException(scopeResult.deny);
+    }
+
+    const result = await this.query.get({ filter: scopeResult.filter, id });
+    if (result.status === 'not_found') {
+      throw new HttpException(
+        new FederationNotFoundError('Requested federation resource was not found').toEnvelope(),
+        404,
+      );
+    }
+    if (result.status === 'denied') {
+      throw new HttpException(
+        new FederationScopeViolationError(result.reason, {
+          resource,
+          id,
+          grantId: request.federationContext.grantId,
+          peerId: request.federationContext.peerId,
+          subjectUserId: request.federationContext.subjectUserId,
+        }).toEnvelope(),
+        403,
+      );
+    }
+
+    return { item: { ...result.item, _source: SOURCE_LOCAL } };
+  }
+}

apps/gateway/src/gc/gc.module.ts

@@ -1,5 +1,7 @@
-import { Module, type OnApplicationShutdown, Inject } from '@nestjs/common';
+import { Module, type OnApplicationShutdown, Inject, Optional } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
+import type { MosaicConfig } from '@mosaicstack/config';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { SessionGCService } from './session-gc.service.js';
 import { REDIS } from './gc.tokens.js';
 
@@ -9,13 +11,17 @@ const GC_QUEUE_HANDLE = 'GC_QUEUE_HANDLE';
   providers: [
     {
       provide: GC_QUEUE_HANDLE,
-      useFactory: (): QueueHandle => {
+      useFactory: (config: MosaicConfig | null): QueueHandle | null => {
+        // On Local tier there is no Redis — skip the ioredis connection entirely.
+        // The Valkey GC sweep is a no-op on Local (no session keys stored there).
+        if (config?.queue?.type === 'local') return null;
         return createQueue();
       },
+      inject: [MOSAIC_CONFIG],
     },
     {
       provide: REDIS,
-      useFactory: (handle: QueueHandle) => handle.redis,
+      useFactory: (handle: QueueHandle | null) => handle?.redis ?? null,
       inject: [GC_QUEUE_HANDLE],
     },
     SessionGCService,
@@ -23,9 +29,13 @@ const GC_QUEUE_HANDLE = 'GC_QUEUE_HANDLE';
   exports: [SessionGCService],
 })
 export class GCModule implements OnApplicationShutdown {
-  constructor(@Inject(GC_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
+  constructor(
+    @Optional()
+    @Inject(GC_QUEUE_HANDLE)
+    private readonly handle: QueueHandle | null,
+  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await this.handle.close().catch(() => {});
+    await this.handle?.close().catch(() => {});
   }
 }

apps/gateway/src/gc/session-gc.service.spec.ts

@@ -119,6 +119,19 @@ describe('SessionGCService', () => {
     ).resolves.toEqual({ allowed: true });
   });
 
+  it('collect() skips Valkey but still demotes only the requested session on local tier', async () => {
+    const localService = new SessionGCService(null, mockLogService as unknown as LogService);
+
+    const result = await localService.collect('local-session');
+
+    expect(result.sessionId).toBe('local-session');
+    expect(result.cleaned.valkeyKeys).toBeUndefined();
+    expect(mockLogService.logs.promoteSessionToWarm).toHaveBeenCalledWith(
+      'local-session',
+      expect.any(Date),
+    );
+  });
+
   it('collect() returns sessionId in result', async () => {
     const result = await service.collect('test-session-id');
     expect(result.sessionId).toBe('test-session-id');

apps/gateway/src/gc/session-gc.service.ts

@@ -1,4 +1,4 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { Inject, Injectable, Optional } from '@nestjs/common';
 import type { QueueHandle } from '@mosaicstack/queue';
 import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
@@ -21,7 +21,10 @@ function escapeRedisGlobLiteral(value: string): string {
 @Injectable()
 export class SessionGCService {
   constructor(
-    @Inject(REDIS) private readonly redis: QueueHandle['redis'],
+    // Local tier has no Redis; lifecycle cleanup still demotes this session's logs.
+    @Optional()
+    @Inject(REDIS)
+    private readonly redis: QueueHandle['redis'] | null,
     @Inject(LOG_SERVICE) private readonly logService: LogService,
   ) {}
 
@@ -29,8 +32,10 @@ export class SessionGCService {
    * Scan Valkey for all keys matching a pattern using SCAN (non-blocking).
    * KEYS is avoided because it blocks the Valkey event loop for the full scan
    * duration, which can cause latency spikes under production key volumes.
+   * Returns an empty population on the Local tier where Redis is disabled.
    */
   private async scanKeys(pattern: string): Promise<string[]> {
+    if (!this.redis) return [];
     const collected: string[] = [];
     let cursor = '0';
     do {
@@ -47,12 +52,14 @@ export class SessionGCService {
   async collect(sessionId: string): Promise<GCResult> {
     const result: GCResult = { sessionId, cleaned: {} };
 
-    // 1. Valkey: delete all session-scoped keys
-    const pattern = `mosaic:session:${escapeRedisGlobLiteral(sessionId)}:*`;
-    const valkeyKeys = await this.scanKeys(pattern);
-    if (valkeyKeys.length > 0) {
-      await this.redis.del(...valkeyKeys);
-      result.cleaned.valkeyKeys = valkeyKeys.length;
+    // 1. Valkey: delete all session-scoped keys (skipped on Local tier).
+    if (this.redis) {
+      const pattern = `mosaic:session:${escapeRedisGlobLiteral(sessionId)}:*`;
+      const valkeyKeys = await this.scanKeys(pattern);
+      if (valkeyKeys.length > 0) {
+        await this.redis.del(...valkeyKeys);
+        result.cleaned.valkeyKeys = valkeyKeys.length;
+      }
     }
 
     // 2. PG: demote hot-tier agent logs for this session only.

apps/gateway/src/log/cron.service.ts

@@ -18,7 +18,7 @@ import type { MosaicJobData } from '../queue/queue.service.js';
 @Injectable()
 export class CronService implements OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(CronService.name);
-  private readonly registeredWorkers: Worker<MosaicJobData>[] = [];
+  private readonly registeredWorkers: Array<Worker<MosaicJobData>> = [];
 
   constructor(
     @Inject(SummarizationService) private readonly summarization: SummarizationService,
@@ -26,6 +26,12 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
   ) {}
 
   async onModuleInit(): Promise<void> {
+    // Local tier deliberately has no BullMQ consumers or repeatable jobs.
+    if (!this.queueService.isEnabled()) {
+      this.logger.log('CronService: BullMQ disabled on local tier — no jobs will be scheduled');
+      return;
+    }
+
     const summarizationSchedule = process.env['SUMMARIZATION_CRON'] ?? '0 */6 * * *'; // every 6 hours
     const tierManagementSchedule = process.env['TIER_MANAGEMENT_CRON'] ?? '0 3 * * *'; // daily at 3am
 
@@ -39,7 +45,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const summarizationWorker = this.queueService.registerWorker(QUEUE_SUMMARIZATION, async () => {
       await this.summarization.runSummarization();
     });
-    this.registeredWorkers.push(summarizationWorker);
+    if (summarizationWorker) this.registeredWorkers.push(summarizationWorker);
 
     // M6-005: Tier management repeatable job
     await this.queueService.addRepeatableJob(
@@ -51,7 +57,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const tierWorker = this.queueService.registerWorker(QUEUE_TIER_MANAGEMENT, async () => {
       await this.summarization.runTierManagement();
     });
-    this.registeredWorkers.push(tierWorker);
+    if (tierWorker) this.registeredWorkers.push(tierWorker);
 
     // Retire any repeatable global GC schedule created by older deployments.
     // Session cleanup is now triggered only by an authorized session lifecycle operation.

apps/gateway/src/preferences/system-override.service.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import type { MosaicConfig } from '@mosaicstack/config';
+import { SystemOverrideService } from './system-override.service.js';
+
+const localConfig = { queue: { type: 'local' } } as MosaicConfig;
+
+describe('SystemOverrideService local tier', () => {
+  it('keeps ephemeral overrides isolated by tenant and user scope', async () => {
+    const service = new SystemOverrideService(localConfig);
+    const firstScope = { tenantId: 'tenant-a', userId: 'user-a' };
+    const secondScope = { tenantId: 'tenant-b', userId: 'user-b' };
+
+    await service.set('shared-session', 'first override', firstScope);
+    await service.set('shared-session', 'second override', secondScope);
+
+    await expect(service.get('shared-session', firstScope)).resolves.toBe('first override');
+    await expect(service.get('shared-session', secondScope)).resolves.toBe('second override');
+
+    await service.clear('shared-session', firstScope);
+    await expect(service.get('shared-session', firstScope)).resolves.toBeNull();
+    await expect(service.get('shared-session', secondScope)).resolves.toBe('second override');
+  });
+});

apps/gateway/src/preferences/system-override.service.ts

@@ -1,6 +1,8 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable, Logger, Optional, type OnApplicationShutdown } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
+import type { MosaicConfig } from '@mosaicstack/config';
 import type { ActorTenantScope } from '../auth/session-scope.js';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 
 const scopedSessionId = (sessionId: string, scope: ActorTenantScope) =>
   `${scope.tenantId}:${scope.userId}:${sessionId}`;
@@ -15,16 +17,45 @@ interface OverrideFragment {
   addedAt: number;
 }
 
-@Injectable()
-export class SystemOverrideService {
-  private readonly logger = new Logger(SystemOverrideService.name);
-  private readonly handle: QueueHandle;
+interface LocalOverrideEntry {
+  condensed: string;
+  fragments: OverrideFragment[];
+}
 
-  constructor() {
-    this.handle = createQueue();
+@Injectable()
+export class SystemOverrideService implements OnApplicationShutdown {
+  private readonly logger = new Logger(SystemOverrideService.name);
+  private readonly handle: QueueHandle | null;
+  /** Local-tier fallback, keyed by the same tenant/user/session scope as Redis. */
+  private readonly localStore = new Map<string, LocalOverrideEntry>();
+
+  constructor(
+    @Optional()
+    @Inject(MOSAIC_CONFIG)
+    private readonly mosaicConfig: MosaicConfig | null,
+  ) {
+    this.handle = this.mosaicConfig?.queue?.type === 'local' ? null : createQueue();
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    await this.handle?.close().catch(() => {});
   }
 
   async set(sessionId: string, override: string, scope: ActorTenantScope): Promise<void> {
+    if (!this.handle) {
+      const key = scopedSessionId(sessionId, scope);
+      const entry = this.localStore.get(key) ?? { condensed: '', fragments: [] };
+      entry.fragments.push({ text: override, addedAt: Date.now() });
+      entry.condensed = await this.condenseOverrides(
+        entry.fragments.map((fragment) => fragment.text),
+      );
+      this.localStore.set(key, entry);
+      this.logger.debug(
+        `Set system override for session ${sessionId} (local, ${entry.fragments.length} fragment(s))`,
+      );
+      return;
+    }
+
     // Load existing fragments
     const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope));
     const fragments: OverrideFragment[] = existing
@@ -54,10 +85,14 @@ export class SystemOverrideService {
   }
 
   async get(sessionId: string, scope: ActorTenantScope): Promise<string | null> {
+    if (!this.handle) {
+      return this.localStore.get(scopedSessionId(sessionId, scope))?.condensed ?? null;
+    }
     return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId, scope));
   }
 
   async renew(sessionId: string, scope: ActorTenantScope): Promise<void> {
+    if (!this.handle) return;
     const pipeline = this.handle.redis.pipeline();
     pipeline.expire(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
     pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
@@ -65,6 +100,11 @@ export class SystemOverrideService {
   }
 
   async clear(sessionId: string, scope: ActorTenantScope): Promise<void> {
+    if (!this.handle) {
+      this.localStore.delete(scopedSessionId(sessionId, scope));
+      this.logger.debug(`Cleared system override for session ${sessionId} (local)`);
+      return;
+    }
     await this.handle.redis.del(
       SESSION_SYSTEM_KEY(sessionId, scope),
       SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),

apps/gateway/src/queue/queue.service.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { MosaicConfig } from '@mosaicstack/config';
+import { QueueService } from './queue.service.js';
+
+const localConfig = {
+  queue: { type: 'local' },
+} as MosaicConfig;
+
+describe('QueueService local tier', () => {
+  it('disables BullMQ and treats queue operations as local no-ops', async () => {
+    const service = new QueueService(null, localConfig);
+
+    expect(service.isEnabled()).toBe(false);
+    expect(service.getQueue('mosaic-test')).toBeNull();
+    expect(service.registerWorker('mosaic-test', vi.fn())).toBeNull();
+
+    await expect(
+      service.addRepeatableJob('mosaic-test', 'local-noop', {}, '* * * * *'),
+    ).resolves.toBeUndefined();
+    await expect(service.removeRepeatableJobs('mosaic-test', 'local-noop')).resolves.toBe(0);
+    await expect(service.getHealthStatus()).resolves.toEqual({ queues: {}, healthy: true });
+    await expect(service.listJobs()).resolves.toEqual([]);
+    await expect(service.retryJob('mosaic-test__1')).resolves.toEqual({
+      ok: false,
+      message: 'BullMQ is disabled on local tier.',
+    });
+    await expect(service.pauseQueue('mosaic-test')).resolves.toEqual({
+      ok: false,
+      message: 'BullMQ is disabled on local tier.',
+    });
+    await expect(service.resumeQueue('mosaic-test')).resolves.toEqual({
+      ok: false,
+      message: 'BullMQ is disabled on local tier.',
+    });
+  });
+});

apps/gateway/src/queue/queue.service.ts

@@ -8,7 +8,9 @@ import {
 } from '@nestjs/common';
 import { Queue, Worker, type Job, type ConnectionOptions } from 'bullmq';
 import type { LogService } from '@mosaicstack/log';
+import type { MosaicConfig } from '@mosaicstack/config';
 import { LOG_SERVICE } from '../log/log.tokens.js';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 import type { JobDto, JobStatus } from './queue-admin.dto.js';
 
 // ---------------------------------------------------------------------------
@@ -108,21 +110,42 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   private readonly connection: ConnectionOptions;
   private readonly queues = new Map<string, Queue<MosaicJobData>>();
   private readonly workers = new Map<string, Worker<MosaicJobData>>();
+  /** False on Local tier — BullMQ/Redis operations become no-ops. */
+  private readonly enabled: boolean;
 
   constructor(
     @Optional()
     @Inject(LOG_SERVICE)
     private readonly logService: LogService | null,
+    @Optional()
+    @Inject(MOSAIC_CONFIG)
+    private readonly mosaicConfig: MosaicConfig | null,
   ) {
-    this.connection = getConnection();
+    this.enabled = this.mosaicConfig?.queue?.type !== 'local';
+    this.connection = this.enabled
+      ? getConnection()
+      : ({ host: '127.0.0.1', port: 6380 } as ConnectionOptions);
+  }
+
+  /** Returns true when BullMQ/Redis is active (Standalone and Federated tiers). */
+  isEnabled(): boolean {
+    return this.enabled;
   }
 
   onModuleInit(): void {
-    this.logger.log('QueueService initialised (BullMQ)');
+    if (this.enabled) {
+      this.logger.log('QueueService initialised (BullMQ)');
+    } else {
+      this.logger.log(
+        'QueueService: BullMQ disabled for local tier — no Redis connections will be opened',
+      );
+    }
   }
 
   async onModuleDestroy(): Promise<void> {
-    await this.closeAll();
+    if (this.enabled) {
+      await this.closeAll();
+    }
   }
 
   // -------------------------------------------------------------------------
@@ -131,8 +154,10 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
 
   /**
    * Get or create a BullMQ Queue for the given queue name.
+   * Returns null on Local tier where BullMQ is disabled.
    */
-  getQueue<T extends MosaicJobData = MosaicJobData>(name: string): Queue<T> {
+  getQueue<T extends MosaicJobData = MosaicJobData>(name: string): Queue<T> | null {
+    if (!this.enabled) return null;
     let queue = this.queues.get(name) as Queue<T> | undefined;
     if (!queue) {
       queue = new Queue<T>(name, { connection: this.connection });
@@ -144,6 +169,7 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   /**
    * Add a BullMQ repeatable job (cron-style).
    * Uses `jobId` as a deterministic key so duplicate registrations are idempotent.
+   * No-op on Local tier.
    */
   async addRepeatableJob<T extends MosaicJobData>(
     queueName: string,
@@ -151,7 +177,13 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
     data: T,
     cronExpression: string,
   ): Promise<void> {
-    const queue = this.getQueue<T>(queueName);
+    if (!this.enabled) {
+      this.logger.debug(
+        `Skipping repeatable job "${jobName}" on "${queueName}" (local tier — BullMQ disabled)`,
+      );
+      return;
+    }
+    const queue = this.getQueue<T>(queueName)!;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     await (queue as Queue<any>).add(jobName, data, {
       repeat: { pattern: cronExpression },
@@ -167,7 +199,14 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * safe retirement of previously registered system-wide jobs.
    */
   async removeRepeatableJobs(queueName: string, jobName: string): Promise<number> {
+    if (!this.enabled) {
+      this.logger.debug(
+        `Skipping repeatable-job removal for "${jobName}" on "${queueName}" (local tier — BullMQ disabled)`,
+      );
+      return 0;
+    }
     const queue = this.getQueue(queueName);
+    if (!queue) return 0;
     const jobs = await queue.getRepeatableJobs();
     const matchingJobs = jobs.filter((job) => job.name === jobName);
     await Promise.all(matchingJobs.map((job) => queue.removeRepeatableByKey(job.key)));
@@ -182,8 +221,18 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   /**
    * Register a Worker for the given queue name with error handling and
    * exponential backoff.
+   * Returns null on Local tier where BullMQ is disabled.
    */
-  registerWorker<T extends MosaicJobData>(queueName: string, handler: JobHandler<T>): Worker<T> {
+  registerWorker<T extends MosaicJobData>(
+    queueName: string,
+    handler: JobHandler<T>,
+  ): Worker<T> | null {
+    if (!this.enabled) {
+      this.logger.debug(
+        `Skipping worker registration for "${queueName}" (local tier — BullMQ disabled)`,
+      );
+      return null;
+    }
     const worker = new Worker<T>(
       queueName,
       async (job) => {
@@ -240,8 +289,12 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
 
   /**
    * Return queue health statistics for all managed queues.
+   * Returns an empty healthy result on Local tier.
    */
   async getHealthStatus(): Promise<QueueHealthStatus> {
+    if (!this.enabled) {
+      return { queues: {}, healthy: true };
+    }
     const queues: QueueHealthStatus['queues'] = {};
     let healthy = true;
 
@@ -272,8 +325,10 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   /**
    * List jobs across all managed queues, optionally filtered by status.
    * BullMQ jobs are fetched by state type from each queue.
+   * Returns empty array on Local tier.
    */
   async listJobs(status?: JobStatus): Promise<JobDto[]> {
+    if (!this.enabled) return [];
     const jobs: JobDto[] = [];
     const states: JobStatus[] = status
       ? [status]
@@ -300,8 +355,10 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Retry a specific failed job by its BullMQ job ID (format: "queueName:id").
    * The caller passes "<queueName>__<jobId>" as the composite ID because BullMQ
    * job IDs are not globally unique — they are scoped to their queue.
+   * Returns an error on Local tier.
    */
   async retryJob(compositeId: string): Promise<{ ok: boolean; message: string }> {
+    if (!this.enabled) return { ok: false, message: 'BullMQ is disabled on local tier.' };
     const sep = compositeId.lastIndexOf('__');
     if (sep === -1) {
       return { ok: false, message: 'Invalid job id format. Expected "<queue>__<jobId>".' };
@@ -333,6 +390,7 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Pause a queue by name.
    */
   async pauseQueue(name: string): Promise<{ ok: boolean; message: string }> {
+    if (!this.enabled) return { ok: false, message: 'BullMQ is disabled on local tier.' };
     const queue = this.queues.get(name);
     if (!queue) return { ok: false, message: `Queue "${name}" not found.` };
     await queue.pause();
@@ -344,6 +402,7 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Resume a paused queue by name.
    */
   async resumeQueue(name: string): Promise<{ ok: boolean; message: string }> {
+    if (!this.enabled) return { ok: false, message: 'BullMQ is disabled on local tier.' };
     const queue = this.queues.get(name);
     if (!queue) return { ok: false, message: `Queue "${name}" not found.` };
     await queue.resume();

apps/gateway/src/workspace/workspace.controller.spec.ts

@@ -0,0 +1,104 @@
+import 'reflect-metadata';
+import {
+  type CanActivate,
+  type ExecutionContext,
+  type INestApplication,
+  ValidationPipe,
+} from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { ProjectBootstrapService } from './project-bootstrap.service.js';
+import { WorkspaceController } from './workspace.controller.js';
+
+const bootstrapMock = vi.fn(() =>
+  Promise.resolve({
+    projectId: 'project-1',
+    workspacePath: '/opt/mosaic/.workspaces/users/user-1/project-1',
+  }),
+);
+
+const authGuard: CanActivate = {
+  canActivate(context: ExecutionContext): boolean {
+    const requestContext = context.switchToHttp().getRequest<{ user?: { id: string } }>();
+    requestContext.user = { id: 'user-1' };
+    return true;
+  },
+};
+
+describe('POST /api/workspaces repoUrl validation', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [WorkspaceController],
+      providers: [
+        {
+          provide: ProjectBootstrapService,
+          useValue: { bootstrap: bootstrapMock },
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(authGuard)
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    app.useGlobalPipes(
+      new ValidationPipe({
+        whitelist: true,
+        forbidNonWhitelisted: true,
+        transform: true,
+      }),
+    );
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  beforeEach(() => {
+    bootstrapMock.mockClear();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it.each([
+    ['a leading-dash value', '--upload-pack=sh -c id'],
+    ['an ext remote helper', 'ext::sh -c id'],
+    ['a file URL', 'file:///tmp/repository'],
+    ['an unparseable value', 'not a url'],
+    ['an SSH shorthand', '[email protected]:acme/repository.git'],
+    ['a scheme without //', 'https:example.com/acme/repository.git'],
+    ['a hostless git URL', 'git:///tmp/repository'],
+  ])('returns 400 for %s', async (_description, repoUrl) => {
+    const response = await request(app.getHttpServer())
+      .post('/api/workspaces')
+      .send({ name: 'Example', repoUrl })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(400);
+    expect(bootstrapMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['a plain HTTPS repository URL', 'https://example.com/acme/repository.git'],
+    ['a git protocol repository URL', 'git://example.com/acme/repository.git'],
+  ])('accepts %s', async (_description, repoUrl) => {
+    const response = await request(app.getHttpServer())
+      .post('/api/workspaces')
+      .send({ name: 'Example', repoUrl })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(201);
+    expect(bootstrapMock).toHaveBeenCalledWith({
+      name: 'Example',
+      description: undefined,
+      userId: 'user-1',
+      teamId: undefined,
+      repoUrl,
+    });
+  });
+});

apps/gateway/src/workspace/workspace.controller.ts

@@ -1,7 +1,11 @@
 import { Body, Controller, Post, UseGuards } from '@nestjs/common';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
-import { ProjectBootstrapService } from './project-bootstrap.service.js';
+import {
+  ProjectBootstrapService,
+  type BootstrapProjectResult,
+} from './project-bootstrap.service.js';
+import { CreateWorkspaceDto } from './workspace.dto.js';
 
 @Controller('api/workspaces')
 @UseGuards(AuthGuard)
@@ -11,20 +15,14 @@ export class WorkspaceController {
   @Post()
   async create(
     @CurrentUser() user: { id: string },
-    @Body()
-    body: {
-      name: string;
-      description?: string;
-      teamId?: string;
-      repoUrl?: string;
-    },
-  ) {
+    @Body() dto: CreateWorkspaceDto,
+  ): Promise<BootstrapProjectResult> {
     return this.bootstrap.bootstrap({
-      name: body.name,
-      description: body.description,
+      name: dto.name,
+      description: dto.description,
       userId: user.id,
-      teamId: body.teamId,
-      repoUrl: body.repoUrl,
+      teamId: dto.teamId,
+      repoUrl: dto.repoUrl,
     });
   }
 }

apps/gateway/src/workspace/workspace.dto.ts

@@ -0,0 +1,33 @@
+import { IsOptional, IsString, IsUrl, Matches, MaxLength } from 'class-validator';
+
+export class CreateWorkspaceDto {
+  @IsString()
+  @MaxLength(255)
+  name!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
+  description?: string;
+
+  @IsOptional()
+  @IsString()
+  teamId?: string;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^(?:https|git):\/\//i, {
+    message: 'repoUrl must be a valid https:// or git:// URL',
+  })
+  @IsUrl(
+    {
+      protocols: ['https', 'git'],
+      require_host: true,
+      require_protocol: true,
+      require_tld: false,
+      require_valid_protocol: true,
+    },
+    { message: 'repoUrl must be a valid https:// or git:// URL' },
+  )
+  repoUrl?: string;
+}

apps/gateway/src/workspace/workspace.service.spec.ts

@@ -1,11 +1,33 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { WorkspaceService } from './workspace.service.js';
+import { BadRequestException } from '@nestjs/common';
+import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { WorkspaceService } from './workspace.service.js';
+
+type ExecFileMock = (
+  command: string,
+  args: readonly string[],
+  options: { cwd: string },
+  callback: (error: Error | null, stdout: string, stderr: string) => void,
+) => void;
+
+const { execFileMock } = vi.hoisted(() => ({
+  execFileMock: vi.fn<ExecFileMock>(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: execFileMock,
+}));
 
 describe('WorkspaceService', () => {
   let service: WorkspaceService;
 
   beforeEach(() => {
+    execFileMock.mockReset();
+    execFileMock.mockImplementation((_command, _args, _options, callback) => {
+      callback(null, '', '');
+    });
     service = new WorkspaceService();
   });
 
@@ -76,4 +98,69 @@ describe('WorkspaceService', () => {
       }
     });
   });
+
+  describe('create', () => {
+    const project = {
+      id: 'project-1',
+      ownerType: 'user',
+      userId: 'user-1',
+      teamId: null,
+    } as const;
+
+    let originalRoot: string | undefined;
+    let temporaryRoot: string;
+
+    beforeEach(async () => {
+      originalRoot = process.env['MOSAIC_ROOT'];
+      temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'mosaic-workspace-'));
+      process.env['MOSAIC_ROOT'] = temporaryRoot;
+      service = new WorkspaceService();
+    });
+
+    afterEach(async () => {
+      if (originalRoot === undefined) {
+        delete process.env['MOSAIC_ROOT'];
+      } else {
+        process.env['MOSAIC_ROOT'] = originalRoot;
+      }
+      await fs.rm(temporaryRoot, { recursive: true, force: true });
+    });
+
+    it.each([
+      ['a leading-dash URL', '--upload-pack=sh -c id'],
+      ['an ext remote helper', 'ext::sh -c id'],
+      ['a file URL', 'file:///tmp/repository'],
+      ['an unparseable value', 'not a url'],
+      ['an SSH shorthand', '[email protected]:acme/repository.git'],
+      ['a scheme without //', 'https:example.com/acme/repository.git'],
+      ['a hostless git URL', 'git:///tmp/repository'],
+    ])('rejects %s before invoking git', async (_description, repoUrl) => {
+      await expect(service.create(project, repoUrl)).rejects.toBeInstanceOf(BadRequestException);
+      expect(execFileMock).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['an HTTPS URL', 'https://example.com/acme/repository.git'],
+      ['a git protocol URL', 'git://example.com/acme/repository.git'],
+    ])('accepts %s and invokes hardened git clone arguments', async (_description, repoUrl) => {
+      const workspacePath = await service.create(project, repoUrl);
+
+      expect(execFileMock).toHaveBeenCalledOnce();
+      expect(execFileMock).toHaveBeenCalledWith(
+        'git',
+        [
+          '-c',
+          'protocol.ext.allow=never',
+          '-c',
+          'protocol.file.allow=never',
+          'clone',
+          '--',
+          repoUrl,
+          '.',
+        ],
+        { cwd: workspacePath },
+        expect.any(Function),
+      );
+    });
+  });
 });

apps/gateway/src/workspace/workspace.service.ts

@@ -1,10 +1,30 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
+const allowedRepositoryProtocols = new Set(['https:', 'git:']);
+const repositoryUrlPrefixPattern = /^(?:https|git):\/\//i;
+const repositoryUrlError = 'repoUrl must be a valid https:// or git:// URL';
+
+function assertAllowedRepositoryUrl(repoUrl: string): void {
+  if (repoUrl.startsWith('-') || !repositoryUrlPrefixPattern.test(repoUrl)) {
+    throw new BadRequestException(repositoryUrlError);
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(repoUrl);
+  } catch {
+    throw new BadRequestException(repositoryUrlError);
+  }
+
+  if (!allowedRepositoryProtocols.has(parsedUrl.protocol) || parsedUrl.hostname.length === 0) {
+    throw new BadRequestException(repositoryUrlError);
+  }
+}
 
 export interface WorkspaceProject {
   id: string;
@@ -39,14 +59,32 @@ export class WorkspaceService {
    * If repoUrl is provided, clone instead of init.
    */
   async create(project: WorkspaceProject, repoUrl?: string): Promise<string> {
+    if (repoUrl !== undefined) {
+      assertAllowedRepositoryUrl(repoUrl);
+    }
+
     const workspacePath = this.resolvePath(project);
 
     // Create directory
     await fs.mkdir(workspacePath, { recursive: true });
 
-    if (repoUrl) {
-      // Clone existing repo
-      await execFileAsync('git', ['clone', repoUrl, '.'], { cwd: workspacePath });
+    if (repoUrl !== undefined) {
+      // Clone existing repo. Defense in depth keeps dangerous local helpers
+      // disabled and terminates option parsing before positional arguments.
+      await execFileAsync(
+        'git',
+        [
+          '-c',
+          'protocol.ext.allow=never',
+          '-c',
+          'protocol.file.allow=never',
+          'clone',
+          '--',
+          repoUrl,
+          '.',
+        ],
+        { cwd: workspacePath },
+      );
       this.logger.log(`Cloned ${repoUrl} into workspace ${workspacePath}`);
     } else {
       // Init new git repo

apps/web/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Mosaic</title>
+    <meta name="description" content="Mosaic Stack Dashboard" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Fira+Code:wght@400;500&display=swap"
+    />
+    <script>
+      // set data-theme before first paint so the stored theme never flashes
+      (function () {
+        try {
+          var theme = window.localStorage.getItem('mosaic-theme') || 'dark';
+          document.documentElement.setAttribute('data-theme', theme === 'light' ? 'light' : 'dark');
+        } catch (error) {
+          document.documentElement.setAttribute('data-theme', 'dark');
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/web/package.json

@@ -3,8 +3,10 @@
   "version": "0.0.2",
   "private": true,
   "scripts": {
-    "build": "next build",
+    "build": "node ../../scripts/build-web.mjs",
+    "build:vite": "vite build",
     "dev": "next dev",
+    "dev:vite": "vite",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
@@ -19,6 +21,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.18.2",
     "socket.io-client": "^4.8.0",
     "tailwind-merge": "^3.5.0"
   },
@@ -28,9 +31,11 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.5",
     "jsdom": "^29.0.0",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.8.0",
-    "vitest": "^2.0.0"
+    "vite": "^8.2.1",
+    "vitest": "^3.2.7"
   }
 }

apps/web/src/app/auth/provider/[provider]/page.tsx

@@ -3,41 +3,56 @@
 import Link from 'next/link';
 import { useEffect, useState } from 'react';
 import { useParams, useSearchParams } from 'next/navigation';
+import { api } from '@/lib/api';
+import { resolveAuthCallbackURL } from '@/lib/auth-redirect';
 import { signIn } from '@/lib/auth-client';
-import { getSsoProvider } from '@/lib/sso-providers';
+import type { SsoProviderDiscovery } from '@/lib/sso';
 
 export default function AuthProviderRedirectPage(): React.ReactElement {
   const params = useParams<{ provider: string }>();
   const searchParams = useSearchParams();
   const providerId = typeof params.provider === 'string' ? params.provider : '';
-  const provider = getSsoProvider(providerId);
-  const callbackURL = searchParams.get('callbackURL') ?? '/chat';
+  const requestedCallbackURL = searchParams.get('callbackURL');
+  const [providerName, setProviderName] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
-    const currentProvider = provider;
-
-    if (!currentProvider) {
-      setError('Unknown SSO provider.');
-      return;
-    }
-
-    if (!currentProvider.enabled) {
-      setError(`${currentProvider.buttonLabel} is not enabled in this deployment.`);
-      return;
-    }
-
-    const activeProvider = currentProvider;
     let cancelled = false;
 
     async function redirectToProvider(): Promise<void> {
-      const result = await signIn.oauth2({
-        providerId: activeProvider.id,
-        callbackURL,
-      });
+      try {
+        const callbackURL = resolveAuthCallbackURL(requestedCallbackURL, window.location.origin);
+        const providers = await api<SsoProviderDiscovery[]>('/api/sso/providers');
+        if (cancelled) return;
 
-      if (!cancelled && result?.error) {
-        setError(result.error.message ?? `${activeProvider.buttonLabel} sign in failed.`);
+        const provider = providers.find((candidate) => candidate.id === providerId);
+        if (!provider) {
+          setError('Unknown SSO provider.');
+          return;
+        }
+
+        setProviderName(provider.name);
+        if (!provider.configured) {
+          setError(`${provider.name} is not enabled in this deployment.`);
+          return;
+        }
+        if (provider.loginMode !== 'oidc') {
+          setError(`${provider.name} is not available for OIDC sign in.`);
+          return;
+        }
+
+        const result = await signIn.oauth2({
+          providerId: provider.id,
+          callbackURL,
+        });
+
+        if (!cancelled && result?.error) {
+          setError(result.error.message ?? `${provider.name} sign in failed.`);
+        }
+      } catch (caught: unknown) {
+        if (!cancelled) {
+          setError(caught instanceof Error ? caught.message : 'Unable to start single sign-on.');
+        }
       }
     }
 
@@ -46,19 +61,22 @@ export default function AuthProviderRedirectPage(): React.ReactElement {
     return () => {
       cancelled = true;
     };
-  }, [callbackURL, provider]);
+  }, [providerId, requestedCallbackURL]);
 
   return (
     <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
       <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
       <p className="mt-2 text-sm text-text-secondary">
-        {provider
-          ? `Redirecting you to ${provider.buttonLabel.replace('Continue with ', '')}...`
+        {providerName
+          ? `Redirecting you to ${providerName}...`
           : 'Preparing your sign-in request...'}
       </p>
 
       {error ? (
-        <div className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error">
+        <div
+          role="alert"
+          className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
           <p>{error}</p>
           <Link
             href="/login"

apps/web/src/lib/api.spec.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { api } from './api';
+
+describe('api', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('fetches the supplied relative path with credentials and a JSON body', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(
+      api<{ ok: boolean }>('/api/projects', {
+        method: 'POST',
+        body: { name: 'Mosaic' },
+      }),
+    ).resolves.toEqual({ ok: true });
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/projects',
+      expect.objectContaining({
+        method: 'POST',
+        credentials: 'include',
+        body: JSON.stringify({ name: 'Mosaic' }),
+        headers: expect.objectContaining({
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        }),
+      }),
+    );
+  });
+
+  it('throws the gateway JSON error with its statusCode', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ statusCode: 403, message: 'Forbidden' }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(api('/api/admin/users')).rejects.toMatchObject({
+      name: 'Error',
+      message: 'Forbidden',
+      statusCode: 403,
+    });
+  });
+});

apps/web/src/lib/api.ts

@@ -1,5 +1,3 @@
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
-
 export interface ApiRequestInit extends Omit<RequestInit, 'body'> {
   body?: unknown;
 }
@@ -25,7 +23,7 @@ export async function api<T>(path: string, init?: ApiRequestInit): Promise<T> {
     headers['Content-Type'] = 'application/json';
   }
 
-  const res = await fetch(`${GATEWAY_URL}${path}`, {
+  const res = await fetch(path, {
     credentials: 'include',
     ...rest,
     headers,

apps/web/src/lib/auth-client.spec.ts

@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+describe('auth client origin contract', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('uses the same-origin BetterAuth mount at /api/auth', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ session: null, user: null }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { authClient } = await import('./auth-client');
+    await authClient.getSession();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const firstCall = fetchMock.mock.calls.at(0);
+    expect(firstCall).toBeDefined();
+    const requestURL = new URL(String(firstCall?.[0]), window.location.origin);
+    expect(requestURL.origin).toBe(window.location.origin);
+    expect(requestURL.pathname).toBe('/api/auth/get-session');
+  });
+});

apps/web/src/lib/auth-client.ts

@@ -1,8 +1,9 @@
 import { createAuthClient } from 'better-auth/react';
 import { adminClient, genericOAuthClient } from 'better-auth/client/plugins';
 
+// The gateway and BetterAuth client both use /api/auth. Omitting baseURL keeps
+// every browser request on the current origin in development and production.
 export const authClient = createAuthClient({
-  baseURL: process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242',
   plugins: [adminClient(), genericOAuthClient()],
 });
 

apps/web/src/lib/auth-redirect.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { resolveAuthCallbackURL } from './auth-redirect';
+
+const CURRENT_ORIGIN = 'https://mosaic.example';
+
+describe('resolveAuthCallbackURL', () => {
+  it('preserves a canonical same-origin path with search and hash', () => {
+    expect(resolveAuthCallbackURL('/projects?view=active#current', CURRENT_ORIGIN)).toBe(
+      '/projects?view=active#current',
+    );
+  });
+
+  it.each([
+    null,
+    'chat',
+    '//evil.example',
+    '/..//evil.com',
+    '/..//evil.com/x',
+    '/./..//evil.com',
+    '/../..//evil.com',
+    '/foo/..//evil.com',
+    '/\\evil.example',
+    '/\n//evil.example',
+    '/\r//evil.example',
+    '/\t//evil.example',
+    'https://evil.example/phish',
+  ])('falls back to chat for an unsafe callback target %#', (candidate) => {
+    expect(resolveAuthCallbackURL(candidate, CURRENT_ORIGIN)).toBe('/chat');
+  });
+});

apps/web/src/lib/auth-redirect.ts

@@ -0,0 +1,23 @@
+const DEFAULT_AUTH_CALLBACK_URL = '/chat';
+
+/**
+ * Return a canonical same-origin path for post-auth navigation.
+ *
+ * Parsing before comparing origins rejects protocol-relative URLs, backslash
+ * variants, and control characters that the WHATWG parser normalizes away.
+ */
+export function resolveAuthCallbackURL(candidate: string | null, currentOrigin: string): string {
+  if (!candidate?.startsWith('/')) return DEFAULT_AUTH_CALLBACK_URL;
+
+  try {
+    const expectedOrigin = new URL(currentOrigin).origin;
+    const resolved = new URL(candidate, expectedOrigin);
+    if (resolved.origin !== expectedOrigin || resolved.pathname.startsWith('//')) {
+      return DEFAULT_AUTH_CALLBACK_URL;
+    }
+
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+  } catch {
+    return DEFAULT_AUTH_CALLBACK_URL;
+  }
+}

apps/web/src/lib/socket.spec.ts

@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { ioMock } = vi.hoisted(() => ({
+  ioMock: vi.fn(),
+}));
+
+vi.mock('socket.io-client', () => ({
+  io: ioMock,
+}));
+
+import { destroySocket, getSocket } from './socket';
+
+describe('chat socket', () => {
+  let disconnectHandler: (() => void) | undefined;
+
+  beforeEach(() => {
+    disconnectHandler = undefined;
+    ioMock.mockReset();
+
+    const mockSocket = {
+      on: vi.fn((event: string, handler: () => void) => {
+        if (event === 'disconnect') disconnectHandler = handler;
+        return mockSocket;
+      }),
+      offAny: vi.fn(() => mockSocket),
+      disconnect: vi.fn(() => mockSocket),
+    };
+
+    ioMock.mockReturnValue(mockSocket);
+  });
+
+  afterEach(() => {
+    destroySocket();
+  });
+
+  it('creates one same-origin /chat namespace socket until it disconnects', () => {
+    const first = getSocket();
+    const second = getSocket();
+
+    expect(first).toBe(second);
+    expect(ioMock).toHaveBeenCalledOnce();
+    expect(ioMock).toHaveBeenCalledWith('/chat', {
+      withCredentials: true,
+      autoConnect: false,
+      transports: ['websocket', 'polling'],
+    });
+
+    disconnectHandler?.();
+    getSocket();
+    expect(ioMock).toHaveBeenCalledTimes(2);
+  });
+});

apps/web/src/lib/socket.ts

@@ -1,12 +1,10 @@
 import { io, type Socket } from 'socket.io-client';
 
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
-
 let socket: Socket | null = null;
 
 export function getSocket(): Socket {
   if (!socket) {
-    socket = io(`${GATEWAY_URL}/chat`, {
+    socket = io('/chat', {
       withCredentials: true,
       autoConnect: false,
       transports: ['websocket', 'polling'],

apps/web/src/lib/sso-providers.test.ts

@@ -1,48 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { getEnabledSsoProviders, getSsoProvider } from './sso-providers';
-
-describe('sso-providers', () => {
-  afterEach(() => {
-    vi.unstubAllEnvs();
-  });
-
-  it('returns the enabled providers in login button order', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'true');
-
-    expect(getEnabledSsoProviders()).toEqual([
-      {
-        id: 'workos',
-        buttonLabel: 'Continue with WorkOS',
-        description: 'Enterprise SSO via WorkOS',
-        enabled: true,
-        href: '/auth/provider/workos',
-      },
-      {
-        id: 'keycloak',
-        buttonLabel: 'Continue with Keycloak',
-        description: 'Enterprise SSO via Keycloak',
-        enabled: true,
-        href: '/auth/provider/keycloak',
-      },
-    ]);
-  });
-
-  it('marks disabled providers without exposing them in the enabled list', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'false');
-
-    expect(getEnabledSsoProviders().map((provider) => provider.id)).toEqual(['workos']);
-    expect(getSsoProvider('keycloak')).toEqual({
-      id: 'keycloak',
-      buttonLabel: 'Continue with Keycloak',
-      description: 'Enterprise SSO via Keycloak',
-      enabled: false,
-      href: '/auth/provider/keycloak',
-    });
-  });
-
-  it('returns null for unknown providers', () => {
-    expect(getSsoProvider('authentik')).toBeNull();
-  });
-});

apps/web/src/lib/sso-providers.ts

@@ -1,53 +0,0 @@
-export type SsoProviderId = 'workos' | 'keycloak';
-
-export interface SsoProvider {
-  id: SsoProviderId;
-  buttonLabel: string;
-  description: string;
-  enabled: boolean;
-  href: string;
-}
-
-const PROVIDER_METADATA: Record<SsoProviderId, Omit<SsoProvider, 'enabled' | 'href'>> = {
-  workos: {
-    id: 'workos',
-    buttonLabel: 'Continue with WorkOS',
-    description: 'Enterprise SSO via WorkOS',
-  },
-  keycloak: {
-    id: 'keycloak',
-    buttonLabel: 'Continue with Keycloak',
-    description: 'Enterprise SSO via Keycloak',
-  },
-};
-
-export function getEnabledSsoProviders(): SsoProvider[] {
-  return (Object.keys(PROVIDER_METADATA) as SsoProviderId[])
-    .map((providerId) => getSsoProvider(providerId))
-    .filter((provider): provider is SsoProvider => provider?.enabled === true);
-}
-
-export function getSsoProvider(providerId: string): SsoProvider | null {
-  if (!isSsoProviderId(providerId)) {
-    return null;
-  }
-
-  return {
-    ...PROVIDER_METADATA[providerId],
-    enabled: isSsoProviderEnabled(providerId),
-    href: `/auth/provider/${providerId}`,
-  };
-}
-
-function isSsoProviderId(value: string): value is SsoProviderId {
-  return value === 'workos' || value === 'keycloak';
-}
-
-function isSsoProviderEnabled(providerId: SsoProviderId): boolean {
-  switch (providerId) {
-    case 'workos':
-      return process.env['NEXT_PUBLIC_WORKOS_ENABLED'] === 'true';
-    case 'keycloak':
-      return process.env['NEXT_PUBLIC_KEYCLOAK_ENABLED'] === 'true';
-  }
-}

apps/web/src/main.tsx

@@ -0,0 +1,19 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from 'react-router-dom';
+import { ThemeProvider } from '@/providers/theme-provider';
+import { createAppRouter } from '@/routes';
+import '@/app/globals.css';
+
+const container = document.getElementById('root');
+if (!container) {
+  throw new Error('missing #root element');
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <ThemeProvider>
+      <RouterProvider router={createAppRouter()} />
+    </ThemeProvider>
+  </StrictMode>,
+);

apps/web/src/routes.tsx

@@ -0,0 +1,49 @@
+import type { ReactElement } from 'react';
+import { createBrowserRouter, Navigate, Outlet, type RouteObject } from 'react-router-dom';
+import { LoginPage } from '@/spa/pages/login';
+import { RegisterPage } from '@/spa/pages/register';
+import { SsoCallbackPage } from '@/spa/pages/sso-callback';
+import { AuthGuard, GuestGuard } from '@/spa/guards';
+import { Placeholder } from '@/spa/placeholder';
+
+function GuestLayout(): ReactElement {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-surface-bg px-4 py-8">
+      <div className="w-full max-w-md rounded-xl border border-surface-border bg-surface-card p-8 shadow-lg">
+        <Outlet />
+      </div>
+    </div>
+  );
+}
+
+export const routes: RouteObject[] = [
+  {
+    element: <GuestGuard />,
+    children: [
+      {
+        element: <GuestLayout />,
+        children: [
+          { path: '/login', element: <LoginPage /> },
+          { path: '/register', element: <RegisterPage /> },
+          { path: '/auth/provider/:provider', element: <SsoCallbackPage /> },
+        ],
+      },
+    ],
+  },
+  {
+    element: <AuthGuard />,
+    children: [
+      { path: '/', element: <Navigate to="/chat" replace /> },
+      { path: '/chat', element: <Placeholder title="Chat" /> },
+      { path: '/projects', element: <Placeholder title="Projects" /> },
+      { path: '/projects/:id', element: <Placeholder title="Project" /> },
+      { path: '/tasks', element: <Placeholder title="Tasks" /> },
+      { path: '/settings', element: <Placeholder title="Settings" /> },
+      { path: '/admin', element: <Placeholder title="Admin" /> },
+    ],
+  },
+];
+
+export function createAppRouter(): ReturnType<typeof createBrowserRouter> {
+  return createBrowserRouter(routes);
+}

apps/web/src/spa/guards.spec.tsx

@@ -0,0 +1,135 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+const { useSessionMock } = vi.hoisted(() => ({
+  useSessionMock: vi.fn(),
+}));
+
+vi.mock('@/lib/auth-client', () => ({
+  useSession: useSessionMock,
+}));
+
+import { AuthGuard, GuestGuard } from './guards';
+
+interface RenderedRouter {
+  container: HTMLDivElement;
+  router: ReturnType<typeof createMemoryRouter>;
+}
+
+const mountedRoots: Root[] = [];
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+async function renderRouter(
+  routeObjects: RouteObject[],
+  initialEntry: string,
+): Promise<RenderedRouter> {
+  const container = document.createElement('div');
+  document.body.append(container);
+  const router = createMemoryRouter(routeObjects, { initialEntries: [initialEntry] });
+  const root = createRoot(container);
+  mountedRoots.push(root);
+
+  await act(async () => {
+    root.render(<RouterProvider router={router} />);
+  });
+
+  return { container, router };
+}
+
+afterEach(async () => {
+  for (const root of mountedRoots.splice(0)) {
+    await act(async () => {
+      root.unmount();
+    });
+  }
+  document.body.replaceChildren();
+  useSessionMock.mockReset();
+});
+
+const guestRoutes: RouteObject[] = [
+  {
+    path: '/login',
+    element: <GuestGuard />,
+    children: [{ index: true, element: <p>Guest page</p> }],
+  },
+  { path: '/chat', element: <p>Chat page</p> },
+];
+
+const authenticatedRoutes: RouteObject[] = [
+  {
+    path: '/chat',
+    element: <AuthGuard />,
+    children: [{ index: true, element: <p>Private page</p> }],
+  },
+  { path: '/login', element: <p>Login page</p> },
+];
+
+describe('GuestGuard', () => {
+  it('renders the guest outlet while session lookup is pending', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: true });
+
+    const view = await renderRouter(guestRoutes, '/login');
+
+    expect(view.container.textContent).toContain('Guest page');
+    expect(view.router.state.location.pathname).toBe('/login');
+  });
+
+  it('renders the guest outlet when no session exists', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: false });
+
+    const view = await renderRouter(guestRoutes, '/login');
+
+    expect(view.container.textContent).toContain('Guest page');
+    expect(view.router.state.location.pathname).toBe('/login');
+  });
+
+  it('redirects an authenticated session to chat', async () => {
+    useSessionMock.mockReturnValue({ data: { user: { id: 'user-1' } }, isPending: false });
+
+    const view = await renderRouter(guestRoutes, '/login');
+
+    expect(view.container.textContent).toContain('Chat page');
+    expect(view.router.state.location.pathname).toBe('/chat');
+  });
+});
+
+describe('AuthGuard', () => {
+  it('renders the existing loading treatment while session lookup is pending', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: true });
+
+    const view = await renderRouter(authenticatedRoutes, '/chat');
+
+    expect(view.container.textContent).toContain('Loading...');
+    expect(view.router.state.location.pathname).toBe('/chat');
+  });
+
+  it('redirects an unauthenticated visitor to login', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: false });
+
+    const view = await renderRouter(authenticatedRoutes, '/chat');
+
+    expect(view.container.textContent).toContain('Login page');
+    expect(view.router.state.location.pathname).toBe('/login');
+  });
+
+  it('renders the authenticated outlet when a session exists', async () => {
+    useSessionMock.mockReturnValue({ data: { user: { id: 'user-1' } }, isPending: false });
+
+    const view = await renderRouter(authenticatedRoutes, '/chat');
+
+    expect(view.container.textContent).toContain('Private page');
+    expect(view.router.state.location.pathname).toBe('/chat');
+  });
+});

apps/web/src/spa/guards.tsx

@@ -0,0 +1,23 @@
+import type { ReactElement } from 'react';
+import { Navigate, Outlet } from 'react-router-dom';
+import { useSession } from '@/lib/auth-client';
+
+export function GuestGuard(): ReactElement {
+  const { data: session } = useSession();
+
+  return session ? <Navigate to="/chat" replace /> : <Outlet />;
+}
+
+export function AuthGuard(): ReactElement {
+  const { data: session, isPending } = useSession();
+
+  if (isPending) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <div className="text-sm text-text-muted">Loading...</div>
+      </div>
+    );
+  }
+
+  return session ? <Outlet /> : <Navigate to="/login" replace />;
+}

apps/web/src/spa/pages/login.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useState, type FormEvent, type ReactElement } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+import { SsoProviderButtons } from '@/components/auth/sso-provider-buttons';
+import { api } from '@/lib/api';
+import { authClient, signIn } from '@/lib/auth-client';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+
+export function LoginPage(): ReactElement {
+  const navigate = useNavigate();
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [ssoProviders, setSsoProviders] = useState<SsoProviderDiscovery[]>([]);
+  const [ssoLoadingProviderId, setSsoLoadingProviderId] = useState<
+    SsoProviderDiscovery['id'] | null
+  >(null);
+
+  useEffect(() => {
+    let active = true;
+
+    void api<SsoProviderDiscovery[]>('/api/sso/providers').then(
+      (providers) => {
+        if (active) setSsoProviders(providers.filter((provider) => provider.configured));
+      },
+      () => {
+        if (active) setSsoProviders([]);
+      },
+    );
+
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault();
+    setError(null);
+    setLoading(true);
+
+    const form = new FormData(event.currentTarget);
+    const email = String(form.get('email') ?? '');
+    const password = String(form.get('password') ?? '');
+
+    try {
+      const result = await signIn.email({ email, password });
+
+      if (result.error) {
+        setError(result.error.message ?? 'Sign in failed');
+        return;
+      }
+
+      navigate('/chat', { replace: true });
+    } catch (caught: unknown) {
+      setError(caught instanceof Error ? caught.message : 'Sign in failed');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function handleSsoSignIn(providerId: SsoProviderDiscovery['id']): Promise<void> {
+    setError(null);
+    setSsoLoadingProviderId(providerId);
+
+    try {
+      const result = await authClient.signIn.oauth2({
+        providerId,
+        callbackURL: '/chat',
+        newUserCallbackURL: '/chat',
+      });
+
+      if (result.error) {
+        setError(result.error.message ?? `Sign in with ${providerId} failed`);
+        setSsoLoadingProviderId(null);
+      }
+    } catch (caught: unknown) {
+      setError(caught instanceof Error ? caught.message : `Sign in with ${providerId} failed`);
+      setSsoLoadingProviderId(null);
+    }
+  }
+
+  return (
+    <div>
+      <h1 className="text-2xl font-semibold">Sign in</h1>
+      <p className="mt-1 text-sm text-text-secondary">Sign in to your Mosaic account</p>
+
+      {error ? (
+        <div
+          role="alert"
+          className="mt-4 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
+          {error}
+        </div>
+      ) : null}
+
+      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
+        <div>
+          <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
+            Email
+          </label>
+          <input
+            id="email"
+            name="email"
+            type="email"
+            autoComplete="email"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="[email protected]"
+          />
+        </div>
+
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium text-text-secondary">
+            Password
+          </label>
+          <input
+            id="password"
+            name="password"
+            type="password"
+            autoComplete="current-password"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="••••••••"
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
+        >
+          {loading ? 'Signing in...' : 'Sign in'}
+        </button>
+      </form>
+
+      <SsoProviderButtons
+        providers={ssoProviders}
+        loadingProviderId={ssoLoadingProviderId}
+        onOidcSignIn={(providerId) => {
+          void handleSsoSignIn(providerId);
+        }}
+      />
+
+      <p className="mt-4 text-center text-sm text-text-muted">
+        Don&apos;t have an account?{' '}
+        <Link to="/register" className="text-blue-400 hover:text-blue-300">
+          Sign up
+        </Link>
+      </p>
+    </div>
+  );
+}

apps/web/src/spa/pages/register.tsx

@@ -0,0 +1,116 @@
+import { useState, type FormEvent, type ReactElement } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+import { signUp } from '@/lib/auth-client';
+
+export function RegisterPage(): ReactElement {
+  const navigate = useNavigate();
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault();
+    setError(null);
+    setLoading(true);
+
+    const form = new FormData(event.currentTarget);
+    const name = String(form.get('name') ?? '');
+    const email = String(form.get('email') ?? '');
+    const password = String(form.get('password') ?? '');
+
+    try {
+      const result = await signUp.email({ name, email, password });
+
+      if (result.error) {
+        setError(result.error.message ?? 'Registration failed');
+        return;
+      }
+
+      navigate('/chat', { replace: true });
+    } catch (caught: unknown) {
+      setError(caught instanceof Error ? caught.message : 'Registration failed');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div>
+      <h1 className="text-2xl font-semibold">Create account</h1>
+      <p className="mt-1 text-sm text-text-secondary">Get started with Mosaic</p>
+
+      {error ? (
+        <div
+          role="alert"
+          className="mt-4 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
+          {error}
+        </div>
+      ) : null}
+
+      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
+        <div>
+          <label htmlFor="name" className="block text-sm font-medium text-text-secondary">
+            Name
+          </label>
+          <input
+            id="name"
+            name="name"
+            type="text"
+            autoComplete="name"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="Your name"
+          />
+        </div>
+
+        <div>
+          <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
+            Email
+          </label>
+          <input
+            id="email"
+            name="email"
+            type="email"
+            autoComplete="email"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="[email protected]"
+          />
+        </div>
+
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium text-text-secondary">
+            Password
+          </label>
+          <input
+            id="password"
+            name="password"
+            type="password"
+            autoComplete="new-password"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="••••••••"
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
+        >
+          {loading ? 'Creating account...' : 'Create account'}
+        </button>
+      </form>
+
+      <p className="mt-4 text-center text-sm text-text-muted">
+        Already have an account?{' '}
+        <Link to="/login" className="text-blue-400 hover:text-blue-300">
+          Sign in
+        </Link>
+      </p>
+    </div>
+  );
+}

apps/web/src/spa/pages/sso-callback.spec.tsx

@@ -0,0 +1,90 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { apiMock, oauth2Mock } = vi.hoisted(() => ({
+  apiMock: vi.fn(),
+  oauth2Mock: vi.fn(),
+}));
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}));
+
+vi.mock('@/lib/auth-client', () => ({
+  signIn: { oauth2: oauth2Mock },
+}));
+
+import { SsoCallbackPage } from './sso-callback';
+
+const mountedRoots: Root[] = [];
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+beforeEach(() => {
+  apiMock.mockResolvedValue([
+    {
+      id: 'authentik',
+      name: 'Authentik',
+      protocols: ['oidc'],
+      configured: true,
+      loginMode: 'oidc',
+      callbackPath: '/api/auth/oauth2/callback/authentik',
+      teamSync: { enabled: false, claim: null },
+      samlFallback: { configured: false, loginUrl: null },
+      warnings: [],
+    },
+  ]);
+  oauth2Mock.mockResolvedValue({ data: null, error: null });
+});
+
+afterEach(async () => {
+  for (const root of mountedRoots.splice(0)) {
+    await act(async () => {
+      root.unmount();
+    });
+  }
+  document.body.replaceChildren();
+  apiMock.mockReset();
+  oauth2Mock.mockReset();
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+describe('SsoCallbackPage', () => {
+  it('rejects a control-character callback that normalizes to an external origin', async () => {
+    const router = createMemoryRouter(
+      [
+        {
+          path: '/auth/provider/:provider',
+          element: <SsoCallbackPage />,
+        },
+      ],
+      {
+        initialEntries: ['/auth/provider/authentik?callbackURL=%2F%0A%2F%2Fevil.example'],
+      },
+    );
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+    mountedRoots.push(root);
+
+    await act(async () => {
+      root.render(<RouterProvider router={router} />);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    expect(oauth2Mock).toHaveBeenCalledWith({
+      providerId: 'authentik',
+      callbackURL: '/chat',
+    });
+  });
+});

apps/web/src/spa/pages/sso-callback.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useState, type ReactElement } from 'react';
+import { Link, useParams, useSearchParams } from 'react-router-dom';
+import { api } from '@/lib/api';
+import { resolveAuthCallbackURL } from '@/lib/auth-redirect';
+import { signIn } from '@/lib/auth-client';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+
+export function SsoCallbackPage(): ReactElement {
+  const { provider: providerId = '' } = useParams<'provider'>();
+  const [searchParams] = useSearchParams();
+  const requestedCallbackURL = searchParams.get('callbackURL');
+  const [providerName, setProviderName] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function redirectToProvider(): Promise<void> {
+      try {
+        const callbackURL = resolveAuthCallbackURL(requestedCallbackURL, window.location.origin);
+        const providers = await api<SsoProviderDiscovery[]>('/api/sso/providers');
+        if (cancelled) return;
+
+        const provider = providers.find((candidate) => candidate.id === providerId);
+        if (!provider) {
+          setError('Unknown SSO provider.');
+          return;
+        }
+
+        setProviderName(provider.name);
+        if (!provider.configured) {
+          setError(`${provider.name} is not enabled in this deployment.`);
+          return;
+        }
+        if (provider.loginMode !== 'oidc') {
+          setError(`${provider.name} is not available for OIDC sign in.`);
+          return;
+        }
+
+        const result = await signIn.oauth2({
+          providerId: provider.id,
+          callbackURL,
+        });
+
+        if (!cancelled && result?.error) {
+          setError(result.error.message ?? `${provider.name} sign in failed.`);
+        }
+      } catch (caught: unknown) {
+        if (!cancelled) {
+          setError(caught instanceof Error ? caught.message : 'Unable to start single sign-on.');
+        }
+      }
+    }
+
+    void redirectToProvider();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [providerId, requestedCallbackURL]);
+
+  return (
+    <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
+      <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
+      <p className="mt-2 text-sm text-text-secondary">
+        {providerName
+          ? `Redirecting you to ${providerName}...`
+          : 'Preparing your sign-in request...'}
+      </p>
+
+      {error ? (
+        <div
+          role="alert"
+          className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
+          <p>{error}</p>
+          <Link
+            to="/login"
+            className="mt-3 inline-block font-medium text-blue-400 hover:text-blue-300"
+          >
+            Return to login
+          </Link>
+        </div>
+      ) : (
+        <div className="mt-6 rounded-lg border border-surface-border bg-surface-elevated px-4 py-3 text-sm text-text-secondary">
+          If the redirect does not start automatically, return to the login page and try again.
+        </div>
+      )}
+    </div>
+  );
+}

apps/web/src/spa/placeholder.tsx

@@ -0,0 +1,9 @@
+import type { ReactElement } from 'react';
+
+export function Placeholder({ title }: { title: string }): ReactElement {
+  return (
+    <main className="flex min-h-screen items-center justify-center">
+      <h1 className="text-xl font-medium">{title}</h1>
+    </main>
+  );
+}

apps/web/src/spa/routes.spec.tsx

@@ -0,0 +1,58 @@
+import { isValidElement } from 'react';
+import { describe, expect, it } from 'vitest';
+import type { RouteObject } from 'react-router-dom';
+import { routes } from '@/routes';
+import { Placeholder } from '@/spa/placeholder';
+
+function collectPaths(routeObjects: RouteObject[]): string[] {
+  return routeObjects.flatMap((route) => [
+    ...(route.path ? [route.path] : []),
+    ...(route.children ? collectPaths(route.children) : []),
+  ]);
+}
+
+function findRoute(routeObjects: RouteObject[], path: string): RouteObject | undefined {
+  for (const route of routeObjects) {
+    if (route.path === path) return route;
+    const nested = route.children ? findRoute(route.children, path) : undefined;
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+describe('SPA route table', () => {
+  it('covers every v1 parity route from the Phase P RFC', () => {
+    expect(collectPaths(routes).sort()).toEqual(
+      [
+        '/',
+        '/admin',
+        '/auth/provider/:provider',
+        '/chat',
+        '/login',
+        '/projects',
+        '/projects/:id',
+        '/register',
+        '/settings',
+        '/tasks',
+      ].sort(),
+    );
+  });
+
+  it('separates guest and authenticated route groups', () => {
+    const guestPaths = collectPaths(routes.at(0)?.children ?? []);
+    const authPaths = collectPaths(routes.at(1)?.children ?? []);
+    expect(guestPaths).toContain('/login');
+    expect(guestPaths).not.toContain('/chat');
+    expect(authPaths).toContain('/chat');
+  });
+
+  it.each(['/login', '/register', '/auth/provider/:provider'])(
+    'renders a real guest page instead of the P1 placeholder at %s',
+    (path) => {
+      const element = findRoute(routes, path)?.element;
+      expect(isValidElement(element)).toBe(true);
+      if (!isValidElement(element)) throw new Error(`Missing route element for ${path}`);
+      expect(element.type).not.toBe(Placeholder);
+    },
+  );
+});

apps/web/src/test/setup.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+describe('Vitest abort-controller realm', () => {
+  it('provides a global signal accepted by Node native Request', () => {
+    const controller = new AbortController();
+    const request = new Request('https://mosaic.invalid/navigation', {
+      signal: controller.signal,
+    });
+
+    expect(request.signal).toBeInstanceOf(AbortSignal);
+    controller.abort();
+    expect(request.signal.aborted).toBe(true);
+  });
+});

apps/web/src/test/setup.ts

@@ -0,0 +1,23 @@
+import { transferableAbortController } from 'node:util';
+
+// jsdom installs realm-local abort constructors while Node's undici Request
+// remains native. React Router passes a global AbortSignal to Request, so both
+// constructors must come from Node's native realm during tests.
+const nativeController = transferableAbortController();
+const nativeAbortController = nativeController.constructor;
+const nativeAbortSignal = nativeController.signal.constructor;
+
+for (const target of [globalThis, window]) {
+  Object.defineProperties(target, {
+    AbortController: {
+      configurable: true,
+      writable: true,
+      value: nativeAbortController,
+    },
+    AbortSignal: {
+      configurable: true,
+      writable: true,
+      value: nativeAbortSignal,
+    },
+  });
+}

apps/web/vite.config.ts

@@ -0,0 +1,24 @@
+import { fileURLToPath } from 'node:url';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+// The proxy exists only in dev; in production the SPA is same-origin with the gateway
+// (served by it under Candidate A, or behind one FQDN under Candidate B) and every
+// request uses a relative path, so no origin may ever be configured here or in src/.
+const gatewayTarget = 'http://localhost:14242';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  server: {
+    port: 3100,
+    proxy: {
+      '/api': gatewayTarget,
+      '/socket.io': { target: gatewayTarget, ws: true },
+    },
+  },
+});

apps/web/vitest.config.ts

@@ -1,9 +1,21 @@
+import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  // tsconfig uses "jsx": "preserve" for Next; tests need esbuild to compile it
+  esbuild: {
+    jsx: 'automatic',
+  },
   test: {
     globals: true,
     environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    isolate: true,
     exclude: ['e2e/**', 'node_modules/**'],
   },
 });

docker/gateway.Dockerfile

@@ -10,6 +10,8 @@ COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
 COPY apps/gateway/package.json ./apps/gateway/
 COPY packages/ ./packages/
 COPY plugins/ ./plugins/
+# the root prepare script runs scripts/install-hooks.mjs on install
+COPY scripts/ ./scripts/
 RUN pnpm install --frozen-lockfile
 COPY . .
 # Build gateway and all of its workspace dependencies via turbo dependency graph
@@ -21,11 +23,22 @@ RUN pnpm --filter @mosaicstack/gateway --prod deploy --legacy /deploy
 FROM base AS runner
 WORKDIR /app
 ENV NODE_ENV=production
+# WorkspaceService shells out to git at runtime and roots workspaces at
+# $MOSAIC_ROOT/.workspaces (apps/gateway/src/workspace/workspace.service.ts);
+# mount a volume over /opt/mosaic to persist workspaces across container restarts.
+# Intentionally unpinned: Alpine's signed repository is the trust anchor; pinning
+# git was declined so routine base-image security updates remain maintainable.
+RUN apk add --no-cache git \
+  && mkdir -p /opt/mosaic/.workspaces \
+  && chown -R node:node /opt/mosaic /app
+ENV MOSAIC_ROOT=/opt/mosaic
 # Use the pnpm deploy output — resolves all deps into a flat, self-contained node_modules
-COPY --from=builder /deploy/node_modules ./node_modules
-COPY --from=builder /deploy/package.json ./package.json
+COPY --chown=node:node --from=builder /deploy/node_modules ./node_modules
+COPY --chown=node:node --from=builder /deploy/package.json ./package.json
 # dist is declared in package.json "files" so pnpm deploy copies it into /deploy;
 # copy from builder explicitly as belt-and-suspenders
-COPY --from=builder /app/apps/gateway/dist ./dist
-EXPOSE 4000
+COPY --chown=node:node --from=builder /app/apps/gateway/dist ./dist
+# gateway defaults to port 14242 (apps/gateway/src/main.ts)
+EXPOSE 14242
+USER node
 CMD ["node", "dist/main.js"]

docker/web.Dockerfile

@@ -8,9 +8,11 @@ WORKDIR /app
 COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
 COPY apps/web/package.json ./apps/web/
 COPY packages/ ./packages/
+# the root prepare script runs scripts/install-hooks.mjs on install
+COPY scripts/ ./scripts/
 RUN pnpm install --frozen-lockfile
 COPY . .
-RUN pnpm --filter @mosaic/web build
+RUN pnpm --filter @mosaicstack/web build
 
 FROM base AS runner
 WORKDIR /app

docs/PRD.md

@@ -79,6 +79,29 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 
 ---
 
+## Compaction Refresh Trust Lifecycle (M1, #827–#830)
+
+### Problem and objective
+
+Context compaction, session replacement, and same-PID runtime reloads can leave a previously VERIFIED runtime lease attached to stale directives. M1 must revoke that authority mechanically for Claude (including Claudex) and Pi without trusting caller-asserted identity or forking the external broker state machine.
+
+### Requirements
+
+1. `CR-REQ-01`: Claude `PreCompact` and `SessionStart` with matcher `compact`, plus Pi `session_before_compact` and the first post-`session_compact` `context`, SHALL independently revoke the active broker lease.
+2. `CR-REQ-02`: Runtime generation increases—including same-PID Pi reload/new/resume/fork and Claude resume/clear—SHALL monotonically replace the prior broker incarnation and inherit no VERIFIED lease.
+3. `CR-REQ-03`: A fired observer that cannot confirm broker revocation SHALL fail closed through lifecycle cancellation, a private local generation fence, and/or a runtime-local tool latch. The existing all-tools broker gate remains authoritative.
+4. `CR-REQ-04`: The lease TTL SHALL remain monotonic and capped at 300 seconds. If both observers are missed, within-TTL consequential actions remain allowed and after-TTL actions are denied. This named bounded residual stale window SHALL be documented without claiming a mutator-action bound inside the window.
+5. `CR-REQ-05`: Hook descendants SHALL use the broker-minted session and owner-only current-generation state inherited from register-before-exec. Caller-minted sessions and parallel lease state machines remain forbidden.
+
+### Acceptance criteria
+
+1. `AC-CR-01`: Real-socket tests prove each Claude observer revokes, Pi lifecycle tests prove both observer paths, and Claudex isolated settings preserve and install the mandatory hooks.
+2. `AC-CR-02`: A same-PID generation test proves the old generation is stale and the replacement generation is UNVERIFIED across reload/resume/fork-equivalent lifecycle events.
+3. `AC-CR-03`: RED-first T12b/T30 evidence explicitly reports dual-hook miss within TTL as **ALLOWED** and after TTL as **DENIED**.
+4. `AC-CR-04`: Attributable executable coverage is at least 85%, the full repository suite is green on deterministic main, and independent code/security review completes before merge.
+
+---
+
 ## Fleet Declarative Configuration Management Workstream (FCM, #758)
 
 ### Problem and objective

docs/SITEMAP.md

@@ -3,9 +3,11 @@
 ## Compaction refresh lease broker
 
 - [Internal broker protocol](architecture/lease-broker-protocol.md) — kernel identity, ancestry and generation invariants, framed requests, responses, and persisted cycle bindings.
-- [Broker operations](guides/lease-broker-operations.md) — protected paths, startup, fail-closed recovery posture, distinct-principal deployment, and residual risk.
+- [Broker operations](guides/lease-broker-operations.md) — protected paths, startup, constrained recovery, fail-closed posture, distinct-principal deployment, and residual risk.
+- [Constrained recovery skill](../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md) — source-resident thin wrapper, receipt scope, C4 replay boundary, and T-C middle-drop disclosure.
 - [Lease-broker security notes](architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements.
 - [Whole mutator-class gate](architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary.
+- [Compaction revocation lifecycle](architecture/compaction-revocation.md) — Claude/Pi observer matrix, same-PID generation rollover, failure fencing, and the named bounded residual stale window.
 
 ## CLI and skill management
 
@@ -14,10 +16,24 @@
 
 ## Fleet configuration management
 
-- [Generated environment boundary](fleet/reference/generated-env-boundary.md) — roster-derived launch projection, strict local data, legacy quarantine, and downstream interface evidence.
-- [Roster v2 structural contract](fleet/reference/roster-v2-fields.md) — local-tmux schema v2 parsing and structural validation.
-- [Role classes and authority](fleet/reference/role-classes.md) — canonical role resolver and protected authority boundaries.
-- [Executable asset dispositions](fleet/migration/example-profile-disposition.md) — shipped v1 fixture/profile/service validation posture.
+- [Fleet configuration entry point](fleet/README.md) — desired-versus-observed decision tree and complete operator link map.
+- [Desired, derived, and observed state](fleet/concepts/desired-vs-observed-state.md) — roster authority, generation, ownership, and drift.
+- [Identity, class, and runtime](fleet/concepts/identity-class-runtime.md) — stable name, display alias, class, runtime, provider, and model separation.
+- [Role authority and leases](fleet/concepts/role-authority-and-leases.md) — validator/merge-gate separation and bounded lease authority.
+- [Generated launch chain](fleet/concepts/generated-env-launch-chain.md) — strict data parsing, precedence, and quarantine.
+- [Roster v2 structural contract](fleet/reference/roster-v2-fields.md) — schema, supported values, required fields, defaults, and constraints.
+- [Fleet CLI reference](fleet/reference/cli.md) — local desired-state commands, JSON/exit behavior, and gateway-catalog separation.
+- [Lifecycle transitions](fleet/reference/lifecycle-transitions.md) — create/apply/reboot/migration/rollback boundaries.
+- [Status and drift](fleet/reference/status-and-drift.md) — desired/managed/observed state and current/future classifications.
+- [Safe agent CRUD](fleet/how-to/create-update-delete-agent.md) — expected generation, dry-run, and partial-failure recovery.
+- [Local lifecycle operations](fleet/how-to/start-stop-restart.md) — persisted versus one-shot actions.
+- [Configurable interaction instance](fleet/how-to/configure-tess-interaction.md) and [validator instance](fleet/how-to/configure-ultron-validator.md) — generic identities and protected limits.
+- [Reconcile and recover](fleet/operations/reconcile-and-recover.md) — plan/apply lock and recovery behavior.
+- [Environment quarantine](fleet/operations/env-quarantine.md) — private evidence and value-free diagnostics.
+- [Systemd/tmux troubleshooting](fleet/operations/systemd-tmux-troubleshooting.md) — socket, holder, unmanaged-session, and lock decisions.
+- [Backup/restore boundary](fleet/operations/backup-restore.md) and [upgrade-assets hold](fleet/operations/upgrade-assets.md).
+- [v1-to-v2 migration preview](fleet/migration/v1-to-v2.md) and [executable artifact dispositions](fleet/migration/example-profile-disposition.md).
+- [FCM M5 closure evidence](reports/documentation/758-fleet-config-ia-closure.md) and [approved deferrals](reports/deferred/758-fleet-config-deferrals.md).
 
 ## Official channel plugins
 
@@ -80,3 +96,8 @@
 - [Logical identity and connector lease/fencing implementation](https://git.mosaicstack.dev/mosaicstack/stack/issues/755)
 - [M1 logical identity and fencing architecture](architecture/mos-runtime-portability-m1.md)
 - [M1 connector lease operations](guides/mos-connector-lease-operations.md)
+
+## Comms evolution — Matrix-native MACP (design, draft)
+
+- [RFC-001 — MACP: a Mosaic-native, Matrix-native comms layer](rfcs/RFC-001-MACP-MATRIX-NATIVE.md) — Synapse + Mosaic appservice backbone, MACP v1 protocol, presence/escalation, federation, strangler migration off the Hermes MCP bridge.
+- [RFC-002 — Install, configuration & topology for the Matrix/MACP comms system](rfcs/RFC-002-INSTALL-CONFIG-TOPOLOGY.md) — open-source install topology modes, ACME cert provisioning, pluggable secret backend, and config precedence.

docs/TASKS.md

@@ -52,20 +52,20 @@ Active workstream is **W1 — Federation v1**. Workers should:
 > the repository quality gates, independent code and security review, terminal-green CI, and
 > the applicable acceptance evidence before merge. Issue #758 remains open until M5 closes.
 
-| id         | status      | description                                                                                                                                                            | issue | agent         | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                            |
-| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
-| FCM-M0-001 | done        | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet        | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5                                   |
-| FCM-M1-001 | done        | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | coder0        | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation               |
-| FCM-M1-002 | done        | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | #768 squash `a5e8e55`; shared resolver and canonical authority/alias validation delivered                        |
-| FCM-M1-003 | done        | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex         | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | #770 squash `e9c4aa3`; shipped artifact disposition validation delivered                                         |
-| FCM-M2-001 | done        | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex         | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | #772 squash `191efae`; generated/local boundary and private quarantine delivered                                 |
-| FCM-M2-002 | done        | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex         | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | #773 squash `bc5e736`; generation-guarded atomic CRUD and recovery contracts delivered                           |
-| FCM-M3-001 | done        | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex         | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | #785 squash `4990905`; exact roster-owned systemd/tmux reconcile and lifecycle contracts delivered               |
-| FCM-M3-002 | in-progress | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet        | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Canonical v2 named-socket + legacy-v1 default-server boundaries; fake adapters/temp fixtures only                |
-| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | Preview first; no unreviewed lifecycle inference                                                                 |
-| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | Never starts a previously stopped agent or kills an unproven unmanaged session                                   |
-| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Must close every checklist item or record an approved deferral                                                   |
-| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI |
+| id         | status      | description                                                                                                                                                            | issue | agent         | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                                                                                                                              |
+| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| FCM-M0-001 | done        | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet        | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5                                                                                                                                     |
+| FCM-M1-001 | done        | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | coder0        | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation                                                                                                                 |
+| FCM-M1-002 | done        | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | #768 squash `a5e8e55`; shared resolver and canonical authority/alias validation delivered                                                                                                                          |
+| FCM-M1-003 | done        | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex         | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | #770 squash `e9c4aa3`; shipped artifact disposition validation delivered                                                                                                                                           |
+| FCM-M2-001 | done        | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex         | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | #772 squash `191efae`; generated/local boundary and private quarantine delivered                                                                                                                                   |
+| FCM-M2-002 | done        | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex         | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | #773 squash `bc5e736`; generation-guarded atomic CRUD and recovery contracts delivered                                                                                                                             |
+| FCM-M3-001 | done        | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex         | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | #785 squash `4990905`; exact roster-owned systemd/tmux reconcile and lifecycle contracts delivered                                                                                                                 |
+| FCM-M3-002 | in-progress | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet        | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Canonical v2 named-socket + legacy-v1 default-server boundaries; fake adapters/temp fixtures only                                                                                                                  |
+| FCM-M4-001 | done        | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | PR #788; final head `d63bb0206a1d312ab8352ec1d3ca3631146b0baa`; tree `4da210da9a71b035130d4160a4a2e691bdfde2da`; squash `9745bc3f29c26b021a478b7ad03cfb494f6c9de3`; descendant-main pipeline 1855 terminal success |
+| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | HOLD: never starts a previously stopped agent or kills an unproven unmanaged session; not authorized by FCM-M5-001                                                                                                 |
+| FCM-M5-001 | done        | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | #789 content squash 627cf2bb; de-flake repair PR#851/#849 squash 77c9a826; completion proof wp1937 @aa999daf push/ci step 49632 recovery_runtime_unittest.py 3/3 OK (closes wp1932 step 49576 Errno111)            |
+| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | HOLD: final #758 gate; quality, independent code/security review, validator certificate, merge-gate approval, and green CI remain out of M5-001                                                                    |
 
 ## Thin-core prompt diet (#528) — feat/contract-thin-core
 

docs/architecture/compaction-revocation.md

@@ -0,0 +1,59 @@
+# Compaction observer revocation and runtime generations
+
+WI-3 connects Claude and Pi compaction/session lifecycle events to the existing authenticated lease-broker state machine. It does not add a second lease store or let runtime hooks assert identity. Each observer inherits the broker-minted session, resolves the current private runtime generation, and sends the existing `revoke_lease` action over the authenticated Unix socket.
+
+## Observer matrix
+
+| Runtime          | Lifecycle signal                                                 | Action                                                                                                                       |
+| ---------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Claude / Claudex | `PreCompact`                                                     | Revoke the current lease before compaction. A non-zero hook result blocks the lifecycle transition.                          |
+| Claude / Claudex | `SessionStart` with matcher `compact`                            | Revoke again after compacted context starts.                                                                                 |
+| Claude / Claudex | `SessionStart` with matcher `resume\|clear`                      | Atomically advance the private generation, then revoke the replacement incarnation.                                          |
+| Pi               | `session_before_compact`                                         | Revoke before compaction; return `{ cancel: true }` if revocation cannot be confirmed.                                       |
+| Pi               | `session_compact` then the first `context`                       | Arm and run an independent post-compaction revoke. A failed post observer blocks later tools locally until a retry succeeds. |
+| Pi               | `session_start` with reason `reload`, `new`, `resume`, or `fork` | Atomically advance the private generation, then revoke the replacement incarnation before reuse.                             |
+
+The first observer that reaches the broker deletes pending promotion tokens and makes the lease `UNVERIFIED`. The second compaction observer is deliberate redundancy, not a prerequisite for the first. Claudex receives the same mandatory hooks in its isolated `CLAUDE_CONFIG_DIR`; hook merging preserves unrelated isolated settings and rejects malformed or symlinked settings fail-closed.
+
+## Private generation authority
+
+`launch-runtime.py` still registers before `exec`, preserving the kernel-authenticated PID/starttime anchor. It now also creates `generation-<broker-session>.state` beside the broker socket. The file is owner-only mode `0600` under the broker's mode-`0700` directory. Hook descendants read that file instead of relying only on an immutable inherited environment value.
+
+Generation changes use an exclusive file lock, validate owner/type/mode/size, increment monotonically, truncate and write the complete new value, and `fsync` before contacting the broker. Therefore reload, new-session, resume, and fork events may retain the same PID/starttime while still becoming a new broker incarnation. The higher generation causes the broker to atomically discard prior tokens and lease authority; the replacement generation inherits no VERIFIED lease.
+
+If an observer fires while broker transport is unavailable, `revoke-lease.py` advances the private generation as a local fence before returning non-zero. Every later all-tools gate reads that higher value. When the broker is reachable again, authentication of that value performs the same old-generation revocation before authorization. Pi also keeps a process-local post-compaction/rollover failure latch that blocks tool calls. An unsafe or unreadable generation file itself makes both lifecycle revocation and tool authorization fail closed.
+
+## Threat contract and stopping boundary
+
+### BOUNDED RESIDUAL STALE WINDOW
+
+If **both** pre- and post-compaction observers are missed entirely, no revocation signal exists. During the remaining unexpired lease, **within-TTL consequential actions are allowed**. Their count and timing are **bounded by lease expiry, not by the mutator gate**. WI-3 makes no claim that it bounds mutator actions inside this stale interval. The broker's monotonic lease TTL is capped at 300 seconds; after expiry, the next consequential tool is denied with `LEASE_EXPIRED`.
+
+This is the named D2-v5 T-A residual. It is distinct from an observer that fires but cannot contact the broker: the latter creates a local generation fence and fails closed. It is also distinct from T-C total rot, where the lifecycle observers and the all-tools gate are both absent or replaced. Server-side branch protection, required CI, and independent review remain the irreducible backstop for T-C.
+
+| Condition                                                       | Result                                                                                                                |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Either compaction observer succeeds                             | Existing lease and pending promotion tokens are revoked immediately.                                                  |
+| Observer runs but broker confirmation fails                     | Lifecycle transition is denied where supported; local generation fence and runtime latch prevent inherited authority. |
+| Both observers are missed, lease unexpired                      | **ALLOWED** inside the bounded residual stale window. No within-window mutator bound is claimed.                      |
+| Both observers are missed, lease expired                        | **DENIED** by monotonic TTL expiry.                                                                                   |
+| Generation advances on reload/new/resume/fork                   | Prior incarnation revoked; replacement starts `UNVERIFIED`.                                                           |
+| Lifecycle observers and all-tools gate both fail or are removed | T-C total-hook-miss residual; protected-branch controls remain required.                                              |
+
+## T-C server-side branch-protection posture
+
+The required posture is that `main` is push-blocked and PR-only-merge is **MANDATORY**, regardless
+of client-gate state. The client-side gate narrows the exposure window only; it is not the T-C
+guarantee. The server-side protected-branch configuration is the irreducible guarantee for protected
+repository actions. Status-check enforcement and approval enforcement are **RECOMMENDED**.
+
+## Current-vs-required gap (recorded, not enacted)
+
+The current empirical configuration is recorded here without re-probing or mutating live branch
+protection. `enable_push=False` (push-block present), so the mandatory push-block/PR-only-merge core
+holds. `require_approvals=0` (approvals not enforced), `enable_status_check=False` (status checks not
+enforced), and `block_on_official_review=False` (official review not enforced). Those recommended
+merge-quality controls are the current gap; changing them is a separate, owner-gated operations
+decision and is not enacted by this documentation change.
+
+The permanent T12b/T30 acceptance case prints both required outcomes: dual-hook miss within TTL is **ALLOWED**, and the same lease after TTL is **DENIED**. Separate real-socket tests prove each Claude observer and same-PID generation rollover; Pi lifecycle tests exercise pre/post observers, all four replacement reasons, and local failure closure.

docs/architecture/lease-broker-protocol.md

@@ -13,12 +13,23 @@ Each connection carries exactly one UTF-8 JSON object followed by one newline, c
 - `mint_token`: authenticated identity plus `binding` containing exactly `compaction_epoch`, `request_epoch`, `h_source`, `h_payload`, and `schema_version`.
 - `consume_token`: authenticated identity plus `token`.
 - `begin_verification`: authenticated identity, runtime (`claude` or `pi`), cycle `binding`, and a TTL no greater than 300 seconds. The broker revokes existing authority first, enters `PENDING_VERIFICATION`, and returns a single-use promotion token.
+- `begin_recovery`: the constrained recovery entrypoint. It rejects caller-provided receipt/challenge fields and delegates to the same `begin_verification` transition, but reports `PENDING_DELIVERY` and marks the volatile cycle as recovery-owned.
+- `complete_recovery`: authenticated identity only. It rejects caller-provided receipt/challenge fields, obtains the current recovery challenge only from broker state, and delegates to the same trusted-observer → evidence → consume → promote sequence. An observation failure revokes recovery authority; retry starts a fresh challenge.
+
+The daemon owns a second protected production observer socket (mode `0600`) unless a private `--test-observer-file` fixture is selected. That transport accepts only the exact `record_runtime_observation` schema after kernel `SO_PEERCRED` plus the existing anchor/ancestry authentication; it validates the pending runtime/generation before storing one finalized assistant entry for the in-process `RuntimeReceiptObserver`. It is **not** a broker request action. Claude sends its latest assistant entry from the Stop-hook transport; Pi sends only finalized `message_end` assistant content. The public broker socket continues to reject request-supplied `latest_assistant_message` in begin, observe, and complete paths.
+
 - `promote_lease`: authenticated identity plus the exact pending promotion token. The broker commits token consumption before making `VERIFIED` visible.
-- `revoke_lease`: authenticated observer signal; deletes pending tokens and makes the session `UNVERIFIED` immediately.
+- `revoke_lease`: authenticated observer signal; deletes pending tokens and makes the session `UNVERIFIED` immediately. WI-3 Claude/Pi hooks send this existing action; `runtime` and bounded `reason` fields are diagnostic input only and never identity authority.
 - `authorize_tool`: authenticated identity, runtime, and exact runtime-reported tool name. The broker returns an explicit allow/deny decision from the whole-class policy and current lease.
 
-A higher generation for the same anchor atomically replaces the stored incarnation and deletes all prior tokens and lease authority for that session. A lower generation is stale. Tokens are 256-bit values from the operating-system cryptographic RNG and are single use. At most 256 pending tokens may be persisted; another mint fails with `TOKEN_CAPACITY` before mutation. Successful consumption deletes the token, while a replay still fails with `TOKEN_REPLAY`. Live v1 token records retain the existing `consumed: false` schema.
+A higher generation for the same anchor atomically replaces the stored incarnation and deletes all prior tokens and lease authority for that session. A lower generation is stale. Runtime descendants resolve the current generation from an owner-only, locked generation file created by the register-before-exec launcher; reload/new/resume/fork observers advance and `fsync` it before broker revocation. This supports generation replacement even when PID/starttime do not change. Tokens are 256-bit values from the operating-system cryptographic RNG and are single use. At most 256 pending tokens may be persisted; another mint fails with `TOKEN_CAPACITY` before mutation. Successful consumption deletes the token, while a replay still fails with `TOKEN_REPLAY`. Live v1 token records retain the existing `consumed: false` schema.
 
-VERIFIED leases are volatile and monotonic-time bounded: broker restart, generation change, explicit observer revocation, or expiry returns the session to `UNVERIFIED`. `begin_verification` always revokes before minting a new prerequisite. `promote_lease` is valid only from the matching pending cycle; persistence failure rolls token and lease state back, while post-rename durability uncertainty terminates the broker. The WI-1 token is the atomic promotion prerequisite substrate. A later receipt implementation must satisfy that prerequisite but cannot replace the mechanical mutator gate as safety authority.
+VERIFIED leases are volatile and monotonic-time bounded: broker restart, generation change, explicit observer revocation, or expiry returns the session to `UNVERIFIED`. `begin_verification` always revokes before minting a new prerequisite. `begin_recovery` reuses that exact transition and mints a new challenge, so a normal-path receipt/challenge cannot be replayed through recovery. `promote_lease` is valid only from the matching pending cycle; persistence failure rolls token and lease state back, while post-rename durability uncertainty terminates the broker. The WI-1 token is the atomic promotion prerequisite substrate.
+
+## Receipt boundary and T-C residual (R1)
+
+Receipt evidence is a T-A delivery/liveness prerequisite only; it cannot replace the mechanical
+mutator gate as safety authority. The receipt detects an **ABSENT** or **PREFIX-TRUNCATED** terminal
+token. A **MIDDLE-DROP** that preserves the tail is a T-C contract violation that is **NOT receipt-detectable**. It is covered by server-side protected-branch controls, **NOT** by the receipt; no category-wide receipt-detection claim is made for that tail-preserving transformation.
 
 State replacement serializes and enforces the 4 MiB maximum before opening a temporary file, then uses a mode-`0600` temporary file, `fsync`, atomic rename, and parent-directory `fsync`. Every broker mutation snapshots the prior v1 state. A commit failure before rename restores that snapshot and leaves durable state unchanged. A failure after rename makes durability uncertain, so the store is poisoned without rolling memory back and the daemon terminates rather than serving with divergent state. Existing state is opened without following symlinks, must be a bounded regular file at mode `0600`, and is fully schema- and invariant-validated before use. Persisted tokens must be unconsumed, match their session's current generation, and remain within the 256-token cap. Session identity is uniquely keyed by `(anchor_pid,anchor_starttime)`; duplicate logical sessions for one anchor refuse startup. State integrity or mode failures refuse startup. The daemon does not log session IDs or tokens.

docs/architecture/lease-broker-security.md

@@ -2,13 +2,25 @@
 
 - Trusted identity comes only from Linux `SO_PEERCRED` plus `/proc` starttime, never request identity fields.
 - Descendant authorization is anchored to `(pid,starttime)` and uses a complete second starttime pass to fail closed on disappearance or PID-reuse races.
-- Runtime generations are monotonic per anchor; a bump revokes prior-incarnation tokens before persistence commits.
+- Runtime generations are monotonic per anchor; a bump revokes prior-incarnation tokens before persistence commits. WI-3 stores the live generation in an owner-only locked file so same-PID Pi reload/new/resume/fork and Claude resume/clear transitions cannot inherit a VERIFIED lease.
 - Session IDs and cycle tokens use the OS cryptographic RNG. `Math.random` and model output are not token sources.
 - Framing and persistence failures fail closed. Sensitive tokens are not logged.
 - Built-in `0700`/`0600` filesystem modes provide same-principal hardening only, not socket authenticity against the same UID. WI-1 provides no distinct-principal isolation. That stronger deployment requires an external protected proxy, ACL, or service boundary, and the boundary must preserve authenticated client identity for the broker's `SO_PEERCRED` and ancestry authorization rather than substituting a shared proxy identity.
 - WI-2 whole-class authorization denies every consequential, unknown, and custom tool while UNVERIFIED; it does not inspect shell strings or trust wrapper selection. First-class Claude/Pi, both Claudex dispatch modes, PRDY, QA remediation, coord, orchestrator, and fleet starts converge on broker register-before-exec; Claudex additionally installs the mandatory all-tools hook inside its preserved isolated config and fails closed on unsafe settings.
 - The permanent `check-runtime-launches.py` suite/CI guard scans production source for direct literal, absolute-path, process-API, command-array, and dynamic Claude/Pi launches. It has no bypass allowlist: an unrecognized launch form fails CI until routed through the common boundary.
 - WI-2 promotion consumes a WI-1 cycle token before VERIFIED becomes visible. Observer revocation, runtime-generation replacement, broker restart, and monotonic TTL expiry remove authority.
-- Receipt observation, payload construction, compaction observers, and constrained recovery implementation remain later surfaces. A receipt can become a promotion prerequisite but is never the safety mechanism.
+- WI-3 wires redundant Claude `PreCompact`/`SessionStart(compact)` and Pi `session_before_compact`/post-`session_compact` `context` observers to that same revoke action. If broker confirmation fails after an observer fires, the revoker advances the private generation as a local fence; subsequent authorization revokes the stale broker incarnation before any consequential allow.
+- Dual observer absence while a lease remains live is the named **bounded residual stale window**: consequential tools remain allowed until monotonic expiry, with no claimed within-window action bound. After expiry they are denied. Total observer-plus-gate absence remains T-C.
+- Receipt observation, payload construction, and constrained recovery implementation remain later surfaces. A receipt can become a promotion prerequisite but is never the safety mechanism.
+
+## Named residual: promote-lease-lost-ACK (WI-3 D2-v5)
+
+A valid `promote_lease` can leave a session `VERIFIED` in the broker while the client never learns of it. This is a named, bounded D2-v5 T-A residual — an **authority-observability divergence, not an authority divergence, not an ALLOW-risk, and not a retry double-apply**. It is disclosed here, not laundered.
+
+**Window — where it can occur.** The broker commits token consumption and durable `VERIFIED` state _before_ the success reply becomes visible (see the promotion order in `lease-broker-protocol.md`). The residual is confined to the interval after that commit+fsync when the broker→client reply or peer-ACK is lost — for example an extreme-contention send failure or peer disconnect after `handle()` has already mutated and persisted state (the #838 fail-closed transport path). The lease mutation is already durable broker-side; only the acknowledgement to the client is lost. No uncommitted or partially-applied state is involved: the commit either happened (and is authoritative) or it did not (and no lease exists).
+
+**Fail-safe direction — the client can only under-claim.** Broker intent is the ceiling; client authority is always ≤ broker intent, never more. Client-side authority-belief is granted only by a _received_ acknowledgement; a lost acknowledgement conveys nothing, so the client cannot conclude "verified" and continues to treat itself as `UNVERIFIED` (it re-verifies or recovers). If the client retries `promote_lease` with the same token, the token is already consumed and the broker rejects the retry (`PROMOTION_TOKEN_MISMATCH` / `INVALID_LEASE_TRANSITION`); there is no double-apply. The committed `VERIFIED` state the broker holds is authority the lease _legitimately earned_ from a real promotion — the broker authorizing consequential tools under it is correct, not inflation. Divergence is therefore strictly toward _less_ client authority than the broker granted; it never produces authority the broker did not grant.
+
+**Bound — TTL plus the observer/gen-bump revoke backstop, self-healing.** The orphaned `VERIFIED` lease is indistinguishable to the broker from any other legitimately verified lease, so the identical D2-v5 revocation backstops dispose of it: any compaction observer (`PreCompact` / `SessionStart(compact)` for Claude; `session_before_compact` / post-`session_compact` `context` for Pi), any same-PID runtime-generation bump (reload/new/resume/fork), broker restart, or monotonic-time expiry returns the session to `UNVERIFIED`. Monotonic TTL expiry (capped at 300 seconds) is **unconditional** — it requires no observer at all — so the maximum exposure of the orphaned lease is one TTL, ≤ 300 s, after which the next consequential tool is denied with `LEASE_EXPIRED`. Any observer that fires shortens the window further. The residual self-heals: "≥1 observer fires OR expiry ⇒ revoke" catches the lost-ACK lease on the same terms as every other stale lease. As with the dual-observer-miss stale window, WI-3 makes no claim that the mutator gate bounds actions inside the residual interval; the interval is bounded by TTL and the revoke backstop, and the server-side branch-protection / required-CI / independent-review line remains the irreducible backstop for protected-repository mutations.
 
 Coordinator security review must rerun the real socket/peercred and mutator-gate acceptance suites on an unrestricted Linux runner and obtain the mandated independent Opus-SECREV review before integration.

docs/architecture/mutator-class-gate.md

@@ -21,13 +21,13 @@ The authenticated broker is the sole lease writer:
 3. Token consumption commits before the volatile lease becomes VERIFIED. Promotion is last and cannot be reached directly from UNVERIFIED.
 4. `revoke_lease`, a runtime-generation increase, broker restart, or monotonic expiry removes mutator authority.
 
-The initial TTL is capped at the ratified 300-second maximum. A caller may request a shorter positive TTL but cannot lengthen the maximum. Dual compaction-hook miss within an unexpired lease remains the ratified bounded T-A residual; once either observer revokes or TTL expires, the next consequential tool is denied.
+The initial TTL is capped at the ratified 300-second maximum. A caller may request a shorter positive TTL but cannot lengthen the maximum. WI-3 installs the [compaction observer and generation lifecycle](compaction-revocation.md). Dual compaction-hook miss within an unexpired lease remains the ratified bounded T-A residual: consequential tools are allowed until expiry, with no claimed within-window action bound; once either observer revokes or TTL expires, the next consequential tool is denied.
 
 A receipt is only a future promotion prerequisite. It is not an obedience, residency, or safety proof and never replaces this mechanical gate.
 
 ## Runtime adapters
 
-`launch-runtime.py` registers itself with the broker and then `exec`s Claude or Pi so PID/starttime remain the authenticated parent anchor. It exports only the broker-minted session ID and current generation to descendants.
+`launch-runtime.py` registers itself with the broker and then `exec`s Claude or Pi so PID/starttime remain the authenticated parent anchor. It exports the broker-minted session ID and an owner-only generation-file reference to descendants; lifecycle hooks advance that file for same-PID replacement generations.
 
 - Claude installs `mutator-gate.py` as an all-tools (`.*`) `PreToolUse` hook.
 - `mosaic claudex` and `mosaic yolo claudex` preserve their isolated `CLAUDE_CONFIG_DIR`, merge the mandatory hook into that isolated `settings.json`, and use the same register-before-exec launcher. Malformed or symlinked isolated settings deny launch.

docs/compaction-refresh/governance/GATE0-PROBE3-EXEC-AMENDMENT.md

@@ -1,109 +0,0 @@
-# Gate0 Charter Amendment — Probe-3 (D4) Evidence-Class EXECUTION Authorization
-
-**Status:** DRAFT (revision 2) — supersedes prior candidate pin `8fca5b7a`; pending Mos re-scope-verify BEFORE
-re-pin is ratified. Revised per Mos adjudication directive (2026-07-18): §3 = D4-focused Option A; §1 = explicit binding model.
-**Amendment type:** Additive durable-authority amendment (does NOT mutate any ratified pinned doc in place).
-**Milestone:** 188 — Compaction-Refresh Mechanism · **Issue:** Gitea #827 (WI-0 Gate0) · gates WI-3 #830 merge.
-
----
-
-## 1. Authorized source (why this amendment is valid)
-
-Per the Mosaic governance principle (OpenBrain `f0cb61b6`, permanent; fail-closed / DO-178C): a durable
-Gate0 execution-hold clears ONLY by **(i) explicit user (owner) authorization** OR **(ii) a durable-authority
-amendment from an authorized source**. A runtime coordinator's verbal GO does NOT qualify.
-
-- **Owner authorization (i):** Jason (owner / north-star) directed in `#mos` **2026-07-18 17:28Z** — *"amend the
-  charter"* (option **B** from the WI-3 escalation), quoting the escalation back. This is the direct-user
-  authorization artifact that homelab's durable-Gate0 objection (2026-07-18 06:34:56Z) explicitly named as a
-  valid resolution condition (*"user artifact OR auth amendment"*). Relayed + authenticity-adjudicated by Mos
-  (`web1:mos-claude`). Owner outranks any peer-lane durable authority.
-- **Amendment (ii):** this document, authorized BY that owner directive.
-
-Both qualifying conditions are therefore satisfied. Homelab's stated condition is met by the owner artifact;
-homelab is NOTIFIED as a transparency step (it holds durable-Gate0 standing and raised the original catch),
-but its co-sign is not a gate (owner > peer).
-
-**Binding model (explicit — how this SHA is authorized).** The authority binding for this amendment's pinned
-bytes is the composition of two distinct acts:
-1. **Owner class-authorization (PRE-SHA):** Jason (owner) authorized the *class of action* — "amend the
-   charter" (option B), `#mos` 2026-07-18 17:28Z. This occurred **before** these amendment bytes (and hence
-   this SHA256) existed; the owner authorized the amendment, not a specific hash.
-2. **Independent-adjudicator byte-verification:** Mos (`web1:mos-claude`), acting as the independent
-   adjudicator (author ≠ verifier — MS-LEAD authored, Mos verifies), scope-verifies the **exact bytes** of
-   this document and confirms they express only the owner-authorized narrow scope.
-
-There is therefore **NO single "Jason-signs-the-SHA" artifact, and none is required** under this binding
-model: owner-authorized-class + independent-adjudicator-byte-verify **is** the binding. This is the durable,
-inspectable chain of custody for the pin.
-
-## 2. Charter provisions amended (sha-pinned, unmutated)
-
-This amendment attaches to — and does NOT rewrite — the ratified Gate0 charter provisions:
-
-- `compaction-refresh-BUILD-BRIEF.md` §5 / R4 "Gate0 = BUILD-ADMISSION GATE", specifically the item:
-  *"Same-PID `runtime_generation` bump on reload/resume/fork revokes prior lease (D4)."*
-  sha256 `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b` (intact/unchanged).
-- `compaction-refresh-SPEC-RATIFICATION.md` R4.
-  sha256 `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67` (intact/unchanged).
-
-The two pinned docs remain byte-identical; this amendment is the delta of record.
-
-## 3. What is authorized (NARROW — D4-focused harness ONLY)
-
-Adjudicator ruling (Mos, `web1:mos-claude`): "D4-only" against the existing runner is non-executable — the
-only runner (`pi_gate0_run.py`) drives P2+P5+P6+D4 in one flow, and D4 intrinsically requires a
-promoted-to-VERIFIED baseline (spec L219: "P3 immediately follows the valid P2 promotion so reload must
-revoke a genuinely VERIFIED prior gen") to revoke a genuine prior generation. Therefore authorize EXACTLY the
-minimal executable form (Option A) required as WI-3 (#830) merge-gate (2):
-
-- **D4-focused harness:** spawns **ONLY** `p3_generation_broker.py` (not the full `pi_gate0_run.py` runner).
-- **Minimal promotion-to-VERIFIED, as a FIXTURE PRECONDITION ONLY:** established solely so the D4 revoke has a
-  genuine `VERIFIED` target. This is **NOT** authorization to bank P2 as an independent evidence class.
-- **D4 same-PID `runtime_generation`-bump revoke observation:** new generation → `MUTATOR_UNVERIFIED`;
-  prior (superseded) generation → `STALE_GENERATION`.
-- **Explicitly EXCLUDED:** P5 (missing / oversize / hash-invalidation) and P6 (atomic-observation) — not
-  needed for the WI-3 D4 gate and **not authorized** by this amendment.
-- **Isolation / integrity (per §4/§5):** 3× repeated, isolated runs; hardened deterministic harness;
-  non-destructive; launches broker/socket/state artifacts in an isolated fixture ONLY; **does NOT touch
-  production**, mutates no live lease/broker/deployment, creates no durable side effect outside the fixture;
-  a **FAIL** returns to planner — no retry-launder.
-
-**Intrinsic-precondition boundary (verbatim):** the promotion step is a D4 test fixture, not a P2
-evidence-gathering authorization; P5/P6 remain unauthorized.
-
-## 4. What is NOT authorized (all other holds remain in force)
-
-- This is **NOT** a blanket Gate0-execution release. Every other Gate0 execution item and every standing
-  execution hold remains exactly as-is.
-- No live mutation, migration, canary, deployment, systemd, tmux-fleet, or connector/socket/Hermes action is
-  authorized by this amendment.
-- Authorizes producing THIS evidence class once (3× isolation is the evidence-integrity requirement, not a
-  license to re-run on failure): a **FAIL** returns to planner — **no retry-launder**, no severity-laundering.
-
-## 5. Preserved fail-closed / DO-178C invariants (verbatim, unchanged)
-
-- Producing probe evidence **EXECUTES** the Gate0 mechanism (launches processes, creates socket/state
-  artifacts, exercises revocation transitions); "isolated + non-destructive" does **not** make it
-  non-execution. This amendment authorizes that execution for the narrow class in §3 — it does not redefine
-  execution as non-execution.
-- A sha-pinned DURABLE authority OUTRANKS a runtime coordinator's verbal GO; when they conflict the durable
-  artifact wins. This amendment derives its authority from the OWNER, not from a coordinator.
-- Card-advancement gates and execution-holds are distinct; this amendment lifts ONLY the §3 execution-hold,
-  not any advancement/review/SECREV gate. WI-3's independent-review + Opus-SECREV + green-suite gates stand.
-
-## 6. Effect on WI-3 (#830) merge chain
-
-On this amendment being pinned (Mos-verified + Jason-shown): a fresh lane (ms-rev-826) executes the §3
-probe-3 evidence class (3× isolation) → PASS/FAIL reported to Mos. **On PASS**, and only after re-confirming
-WI-3 head `f4008307` UNMOVED + FIRE-PRECONDITION-0 (fresh `mosaic-context-refresh` attestation for
-mosaic-100 + planner-opus), the existing chain runs: CI queue-guard → push → PR → mirror RoR → relay full-40
-head + pr/ci# → Mos independent 6-check → squash `closes #830` → chain WI-4→7. **On FAIL**: planner-return.
-
----
-
-**Amendment author:** MS-LEAD (`web1:mosaic-100`), Gate0 governance interface / charter custodian.
-**Pin protocol:** this file's sha256 becomes the amendment pin ONLY after Mos re-scope-verify. Reported to Mos
-before any ratification/publication, per the transparency checkpoint on a durable-authority change. Ratification
-and durable publication (to a homelab-inspectable provider ref) are the adjudicator's (Mos), NOT the author's
-(MS-LEAD) — the author does not self-ratify and does not publish.

docs/compaction-refresh/governance/OWNER-WINDOW.md

@@ -1,49 +0,0 @@
-# Gate0 Probe-3 Amendment — Owner Transparency Window (durable record)
-
-**Purpose.** Durable evidence (defined duration + closure) that the owner-transparency window on the
-probe-3 amendment **scope-correction** has a bounded, inspectable lifecycle — per homelab's GATE-A
-requirement (2026-07-18 18:13:14Z). This is NOT the owner's core authorization (that is durable in the
-amendment §1); it is the objection-window on the narrowing disclosed afterward.
-
-## What was disclosed
-The owner (Jason) explicitly authorized the amendment **class** — "amend the charter" (option B),
-`#mos` 2026-07-18 17:28Z (amendment §1). My initial narrowing was "D4-only"; on adjudication that proved
-non-executable (D4 intrinsically needs a promoted-to-VERIFIED baseline). The **corrected** scope
-(rev 2, pin `9ac9ff87`, §3) adds a *minimal promotion-to-VERIFIED as a test fixture only* (P5/P6 still
-excluded, P2 not banked as evidence). Because this adds a fixture step beyond the "D4-only" I first told
-the owner, I disclosed the correction to him for transparency.
-
-## Window (bounded, durable)
-- **Opened:** 2026-07-18T18:00:25Z  — anchored to the adjudicator's Discord scope-correction disclosure to the
-  owner (message id `1528099140100296736`, snowflake-decoded; not an informal estimate).
-- **Duration:** 2 hours (defined).
-- **Scheduled closure:** 2026-07-18T20:00:25Z.
-- **Closure condition (fail-closed):**
-  - No owner objection received by scheduled closure → window **CLOSED-CLEAR** (the disclosed correction
-    stands; it is within the already-granted class authorization).
-  - Any owner objection before closure → window does **NOT** clear → re-adjudicate the corrected scope.
-  - An affirmative owner "proceed" before closure → **early CLOSED-CLEAR** (recorded here).
-
-## Closure attestation
-Closure will be confirmed by a dated adjudicator tick appended below (and to the orchestration ledger)
-at/after 2026-07-18T20:00:25Z. Until that attestation exists, GATE A is OPEN and probe-3 execution stays HELD.
-
-- [x] **CLOSED-CLEAR attestation — recorded 2026-07-18T20:08Z by adjudicator Mos (`web1:mos-claude`).**
-
-### CLOSED-CLEAR attestation (2026-07-18T20:08Z)
-
-The owner-transparency window on the probe-3 amendment scope-correction is **CLOSED-CLEAR**.
-
-- **Scheduled closure:** 2026-07-18T20:00:25Z — reached (authoritative UTC at attestation: 2026-07-18T20:07Z, past closure).
-- **Closure condition met:** *No owner objection received by scheduled closure.* Verified fail-closed against the
-  **durable Discord #mos record** (not memory): the channel's last message is the scope-correction disclosure itself
-  (`id 1528099140100296736`, 2026-07-18T18:00:25.709Z). From window-open (18:00:25Z) through closure (20:00:25Z) and
-  to this attestation, there are **zero owner (jetrich) messages** — no objection, no affirmative early-GO. The last
-  owner message preceding the window was the class authorization *"Amend the charter"* (17:28Z, amendment §1).
-- **Effect:** the disclosed corrected scope (rev 2, pin `9ac9ff87`, §3 — minimal promotion-to-VERIFIED as a D4 test
-  fixture only; P5/P6 excluded; P2 not banked as evidence) **stands**, within the already-granted class authorization.
-- **GATE A is now CLOSED.** Probe-3 execution proceeds ONLY under the full remaining chain: GATE-B fresh §3-review PASS
-  (concurred @839d156f, author≠reviewer) + adjudicator explicit FIRE GO. No other Gate0 hold is lifted by this tick.
-
-*Adjudicator: Mos (`web1:mos-claude`). This record is durable and provider-inspectable alongside the
-amendment (`9ac9ff87`) and its RATIFICATION.md.*

docs/compaction-refresh/governance/RATIFICATION.md

@@ -1,37 +0,0 @@
-# Gate0 Probe-3 (D4) Amendment — Adjudicator Ratification Record
-
-**Ratifies pin:** `9ac9ff873fad41a6e15763cc89cb94d0bc4a6b0cf9b6770561d1781b03f63276`
-(`GATE0-PROBE3-EXEC-AMENDMENT.md`, 7699 bytes, this branch).
-**Supersedes:** prior candidate pin `8fca5b7a` (never executed against; withdrawn on scope + durability grounds).
-
-## Re-scope-verify — PASSED
-Verified by **Mos (`web1:mos-claude`)**, acting as independent adjudicator (author ≠ verifier: MS-LEAD
-authored, Mos verified), 2026-07-18. SHA256 recomputed = pin (exact). Scope checks, all PASS:
-- §3 = Option A, D4-focused: harness spawns ONLY `p3_generation_broker.py`; minimal promotion-to-VERIFIED
-  is a FIXTURE PRECONDITION only (not P2 evidence-banking); D4 gen-bump revoke observation
-  (new→`MUTATOR_UNVERIFIED`, prior→`STALE_GENERATION`); **P5/P6 explicitly excluded + unauthorized**;
-  verbatim intrinsic-precondition boundary line present.
-- §1 binding model explicit; §2 charter provisions pinned unmutated; §4/§5 invariants intact.
-- No scope creep beyond the owner-authorized narrow class.
-
-## Authority binding
-- **Owner class-authorization (PRE-SHA):** Jason (owner) — "amend the charter" (option B), `#mos`
-  2026-07-18 17:28Z. Authorized the amendment class before these bytes existed.
-- **Independent-adjudicator byte-verification:** Mos scope-verified the exact bytes.
-- No single "Jason-signs-the-SHA" artifact exists or is required under this binding model.
-
-## Round-trip integrity (this branch/commit)
-All three files fetched back via the Gitea raw API and SHA-matched (each > 200B, no not-found sentinel):
-- `GATE0-PROBE3-EXEC-AMENDMENT.md` → `9ac9ff87…f63276` ✓
-- `charter-BUILD-BRIEF.md`         → `89fdbc27…71b` ✓
-- `charter-SPEC-RATIFICATION.md`   → `bac58319…67` ✓
-
-## Status: RATIFIED — probe-3 execution remains HELD
-Publication here closes the governance-infra gap (the charter provisions were previously local-only,
-not inspectable). Probe-3 execution stays HELD pending both: (1) homelab independent verification of
-these published bytes; (2) owner transparency window. On both clearing → ms-rev-826 builds + runs the
-§3 D4-focused harness (3× isolation, non-destructive) → PASS/FAIL to Mos → WI-3 (#830) chain per §6.
-
-*Note: the amendment file's own status line reads "DRAFT (revision 2)"; that internal text is
-superseded by THIS external ratification record (the pinned bytes are deliberately not edited, so the
-SHA stays stable). Ratification status lives here, not in the pinned artifact.*

docs/compaction-refresh/governance/charter-BUILD-BRIEF.md

@@ -1,106 +0,0 @@
-# Compaction-Refresh Mechanism — BUILD BRIEF (Mos → MS-LEAD)
-
-**Status:** STAGED — do NOT dispatch until PR #826 (#824 skill-CLI bridge) MERGES. Mos routes this to
-MS-LEAD at #824 land. PLAN phase COMPLETE + RATIFIED; this is the BUILD-execution brief.
-**Routed by:** Mos (main orchestrator). **Owner:** MS-LEAD (mosaic-100). **Runtime scope M1:** Claude + Pi.
-
-## 1. AUTHORITY (sha256-pinned — build AGAINST these, do not re-derive)
-| Artifact | Path | SHA-256 |
-|---|---|---|
-| **Ratification record (SSOT)** | `~/agent-work/reviews/compaction-refresh-SPEC-RATIFICATION.md` | `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67` |
-| Ratified SPEC v5 | `~/agent-work/reviews/compaction-refresh-SPEC-v5.md` | `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433` |
-| sol FINAL red-team (GO) | `~/agent-work/reviews/compaction-refresh-SPEC-v5-redteam-sol.md` | `3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa` |
-
-The coder MUST verify these hashes before building. The in-context working spec is DERIVED and
-compaction-fragile — the sha256'd records above are the recovery SSOT (durable-authority discipline).
-
-## 2. TARGET & SCOPE
-- **Framework-native `packages/mosaic/…`** in `mosaicstack/stack`. NOT jarvis-brain. NOT
-  `~/.config/mosaic/` directly (that tree is WIPED on framework upgrade — durable home is SOURCE).
-- **M1 = Claude + Pi orchestrators only.** Codex/other runtimes = scope-note only.
-- **Hard dependency (now satisfied at dispatch):** the `mosaic skill` register/list + install/upgrade
-  symlink auto-sync (#824 / PR #826) — so the durable `mosaic-context-refresh` skill ships REACHABLE
-  (auto-symlinked into `~/.claude/skills/`). Do not dispatch before #826 merges.
-
-## 3. DELIVERABLES (locked architecture — from the ratification record; do NOT redesign)
-1. **Authenticated external lease broker** bound to kernel `SO_PEERCRED` `(pid, starttime,
-   runtime_generation)` — the only unforgeable identity on a same-uid tmux fleet. Broker **MINTS** the
-   logical `session_id` at first peercred contact (NEVER caller-asserted). Distinct-principal /
-   protected socket.
-2. **Whole mutator-class gate** (not per-wrapper): no consequential mutator succeeds without a valid
-   VERIFIED lease. **Revoke-first / promote-last.**
-3. **Compaction observers → revoke:** Claude `PreCompact` + `SessionStart(matcher=compact)`; Pi
-   `session_before_compact`/`context` equivalents. Any `runtime_generation` bump (reload/resume/fork,
-   same PID included) auto-revokes the prior incarnation.
-4. **Verbatim-hashed normative fragments:** `B_payload` (exact fragments + deterministic metadata) and
-   `H_payload = SHA256(domain_sep ‖ length_framed(B_payload))` — NO self-reference (byte-identical
-   across the Claude and Pi builders).
-5. **Receipt-challenge protocol (promotion prerequisite, NOT the safety mechanism):** broker mints a
-   single-use `receipt_challenge` per cycle bound to `(session_id, runtime_generation,
-   compaction_epoch, request_epoch, H_source, H_payload, schema_version)`. **COMPUTE = broker**
-   (observes latest-assistant message, computes the binding incl `H(latest-assistant-message)`);
-   **COPY = model** (verbatim copy of challenge + `H_payload` — an LLM cannot hash its own output;
-   T29). Observed in the EXACT latest assistant message (Claude: latest assistant entry + pending
-   challenge, NO transcript grep; Pi: `message_end`, NOT `after_provider_response`). Single-use,
-   consumed before the tool batch. Broker transition order (mandatory): `revoke → build
-   B_payload/H_payload → PENDING_DELIVERY(mint unique challenge) → deliver → observe exact receipt →
-   evidence commit → consume challenge → promote VERIFIED (last)`.
-6. **Constrained recovery command** = the single ungated mutator; the `mosaic-context-refresh` skill
-   is its wrapper (uses a newly-minted challenge + identical protocol; cannot replay normal-path
-   receipt). Durable skill lands here, symlink-reachable via #824.
-7. **T-C server-side line = branch protection** (the irreducible guarantee; client gate is
-   window-narrowing only). If ops-config rather than code, DOCUMENT the required posture explicitly.
-
-## 4. BINDING BUILD CONDITIONS R1–R6 (MANDATORY — verbatim from ratification record)
-- **R1 (honesty):** state that the receipt detects ABSENT or PREFIX-TRUNCATED terminal token, but a
-  MIDDLE-DROP preserving the tail is a **T-C contract violation, NOT receipt-detectable** (covered by
-  server-side). No over-claim.
-- **R2 (atomicity):** evidence-commit → consume-challenge → promote-VERIFIED is ONE atomic broker
-  transaction; a crash leaves neither VERIFIED-with-live-challenge nor consumed-with-ambiguous-promote;
-  recovery mints a NEW challenge, never reuses.
-- **R3 (parsing):** exact single current-cycle receipt parse — no unbounded grep; reject
-  quoted/tool-output receipts, wrong generation/epoch, unknown/stale challenge, multiple receipts.
-- **R4 (Gate0 = BUILD-ADMISSION GATE):** see §5 — runtime evidence BEFORE build admission; a failed
-  Gate0 item RETURNS the design to planner review, it is NOT waived by the GO.
-- **R5 (TTL):** 300 s MAX lease TTL + soak-tighten; soak may only SHORTEN, never lengthen. Mos-accepted.
-- **R6 (receipt semantics):** receipt = T-A delivery/liveness ONLY, never obedience/safety/residency.
-  Permanent invariant.
-
-## 5. R4 GATE0 — RUNTIME EVIDENCE BEFORE BUILD ADMISSION (WI-0, do this FIRST)
-Structure the build like gitwatch: **WI-0 is a Gate0 runtime-evidence probe; no feature build admitted
-until every item produces POSITIVE runtime evidence** (not a design assertion). A failed item RETURNS
-to planner — do not paper over:
-- Launcher `exec`/parent topology + supported-hook ancestry (D1); broker authenticates the launcher
-  chain, rejects sibling-substitution.
-- Pi lifecycle: last-position invariant (last-or-closed), per-tool nonce → tool-call-id map (D5).
-- Same-PID `runtime_generation` bump on reload/resume/fork revokes prior lease (D4).
-- Broker socket authenticity posture (protected / distinct-principal); `SO_PEERCRED` returns the true
-  `(pid, starttime)`.
-- Source-invalidation fail-closed (missing/oversize/hash-mismatch fragment → no promotion).
-- Claude `additionalContext` + Pi `context` inject atomically (A-v5-1) — the transport assumption
-  T27 rests on; verify or class the gap T-C.
-
-## 6. ACCEPTANCE TESTS (red-first TDD)
-Carry all v4 ACs + T12b; add **T24–T30**: T24 hash-construction no-self-reference byte-identical across
-builders · T25 replay rejected · T26 transcript-stale-match cannot promote · T27 partial-delivery
-(prefix-trunc/tail-only/middle-drop/malformed) none promote · T28 single-use (no renew/reopen) · T29
-model copies not computes · T30 dual-hook-miss matches AMENDED threat table within+after TTL.
-Acceptance = full green suite + Gate0 evidence pack.
-
-## 7. REVIEW & MERGE DISCIPLINE
-- **This IS an Opus-SECREV-mandatory surface** — UNLIKE #824 (local same-uid FS). The broker is an
-  authentication/identity/authorization mechanism (peercred binding, session_id minting, mutator-class
-  gating, receipt protocol). Security review = **Opus-SECREV, no GPT/terra substitute** on the
-  broker/gate/receipt/socket surfaces. Functional/non-security parts may take GPT review.
-- **Author ≠ reviewer**, independent review, no self-merge, exact-head RoR (reviewed-SHA=merged-SHA),
-  `closes #<issue>` close-keyword, full 40-char head. Never edit tests to pass / never force-merge red
-  / never `--no-verify`.
-- **Mos merges** (per ratification record) after Opus-SECREV + independent review pass + green suite +
-  Gate0 pack. Decompose into work-items (WI-0 Gate0 first); likely a milestone, not one monolithic PR.
-
-## 8. SEQUENCING
-#826 (#824 bridge) MERGES → Mos routes this brief → MS-LEAD decomposes (WI-0 Gate0 first) → build M1
-(Claude+Pi) → Gate0 evidence pack (failed item → planner) → Opus-SECREV + independent review → Mos
-merges → durable `mosaic-context-refresh` skill lands symlink-reachable → jarvis-brain `CLAUDE.md`
-mandate PR aligns to the shipped receipt/hash contract. Interim skill + CLAUDE.md mandate stay LIVE
-until the mechanism ships.

docs/compaction-refresh/governance/charter-SPEC-RATIFICATION.md

@@ -1,75 +0,0 @@
-# Compaction-Refresh Mechanism — SPEC RATIFICATION RECORD
-
-**Ratifier:** Mos (main fleet orchestrator, `mos-claude`)
-**Date:** 2026-07-17 ~22:2xZ
-**Decision:** ✅ **RATIFIED — GO WITH BINDING CONDITIONS R1–R6.** Architecture converged v1→v5 via
-oppositional adversarial planning (planner-opus authors / planner-sol red-teams). No v6 required.
-
-## Authenticated authority artifacts (sha256-pinned)
-
-| Artifact | Path | SHA-256 |
-|---|---|---|
-| Ratified SPEC v5 | `~/agent-work/reviews/compaction-refresh-SPEC-v5.md` | `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433` |
-| sol FINAL red-team (GO) | `~/agent-work/reviews/compaction-refresh-SPEC-v5-redteam-sol.md` | `3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa` |
-| (base) SPEC v4 | `~/agent-work/reviews/compaction-refresh-SPEC-v4.md` | `a5e9c261a613974fc0d853d69ad76f616f5f1c3b6b63a436daecdd15b4a72b80` |
-| (base) sol v4 red-team | `~/agent-work/reviews/compaction-refresh-SPEC-v4-redteam-sol.md` | `1e76ee5942241d9520b9ff8f39a628488578ec2d9b91cc09b9f0e7cc6091ef2f` |
-| Ratification-Input (R1-R6 + rulings, provenance-clean) | `~/agent-work/reviews/compaction-refresh-SPEC-RATIFICATION-INPUT.md` | `d01411a5c966f513e992a941deef0ff5cc6f29d37adab97ea2fbd3c5e6aef266` |
-
-## Convergence trail
-v1 NO-GO (9 architectural) → v2 NO-GO (7 enforcement, arch accepted) → v3 NO-GO (5 surgical, arch
-locked) → v4 NO-GO (narrow; echo-lock narrowing APPROVED) → **v5 GO-with-conditions**.
-
-## Locked architecture (do not redesign)
-Authenticated external **lease broker** bound to kernel `SO_PEERCRED` (pid, starttime,
-runtime_generation) — the only unforgeable identity fact on a same-uid tmux fleet. Broker MINTS the
-logical session_id at first peercred contact (never caller-asserted). **Revoke-first / promote-last.**
-Whole **mutator-class gate** (not per-wrapper). Verbatim-hashed normative fragments. Single
-**constrained recovery command** = the only ungated mutator; the `mosaic-context-refresh` skill is its
-wrapper. **Threat tiers:** T-A honest-stale → client gate · T-B compromised-tool → mutator-class · T-C
-fully-rotted → **server-side branch-protection = the irreducible line** (client gate is
-window-narrowing, NOT a complete guarantee).
-
-**Delivery-receipt (echo-lock, sol §8-final):** broker mints a single-use `receipt_challenge` per
-cycle bound to (session, runtime_generation, epochs, H_source, H_payload); **COMPUTE = broker**
-(observes + computes the full binding incl H(latest-assistant-message) as the cycle-audit fact),
-**COPY = model** (copies challenge + H_payload verbatim — model never computes a hash; sol T29
-copy-not-compute preserved). Receipt is a **one-cycle T-A delivery/liveness proof ONLY — never an
-obedience, residency, or safety proof.** The mechanical mutator-class gate remains THE safety
-mechanism; §8 intact for T-B/T-C.
-
-## Binding ratification conditions (R1–R6) — MANDATORY for build acceptance
-- **R1 (honesty / T27 amendment):** state honestly that the receipt detects an ABSENT or
-  PREFIX-TRUNCATED terminal token, but a MIDDLE-DROP that preserves the tail token is a **T-C
-  contract violation, NOT receipt-detectable** (covered by server-side, not the receipt). No
-  over-claim. Fold as a doc amendment — no v6.
-- **R2 (atomicity):** evidence-commit → consume-challenge → promote-VERIFIED is ONE atomic broker
-  transaction. A crash leaves NEITHER a VERIFIED-with-live-challenge NOR a
-  consumed-with-ambiguous-promotion state; recovery mints a **NEW** challenge, never reuses one.
-- **R3 (parsing):** exact single current-cycle receipt parse — no unbounded grep; reject
-  quoted/tool-output receipts, wrong generation/epoch, unknown/stale challenge, and multiple receipts.
-- **R4 (Gate0 runtime evidence — BUILD-ADMISSION GATE):** launcher-ancestry/D1,
-  sibling-substitution rejection, Pi last-or-closed, same-PID runtime_generation bump,
-  nonce→tool-call-id map, socket/authenticity posture, and source-invalidation fail-closed require
-  **runtime Gate0 evidence BEFORE build admission**, not design assertion. **A failed Gate0 item
-  RETURNS the design to planner review — it is NOT waived by this GO.**
-- **R5 (TTL — RATIFIER ACCEPTED):** proposed **300s MAX lease TTL + soak-tighten** is **ACCEPTED by
-  Mos (ratifier)**. Safe-direction default: soak data may only SHORTEN it, never lengthen. Operator
-  (Jason) may tighten at will; flagged for operator awareness, non-blocking (not an escalation
-  trigger — a proposed max that only tightens).
-- **R6 (receipt semantics — REAFFIRMED):** receipt remains T-A delivery/liveness ONLY, never
-  obedience/safety proof. Reaffirmed as a permanent invariant of the design.
-
-## Build sequencing (PLAN-ONLY until these clear)
-1. **HARD DEP:** `mosaic skill` register/unregister/list + generic install/upgrade symlink auto-sync
-   (mosaicstack/stack **#824**, in flight on ms-824) MUST land first — else the durable
-   `mosaic-context-refresh` skill ships unreachable (no `~/.claude/skills/` bridge symlink).
-2. Then MS-LEAD builds the mechanism in **packages/mosaic** (M1 = Claude + Pi orchestrators) against
-   THIS ratified spec + R1–R6, producing R4 Gate0 evidence. Author≠reviewer independent review; no
-   self-merge; Mos merges.
-3. The durable `mosaic-context-refresh` skill (+ jarvis-brain CLAUDE.md mandate PR) lands aligned to
-   the ratified receipt/hash contract, AFTER the #824 bridge exists.
-
-**Interim protection (live now, until the mechanism ships):** `mosaic-context-refresh` skill
-(fail-closed 7-line residency attestation) + jarvis-brain CLAUDE.md "Directive Freshness After
-Compaction" mandate — self-run manual re-read + attestation. Symlink hand-created this session; loads
-and attests 7/7.

docs/compaction-refresh/probes/p5_receipt_replay.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""P5 Gate0 replay probe; BUILT ONLY, execution is Mos-gated.
+
+Run only under fresh-executor authorization:
+  python3 -I -S -B docs/compaction-refresh/probes/p5_receipt_replay.py
+
+Each of the default three isolated runs launches the shipped lease-broker daemon
+in a distinct private temporary directory.  This driver never changes broker
+state directly and does not replace the promote gate: every transition is sent
+over the daemon's real Unix socket.  It proves the shipped order is
+PENDING_DELIVERY -> observe/evidence commit -> consume -> VERIFIED and that a
+consumed challenge cannot be replayed or reopen/renew its lease.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import importlib.util
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+HERE = Path(__file__).resolve().parent
+REPOSITORY = HERE.parents[2]
+TOOLS = REPOSITORY / "packages/mosaic/framework/tools/lease-broker"
+DAEMON = TOOLS / "daemon.py"
+FRAGMENTS = TOOLS / "normative_fragments.py"
+
+
+def load_shipped_fragments():
+    if not FRAGMENTS.is_file():
+        raise RuntimeError(f"shipped normative construction missing: {FRAGMENTS}")
+    spec = importlib.util.spec_from_file_location("p5_shipped_normative_fragments", FRAGMENTS)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("unable to load shipped normative construction")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def request(socket_path: Path, value: dict[str, object]) -> dict[str, object]:
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
+        connection.settimeout(3.0)
+        connection.connect(str(socket_path))
+        connection.sendall((json.dumps(value, separators=(",", ":")) + "\n").encode())
+        connection.shutdown(socket.SHUT_WR)
+        response = bytearray()
+        while True:
+            chunk = connection.recv(4096)
+            if not chunk:
+                break
+            response.extend(chunk)
+    if not response.endswith(b"\n") or response.count(b"\n") != 1:
+        raise AssertionError(f"unframed broker reply: {bytes(response)!r}")
+    parsed = json.loads(response[:-1])
+    if not isinstance(parsed, dict):
+        raise AssertionError(f"non-object broker reply: {parsed!r}")
+    return parsed
+
+
+def wait_ready(process: subprocess.Popen[str], socket_path: Path) -> None:
+    deadline = time.monotonic() + 5.0
+    while time.monotonic() < deadline:
+        if socket_path.exists():
+            return
+        if process.poll() is not None:
+            output = process.stdout.read() if process.stdout is not None else ""
+            raise RuntimeError(f"shipped daemon exited before READY: {output}")
+        time.sleep(0.02)
+    raise TimeoutError("shipped daemon did not create private probe socket")
+
+
+def expect_refused(reply: dict[str, object], code: str) -> None:
+    if reply != {"ok": False, "code": code}:
+        raise AssertionError(f"expected refusal {code}, got {reply!r}")
+
+
+def run_once(index: int) -> str:
+    fragments = load_shipped_fragments()
+    root = Path(tempfile.mkdtemp(prefix=f"mosaic-p5-replay-{index}-"))
+    os.chmod(root, 0o700)
+    socket_path = root / "broker.sock"
+    state_path = root / "state.json"
+    observer_path = root / "test-observer.json"
+    process = subprocess.Popen(
+        [
+            sys.executable, "-I", "-S", "-B", str(DAEMON), "--socket", str(socket_path),
+            "--state", str(state_path), "--test-observer-file", str(observer_path),
+        ],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+    try:
+        wait_ready(process, socket_path)
+        registered = request(socket_path, {"action": "register_anchor", "runtime_generation": 1})
+        if registered.get("ok") is not True or not isinstance(registered.get("session_id"), str):
+            raise AssertionError(f"registration failed: {registered!r}")
+        session_id = registered["session_id"]
+        construction = fragments.build_payload(
+            manifest_version=1,
+            generator_version="p5-replay-probe",
+            fragments=[
+                fragments.NormativeFragment(
+                    "authority/probe",
+                    b"P5 shipped transition driver\n",
+                    "63537df1a6cb0d80195a96757ab11d629e5b5e1f23be167218b84cb195b1c1d6",
+                ),
+            ],
+        )
+        if construction.injectionDecision != "ACCEPTED" or not construction.promotion:
+            raise AssertionError("shipped normative construction refused P5 fixture")
+        binding = {
+            "compaction_epoch": index,
+            "request_epoch": index + 100,
+            "h_source": construction.h_source,
+            "h_payload": construction.h_payload,
+            "schema_version": 1,
+        }
+        construction_request = {
+            "manifest_version": 1,
+            "generator_version": "p5-replay-probe",
+            "fragments": [{
+                "source_id": "authority/probe",
+                "content_base64": base64.b64encode(b"P5 shipped transition driver\n").decode("ascii"),
+                "expected_sha256": "63537df1a6cb0d80195a96757ab11d629e5b5e1f23be167218b84cb195b1c1d6",
+            }],
+        }
+        pending = request(socket_path, {
+            "action": "begin_verification",
+            "session_id": session_id,
+            "runtime_generation": 1,
+            "runtime": "pi",
+            "binding": binding,
+            "construction": construction_request,
+        })
+        if pending.get("ok") is not True or pending.get("state") != "PENDING_VERIFICATION":
+            raise AssertionError(f"shipped pending-delivery transition failed: {pending!r}")
+        challenge = pending.get("receipt_challenge")
+        receipt = pending.get("receipt")
+        if not isinstance(challenge, str) or not isinstance(receipt, str):
+            raise AssertionError(f"shipped broker did not mint a receipt challenge: {pending!r}")
+
+        # Promotion before observation/evidence/consumption is forbidden.
+        expect_refused(request(socket_path, {
+            "action": "promote_lease",
+            "session_id": session_id,
+            "runtime_generation": 1,
+            "receipt_challenge": challenge,
+        }), "INVALID_LEASE_TRANSITION")
+
+        observer_path.write_text(json.dumps({
+            "session_id": session_id,
+            "runtime_generation": 1,
+            "latest_assistant_message": receipt,
+        }), encoding="utf-8")
+        os.chmod(observer_path, 0o600)
+        observed = request(socket_path, {
+            "action": "observe_receipt",
+            "session_id": session_id,
+            "runtime_generation": 1,
+            "receipt_challenge": challenge,
+        })
+        if observed.get("ok") is not True or observed.get("state") != "PENDING_PROMOTION":
+            raise AssertionError(f"shipped evidence transition failed: {observed!r}")
+        durable = json.loads(state_path.read_text(encoding="utf-8"))
+        evidence = durable["tokens"][challenge].get("evidence")
+        if not isinstance(evidence, dict) or not isinstance(evidence.get("h_latest_assistant"), str):
+            raise AssertionError("shipped receipt evidence was not committed before consume/promote")
+
+        promoted = request(socket_path, {
+            "action": "promote_lease",
+            "session_id": session_id,
+            "runtime_generation": 1,
+            "receipt_challenge": challenge,
+        })
+        if promoted.get("ok") is not True or promoted.get("state") != "VERIFIED":
+            raise AssertionError(f"shipped consume-before-promote transition failed: {promoted!r}")
+
+        # T25/T28: the actual consumed challenge, re-presented through the
+        # shipped daemon, can neither be observed again nor re-promote/reopen.
+        expect_refused(request(socket_path, {
+            "action": "observe_receipt",
+            "session_id": session_id,
+            "runtime_generation": 1,
+            "receipt_challenge": challenge,
+        }), "RECEIPT_REPLAY")
+        expect_refused(request(socket_path, {
+            "action": "promote_lease",
+            "session_id": session_id,
+            "runtime_generation": 1,
+            "receipt_challenge": challenge,
+        }), "RECEIPT_REPLAY")
+        return challenge
+    finally:
+        if process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=3.0)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--runs", type=int, default=3)
+    arguments = parser.parse_args()
+    if arguments.runs != 3:
+        raise SystemExit("P5 requires exactly three isolated runs")
+    challenges = [run_once(index) for index in range(arguments.runs)]
+    if len(set(challenges)) != arguments.runs:
+        raise AssertionError("separate shipped cycles did not mint unique challenges")
+    print("P5 receipt replay probe PASS: 3 isolated shipped-daemon runs")
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p6_constrained_recovery.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""P6 constrained-recovery probe; BUILT ONLY and Mos-gated.
+
+DO NOT self-fire. Under Mos authorization only:
+  python3 -I -S -B docs/compaction-refresh/probes/p6_constrained_recovery.py
+
+The default three isolated runs launch the shipped daemon plus its production
+observer transport on private sockets. The driver invokes the shipped recovery
+command and adapter gate identity; it never resets broker state, mocks promote,
+or taps a live model-output stream.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import importlib.util
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+HERE = Path(__file__).resolve().parent
+REPOSITORY = HERE.parents[2]
+TOOLS = REPOSITORY / "packages/mosaic/framework/tools/lease-broker"
+DAEMON = TOOLS / "daemon.py"
+GATE = TOOLS / "mutator-gate.py"
+RECOVERY_COMMAND = TOOLS / "recover-context.py"
+OBSERVER_CLIENT = TOOLS / "receipt-observer-client.py"
+FRAGMENTS = TOOLS / "normative_fragments.py"
+CLAUDE_SETTINGS = REPOSITORY / "packages/mosaic/framework/runtime/claude/settings.json"
+PI_EXTENSION = REPOSITORY / "packages/mosaic/framework/runtime/pi/mosaic-extension.ts"
+
+
+def load_shipped_fragments():
+    spec = importlib.util.spec_from_file_location("p6_shipped_fragments", FRAGMENTS)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("shipped normative construction unavailable")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def request(socket_path: Path, value: dict[str, object]) -> dict[str, object]:
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
+        connection.settimeout(3.0)
+        connection.connect(str(socket_path))
+        connection.sendall((json.dumps(value, separators=(",", ":")) + "\n").encode())
+        connection.shutdown(socket.SHUT_WR)
+        response = bytearray()
+        while True:
+            chunk = connection.recv(4096)
+            if not chunk:
+                break
+            response.extend(chunk)
+    if not response.endswith(b"\n") or response.count(b"\n") != 1:
+        raise AssertionError(f"unframed broker reply: {bytes(response)!r}")
+    reply = json.loads(response[:-1])
+    if not isinstance(reply, dict):
+        raise AssertionError("broker reply is not an object")
+    return reply
+
+
+def wait_ready(process: subprocess.Popen[str], socket_path: Path) -> None:
+    deadline = time.monotonic() + 5.0
+    while time.monotonic() < deadline:
+        if socket_path.exists():
+            return
+        if process.poll() is not None:
+            output = process.stdout.read() if process.stdout is not None else ""
+            raise RuntimeError(f"shipped daemon exited before READY: {output}")
+        time.sleep(0.02)
+    raise TimeoutError("shipped daemon did not create private probe socket")
+
+
+def run_json(command: list[str], environment: dict[str, str], input_value: object | None = None) -> dict[str, object]:
+    completed = subprocess.run(
+        command,
+        input=None if input_value is None else json.dumps(input_value),
+        text=True,
+        capture_output=True,
+        env=environment,
+        check=False,
+    )
+    if not completed.stdout.endswith("\n"):
+        raise AssertionError(f"command omitted framed result: {completed.stderr!r}")
+    reply = json.loads(completed.stdout)
+    if not isinstance(reply, dict):
+        raise AssertionError("command result is not an object")
+    return reply
+
+
+def gate_recovery(runtime: str, phase: str, environment: dict[str, str]) -> None:
+    command = [sys.executable, "-I", "-S", "-B", str(GATE), "--runtime", runtime]
+    if runtime == "claude":
+        command.extend(["--recovery-command", str(RECOVERY_COMMAND)])
+        recovery_invocation = (
+            f"python3 {RECOVERY_COMMAND} begin --construction /tmp/p6.json "
+            "--compaction-epoch 1 --request-epoch 1"
+            if phase == "begin"
+            else f"python3 {RECOVERY_COMMAND} complete"
+        )
+        value = {"tool_name": "Bash", "tool_input": {"command": recovery_invocation}}
+    else:
+        value = {"tool_name": "mosaic_context_recover"}
+    completed = subprocess.run(command, input=json.dumps(value), text=True, capture_output=True, env=environment, check=False)
+    if completed.returncode != 0:
+        raise AssertionError(f"{runtime} recovery invocation remained gated: {completed.stderr!r}")
+
+
+def record_production_observation(runtime: str, message: str, root: Path, environment: dict[str, str]) -> None:
+    command = [sys.executable, "-I", "-S", "-B", str(OBSERVER_CLIENT), "--runtime", runtime]
+    if runtime == "claude":
+        transcript = root / "claude-transcript.jsonl"
+        transcript.write_text(json.dumps({"message": {"role": "assistant", "content": message}}) + "\n", encoding="utf-8")
+        payload = {"transcript_path": str(transcript)}
+        command.append("--latest-entry")
+    else:
+        payload = {"latest_assistant_message": message}
+    completed = subprocess.run(command, input=json.dumps(payload), text=True, capture_output=True, env=environment, check=False)
+    if completed.returncode != 0:
+        raise AssertionError(f"{runtime} production observer transport refused: {completed.stderr!r}")
+
+
+def run_once(index: int, runtime: str) -> None:
+    # Parity guard: drive the shipped command and the repaired adapter/observer
+    # bytes, not a shadow receipt or promotion implementation.
+    recovery_source = RECOVERY_COMMAND.read_text(encoding="utf-8")
+    if '"action": "begin_recovery"' not in recovery_source or '"action": "complete_recovery"' not in recovery_source:
+        raise AssertionError("P6 parity guard: recovery command no longer drives shipped broker entrypoints")
+    gate_source = GATE.read_text(encoding="utf-8")
+    if "--recovery-command" not in CLAUDE_SETTINGS.read_text(encoding="utf-8"):
+        raise AssertionError("P6 parity guard: Claude recovery mapping is missing")
+    if "_SHELL_ACTIVE" not in gate_source or "argv[1] != str(recovery_command)" not in gate_source:
+        raise AssertionError("P6 parity guard: Claude mapping is not literal-only")
+    if "const RECOVERY_TOOL = 'mosaic_context_recover'" not in PI_EXTENSION.read_text(encoding="utf-8"):
+        raise AssertionError("P6 parity guard: Pi recovery tool mapping is missing")
+
+    fragments = load_shipped_fragments()
+    root = Path(tempfile.mkdtemp(prefix=f"mosaic-p6-recovery-{index}-"))
+    os.chmod(root, 0o700)
+    socket_path = root / "broker.sock"
+    observer_socket = root / "observer.sock"
+    state_path = root / "state.json"
+    construction_path = root / "construction.json"
+    content = b"P6 constrained recovery fixture\n"
+    construction = {
+        "manifest_version": 1,
+        "generator_version": "p6-constrained-recovery",
+        "fragments": [{
+            "source_id": "authority/p6",
+            "content_base64": base64.b64encode(content).decode("ascii"),
+            "expected_sha256": hashlib.sha256(content).hexdigest(),
+        }],
+    }
+    construction_path.write_text(json.dumps(construction), encoding="utf-8")
+    os.chmod(construction_path, 0o600)
+    process = subprocess.Popen(
+        [sys.executable, "-I", "-S", "-B", str(DAEMON), "--socket", str(socket_path),
+         "--state", str(state_path), "--observer-socket", str(observer_socket)],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+    try:
+        wait_ready(process, socket_path)
+        registered = request(socket_path, {"action": "register_anchor", "runtime_generation": 1})
+        session_id = registered.get("session_id")
+        if registered.get("ok") is not True or not isinstance(session_id, str):
+            raise AssertionError(f"broker anchor registration failed: {registered!r}")
+        built = fragments.build_payload_from_wire(construction)
+        normal = request(socket_path, {
+            "action": "begin_verification", "session_id": session_id, "runtime_generation": 1,
+            "runtime": runtime, "construction": construction,
+            "binding": {"compaction_epoch": index, "request_epoch": index + 100,
+                        "h_source": built.h_source, "h_payload": built.h_payload, "schema_version": 1},
+        })
+        normal_challenge = normal.get("receipt_challenge")
+        normal_receipt = normal.get("receipt")
+        if not isinstance(normal_challenge, str) or not isinstance(normal_receipt, str):
+            raise AssertionError("normal path did not mint a receipt challenge")
+        environment = {
+            **os.environ,
+            "MOSAIC_LEASE_BROKER_SOCKET": str(socket_path),
+            "MOSAIC_RECEIPT_OBSERVER_SOCKET": str(observer_socket),
+            "MOSAIC_LEASE_SESSION_ID": session_id,
+            "MOSAIC_RUNTIME_GENERATION": "1",
+            "MOSAIC_LEASE_RUNTIME": runtime,
+        }
+        gate_recovery(runtime, "begin", environment)
+        recovery = run_json([
+            sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "begin", "--construction", str(construction_path),
+            "--compaction-epoch", str(index + 10), "--request-epoch", str(index + 110),
+        ], environment)
+        challenge = recovery.get("receipt_challenge")
+        receipt = recovery.get("receipt")
+        if recovery.get("state") != "PENDING_DELIVERY" or not isinstance(challenge, str) or not isinstance(receipt, str):
+            raise AssertionError(f"recovery command did not drive pending delivery: {recovery!r}")
+        if challenge == normal_challenge:
+            raise AssertionError("recovery reused a normal-path challenge")
+
+        # C4: production observer content is still exact-current-cycle only.
+        record_production_observation(runtime, normal_receipt, root, environment)
+        refused = run_json([sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "complete"], environment)
+        if refused.get("ok") is not False or refused.get("code") != "RECEIPT_MISMATCH":
+            raise AssertionError(f"normal-path receipt replay was not refused: {refused!r}")
+
+        gate_recovery(runtime, "begin", environment)
+        recovery = run_json([
+            sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "begin", "--construction", str(construction_path),
+            "--compaction-epoch", str(index + 20), "--request-epoch", str(index + 120),
+        ], environment)
+        receipt = recovery.get("receipt")
+        if recovery.get("state") != "PENDING_DELIVERY" or not isinstance(receipt, str):
+            raise AssertionError(f"fresh recovery retry did not pend: {recovery!r}")
+        record_production_observation(runtime, receipt, root, environment)
+        gate_recovery(runtime, "complete", environment)
+        promoted = run_json([sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "complete"], environment)
+        if promoted.get("ok") is not True or promoted.get("state") != "VERIFIED":
+            raise AssertionError(f"recovery consume-before-promote failed: {promoted!r}")
+        replay = run_json([sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "complete"], environment)
+        if replay.get("ok") is not False or replay.get("code") != "INVALID_LEASE_TRANSITION":
+            raise AssertionError(f"consumed recovery challenge re-promoted: {replay!r}")
+    finally:
+        if process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=3.0)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--runs", type=int, default=3)
+    arguments = parser.parse_args()
+    if arguments.runs != 3:
+        raise SystemExit("P6 requires exactly three isolated runs")
+    for index, runtime in enumerate(("pi", "claude", "pi")):
+        run_once(index, runtime)
+    print("P6 constrained recovery probe PASS: 3 isolated shipped recovery-command runs")
+
+
+if __name__ == "__main__":
+    main()

docs/design/prerelease-next-dist-tag-pipeline.md

@@ -0,0 +1,63 @@
+# npm `@next` prerelease lane
+
+Status: **IMPLEMENTED**
+
+## Current behavior
+
+`tools/install.sh --next` provides the prerelease integration lane for the permanent `next` branch.
+
+The lane is fast-by-default:
+
+1. Install framework files from the `next` source archive.
+2. Resolve the Gitea npm registry `next` dist-tag for the globally installed packages:
+
+   ```bash
+   npm view @mosaicstack/gateway@next version
+   npm view @mosaicstack/mosaic@next version
+   ```
+
+3. Require both resolved versions to share the same `next.<pipeline>` suffix, then install the exact resolved versions.
+4. If either `@next` package is missing, unreachable, mismatched, or fails to install, fall back to the source-build path at `next`.
+
+`--next` never hard-fails solely because the prerelease npm dist-tag is unavailable.
+
+## Published packages
+
+The `next` publish pipeline publishes non-private `@mosaicstack/*` packages to the Mosaic Gitea npm registry:
+
+```text
+https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
+```
+
+Observed `next` dist-tags after enabling the pipeline:
+
+```text
+@mosaicstack/mosaic@next  -> 0.0.49-next.1633
+@mosaicstack/gateway@next -> 0.0.7-next.1633
+```
+
+The gateway also publishes a Docker image as `gateway:sha-<short>` on `next` merges. The installer fast path uses the npm gateway package when available; the Docker image is for deployed gateway/runtime harness flows.
+
+## Explicit source lanes
+
+Source builds remain available and are still the authority for explicit ref validation:
+
+- `--dev` always builds from source.
+- `--ref <ref>` / `MOSAIC_REF=<ref>` wins over `--next` and uses the source path for that exact ref.
+
+## Pipeline shape
+
+1. Trigger on `next` merges.
+2. Compute the next prerelease version from the upcoming stable version plus the Woodpecker pipeline number (`<target-stable>-next.<CI_PIPELINE_NUMBER>`).
+3. Build and publish non-private packages in CI.
+4. Publish to the Mosaic Gitea npm registry with dist-tag `next`.
+5. Keep `latest` untouched; only main/release promotion can update `latest`.
+6. Publish gateway Docker images from `next` as `gateway:sha-<short>` only.
+
+## Guardrails
+
+- `@next` is mutable prerelease convenience, not a deployment pin.
+- Stable installs continue to use `@latest`.
+- Contributor validation remains available through `--dev --ref <branch>`.
+- Pipeline output traces every prerelease package back to the source commit on `next`.
+- The installer falls back to source rather than hard-failing on prerelease registry issues.

docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md

@@ -5,28 +5,17 @@
 This checklist is an acceptance contract for documentation and examples. It does not authorize
 schema, runtime, systemd, role, profile, or live-fleet changes. An item is complete only when its
 named artifact exists, is linked from the fleet documentation entry point, and its evidence is
-recorded in the M0 task/PR.
+recorded in the M5 closure report and linked deferral evidence.
 
 ## M0 baseline acceptance
 
-- [ ] `docs/PRD.md` states the roster as desired-state SSOT; generated environment, systemd,
-      tmux, and heartbeat artifacts as non-authoritative projections; and fail-closed handling of
-      unsupported or quarantined legacy input.
-- [ ] `docs/PRD.md` defines the required classes and authority boundary: `validator` certifies but
-      does not merge; `merge-gate` remains sole approve-to-land/merge authority; `team-leader`
-      capacity is lease-bounded; `interaction` is request/status only; instance names such as Tess
-      and Ultron remain configurable.
-- [ ] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and
-      observed state, including stopped-state preservation through migration, apply, and reboot.
-- [ ] `docs/PRD.md` defines the generated-env/local-override boundary, explicitly denies arbitrary
-      command overrides in M1–M5, and requires key-name/hash-only quarantine diagnostics.
-- [ ] `docs/PRD.md` identifies the M1–M5 local-tmux scope and excludes remote reconciliation,
-      connector mutation, secret references, arbitrary commands/channels, gateway convergence, and
-      UI configuration storage.
-- [ ] `docs/TASKS.md` contains the complete M0–M5 one-card/one-PR dependency DAG for #758 with
-      agent tier, branch, dependency, estimate, and evidence expectations.
-- [ ] `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` classifies every current shipped
-      fleet example, profile, and service preset before M1 implementation starts.
+- [x] `docs/PRD.md` states the roster as desired-state SSOT; generated environment, systemd, tmux, and heartbeat artifacts as non-authoritative projections; and fail-closed handling of unsupported or quarantined legacy input.
+- [x] `docs/PRD.md` defines the required classes and authority boundary: `validator` certifies but does not merge; `merge-gate` remains sole approve-to-land/merge authority; `team-leader` capacity is lease-bounded; `interaction` is request/status only; instance names such as Tess and Ultron remain configurable.
+- [x] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and observed state, including stopped-state preservation through migration, apply, and reboot.
+- [x] `docs/PRD.md` defines the generated-env/local-override boundary, explicitly denies arbitrary command overrides in M1–M5, and requires key-name/hash-only quarantine diagnostics.
+- [x] `docs/PRD.md` identifies the M1–M5 local-tmux scope and excludes remote reconciliation, connector mutation, secret references, arbitrary commands/channels, gateway convergence, and UI configuration storage.
+- [x] `docs/TASKS.md` contains the complete M0–M5 one-card/one-PR dependency DAG for #758 with agent tier, branch, dependency, estimate, and evidence expectations.
+- [x] `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` classifies every current shipped fleet example, profile, and service preset before M1 implementation starts.
 
 ## Required documentation IA for M1–M5
 
@@ -72,15 +61,18 @@ recorded in the M0 task/PR.
 
 ## Cross-cutting evidence gates
 
-- [ ] Every retained or migrated YAML/JSON example, profile, and service preset validates through the
-      same executable schema and shared baseline-plus-`roles.local` resolver used by the CLI.
-- [ ] Every retired example/profile/service preset has a replacement link and deprecation note; no
-      unresolved legacy class or tool-policy alias remains silently shipped.
-- [ ] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded
-      Tess/Ultron identity.
-- [ ] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed
-      `mosaic agent` catalog.
-- [ ] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of
-      legacy sensitive keys are never printed.
-- [ ] M5 release review verifies links, schema/example validation, and that all checklist rows have
-      owner/evidence or an explicit approved deferral.
+- [x] Every retained or migrated YAML/JSON example, profile, and service preset validates through the same declared executable production parser/resolver path recorded by the disposition inventory; versioned v1 fixtures are not forced through the v2 compiler.
+- [x] Every retired example/profile/service preset has a replacement link and deprecation note; no unresolved legacy class or tool-policy alias remains silently shipped.
+- [x] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded Tess/Ultron identity.
+- [x] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed mosaic agent catalog.
+- [x] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of legacy sensitive keys are never printed.
+- [x] M5 documentation validation verifies required IA paths, local file and heading-fragment links, the canonical roster through the production compiler/resolver, and fenced/canonical-example safety checks.
+- [ ] FCM-M5-001 does not deterministically assert owner/evidence/deferral metadata for every checklist row. Closure and deferral reports provide human-reviewable evidence only; broader assertion coverage remains unclaimed.
+
+## Held downstream gates
+
+These unchecked items are intentionally outside FCM-M5-001 and are not authorized by this checklist:
+
+- [ ] FCM-M4-002 executes and evidences live cutover, canary, stopped-state preservation, and rollback.
+- [ ] FCM-M5-002 completes independent exact-head review and issues the validator certificate.
+- [ ] The exact PR head reaches terminal-green CI after independent review.

docs/fleet/FLEET-LAUNCH.md

@@ -8,11 +8,11 @@ Generated environment files are rebuildable projections, not an operator-editabl
 | Layer               | Responsibility                                                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
-| Projection writer   | Renders deterministic `fleet/agents/<name>.env.generated` from the roster.                                                      |
-| Optional local data | Reads a strict, data-only `fleet/agents/<name>.env.local`; it cannot shadow generated keys.                                     |
-| systemd             | Starts the launcher with `env -i` and fixed bootstrap data. It does not preload either environment file.                        |
+| Projection writer   | Renders deterministic fleet/agents/<name>.env.generated from the roster.                                                        |
+| Optional local data | Reads a strict, data-only fleet/agents/<name>.env.local; it cannot shadow generated keys.                                       |
+| systemd             | Starts the launcher with env -i and fixed bootstrap data. It does not preload either environment file.                          |
 | session launcher    | Validates generated and local data before it queries, creates, or stops an exact tmux session.                                  |
-| runtime launch      | Derives the fixed `mosaic yolo <runtime>` argument array from validated roster data, then seeds the runtime contract.           |
+| runtime launch      | Derives the fixed mosaic yolo <runtime> argument array from validated roster data, then seeds the runtime contract.             |
 
 The launcher never `source`s or `eval`s an environment file and never accepts an environment-supplied
 command. `MOSAIC_AGENT_COMMAND`, command/channel overrides, unknown keys, generated-key shadowing,
@@ -20,7 +20,7 @@ secret-like key names, duplicate keys, comments, quoted/export syntax, and unsaf
 
 ## Generated and local files
 
-`<name>.env.generated` is complete, deterministic, and written only by Mosaic. Its ordered keys are:
+<name>.env.generated is complete, deterministic, and written only by Mosaic. Its ordered keys are:
 
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
@@ -33,12 +33,12 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
 
-The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. `mosaic fleet add`
+The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. mosaic fleet add
 rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
 The legacy dogfood stub remains an observability-only canary on its separate `mosaic-factory` socket;
 it has no generated-launch adapter and cannot be added through this path.
 
-`<name>.env.local` is optional and may contain only non-secret machine data:
+<name>.env.local is optional and may contain only non-secret machine data:
 
 - `MOSAIC_RUNTIME_BIN`
 - `MOSAIC_HEARTBEAT_RUN_DIR`
@@ -52,9 +52,9 @@ private, non-symlink paths. Violations fail closed before tmux interaction.
 
 ## Legacy input and diagnostics
 
-A legacy `<name>.env` is input only during projection generation. Roster-owned keys are regenerated;
+A legacy <name>.env is input only during projection generation. Roster-owned keys are regenerated;
 valid allowed local data can move to `.env.local`; invalid legacy input is privately retained at
-`<name>.env.quarantine`. Neither legacy nor quarantine files are launch authority.
+<name>.env.quarantine. Neither legacy nor quarantine files are launch authority.
 
 Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command
 text, credentials, or other values.
@@ -62,11 +62,11 @@ text, credentials, or other values.
 ## Launch and stop behavior
 
 The launcher obtains the agent's socket only from the validated generated projection. It creates or
-checks the exact `=<agent-name>` tmux target; it never uses an ambient socket or fuzzy session match.
+checks the exact =<agent-name> tmux target; it never uses an ambient socket or fuzzy session match.
 The same strict parser runs before exact-stop behavior. A fresh native Pi heartbeat remains authoritative;
 the shell sidecar only provides fallback state when the native marker is stale or absent.
 
-`mosaic agent comms-block <exact-member>` can inspect that exact roster member's resolved Fleet-Comms
+mosaic agent comms-block <exact-member> can inspect that exact roster member's resolved Fleet-Comms
 block. It is a read-only inspection tool and fails loudly for an unknown exact member or missing roster.
 On Linux, the installed roster, TOOLS contract, and executable helper are opened through a held
 descriptor chain rooted at `/`; every managed path component uses no-follow traversal, and content plus

docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md

@@ -14,7 +14,7 @@ parallel resolver. The current executable implementation and per-artifact outcom
 
 | Shipped file                                         | Current class evidence                                              | M0 disposition decision                                                                              | Required M1/M4 evidence                                              |
 | ---------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `framework/fleet/examples/coding.yaml`               | `orchestrator`, `enhancer`, `implementer`, `reviewer`               | Migrate: `implementer → code`, `reviewer → review`; retain orchestration/enhancer intent             | v2 fixture validates; role aliases and authority matrix tested       |
+| `framework/fleet/examples/coding.yaml`               | `orchestrator`, `enhancer`, `implementer`, `reviewer`               | Migrate: implementer → code, reviewer → review; retain orchestration/enhancer intent                 | v2 fixture validates; role aliases and authority matrix tested       |
 | `framework/fleet/examples/general.yaml`              | `orchestrator`, `enhancer`, `worker`                                | Migrate only after operator chooses a concrete canonical role for `worker`; no implicit conversion   | Explicit replacement class, or versioned v1 fixture/retirement note  |
 | `framework/fleet/examples/hybrid.yaml`               | `orchestrator`, `enhancer`, `implementer`, `researcher`, `reviewer` | Migrate aliases; resolve `researcher` through existing role resolver or retain/version               | Shared resolver validation; no ad-hoc class scanner                  |
 | `framework/fleet/examples/local-canary.yaml`         | `orchestrator`, `implementer`, `reviewer`                           | Migrate aliases; preserve its local-tmux canary purpose                                              | v2 fixture validates and preserves safe stopped/running behavior     |
@@ -34,14 +34,14 @@ parallel resolver. The current executable implementation and per-artifact outcom
 
 ## Service presets
 
-| Shipped file                                         | Current policy evidence                                                                                                                                               | M0 disposition decision                                                                                                                                                                                                              | Required M1/M4 evidence                                                                                                                                                               |
-| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `framework/fleet/services/operator-interaction.yaml` | Generic policy only: `runtime: pi`, `model: openai/gpt-5.6-sol`, `reasoning: high`, `tool_policy: operator-interaction`; provisioning supplies the agent name as data | Retain as a generic service policy, not a Tess identity. Migrate `tool_policy: operator-interaction` only through the approved interaction tool-policy alias/semantic resolver; do not infer a class or machine name from this file. | Service-policy fixture validates runtime/model/reasoning and alias behavior; generic provisioning proves a configured interaction instance is supplied without a hardcoded Tess name. |
+| Shipped file                                         | Current policy evidence                                                                                                                                       | M0 disposition decision                                                                                                                                                                                                            | Required M1/M4 evidence                                                                                                                                                               |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `framework/fleet/services/operator-interaction.yaml` | Generic policy only: runtime: pi, model: openai/gpt-5.6-sol, reasoning: high, tool_policy: operator-interaction; provisioning supplies the agent name as data | Retain as a generic service policy, not a Tess identity. Migrate tool_policy: operator-interaction only through the approved interaction tool-policy alias/semantic resolver; do not infer a class or machine name from this file. | Service-policy fixture validates runtime/model/reasoning and alias behavior; generic provisioning proves a configured interaction instance is supplied without a hardcoded Tess name. |
 
 ## Required disposition controls
 
-1. **No silent aliasing:** only `implementer → code`, `reviewer → review`, and
-   `operator-interaction → interaction` are approved deterministic aliases in this M0 baseline.
+1. **No silent aliasing:** only implementer → code, reviewer → review, and
+   operator-interaction → interaction are approved deterministic aliases in this M0 baseline.
    `worker`, `analyst`, `canary`, and domain-specific classes require resolver evidence or an
    explicit version/retirement decision.
 2. **No identity hardcoding:** Tess and Ultron are optional instance/display names. An example/profile

docs/fleet/NORTH_STAR.md

@@ -33,7 +33,7 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
 - **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
 - **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
 - **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
-- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives `mosaic update`: baseline reseed never clobbers user overrides.
+- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives mosaic update: baseline reseed never clobbers user overrides.
 
 ## Workstreams
 

docs/fleet/NORTH_STAR.yaml

@@ -97,7 +97,7 @@ success_criteria:
   - id: AC-NS-7
     text: >-
       A user-customized persona (edited or added via the orchestrator) survives
-      `mosaic update`: baseline reseed never clobbers user overrides.
+      mosaic update: baseline reseed never clobbers user overrides.
 
 workstreams:
   - id: A

docs/fleet/PRD-fleet-suite.md

@@ -8,7 +8,7 @@
 ## Mission
 
 Turn the proven fleet primitives into a **user-installable, AI-free-configurable fleet product**:
-a user runs `mosaic fleet init`, answers a few questions (general / coding / research / hybrid),
+a user runs mosaic fleet init, answers a few questions (general / coding / research / hybrid),
 gets a recommended set of agents plus one always-on orchestrator wired for chat-ops, and can
 operate, mutate, re-create, and observe the fleet — over tmux today and Matrix tomorrow — from
 CLI/TUI and (designed-for) the webUI.
@@ -21,25 +21,25 @@ functional, we use the fleet itself to continue the work.
 
 ### A. Configure-without-AI CLI
 
-| ID  | Requirement                                                                                                   |
-| --- | ------------------------------------------------------------------------------------------------------------- |
-| R1  | `mosaic fleet` command set is functional end-to-end (init/install/start/stop/status/ps/verify + agent verbs). |
-| R2  | `mosaic fleet init` is an interactive, **AI-free** CLI wizard.                                                |
-| R3  | Init asks the **configuration type**: `general`, `coding`, `research`, `hybrid`, … (extensible).              |
-| R4  | Based on the answer, the fleet is populated with a **recommended set of agents** (a preset).                  |
-| R5  | **Exactly one main orchestrator agent** is always configured, regardless of type.                             |
-| R10 | A set of **recommended configurations (presets)** ships for easy duplication.                                 |
-| R8  | User can **re-create** the fleet when config needs change (idempotent re-init / reconfigure).                 |
-| R17 | Fleet controls are **simple and intuitive**.                                                                  |
+| ID  | Requirement                                                                                                 |
+| --- | ----------------------------------------------------------------------------------------------------------- |
+| R1  | mosaic fleet command set is functional end-to-end (init/install/start/stop/status/ps/verify + agent verbs). |
+| R2  | mosaic fleet init is an interactive, **AI-free** CLI wizard.                                                |
+| R3  | Init asks the **configuration type**: `general`, `coding`, `research`, `hybrid`, … (extensible).            |
+| R4  | Based on the answer, the fleet is populated with a **recommended set of agents** (a preset).                |
+| R5  | **Exactly one main orchestrator agent** is always configured, regardless of type.                           |
+| R10 | A set of **recommended configurations (presets)** ships for easy duplication.                               |
+| R8  | User can **re-create** the fleet when config needs change (idempotent re-init / reconfigure).               |
+| R17 | Fleet controls are **simple and intuitive**.                                                                |
 
 ### B. Comms & orchestrator chat-ops
 
-| ID  | Requirement                                                                                                                       |
-| --- | --------------------------------------------------------------------------------------------------------------------------------- |
-| R6  | Init can wire the orchestrator to a chat connector — **Telegram / Discord / Matrix / Slack** — for command + comms.               |
-| R7  | Designed with the end-goal of **Matrix comms on a locally-controlled server**.                                                    |
-| R16 | Fleet supports **tmux AND Matrix** comms, **user-configurable** at init or any time. Not all users want Matrix.                   |
-| R19 | **"Mos" orchestrator on Discord** (`chan 1517622518662434996` / `srv 1112631390438166618`) on `w-jarvis` — the first live target. |
+| ID  | Requirement                                                                                                                   |
+| --- | ----------------------------------------------------------------------------------------------------------------------------- |
+| R6  | Init can wire the orchestrator to a chat connector — **Telegram / Discord / Matrix / Slack** — for command + comms.           |
+| R7  | Designed with the end-goal of **Matrix comms on a locally-controlled server**.                                                |
+| R16 | Fleet supports **tmux AND Matrix** comms, **user-configurable** at init or any time. Not all users want Matrix.               |
+| R19 | **"Mos" orchestrator on Discord** (chan 1517622518662434996 / srv 1112631390438166618) on `w-jarvis` — the first live target. |
 
 ### C. Runtime, health, lifecycle
 
@@ -64,46 +64,46 @@ functional, we use the fleet itself to continue the work.
 - **Orchestrator agent:** always present; carries the chat connector config (connector type + target IDs) so it can be commanded over chat. tmux is the substrate; the connector bridges chat ↔ the orchestrator session.
 - **Comms layers (R16):** (1) **tmux** inter-agent (`agent-send`, proven) — default, always available. (2) **chat connector** for human↔orchestrator (Discord now; Matrix the strategic target). (3) **Matrix** as the locally-controlled cross-agent bus (future). Connector is pluggable + reconfigurable.
 - **Heartbeat (R15):** runtime-agnostic launcher sidecar already covers pi/claude/codex (#584). Refine per-runtime (native HB) with the **custom Pi harness** (R14) + a Claude path.
-- **Updates (R13):** `mosaic update` (CLI) + a fleet-aware harness-update step that refreshes pi/claude/codex and re-launches agents safely (drain → update → relaunch via the durable launcher).
-- **webUI (R18):** the fleet exposes machine-readable state (`fleet ps --json` already carries tenant/host/heartbeat/managed) + control verbs (start/stop/watch/send); webUI consumes these (control plane rides federation per north star). Ensure a stable JSON contract + a terminate/attach(butt-in) path.
+- **Updates (R13):** mosaic update (CLI) + a fleet-aware harness-update step that refreshes pi/claude/codex and re-launches agents safely (drain → update → relaunch via the durable launcher).
+- **webUI (R18):** the fleet exposes machine-readable state (fleet ps --json already carries tenant/host/heartbeat/managed) + control verbs (start/stop/watch/send); webUI consumes these (control plane rides federation per north star). Ensure a stable JSON contract + a terminate/attach(butt-in) path.
 
 ## Phases (incremental, each shippable)
 
-| Phase                             | Deliverable                                                                                                                         | Notes                                 |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| **F1 Presets + init wizard**      | preset rosters (general/coding/research/hybrid) + always-orchestrator + AI-free `fleet init` selecting a preset; re-init idempotent | R1–R5, R8, R10, R17                   |
-| **F2 Connector + Mos-on-Discord** | orchestrator chat-connector config (Discord first) + **Mos live on Discord `1517…`/`1112…`** on w-jarvis                            | R6, R19, partial R16                  |
-| **F3 Heartbeat + harness**        | HB confirmed for claude + pi/gpt; **custom Pi harness** (tool usage, native HB, model self-report); graceful harness updates        | R13, R14, R15                         |
-| **F4 Matrix + comms toggle**      | Matrix connector (local server) + user toggle tmux/Matrix at init/anytime                                                           | R7, R16                               |
-| **F5 Orchestrator-mutable fleet** | orchestrator can add/remove agents at runtime                                                                                       | R9                                    |
-| **F6 webUI hooks**                | stable JSON contract + terminate/attach surface for webUI view/monitor/terminate/butt-in                                            | R18                                   |
-| **F7 Test + docs**                | install+test on w-jarvis AND dragon-lin; user docs (install/configure/use)                                                          | R11, R12 (runs alongside every phase) |
+| Phase                             | Deliverable                                                                                                                       | Notes                                 |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| **F1 Presets + init wizard**      | preset rosters (general/coding/research/hybrid) + always-orchestrator + AI-free fleet init selecting a preset; re-init idempotent | R1–R5, R8, R10, R17                   |
+| **F2 Connector + Mos-on-Discord** | orchestrator chat-connector config (Discord first) + **Mos live on Discord 1517…/1112…** on w-jarvis                              | R6, R19, partial R16                  |
+| **F3 Heartbeat + harness**        | HB confirmed for claude + pi/gpt; **custom Pi harness** (tool usage, native HB, model self-report); graceful harness updates      | R13, R14, R15                         |
+| **F4 Matrix + comms toggle**      | Matrix connector (local server) + user toggle tmux/Matrix at init/anytime                                                         | R7, R16                               |
+| **F5 Orchestrator-mutable fleet** | orchestrator can add/remove agents at runtime                                                                                     | R9                                    |
+| **F6 webUI hooks**                | stable JSON contract + terminate/attach surface for webUI view/monitor/terminate/butt-in                                          | R18                                   |
+| **F7 Test + docs**                | install+test on w-jarvis AND dragon-lin; user docs (install/configure/use)                                                        | R11, R12 (runs alongside every phase) |
 
 ## Work division (proposed — confirm with dragon-lin)
 
 - **Jarvis @ w-jarvis (Lead):** F1 presets+wizard, F2 connector+Mos-on-Discord, F5 mutability, F6 webUI hooks; merge authority + dual-engine reviews; co-testing on w-jarvis.
-- **coder @ dragon-lin:** F3 custom Pi harness + harness-update flow (pi/codex-savvy); plus its in-flight constitution P4–P6 (P4 installer rework underpins `fleet init`/updates — coordinate the install path). Co-testing on dragon-lin (R11).
+- **coder @ dragon-lin:** F3 custom Pi harness + harness-update flow (pi/codex-savvy); plus its in-flight constitution P4–P6 (P4 installer rework underpins fleet init/updates — coordinate the install path). Co-testing on dragon-lin (R11).
 - **Shared:** F4 Matrix (whoever has bandwidth); F7 testing/docs continuous.
 
 ## Immediate target: Mos on Discord (F2 first slice)
 
-The discord plugin is available (`~/.claude.json`). Path: configure the **orchestrator** as a durable
+The discord plugin is available (~/.claude.json). Path: configure the **orchestrator** as a durable
 fleet session running Claude Code with the discord plugin bridged to channel `1517622518662434996`
 (server `1112631390438166618`) on w-jarvis, with the existing Discord Bridge Protocol (ack within
 ~3s, reply via `mcp__discord__reply`, no `AskUserQuestion`). Heartbeat via the launcher sidecar.
 
 ## Success criteria
 
-- A non-AI user can `mosaic fleet init`, pick a type, and get a working fleet + orchestrator.
-- **Mos answers in Discord `1517…`** on w-jarvis.
-- Fleet runs + is observable (`fleet ps`) on **both** w-jarvis and dragon-lin.
+- A non-AI user can mosaic fleet init, pick a type, and get a working fleet + orchestrator.
+- **Mos answers in Discord 1517…** on w-jarvis.
+- Fleet runs + is observable (fleet ps) on **both** w-jarvis and dragon-lin.
 - Harness updates handled gracefully; HB healthy for claude + pi/gpt agents.
 - Docs let a new operator install/configure/use the fleet.
 - Re-init + orchestrator mutation work.
 
 ## Assumptions (veto-able)
 
-- `ASSUMPTION:` presets ship as example rosters under the framework (`fleet/examples/*.yaml`), selected by `init`.
+- `ASSUMPTION:` presets ship as example rosters under the framework (fleet/examples/\*.yaml), selected by `init`.
 - `ASSUMPTION:` chat connectors are pluggable; Discord first (target exists), Matrix is the strategic default later.
 - `ASSUMPTION:` "Mos" = a Claude Code orchestrator session with the discord plugin (reuses the documented Discord Bridge Protocol).
 - `ASSUMPTION:` per north star, runtimes default to Codex/pi-on-Codex for workers; the orchestrator "Mos" runs Claude Code (in Claude Code, which is allowed).

docs/fleet/PRD.md

@@ -10,8 +10,8 @@
 The durable tmux fleet runs on the isolated `mosaic-fleet` socket. That isolation
 (which protects the operator's default tmux) makes the fleet **invisible** to default
 tooling, and truth is split across three planes no single command joins — systemd
-(`systemctl --user`), tmux (`-L mosaic-fleet`), and the process tree (`pstree`).
-`agent tail` (`capture-pane`) returns **blank for full-screen TUIs**, and `agent send`
+(systemctl --user), tmux (-L mosaic-fleet), and the process tree (`pstree`).
+agent tail (`capture-pane`) returns **blank for full-screen TUIs**, and agent send
 confirms only keystroke injection, not acceptance. Net: the operator has near-zero
 observability and no safe way to watch a session.
 
@@ -32,22 +32,22 @@ observability and no safe way to watch a session.
 
 ## Functional requirements
 
-| ID   | Requirement                                                                                                                                                                                                                                                                                                    |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR-1 | `mosaic fleet ps [--json]` prints one row per roster agent joining: name · tenant · host · runtime · systemd(active/enabled) · pane(alive/dead) · pid · idle · **last-heartbeat age** · **drift** flag (roster runtime ≠ actual pane command) · **boot-enable** warning (active but `UnitFileState=disabled`). |
-| FR-2 | **Heartbeat protocol v1** (see below); `dogfood-agent.py` implements the responder. `fleet ps` issues probes (or reads last-seen) and reports health per FR-1.                                                                                                                                                 |
-| FR-3 | `mosaic agent watch <name>` opens a **read-only** view of the pane (grouped session or `tmux attach -r`) that cannot send keystrokes and does not shrink the agent's window.                                                                                                                                   |
-| FR-4 | `mosaic agent attach <name>` remains the **explicit** interactive-takeover path (separate verb, documented as the only one that can type).                                                                                                                                                                     |
-| FR-5 | `mosaic agent send <name> --verify` confirms the message was **accepted** (not left as an unsubmitted draft) and returns non-zero if delivery cannot be verified.                                                                                                                                              |
-| FR-6 | All structured output (`--json`) includes `tenant_id` and `host` fields.                                                                                                                                                                                                                                       |
+| ID   | Requirement                                                                                                                                                                                                                                                                                                  |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| FR-1 | mosaic fleet ps [--json] prints one row per roster agent joining: name · tenant · host · runtime · systemd(active/enabled) · pane(alive/dead) · pid · idle · **last-heartbeat age** · **drift** flag (roster runtime ≠ actual pane command) · **boot-enable** warning (active but `UnitFileState=disabled`). |
+| FR-2 | **Heartbeat protocol v1** (see below); `dogfood-agent.py` implements the responder. fleet ps issues probes (or reads last-seen) and reports health per FR-1.                                                                                                                                                 |
+| FR-3 | mosaic agent watch <name> opens a **read-only** view of the pane (grouped session or tmux attach -r) that cannot send keystrokes and does not shrink the agent's window.                                                                                                                                     |
+| FR-4 | mosaic agent attach <name> remains the **explicit** interactive-takeover path (separate verb, documented as the only one that can type).                                                                                                                                                                     |
+| FR-5 | mosaic agent send <name> --verify confirms the message was **accepted** (not left as an unsubmitted draft) and returns non-zero if delivery cannot be verified.                                                                                                                                              |
+| FR-6 | All structured output (`--json`) includes `tenant_id` and `host` fields.                                                                                                                                                                                                                                     |
 
 ## Heartbeat protocol v1
 
-- **Probe:** operator/`fleet ps` writes a sentinel line to the agent's input or a
-  well-known per-agent heartbeat file path `~/.config/mosaic/fleet/run/<agent>.hb`.
-- **Response:** the runtime updates `<agent>.hb` with `ts=<iso8601> pid=<pid> status=<ok|busy>`
+- **Probe:** operator/fleet ps writes a sentinel line to the agent's input or a
+  well-known per-agent heartbeat file path ~/.config/mosaic/fleet/run/<agent>.hb.
+- **Response:** the runtime updates <agent>.hb with ts=<iso8601> pid=<pid> status=<ok|busy>
   on a fixed interval (default 15s) and on demand when probed.
-- **Health rule:** `healthy` if `now - ts <= 3 × interval`; else `stale`; missing file = `unknown`.
+- **Health rule:** `healthy` if now - ts <= 3 × interval; else `stale`; missing file = `unknown`.
 - **Contract:** every runtime (dogfood stub now; claude/codex/pi/opencode in Phase 3)
   MUST emit the heartbeat. The protocol is file-based so it works for headless stubs and
   full-screen TUIs alike (no `capture-pane` dependency).
@@ -56,15 +56,15 @@ observability and no safe way to watch a session.
 
 ## Acceptance criteria
 
-- `mosaic fleet ps` shows all 5 live sessions on `mosaic-fleet` with correct
+- mosaic fleet ps shows all 5 live sessions on `mosaic-fleet` with correct
   pane/pid/idle and flags the dogfood **drift** (`canary-pi` runtime=pi but pane runs
   `dogfood-agent.py`) and the **boot-enable** gap (active but disabled).
 - Killing one agent's pane flips its row to dead/stale within one `interval`.
-- `agent watch` shows live output and provably cannot type into the pane; detaching
+- agent watch shows live output and provably cannot type into the pane; detaching
   leaves the agent's window size unchanged.
-- `agent send --verify` returns success on an accepting pane and non-zero on a wedged/draft pane.
-- Quality gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, plus
-  `pnpm --filter @mosaicstack/mosaic test`.
+- agent send --verify returns success on an accepting pane and non-zero on a wedged/draft pane.
+- Quality gates green: pnpm typecheck, pnpm lint, pnpm format:check, plus
+  pnpm --filter @mosaicstack/mosaic test.
 - Independent review passed; dogfood evidence captured against the live fleet.
 
 ## Test plan
@@ -72,18 +72,18 @@ observability and no safe way to watch a session.
 - Unit/CLI specs in `packages/mosaic/src/commands/fleet.spec.ts` (and a new
   `fleet-ps`/`watch`/`send-verify` spec) using the injected `CommandRunner` to assert
   exact tmux/systemd command construction and JSON shape (tenant+host present).
-- Situational: run against the live `mosaic-fleet` fleet; capture `fleet ps` output,
-  a kill-and-detect cycle, a read-only `watch`, and a `send --verify` pass/fail pair.
+- Situational: run against the live `mosaic-fleet` fleet; capture fleet ps output,
+  a kill-and-detect cycle, a read-only `watch`, and a send --verify pass/fail pair.
 
 ## Known limitations
 
-- **Verify heuristic is best-effort:** `agent send --verify` uses a `>` -prefix draft
+- **Verify heuristic is best-effort:** agent send --verify uses a > -prefix draft
   heuristic that is specific to pi/claude TUIs. Draft detection for codex and opencode
   TUIs is best-effort only; those runtimes may not use the same input-line indicator.
 - **Pane-change check is the best Phase-2 signal; verify now polls up to a bounded
-  timeout:** `agent send --verify` captures a BEFORE snapshot, sends the message, then
+  timeout:** agent send --verify captures a BEFORE snapshot, sends the message, then
   polls `capture-pane` every ~400 ms up to a configurable total timeout (default ~6 s,
-  controlled by `--verify-timeout <ms>`). On each poll it runs classifySendResult: if
+  controlled by --verify-timeout <ms>). On each poll it runs classifySendResult: if
   the pane shows 'accepted' or 'draft' the loop exits immediately; while the result is
   'unverifiable' (no pane change yet) it keeps polling. After the timeout with no
   definitive result, it fails closed: exit 1 with "no pane change after send". This
@@ -92,15 +92,15 @@ observability and no safe way to watch a session.
   requires a runtime acknowledgement (Phase-3 heartbeat-ack); the bounded pane-change
   poll is the best signal available against an opaque TUI for Phase-2.
 - **Blank AFTER capture fails closed:** Full-screen TUIs (claude, codex, opencode, pi)
-  render blank for `tmux capture-pane`. When the AFTER snapshot is empty, `send --verify`
+  render blank for tmux capture-pane. When the AFTER snapshot is empty, send --verify
   returns non-zero with an "unverifiable" message rather than silently succeeding. This
   is an intentional fail-closed design (FR-5).
-- **`agent watch` uses a grouped viewer session:** `tmux attach -r` directly against the
-  agent session lets the viewer terminal shrink the agent's window. `agent watch` instead
-  creates a throwaway grouped session (`tmux new-session -d -t '=<agent>' -s
-'<agent>-watch-<pid>'`), attaches read-only to that session, and kills it on detach.
+- **agent watch uses a grouped viewer session:** tmux attach -r directly against the
+  agent session lets the viewer terminal shrink the agent's window. agent watch instead
+  creates a throwaway grouped session (tmux new-session -d -t '=<agent>' -s
+  '<agent>-watch-<pid>'), attaches read-only to that session, and kills it on detach.
   The grouped session shares the agent's windows but has independent sizing, so the
-  agent's window is never affected. `tmux attach` is still interactive and requires
+  agent's window is never affected. tmux attach is still interactive and requires
   inherited stdio; the `interactiveRunner` handles TTY passthrough.
 
 ## Surfaces & parity (MVP-X1)

docs/fleet/README.md

@@ -0,0 +1,63 @@
+# Fleet Configuration Management
+
+This book documents the local roster-v2 desired-state control plane delivered under issue #758. The normative requirements are the [FCM section of the repository PRD](../PRD.md#fleet-declarative-configuration-management-workstream-fcm-758), not the older fleet-suite or observability planning pages.
+
+## Authority boundary
+
+<MOSAIC_HOME>/fleet/roster.yaml is the sole writable desired-state authority for local fleet membership, launch policy, and persisted lifecycle. Generated environment files, systemd enablement, tmux sessions, heartbeat files, and status output are derived or observed. Rebuild projections from the roster; never edit them as desired state.
+
+This control plane is local tmux/systemd only. Remote/SSH entries and connectors are inventory, not reconciliation targets. Arbitrary commands, channels, secret references, gateway catalog convergence, and UI configuration storage are outside this workstream. `mos-comms` is temporary transport glue, not permanent fleet architecture.
+
+## Choose the right workflow
+
+1. **Need to inspect intent?** Read the roster and use mosaic fleet get; see [desired versus observed state](concepts/desired-vs-observed-state.md).
+2. **Need to inspect reality?** Use `status` or `doctor`; use `verify` for a strict non-zero drift/ownership gate. These commands do not repair anything.
+3. **Need to change membership or persisted policy?** Use generation-guarded `plan`, `create`, `update`, or `delete`; see [safe CRUD](how-to/create-update-delete-agent.md).
+4. **Need a one-time runtime action?** Use `start`, `stop`, or `restart`. These do not change persisted desired state.
+5. **Need convergence?** Review apply --dry-run, resolve blockers, then use `apply` with the same current generation; see [reconcile and recover](operations/reconcile-and-recover.md).
+6. **Need v1 migration evidence?** Use preview only. Cutover, canary, and rollback remain held for FCM-M4-002.
+7. **Need the gateway-backed agent catalog?** That is the separate mosaic agent surface, not local fleet desired state.
+
+## Concepts
+
+- [Desired versus observed state](concepts/desired-vs-observed-state.md)
+- [Identity, class, runtime, provider, and model](concepts/identity-class-runtime.md)
+- [Role authority and leases](concepts/role-authority-and-leases.md)
+- [Generated environment launch chain](concepts/generated-env-launch-chain.md)
+
+## Operator how-to
+
+- [Create, inspect, update, and delete](how-to/create-update-delete-agent.md)
+- [Start, stop, restart, and reconcile](how-to/start-stop-restart.md)
+- [Configure an interaction instance](how-to/configure-tess-interaction.md)
+- [Configure a validator instance](how-to/configure-ultron-validator.md)
+- [Customize roles](how-to/customize-roles.md)
+
+## Operations and recovery
+
+- [Reconcile and recover](operations/reconcile-and-recover.md)
+- [Environment quarantine](operations/env-quarantine.md)
+- [Systemd/tmux troubleshooting](operations/systemd-tmux-troubleshooting.md)
+- [Backup and restore boundary](operations/backup-restore.md)
+- [Upgrade and asset-drift hold](operations/upgrade-assets.md)
+
+## Reference and migration
+
+- [Roster v2 fields](reference/roster-v2-fields.md) · [executable JSON Schema](reference/roster-v2.schema.json) · [validated example](examples/roster-v2.yaml)
+- [CLI and exit codes](reference/cli.md)
+- [Role classes](reference/role-classes.md)
+- [Lifecycle transitions](reference/lifecycle-transitions.md)
+- [Status and drift](reference/status-and-drift.md)
+- [Generated environment boundary](reference/generated-env-boundary.md)
+- [v1-to-v2 preview](migration/v1-to-v2.md)
+- [Example/profile dispositions](migration/example-profile-disposition.md)
+- [Legacy class aliases](migration/legacy-class-aliases.md)
+
+## Acceptance evidence and holds
+
+- [M0/M5 IA checklist](FLEET-CONFIG-DOCS-IA-CHECKLIST.md)
+- [Legacy example/profile inventory](LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md)
+- [M5 closure evidence](../reports/documentation/758-fleet-config-ia-closure.md)
+- [Approved-existing deferrals and live-action holds](../reports/deferred/758-fleet-config-deferrals.md)
+
+The canonical publishing source remains this repository. This card does not publish externally, run a migration, operate a live fleet, or close parent issue #758.

docs/fleet/TASKS.md

@@ -7,21 +7,21 @@
 > Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/north-star.md](./north-star.md)
 > Status: `not-started` | `in-progress` | `done` | `blocked` | `failed`
 
-| id            | status      | description                                                                                                        | depends_on            | agent       | pr  | notes                                                                                                                       |
-| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
-| FLEET-OBS-000 | done        | Plan: north-star + Phase-2 PRD + workstream scaffolding                                                            | —                     | lead        | —   | persisted 2026-06-20 on `feat/fleet-observability`                                                                          |
-| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                        | FLEET-OBS-000         | lead        | —   | file-based `~/.config/mosaic/fleet/run/<agent>.hb`; spec in PRD                                                             |
-| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                                | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc `mosaic yolo` fleet agent (dogfood)                                                                    |
-| FLEET-OBS-003 | done        | `mosaic fleet ps` — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
-| FLEET-OBS-004 | done        | `mosaic agent watch <name>` — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | `attach -r`; verb wired                                                                                                     |
-| FLEET-OBS-005 | done        | `mosaic agent send --verify` — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
-| FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                       | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
-| FLEET-OBS-007 | not-started | Framework doc: fleet observability guide + verbs                                                                   | FLEET-OBS-003,004,005 | lead        | —   | `docs/guides/` or `framework/tools/.../README`                                                                              |
-| FLEET-OBS-008 | not-started | Independent review + dogfood verification on live fleet                                                            | FLEET-OBS-002..007    | reviewer    | —   | author ≠ reviewer; capture evidence in scratchpad                                                                           |
-| FLEET-OBS-009 | not-started | Open PR → green CI (queue guard) → squash-merge → close `fleet-observability-1`                                    | FLEET-OBS-008         | lead        | —   | trunk merge; no direct push to main                                                                                         |
+| id            | status      | description                                                                                                      | depends_on            | agent       | pr  | notes                                                                                                                       |
+| ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
+| FLEET-OBS-000 | done        | Plan: north-star + Phase-2 PRD + workstream scaffolding                                                          | —                     | lead        | —   | persisted 2026-06-20 on `feat/fleet-observability`                                                                          |
+| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                      | FLEET-OBS-000         | lead        | —   | file-based ~/.config/mosaic/fleet/run/<agent>.hb; spec in PRD                                                               |
+| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                              | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc mosaic yolo fleet agent (dogfood)                                                                      |
+| FLEET-OBS-003 | done        | mosaic fleet ps — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
+| FLEET-OBS-004 | done        | mosaic agent watch <name> — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | attach -r; verb wired                                                                                                       |
+| FLEET-OBS-005 | done        | mosaic agent send --verify — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
+| FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                     | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
+| FLEET-OBS-007 | not-started | Framework doc: fleet observability guide + verbs                                                                 | FLEET-OBS-003,004,005 | lead        | —   | `docs/guides/` or `framework/tools/.../README`                                                                              |
+| FLEET-OBS-008 | not-started | Independent review + dogfood verification on live fleet                                                          | FLEET-OBS-002..007    | reviewer    | —   | author ≠ reviewer; capture evidence in scratchpad                                                                           |
+| FLEET-OBS-009 | not-started | Open PR → green CI (queue guard) → squash-merge → close `fleet-observability-1`                                  | FLEET-OBS-008         | lead        | —   | trunk merge; no direct push to main                                                                                         |
 
 ## Proposed MVP rollup row (for the MVP orchestrator — not written by this workstream)
 
-```
+```text-table
 | W-FLEET | in-progress | Fleet (agent-session execution layer) | Phase 2/5 | docs/fleet/TASKS.md | observability dogfooded on live stub fleet; control plane rides federation (W1) |
 ```

docs/fleet/backlog-conventions.md

@@ -2,10 +2,10 @@
 
 The **backlog** is Mosaic's native backlog-of-record for fleet work. It is built
 end-to-end on Mosaic's own storage layer (`@mosaicstack/db`, drizzle/Postgres)
-and surfaced as `mosaic fleet backlog <sub> --json`.
+and surfaced as mosaic fleet backlog <sub> --json.
 
 > **Mosaic-native, no Hermes.** This backlog REPLACES the former Hermes adapter.
-> There is **no** runtime dependency on Hermes, `hermes kanban`, or `~/.hermes`
+> There is **no** runtime dependency on Hermes, hermes kanban, or ~/.hermes
 > anywhere in this feature. Anything previously delegated to Hermes is recreated
 > here on Mosaic's own Postgres storage layer.
 
@@ -18,7 +18,7 @@ engine (no sqlite, no raw client).
 | ---------------------------------- | -------------------- | ---------------------------------------------------------------- |
 | `DATABASE_URL` injected at runtime | Full server Postgres | the verified runtime database; it never authorizes migration/DDL |
 | `PGLITE_DATA_DIR` set (no URL)     | Embedded PGlite      | that directory                                                   |
-| neither (default)                  | Embedded PGlite      | `~/.config/mosaic/fleet/backlog`                                 |
+| neither (default)                  | Embedded PGlite      | ~/.config/mosaic/fleet/backlog                                   |
 
 PGlite is real Postgres semantics in-process — including the row locks the atomic
 claim relies on — so the **same code** runs on a laptop (embedded, single-host
@@ -28,9 +28,9 @@ For embedded PGlite only, the local backlog routine may prepare its local schema
 
 ### Update safety
 
-The embedded PGlite store lives under `~/.config/mosaic/fleet/backlog`, which is
+The embedded PGlite store lives under ~/.config/mosaic/fleet/backlog, which is
 listed in `PRESERVE_PATHS` in `packages/mosaic/framework/install.sh`. This means
-`mosaic update` (which runs the framework sync with `rsync --delete`) will **not**
+mosaic update (which runs the framework sync with rsync --delete) will **not**
 wipe the operator's backlog — same protection as the roster, per-agent env, and
 heartbeat run dir.
 
@@ -46,10 +46,10 @@ A card is one row in the `backlog` table:
 | `phase`             | text (nullable)     | Board/phase grouping (see below).                             |
 | `priority`          | int (default 0)     | **Higher = sooner.** Claim picks the max-priority ready card. |
 | `status`            | enum                | `ready` \| `claimed` \| `blocked` \| `done`.                  |
-| `depends_on`        | jsonb `string[]`    | DAG edges — ids of cards this one depends on.                 |
+| `depends_on`        | jsonb string[]      | DAG edges — ids of cards this one depends on.                 |
 | `claim_owner`       | text (nullable)     | Owner token of the active claim.                              |
 | `claim_ttl_seconds` | int (nullable)      | TTL of the active claim.                                      |
-| `claimed_at`        | timestamptz (null)  | When the claim was taken. `claimed_at + ttl` = expiry.        |
+| `claimed_at`        | timestamptz (null)  | When the claim was taken. claimed_at + ttl = expiry.          |
 | `attempts`          | int (default 0)     | Incremented each time the card is claimed.                    |
 | `idempotency_key`   | text (unique, null) | Dedups `create`; NULLs are distinct in Postgres.              |
 | `acceptance`        | jsonb (nullable)    | Acceptance criteria (array of strings or object).             |
@@ -65,12 +65,12 @@ would add ceremony without benefit.
 ### Board / phase convention
 
 `phase` is a free-form grouping string used as the board column / milestone label
-(e.g. `M1`, `fleet`, `infra`). `list --phase <phase>` filters to one board lane.
+(e.g. `M1`, `fleet`, `infra`). list --phase <phase> filters to one board lane.
 `priority` orders cards **within** the ready pool regardless of phase.
 
 ## Status lifecycle
 
-```
+```text-diagram
             create
               │
               ▼
@@ -87,51 +87,49 @@ would add ceremony without benefit.
 - **blocked** — explicitly parked; never auto-claimed.
 - **done** — completed; satisfies dependents.
 
-## Atomic claim (`FOR UPDATE SKIP LOCKED`) + TTL
+## Atomic claim (FOR UPDATE SKIP LOCKED) + TTL
 
 `claim` is atomic. Inside a single transaction it locks candidate `ready` rows
-with `SELECT ... FOR UPDATE SKIP LOCKED` (via the drizzle `sql` operator), picks
+with SELECT ... FOR UPDATE SKIP LOCKED (via the drizzle `sql` operator), picks
 the highest-priority deps-satisfied card, and flips it to `claimed`. Because a row
 already locked by a concurrent claimer is **skipped**, two claimers can **never**
 both win the same card — the loser falls through to the next candidate or gets
 `null`. (Proven by the concurrency tests in `packages/db/src/backlog.spec.ts`.)
 
 - **Deps gate:** a card is only claimable when every id in `depends_on` is `done`.
-- **TTL:** `claim --ttl <sec>` (default **900s**) records `claim_ttl_seconds`.
-- **reclaim:** releases claims whose `claimed_at + ttl` is in the past (expired)
-  back to `ready`, clearing the claim fields. `reclaim --id <id>` force-releases a
+- **TTL:** claim --ttl <sec> (default **900s**) records `claim_ttl_seconds`.
+- **reclaim:** releases claims whose claimed_at + ttl is in the past (expired)
+  back to `ready`, clearing the claim fields. reclaim --id <id> force-releases a
   specific card regardless of expiry. This is how a crashed worker's card returns
   to the pool.
 
-## CLI — `mosaic fleet backlog <sub> --json`
+## CLI — mosaic fleet backlog <sub> --json
 
 All subcommands support `--json`.
 
-| Subcommand                                                                                    | Purpose                                                                                   |
-| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key]` | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
-| `list [--status --phase --ready-only]`                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
-| `claim --owner [--ttl <sec> --id <id>]`                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
-| `reclaim [--id <id>]`                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
-| `link --from --to`                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
-| `stats`                                                                                       | Counts by status, oldest-ready age, expired-claim count.                                  |
-| `block --id`                                                                                  | Set a card to `blocked`.                                                                  |
-| `complete --id`                                                                               | Set a card to `done` (releases any claim).                                                |
+| Subcommand                                                                                  | Purpose                                                                                   |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key] | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
+| list [--status --phase --ready-only]                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
+| claim --owner [--ttl <sec> --id <id>]                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
+| reclaim [--id <id>]                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
+| link --from --to                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
+| `stats`                                                                                     | Counts by status, oldest-ready age, expired-claim count.                                  |
+| block --id                                                                                  | Set a card to `blocked`.                                                                  |
+| complete --id                                                                               | Set a card to `done` (releases any claim).                                                |
 
 ### Example
 
-```sh
-# Seed two cards, the second depends on the first.
+Seed two cards; the second depends on the first. Because A2 is gated on A1, claim returns A1 first. Finish A1, then list A2 as ready. Recover stalled work.
+
+```fleet-command
 mosaic fleet backlog create --id A1 --title "schema" --priority 5
 mosaic fleet backlog create --id A2 --title "service" --depends-on A1 --priority 9
 
-# A2 is gated on A1, so claim returns A1 first.
 mosaic fleet backlog claim --owner worker-1 --ttl 600 --json
 
-# Finish A1; now A2 is ready.
 mosaic fleet backlog complete --id A1
 mosaic fleet backlog list --ready-only --json
 
-# Recover stalled work.
 mosaic fleet backlog reclaim --json
 ```

docs/fleet/concepts/desired-vs-observed-state.md

@@ -0,0 +1,42 @@
+# Desired, Derived, and Observed Fleet State
+
+## One writable authority
+
+The canonical local v2 roster at <MOSAIC_HOME>/fleet/roster.yaml is desired state. Membership, stable identity, class, runtime/provider/model selection, launch policy, enablement, and persisted `running`/`stopped` intent are written only through generation-guarded roster mutations.
+
+Derived projections are reproducible consequences of that authority:
+
+- <name>.env.generated;
+- exact roster-named tmux sessions on the configured socket after reconciliation;
+- systemd service targets managed by installation/reconciliation.
+
+Current systemd unit enablement is not yet lifecycle-conformant at boot: installation can enable every
+agent unit, and the launcher projection does not carry `enabled` or `desired_state`. Therefore reboot
+preservation for stopped/disabled agents remains an FCM-M3-002 acceptance hold, not a guaranteed
+projection behavior.
+
+Observed evidence available to current roster-v2 status commands includes systemd active state, tmux
+presence, holder ownership, and unmanaged sessions. Heartbeat files are observational in the wider fleet,
+but roster-v2 `status`, `doctor`, and `verify` do not currently read them. Observation never writes back
+to the roster.
+
+## Generation and ownership
+
+`generation` is a positive integer concurrency fence. A mutating request must provide the current value. Successful changed CRUD increments it exactly once; stale or concurrent writers fail before mutation. Apply/reconcile rereads the canonical roster under a private exclusive lock and uses only that generation and content for effects.
+
+Ownership is exact, never fuzzy. Reconciliation is limited to roster names, the configured socket, the exact holder session, a private installation identity, and private managed paths. An ownership mismatch, unmanaged session, unsafe path, stale generation, or ambiguous lock fails closed.
+
+## Drift decisions
+
+| Observation                              | Interpretation           | Safe response                                                          |
+| ---------------------------------------- | ------------------------ | ---------------------------------------------------------------------- |
+| Generated file differs or is missing     | Derived projection drift | Review apply --dry-run; regenerate from the roster.                    |
+| Desired `running`, exact session missing | `missing-session`        | Diagnose ownership/runtime, then reconcile if safe.                    |
+| Desired `stopped`, exact session present | `unexpected-session`     | Inspect; reconciliation may stop only the proven roster target.        |
+| Disabled agent running                   | `disabled-running`       | Inspect; disabled state wins during explicit safe reconciliation.      |
+| Unknown session on the configured socket | Unmanaged state          | Report only. Do not adopt, rename, or kill it.                         |
+| Heartbeat stale in the wider fleet       | Liveness evidence        | Diagnose separately; current roster-v2 status does not read heartbeat. |
+
+`status` and `doctor` classify. `verify` is also observational but exits non-zero when ownership, drift, or unmanaged-state checks fail. `plan`/apply --dry-run validates proposed projection and lifecycle work without mutation. `apply` and `reconcile` converge only after all preconditions pass.
+
+A partial projection failure does not roll the roster back. Treat the committed roster as authority and regenerate. A lifecycle failure after projection completion preserves both roster and projections for inspection. Sensitive legacy values are never printed; diagnostics are bounded to stable codes, key names where applicable, and hashes.

docs/fleet/concepts/generated-env-launch-chain.md

@@ -0,0 +1,23 @@
+# Generated Environment Launch Chain
+
+The launcher consumes validated data, not shell configuration.
+
+1. Read and validate the canonical roster.
+2. Render deterministic <name>.env.generated data from that roster.
+3. Parse optional <name>.env.local through a strict allowlist.
+4. Reject generated-key shadowing, unknown or sensitive-looking keys, unsafe paths/values, duplicates, malformed lines, shell syntax, and command overrides.
+5. Derive the runtime command from validated runtime/model/reasoning data.
+6. Target only the exact configured tmux socket and roster session after ownership checks.
+
+## File precedence and ownership
+
+| File              | Owner                    | Use                                                                         |
+| ----------------- | ------------------------ | --------------------------------------------------------------------------- |
+| `.env.generated`  | Mosaic projection writer | Complete deterministic roster projection. Rebuild; do not edit.             |
+| `.env.local`      | Operator                 | Optional, private, strict machine-local data. Cannot shadow generated keys. |
+| `.env`            | Legacy input             | One-time migration input only; never launch authority.                      |
+| `.env.quarantine` | Private quarantine       | Retained unsafe legacy evidence; never loaded by the launcher.              |
+
+Neither systemd nor the launcher sources these files. No `eval`, shell expansion, arbitrary `MOSAIC_AGENT_COMMAND`, channel, or secret-reference compatibility path exists. Safe legacy generated keys are regenerated, allowed local keys are relocated, and unsafe material is quarantined.
+
+Diagnostics never expose the rejected value, credential material, or command text. They are bounded to stable rule code, key name where safe, and SHA-256 content identity. See [generated environment reference](../reference/generated-env-boundary.md) and [quarantine operations](../operations/env-quarantine.md).

docs/fleet/concepts/identity-class-runtime.md

@@ -0,0 +1,20 @@
+# Fleet Identity, Class, and Runtime
+
+Each roster field has one job. Do not use names or model strings as authority shortcuts.
+
+| Concern                 | Field                         | Contract                                                                                     |
+| ----------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
+| Stable machine identity | agents[].name                 | Unique, immutable mutation target and exact service/session name.                            |
+| Display identity        | agents[].alias                | Human-facing label only; may be changed and grants no authority.                             |
+| Behavioral contract     | agents[].class                | Resolves through the shared baseline plus `roles.local` persona library.                     |
+| Tool boundary           | agents[].tool_policy          | Must match protected canonical classes; cannot independently grant authority.                |
+| Harness                 | agents[].runtime              | One of `claude`, `codex`, `opencode`, or `pi`, declared in `runtimes`.                       |
+| Backend selection       | agents[].provider and `model` | Explicit non-empty data; capability validity is not inferred from the display name or class. |
+| Effort                  | agents[].reasoning            | `low`, `medium`, or `high`.                                                                  |
+| Local placement         | `working_directory`           | Explicit safe local work path; not remote placement authority.                               |
+
+Tess and Ultron are conventional instance/display names only. They are not products, required machine identities, role aliases, or authority-bearing classes. A configurable interaction instance uses class: interaction; a configurable validation instance uses class: validator. Any stable name and alias satisfying the structural contract may be used.
+
+Class aliases are deliberately narrow: implementer → code, reviewer → review, and operator-interaction → interaction. No runtime, provider, model, persona prose, or instance name changes this mapping. See [role classes](../reference/role-classes.md) and the [validated generic example](../examples/roster-v2.yaml).
+
+Roster v2 is local-only. It contains no host/SSH placement, connector, channel, secret-reference, arbitrary-command, per-agent socket, or gateway mapping fields. Those concerns require separate requirements and threat models.

docs/fleet/concepts/role-authority-and-leases.md

@@ -0,0 +1,22 @@
+# Fleet Role Authority and Leases
+
+Role content describes behavior; protected authority is immutable code metadata derived only from the canonical class.
+
+## Required workstream classes
+
+`code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction` are required FCM classes. `merge-gate` is additionally protected because it remains the sole approve-to-land and merge authority.
+
+| Class                                        | Authority                                         | Boundary                                                                               |
+| -------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `merge-gate`                                 | Approve-to-land and merge                         | Sole merge authority.                                                                  |
+| `validator`                                  | Issue independent validation evidence/certificate | Never approves landing or merges.                                                      |
+| `orchestrator`                               | Orchestrate topology and issue bounded leases     | Does not gain merge authority.                                                         |
+| `team-leader`                                | Use explicitly leased capacity                    | Cannot issue leases or mutate roster, credentials, topology authority, or merge state. |
+| `interaction`                                | Receive requests and report status                | Cannot orchestrate, issue leases, mutate configuration, or merge.                      |
+| `code`, `review`, `enhancer`, custom classes | No protected authority by default                 | Persona prose cannot grant protected powers.                                           |
+
+A lease is capacity authorization from an orchestrator, not ownership. It must identify a bounded task or period and does not alter the leased agent's roster identity, role contract, credentials, authority, or persisted lifecycle. Expiry/revocation returns capacity; it does not rewrite the roster.
+
+Semantic validation rejects protected class/tool-policy mismatch in either direction. An instance named Ultron with class: validator remains validation-only. An instance named Tess with class: interaction remains request/status-only. Renaming either instance changes no authority.
+
+For resolver layering and safe customization, see [role classes](../reference/role-classes.md) and [customize roles](../how-to/customize-roles.md).

docs/fleet/examples/roster-v2.yaml

@@ -0,0 +1,61 @@
+version: 2
+generation: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~/src
+  runtime: pi
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: code-example
+    alias: Code Example
+    class: code
+    runtime: pi
+    provider: example-provider
+    model: example-model
+    reasoning: medium
+    tool_policy: code
+    working_directory: ~/src
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: false
+  - name: interaction-example
+    alias: Interaction Example
+    class: interaction
+    runtime: pi
+    provider: example-provider
+    model: example-model
+    reasoning: low
+    tool_policy: interaction
+    working_directory: ~/src
+    persistent_persona: true
+    reset_between_tasks: false
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: false
+  - name: validator-example
+    alias: Validator Example
+    class: validator
+    runtime: pi
+    provider: example-provider
+    model: example-model
+    reasoning: high
+    tool_policy: validator
+    working_directory: ~/src
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: false

docs/fleet/f4-matrix-connector.md

@@ -15,7 +15,7 @@ core.
 
 Connectors implement one small, uniform interface (`src/fleet/connectors/types.ts`):
 
-```ts
+```typescript
 interface OrchestratorConnector {
   readonly kind: 'tmux' | 'discord' | 'matrix';
   send(message: OutboundMessage): Promise<SendResult>; // orchestrator → human
@@ -25,11 +25,11 @@ interface OrchestratorConnector {
 ```
 
 - **send / subscribe / health** — the only surface fleet core depends on. `SendResult` is the
-  ack half; `health()` is the liveness half.
+  ack half; health() is the liveness half.
 - **Thread-aware by metadata** — `OutboundMessage.threadId` / `InboundMessage.threadId` are
   optional, so thread-capable connectors (Matrix rooms/threads, the future first-party Mosaic
   Discord plugin) fit **without an interface change**.
-- **Registry** (`registry.ts`) — implementations register a factory by kind; `createConnector(config)`
+- **Registry** (`registry.ts`) — implementations register a factory by kind; createConnector(config)
   resolves one from roster config. Phase 1 ships the registry + `resolveConnectorKind` (defaults
   `tmux` when a roster declares no connector — **back-compat**); the factories land in Phase 2.
 
@@ -39,7 +39,7 @@ A roster may carry an optional `connector` block (`roster.schema.json`); absent
 
 ```yaml
 connector:
-  kind: matrix # tmux | discord | matrix
+  kind: matrix
   matrix:
     homeserver_url: https://matrix.example.internal
     user_id: '@mos:example.internal'
@@ -55,12 +55,12 @@ reject a token committed to a shipped file anyway.
 The connector speaks the **Matrix client-server API** directly over HTTPS (`fetch` — no SDK needed
 for MVP), so it is **homeserver-agnostic**:
 
-| Op          | Matrix CS-API                                                            |
-| ----------- | ------------------------------------------------------------------------ |
-| `send`      | `PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}`      |
-| `subscribe` | `GET /_matrix/client/v3/sync` (long-poll, `since` token) → room timeline |
-| `health`    | `GET /_matrix/client/versions` (reachable) + `…/account/whoami` (authed) |
-| threads     | `m.thread` relations ↔ `threadId`                                        |
+| Op          | Matrix CS-API                                                           |
+| ----------- | ----------------------------------------------------------------------- |
+| `send`      | PUT /\_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}      |
+| `subscribe` | GET /\_matrix/client/v3/sync (long-poll, `since` token) → room timeline |
+| `health`    | GET /\_matrix/client/versions (reachable) + …/account/whoami (authed)   |
+| threads     | `m.thread` relations ↔ `threadId`                                       |
 
 ## Local homeserver (infra, not connector code)
 
@@ -79,7 +79,7 @@ homeserver choice is a **deployment** concern (a Phase-2 deploy guide), not conn
 | ----- | --------------------------------------------------------------------------------------- | ------- |
 | **1** | Connector interface + types, registry + kind resolution, roster `connector` schema, doc | ✅ yes  |
 | 2     | Matrix CS-API client (fetch-based send/sync/health) + registered factory + tests        | follow  |
-| 2     | `fleet init` / `configure` connector-selection UX; roster parse wires the block         | follow  |
+| 2     | fleet init / `configure` connector-selection UX; roster parse wires the block           | follow  |
 | 2     | systemd launch wiring so the orchestrator starts on the chosen connector                | follow  |
 | 3     | Conduit deploy guide; first-party Mosaic Discord (threads) registers as a connector     | follow  |
 

docs/fleet/how-to/configure-tess-interaction.md

@@ -0,0 +1,21 @@
+# Configure an Interaction Instance
+
+An interaction instance is a configurable local roster member with canonical class: interaction and matching tool_policy: interaction. “Tess” may be used as a display alias, but neither that alias nor the stable name is required or authority-bearing.
+
+Use the [validated generic roster](../examples/roster-v2.yaml) as the safe shape. Choose a unique stable `name`, any descriptive `alias`, a supported declared runtime, explicit provider/model/reasoning, and a safe work directory. Start with:
+
+```yaml
+name: interaction-example
+alias: Interaction Example
+class: interaction
+tool_policy: interaction
+lifecycle:
+  enabled: true
+  desired_state: stopped
+```
+
+Plan the complete agent payload with the current roster generation, then create it without `--persisted-start`. Creation defaults to enabled/stopped and performs no runtime action. Review the resulting roster and projection plan before any later lifecycle decision.
+
+The interaction class is request/status only. It cannot orchestrate, issue leases, mutate the roster/configuration, grant credentials, certify validation, approve landing, or merge. Connector and channel configuration are outside roster v2; do not add connector, channel, secret, command, remote-host, or gateway fields.
+
+See [safe CRUD](create-update-delete-agent.md), [identity separation](../concepts/identity-class-runtime.md), and [role authority](../concepts/role-authority-and-leases.md).

docs/fleet/how-to/configure-ultron-validator.md

@@ -0,0 +1,21 @@
+# Configure a Validator Instance
+
+A validator instance is a configurable local roster member with canonical class: validator and matching tool_policy: validator. “Ultron” may be used as a display alias, but it is not a required identity, class alias, product name, or source of authority.
+
+Use the [validated generic roster](../examples/roster-v2.yaml) as the safe shape. Choose a unique stable name and explicit supported runtime/provider/model/reasoning values. Start stopped:
+
+```yaml
+name: validator-example
+alias: Validator Example
+class: validator
+tool_policy: validator
+lifecycle:
+  enabled: true
+  desired_state: stopped
+```
+
+Plan the full payload with the current generation and create without `--persisted-start`. Creation writes desired state and projections only; it does not launch a validator.
+
+`validator` may issue independent validation evidence or a certificate. It has no approve-to-land or merge authority. `merge-gate` remains the sole protected merge authority, and changing the validator's name, alias, persona prose, runtime, provider, model, or tool-policy text cannot elevate it.
+
+Certificate consumption and final release evidence remain FCM-M5-002 gates. This page does not create a certificate or authorize merge. See [safe CRUD](create-update-delete-agent.md) and [role authority](../concepts/role-authority-and-leases.md).

docs/fleet/how-to/create-update-delete-agent.md

@@ -4,20 +4,20 @@ Use the local roster-v2 control plane only. These commands change desired state
 
 ## Read and plan first
 
-```sh
+```fleet-synopsis
 mosaic fleet get <name>
 mosaic fleet plan create --expected-generation <n> --agent '<json>'
 mosaic fleet plan update <name> --expected-generation <n> --agent '<json>'
 mosaic fleet plan delete <name> --expected-generation <n>
 ```
 
-`plan create` takes the name from `--agent`. `plan update` and `plan delete` require the target name immediately after the operation. A plan is deterministic and side-effect free: it validates the complete proposed roster and projection targets without changing files. Use `--dry-run` on `create`, `update`, or `delete` for the same no-write result.
+plan create takes the name from `--agent`. plan update and plan delete require the target name immediately after the operation. A plan is deterministic and side-effect free: it validates the complete proposed roster and projection targets without changing files. Use `--dry-run` on `create`, `update`, or `delete` for the same no-write result.
 
-Every successful command prints JSON. `get` returns `{ "generation", "agent" }`; mutation results contain `plan`, `applied`, `authoritativeRoster`, and `projections`.
+Every successful command prints JSON. `get` returns { "generation", "agent" }; mutation results contain `plan`, `applied`, `authoritativeRoster`, and `projections`.
 
 ## Create safely
 
-```sh
+```fleet-command
 mosaic fleet create --expected-generation 7 --agent '{
   "name":"coder0",
   "alias":"Coder 0",
@@ -34,20 +34,20 @@ mosaic fleet create --expected-generation 7 --agent '{
 }'
 ```
 
-Create defaults to `enabled: true` and `desired_state: stopped`. It does not start a process. Add `--persisted-start` only to persist `desired_state: running`; that still does not start a runtime in this M2 command. The JSON payload is an allowlist of the roster-v2 fields shown above plus `launch.yolo`; command, channel, secret-reference, and other unknown keys are rejected rather than ignored. The JSON error exposes only a stable code, never the rejected value.
+Create defaults to enabled: true and desired_state: stopped. It does not start a process. Add `--persisted-start` only to persist desired_state: running; that still does not start a runtime in this M2 command. The JSON payload is an allowlist of the roster-v2 fields shown above plus `launch.yolo`; command, channel, secret-reference, and other unknown keys are rejected rather than ignored. The JSON error exposes only a stable code, never the rejected value.
 
 ## Update and delete safely
 
-```sh
-mosaic fleet update coder0 --expected-generation 8 --agent '<complete JSON agent payload>'
-mosaic fleet delete coder0 --expected-generation 9
+```fleet-synopsis
+mosaic fleet update <name> --expected-generation <n> --agent '<complete JSON agent payload>'
+mosaic fleet delete <name> --expected-generation <n>
 ```
 
 Updates require a complete agent JSON payload and preserve the stable name. Delete removes only the exact roster-owned `coder0.env.generated` projection. It retains `coder0.env.local`, legacy `coder0.env`, `coder0.env.quarantine`, and every unrelated projection. A delete dry-run leaves all of those files byte-identical.
 
 ## Handle generation conflicts
 
-Every mutation requires the current authoritative `--expected-generation`. A stale value returns JSON `error.code: "stale-generation"` with a non-zero exit. Reload with `mosaic fleet get <name>` or reread the roster, plan again using the returned generation, then retry. A concurrent mutation returns `concurrent-mutation`; do not force or bypass the lock.
+Every mutation requires the current authoritative `--expected-generation`. A stale value returns JSON error.code: "stale-generation" with a non-zero exit. Reload with mosaic fleet get <name> or reread the roster, plan again using the returned generation, then retry. A concurrent mutation returns `concurrent-mutation`; do not force or bypass the lock.
 
 ## Interpret partial failures
 
@@ -71,4 +71,4 @@ This is not a rollback and not a no-op: reload the roster because its generation
 
 Handled validation errors and partial projection failures exit non-zero. `plan`/`--dry-run` and normal mutation JSON make the state explicit; scripts should use both the exit code and `authoritativeRoster`/`projections`, not `applied` alone.
 
-The commands operate only on `<mosaic-home>/fleet/roster.yaml`, the local roster desired-state authority. They do not accept arbitrary commands, channels, secrets, remote/connector actions, migration/canary actions, or runtime lifecycle operations.
+The commands operate only on <mosaic-home>/fleet/roster.yaml, the local roster desired-state authority. They do not accept arbitrary commands, channels, secrets, remote/connector actions, migration/canary actions, or runtime lifecycle operations.

docs/fleet/how-to/customize-roles.md

@@ -2,8 +2,8 @@
 
 Mosaic resolves persona contracts through two layers:
 
-1. `fleet/roles/<canonical-class>.md` — seeded baseline contract.
-2. `fleet/roles.local/<canonical-class>.md` — operator override or custom role; this layer wins.
+1. fleet/roles/<canonical-class>.md — seeded baseline contract.
+2. fleet/roles.local/<canonical-class>.md — operator override or custom role; this layer wins.
 
 The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation,
 and launch-time persona injection.
@@ -34,11 +34,11 @@ A custom class remains supported when a readable contract exists for the exact i
 The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
 ```
 
-Save it as `fleet/roles.local/release-notes.md`, then reference `class: release-notes` and a matching
-`tool_policy: release-notes` in roster v2. Adding only a `LIBRARY.md` row is insufficient.
+Save it as `fleet/roles.local/release-notes.md`, then reference class: release-notes and a matching
+tool_policy: release-notes in roster v2. Adding only a `LIBRARY.md` row is insufficient.
 
 Names such as `worker`, `analyst`, and `canary` are not built-in aliases; they need genuine custom
-contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.
+contracts. agents[].alias, Tess, and Ultron are display names and cannot select a class.
 
 ## Validation and authority boundaries
 

docs/fleet/how-to/start-stop-restart.md

@@ -2,22 +2,22 @@
 
 Use the canonical local roster-v2 command surface:
 
-```sh
+```fleet-synopsis
 mosaic fleet apply --expected-generation <n> --dry-run
 mosaic fleet apply --expected-generation <n>
 mosaic fleet reconcile --expected-generation <n>
 mosaic fleet start <name> --expected-generation <n>
 mosaic fleet stop <name> --expected-generation <n>
 mosaic fleet restart <name> --expected-generation <n>
-mosaic fleet status [name]
+mosaic fleet status [<name>]
 mosaic fleet verify
 mosaic fleet doctor
 ```
 
-Start with `--dry-run`. It validates roster semantics, deterministic projections, private managed paths, exact holder ownership, and named-socket state without changing files or lifecycle state. `apply` and `reconcile` rebuild derived projections and enforce only persisted roster state: enabled `running` agents may start, while stopped or disabled agents are not started.
+Start with `--dry-run`. It validates roster semantics, deterministic projections, private managed paths, exact holder ownership, and named-socket state without changing files or lifecycle state. Explicit `apply` and `reconcile` rebuild derived projections and enforce persisted roster state: enabled `running` agents may start, while stopped or disabled agents are not started. This guarantee does not extend to reboot/service activation yet; boot preservation remains an FCM-M3-002 hold.
 
-`start`, `stop`, and `restart` are explicit one-shot exact-service actions. They do not persist a lifecycle change. Roster CRUD is the only way to change persisted desired state.
+`start`, `stop`, and `restart` are explicit one-shot exact-service actions. They do not persist a lifecycle change. `update` preserves the agent's existing lifecycle, and no delivered operation changes durable lifecycle after creation.
 
-Every command prints JSON. Observation commands report drift without mutation; `verify` exits non-zero on ownership mismatch, unmanaged sessions, or drift. A failed apply that wrote some derived projections reports `projections: "incomplete"` with bounded recovery to regenerate from the roster. A lifecycle failure after projections reports incomplete lifecycle work; it is never represented as a rollback or no-op.
+Every command prints JSON. Observation commands report drift without mutation; `verify` exits non-zero on ownership mismatch, unmanaged sessions, or drift. A failed apply that wrote some derived projections reports projections: "incomplete" with bounded recovery to regenerate from the roster. A lifecycle failure after projections reports incomplete lifecycle work; it is never represented as a rollback or no-op.
 
 These commands are local only. Remote/SSH/connector entries are inventory/validation-only. Commands do not accept arbitrary runtime commands, channels, secrets, generated-file desired state, or arbitrary tmux sockets.

docs/fleet/migration/example-profile-disposition.md

@@ -11,7 +11,7 @@ artifact is added, removed, or left without one of the dispositions below.
 ## Disposition rules
 
 - **Explicit v1 fixture:** the artifact is loaded through the existing v1 roster parser and must
-  declare `version: 1`. It remains a compatibility fixture; it is not silently treated as a v2
+  declare version: 1. It remains a compatibility fixture; it is not silently treated as a v2
   roster or given inferred aliases.
 - **Canonical profile:** the artifact is loaded through `loadProfiles`, which uses the shared
   baseline-plus-`roles.local` persona resolver and rejects unreadable or unresolved classes.
@@ -59,7 +59,7 @@ rollback; those gates belong to FCM-M4-002. See [v1-to-v2 preview](./v1-to-v2.md
 
 ## Running the guard
 
-```bash
+```fleet-command
 pnpm --filter @mosaicstack/mosaic test -- v1-v2-migration.spec.ts \
   -t "validates all 13 shipped artifacts and executes ready previews for every v1 fixture"
 ```

docs/fleet/migration/v1-to-v2.md

@@ -2,14 +2,14 @@
 
 **Issue:** #758 · **Card:** FCM-M4-001 · **Effect boundary:** preview only
 
-`mosaic fleet migrate-v1 preview` inventories a v1 roster and emits a canonical v2 candidate plus
+mosaic fleet migrate-v1 preview inventories a v1 roster and emits a canonical v2 candidate plus
 recovery evidence. It does not write a roster, apply environment projections, invoke systemd or
 `tmux`, contact connectors or remote hosts, launch an agent, run a canary, or execute rollback.
 FCM-M4-002 owns reversible cutover and rollback.
 
 ## Inputs
 
-```bash
+```fleet-command
 mosaic fleet migrate-v1 preview \
   --source roster-v1.yaml \
   --decisions migration-decisions.json \
@@ -44,25 +44,25 @@ be marked disabled. Observed-stopped agents always remain stopped.
 
 ## Field disposition
 
-| v1 field                                                                 | v2 disposition                                                                                                                                                                                                                                                                                                                    |
-| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`, `transport`, `tmux`, `defaults`, `runtimes`                   | Inventoried and structurally compiled; omitted runtimes retain v1 built-in defaults, while each explicitly declared runtime without a reset field follows the production v1 `/clear` fallback; present-empty holder/work-directory/reset values block                                                                             |
-| agent `name`, `alias`, `runtime`, working directory, persona/reset flags | Copied or explicitly defaulted only when absent; present-empty alias/work-directory values block for explicit disposition. Canonical `~`/`~/...` values stay unchanged in roster evidence and traversal-free forms expand only at the shared production environment-projection boundary before unchanged absolute-path validation |
-| `provider`, `model_hint`, `reasoning_level`                              | Explicit provider/model/reasoning decisions; no model-hint inference                                                                                                                                                                                                                                                              |
-| `class`, `tool_policy`                                                   | Only approved aliases canonicalize automatically; other classes require explicit preserve/replace disposition and shared-resolver validation                                                                                                                                                                                      |
-| `kickstart_template`                                                     | No v2 field; explicit inventory-only disposition required                                                                                                                                                                                                                                                                         |
-| agent `host`, `ssh`                                                      | `host != fleetHost` is demonstrably remote and inventory-only; `host == fleetHost` stays local; SSH targets with or without an explicit user must agree with `host`; ssh-only, missing fleet-host evidence, or contradictory targets block                                                                                        |
-| agent `socket`                                                           | Same-host candidate only when it matches the canonical fleet socket; conflicts block for explicit future disposition                                                                                                                                                                                                              |
-| root `connector`                                                         | Inventory-only; never contacted or reconciled                                                                                                                                                                                                                                                                                     |
-| unknown fields or snake/camel synonym collisions                         | Inventoried and block readiness                                                                                                                                                                                                                                                                                                   |
-| `.env.generated`                                                         | Rebuild from canonical roster data                                                                                                                                                                                                                                                                                                |
-| no legacy `.env`                                                         | `absent`; no legacy action required                                                                                                                                                                                                                                                                                               |
-| legacy `.env` containing generated keys only                             | `regenerate-only`; replace later from canonical roster data                                                                                                                                                                                                                                                                       |
-| legacy `.env` containing strict local keys                               | `relocate-local`; preserve those keys in `.env.local` during a later reviewed cutover                                                                                                                                                                                                                                             |
-| legacy `.env` containing forbidden/unsafe/sensitive/malformed keys       | `quarantine`; private input only, with diagnostics limited to code, key, and SHA-256                                                                                                                                                                                                                                              |
+| v1 field                                                                 | v2 disposition                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`, `transport`, `tmux`, `defaults`, `runtimes`                   | Inventoried and structurally compiled; omitted runtimes retain v1 built-in defaults, while each explicitly declared runtime without a reset field follows the production v1 `/clear` fallback; present-empty holder/work-directory/reset values block                                                                         |
+| agent `name`, `alias`, `runtime`, working directory, persona/reset flags | Copied or explicitly defaulted only when absent; present-empty alias/work-directory values block for explicit disposition. Canonical ~/~/... values stay unchanged in roster evidence and traversal-free forms expand only at the shared production environment-projection boundary before unchanged absolute-path validation |
+| `provider`, `model_hint`, `reasoning_level`                              | Explicit provider/model/reasoning decisions; no model-hint inference                                                                                                                                                                                                                                                          |
+| `class`, `tool_policy`                                                   | Only approved aliases canonicalize automatically; other classes require explicit preserve/replace disposition and shared-resolver validation                                                                                                                                                                                  |
+| `kickstart_template`                                                     | No v2 field; explicit inventory-only disposition required                                                                                                                                                                                                                                                                     |
+| agent `host`, `ssh`                                                      | host != fleetHost is demonstrably remote and inventory-only; host == fleetHost stays local; SSH targets with or without an explicit user must agree with `host`; ssh-only, missing fleet-host evidence, or contradictory targets block                                                                                        |
+| agent `socket`                                                           | Same-host candidate only when it matches the canonical fleet socket; conflicts block for explicit future disposition                                                                                                                                                                                                          |
+| root `connector`                                                         | Inventory-only; never contacted or reconciled                                                                                                                                                                                                                                                                                 |
+| unknown fields or snake/camel synonym collisions                         | Inventoried and block readiness                                                                                                                                                                                                                                                                                               |
+| `.env.generated`                                                         | Rebuild from canonical roster data                                                                                                                                                                                                                                                                                            |
+| no legacy `.env`                                                         | `absent`; no legacy action required                                                                                                                                                                                                                                                                                           |
+| legacy `.env` containing generated keys only                             | `regenerate-only`; replace later from canonical roster data                                                                                                                                                                                                                                                                   |
+| legacy `.env` containing strict local keys                               | `relocate-local`; preserve those keys in `.env.local` during a later reviewed cutover                                                                                                                                                                                                                                         |
+| legacy `.env` containing forbidden/unsafe/sensitive/malformed keys       | `quarantine`; private input only, with diagnostics limited to code, key, and SHA-256                                                                                                                                                                                                                                          |
 
-The only automatic aliases are `implementer → code`, `reviewer → review`, and
-`operator-interaction → interaction`. Similar or domain-specific names are never inferred. Automatic
+The only automatic aliases are implementer → code, reviewer → review, and
+operator-interaction → interaction. Similar or domain-specific names are never inferred. Automatic
 classes do not accept competing disposition records. Semantic validation delegates to the existing
 baseline-plus-`roles.local` resolver after the candidate is compiled by the existing v2 compiler.
 

docs/fleet/north-star.md

@@ -44,9 +44,9 @@ The Fleet inherits — does not re-invent — the MVP's hard requirements:
 | MVP req                       | What it means for the Fleet                                                                                             |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
 | MVP-X1 three-surface parity   | fleet observability/control reachable via **CLI + TUI + webUI** (CLI first; webUI is required for parity, not optional) |
-| MVP-X2 multi-tenant isolation | one tenant = one **Linux uid** (own `systemd --user`, socket, `~/.config/mosaic`); no cross-tenant leakage              |
+| MVP-X2 multi-tenant isolation | one tenant = one **Linux uid** (own systemd --user, socket, ~/.config/mosaic); no cross-tenant leakage                  |
 | MVP-X3 auth (BetterAuth/SSO)  | operator→fleet and cross-host views are auth-gated through the platform's existing auth                                 |
-| MVP-X4 quality gates          | `pnpm typecheck`/`lint`/`format:check` green before any push                                                            |
+| MVP-X4 quality gates          | pnpm typecheck/`lint`/`format:check` green before any push                                                              |
 | MVP-X5 federated topology     | cross-host fleet visibility rides the **federation** boundary (W1), not a bespoke broker                                |
 | MVP-X6 OTEL tracing           | heartbeats, sends, and lifecycle events emit spans; `traceparent` crosses the federation boundary                       |
 | MVP-X7 trunk merge            | branch from `main`, squash-merge via PR, never push to `main`                                                           |
@@ -55,20 +55,20 @@ The Fleet inherits — does not re-invent — the MVP's hard requirements:
 
 One **definition** is the source of truth; the **session** is how it runs.
 
-| Layer                            | Owner                                                                                       | Phase-2 reality                                        | Destination                                                                                                                         |
-| -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| **Definition + identity + auth** | gateway / `mosaic-as` (scoped tokens, #541)                                                 | `roster.yaml` (tenant-tagged)                          | one definition; `mosaic agent --new` materializes it                                                                                |
-| **Tenancy boundary**             | **Linux uid per tenant** (linger, own `systemd --user`, own socket, own `~/.config/mosaic`) | one tenant: `jarvis` = tenant zero                     | uid-per-tenant; federation aggregates across hosts                                                                                  |
-| **Runtime**                      | per-tenant tmux session on isolated socket                                                  | dogfood stub sessions (live now on `mosaic-factory`)   | claude/codex/pi/opencode TUIs                                                                                                       |
-| **Liveness**                     | **heartbeat protocol** every runtime answers                                                | protocol defined + dogfood stub answers it             | all runtimes answer; "healthy" ≠ "pane alive"                                                                                       |
-| **Observation**                  | read-only `watch` (native tmux) + `pipe-pane` stream                                        | CLI `watch`/`ps`; explicit opt-in `attach` for control | + auth-gated webUI streams                                                                                                          |
-| **Control plane**                | **federation** across hosts × tenants                                                       | records already carry `tenant_id` + `host`             | federated gateways expose fleet state; webUI in Phase 5                                                                             |
-| **Central register**             | Postgres `fleet` schema (gateway instance); access via gateway API only                     | _none in PoC_ (files + `roster.yaml`)                  | agents, missions, tasks, heartbeats, spend — single network-accessible SSOT; docs = generated projections                           |
-| **Budget / spend governance**    | **per-tenant budget policy** ingested by the orchestrator + routing layer                   | none today (spend is unmetered)                        | usage-vs-limit feedback ingested; spend auto-paced to the limit window; per-provider/per-account/concurrency/API-$ budgets enforced |
+| Layer                            | Owner                                                                                   | Phase-2 reality                                        | Destination                                                                                                                         |
+| -------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Definition + identity + auth** | gateway / `mosaic-as` (scoped tokens, #541)                                             | `roster.yaml` (tenant-tagged)                          | one definition; mosaic agent --new materializes it                                                                                  |
+| **Tenancy boundary**             | **Linux uid per tenant** (linger, own systemd --user, own socket, own ~/.config/mosaic) | one tenant: `jarvis` = tenant zero                     | uid-per-tenant; federation aggregates across hosts                                                                                  |
+| **Runtime**                      | per-tenant tmux session on isolated socket                                              | dogfood stub sessions (live now on `mosaic-factory`)   | claude/codex/pi/opencode TUIs                                                                                                       |
+| **Liveness**                     | **heartbeat protocol** every runtime answers                                            | protocol defined + dogfood stub answers it             | all runtimes answer; "healthy" ≠ "pane alive"                                                                                       |
+| **Observation**                  | read-only `watch` (native tmux) + `pipe-pane` stream                                    | CLI `watch`/`ps`; explicit opt-in `attach` for control | + auth-gated webUI streams                                                                                                          |
+| **Control plane**                | **federation** across hosts × tenants                                                   | records already carry `tenant_id` + `host`             | federated gateways expose fleet state; webUI in Phase 5                                                                             |
+| **Central register**             | Postgres `fleet` schema (gateway instance); access via gateway API only                 | _none in PoC_ (files + `roster.yaml`)                  | agents, missions, tasks, heartbeats, spend — single network-accessible SSOT; docs = generated projections                           |
+| **Budget / spend governance**    | **per-tenant budget policy** ingested by the orchestrator + routing layer               | none today (spend is unmetered)                        | usage-vs-limit feedback ingested; spend auto-paced to the limit window; per-provider/per-account/concurrency/API-$ budgets enforced |
 
 > **PoC socket hygiene:** the PoC fleet runs on the **default tmux socket** (no `-L`).
 > The named production-isolation socket is **`mosaic-fleet`** (matches the product brand);
-> an absent roster `socket_name` means the default socket everywhere (spawn, `fleet ps`,
+> an absent roster `socket_name` means the default socket everywhere (spawn, fleet ps,
 > onboarding cheat-sheet). The legacy dogfood canary still runs on the old `mosaic-factory`
 > socket pending migration.
 
@@ -177,22 +177,22 @@ routing flow**, **concurrency** (the spend multiplier), and **hard API-token $-l
 are enforced at the orchestrator + routing boundary, not inside individual workers (a worker never
 decides its own budget — see delegation discipline).
 
-**Budget CLI UX (#558):** `mosaic budget set --reset-at` sets the window reset; reset-datetimes
+**Budget CLI UX (#558):** mosaic budget set --reset-at sets the window reset; reset-datetimes
 carry **confidence tags** (`user` / `provider` / `estimated` / `unknown`); and **urgency/criticality
 is a dispatch-gate modifier** — high-urgency work may override even-spread pacing **within
 authorization**. (Also feeds the budgeting workstream, not only this doc.)
 
 ## Observation model
 
-| Verb                                | Behavior                                                                                           |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `mosaic fleet ps`                   | one table joining systemd + tmux + process + idle + last-heartbeat, with drift + boot-enable flags |
-| `mosaic agent watch <name>`         | **read-only** join (grouped session / `-r`), no resize tyranny, no keystrokes                      |
-| `mosaic agent attach <name>`        | explicit interactive takeover (the only path that can type)                                        |
-| `mosaic agent send <name> --verify` | confirms message **accepted**, not merely keystroke-injected                                       |
+| Verb                              | Behavior                                                                                           |
+| --------------------------------- | -------------------------------------------------------------------------------------------------- |
+| mosaic fleet ps                   | one table joining systemd + tmux + process + idle + last-heartbeat, with drift + boot-enable flags |
+| mosaic agent watch <name>         | **read-only** join (grouped session / `-r`), no resize tyranny, no keystrokes                      |
+| mosaic agent attach <name>        | explicit interactive takeover (the only path that can type)                                        |
+| mosaic agent send <name> --verify | confirms message **accepted**, not merely keystroke-injected                                       |
 
 > Why the current PoC blocks observation: sessions live on the isolated `mosaic-factory`
-> socket (invisible to default `tmux ls`), the only sanctioned read is `capture-pane`
+> socket (invisible to default tmux ls), the only sanctioned read is `capture-pane`
 > (blank for full-screen TUIs), and `attach` is read-write + resizes the session. The
 > verbs above restore "join and observe" safely.
 
@@ -214,7 +214,7 @@ compromised pane cannot corrupt or exfiltrate the register.
 | Layer                  | Responsibility                                                                                                | Implementation                                                                                                                                                                                            |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Register**           | Source of truth: agents, missions, tasks, heartbeats, spend                                                   | Postgres `fleet` schema — existing stack instance (`@mosaicstack/db`)                                                                                                                                     |
-| **Access**             | Typed, auth-gated API                                                                                         | Gateway `fleet/*` routes                                                                                                                                                                                  |
+| **Access**             | Typed, auth-gated API                                                                                         | Gateway fleet/\* routes                                                                                                                                                                                   |
 | **Dispatcher**         | Brief classification, BOD review, planning/coding/review/test/deploy sequencing + gates → fleet task dispatch | **forge pipeline engine** (`runPipeline`/`resumePipeline`, brief classifier, BOD) **+ thin `forge-exec` adapter → `agent-send.sh`**; NOT a new daemon — forge is reused, only stage→agent dispatch is new |
 | **Orchestrator (Mos)** | Goals, missions, judgment, user/PA interface                                                                  | Context-light; sets intent → re-engages only for decisions                                                                                                                                                |
 
@@ -236,7 +236,7 @@ role implementation.
 
 `docs/TASKS.md` and `MISSION-MANIFEST.md` are **generated projections** of the DB,
 not hand-maintained. The dispatcher (or a scheduled job) renders Markdown from
-`fleet.*` tables and commits the output. DB is authoritative; docs are for human
+fleet.\* tables and commits the output. DB is authoritative; docs are for human
 reference.
 
 ### Spend
@@ -266,13 +266,13 @@ re-evaluate if isolation or write-volume demands it.
 
 ## Phased roadmap
 
-| Phase                  | Outcome                                                                                                                                                                                                  | Status  |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                                                                                   | ✅ done |
-| **2 — Observability**  | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts                                                             | ▶ now   |
-| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)                                                                | planned |
-| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
-| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**              | planned |
+| Phase                  | Outcome                                                                                                                                                                                                | Status  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                                                                                 | ✅ done |
+| **2 — Observability**  | fleet ps (host+tenant aware join), heartbeat protocol + dogfood stub answers it, agent watch (read-only), agent send --verify receipts                                                                 | ▶ now   |
+| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)                                                              | planned |
+| 4 — Unified definition | one agent schema in gateway; mosaic agent --new → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
+| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**            | planned |
 
 ## Decisions of record (2026-06-20, with Jason)
 
@@ -285,9 +285,9 @@ re-evaluate if isolation or write-volume demands it.
 - Delivery: **CLI-first now**, dogfood against the live stub fleet; webUI deferred to Phase 5.
 - Runtimes: fleet agents default to **Codex / pi-on-Codex**; **Claude is reserved for Claude
   Code only** (avoid alternate-harness API pricing). Validated durable recipe:
-  `mosaic yolo pi --model openai-codex/gpt-5.5:high`. Durable detached launch requires the
+  mosaic yolo pi --model openai-codex/gpt-5.5:high. Durable detached launch requires the
   runtime-bin on PATH (baked into the pane command) + boot-survival (`enable` + linger),
-  which `fleet init` should automate.
+  which fleet init should automate.
 
 ## Decisions of record (2026-06-22, with Jason)
 
@@ -304,19 +304,18 @@ re-evaluate if isolation or write-volume demands it.
 - **Session context cap = 200k tokens (GLOBAL to all Claude sessions):** Claude Code sessions are
   capped at a **max 200k-token context window**. Long-running sessions extended toward 1M tokens
   have proven **worse in practice** (degraded steering, off-plan divergence); 200k is the standard.
-  **Enforcement split:** the _window_ lives in **`~/.claude/settings.json`** (host-global) as
-  `"autoCompactWindow": 200000` + `"autoCompactEnabled": true`; the _1M-disable_ lives in **launch
+  **Enforcement split:** the _window_ lives in **~/.claude/settings.json** (host-global) as
+  "autoCompactWindow": 200000 + "autoCompactEnabled": true; the _1M-disable_ lives in **launch
   ENV** (`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, plus `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`) wherever
-  a `[1m]` model can be selected (`mos-claude.service` + the fleet Claude launcher), so every Claude
+  a [1m] model can be selected (`mos-claude.service` + the fleet Claude launcher), so every Claude
   agent is capped at spawn. (settings = window; env = 1M-disable.)
 - **Worker context bound (#8):** workers are kept context-bounded via the **ephemeral-per-lane
   lifecycle + native compaction**, not via the 200k knob. The explicit `autoCompactWindow` 200k knob
   **stays Claude-specific** — the _principle_ (bounded context) extends to workers, the _knob_ does not.
 - **Orchestrator delegation discipline:** the orchestrator **delegates all delivery work** to
-  subagents / workflows / ultracode / coder agents and confines its own context to \*\*orchestration
-  - the personal-assistant lane\*\*. Keeping delivery out of the orchestrator's window keeps its
-    context unpolluted and measurably reduces off-plan divergence. The orchestrator coordinates and
-    decides; it does not implement.
+  subagents / workflows / ultracode / coder agents and confines its own context to the personal-assistant
+  lane. Keeping delivery out of the orchestrator's window keeps its context unpolluted and measurably
+  reduces off-plan divergence. The orchestrator coordinates and decides; it does not implement.
 - **Budget governance is fleet doctrine:** token/API-dollar budgeting is a first-class fleet concern
   (see "Budget & token governance"). OAuth-sub usage-vs-limit feedback is ingested per account, spend
   is **auto-paced EVEN-SPREAD over remaining time** (rapid/overspend only on explicit authorization),
@@ -344,7 +343,7 @@ re-evaluate if isolation or write-volume demands it.
 ### Control plane & central register
 
 - **Store:** Postgres (existing stack instance, dedicated `fleet` schema via `@mosaicstack/db`). SQLite rejected: (1) it is a local file — structurally incompatible with a multi-host fleet; (2) concurrent multi-agent writes caused repeated corruption in Hermes. "SQLite + access service" rejected as reinventing a DB server badly; "LLM agent gating DB access" rejected as slow, expensive, and a single point of failure.
-- **Access:** gateway API only (`apps/gateway`, `fleet/*` routes). No raw DB credentials in any agent/dispatcher pane — directly mitigates the tmux attack-surface concern.
+- **Access:** gateway API only (`apps/gateway`, fleet/\* routes). No raw DB credentials in any agent/dispatcher pane — directly mitigates the tmux attack-surface concern.
 - **Dispatcher = forge (reuse, not a new build):** the dispatcher IS `@mosaicstack/forge`'s pipeline engine (`runPipeline`/`resumePipeline` + brief classifier + BOD persona loader), a fully-implemented software-factory pipeline (brief → BOD review → 3 planning stages → coding → review/remediation → testing → deploy). We do **not** design/build a new dispatcher and do **not** re-implement sequencing, gate logic, or brief classification. The only new fleet-owned piece is a thin **`forge-exec` TaskExecutor adapter** (suggested package `packages/forge-exec`) mapping a `ForgeTask` → `agent-send.sh` dispatch to a named fleet agent — forge's single missing piece. It is tracked as a Gitea issue and built **post-PoC** (not now).
 - **Register backs forge:** the Postgres `fleet` register is genuinely new (neither forge nor the fleet has cross-project state). It BACKS forge's pipeline state (durable `resumePipeline`, cross-host) plus cross-project missions/tasks/Kanban.
 - **'board' role = forge BOD:** the north-star role-library 'board' role IS forge's Board-of-Directors — reused, not reinvented.
@@ -357,9 +356,9 @@ re-evaluate if isolation or write-volume demands it.
 
 - **Per-agent model switch (operator-configurable, NOT a global lock):** model selection is
   **per-agent**, never a host-global pin. Claude sessions MUST NOT be locked to a single model in
-  `~/.claude/settings.json`; each agent chooses its model independently. The plumbing already exists —
-  roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends `--model <hint>` to that
-  agent's harness (claude or pi); settable today via `mosaic fleet add|edit <agent> --model <hint>`.
+  ~/.claude/settings.json; each agent chooses its model independently. The plumbing already exists —
+  roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends --model <hint> to that
+  agent's harness (claude or pi); settable today via mosaic fleet add|edit <agent> --model <hint>.
   **North-star target:** surface this as a **per-agent model switch in the webUI** (with CLI/TUI parity
   per MVP-X1) — read the roster, expose a per-agent model dropdown, write `model_hint` back, and restart
   that one agent to apply. Unset = inherit the harness default. This **composes with** the budget
@@ -385,7 +384,7 @@ re-evaluate if isolation or write-volume demands it.
   self-hosted homeserver (Conduit default, Synapse alt). Matrix is named here as the strategic
   future transport — peer to tmux/Discord, not superseded by them.
 - **tmux fleet attack-surface hardening.** Many always-on tmux sessions are an attack surface;
-  `tmux send-keys` / socket access could enable malicious action against agents directly.
+  tmux send-keys / socket access could enable malicious action against agents directly.
   Mitigations to build toward: socket ownership/perms, per-tenant socket isolation (already an
   invariant), authenticated `agent-send`, and an audit of who can write to any pane. **Post-MVP
   unless a P0 surfaces.** The control-plane register reinforces this (gateway-API access = no raw
@@ -418,9 +417,9 @@ re-evaluate if isolation or write-volume demands it.
 
 ---
 
-> **Release procedure (drift re-capture, 2026-06-22):** `mosaic update` only propagates new fleet
+> **Release procedure (drift re-capture, 2026-06-22):** mosaic update only propagates new fleet
 > commands when the **CLI version is bumped** — without a version bump, fleet command changes never
-> reach installed hosts. The release/version-bump procedure (bump → publish → `mosaic update`
+> reach installed hosts. The release/version-bump procedure (bump → publish → mosaic update
 > [→ `--relaunch`]) must be documented so fleet changes actually land. (Also feeds the budgeting
 > workstream.)
 >

docs/fleet/operations/backup-restore.md

@@ -30,7 +30,7 @@ connector entry.
 
 The preview evidence deliberately records:
 
-- `executable: false`;
+- executable: false;
 - required backup artifacts;
 - source and candidate identities;
 - lifecycle observations and resulting desired states;