lease probe: fix the same 2s budget on the activation half

The enforcement half was fixed in 9efd903c. The activation half
(`defaultCapabilityProbe`) had the identical hardcoded 2000 ms budget
against the identical CLI boot, so half the defect was still shipping.

Measured cost of the exact call this makes: 1.04-1.11 s on an idle
developer host against `node -e 0` at 0.055 s, and 3.0-3.7 s on a 4-core
VM / 3.55-3.61 s on web1 when reached through the `mosaic` shim. The
budget was below the real cost on two production hosts and inside the
noise band on a third.

Because the probe is fail-closed, an expiry is indistinguishable from
"this build has no activation capability", so it surfaced as a
framework/CLI version-skew error that no upgrade could satisfy.

This was not theoretical: install-ordering-guard.spec.ts failed
intermittently in the full suite (3819 ms) while passing alone (2199 ms)
— the budget expiring under parallel load. That failure is gone.

- named constant + env override, mirroring the enforcement half
- override rejects non-finite/non-positive values rather than unbounding
  the probe, so a bad value cannot hang a launch
- a test asserts the two halves stay numerically equal, so the tighter
  one can never silently become the real budget again

Verified: build rc=0; new tests red against the old constant (2 fail),
green after; full vitest down to the 4 pre-existing
mutator-gate.acceptance failures that are also red on origin/main.

.woodpecker/ci.yml

@@ -46,6 +46,28 @@ steps:
       # [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
+      # Tool-index gate: a shipped wrapper that appears in no resident index doc
+      # is undiscoverable from inside a session, and an agent that cannot learn a
+      # wrapper exists reaches for raw curl instead — which is how a Gitea review
+      # got filed PENDING three times. Ships-and-documented is one commit, or red.
+      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh --self-test
+      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh
+      # Hermetic regression for issue-close.sh (#1081): mocks tea/curl onto PATH
+      # and sandboxes a throwaway git repo, so it resolves no real credentials and
+      # joins CI directly rather than the exclusions file.
+      - bash packages/mosaic/framework/tools/git/test-issue-close-fail-closed.sh
+      # Hermetic behavioural regression for the PreToolUse wrapper guard: proves
+      # it still blocks the three mistakes AND still lets reads, unwrapped
+      # endpoints and ordinary commands through. Both directions are asserted —
+      # a guard that over-blocks gets routed around, which fails just as hard.
+      - bash packages/mosaic/framework/tools/git/test-wrapper-guard.sh
+      # Hermetic regression for mosaic-worktree.sh at fleet scale: stubs git onto
+      # PATH so `list` faces ~450 KB of porcelain. The defect it pins is invisible
+      # at small size — `git … | awk '…exit'` gives the producer SIGPIPE, which
+      # under `set -euo pipefail` aborts the caller silently with rc=141 and no
+      # output. A repo only reaches that once it has enough worktrees, so the
+      # stub supplies the scale instead of the host's own checkout.
+      - bash packages/mosaic/framework/tools/git/test-mosaic-worktree-large-repo.sh
 
   # Blocking gate (#791): a framework upgrade must never write or delete an
   # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
@@ -109,6 +131,16 @@ steps:
       # `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
+      # Pi runtime (Invariant R): invariant_r_unittest.py hard-requires an
+      # installed `pi` binary at exactly this measured version — the test
+      # boots Pi's real tool registry to prove the read-only carve-out
+      # resolves to real, unshadowed builtins, and fails loud (by design)
+      # when the runtime is absent or drifts. The canonical Pi is
+      # @earendil-works/[email protected] exactly (@mariozechner/* is
+      # embedded-legacy). Step-level install because ci-base image publishes
+      # are currently blocked on registry auth; fold into Dockerfile.ci once
+      # that is fixed, keeping this as a fast no-op guard.
+      - npm install -g @earendil-works/[email protected]
       # 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.
       - |

README.md

@@ -74,6 +74,14 @@ The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md
 
 Pi launches default to a token-lean skill posture: `mosaic pi` passes `--no-skills` so Pi does not preload every global skill description into the system prompt. Use `MOSAIC_PI_SKILL_MODE=all mosaic pi` for the legacy all-skills catalog, or `MOSAIC_PI_SKILL_MODE=discover mosaic pi` to let Pi use its native settings/project skill discovery.
 
+Mosaic also loads its Pi extensions from `~/.config/mosaic/runtime/pi/`. Inside Pi,
+`/goal set <statement>` starts a bounded persistent loop that checks every turn and successful
+compaction, requires two evidence-bearing completion reports, and can be inspected or stopped with
+`/goal status`, `/goal pause`, `/goal resume`, and `/goal cancel`. Controller-owned goal-state
+entries redact common credential shapes, but Pi's model/tool-call history is separate, so goals and
+evidence must never contain secrets or raw sensitive output. Mosaic does not install this extension
+into `~/.pi/agent/extensions/`.
+
 ### TUI & Gateway
 
 ```bash

REPORT-T1.md

@@ -0,0 +1,94 @@
+# T1 report: canonical ungated Claude base and lease overlay
+
+## Changed
+
+- Replaced `packages/mosaic/framework/runtime/claude/settings.json` with the canonical ungated base. It retains the model, QA hooks, plugins, command allowlist, permissions, and `mcpServers.sequential-thinking`.
+- Added `packages/mosaic/framework/runtime/claude/lease-overlay.json`. It contains only `hooks` and the six removed lease hook entries.
+- Added the byte-identical pre-split source fixture at `packages/mosaic/src/runtime/fixtures/claude-settings.gated.pre-split.json`.
+- Added `packages/mosaic/src/runtime/claude-settings-base.spec.ts`.
+
+`framework-manifest.txt` already declares `runtime/**`, so the new overlay is framework-owned and shipped without a manifest change.
+
+## Lease-hook enumeration
+
+The actual template has six lease hook entries, matching fred's refined boundary:
+
+1. `PreToolUse` matcher `.*`: `mutator-gate.py`
+2. `Stop`: one combined command containing `receipt-observer-client.py` then `promote-complete.py`
+3. `UserPromptSubmit` matcher `^/mosaic-promote$`: `promote-begin.py`
+4. `PreCompact`: `revoke-lease.py --reason pre-compact`
+5. `SessionStart` matcher `compact`: `revoke-lease.py --reason session-start-compact`
+6. `SessionStart` matcher `resume|clear`: `revoke-lease.py --reason session-start-rollover --bump-generation`
+
+There is no delta from the refined six-entry enumeration. The Stop entry contains the receipt-observer and promote-complete commands together, rather than as two separate hook objects.
+
+## Tests and checks
+
+`pnpm install --frozen-lockfile` was run first because `node_modules` was absent. It completed successfully.
+
+Red-first run before artifacts existed:
+
+```text
+RUN  v2.1.9 .../packages/mosaic
+❯ src/runtime/claude-settings-base.spec.ts (4 tests | 4 failed)
+× keeps every lease command out of the ungated base
+  → mutator-gate: expected true to be false
+× reconstructs the pre-split gated hooks while retaining the canonical MCP correction
+  → ENOENT: .../lease-overlay.json
+× ships sequential-thinking in the base
+  → expected undefined to deeply equal { 'sequential-thinking': ... }
+× limits the overlay to lease hook entries
+  → ENOENT: .../lease-overlay.json
+```
+
+Final focused acceptance run:
+
+```text
+RUN  v2.1.9 .../packages/mosaic
+✓ src/runtime/claude-settings-base.spec.ts (4 tests) 19ms
+Test Files  1 passed (1)
+Tests  4 passed (4)
+```
+
+`pnpm --filter @mosaicstack/mosaic lint` passed:
+
+```text
+> @mosaicstack/[email protected] lint
+> eslint src
+```
+
+`pnpm --filter @mosaicstack/mosaic typecheck` failed on pre-existing workspace resolution and unrelated package errors. The new spec no longer appears in the error list. Initial failures include missing `@mosaicstack/{brain,forge,log,macp,memory,queue,storage,quality-rails,db,config,prdy,types}` declarations, followed by existing `fleet-backlog.ts`, `gateway-doctor.ts`, and TUI implicit-`any` errors. Exit status: 2.
+
+A focused legacy consumer run confirms an existing assumption that `settings.json` itself is gated:
+
+```text
+pnpm --filter @mosaicstack/mosaic exec vitest run src/mutator-gate/mutator-gate.acceptance.spec.ts
+❯ src/mutator-gate/mutator-gate.acceptance.spec.ts (20 tests | 6 failed)
+× non-dangerous parser residual is denied by the global all-tools hook without a lease
+  → expected all-tools mutator-gate command in settings.json
+× Claude and Pi compaction observer wiring is complete and fail-closed
+  → expected PreCompact/SessionStart revoke-lease hooks in settings.json
+```
+
+The other four failures in that focused run reported `STALE_GENERATION` where the test expected `MUTATOR_UNVERIFIED`, plus one successful-gate assertion. I did not redesign this legacy suite because the task explicitly says to report consumers that assume the base is gated.
+
+## Consumers found
+
+Direct `runtime/claude/settings.json` path consumers found by the required repository grep:
+
+- `packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets`: copies the base to `~/.claude/settings.json`.
+- `packages/mosaic/src/commands/install-ordering-guard.ts` and `.spec.ts`: documentation and behavior assume the source embeds enforcement hooks.
+- `packages/mosaic/framework/tools/_scripts/test-install-ordering-guard.sh`: comments and assertions expect `mutator-gate.py` and `receipt-observer-client.py` in the base.
+- `packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts`: reads the base and asserts mutator, promotion, and compaction lease wiring.
+- `packages/mosaic/src/lease-broker/promotion_trigger_unittest.py`: reads the base and asserts promotion wiring.
+- `packages/mosaic/src/lease-broker/recovery_runtime_unittest.py`: reads the base.
+- `packages/mosaic/src/runtime/update-checker.ts` and `.spec.ts`: references the path in settings wiring/update checks.
+- Documentation-only references: `docs/compaction-refresh/probes/p6_constrained_recovery.py`, `docs/plans/agent-reflection-loop-PRD.md`, `docs/tasks/544-agent-reflection-loop.md`, and the framework QA documentation/scripts found by grep.
+
+I did not change these consumers. The install/link and lease acceptance consumers must be taught to select and compose `lease-overlay.json` when a gated promotion seat is requested. That composition behavior is outside T1.
+
+## Ambiguity handled
+
+The exact pre-split template fixture has no `mcpServers` key (SHA-256 `44e74ea1e9d424fffa020ee666402662ac856b88bf6ae7f3b8931eed29dc75a4`). The task simultaneously requires a byte-for-byte pre-split fixture, `mcpServers.sequential-thinking` in the base, and `deep-merge(base, overlay) == original`. Those three conditions cannot all hold because a merge cannot remove the required MCP key.
+
+The acceptance test preserves the exact fixture and asserts that the normalized merge equals the pre-split template plus the required canonical `mcpServers.sequential-thinking` correction. It verifies all original hook content is reconstructed and the base carries the required MCP. Production three-layer merge semantics remain W-F1 work.

REPORT-T2.md

@@ -0,0 +1,102 @@
+# REPORT-T2
+
+Date: 2026-08-13 11:29 CDT
+Branch: `feat/wf-fleet-t2-launch`
+Base: `216cd722`
+Issue: #1209
+
+## What changed
+
+- Added `mosaic fleet launch <name> [--dry-run]` in `packages/mosaic/src/commands/fleet-launch-command.ts` and registered it on the existing fleet command.
+- Added strict schema-one parsing for the user-owned `~/.mosaic/fleet/agents/<name>/profile.json`:
+  - required `schema` and `harness`
+  - default bundle `primary`
+  - optional `model`, `overlay`, `plugins`, `skills`, and string-valued `env`
+  - unknown-key refusal naming the key
+  - dedicated `SCHEMA_TOO_NEW` code and upgrade guidance
+- Added the three-layer settings composer. Objects merge recursively, scalars use the higher layer, arrays replace, and `null` deletes a key. The selected agent overlay defaults to no overlay when the profile field is absent.
+- Writes canonical merged settings to `<agent-home>/settings.json` and the future harvest comparison snapshot to `<agent-dir>/settings.generated.json`.
+- Resolves `primary` to its named bundle, reads an optional account email, and reports forms such as `primary -> fred_example.com ([email protected])`.
+- Validates credential targets with `lstat`, rejects symlink credential files, resolves and checks containment under the harness auth root, and refuses a real credential file at the seat-link path as first-auth state.
+- Installs selected plugin and skill entries as seat-local symlinks, prunes stale symlinks, and refuses real objects instead of deleting them.
+- Builds a declared seat environment with the harness home variable, `MOSAIC_AGENT_NAME`, and profile environment entries. Mechanical values override conflicting profile entries.
+- Extended `launch.ts` so `harnessHome()` accepts fleet context and remains the home-resolution seam. The fleet launcher uses the existing runtime preflight, prompt, ledger, lease-gated, and process execution path over a minimal ambient environment.
+- Added deterministic dry-run output containing source layers, merged settings, output and snapshot paths, resolved bundle, symlink plans, declared environment, and harness argv.
+- Added 17 focused tests, including the required merge, schema, A3, dry-run snapshot, managed-link, command dry-run, execution-seam, and non-zero failure cases.
+
+## Reconciliation decisions and contradictions
+
+### Prominent contradiction: roster registries do not contain the frozen launch schema
+
+The existing code has two other profile/registry concepts:
+
+- `fleet-profiles.ts` models system-type YAML roster templates. Its `FleetProfile` has no harness bundle, overlay, plugin, skill, or seat environment fields.
+- roster-v2 models topology and lifecycle. It requires class, provider, reasoning, tool policy, working directory, lifecycle, and launch-yolo fields that schema-one `profile.json` does not contain.
+
+Deriving a complete roster-v2 member from the frozen per-agent profile is therefore not possible without inventing values. Launch now reads only the per-agent `profile.json` and does not require roster-v2 or the legacy v1 roster. roster-v2 remains the existing lifecycle/topology registry. No second launch registry was introduced.
+
+The pre-existing `resolveFleetIdentity()` path requires a legacy roster and a secure tmux helper whenever `MOSAIC_AGENT_NAME` is present during contract composition. For profile-backed launch, `launch.ts` excludes roster identity keys only from the contract-build environment, then exports the declared profile seat identity to the harness process. Legacy root runtime launches retain the existing roster-backed behavior. This is the smallest reconciliation that allows profile-only launch without fabricating roster-v2 fields.
+
+### Historical whole-store plugin link
+
+The prototype used a whole `plugins` directory symlink, while this task requires selected entry links and pruning. Launch refuses that historical shape with an explicit migration message. It does not delete or silently convert the whole-store link.
+
+### Existing `FleetProfile` name
+
+The system-type YAML `FleetProfile` remains unchanged. The new type is named `FleetAgentLaunchProfile` to keep the concepts separate while treating per-agent `profile.json` as the launch SSOT.
+
+## Ambiguities and bounded choices
+
+- The design does not freeze the generated snapshot filename. This implementation uses `settings.generated.json` in the agent directory, beside the hidden harness home.
+- The design explicitly identifies Claude `.credentials.json` and Pi `auth.json`. Codex and OpenCode use `auth.json` in the filename map, matching their harness-home composition shape, but no real credential launch was performed in this task.
+- Full interactive harvest-back disposition is not implemented. The task asks to store the generated snapshot for the future diff, and this change does that.
+- A machine descriptor file and content digests were not added. Dry-run and execution consume one resolved in-memory composition, and dry-run prints that composition.
+- No real harness process or real operator home was used. Every new filesystem test uses a temporary fixture root.
+
+## Test run
+
+Dependency install and build:
+
+```text
+$ pnpm install --frozen-lockfile
+Scope: all 28 workspace projects
+Lockfile is up to date, resolution step is skipped
+Done in 4.7s using pnpm v10.6.2
+
+$ pnpm --filter @mosaicstack/mosaic... build
+Scope: 13 of 28 workspace projects
+packages/mosaic build: Done
+```
+
+Focused and touched integration tests:
+
+```text
+$ pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet-launch-command.spec.ts src/commands/launch.spec.ts src/commands/fleet.spec.ts
+Test Files  3 passed (3)
+Tests       256 passed (256)
+```
+
+Typecheck and lint:
+
+```text
+$ pnpm --filter @mosaicstack/mosaic typecheck
+> tsc --noEmit
+(exit 0)
+
+$ pnpm exec eslint packages/mosaic/src/commands/fleet-launch-command.ts packages/mosaic/src/commands/fleet-launch-command.spec.ts packages/mosaic/src/commands/launch.ts packages/mosaic/src/commands/fleet.ts packages/mosaic/src/commands/fleet.spec.ts
+(exit 0)
+
+$ pnpm exec prettier --check packages/mosaic/src/commands/fleet-launch-command.ts packages/mosaic/src/commands/fleet-launch-command.spec.ts packages/mosaic/src/commands/launch.ts packages/mosaic/src/commands/fleet.ts packages/mosaic/src/commands/fleet.spec.ts
+Checking formatting...
+All matched files use Prettier code style!
+```
+
+Package-wide Vitest result:
+
+```text
+$ pnpm --filter @mosaicstack/mosaic exec vitest run
+Test Files  1 failed | 83 passed (84)
+Tests       4 failed | 1535 passed (1539)
+```
+
+All four failures are in `src/mutator-gate/mutator-gate.acceptance.spec.ts`. Three expected `MUTATOR_UNVERIFIED` but received `STALE_GENERATION`; one runtime-gate assertion expected status zero and received status two. An isolated rerun produced the same four failures. I did not confirm whether they predate this branch. The focused launch, fleet, and typecheck runs are green.

REPORT-T3.md

@@ -0,0 +1,46 @@
+# T3 report: `mosaic fleet agent new`
+
+## Changed
+
+- Added `packages/mosaic/src/fleet/fleet-agent-scaffold.ts`.
+  - Creates user-owned seats at `~/.mosaic/fleet/agents/<name>` (test seam: `fleetDataHome`, environment default: `MOSAIC_DATA_HOME`).
+  - Writes schema-one `profile.json` with default `harness: "claude"`, `bundle: "primary"`, optional `model`, `overlay: "overlay.json"`, and mandatory `env.MOSAIC_AGENT_NAME`.
+  - Writes a positive `SOUL.md` identity and materializes that identity in `.claude/CLAUDE.md` or `.pi/AGENTS.md`.
+  - Writes `overlay.json` as `{}`. Claude homes get `.claude.json` with `hasCompletedOnboarding: true` and `theme: "dark"`. No settings file is composed.
+  - Creates the appropriate credential symlink (`.credentials.json` for Claude, `auth.json` for Pi), allowing an intentional dangling destination and reporting it at the command surface.
+  - Compares every existing object (including link targets as link text), succeeds only byte-identically, and otherwise refuses with the differing paths.
+- Added `packages/mosaic/src/commands/fleet-agent-scaffold-command.ts` and wired `fleet agent new <name> [--harness claude|pi] [--bundle B] [--model M]` in `packages/mosaic/src/commands/fleet.ts`.
+- Added `packages/mosaic/src/commands/fleet-agent-scaffold-command.spec.ts` with temp-root-only coverage: exact Claude/Pi layouts, literal quote/backtick/`$( )` handling, unsafe names and option failures, idempotence, changed-file refusal, and credential-link comparison.
+
+## Reconciliation
+
+`fleet-agent-crud-command.ts` currently registers roster-v2 `get/create/update/delete/plan` directly under `mosaic fleet`; it has no `agent new` command or profile schema. T3 adds an `agent` namespace for the profile-owned user-data scaffold and leaves roster-v2 CRUD unchanged.
+
+No roster projection is created. Current roster-v2 requires fields that cannot be derived from the new profile (`class`, provider, working directory, reasoning, tool policy, lifecycle), while no current `mosaic fleet launch <name>` consumes these profiles. Writing such a roster entry would create the forbidden second registry and invent semantics. The profile is therefore the sole state created here. When the launcher owns profile-to-roster projection, it must derive it there and emit the required actionable unscaffolded-name message.
+
+## Validation
+
+```text
+$ pnpm install --frozen-lockfile
+Done in 4.1s using pnpm v10.6.2
+
+$ pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet-agent-scaffold-command.spec.ts
+✓ src/commands/fleet-agent-scaffold-command.spec.ts (13 tests) 28ms
+Test Files  1 passed (1)
+Tests       13 passed (13)
+
+$ pnpm --filter @mosaicstack/mosaic exec eslint src/fleet/fleet-agent-scaffold.ts src/commands/fleet-agent-scaffold-command.ts src/commands/fleet-agent-scaffold-command.spec.ts src/commands/fleet.ts
+(exit 0)
+
+$ pnpm exec prettier --check packages/mosaic/src/fleet/fleet-agent-scaffold.ts packages/mosaic/src/commands/fleet-agent-scaffold-command.ts packages/mosaic/src/commands/fleet-agent-scaffold-command.spec.ts packages/mosaic/src/commands/fleet.ts
+All matched files use Prettier code style!
+
+$ git diff --check
+(exit 0)
+```
+
+`pnpm --filter @mosaicstack/mosaic typecheck` remains blocked by pre-existing unresolved workspace package entries (`@mosaicstack/brain`, `@mosaicstack/db`, `@mosaicstack/types`, and others). The typecheck output had no diagnostics naming T3 files. Running the pre-existing CRUD command spec is blocked by the same `@mosaicstack/db` Vite resolution failure through `fleet-backlog.ts`.
+
+## Skipped ambiguity
+
+The design asks for a generated harness-home `settings.json` as part of an earlier generic home-template description, but the task explicitly says composed settings are left to launch. T3 creates no `settings.json`; launch composition remains the owner.

apps/gateway/src/__tests__/conversation-persistence.test.ts

@@ -417,7 +417,7 @@ describe('ConversationsController — search endpoint', () => {
       },
     ];
     brain = createMockBrain({ searchResults });
-    controller = new ConversationsController(brain as never);
+    controller = new ConversationsController(brain as never, { runtimeMode: 'legacy' });
   });
 
   it('returns matching messages for a valid search query', async () => {
@@ -479,7 +479,7 @@ describe('ConversationsController — search endpoint', () => {
 describe('ConversationsController — message CRUD', () => {
   it('listMessages returns 404 when conversation is not owned by user', async () => {
     const brain = createMockBrain({ conversation: undefined });
-    const controller = new ConversationsController(brain as never);
+    const controller = new ConversationsController(brain as never, { runtimeMode: 'legacy' });
 
     await expect(controller.listMessages(CONV_ID, { id: USER_ID })).rejects.toBeInstanceOf(
       NotFoundException,
@@ -489,7 +489,7 @@ describe('ConversationsController — message CRUD', () => {
   it('listMessages returns the messages for an owned conversation', async () => {
     const msgs = [makeMessage('user', 'Test message'), makeMessage('assistant', 'Test reply')];
     const brain = createMockBrain({ conversation: makeConversation(), messages: msgs });
-    const controller = new ConversationsController(brain as never);
+    const controller = new ConversationsController(brain as never, { runtimeMode: 'legacy' });
 
     const result = await controller.listMessages(CONV_ID, { id: USER_ID });
 
@@ -500,7 +500,7 @@ describe('ConversationsController — message CRUD', () => {
 
   it('addMessage returns the persisted message', async () => {
     const brain = createMockBrain({ conversation: makeConversation() });
-    const controller = new ConversationsController(brain as never);
+    const controller = new ConversationsController(brain as never, { runtimeMode: 'legacy' });
 
     const result = await controller.addMessage(
       CONV_ID,

apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts

@@ -35,6 +35,25 @@ function payload(content: string, messageId: string, correlationId: string): Dis
   };
 }
 
+/**
+ * The chat runtime router must never be exercised on the Discord approval/stop control paths —
+ * those paths run entirely through the command-authorization, runtime-provider and durable-session
+ * dependencies. Placed in the gateway's chat-runtime-router slot (the former direct `AgentService`
+ * slot) so any accidental chat-runtime dispatch throws loudly instead of silently passing. Because
+ * approval/stop never resolve a chat runtime, this fixture is never triggered and the integration
+ * stays a GREEN cross-surface control.
+ */
+function failIfUsedChatRuntimeRouter() {
+  return {
+    onModuleInit: () => {
+      throw new Error('chat runtime router must not initialise on the Discord control path');
+    },
+    get active(): never {
+      throw new Error('chat runtime must not be resolved on the Discord approval/stop path');
+    },
+  };
+}
+
 function authorization(): CommandAuthorizationService {
   const entries = new Map<string, string>();
   return new CommandAuthorizationService(
@@ -113,7 +132,7 @@ describe('interaction Discord/CLI durable-session integration', () => {
       },
     );
     const gateway = new ChatGateway(
-      {} as never,
+      failIfUsedChatRuntimeRouter() as never,
       {} as never,
       {} as never,
       {} as never,

apps/gateway/src/__tests__/resource-ownership.test.ts

@@ -60,7 +60,7 @@ describe('Resource ownership checks', () => {
     // The repo enforces ownership via the WHERE clause; it returns undefined when the
     // conversation does not belong to the requesting user.
     brain.conversations.findById.mockResolvedValue(undefined);
-    const controller = new ConversationsController(brain as never);
+    const controller = new ConversationsController(brain as never, { runtimeMode: 'legacy' });
 
     await expect(controller.findOne('conv-1', { id: 'user-1' })).rejects.toBeInstanceOf(
       NotFoundException,

apps/gateway/src/agent/__tests__/session-ownership.test.ts

@@ -1,6 +1,8 @@
+import 'reflect-metadata';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import { Test, type TestingModule } from '@nestjs/testing';
 import { describe, expect, it, vi } from 'vitest';
 
 vi.mock('../agent.service.js', () => ({ AgentService: class AgentService {} }));
@@ -12,10 +14,25 @@ vi.mock('../routing/routing-engine.service.js', () => ({
 }));
 
 import { SessionsController } from '../sessions.controller.js';
+import { AgentService } from '../agent.service.js';
 import { ChatController } from '../../chat/chat.controller.js';
 import { ChatGateway } from '../../chat/chat.gateway.js';
 import type { AgentSession } from '../agent.service.js';
 import type { SessionInfoDto } from '../session.dto.js';
+import type { HarnessAdapter, HarnessConversationService } from '@mosaicstack/types';
+import { AuthGuard } from '../../auth/auth.guard.js';
+import { AUTH } from '../../auth/auth.tokens.js';
+import { BRAIN } from '../../brain/brain.tokens.js';
+import { CommandRegistryService } from '../../commands/command-registry.service.js';
+import { CommandExecutorService } from '../../commands/command-executor.service.js';
+import { RoutingEngineService } from '../routing/routing-engine.service.js';
+import { ChatRuntimeRouter } from '../../chat/chat-runtime-router.js';
+import { EmbeddedChatRuntime } from '../../chat/embedded-chat.runtime.js';
+import { ownConversation } from '../../chat/chat-runtime.js';
+import type { LegacyRuntimeStream } from '../../chat/chat-runtime.js';
+import { HarnessChatRuntime } from '../../chat/harness-chat.runtime.js';
+import { HarnessRegistry } from '../../harness/harness.registry.js';
+import { HARNESS_CONVERSATION_SERVICE_UNAVAILABLE } from '../../harness/harness.tokens.js';
 
 const USER_A = { id: 'user-a', tenantId: 'tenant-a' };
 const USER_B = { id: 'user-b', tenantId: 'tenant-b' };
@@ -74,6 +91,12 @@ function makeAgentSession(owner = USER_A): AgentSession {
   };
 }
 
+/**
+ * A shape-complete, non-throwing AgentService fake scoped so that USER_B (a foreign owner guessing
+ * USER_A's conversation id) is never granted the session. Because every method exists and no method
+ * throws for a wrong shape, production runs to its real ownership decision — the RED never comes from
+ * a `getSession is not a function` TypeError, only from a router-boundary/scope assertion mismatch.
+ */
 function makeScopedAgentService() {
   const foreign = makeAgentSession(USER_A);
   return {
@@ -87,7 +110,7 @@ function makeScopedAgentService() {
     getSession: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
       scope?.userId === USER_B.id ? undefined : foreign,
     ),
-    createSession: vi.fn().mockRejectedValue(new ForbiddenException('Session scope mismatch')),
+    createSession: vi.fn().mockRejectedValue(new NotFoundException('Session scope mismatch')),
     onEvent: vi.fn(() => vi.fn()),
     addChannel: vi.fn(),
     removeChannel: vi.fn(),
@@ -96,6 +119,201 @@ function makeScopedAgentService() {
   };
 }
 
+type ScopedAgentService = ReturnType<typeof makeScopedAgentService>;
+
+/**
+ * A structurally-complete harness conversation service that throws if any method is invoked.
+ * Fronted behind the legacy runtime's harness slot: the legacy path must never reach it.
+ */
+const failIfUsedConversationService = {
+  attach: () => {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+  detach: () => {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+  send: () => {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+
+  subscribeFrom: async function* () {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+} as unknown as HarnessConversationService;
+
+/** A structurally-complete, non-sentinel conversation service used to satisfy the pi-rpc readiness gate. */
+const boundConversationService = {
+  attach: () => Promise.reject(new Error('unused')),
+  detach: () => Promise.reject(new Error('unused')),
+  send: () => Promise.reject(new Error('unused')),
+
+  subscribeFrom: async function* () {
+    throw new Error('unused');
+  },
+} as unknown as HarnessConversationService;
+
+function registryWith(adapterIds: readonly string[]): HarnessRegistry {
+  const registry = new HarnessRegistry();
+  for (const id of adapterIds) {
+    registry.register({
+      id,
+      describe: () => Promise.reject(new Error('unused')),
+      catalog: () => Promise.reject(new Error('unused')),
+      create: () => Promise.reject(new Error('unused')),
+      resume: () => Promise.reject(new Error('unused')),
+    } as HarnessAdapter);
+  }
+  return registry;
+}
+
+/**
+ * Build the real legacy-mode {@link ChatRuntimeRouter} fronting a real {@link EmbeddedChatRuntime}
+ * that holds the scoped AgentService fake. This is the ONLY path server-derived scope may travel to
+ * reach an AgentService: controller/gateway → ChatRuntimeRouter → EmbeddedChatRuntime → AgentService.
+ * The `embeddedAgentService` handed here is a SEPARATE instance from the directly-injected fake, so a
+ * call landing on it proves the router-delegation redesign is live rather than the old direct path.
+ */
+function legacyRouterFronting(agentService: unknown): ChatRuntimeRouter {
+  const embedded = new EmbeddedChatRuntime(agentService as never);
+  const harness = new HarnessChatRuntime(failIfUsedConversationService);
+  const router = new ChatRuntimeRouter(
+    new HarnessRegistry(),
+    HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    embedded,
+    harness,
+    'legacy',
+  );
+  router.onModuleInit();
+  return router;
+}
+
+/**
+ * The AgentService method names the controller/gateway must NEVER drive on the runtime at the
+ * delegation boundary. An AgentService-shaped router shim (a method-for-method mirror) would record
+ * one of these instead of the frozen legacy op, so asserting their ABSENCE from the observed runtime
+ * call set defeats the shim on INVOCATION evidence — never satisfiable by dead source text.
+ */
+const FORBIDDEN_AGENT_OPS = [
+  'getSession',
+  'createSession',
+  'onEvent',
+  'addChannel',
+  'prompt',
+  'setThinking',
+  'abort',
+] as const;
+
+/**
+ * Wrap a real {@link ChatRuntimeRouter} in a call-recording Proxy. Every property access that yields
+ * an OWN/inherited callable is returned as a thin wrapper that appends the method name to `calls` at
+ * INVOCATION time and forwards to the real method (bound to the real target, so the router's internal
+ * delegation to the embedded runtime runs untouched below this boundary). Non-function and MISSING
+ * properties are returned verbatim via Reflect.get — the observer NEVER fabricates a value, returns a
+ * canned outcome, or delegates a not-yet-implemented named op, so it cannot itself become a shim.
+ *
+ * The result is a RUNTIME call set of exactly the methods the controller/gateway invoke ON the router
+ * at the delegation seam. Only an actual call can enter it; a dead method, comment, or string in the
+ * production source cannot. This replaces the earlier `source.toContain('<frozen op>')` proof — which
+ * a dead declaration could satisfy while production still executed a shim — with invocation evidence.
+ */
+function makeRecordingRouter(target: ChatRuntimeRouter, calls: string[]): ChatRuntimeRouter {
+  return new Proxy(target, {
+    get(t, prop) {
+      const value = Reflect.get(t, prop);
+      if (typeof value === 'function' && typeof prop === 'string') {
+        return (...args: unknown[]) => {
+          calls.push(prop);
+          return (value as (...a: unknown[]) => unknown).apply(t, args);
+        };
+      }
+      return value;
+    },
+  }) as ChatRuntimeRouter;
+}
+
+/**
+ * Real Nest DI dual-provider fixture (mirrors the blessed group-3 pattern in chat-security.test.ts).
+ *
+ * BOTH an `AgentService` provider (the FORBIDDEN direct dependency) and a `ChatRuntimeRouter` provider
+ * (fronting a real EmbeddedChatRuntime over a SEPARATE scoped AgentService) are registered. Production
+ * resolves whichever its constructor declares:
+ *   - RED today: the controller/gateway `@Inject(AgentService)` → the direct fake is consulted, the
+ *     router (and its embedded fake) is never reached.
+ *   - GREEN later: the controller/gateway inject `ChatRuntimeRouter` → the direct fake is never
+ *     touched (stays at zero) and scope is observed inside the embedded fake behind the router.
+ * The SAME test body reds today and greens later; a method-for-method AgentService shim on the router
+ * records a FORBIDDEN op (and never the frozen legacy op) in the observed runtime call set, and
+ * restoring the direct injection cannot satisfy the "direct fake at zero" / "embedded fake observed
+ * scope" / "frozen op invoked on the router" anchors. The router is wrapped by {@link
+ * makeRecordingRouter} so those anchors are runtime invocation evidence, not source substrings.
+ */
+function buildRestModule(
+  directAgentService: ScopedAgentService,
+  embeddedAgentService: ScopedAgentService,
+  routerCalls: string[],
+): Promise<TestingModule> {
+  return (
+    Test.createTestingModule({
+      controllers: [ChatController],
+      providers: [
+        { provide: AgentService, useValue: directAgentService },
+        {
+          provide: ChatRuntimeRouter,
+          useFactory: () =>
+            makeRecordingRouter(legacyRouterFronting(embeddedAgentService), routerCalls),
+        },
+      ],
+    })
+      // ChatController's @UseGuards(AuthGuard) is resolved during instance loading; AuthGuard injects
+      // AUTH, an HTTP-only concern never exercised by a direct handler call. Stub it so the graph
+      // resolves and the test reds on BEHAVIOUR, not on a DI collection error.
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: () => true })
+      .compile()
+  );
+}
+
+function buildGatewayModule(
+  directAgentService: ScopedAgentService,
+  embeddedAgentService: ScopedAgentService,
+  routerCalls: string[],
+): Promise<TestingModule> {
+  const brain = {
+    conversations: {
+      // The sender OWNS this durable conversation, so the browser-send admission gate lets the turn
+      // reach the router seam. Foreignness is asserted downstream at the in-memory agent session
+      // (getSession({USER_B}) -> undefined), not at durable admission — the admission-rejection
+      // property has its own dedicated coverage.
+      findById: vi.fn().mockResolvedValue({ id: CONVERSATION_ID, userId: USER_B.id }),
+      create: vi.fn().mockResolvedValue(undefined),
+      update: vi.fn().mockResolvedValue(undefined),
+      findMessages: vi.fn().mockResolvedValue([]),
+      addMessage: vi.fn().mockResolvedValue({ id: 'persisted-turn' }),
+    },
+  };
+  return Test.createTestingModule({
+    providers: [
+      ChatGateway,
+      { provide: AgentService, useValue: directAgentService },
+      { provide: AUTH, useValue: { api: { getSession: vi.fn().mockResolvedValue(null) } } },
+      { provide: BRAIN, useValue: brain },
+      { provide: CommandRegistryService, useValue: { getManifest: vi.fn().mockReturnValue([]) } },
+      { provide: CommandExecutorService, useValue: { execute: vi.fn() } },
+      {
+        provide: RoutingEngineService,
+        useValue: {
+          resolve: vi.fn().mockResolvedValue({ provider: 'test', model: 'test-model' }),
+        },
+      },
+      {
+        provide: ChatRuntimeRouter,
+        useFactory: () =>
+          makeRecordingRouter(legacyRouterFronting(embeddedAgentService), routerCalls),
+      },
+    ],
+  }).compile();
+}
+
 describe('TESS-M1-SEC-002 AgentService ownership boundary', () => {
   it('requires explicit owner+tenant scope on protected session operations', () => {
     const source = readFileSync(resolve('src/agent/agent.service.ts'), 'utf8');
@@ -152,50 +370,66 @@ describe('TESS-M1-SEC-002 REST session ownership and tenant binding', () => {
   });
 });
 
-describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding', () => {
-  it('does not send a prompt into another owner/tenant session by guessed conversationId', async () => {
-    const agentService = makeScopedAgentService();
-    const controller = new ChatController(agentService as never);
+describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding (router-delegated legacy runtime)', () => {
+  // TESS test A — REST /api/chat send. The genuine RED is the router-delegation redesign, not a slot
+  // swap: the forbidden directly-injected AgentService must go UNtouched while the server-derived
+  // scope is observed inside the real ChatRuntimeRouter → EmbeddedChatRuntime → AgentService path.
+  it('routes a REST send through completeLegacyRestTurn and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService(); // FORBIDDEN direct dependency
+    const embeddedAgentService = makeScopedAgentService(); // reached ONLY via router → embedded delegation
+    const routerCalls: string[] = []; // runtime call set observed AT the controller → router seam
+    const moduleRef = await buildRestModule(directAgentService, embeddedAgentService, routerCalls);
+    try {
+      const controller = moduleRef.get(ChatController, { strict: false });
 
-    await expect(
-      controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
-    ).rejects.toMatchObject({ status: 404 });
+      // Foreign ownership is denied (never resolves) — a control that holds today AND at GREEN.
+      await expect(
+        controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
+      ).rejects.toBeDefined();
 
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(agentService.prompt).not.toHaveBeenCalled();
+      // Soft anchors so EVERY anchor is evaluated under each mutation, not just the first to fail.
+
+      // RUNTIME anchor A1 — delegation: the controller must INVOKE the frozen legacy op on the router.
+      // Only an actual call enters routerCalls; a dead method/comment/string cannot. RED today (the
+      // controller @Inject(AgentService) and never calls the router). GREEN once it drives the op.
+      expect
+        .soft(routerCalls, 'controller must invoke completeLegacyRestTurn on the router')
+        .toContain('completeLegacyRestTurn');
+      // RUNTIME anchor A2 — nondelegation: the controller must not drive any AgentService-shaped op on
+      // the router. An AgentService-shaped router shim records one of these → RED, defeating the shim
+      // on invocation evidence (not source text). A dead named method added alongside the shim does not
+      // help: it is never invoked, so it never enters routerCalls while a forbidden op still does.
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      // RUNTIME anchor A3 — the forbidden directly-injected AgentService stays at zero (fails today;
+      // restoring the direct injection keeps it failing).
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      // RUNTIME anchor A4 — server-derived scope observed INSIDE the separate embedded fake behind the
+      // router (fails today; the router path is never taken).
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+
+      // Zero foreign mutation on either path (holds today and at GREEN).
+      expect.soft(directAgentService.prompt).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.prompt).not.toHaveBeenCalled();
+
+      // Defense-in-depth (NOT load-bearing; the runtime anchors above carry the anti-mask): the
+      // controller no longer declares the direct embedded AgentService dependency. A negative source
+      // check cannot be satisfied by dead text — it only fails when the injection is present.
+      const controllerSource = readFileSync(resolve('src/chat/chat.controller.ts'), 'utf8');
+      expect.soft(controllerSource).not.toContain('@Inject(AgentService)');
+    } finally {
+      await moduleRef.close();
+    }
   });
 });
 
-describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding', () => {
-  function makeGateway(agentService = makeScopedAgentService()) {
-    const brain = {
-      conversations: {
-        findById: vi.fn().mockResolvedValue(undefined),
-        create: vi.fn().mockResolvedValue(undefined),
-        update: vi.fn().mockResolvedValue(undefined),
-        findMessages: vi.fn().mockResolvedValue([]),
-        addMessage: vi.fn().mockResolvedValue(undefined),
-      },
-    };
-    const commandRegistry = { getManifest: vi.fn().mockReturnValue([]) };
-    const commandExecutor = { execute: vi.fn() };
-    const routingEngine = {
-      resolve: vi.fn().mockResolvedValue({ provider: 'test', model: 'test-model' }),
-    };
-    const gateway = new ChatGateway(
-      agentService as never,
-      {} as never,
-      brain as never,
-      commandRegistry as never,
-      commandExecutor as never,
-      routingEngine as never,
-    );
-    return { gateway, agentService };
-  }
-
+describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding (router-delegated legacy runtime)', () => {
   function makeSocket() {
     return {
       id: 'socket-b',
@@ -206,57 +440,519 @@ describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding', () =>
     };
   }
 
-  it('does not attach or send to another owner/tenant session by guessed conversationId', async () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
+  // TESS test B — WebSocket send/attach.
+  it('routes a WebSocket send through prepareLegacySocketTurn and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService();
+    const embeddedAgentService = makeScopedAgentService();
+    const routerCalls: string[] = [];
+    const moduleRef = await buildGatewayModule(
+      directAgentService,
+      embeddedAgentService,
+      routerCalls,
+    );
+    try {
+      const gateway = moduleRef.get(ChatGateway, { strict: false });
+      const socket = makeSocket();
 
-    await gateway.handleMessage(socket as never, {
-      conversationId: CONVERSATION_ID,
-      content: 'attach to foreign session',
-    });
+      await Promise.resolve(
+        gateway.handleMessage(socket as never, {
+          conversationId: CONVERSATION_ID,
+          content: 'attach to foreign session',
+        }),
+      ).catch(() => undefined);
 
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(agentService.onEvent).not.toHaveBeenCalled();
-    expect(agentService.addChannel).not.toHaveBeenCalled();
+      // RUNTIME anchor B1 — delegation: the gateway must invoke the frozen socket op on the router.
+      expect
+        .soft(routerCalls, 'gateway must invoke prepareLegacySocketTurn on the router')
+        .toContain('prepareLegacySocketTurn');
+      // RUNTIME anchor B2 — nondelegation: no AgentService-shaped op on the router (defeats the shim).
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      // RED anchor B3 — forbidden direct AgentService untouched (fails today, gateway injects it).
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      // RED anchor B4 — scope observed inside router → embedded delegation (fails today, never reached).
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+      // Foreign session gets zero lease/listener/channel/prompt on EITHER path (holds today and GREEN).
+      expect.soft(directAgentService.onEvent).not.toHaveBeenCalled();
+      expect.soft(directAgentService.addChannel).not.toHaveBeenCalled();
+      expect.soft(directAgentService.prompt).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.onEvent).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.addChannel).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.prompt).not.toHaveBeenCalled();
+      expect
+        .soft(socket.emit)
+        .toHaveBeenCalledWith(
+          'error',
+          expect.objectContaining({ conversationId: CONVERSATION_ID }),
+        );
+
+      // Defense-in-depth (NOT load-bearing): gateway no longer declares the direct dependency.
+      const gatewaySource = readFileSync(resolve('src/chat/chat.gateway.ts'), 'utf8');
+      expect.soft(gatewaySource).not.toContain('@Inject(AgentService)');
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  // TESS test C — WebSocket set:thinking.
+  it('routes set:thinking through setLegacyThinking and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService();
+    const embeddedAgentService = makeScopedAgentService();
+    const routerCalls: string[] = [];
+    const moduleRef = await buildGatewayModule(
+      directAgentService,
+      embeddedAgentService,
+      routerCalls,
+    );
+    try {
+      const gateway = moduleRef.get(ChatGateway, { strict: false });
+      const socket = makeSocket();
+
+      await Promise.resolve(
+        gateway.handleSetThinking(socket as never, {
+          conversationId: CONVERSATION_ID,
+          level: 'high',
+        }),
+      ).catch(() => undefined);
+
+      // RUNTIME anchor C1 — delegation: the gateway must invoke the frozen thinking op on the router.
+      expect
+        .soft(routerCalls, 'gateway must invoke setLegacyThinking on the router')
+        .toContain('setLegacyThinking');
+      // RUNTIME anchor C2 — nondelegation: no AgentService-shaped op on the router (defeats the shim).
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+      expect
+        .soft(socket.emit)
+        .toHaveBeenCalledWith(
+          'error',
+          expect.objectContaining({ conversationId: CONVERSATION_ID }),
+        );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  // TESS test D — WebSocket abort.
+  it('routes abort through abortLegacyTurn and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService();
+    const embeddedAgentService = makeScopedAgentService();
+    const routerCalls: string[] = [];
+    const moduleRef = await buildGatewayModule(
+      directAgentService,
+      embeddedAgentService,
+      routerCalls,
+    );
+    try {
+      const gateway = moduleRef.get(ChatGateway, { strict: false });
+      const socket = makeSocket();
+
+      await Promise.resolve(
+        gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID }),
+      ).catch(() => undefined);
+
+      // RUNTIME anchor D1 — delegation: the gateway must invoke the frozen abort op on the router.
+      expect
+        .soft(routerCalls, 'gateway must invoke abortLegacyTurn on the router')
+        .toContain('abortLegacyTurn');
+      // RUNTIME anchor D2 — nondelegation: no AgentService-shaped op on the router (defeats the shim).
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+      expect
+        .soft(socket.emit)
+        .toHaveBeenCalledWith(
+          'error',
+          expect.objectContaining({ conversationId: CONVERSATION_ID }),
+        );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  // TESS test E (genuine, unchanged) — pi-rpc browser-legacy refusal.
+  it('rejects a browser legacy raw message in pi-rpc mode with a fixed typed unsupported and executes nothing', async () => {
+    // pi-rpc: the harness runtime is live. The browser legacy `message` path is unsupported and
+    // must be refused with a fixed typed code, touching neither the embedded AgentService nor the
+    // harness conversation service.
+    const agentService = makeScopedAgentService();
+    const embedded = new EmbeddedChatRuntime(agentService as never);
+    const harnessConversation = {
+      attach: vi.fn(),
+      detach: vi.fn(),
+      send: vi.fn(),
+      subscribeFrom: vi.fn(),
+    };
+    const harness = new HarnessChatRuntime(harnessConversation as never);
+    const router = new ChatRuntimeRouter(
+      registryWith(['pi']),
+      boundConversationService,
+      embedded,
+      harness,
+      'pi-rpc',
+    );
+    router.onModuleInit();
+
+    const brain = {
+      conversations: {
+        findById: vi.fn().mockResolvedValue(undefined),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        findMessages: vi.fn().mockResolvedValue([]),
+        addMessage: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+    const gateway = new ChatGateway(
+      router as never,
+      {} as never,
+      brain as never,
+      { getManifest: vi.fn().mockReturnValue([]) } as never,
+      { execute: vi.fn() } as never,
+      { resolve: vi.fn() } as never,
+    );
+    const socket = {
+      id: 'socket-b',
+      connected: true,
+      data: { user: USER_B, session: { id: 'auth-session-b', userId: USER_B.id } },
+      emit: vi.fn(),
+      disconnect: vi.fn(),
+    };
+
+    await Promise.resolve(
+      gateway.handleMessage(socket as never, {
+        conversationId: CONVERSATION_ID,
+        content: 'route me',
+      }),
+    ).catch(() => undefined);
+
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ code: 'runtime_unsupported' }),
+    );
+    expect(agentService.getSession).not.toHaveBeenCalled();
     expect(agentService.prompt).not.toHaveBeenCalled();
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    expect(harnessConversation.attach).not.toHaveBeenCalled();
+    expect(harnessConversation.send).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Task-5 AMEND — embedded runtime lease lifecycle (G1) + ownership collapse (G5).
+// These drive the real EmbeddedChatRuntime directly over a shape-complete AgentService
+// fake (every touched method exists, so a RED can only come from behavior, never a
+// `getSession is not a function` TypeError). Ownership context is minted through the
+// real `ownConversation` factory — the only sanctioned way to reach a port op.
+// ---------------------------------------------------------------------------
+
+const EMBEDDED_SCOPE = { userId: USER_A.id, tenantId: USER_A.tenantId };
+const CONVERSATION_UNAVAILABLE_RESULT = {
+  ok: false,
+  code: 'conversation_unavailable',
+  retryable: false,
+} as const;
+
+/** A stream sink; `channelId` is server-derived, `onEvent` records nothing here. */
+function makeStream(): LegacyRuntimeStream {
+  return { channelId: 'websocket:test-1', onEvent: vi.fn() };
+}
+
+/**
+ * getSession → undefined (session missing), createSession → rejects with `err`. Exercises the
+ * `resolveOrCreate` collapse branch. `prompt` exists so its ABSENCE from the call record proves
+ * the turn short-circuited before any dispatch.
+ */
+function makeCollapsingAgentService(err: Error) {
+  return {
+    getSession: vi.fn(() => undefined),
+    createSession: vi.fn().mockRejectedValue(err),
+    onEvent: vi.fn(() => vi.fn()),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    prompt: vi.fn().mockResolvedValue(undefined),
+    recordTokenUsage: vi.fn(),
+  };
+}
+
+/** getSession → a live owned session, so `resolveOrCreate` succeeds and a lease is built. */
+function makeLeaseAgentService() {
+  const session = makeAgentSession(USER_A);
+  const unsubscribe = vi.fn();
+  const svc = {
+    getSession: vi.fn(() => session),
+    createSession: vi.fn(),
+    onEvent: vi.fn(() => unsubscribe),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    prompt: vi.fn().mockResolvedValue(undefined),
+    recordTokenUsage: vi.fn(),
+  };
+  return { svc, unsubscribe, session };
+}
+
+/**
+ * getSession → a live owned session (REST resolveOrCreate succeeds), onEvent returns a `detach`
+ * spy, and `prompt` REJECTS with a non-timeout error. Drives the REST-turn catch path so the single
+ * idempotent teardown must clear the 120s timeout and detach the listener exactly once.
+ */
+function makeRejectingPromptAgentService() {
+  const session = makeAgentSession(USER_A);
+  const detach = vi.fn();
+  const svc = {
+    getSession: vi.fn(() => session),
+    createSession: vi.fn(),
+    onEvent: vi.fn(() => detach),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    prompt: vi.fn().mockRejectedValue(new Error('agent backend exploded')),
+    recordTokenUsage: vi.fn(),
+  };
+  return { svc, detach };
+}
+
+describe('TESS Task-5 embedded ownership collapse (missing and foreign are indistinguishable, never throw)', () => {
+  const ctx = ownConversation(CONVERSATION_ID, EMBEDDED_SCOPE);
+
+  it('collapses a foreign (Forbidden) create to conversation_unavailable and never throws', async () => {
+    const svc = makeCollapsingAgentService(new ForbiddenException('foreign owner'));
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const result = await runtime.completeLegacyRestTurn(ctx, { content: 'take over' });
+
+    expect(result).toEqual(CONVERSATION_UNAVAILABLE_RESULT);
+    expect(svc.prompt).not.toHaveBeenCalled();
+  });
+
+  it('collapses a missing (NotFound) create to conversation_unavailable and never throws', async () => {
+    const svc = makeCollapsingAgentService(new NotFoundException('no such conversation'));
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const result = await runtime.completeLegacyRestTurn(ctx, { content: 'hello' });
+
+    expect(result).toEqual(CONVERSATION_UNAVAILABLE_RESULT);
+    expect(svc.prompt).not.toHaveBeenCalled();
+  });
+
+  it('returns the IDENTICAL collapse for foreign and missing so neither can be distinguished', async () => {
+    const foreign = new EmbeddedChatRuntime(
+      makeCollapsingAgentService(new ForbiddenException('foreign owner')) as never,
     );
+    const missing = new EmbeddedChatRuntime(
+      makeCollapsingAgentService(new NotFoundException('no such conversation')) as never,
+    );
+
+    const foreignResult = await foreign.completeLegacyRestTurn(ctx, { content: 'x' });
+    const missingResult = await missing.completeLegacyRestTurn(ctx, { content: 'x' });
+
+    expect(foreignResult).toEqual(missingResult);
+    expect(foreignResult).toEqual(CONVERSATION_UNAVAILABLE_RESULT);
   });
+});
+
+describe('TESS Task-5 embedded socket lease lifecycle (one-shot dispatch, idempotent dispose, partial-setup rollback)', () => {
+  const ctx = ownConversation(CONVERSATION_ID, EMBEDDED_SCOPE);
+
+  it('dispatches the turn exactly once; a second dispatch is a no-op turn_already_dispatched', async () => {
+    const { svc } = makeLeaseAgentService();
+    const runtime = new EmbeddedChatRuntime(svc as never);
 
-  it('does not mutate thinking level on another owner/tenant session', () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
+    const prepared = await runtime.prepareLegacySocketTurn(ctx, { content: 'first' }, makeStream());
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) throw new Error('prepareLegacySocketTurn should succeed');
+    const lease = prepared.value;
 
-    gateway.handleSetThinking(socket as never, { conversationId: CONVERSATION_ID, level: 'high' });
+    const first = await lease.dispatch();
+    expect(first).toEqual({ ok: true, value: undefined });
+    expect(svc.prompt).toHaveBeenCalledTimes(1);
 
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
+    const second = await lease.dispatch();
+    expect(second).toEqual({ ok: false, code: 'turn_already_dispatched', retryable: false });
+    // Zero additional effect — the second dispatch must not prompt again.
+    expect(svc.prompt).toHaveBeenCalledTimes(1);
+  });
+
+  it('disposes once; a second dispose is a silent no-op that never re-detaches or destroys the session', async () => {
+    const { svc, unsubscribe, session } = makeLeaseAgentService();
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const prepared = await runtime.prepareLegacySocketTurn(ctx, { content: 'x' }, makeStream());
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) throw new Error('prepareLegacySocketTurn should succeed');
+    const lease = prepared.value;
+
+    await lease.dispose();
+    await lease.dispose();
+
+    // Listener + channel torn down exactly once across two dispose calls.
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+    expect(svc.removeChannel).toHaveBeenCalledTimes(1);
+    // Disposal never terminates the underlying session or process.
+    expect(session.piSession.abort).not.toHaveBeenCalled();
+    expect(session.piSession.dispose).not.toHaveBeenCalled();
+  });
+
+  it('rolls back the acquired listener and returns a total safe failure when channel attach fails mid-setup', async () => {
+    const { svc, unsubscribe } = makeLeaseAgentService();
+    svc.addChannel = vi.fn(() => {
+      throw new Error('channel attach failed');
     });
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
-    );
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    // Must NOT throw out of the port — a partial setup collapses to a total safe failure.
+    const prepared = await runtime.prepareLegacySocketTurn(ctx, { content: 'x' }, makeStream());
+    expect(prepared.ok).toBe(false);
+    // Exactly what was acquired (the event listener) is rolled back.
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('TESS Task-5 embedded REST turn teardown (a prompt rejection frees the timer + listener exactly once)', () => {
+  const ctx = ownConversation(CONVERSATION_ID, EMBEDDED_SCOPE);
+
+  it('clears the 120s timeout and detaches the listener exactly once when prompt() rejects, leaving no timer to reject the abandoned done-promise later (Task 5 finding 6)', async () => {
+    const { svc, detach } = makeRejectingPromptAgentService();
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    // A rejected `done` promise firing after completeLegacyRestTurn has already returned would
+    // surface as an unhandledRejection — the leak this test fences. Capture any that escape.
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on('unhandledRejection', onUnhandled);
+    vi.useFakeTimers();
+    try {
+      const result = await runtime.completeLegacyRestTurn(ctx, {
+        content: 'trigger a backend failure',
+      });
+
+      // The rejection collapses to a total safe failure (not a timeout) — never throws out of the port.
+      expect(result).toEqual({ ok: false, code: 'operation_failed', retryable: false });
+      // The single idempotent dispose ran in the catch: listener detached exactly once.
+      expect(detach).toHaveBeenCalledTimes(1);
+
+      // dispose() cleared the REST timeout, so advancing far past it (120s) fires nothing: no second
+      // detach, and — the actual leak — no live timer left to reject the now-abandoned `done` promise.
+      vi.advanceTimersByTime(600_000);
+      expect(detach).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+    // Let any scheduled rejection surface on a real macrotask, then confirm none did.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.off('unhandledRejection', onUnhandled);
+    expect(unhandled).toHaveLength(0);
   });
+
+  it('bounds a hung prompt: when prompt() never settles and no agent_end arrives, the 120s timeout ends the turn with a timeout result and exactly one teardown, no unhandledRejection (Task 5 finding 6 — pending-prompt timeout)', async () => {
+    const session = makeAgentSession(USER_A);
+    const detach = vi.fn();
+    const svc = {
+      getSession: vi.fn(() => session),
+      createSession: vi.fn(),
+      onEvent: vi.fn(() => detach),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      // The prompt never resolves or rejects — a hung agent backend. Under the pre-fix sequential
+      // `await prompt()` the timer could never even be observed, so the turn hung forever.
+      prompt: vi.fn(() => new Promise<void>(() => undefined)),
+      recordTokenUsage: vi.fn(),
+    };
+    const runtime = new EmbeddedChatRuntime(svc as never);
 
-  it('does not terminate another owner/tenant session over WebSocket abort', async () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on('unhandledRejection', onUnhandled);
+    vi.useFakeTimers();
+    try {
+      const resultPromise = runtime.completeLegacyRestTurn(ctx, {
+        content: 'a prompt that never returns',
+      });
+      // No agent_end, prompt still pending: only the 120s timeout can end the turn. Promise.all
+      // installed a handler on `done` synchronously, so the timer bounds the turn while prompt hangs.
+      await vi.advanceTimersByTimeAsync(200_000);
+      const result = await resultPromise;
 
-    await gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID });
+      expect(result).toEqual({ ok: false, code: 'timeout', retryable: true });
+      // The single idempotent dispose ran on the timeout path: listener detached exactly once.
+      expect(detach).toHaveBeenCalledTimes(1);
+      // Advancing far past the deadline fires nothing more: dispose cleared the timer.
+      vi.advanceTimersByTime(600_000);
+      expect(detach).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.off('unhandledRejection', onUnhandled);
+    expect(unhandled).toHaveLength(0);
+  });
 
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
+  it('when the 120s timeout fires while prompt() is still pending, returns timeout with one teardown, and a later prompt rejection surfaces no unhandledRejection (Task 5 finding 6 — timeout/prompt race)', async () => {
+    const session = makeAgentSession(USER_A);
+    const detach = vi.fn();
+    let rejectPrompt: (reason: unknown) => void = () => undefined;
+    const prompting = new Promise<void>((_resolve, reject) => {
+      rejectPrompt = reject;
     });
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
-    );
+    const svc = {
+      getSession: vi.fn(() => session),
+      createSession: vi.fn(),
+      onEvent: vi.fn(() => detach),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt: vi.fn(() => prompting),
+      recordTokenUsage: vi.fn(),
+    };
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on('unhandledRejection', onUnhandled);
+    vi.useFakeTimers();
+    try {
+      const resultPromise = runtime.completeLegacyRestTurn(ctx, {
+        content: 'prompt settles after the deadline',
+      });
+      // The timeout wins the race while prompt is still pending.
+      await vi.advanceTimersByTimeAsync(200_000);
+      const result = await resultPromise;
+
+      expect(result).toEqual({ ok: false, code: 'timeout', retryable: true });
+      expect(detach).toHaveBeenCalledTimes(1);
+
+      // The prompt now rejects LATE — after the turn already returned its timeout result. Because
+      // Promise.all installed a rejection handler on `prompting` synchronously (the fix), this late
+      // rejection is already observed and must not escape as an unhandledRejection.
+      rejectPrompt(new Error('late backend failure'));
+    } finally {
+      vi.useRealTimers();
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.off('unhandledRejection', onUnhandled);
+    expect(unhandled).toHaveLength(0);
   });
 });

apps/gateway/src/app.module.ts

@@ -21,6 +21,7 @@ import { AdminModule } from './admin/admin.module.js';
 import { CommandsModule } from './commands/commands.module.js';
 import { PreferencesModule } from './preferences/preferences.module.js';
 import { GCModule } from './gc/gc.module.js';
+import { HarnessModule } from './harness/harness.module.js';
 import { ReloadModule } from './reload/reload.module.js';
 import { WorkspaceModule } from './workspace/workspace.module.js';
 import { QueueModule } from './queue/queue.module.js';
@@ -60,6 +61,7 @@ const federationEnabled = loadConfig(resolveGatewayConfigPath()).tier === 'feder
     PreferencesModule,
     CommandsModule,
     GCModule,
+    HarnessModule,
     QueueModule,
     ReloadModule,
     WorkspaceModule,

apps/gateway/src/chat/chat-runtime-router.spec.ts

@@ -0,0 +1,920 @@
+import 'reflect-metadata';
+import { Global, Module } from '@nestjs/common';
+import { Test, type TestingModule } from '@nestjs/testing';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import type { HarnessAdapter, HarnessConversationService } from '@mosaicstack/types';
+import { AgentService } from '../agent/agent.service.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { CommandsModule } from '../commands/commands.module.js';
+import { HarnessModule } from '../harness/harness.module.js';
+import { ChatModule } from './chat.module.js';
+import { ChatGateway } from './chat.gateway.js';
+import { HarnessRegistry } from '../harness/harness.registry.js';
+import {
+  HARNESS_CONVERSATION_SERVICE,
+  HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+  HARNESS_REGISTRY,
+  type HarnessConversationServiceBinding,
+} from '../harness/harness.tokens.js';
+import { ChatRuntimeRouter } from './chat-runtime-router.js';
+import {
+  ChatRuntimeUnavailableError,
+  ownConversation,
+  type ChatRuntime,
+  type ChatRuntimeMode,
+  type LegacyEmbeddedChatPort,
+  type LegacyRuntimeStream,
+  type LegacySessionPresentation,
+  type LegacySocketTurnLease,
+  type OwnedConversationContext,
+} from './chat-runtime.js';
+import { AppModule } from '../app.module.js';
+import { ProviderService } from '../agent/provider.service.js';
+
+/**
+ * Task Five, Step One (router). Proves the `ChatRuntimeRouter` resolves exactly one
+ * runtime by mode, fails closed at init when `pi-rpc` preconditions are unmet, and
+ * never downgrades `pi-rpc` to embedded execution. Red-first: the router is an
+ * unimplemented stub, so every behavioural assertion below fails until Step Three.
+ */
+
+const embedded: ChatRuntime = { kind: 'embedded' };
+const harness: ChatRuntime = { kind: 'harness' };
+
+/** A structurally-complete, non-sentinel conversation service. Its methods are never invoked here. */
+const boundConversationService = {
+  attach: () => Promise.reject(new Error('unused')),
+  detach: () => Promise.reject(new Error('unused')),
+  send: () => Promise.reject(new Error('unused')),
+
+  subscribeFrom: async function* () {
+    throw new Error('unused');
+  },
+} as unknown as HarnessConversationService;
+
+function registryWith(adapterIds: readonly string[]): HarnessRegistry {
+  const registry = new HarnessRegistry();
+  for (const id of adapterIds) {
+    registry.register({
+      id,
+      describe: () => Promise.reject(new Error('unused')),
+      catalog: () => Promise.reject(new Error('unused')),
+      create: () => Promise.reject(new Error('unused')),
+      resume: () => Promise.reject(new Error('unused')),
+    } as HarnessAdapter);
+  }
+  return registry;
+}
+
+function buildRouter(
+  mode: ChatRuntimeMode,
+  opts: { adapters: readonly string[]; service: HarnessConversationServiceBinding },
+): ChatRuntimeRouter {
+  return new ChatRuntimeRouter(registryWith(opts.adapters), opts.service, embedded, harness, mode);
+}
+
+/**
+ * Tear down a module that was deliberately driven to a fail-closed init.
+ * `NestApplicationContext.close()` re-awaits the module's `initializationPromise` before disposing
+ * (nest-application-context.js:127); when `init()` rejected, that await re-throws the SAME typed
+ * startup error, this time into teardown. Each caller here has already captured and asserted that
+ * exact `ChatRuntimeUnavailableError` via `initError`, so the re-throw is expected teardown noise —
+ * swallow ONLY that error, and surface anything else so a genuine teardown fault still fails loudly.
+ */
+async function closeIgnoringFailedInit(moduleRef: TestingModule): Promise<void> {
+  await moduleRef.close().catch((err: unknown) => {
+    if (err instanceof ChatRuntimeUnavailableError) return;
+    throw err;
+  });
+}
+
+describe('ChatRuntimeRouter', () => {
+  it('resolves only the harness runtime in pi-rpc mode when pi adapter and conversation service are present', () => {
+    const router = buildRouter('pi-rpc', {
+      adapters: ['pi'],
+      service: boundConversationService,
+    });
+
+    expect(() => router.onModuleInit()).not.toThrow();
+    expect(router.active).toBe(harness);
+    expect(router.active.kind).toBe('harness');
+  });
+
+  it('resolves only the embedded runtime in legacy mode and skips the pi preconditions', () => {
+    // Empty registry + unavailable service: legacy must ignore both and still start.
+    const router = buildRouter('legacy', {
+      adapters: [],
+      service: HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    });
+
+    expect(() => router.onModuleInit()).not.toThrow();
+    expect(router.active).toBe(embedded);
+    expect(router.active.kind).toBe('embedded');
+  });
+
+  it('fails closed at init when pi-rpc mode has no registered pi adapter', () => {
+    const router = buildRouter('pi-rpc', {
+      adapters: [],
+      service: boundConversationService,
+    });
+
+    expect(() => router.onModuleInit()).toThrow(ChatRuntimeUnavailableError);
+    try {
+      router.onModuleInit();
+      expect.unreachable('onModuleInit must throw when the pi adapter is absent');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ChatRuntimeUnavailableError);
+      expect((err as ChatRuntimeUnavailableError).reason).toBe('adapter_unavailable');
+      expect((err as ChatRuntimeUnavailableError).code).toBe('runtime_unsupported');
+    }
+  });
+
+  it('fails closed at init when pi-rpc mode has the unavailable conversation-service sentinel', () => {
+    const router = buildRouter('pi-rpc', {
+      adapters: ['pi'],
+      service: HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    });
+
+    try {
+      router.onModuleInit();
+      expect.unreachable('onModuleInit must throw when the conversation service is unbound');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ChatRuntimeUnavailableError);
+      expect((err as ChatRuntimeUnavailableError).reason).toBe('conversation_service_unavailable');
+      expect((err as ChatRuntimeUnavailableError).code).toBe('runtime_unsupported');
+    }
+  });
+
+  it('never falls back to embedded execution when pi-rpc preconditions are unmet', () => {
+    const router = buildRouter('pi-rpc', {
+      adapters: [],
+      service: HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    });
+
+    expect(() => router.onModuleInit()).toThrow(ChatRuntimeUnavailableError);
+    // A failed pi-rpc init must not silently expose the embedded runtime.
+    expect(() => router.active).toThrow();
+    let leaked: ChatRuntime | undefined;
+    try {
+      leaked = router.active;
+    } catch {
+      leaked = undefined;
+    }
+    expect(leaked).not.toBe(embedded);
+  });
+
+  it('exposes only fixed, browser-safe failure text (no raw provider or exception detail)', () => {
+    const router = buildRouter('pi-rpc', {
+      adapters: [],
+      service: boundConversationService,
+    });
+
+    try {
+      router.onModuleInit();
+      expect.unreachable('onModuleInit must throw');
+    } catch (err) {
+      const message = (err as ChatRuntimeUnavailableError).message;
+      expect(message).toBe(
+        'The pi-rpc chat runtime is unavailable: no "pi" harness adapter is registered.',
+      );
+      expect(message).not.toMatch(/Error:|\bat \b|node_modules|Symbol\(/);
+    }
+  });
+});
+
+/**
+ * Task Five, Step Three — legacy port operations fail closed under pi-rpc (direct valid-input).
+ *
+ * The unit suite above constructs the router but never invokes a legacy port operation, so the
+ * six per-operation inner `if (this.mode === 'pi-rpc')` guards are unexercised — a mutation that
+ * deletes one of them SURVIVES for lack of a test that drives that operation. This group closes
+ * that gap the right way: it drives each of the six operations DIRECTLY, in pi-rpc mode, with a
+ * valid branded {@link OwnedConversationContext} and valid input, against a recording embedded
+ * stub whose method returns a distinguishable `ok:true` success and increments a per-op counter.
+ *
+ * For each operation:
+ *  - pi-rpc test asserts the exact frozen `{ ok:false, code:'runtime_unsupported', retryable:false }`
+ *    result AND that the embedded stub was touched zero times (no effects);
+ *  - the paired legacy test proves that same stub method IS reached and returns its distinguishable
+ *    success when the mode does not refuse — so the pi-rpc zero-invocation assertion is meaningful,
+ *    not vacuously true because the stub could never be called.
+ *
+ * Deleting ONLY one operation's inner guard makes THAT operation's pi-rpc test behaviorally RED
+ * (the router returns the embedded `ok:true` value and records the call), with every outer guard
+ * and the other five inner guards intact. `next` is untouched; nothing here changes production.
+ */
+describe('ChatRuntimeRouter — legacy port ops fail closed under pi-rpc (Task Five, Step Three)', () => {
+  const RUNTIME_UNSUPPORTED = {
+    ok: false,
+    code: 'runtime_unsupported',
+    retryable: false,
+  } as const;
+
+  const PRESENTATION: LegacySessionPresentation = {
+    provider: 'embedded-provider',
+    modelId: 'embedded-model',
+    thinkingLevel: 'low',
+    availableThinkingLevels: ['low', 'high'],
+  };
+
+  const stream: LegacyRuntimeStream = {
+    channelId: 'websocket:test-socket',
+    onEvent: () => {},
+  };
+
+  const ctx = (): OwnedConversationContext =>
+    ownConversation('conversation-1', { userId: 'user-1', tenantId: 'tenant-1' });
+
+  /**
+   * Per-operation invocation counters with declared keys (not an index signature) so each
+   * `calls.<op>` is definitely `number` under `noUncheckedIndexedAccess`.
+   */
+  type LegacyPortCallCounts = {
+    completeLegacyRestTurn: number;
+    prepareLegacySocketTurn: number;
+    setLegacyThinking: number;
+    abortLegacyTurn: number;
+    applyLegacyModelOverride: number;
+    readLegacySessionPresentation: number;
+    dispatchVerifiedDiscordIngress: number;
+  };
+
+  /**
+   * An embedded port that records every invocation and returns a distinguishable `ok:true`
+   * value per operation. If a router op reaches it (its guard removed), both the recorded call
+   * count and the returned `ok:true` value diverge from the frozen `runtime_unsupported` result.
+   */
+  function recordingEmbeddedPort(): {
+    port: ChatRuntime & LegacyEmbeddedChatPort;
+    calls: LegacyPortCallCounts;
+  } {
+    const calls: LegacyPortCallCounts = {
+      completeLegacyRestTurn: 0,
+      prepareLegacySocketTurn: 0,
+      setLegacyThinking: 0,
+      abortLegacyTurn: 0,
+      applyLegacyModelOverride: 0,
+      readLegacySessionPresentation: 0,
+      dispatchVerifiedDiscordIngress: 0,
+    };
+    const lease: LegacySocketTurnLease = {
+      presentation: PRESENTATION,
+      dispatch: () => Promise.resolve({ ok: true, value: undefined }),
+      dispose: () => Promise.resolve(),
+    };
+    const port: ChatRuntime & LegacyEmbeddedChatPort = {
+      kind: 'embedded',
+      completeLegacyRestTurn: () => {
+        calls.completeLegacyRestTurn += 1;
+        return Promise.resolve({
+          ok: true,
+          value: { text: 'EMBEDDED-REST', presentation: PRESENTATION },
+        });
+      },
+      prepareLegacySocketTurn: () => {
+        calls.prepareLegacySocketTurn += 1;
+        return Promise.resolve({ ok: true, value: lease });
+      },
+      setLegacyThinking: () => {
+        calls.setLegacyThinking += 1;
+        return { ok: true, value: PRESENTATION };
+      },
+      abortLegacyTurn: () => {
+        calls.abortLegacyTurn += 1;
+        return Promise.resolve({ ok: true, value: undefined });
+      },
+      applyLegacyModelOverride: () => {
+        calls.applyLegacyModelOverride += 1;
+        return { ok: true, value: PRESENTATION };
+      },
+      readLegacySessionPresentation: () => {
+        calls.readLegacySessionPresentation += 1;
+        return { ok: true, value: PRESENTATION };
+      },
+      dispatchVerifiedDiscordIngress: () => {
+        calls.dispatchVerifiedDiscordIngress += 1;
+        return Promise.resolve({
+          ok: true,
+          value: {
+            presentation: PRESENTATION,
+            dispatch: () => Promise.resolve({ ok: true, value: undefined }),
+            dispose: () => Promise.resolve(),
+          },
+        });
+      },
+    };
+    return { port, calls };
+  }
+
+  function piRouter(port: ChatRuntime & LegacyEmbeddedChatPort): ChatRuntimeRouter {
+    return new ChatRuntimeRouter(
+      registryWith(['pi']),
+      boundConversationService,
+      port,
+      harness,
+      'pi-rpc',
+    );
+  }
+  function legacyRouter(port: ChatRuntime & LegacyEmbeddedChatPort): ChatRuntimeRouter {
+    return new ChatRuntimeRouter(
+      registryWith([]),
+      boundConversationService,
+      port,
+      harness,
+      'legacy',
+    );
+  }
+
+  // completeLegacyRestTurn ---------------------------------------------------
+  it('completeLegacyRestTurn refuses with runtime_unsupported and never touches embedded under pi-rpc', async () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = await piRouter(port).completeLegacyRestTurn(ctx(), { content: 'hello' });
+    expect(result).toEqual(RUNTIME_UNSUPPORTED);
+    expect(calls.completeLegacyRestTurn).toBe(0);
+  });
+  it('completeLegacyRestTurn delegates to embedded under legacy (guard is the sole gate)', async () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = await legacyRouter(port).completeLegacyRestTurn(ctx(), { content: 'hello' });
+    expect(result.ok).toBe(true);
+    expect(calls.completeLegacyRestTurn).toBe(1);
+  });
+
+  // prepareLegacySocketTurn --------------------------------------------------
+  it('prepareLegacySocketTurn refuses with runtime_unsupported and never touches embedded under pi-rpc', async () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = await piRouter(port).prepareLegacySocketTurn(
+      ctx(),
+      { content: 'hello' },
+      stream,
+    );
+    expect(result).toEqual(RUNTIME_UNSUPPORTED);
+    expect(calls.prepareLegacySocketTurn).toBe(0);
+  });
+  it('prepareLegacySocketTurn delegates to embedded under legacy (guard is the sole gate)', async () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = await legacyRouter(port).prepareLegacySocketTurn(
+      ctx(),
+      { content: 'hello' },
+      stream,
+    );
+    expect(result.ok).toBe(true);
+    expect(calls.prepareLegacySocketTurn).toBe(1);
+  });
+
+  // setLegacyThinking (sync) -------------------------------------------------
+  it('setLegacyThinking refuses with runtime_unsupported and never touches embedded under pi-rpc', () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = piRouter(port).setLegacyThinking(ctx(), 'high');
+    expect(result).toEqual(RUNTIME_UNSUPPORTED);
+    expect(calls.setLegacyThinking).toBe(0);
+  });
+  it('setLegacyThinking delegates to embedded under legacy (guard is the sole gate)', () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = legacyRouter(port).setLegacyThinking(ctx(), 'high');
+    expect(result.ok).toBe(true);
+    expect(calls.setLegacyThinking).toBe(1);
+  });
+
+  // abortLegacyTurn ----------------------------------------------------------
+  it('abortLegacyTurn refuses with runtime_unsupported and never touches embedded under pi-rpc', async () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = await piRouter(port).abortLegacyTurn(ctx());
+    expect(result).toEqual(RUNTIME_UNSUPPORTED);
+    expect(calls.abortLegacyTurn).toBe(0);
+  });
+  it('abortLegacyTurn delegates to embedded under legacy (guard is the sole gate)', async () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = await legacyRouter(port).abortLegacyTurn(ctx());
+    expect(result.ok).toBe(true);
+    expect(calls.abortLegacyTurn).toBe(1);
+  });
+
+  // applyLegacyModelOverride (sync) ------------------------------------------
+  it('applyLegacyModelOverride refuses with runtime_unsupported and never touches embedded under pi-rpc', () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = piRouter(port).applyLegacyModelOverride(ctx(), 'model-x');
+    expect(result).toEqual(RUNTIME_UNSUPPORTED);
+    expect(calls.applyLegacyModelOverride).toBe(0);
+  });
+  it('applyLegacyModelOverride delegates to embedded under legacy (guard is the sole gate)', () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = legacyRouter(port).applyLegacyModelOverride(ctx(), 'model-x');
+    expect(result.ok).toBe(true);
+    expect(calls.applyLegacyModelOverride).toBe(1);
+  });
+
+  // readLegacySessionPresentation (sync) -------------------------------------
+  it('readLegacySessionPresentation refuses with runtime_unsupported and never touches embedded under pi-rpc', () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = piRouter(port).readLegacySessionPresentation(ctx());
+    expect(result).toEqual(RUNTIME_UNSUPPORTED);
+    expect(calls.readLegacySessionPresentation).toBe(0);
+  });
+  it('readLegacySessionPresentation delegates to embedded under legacy (guard is the sole gate)', () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const result = legacyRouter(port).readLegacySessionPresentation(ctx());
+    expect(result.ok).toBe(true);
+    expect(calls.readLegacySessionPresentation).toBe(1);
+  });
+
+  // dispatchVerifiedDiscordIngress delegates in BOTH modes (embedded-only, no guard) ---------
+  it('dispatchVerifiedDiscordIngress delegates to embedded under pi-rpc (embedded-only, no mode guard)', async () => {
+    const { port, calls } = recordingEmbeddedPort();
+    const discordCtx = ctx() as unknown as Parameters<
+      ChatRuntimeRouter['dispatchVerifiedDiscordIngress']
+    >[0];
+    const result = await piRouter(port).dispatchVerifiedDiscordIngress(discordCtx, stream);
+    expect(result.ok).toBe(true);
+    expect(calls.dispatchVerifiedDiscordIngress).toBe(1);
+  });
+});
+
+/**
+ * Task Five, Step Two — group 1 (real Nest module-graph readiness).
+ *
+ * The unit suite above constructs the router directly. This group drives the SAME contract
+ * through a real NestJS graph: it imports the production `HarnessModule` (the proven-booting
+ * idiom from harness.controller.spec.ts) so the router resolves the REAL, empty `HarnessRegistry`
+ * via the real `HARNESS_REGISTRY` token, then runs the router's `OnModuleInit` through the Nest
+ * lifecycle (`moduleRef.init()`). Red-first: the router is an unimplemented stub whose
+ * `onModuleInit` throws a generic Error, so:
+ *   - readiness cases fail because the graph never comes up (init rejects), and
+ *   - fail-closed cases fail because a generic stub throw is NOT the SPECIFIC typed
+ *     `ChatRuntimeUnavailableError` (reason/code) the contract demands — a stub that
+ *     "throws anything" cannot mask these greens.
+ * The router is NOT wired into a production module yet, so it is provided here via a factory
+ * over the real registry token. Importing the real `ChatModule` bare is deliberately avoided:
+ * it injects `AgentService` without importing `AgentModule`, so its graph fails to RESOLVE — a
+ * collection/DI error, not a behavioural red. `next` is untouched; nothing here implements the router.
+ */
+describe('ChatRuntimeRouter — real Nest module-graph readiness (Task Five, Step Two group 1)', () => {
+  async function bootRouterGraph(
+    mode: ChatRuntimeMode,
+    opts: { adapters: readonly string[]; service: HarnessConversationServiceBinding },
+  ) {
+    const moduleRef = await Test.createTestingModule({
+      imports: [HarnessModule],
+      providers: [
+        {
+          provide: ChatRuntimeRouter,
+          useFactory: (registry: HarnessRegistry) =>
+            new ChatRuntimeRouter(registry, opts.service, embedded, harness, mode),
+          inject: [HARNESS_REGISTRY],
+        },
+      ],
+    })
+      // The imported HarnessModule's controllers reference AuthGuard (an HTTP-only concern,
+      // never exercised here); stub it so the graph resolves. The registry is NOT overridden —
+      // group 1 asserts against the genuine production HarnessRegistry.
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    // Resolve the production registry singleton and register the requested adapters ON IT, so
+    // the router (which injects the same singleton) sees them when its lifecycle hook runs.
+    const registry = moduleRef.get<HarnessRegistry>(HARNESS_REGISTRY, { strict: false });
+    for (const id of opts.adapters) {
+      registry.register({
+        id,
+        describe: () => Promise.reject(new Error('unused')),
+        catalog: () => Promise.reject(new Error('unused')),
+        create: () => Promise.reject(new Error('unused')),
+        resume: () => Promise.reject(new Error('unused')),
+      } as HarnessAdapter);
+    }
+    return moduleRef;
+  }
+
+  // Capture an init rejection without letting a resolved init masquerade as success.
+  const initError = (moduleRef: { init(): Promise<unknown> }): Promise<unknown> =>
+    moduleRef.init().then(
+      () => new Error('module init resolved but the contract requires it to reject'),
+      (err: unknown) => err,
+    );
+
+  it('brings the graph up and resolves only the harness runtime in pi-rpc mode (pi adapter + bound service)', async () => {
+    const moduleRef = await bootRouterGraph('pi-rpc', {
+      adapters: ['pi'],
+      service: boundConversationService,
+    });
+    try {
+      await moduleRef.init();
+      const router = moduleRef.get(ChatRuntimeRouter, { strict: false });
+      expect(router.active).toBe(harness);
+      expect(router.active.kind).toBe('harness');
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  it('brings the graph up in legacy mode over the REAL empty HarnessRegistry and resolves only the embedded runtime', async () => {
+    const moduleRef = await bootRouterGraph('legacy', {
+      adapters: [],
+      service: HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    });
+    try {
+      // Defense-in-depth: the production module wires the genuine registry, empty by default —
+      // guards against a test-double registry silently satisfying the readiness check.
+      const registry = moduleRef.get<HarnessRegistry>(HARNESS_REGISTRY, { strict: false });
+      expect(registry).toBeInstanceOf(HarnessRegistry);
+      expect(registry.list()).toHaveLength(0);
+
+      await moduleRef.init();
+      const router = moduleRef.get(ChatRuntimeRouter, { strict: false });
+      expect(router.active).toBe(embedded);
+      expect(router.active.kind).toBe('embedded');
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  it('fails closed at module init when pi-rpc mode has no registered pi adapter (specific typed error, not a stub throw)', async () => {
+    const moduleRef = await bootRouterGraph('pi-rpc', {
+      adapters: [],
+      service: boundConversationService,
+    });
+    try {
+      const err = await initError(moduleRef);
+      expect(err).toBeInstanceOf(ChatRuntimeUnavailableError);
+      expect((err as ChatRuntimeUnavailableError).reason).toBe('adapter_unavailable');
+      expect((err as ChatRuntimeUnavailableError).code).toBe('runtime_unsupported');
+    } finally {
+      await closeIgnoringFailedInit(moduleRef);
+    }
+  });
+
+  it('fails closed at module init when pi-rpc mode has the unavailable conversation-service sentinel', async () => {
+    const moduleRef = await bootRouterGraph('pi-rpc', {
+      adapters: ['pi'],
+      service: HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    });
+    try {
+      const err = await initError(moduleRef);
+      expect(err).toBeInstanceOf(ChatRuntimeUnavailableError);
+      expect((err as ChatRuntimeUnavailableError).reason).toBe('conversation_service_unavailable');
+      expect((err as ChatRuntimeUnavailableError).code).toBe('runtime_unsupported');
+    } finally {
+      await closeIgnoringFailedInit(moduleRef);
+    }
+  });
+
+  it('surfaces only fixed, browser-safe failure text when the graph fails closed (no stub/exception detail)', async () => {
+    const moduleRef = await bootRouterGraph('pi-rpc', {
+      adapters: [],
+      service: boundConversationService,
+    });
+    try {
+      const err = await initError(moduleRef);
+      expect(err).toBeInstanceOf(ChatRuntimeUnavailableError);
+      const message = (err as ChatRuntimeUnavailableError).message;
+      expect(message).toBe(
+        'The pi-rpc chat runtime is unavailable: no "pi" harness adapter is registered.',
+      );
+      expect(message).not.toMatch(/Error:|\bat \b|node_modules|Symbol\(|not implemented/);
+    } finally {
+      await closeIgnoringFailedInit(moduleRef);
+    }
+  });
+});
+
+/**
+ * Task Five, Step Two — group 1b (production ChatModule wiring, declaration proof).
+ *
+ * Correction #1 (Scrappy fe3e02) asked for a red that imports the real `ChatModule` and calls
+ * `module.init()`. Investigated and found impractical/masking-prone: `ChatModule` provides
+ * `ChatGateway`, whose 10-argument constructor injects app-global providers (AgentService, AUTH,
+ * BRAIN, RoutingEngineService) plus the Commands/GC/Mcp/Reload subsystems across a forwardRef
+ * cycle. Booting it in isolation is a full-app integration boot — "override only unrelated
+ * dependencies" balloons into faking ~4 subsystems, and `overrideProvider` cannot even grant the
+ * cross-module export-scope visibility ChatGateway needs (probe: `ChatGateway` unresolved at
+ * `CommandExecutorService`). That is exactly the STOP-and-return branch of the directive.
+ *
+ * The faithful, unmaskable cover instead of a fragile boot: read the PRODUCTION `ChatModule`'s own
+ * Nest `@Module` metadata to prove it DECLARES the exclusive router provider and imports the real
+ * `HarnessModule` (the genuine registry source). This inspects the actual module object — not
+ * source text, not a test factory — so nothing can mask it. Group 1 above separately proves the
+ * router RESOLVES against the real, empty `HarnessRegistry` through the Nest lifecycle; the union
+ * of the two covers "the router is wired through ChatModule to the real registry" without the
+ * impractical single-graph boot. RED today (ChatModule provides only ChatGateway and imports only
+ * CommandsModule); GREEN once Step Three registers the router and imports HarnessModule.
+ */
+describe('ChatModule production wiring (Task Five, Step Two group 1b — declaration proof)', () => {
+  // Unwrap a forwardRef(() => Module) import to the module it references; pass others through.
+  const resolveImport = (imp: unknown): unknown =>
+    imp &&
+    typeof imp === 'object' &&
+    typeof (imp as { forwardRef?: unknown }).forwardRef === 'function'
+      ? (imp as { forwardRef: () => unknown }).forwardRef()
+      : imp;
+
+  // A provider entry is either a class (shorthand) or a { provide, ... } object; take its token.
+  const providerToken = (provider: unknown): unknown =>
+    typeof provider === 'function' ? provider : (provider as { provide?: unknown })?.provide;
+
+  it('declares the exclusive ChatRuntimeRouter as a provider on the production ChatModule', () => {
+    const providers: unknown[] = Reflect.getMetadata('providers', ChatModule) ?? [];
+    expect(providers.map(providerToken)).toContain(ChatRuntimeRouter);
+  });
+
+  it('imports the real HarnessModule into the production ChatModule (registry source, not a test double)', () => {
+    const imports: unknown[] = Reflect.getMetadata('imports', ChatModule) ?? [];
+    expect(imports.map(resolveImport)).toContain(HarnessModule);
+  });
+});
+
+/**
+ * Task Five, Step Two — group 1c (bounded real-`ChatModule` boot).
+ *
+ * Scrappy adjudication d67d2b (option c): boot the ACTUAL production `ChatModule` as the SUT and
+ * assert the exclusive router resolves THROUGH it — the single-graph proof group 1 (router over the
+ * real registry) and group 1b (production-module metadata) each cover only a half of. The heavy,
+ * UNRELATED cycle is the only thing bounded away, per the established isolation pattern in
+ * `apps/gateway/src/agent/hermes-runtime-reachability.e2e.test.ts`:
+ *   - `CommandsModule` (drags the Commands <-> Reload <-> Chat forwardRef cycle plus GC/Mcp/queue)
+ *     is replaced wholesale with an empty module via `.overrideModule(...).useModule(...)`;
+ *   - `ChatGateway` (10-arg constructor, an HTTP/socket concern never exercised here) is replaced
+ *     with an inert value;
+ *   - the sole legacy-controller dependency, `AgentService`, is supplied by a tiny `@Global()` stub;
+ *   - the HTTP-only `AuthGuard` is stubbed.
+ * Nothing about the router, `HarnessModule`, the registry, or the conversation-service binding is
+ * faked in the production-legacy case — those are retrieved from the REAL `ChatModule` graph. Mode
+ * is driven only through the production `CHAT_HARNESS_RUNTIME` env contract (`resolveChatRuntimeMode`).
+ *
+ * Red-first: today `ChatModule` neither imports `HarnessModule` nor provides `ChatRuntimeRouter`, so
+ * the booted graph contains no router/registry/conversation-service tokens. `init()` may resolve
+ * (there is no router lifecycle hook yet to reject), so every case fails on the MISSING actual
+ * router/registry/service wiring — not on unrelated DI, which is bounded away. GREEN at Step Three
+ * once `ChatModule` imports `HarnessModule`, provides the exclusive router, and binds the
+ * conversation-service token (defaulting to the unavailable sentinel).
+ */
+describe('ChatModule bounded real boot (Task Five, Step Two group 1c)', () => {
+  // The unrelated heavy cycle, replaced wholesale — not stubbed provider-by-provider.
+  @Module({})
+  class EmptyCommandsModule {}
+
+  // The ONLY genuine legacy dependency of the real ChatController, supplied inertly and globally so
+  // the pre-refactor controller instantiates without dragging AgentModule into the graph.
+  @Global()
+  @Module({
+    providers: [{ provide: AgentService, useValue: {} }],
+    exports: [AgentService],
+  })
+  class LegacyControllerDepsModule {}
+
+  const ORIGINAL_RUNTIME_ENV = process.env['CHAT_HARNESS_RUNTIME'];
+  afterEach(() => {
+    if (ORIGINAL_RUNTIME_ENV === undefined) delete process.env['CHAT_HARNESS_RUNTIME'];
+    else process.env['CHAT_HARNESS_RUNTIME'] = ORIGINAL_RUNTIME_ENV;
+  });
+
+  /**
+   * Boot the real ChatModule with only the unrelated cycle bounded away. `mode` is set through the
+   * genuine production env contract before providers instantiate. The optional overrides replace
+   * the registry / conversation-service the router injects, exercising the pi-rpc precondition
+   * branches through the ACTUAL module (they are no-ops today because those tokens are not yet in
+   * the graph — which is exactly why the router-retrieval assertions go red).
+   */
+  async function bootChatModule(
+    mode: ChatRuntimeMode,
+    overrides: {
+      registryAdapters?: readonly string[];
+      conversationService?: HarnessConversationServiceBinding;
+    } = {},
+  ): Promise<TestingModule> {
+    if (mode === 'pi-rpc') process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    else delete process.env['CHAT_HARNESS_RUNTIME'];
+
+    let builder = Test.createTestingModule({
+      imports: [LegacyControllerDepsModule, ChatModule],
+    })
+      .overrideModule(CommandsModule)
+      .useModule(EmptyCommandsModule)
+      .overrideProvider(ChatGateway)
+      .useValue({})
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: () => true });
+
+    if (overrides.registryAdapters) {
+      builder = builder
+        .overrideProvider(HARNESS_REGISTRY)
+        .useValue(registryWith(overrides.registryAdapters));
+    }
+    if (overrides.conversationService !== undefined) {
+      builder = builder
+        .overrideProvider(HARNESS_CONVERSATION_SERVICE)
+        .useValue(overrides.conversationService);
+    }
+    return builder.compile();
+  }
+
+  // Capture an init rejection without letting a resolved init masquerade as success.
+  const initError = (moduleRef: TestingModule): Promise<unknown> =>
+    moduleRef.init().then(
+      () => new Error('module init resolved but the contract requires it to reject'),
+      (err: unknown) => err,
+    );
+
+  it('legacy mode: the actual router resolves the embedded runtime, the actual registry is empty, and the conversation-service token is the unavailable sentinel', async () => {
+    const moduleRef = await bootChatModule('legacy');
+    try {
+      await moduleRef.init();
+      const router = moduleRef.get(ChatRuntimeRouter, { strict: false });
+      expect(router.active.kind).toBe('embedded');
+
+      const registry = moduleRef.get<HarnessRegistry>(HARNESS_REGISTRY, { strict: false });
+      expect(registry).toBeInstanceOf(HarnessRegistry);
+      expect(registry.list()).toHaveLength(0);
+
+      const service = moduleRef.get<HarnessConversationServiceBinding>(
+        HARNESS_CONVERSATION_SERVICE,
+        {
+          strict: false,
+        },
+      );
+      expect(service).toBe(HARNESS_CONVERSATION_SERVICE_UNAVAILABLE);
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  it('pi-rpc mode over the REAL empty registry fails closed at init with the typed adapter-unavailable error', async () => {
+    const moduleRef = await bootChatModule('pi-rpc');
+    try {
+      const err = await initError(moduleRef);
+      expect(err).toBeInstanceOf(ChatRuntimeUnavailableError);
+      expect((err as ChatRuntimeUnavailableError).reason).toBe('adapter_unavailable');
+      expect((err as ChatRuntimeUnavailableError).code).toBe('runtime_unsupported');
+    } finally {
+      await closeIgnoringFailedInit(moduleRef);
+    }
+  });
+
+  it('pi-rpc mode with a pi adapter present but the sentinel conversation service fails closed with the typed conversation-service-unavailable error', async () => {
+    const moduleRef = await bootChatModule('pi-rpc', {
+      registryAdapters: ['pi'],
+      conversationService: HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    });
+    try {
+      const err = await initError(moduleRef);
+      expect(err).toBeInstanceOf(ChatRuntimeUnavailableError);
+      expect((err as ChatRuntimeUnavailableError).reason).toBe('conversation_service_unavailable');
+      expect((err as ChatRuntimeUnavailableError).code).toBe('runtime_unsupported');
+    } finally {
+      await closeIgnoringFailedInit(moduleRef);
+    }
+  });
+
+  it('pi-rpc mode with a pi adapter and a bound conversation service: the actual router selects the harness runtime', async () => {
+    const moduleRef = await bootChatModule('pi-rpc', {
+      registryAdapters: ['pi'],
+      conversationService: boundConversationService,
+    });
+    try {
+      await moduleRef.init();
+      const router = moduleRef.get(ChatRuntimeRouter, { strict: false });
+      expect(router.active.kind).toBe('harness');
+    } finally {
+      await moduleRef.close();
+    }
+  });
+});
+
+/**
+ * Task Five, Step Two — group 2 (WHOLE production `AppModule` boot, legacy end-to-end wiring).
+ *
+ * The groups above bound away the heavy cycle to isolate the router. This group instead boots the
+ * ACTUAL production `AppModule` (the exact graph `main.ts` runs) in the default LEGACY chat-runtime
+ * mode, overriding ONLY the storage/network side-effect adapters so the boot is bounded and offline
+ * — never the chat/router/harness/reload/commands surface under test. The bounded fakes are exactly
+ * the disk/network leaves:
+ *   - `ProviderService` (the #1 hang risk: its real `onModuleInit` starts an unref'd health-check
+ *     `setInterval` and fetches Ollama over HTTP) → inert no-op instance;
+ *   - `DB_HANDLE`/`DB` → a fake Drizzle-shaped handle that satisfies `runPgliteMigrations` (the local
+ *     tier's `DatabaseModule.onModuleInit`) AND `DefaultRoutingRulesSeed.onModuleInit` (which reads a
+ *     system-rule count — the fake reports rules already present so the seed insert is skipped),
+ *     opening no real database;
+ *   - `STORAGE_ADAPTER`/`MEMORY`/`MEMORY_ADAPTER`/`AUTH`/`BRAIN`/`LOG_SERVICE` → inert fakes so no
+ *     storage/auth/log backend is contacted.
+ * Local tier (the repo's `mosaic.config.json`) already disables BullMQ/Redis and the queue handles;
+ * Discord/Telegram/MCP plugins are env-gated and disarmed by deleting their tokens. Nothing about the
+ * router, `ChatModule`, `HarnessModule`, or `ChatGateway` is faked — those come from the REAL graph.
+ *
+ * The boot+init MUST SUCCEED cleanly (proven by `beforeAll` completing and the ChatGateway test
+ * passing). Red-first: on this branch `ChatRuntimeRouter` is registered in NO module (ChatModule
+ * provides only ChatGateway), so `moduleRef.get(ChatRuntimeRouter)` throws `UnknownElementException`
+ * — a WIRING gap, NOT an init failure. That single retrieval is the intended behavioural red; it
+ * flips green once Step Three registers the exclusive router. The ChatGateway retrieval and its
+ * browser-facing method surface are asserted alongside and pass today, pinning that the boot itself
+ * is healthy so the router failure cannot be mistaken for a mis-shaped fake or an unbounded side
+ * effect.
+ */
+describe('AppModule production boot — legacy ChatRuntimeRouter wiring (Task Five, Step Two group 2)', () => {
+  // A Drizzle-shaped fake that satisfies both DB consumers reached during a local-tier init:
+  //   • runPgliteMigrations(): reads handle.db.$client.exec + handle.db.execute(SELECT hashes);
+  //     exec is a no-op and execute yields an empty ledger, so migration statements no-op through.
+  //   • DefaultRoutingRulesSeed.seedDefaultRules(): db.select().from().where() must resolve to a
+  //     row set — we report a non-zero system-rule count so the seeding INSERT branch is skipped.
+  const fakeDb = {
+    $client: { exec: async (): Promise<void> => {} },
+    execute: async (): Promise<{ rows: unknown[] }> => ({ rows: [] }),
+    select: () => ({
+      from: () => ({
+        where: async (): Promise<Array<{ count: number }>> => [{ count: 1 }],
+      }),
+    }),
+    insert: () => ({ values: async (): Promise<void> => {} }),
+  };
+  const fakeDbHandle = { db: fakeDb, close: async (): Promise<void> => {} };
+  const fakeStorageAdapter = {
+    name: 'fake',
+    migrate: async (): Promise<void> => {},
+    close: async (): Promise<void> => {},
+  };
+  // Inert stand-in for the real ProviderService: no health-check interval, no Ollama fetch.
+  const fakeProviderService = {
+    onModuleInit: async (): Promise<void> => {},
+    onModuleDestroy: (): void => {},
+    getRegistry: () => ({
+      getAvailable: () => [],
+      getAll: () => [],
+      find: () => undefined,
+    }),
+    getDefaultModel: () => undefined,
+    listAvailableModels: () => [],
+    listProviders: () => [],
+    getAdapter: () => undefined,
+    getProvidersHealth: () => [],
+  };
+  const fakeBrain = { conversations: {}, agents: {} };
+
+  const BOOT_TIMEOUT_MS = 120_000;
+
+  let moduleRef: TestingModule;
+  let envSnapshot: Record<string, string | undefined>;
+
+  beforeAll(async () => {
+    envSnapshot = { ...process.env };
+    // Env hygiene: disarm the network-facing plugins/adapters and pin the legacy runtime mode.
+    delete process.env['DATABASE_URL'];
+    delete process.env['DISCORD_BOT_TOKEN'];
+    delete process.env['TELEGRAM_BOT_TOKEN'];
+    delete process.env['MCP_SERVERS'];
+    delete process.env['CHAT_HARNESS_RUNTIME']; // resolveChatRuntimeMode → 'legacy'
+    process.env['MOSAIC_STORAGE_TIER'] = 'local';
+
+    moduleRef = await Test.createTestingModule({ imports: [AppModule] })
+      // Storage/network side-effect adapters ONLY — never the router/chat/harness surface under test.
+      .overrideProvider('DB_HANDLE')
+      .useValue(fakeDbHandle)
+      .overrideProvider('DB')
+      .useValue(fakeDb)
+      .overrideProvider('STORAGE_ADAPTER')
+      .useValue(fakeStorageAdapter)
+      .overrideProvider('AUTH')
+      .useValue({})
+      .overrideProvider('BRAIN')
+      .useValue(fakeBrain)
+      .overrideProvider('LOG_SERVICE')
+      .useValue({})
+      .overrideProvider('MEMORY')
+      .useValue({})
+      .overrideProvider('MEMORY_ADAPTER')
+      .useValue({})
+      .overrideProvider(ProviderService)
+      .useValue(fakeProviderService)
+      .compile();
+
+    // The boot itself MUST succeed cleanly — a rejection here is a bounding failure, not the red.
+    await moduleRef.init();
+  }, BOOT_TIMEOUT_MS);
+
+  afterAll(async () => {
+    if (moduleRef) await moduleRef.close();
+    for (const key of Object.keys(process.env)) {
+      if (!(key in envSnapshot)) delete process.env[key];
+    }
+    for (const [key, value] of Object.entries(envSnapshot)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  // Passes TODAY: the real ChatGateway is provided by the real ChatModule and its browser-facing
+  // surface exists. This pins that the whole-AppModule boot came up healthy, so the router failure
+  // below is unambiguously a wiring gap and not a mis-shaped fake or an unbounded side effect.
+  it('boots the whole AppModule and exposes the real ChatGateway with its browser-facing methods', () => {
+    const gateway = moduleRef.get(ChatGateway, { strict: false });
+    expect(typeof gateway.broadcastReload).toBe('function');
+    expect(typeof gateway.getModelOverride).toBe('function');
+    expect(typeof gateway.setModelOverride).toBe('function');
+    expect(typeof gateway.broadcastSessionInfo).toBe('function');
+  });
+
+  // RED TODAY: ChatRuntimeRouter is registered in no module on this branch, so this retrieval throws
+  // UnknownElementException — the intended red-first wiring failure. GREEN once Step Three registers
+  // the exclusive router in the production graph, where legacy mode resolves the embedded runtime.
+  it('resolves the exclusive ChatRuntimeRouter to the embedded runtime in legacy mode', () => {
+    const router = moduleRef.get(ChatRuntimeRouter, { strict: false });
+    expect(router.active.kind).toBe('embedded');
+  });
+});

apps/gateway/src/chat/chat-runtime-router.ts

@@ -0,0 +1,173 @@
+import { Injectable, type OnModuleInit } from '@nestjs/common';
+import { HarnessRegistry } from '../harness/harness.registry.js';
+import {
+  isHarnessConversationServiceAvailable,
+  type HarnessConversationServiceBinding,
+} from '../harness/harness.tokens.js';
+import type {
+  ChatRuntime,
+  ChatRuntimeMode,
+  LegacyBrowserMessagePayload,
+  LegacyEmbeddedChatPort,
+  LegacyRuntimeResult,
+  LegacyRuntimeStream,
+  LegacySessionPresentation,
+  LegacySocketTurnLease,
+  OwnedConversationContext,
+  VerifiedDiscordIngressContext,
+  VerifiedDiscordTurnLease,
+} from './chat-runtime.js';
+import { ChatRuntimeUnavailableError, resolveChatRuntimeMode } from './chat-runtime.js';
+
+/** The fixed fail-closed result for a legacy browser operation issued under `pi-rpc`. */
+const RUNTIME_UNSUPPORTED = {
+  ok: false as const,
+  code: 'runtime_unsupported' as const,
+  retryable: false as const,
+};
+
+/**
+ * Resolves the one live {@link ChatRuntime} for this process and enforces the
+ * `pi-rpc` readiness preconditions at module init — before the gateway accepts
+ * traffic. It never falls back from `pi-rpc` to embedded execution: an unmet
+ * `pi-rpc` precondition is a typed startup failure ({@link ChatRuntimeUnavailableError}),
+ * and until `onModuleInit` selects a runtime, {@link active} throws rather than
+ * exposing any runtime — a failed `pi-rpc` init can never leak the embedded one.
+ */
+@Injectable()
+export class ChatRuntimeRouter implements OnModuleInit, LegacyEmbeddedChatPort {
+  private readonly mode: ChatRuntimeMode;
+
+  /** The single resolved runtime. Undefined until a successful `onModuleInit`. */
+  private resolved: ChatRuntime | undefined;
+
+  constructor(
+    private readonly harnessRegistry: HarnessRegistry,
+    private readonly conversationService: HarnessConversationServiceBinding,
+    private readonly embedded: ChatRuntime,
+    private readonly harness: ChatRuntime,
+    mode: ChatRuntimeMode = resolveChatRuntimeMode(),
+  ) {
+    this.mode = mode;
+  }
+
+  onModuleInit(): void {
+    if (this.mode === 'legacy') {
+      // Legacy ignores the pi-rpc preconditions entirely and always runs embedded.
+      this.resolved = this.embedded;
+      return;
+    }
+
+    // pi-rpc: both preconditions are hard startup failures, checked in a fixed order.
+    if (!this.harnessRegistry.has('pi')) {
+      this.resolved = undefined;
+      throw new ChatRuntimeUnavailableError('adapter_unavailable');
+    }
+    if (!isHarnessConversationServiceAvailable(this.conversationService)) {
+      this.resolved = undefined;
+      throw new ChatRuntimeUnavailableError('conversation_service_unavailable');
+    }
+
+    this.resolved = this.harness;
+  }
+
+  get active(): ChatRuntime {
+    if (this.resolved === undefined) {
+      // Reached only if init has not run or failed closed; never expose a runtime here.
+      throw new Error('The chat runtime is not available: startup did not resolve a runtime.');
+    }
+    return this.resolved;
+  }
+
+  /**
+   * The process-wide mode, available before {@link onModuleInit}. Production handlers read
+   * this to fail a legacy browser turn closed under `pi-rpc` *before* parsing the payload as
+   * either browser-legacy input or a Discord envelope — never to branch into a fallback.
+   */
+  get runtimeMode(): ChatRuntimeMode {
+    return this.mode;
+  }
+
+  /**
+   * The embedded runtime narrowed to its port. Only reached on the legacy path (and for the
+   * verified-Discord op in both modes), where the injected runtime is always a real
+   * `EmbeddedChatRuntime`. The router spec constructs the router with a bare `{ kind }` stub
+   * but never invokes a port op, so this narrowing is never exercised against the stub.
+   */
+  private get embeddedPort(): LegacyEmbeddedChatPort {
+    return this.embedded as unknown as LegacyEmbeddedChatPort;
+  }
+
+  // --- LegacyEmbeddedChatPort: legacy browser operations fail closed under pi-rpc ---
+
+  completeLegacyRestTurn(
+    context: OwnedConversationContext,
+    input: Readonly<{ content: string }>,
+  ): Promise<
+    LegacyRuntimeResult<Readonly<{ text: string; presentation: LegacySessionPresentation }>>
+  > {
+    if (this.mode === 'pi-rpc') {
+      return Promise.resolve(RUNTIME_UNSUPPORTED);
+    }
+    return this.embeddedPort.completeLegacyRestTurn(context, input);
+  }
+
+  prepareLegacySocketTurn(
+    context: OwnedConversationContext,
+    input: LegacyBrowserMessagePayload,
+    stream: LegacyRuntimeStream,
+  ): Promise<LegacyRuntimeResult<LegacySocketTurnLease>> {
+    if (this.mode === 'pi-rpc') {
+      return Promise.resolve(RUNTIME_UNSUPPORTED);
+    }
+    return this.embeddedPort.prepareLegacySocketTurn(context, input, stream);
+  }
+
+  setLegacyThinking(
+    context: OwnedConversationContext,
+    level: string,
+  ): LegacyRuntimeResult<LegacySessionPresentation> {
+    if (this.mode === 'pi-rpc') {
+      return RUNTIME_UNSUPPORTED;
+    }
+    return this.embeddedPort.setLegacyThinking(context, level);
+  }
+
+  abortLegacyTurn(context: OwnedConversationContext): Promise<LegacyRuntimeResult<void>> {
+    if (this.mode === 'pi-rpc') {
+      return Promise.resolve(RUNTIME_UNSUPPORTED);
+    }
+    return this.embeddedPort.abortLegacyTurn(context);
+  }
+
+  applyLegacyModelOverride(
+    context: OwnedConversationContext,
+    modelId: string,
+  ): LegacyRuntimeResult<LegacySessionPresentation> {
+    if (this.mode === 'pi-rpc') {
+      return RUNTIME_UNSUPPORTED;
+    }
+    return this.embeddedPort.applyLegacyModelOverride(context, modelId);
+  }
+
+  readLegacySessionPresentation(
+    context: OwnedConversationContext,
+  ): LegacyRuntimeResult<LegacySessionPresentation> {
+    if (this.mode === 'pi-rpc') {
+      return RUNTIME_UNSUPPORTED;
+    }
+    return this.embeddedPort.readLegacySessionPresentation(context);
+  }
+
+  /**
+   * Verified Discord ingress bypasses browser mode: it is embedded-only in BOTH modes and
+   * never reaches the harness or routing-engine selection. It is reached only through a
+   * {@link VerifiedDiscordIngressContext}, which exists only after every ingress check.
+   */
+  dispatchVerifiedDiscordIngress(
+    context: VerifiedDiscordIngressContext,
+    stream: LegacyRuntimeStream,
+  ): Promise<LegacyRuntimeResult<VerifiedDiscordTurnLease>> {
+    return this.embeddedPort.dispatchVerifiedDiscordIngress(context, stream);
+  }
+}

apps/gateway/src/chat/chat-runtime.ts

@@ -0,0 +1,273 @@
+import type { ChannelAttachmentDto, RoutingDecisionInfo } from '@mosaicstack/types';
+
+/**
+ * The single chat execution strategy resolved by {@link ChatRuntimeRouter}.
+ *
+ * Exactly one runtime is live per process. There is no union that lets a
+ * `pi-rpc` deployment silently fall back to embedded execution: an unmet
+ * `pi-rpc` precondition is a typed startup failure, never a downgrade.
+ */
+export type ChatRuntimeMode = 'legacy' | 'pi-rpc';
+
+export type ChatRuntimeKind = 'embedded' | 'harness';
+
+/** The resolved runtime. Slice Zero exposes only its immutable {@link ChatRuntimeKind}. */
+export interface ChatRuntime {
+  readonly kind: ChatRuntimeKind;
+}
+
+/** Why the `pi-rpc` runtime could not be made ready. Both are hard startup failures. */
+export type ChatRuntimeUnavailableReason =
+  | 'adapter_unavailable'
+  | 'conversation_service_unavailable';
+
+/**
+ * Raised at module init when `pi-rpc` mode is selected but its preconditions are
+ * unmet. Carries only fixed, browser-safe text — never a raw exception message,
+ * stack, or provider detail — and reports the frozen ack code `runtime_unsupported`.
+ */
+export class ChatRuntimeUnavailableError extends Error {
+  readonly code = 'runtime_unsupported' as const;
+  readonly reason: ChatRuntimeUnavailableReason;
+
+  constructor(reason: ChatRuntimeUnavailableReason) {
+    super(
+      reason === 'adapter_unavailable'
+        ? 'The pi-rpc chat runtime is unavailable: no "pi" harness adapter is registered.'
+        : 'The pi-rpc chat runtime is unavailable: the harness conversation service is not bound.',
+    );
+    this.name = 'ChatRuntimeUnavailableError';
+    this.reason = reason;
+  }
+}
+
+/**
+ * Resolves the process-wide chat runtime mode from the environment. Anything other
+ * than the exact opt-in token `pi-rpc` keeps the legacy embedded runtime.
+ */
+export function resolveChatRuntimeMode(
+  env: Record<string, string | undefined> = process.env,
+): ChatRuntimeMode {
+  return env['CHAT_HARNESS_RUNTIME'] === 'pi-rpc' ? 'pi-rpc' : 'legacy';
+}
+
+// ---------------------------------------------------------------------------
+// Transitional embedded chat port (Task Five).
+//
+// The legacy embedded browser behaviour is moved behind this exact interface so
+// neither the controller nor the gateway retains AgentService, RoutingEngine,
+// session, `piSession`, metric, listener, or channel access. `EmbeddedChatRuntime`
+// implements the port; `ChatRuntimeRouter` exposes the same narrowly named
+// operations and returns `runtime_unsupported` before touching Embedded for legacy
+// browser operations when the mode is `pi-rpc`.
+//
+// The names are frozen (spec jarvis-brain@1c629b06). Legacy REST completion,
+// legacy Socket streaming, P3 harness turns, and verified Discord are distinct
+// transport/trust capabilities — there is deliberately no generic
+// `sendConversationTurn` nor an AgentService-shaped mirror on the router.
+// ---------------------------------------------------------------------------
+
+/**
+ * Phantom brand keeping {@link OwnedConversationContext} nominally distinct so browser
+ * DTOs are never structurally assignable to it. The factory that mints one may be called
+ * only after authentication with `scopeFromUser(...)`, never with payload authority fields.
+ */
+declare const ownedConversationContextBrand: unique symbol;
+
+/** Gateway-only ownership context. Embedded rechecks owner+tenant on every operation. */
+export interface OwnedConversationContext {
+  readonly [ownedConversationContextBrand]: true;
+  readonly conversationId: string;
+  readonly scope: Readonly<{ userId: string; tenantId: string }>;
+}
+
+/**
+ * Every non-`ok` legacy runtime outcome. Missing, foreign, and no-longer-owned
+ * conversations all collapse to `conversation_unavailable`. Ownership/mode/validation
+ * failures are total results and never throw.
+ */
+export type LegacyRuntimeFailure =
+  | { readonly ok: false; readonly code: 'runtime_unsupported'; readonly retryable: false }
+  | { readonly ok: false; readonly code: 'conversation_unavailable'; readonly retryable: false }
+  | { readonly ok: false; readonly code: 'request_invalid'; readonly retryable: false }
+  | {
+      readonly ok: false;
+      readonly code: 'thinking_level_invalid';
+      readonly retryable: false;
+      readonly availableThinkingLevels: readonly string[];
+    }
+  | { readonly ok: false; readonly code: 'runtime_unavailable'; readonly retryable: true }
+  | { readonly ok: false; readonly code: 'turn_already_dispatched'; readonly retryable: false }
+  | { readonly ok: false; readonly code: 'operation_failed'; readonly retryable: boolean }
+  | { readonly ok: false; readonly code: 'timeout'; readonly retryable: true };
+
+/** Total result: an `ok` value or one of the fixed {@link LegacyRuntimeFailure} codes. */
+export type LegacyRuntimeResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | LegacyRuntimeFailure;
+
+/** User-facing session projection. Carries no session object, handle, or credential path. */
+export interface LegacySessionPresentation {
+  readonly provider: string;
+  readonly modelId: string;
+  readonly thinkingLevel: string;
+  readonly availableThinkingLevels: readonly string[];
+  readonly agentName?: string;
+  readonly routingDecision?: RoutingDecisionInfo;
+}
+
+/** Terminal usage stats, normalized by Embedded from AgentService metrics. */
+export interface LegacyUsage {
+  readonly provider: string;
+  readonly modelId: string;
+  readonly thinkingLevel: string;
+  readonly tokens: Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  }>;
+  readonly cost: number;
+  readonly context: Readonly<{ percent: number | null; window: number }>;
+}
+
+/**
+ * Normalized stream event. Exposes no `AgentSession`, `piSession`, native handle, raw
+ * exception, tool arguments, or credential-bearing path — the gateway sees only these.
+ */
+export type LegacyRuntimeEvent =
+  | { readonly type: 'started' }
+  | { readonly type: 'text_delta'; readonly text: string }
+  | { readonly type: 'thinking_delta'; readonly text: string }
+  | {
+      readonly type: 'tool_started';
+      readonly toolCallId: string;
+      readonly toolName: string;
+    }
+  | {
+      readonly type: 'tool_finished';
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly isError: boolean;
+    }
+  | { readonly type: 'settled'; readonly usage?: LegacyUsage };
+
+/** Legacy browser message input. Authority fields are advisory only; scope comes from the context. */
+export interface LegacyBrowserMessagePayload {
+  readonly content: string;
+  readonly provider?: string;
+  readonly modelId?: string;
+  readonly agentId?: string;
+  readonly attachments?: readonly ChannelAttachmentDto[];
+}
+
+/** A prepared-but-not-yet-dispatched legacy socket turn. */
+export interface LegacySocketTurnLease {
+  readonly presentation: LegacySessionPresentation;
+  /**
+   * Atomically one-shot and scope-rechecking. A second call returns
+   * `turn_already_dispatched` and performs zero prompt/tool effects.
+   */
+  dispatch(): Promise<LegacyRuntimeResult<void>>;
+  /** Idempotent, non-throwing. Removes listener and channel, including partial setup. */
+  dispose(): Promise<void>;
+}
+
+/**
+ * Phantom brand for {@link VerifiedDiscordIngressContext}. Minted only after service-token
+ * auth plus signature, allowlist, binding, expected-route, replay, configured-agent,
+ * forced-scope, and attachment-normalization checks.
+ */
+declare const verifiedDiscordIngressContextBrand: unique symbol;
+
+/** Fully-verified Discord ingress. Contains no socket, envelope, signature, token, or escape hatch. */
+export interface VerifiedDiscordIngressContext {
+  readonly [verifiedDiscordIngressContextBrand]: true;
+  readonly conversationId: string;
+  readonly scope: Readonly<{ userId: string; tenantId: string }>;
+  readonly configuredAgent: Readonly<{ agentConfigId: string; instanceId: string }>;
+  readonly content: string;
+  readonly attachments?: readonly ChannelAttachmentDto[];
+  readonly correlationId: string;
+  readonly discordMessageId: string;
+  readonly discordUserId: string;
+}
+
+/** Verified-Discord turn lease. Same atomic one-shot dispatch and idempotent dispose rules. */
+export interface VerifiedDiscordTurnLease {
+  readonly presentation: LegacySessionPresentation;
+  dispatch(): Promise<LegacyRuntimeResult<void>>;
+  dispose(): Promise<void>;
+}
+
+/** Server-owned egress projection the runtime pushes normalized events into. */
+export interface LegacyRuntimeStream {
+  /** Server-derived, e.g. `websocket:<socket-id>`. Never client-supplied. */
+  readonly channelId: string;
+  onEvent(event: LegacyRuntimeEvent): void;
+}
+
+/**
+ * The exact transitional port. `EmbeddedChatRuntime` implements it; `ChatRuntimeRouter`
+ * mirrors the operation names and fails closed with `runtime_unsupported` for legacy
+ * browser operations under `pi-rpc`.
+ */
+export interface LegacyEmbeddedChatPort {
+  completeLegacyRestTurn(
+    context: OwnedConversationContext,
+    input: Readonly<{ content: string }>,
+  ): Promise<
+    LegacyRuntimeResult<Readonly<{ text: string; presentation: LegacySessionPresentation }>>
+  >;
+
+  prepareLegacySocketTurn(
+    context: OwnedConversationContext,
+    input: LegacyBrowserMessagePayload,
+    stream: LegacyRuntimeStream,
+  ): Promise<LegacyRuntimeResult<LegacySocketTurnLease>>;
+
+  setLegacyThinking(
+    context: OwnedConversationContext,
+    level: string,
+  ): LegacyRuntimeResult<LegacySessionPresentation>;
+
+  abortLegacyTurn(context: OwnedConversationContext): Promise<LegacyRuntimeResult<void>>;
+
+  applyLegacyModelOverride(
+    context: OwnedConversationContext,
+    modelId: string,
+  ): LegacyRuntimeResult<LegacySessionPresentation>;
+
+  readLegacySessionPresentation(
+    context: OwnedConversationContext,
+  ): LegacyRuntimeResult<LegacySessionPresentation>;
+
+  dispatchVerifiedDiscordIngress(
+    context: VerifiedDiscordIngressContext,
+    stream: LegacyRuntimeStream,
+  ): Promise<LegacyRuntimeResult<VerifiedDiscordTurnLease>>;
+}
+
+/**
+ * Mints an {@link OwnedConversationContext} from a server-derived scope. Callers must pass
+ * a scope produced by `scopeFromUser(...)` after authentication — never a client-supplied
+ * authority field. The brand is phantom, so this is the only way to obtain the branded type.
+ */
+export function ownConversation(
+  conversationId: string,
+  scope: Readonly<{ userId: string; tenantId: string }>,
+): OwnedConversationContext {
+  return { conversationId, scope } as unknown as OwnedConversationContext;
+}
+
+/**
+ * Mints a {@link VerifiedDiscordIngressContext}. Callers must have already completed every
+ * ingress check (service-token auth, signature, allowlist, binding, expected-route, replay,
+ * configured-agent, forced-scope, attachment normalization) before calling this.
+ */
+export function verifyDiscordIngress(
+  fields: Omit<VerifiedDiscordIngressContext, typeof verifiedDiscordIngressContextBrand>,
+): VerifiedDiscordIngressContext {
+  return { ...fields } as unknown as VerifiedDiscordIngressContext;
+}

apps/gateway/src/chat/chat.controller.ts

@@ -3,21 +3,20 @@ import {
   Post,
   Body,
   Logger,
-  ForbiddenException,
   HttpException,
   HttpStatus,
   NotFoundException,
-  Inject,
   UseGuards,
 } from '@nestjs/common';
-import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
 import { Throttle } from '@nestjs/throttler';
-import { AgentService } from '../agent/agent.service.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
 import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
 import { v4 as uuid } from 'uuid';
 import { ChatRequestDto } from './chat.dto.js';
+import { ChatRuntimeRouter } from './chat-runtime-router.js';
+import { ownConversation } from './chat-runtime.js';
+import type { LegacyRuntimeFailure } from './chat-runtime.js';
 
 interface ChatResponse {
   conversationId: string;
@@ -29,7 +28,7 @@ interface ChatResponse {
 export class ChatController {
   private readonly logger = new Logger(ChatController.name);
 
-  constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
+  constructor(private readonly runtime: ChatRuntimeRouter) {}
 
   @Post()
   @Throttle({ default: { limit: 10, ttl: 60_000 } })
@@ -40,68 +39,38 @@ export class ChatController {
     const conversationId = body.conversationId ?? uuid();
     const scope = scopeFromUser(user);
 
-    try {
-      let agentSession = this.agentService.getSession(conversationId, scope);
-      if (!agentSession) {
-        agentSession = await this.agentService.createSession(conversationId, {
-          userId: scope.userId,
-          tenantId: scope.tenantId,
-        });
-      }
-    } catch (err) {
-      if (err instanceof ForbiddenException) {
-        throw new NotFoundException('Session not found');
-      }
-      this.logger.error(
-        `Session creation failed for conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      throw new HttpException('Agent session unavailable', HttpStatus.SERVICE_UNAVAILABLE);
-    }
-
     this.logger.debug(`Handling chat request for user=${user.id}, conversation=${conversationId}`);
 
-    let responseText = '';
+    // The one exclusive runtime owns execution. In legacy mode this reaches the embedded runtime;
+    // in pi-rpc it fails closed with `runtime_unsupported` before ever touching embedded execution.
+    const result = await this.runtime.completeLegacyRestTurn(
+      ownConversation(conversationId, scope),
+      { content: body.content },
+    );
 
-    const done = new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        cleanup();
-        this.logger.error(`Agent response timed out after 120s for conversation=${conversationId}`);
-        reject(new Error('Agent response timed out'));
-      }, 120_000);
-
-      const cleanup = this.agentService.onEvent(
-        conversationId,
-        (event: AgentSessionEvent) => {
-          if (
-            event.type === 'message_update' &&
-            event.assistantMessageEvent.type === 'text_delta'
-          ) {
-            responseText += event.assistantMessageEvent.delta;
-          }
-          if (event.type === 'agent_end') {
-            clearTimeout(timer);
-            cleanup();
-            resolve();
-          }
-        },
-        scope,
-      );
-    });
-
-    try {
-      await this.agentService.prompt(conversationId, body.content, scope);
-      await done;
-    } catch (err) {
-      if (err instanceof HttpException) throw err;
-      const message = err instanceof Error ? err.message : String(err);
-      if (message.includes('timed out')) {
-        throw new HttpException('Agent response timed out', HttpStatus.GATEWAY_TIMEOUT);
-      }
-      this.logger.error(`Chat prompt failed for conversation=${conversationId}`, String(err));
-      throw new HttpException('Agent processing failed', HttpStatus.INTERNAL_SERVER_ERROR);
+    if (result.ok) {
+      return { conversationId, text: result.value.text };
     }
 
-    return { conversationId, text: responseText };
+    throw this.toHttpException(result, conversationId);
+  }
+
+  /** Maps a total {@link LegacyRuntimeFailure} to the fixed browser-safe HTTP surface. */
+  private toHttpException(failure: LegacyRuntimeFailure, conversationId: string): HttpException {
+    switch (failure.code) {
+      case 'conversation_unavailable':
+        return new NotFoundException('Session not found');
+      case 'request_invalid':
+      case 'thinking_level_invalid':
+        return new HttpException('Invalid chat request', HttpStatus.BAD_REQUEST);
+      case 'timeout':
+        return new HttpException('Agent response timed out', HttpStatus.GATEWAY_TIMEOUT);
+      case 'runtime_unsupported':
+      case 'runtime_unavailable':
+        return new HttpException('Agent runtime unavailable', HttpStatus.SERVICE_UNAVAILABLE);
+      default:
+        this.logger.error(`Chat turn failed for conversation=${conversationId}: ${failure.code}`);
+        return new HttpException('Agent processing failed', HttpStatus.INTERNAL_SERVER_ERROR);
+    }
   }
 }

apps/gateway/src/chat/chat.dto.ts

@@ -1,5 +1,14 @@
 import type { ChannelAttachmentDto } from '@mosaicstack/types';
-import { IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
+import { Transform, Type } from 'class-transformer';
+import {
+  IsNotEmpty,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+  ValidateNested,
+} from 'class-validator';
 
 export class ChatRequestDto {
   @IsOptional()
@@ -37,3 +46,56 @@ export class ChatSocketMessageDto {
   /** Validated channel attachment references; binary content is not embedded. */
   attachments?: readonly ChannelAttachmentDto[];
 }
+
+/**
+ * Task Five, group 2 — the frozen pi-rpc `turn:send` selection triple.
+ *
+ * Each id is a required, non-empty, bounded string. There is no `@IsOptional` and no extra
+ * field: under `forbidNonWhitelisted` an unknown selection key is rejected, and a missing id
+ * fails `@IsString` (undefined is not a string) rather than silently passing.
+ */
+export class HarnessTurnSelectionDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  harnessId!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  providerId!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  modelId!: string;
+}
+
+/**
+ * Task Five, group 2 — the frozen wire contract for a pi-rpc `turn:send`.
+ *
+ * Validated through the production `ValidationPipe({ whitelist, forbidNonWhitelisted, transform })`:
+ * a UUID conversation id; `content` trimmed then bounded to 1..10_000 characters (whitespace-only
+ * collapses to empty and fails `@IsNotEmpty`); a nested `selection` object recursed with an
+ * explicit `@Type` (a bare `@ValidateNested` is masked green by class-validator's empty-metadata
+ * `unknownValue`); and a UUID-v4 idempotency key. No `provider`/`modelId`/`attachments` or other
+ * authority field is declared, so `forbidNonWhitelisted` rejects every unknown top-level key.
+ */
+export class HarnessTurnSendDto {
+  @IsUUID()
+  conversationId!: string;
+
+  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(10_000)
+  content!: string;
+
+  @IsObject()
+  @ValidateNested()
+  @Type(() => HarnessTurnSelectionDto)
+  selection!: HarnessTurnSelectionDto;
+
+  @IsUUID('4')
+  idempotencyKey!: string;
+}

apps/gateway/src/chat/chat.gateway-command-approval.spec.ts

@@ -8,12 +8,31 @@ const payload: SlashCommandPayload = {
   approvalId: 'approval-1',
 };
 
+/**
+ * Task 5 fence (F, existing control): gateway-owned command authorization/approval must
+ * cause ZERO chat-runtime dispatch. Placed in the gateway's chat-runtime-router slot (the
+ * former direct `AgentService` slot) so any accidental chat-runtime resolution throws
+ * loudly instead of silently passing. Because execute/approval run entirely through the
+ * command executor dependency and never resolve a chat runtime, this fixture is never
+ * triggered and the ingress stays a GREEN control.
+ */
+function failIfUsedChatRuntimeRouter() {
+  return {
+    onModuleInit: () => {
+      throw new Error('chat runtime router must not initialise on the command approval path');
+    },
+    get active(): never {
+      throw new Error('chat runtime must not be resolved on the command approval path');
+    },
+  };
+}
+
 function buildGateway(commandExecutor: {
   execute: ReturnType<typeof vi.fn>;
   createApproval: ReturnType<typeof vi.fn>;
 }): ChatGateway {
   return new ChatGateway(
-    {} as never,
+    failIfUsedChatRuntimeRouter() as never,
     {} as never,
     {} as never,
     {} as never,
@@ -72,3 +91,114 @@ describe('ChatGateway command approval ingress', () => {
     });
   });
 });
+
+/**
+ * Task 5 (G3) command runtime fence. Under pi-rpc there is no embedded chat session, so
+ * embedded slash-commands (/model, /agent, and every other non-audited command) are fixed
+ * "unsupported" and MUST fail closed BEFORE reaching the command executor — never a silent
+ * fall-through to embedded execution. Only runtime-independent audited system commands
+ * (/reload) pass through as a positive control, and the approval path stays runtime-independent.
+ * The router stub here carries `runtimeMode: 'pi-rpc'` and throws if any runtime is resolved, so
+ * a fence bypass surfaces as a thrown error rather than a silent embedded dispatch.
+ */
+function buildPiRpcGateway(commandExecutor: {
+  execute: ReturnType<typeof vi.fn>;
+  createApproval: ReturnType<typeof vi.fn>;
+}): ChatGateway {
+  const piRpcRouter = {
+    runtimeMode: 'pi-rpc' as const,
+    onModuleInit: () => {
+      throw new Error('chat runtime router must not initialise on the pi-rpc command path');
+    },
+    get active(): never {
+      throw new Error('chat runtime must not be resolved on the pi-rpc command path');
+    },
+  };
+  return new ChatGateway(
+    piRpcRouter as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    commandExecutor as never,
+    {} as never,
+  );
+}
+
+describe('ChatGateway command runtime fence (Task 5 G3, pi-rpc)', () => {
+  const UNSUPPORTED = 'Slash commands are not available on this deployment.';
+
+  it.each(['model', 'agent', 'gc'])(
+    'fails /%s closed before the executor under pi-rpc (execute never called)',
+    async (command): Promise<void> => {
+      const commandExecutor = {
+        execute: vi
+          .fn()
+          .mockResolvedValue({ command, conversationId: 'conversation-1', success: true }),
+        createApproval: vi.fn(),
+      };
+      const gateway = buildPiRpcGateway(commandExecutor);
+      const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
+
+      await gateway.handleCommandExecute(client as never, {
+        command,
+        conversationId: 'conversation-1',
+      });
+
+      expect(commandExecutor.execute).toHaveBeenCalledTimes(0);
+      expect(client.emit).toHaveBeenCalledWith('command:result', {
+        command,
+        conversationId: 'conversation-1',
+        success: false,
+        message: UNSUPPORTED,
+      });
+    },
+  );
+
+  it('passes the audited /reload system command through as a positive control under pi-rpc', async (): Promise<void> => {
+    const reloadResult = { command: 'reload', conversationId: 'conversation-1', success: true };
+    const commandExecutor = {
+      execute: vi.fn().mockResolvedValue(reloadResult),
+      createApproval: vi.fn(),
+    };
+    const gateway = buildPiRpcGateway(commandExecutor);
+    const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
+
+    await gateway.handleCommandExecute(client as never, {
+      command: 'reload',
+      conversationId: 'conversation-1',
+    });
+
+    expect(commandExecutor.execute).toHaveBeenCalledTimes(1);
+    expect(commandExecutor.execute).toHaveBeenCalledWith(
+      { command: 'reload', conversationId: 'conversation-1' },
+      { userId: 'admin-1', tenantId: 'admin-1' },
+    );
+    expect(client.emit).toHaveBeenCalledWith('command:result', reloadResult);
+  });
+
+  it('keeps command approval runtime-independent under pi-rpc (createApproval still runs)', async (): Promise<void> => {
+    const commandExecutor = {
+      execute: vi.fn(),
+      createApproval: vi.fn().mockResolvedValue({
+        approvalId: 'approval-1',
+        expiresAt: '2026-07-12T00:05:00.000Z',
+      }),
+    };
+    const gateway = buildPiRpcGateway(commandExecutor);
+    const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
+
+    await gateway.handleCommandApproval(client as never, {
+      command: 'gc',
+      conversationId: 'conversation-1',
+    });
+
+    expect(commandExecutor.createApproval).toHaveBeenCalledWith(
+      { command: 'gc', conversationId: 'conversation-1' },
+      { userId: 'admin-1', tenantId: 'admin-1' },
+    );
+    expect(client.emit).toHaveBeenCalledWith(
+      'command:approval',
+      expect.objectContaining({ success: true, approvalId: 'approval-1' }),
+    );
+  });
+});

apps/gateway/src/chat/chat.module.ts

@@ -1,12 +1,59 @@
 import { forwardRef, Module } from '@nestjs/common';
 import { CommandsModule } from '../commands/commands.module.js';
+import { HarnessModule } from '../harness/harness.module.js';
+import { HarnessRegistry } from '../harness/harness.registry.js';
+import {
+  HARNESS_CONVERSATION_SERVICE,
+  HARNESS_REGISTRY,
+  type HarnessConversationServiceBinding,
+} from '../harness/harness.tokens.js';
+import type { HarnessConversationService } from '@mosaicstack/types';
 import { ChatGateway } from './chat.gateway.js';
 import { ChatController } from './chat.controller.js';
+import { ChatRuntimeRouter } from './chat-runtime-router.js';
+import { EmbeddedChatRuntime } from './embedded-chat.runtime.js';
+import { HarnessChatRuntime } from './harness-chat.runtime.js';
 
+/**
+ * Task Five wiring. The exclusive {@link ChatRuntimeRouter} is the single chat-execution
+ * authority: the controller and gateway inject only the router, never `AgentService`,
+ * `RoutingEngineService`, or a session/`piSession` handle. The router resolves exactly one
+ * runtime at module init — {@link EmbeddedChatRuntime} in legacy mode, {@link HarnessChatRuntime}
+ * in `pi-rpc` — over the REAL {@link HarnessModule} registry and conversation-service binding.
+ *
+ * The router and the harness runtime are constructed through factories because their
+ * dependencies are interface/union types with no runtime injection token (the registry and
+ * conversation-service arrive via the string tokens exported by `HarnessModule`); the embedded
+ * runtime injects the class-typed `AgentService` and is provided directly.
+ */
 @Module({
-  imports: [forwardRef(() => CommandsModule)],
+  imports: [forwardRef(() => CommandsModule), HarnessModule],
   controllers: [ChatController],
-  providers: [ChatGateway],
-  exports: [ChatGateway],
+  providers: [
+    ChatGateway,
+    EmbeddedChatRuntime,
+    {
+      provide: HarnessChatRuntime,
+      useFactory: (conversationService: HarnessConversationServiceBinding) =>
+        new HarnessChatRuntime(conversationService as HarnessConversationService),
+      inject: [HARNESS_CONVERSATION_SERVICE],
+    },
+    {
+      provide: ChatRuntimeRouter,
+      useFactory: (
+        registry: HarnessRegistry,
+        conversationService: HarnessConversationServiceBinding,
+        embedded: EmbeddedChatRuntime,
+        harness: HarnessChatRuntime,
+      ) => new ChatRuntimeRouter(registry, conversationService, embedded, harness),
+      inject: [
+        HARNESS_REGISTRY,
+        HARNESS_CONVERSATION_SERVICE,
+        EmbeddedChatRuntime,
+        HarnessChatRuntime,
+      ],
+    },
+  ],
+  exports: [ChatGateway, ChatRuntimeRouter],
 })
 export class ChatModule {}

apps/gateway/src/chat/embedded-chat.runtime.ts

@@ -0,0 +1,532 @@
+import { ForbiddenException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import { AgentService, type AgentSession } from '../agent/agent.service.js';
+import type { ActorTenantScope } from '../auth/session-scope.js';
+import type {
+  ChatRuntime,
+  LegacyBrowserMessagePayload,
+  LegacyEmbeddedChatPort,
+  LegacyRuntimeEvent,
+  LegacyRuntimeResult,
+  LegacySessionPresentation,
+  LegacySocketTurnLease,
+  LegacyUsage,
+  OwnedConversationContext,
+  VerifiedDiscordIngressContext,
+  VerifiedDiscordTurnLease,
+  LegacyRuntimeStream,
+} from './chat-runtime.js';
+
+/** Fixed timeout for a synchronous REST turn, matching the historical controller budget. */
+const REST_TURN_TIMEOUT_MS = 120_000;
+
+/**
+ * The `legacy` chat runtime and the sole implementation of {@link LegacyEmbeddedChatPort}.
+ *
+ * It owns the embedded in-process execution path — the `AgentService` stack that the
+ * `ChatController` and `ChatGateway` drove directly before Task Five. Once the
+ * {@link import('./chat-runtime-router.js').ChatRuntimeRouter} fronts it, the browser
+ * HTTP/WebSocket legacy path and verified-Discord ingress route through THIS runtime, so
+ * neither the controller nor the gateway retains `AgentService`, `piSession`, session,
+ * listener, channel, or metric access. Ownership (`userId`/`tenantId`) is re-checked by
+ * `AgentService` on every operation; a missing, foreign, or no-longer-owned conversation
+ * collapses to `conversation_unavailable` and never throws out of the port.
+ */
+@Injectable()
+export class EmbeddedChatRuntime implements ChatRuntime, LegacyEmbeddedChatPort {
+  readonly kind = 'embedded' as const;
+  private readonly logger = new Logger(EmbeddedChatRuntime.name);
+
+  constructor(readonly agentService: AgentService) {}
+
+  // -------------------------------------------------------------------------
+  // Legacy REST completion (op A)
+  // -------------------------------------------------------------------------
+
+  async completeLegacyRestTurn(
+    context: OwnedConversationContext,
+    input: Readonly<{ content: string }>,
+  ): Promise<
+    LegacyRuntimeResult<Readonly<{ text: string; presentation: LegacySessionPresentation }>>
+  > {
+    const scope = toScope(context.scope);
+    const { conversationId } = context;
+
+    const resolved = await this.resolveOrCreate(conversationId, scope, {});
+    if (!resolved.ok) return resolved;
+
+    let responseText = '';
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let detach: (() => void) | undefined;
+    let disposed = false;
+    // One idempotent teardown owned OUTSIDE the completion promise: it clears the timeout and
+    // detaches the event listener exactly once, whichever of agent_end, timeout, or a prompt
+    // rejection fires first. Without this, a prompt() rejection surfaced through the catch below
+    // would return while leaving the listener attached (free to consume a later turn's events) and
+    // the 120s timer live (its rejection later going unobserved).
+    const dispose = (): void => {
+      if (disposed) return;
+      disposed = true;
+      if (timer !== undefined) clearTimeout(timer);
+      detach?.();
+    };
+    const done = new Promise<void>((resolve, reject) => {
+      timer = setTimeout(() => {
+        dispose();
+        reject(new Error('Agent response timed out'));
+      }, REST_TURN_TIMEOUT_MS);
+
+      detach = this.agentService.onEvent(
+        conversationId,
+        (event: AgentSessionEvent) => {
+          if (
+            event.type === 'message_update' &&
+            event.assistantMessageEvent.type === 'text_delta'
+          ) {
+            responseText += event.assistantMessageEvent.delta;
+          }
+          if (event.type === 'agent_end') {
+            dispose();
+            resolve();
+          }
+        },
+        scope,
+      );
+    });
+
+    // Attach the prompt and the completion promise CONCURRENTLY. Awaiting prompt() first left the
+    // timeout unobservable until prompt settled (a hung prompt could never time out) and, worse,
+    // let the 120s timer reject `done` while nothing yet awaited it — a transient unhandledRejection
+    // window. Promise.all installs handlers on BOTH synchronously, so the timeout bounds the whole
+    // turn even while prompt is pending, and neither promise can reject unobserved. Success still
+    // requires both prompt() to resolve AND agent_end to arrive (identical to the prior sequential
+    // await). The idempotent dispose() clears the timer + detaches on whichever settles first.
+    const prompting = this.agentService.prompt(conversationId, input.content, scope);
+    try {
+      await Promise.all([prompting, done]);
+    } catch (err) {
+      dispose();
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes('timed out')) {
+        return { ok: false, code: 'timeout', retryable: true };
+      }
+      this.logger.error(`Legacy REST turn failed for conversation=${conversationId}`, message);
+      return { ok: false, code: 'operation_failed', retryable: false };
+    }
+
+    const presentation = this.presentationFor(conversationId, scope) ?? resolved.presentation;
+    return { ok: true, value: { text: responseText, presentation } };
+  }
+
+  // -------------------------------------------------------------------------
+  // Legacy Socket streaming (op B)
+  // -------------------------------------------------------------------------
+
+  async prepareLegacySocketTurn(
+    context: OwnedConversationContext,
+    input: LegacyBrowserMessagePayload,
+    stream: LegacyRuntimeStream,
+  ): Promise<LegacyRuntimeResult<LegacySocketTurnLease>> {
+    const scope = toScope(context.scope);
+    const { conversationId } = context;
+
+    const resolved = await this.resolveOrCreate(conversationId, scope, {
+      ...(input.provider ? { provider: input.provider } : {}),
+      ...(input.modelId ? { modelId: input.modelId } : {}),
+      ...(input.agentId ? { agentConfigId: input.agentId } : {}),
+    });
+    if (!resolved.ok) return resolved;
+
+    let detach: () => void;
+    try {
+      detach = this.subscribe(conversationId, scope, stream);
+    } catch (err) {
+      // A partial listener/channel setup rolled itself back inside subscribe(); surface a total
+      // safe failure instead of throwing out of the port. Retryable — the attach is transient.
+      this.logger.error(
+        `Embedded socket subscription failed for conversation=${conversationId}`,
+        err instanceof Error ? err.message : String(err),
+      );
+      return { ok: false, code: 'runtime_unavailable', retryable: true };
+    }
+
+    return {
+      ok: true,
+      value: this.buildLease(
+        conversationId,
+        scope,
+        input.content,
+        input.attachments,
+        detach,
+        resolved.presentation,
+      ),
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Thinking level (op C) — synchronous, total
+  // -------------------------------------------------------------------------
+
+  setLegacyThinking(
+    context: OwnedConversationContext,
+    level: string,
+  ): LegacyRuntimeResult<LegacySessionPresentation> {
+    const scope = toScope(context.scope);
+    const session = this.agentService.getSession(context.conversationId, scope);
+    if (!session) return CONVERSATION_UNAVAILABLE;
+
+    const availableThinkingLevels = session.piSession.getAvailableThinkingLevels();
+    if (!(availableThinkingLevels as readonly string[]).includes(level)) {
+      return {
+        ok: false,
+        code: 'thinking_level_invalid',
+        retryable: false,
+        availableThinkingLevels,
+      };
+    }
+
+    session.piSession.setThinkingLevel(level as never);
+    return { ok: true, value: this.presentationForSession(session) };
+  }
+
+  // -------------------------------------------------------------------------
+  // Abort (op D)
+  // -------------------------------------------------------------------------
+
+  async abortLegacyTurn(context: OwnedConversationContext): Promise<LegacyRuntimeResult<void>> {
+    const scope = toScope(context.scope);
+    const session = this.agentService.getSession(context.conversationId, scope);
+    if (!session) return CONVERSATION_UNAVAILABLE;
+
+    try {
+      await session.piSession.abort();
+    } catch (err) {
+      this.logger.error(
+        `Legacy abort failed for conversation=${context.conversationId}`,
+        err instanceof Error ? err.message : String(err),
+      );
+      return { ok: false, code: 'operation_failed', retryable: false };
+    }
+    return { ok: true, value: undefined };
+  }
+
+  // -------------------------------------------------------------------------
+  // Model override (synchronous, total)
+  // -------------------------------------------------------------------------
+
+  applyLegacyModelOverride(
+    context: OwnedConversationContext,
+    modelId: string,
+  ): LegacyRuntimeResult<LegacySessionPresentation> {
+    const scope = toScope(context.scope);
+    const session = this.agentService.getSession(context.conversationId, scope);
+    if (!session) return CONVERSATION_UNAVAILABLE;
+
+    this.agentService.updateSessionModel(context.conversationId, modelId, scope);
+    const refreshed = this.agentService.getSession(context.conversationId, scope) ?? session;
+    return { ok: true, value: this.presentationForSession(refreshed) };
+  }
+
+  // -------------------------------------------------------------------------
+  // Presentation read (synchronous, total)
+  // -------------------------------------------------------------------------
+
+  readLegacySessionPresentation(
+    context: OwnedConversationContext,
+  ): LegacyRuntimeResult<LegacySessionPresentation> {
+    const scope = toScope(context.scope);
+    const session = this.agentService.getSession(context.conversationId, scope);
+    if (!session) return CONVERSATION_UNAVAILABLE;
+    return { ok: true, value: this.presentationForSession(session) };
+  }
+
+  // -------------------------------------------------------------------------
+  // Verified Discord ingress (embedded-only in both modes)
+  // -------------------------------------------------------------------------
+
+  async dispatchVerifiedDiscordIngress(
+    context: VerifiedDiscordIngressContext,
+    stream: LegacyRuntimeStream,
+  ): Promise<LegacyRuntimeResult<VerifiedDiscordTurnLease>> {
+    const scope = toScope(context.scope);
+    const { conversationId } = context;
+
+    const resolved = await this.resolveOrCreate(
+      conversationId,
+      scope,
+      { agentConfigId: context.configuredAgent.agentConfigId },
+      {
+        agentConfigId: context.configuredAgent.agentConfigId,
+        instanceId: context.configuredAgent.instanceId,
+      },
+    );
+    if (!resolved.ok) return resolved;
+
+    let detach: () => void;
+    try {
+      detach = this.subscribe(conversationId, scope, stream);
+    } catch (err) {
+      // A partial listener/channel setup rolled itself back inside subscribe(); surface a total
+      // safe failure instead of throwing out of the port. Retryable — the attach is transient.
+      this.logger.error(
+        `Embedded Discord subscription failed for conversation=${conversationId}`,
+        err instanceof Error ? err.message : String(err),
+      );
+      return { ok: false, code: 'runtime_unavailable', retryable: true };
+    }
+
+    return {
+      ok: true,
+      value: this.buildLease(
+        conversationId,
+        scope,
+        context.content,
+        context.attachments,
+        detach,
+        resolved.presentation,
+      ),
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Shared helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Resolves the owned session, creating it on first use. Ownership/scope rejections
+   * (`Forbidden`/`NotFound`) collapse to `conversation_unavailable`; any other creation
+   * failure surfaces as the retryable `runtime_unavailable`. On success returns the
+   * session presentation so callers avoid a redundant `getSession`.
+   */
+  private async resolveOrCreate(
+    conversationId: string,
+    scope: ActorTenantScope,
+    extraOptions: Readonly<{ provider?: string; modelId?: string; agentConfigId?: string }>,
+    expectedAgent?: Readonly<{ agentConfigId: string; instanceId: string }>,
+  ): Promise<
+    | { readonly ok: true; readonly presentation: LegacySessionPresentation }
+    | Exclude<LegacyRuntimeResult<never>, { ok: true }>
+  > {
+    // A verified-Discord turn may only run under a session whose configured identity matches the
+    // reconciled agent record EXACTLY (config id + resolved name). This holds for BOTH a reused
+    // pre-existing session AND a freshly created one: a session carrying a different configured
+    // agent — however it arose — is rejected rather than executed under the verified label, so we
+    // never silently run a different prompt/model/tool policy. A plain (non-verified) turn passes
+    // no expectedAgent and skips the check.
+    const identityMatches = (candidate: AgentSession): boolean =>
+      expectedAgent === undefined ||
+      (candidate.agentConfigId === expectedAgent.agentConfigId &&
+        candidate.agentName === expectedAgent.instanceId);
+
+    let session = this.agentService.getSession(conversationId, scope);
+    if (session && !identityMatches(session)) {
+      // Reused same-scope session minted under a different configured identity — reject with zero
+      // effects rather than dispatch a verified turn onto a foreign agent's session.
+      return CONVERSATION_UNAVAILABLE;
+    }
+    if (!session) {
+      try {
+        session = await this.agentService.createSession(conversationId, {
+          userId: scope.userId,
+          tenantId: scope.tenantId,
+          ...extraOptions,
+        });
+      } catch (err) {
+        if (err instanceof ForbiddenException || err instanceof NotFoundException) {
+          return CONVERSATION_UNAVAILABLE;
+        }
+        this.logger.error(
+          `Embedded session creation failed for conversation=${conversationId}`,
+          err instanceof Error ? err.stack : String(err),
+        );
+        return { ok: false, code: 'runtime_unavailable', retryable: true };
+      }
+      // The just-created session must ALSO carry the reconciled identity before any effect. A
+      // createSession that returns a session under a different configured agent (misconfiguration
+      // or a substituted factory) is rejected here, before subscribe/persist/ack/prompt.
+      if (!identityMatches(session)) {
+        return CONVERSATION_UNAVAILABLE;
+      }
+    }
+    return { ok: true, presentation: this.presentationForSession(session) };
+  }
+
+  /** Installs a normalizing event listener that forwards to the server-owned stream. */
+  private subscribe(
+    conversationId: string,
+    scope: ActorTenantScope,
+    stream: LegacyRuntimeStream,
+  ): () => void {
+    const unsubscribe = this.agentService.onEvent(
+      conversationId,
+      (event: AgentSessionEvent) => {
+        const normalized = this.normalizeEvent(conversationId, scope, event);
+        if (normalized) stream.onEvent(normalized);
+      },
+      scope,
+    );
+    try {
+      this.agentService.addChannel(conversationId, stream.channelId, scope);
+    } catch (err) {
+      // Partial setup: the listener was acquired but the channel attach failed. Roll back
+      // exactly what was acquired (the listener) before the failure escapes, so no leaked
+      // subscription survives; the caller converts the rethrow into a total safe failure.
+      try {
+        unsubscribe();
+      } catch {
+        /* idempotent teardown */
+      }
+      throw err;
+    }
+    return () => {
+      try {
+        unsubscribe();
+      } catch {
+        /* idempotent teardown */
+      }
+      try {
+        this.agentService.removeChannel(conversationId, stream.channelId, scope);
+      } catch {
+        /* idempotent teardown */
+      }
+    };
+  }
+
+  /** Builds an atomically one-shot, scope-rechecking dispatch lease. */
+  private buildLease(
+    conversationId: string,
+    scope: ActorTenantScope,
+    content: string,
+    attachments: VerifiedDiscordIngressContext['attachments'],
+    detach: () => void,
+    presentation: LegacySessionPresentation,
+  ): LegacySocketTurnLease & VerifiedDiscordTurnLease {
+    let dispatched = false;
+    let disposed = false;
+    return {
+      presentation,
+      dispatch: async (): Promise<LegacyRuntimeResult<void>> => {
+        if (dispatched) {
+          return { ok: false, code: 'turn_already_dispatched', retryable: false };
+        }
+        dispatched = true;
+        try {
+          await this.agentService.prompt(conversationId, content, scope, attachments);
+        } catch (err) {
+          this.logger.error(
+            `Legacy dispatch failed for conversation=${conversationId}`,
+            err instanceof Error ? err.message : String(err),
+          );
+          return { ok: false, code: 'operation_failed', retryable: false };
+        }
+        return { ok: true, value: undefined };
+      },
+      dispose: async (): Promise<void> => {
+        if (disposed) return;
+        disposed = true;
+        detach();
+      },
+    };
+  }
+
+  /** Normalizes a raw agent event into the redaction-agnostic transport event, or drops it. */
+  private normalizeEvent(
+    conversationId: string,
+    scope: ActorTenantScope,
+    event: AgentSessionEvent,
+  ): LegacyRuntimeEvent | undefined {
+    switch (event.type) {
+      case 'agent_start':
+        return { type: 'started' };
+      case 'agent_end':
+        return { type: 'settled', ...this.usageFor(conversationId, scope) };
+      case 'message_update': {
+        const assistant = event.assistantMessageEvent;
+        if (assistant.type === 'text_delta') return { type: 'text_delta', text: assistant.delta };
+        if (assistant.type === 'thinking_delta') {
+          return { type: 'thinking_delta', text: assistant.delta };
+        }
+        return undefined;
+      }
+      case 'tool_execution_start':
+        return { type: 'tool_started', toolCallId: event.toolCallId, toolName: event.toolName };
+      case 'tool_execution_end':
+        return {
+          type: 'tool_finished',
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          isError: event.isError,
+        };
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Gathers terminal usage from the Pi session and records it into session metrics.
+   * Embedded owns AgentService metrics; the gateway never touches `piSession` stats.
+   */
+  private usageFor(conversationId: string, scope: ActorTenantScope): { usage?: LegacyUsage } {
+    const session = this.agentService.getSession(conversationId, scope);
+    const piSession = session?.piSession;
+    const stats = piSession?.getSessionStats();
+    if (!session || !stats) return {};
+    const contextUsage = piSession?.getContextUsage();
+
+    const tokens = {
+      input: stats.tokens?.input ?? 0,
+      output: stats.tokens?.output ?? 0,
+      cacheRead: stats.tokens?.cacheRead ?? 0,
+      cacheWrite: stats.tokens?.cacheWrite ?? 0,
+      total: stats.tokens?.total ?? 0,
+    };
+
+    this.agentService.recordTokenUsage(conversationId, { ...tokens });
+
+    return {
+      usage: {
+        provider: session.provider,
+        modelId: session.modelId,
+        thinkingLevel: piSession?.thinkingLevel ?? 'off',
+        tokens,
+        cost: stats.cost ?? 0,
+        context: {
+          percent: contextUsage?.percent ?? null,
+          window: contextUsage?.contextWindow ?? 0,
+        },
+      },
+    };
+  }
+
+  /** Presentation from a live session id, or undefined when no owned session exists. */
+  private presentationFor(
+    conversationId: string,
+    scope: ActorTenantScope,
+  ): LegacySessionPresentation | undefined {
+    const session = this.agentService.getSession(conversationId, scope);
+    return session ? this.presentationForSession(session) : undefined;
+  }
+
+  /** User-facing projection carrying no session handle, credential, or raw stats. */
+  private presentationForSession(session: AgentSession): LegacySessionPresentation {
+    return {
+      provider: session.provider,
+      modelId: session.modelId,
+      thinkingLevel: session.piSession.thinkingLevel,
+      availableThinkingLevels: session.piSession.getAvailableThinkingLevels(),
+      ...(session.agentName ? { agentName: session.agentName } : {}),
+    };
+  }
+}
+
+/** The shared terminal `conversation_unavailable` failure (missing/foreign/lost ownership). */
+const CONVERSATION_UNAVAILABLE = {
+  ok: false as const,
+  code: 'conversation_unavailable' as const,
+  retryable: false as const,
+};
+
+/** Narrows a branded context scope to the `AgentService` actor/tenant scope (identical shape). */
+function toScope(scope: Readonly<{ userId: string; tenantId: string }>): ActorTenantScope {
+  return { userId: scope.userId, tenantId: scope.tenantId };
+}

apps/gateway/src/chat/harness-chat.runtime.spec.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  AttachConversation,
+  ConversationSnapshot,
+  DetachConversation,
+  HarnessActorContext,
+  HarnessConversationService,
+  HarnessEventEnvelope,
+  HarnessSelection,
+  SendHarnessTurn,
+  TurnReceipt,
+} from '@mosaicstack/types';
+import { HarnessChatRuntime } from './harness-chat.runtime.js';
+
+/**
+ * Task Five, Step One (harness runtime). Proves the `pi-rpc` runtime executes
+ * exclusively through the {@link HarnessConversationService} RPC boundary and
+ * forwards the caller's exact selection tuple and idempotency key without
+ * substitution. Red-first: the runtime is an unimplemented stub, so every
+ * delegation assertion fails until Step Three.
+ */
+
+const context: HarnessActorContext = {
+  actorId: 'actor-1',
+  tenantId: 'tenant-1',
+  seatId: 'seat-1',
+  correlationId: 'corr-1',
+};
+
+const selection: HarnessSelection = {
+  harnessId: 'pi',
+  providerId: 'anthropic',
+  modelId: 'claude-opus-4-8',
+};
+
+const conversationId = '11111111-1111-4111-8111-111111111111';
+const idempotencyKey = '22222222-2222-4222-8222-222222222222';
+
+const sendInput: SendHarnessTurn & { idempotencyKey: string } = {
+  context,
+  conversationId,
+  selection,
+  turnId: 'turn-abc',
+  correlationId: 'corr-1',
+  content: 'hello',
+  idempotencyKey,
+};
+
+const attachInput: AttachConversation & { afterSequence?: number } = {
+  context,
+  conversationId,
+  clientId: 'client-1',
+  selection,
+  afterSequence: 0,
+};
+
+const detachInput: DetachConversation = {
+  context,
+  conversationId,
+  clientId: 'client-1',
+};
+
+interface RecordedCalls {
+  attach: (AttachConversation & { afterSequence?: number })[];
+  detach: DetachConversation[];
+  send: (SendHarnessTurn & { idempotencyKey: string })[];
+  subscribeFrom: { conversationId: string; afterSequence: number }[];
+}
+
+const snapshot: ConversationSnapshot = {
+  session: {
+    conversationId,
+    nativeSessionId: 'native-1',
+    seatId: 'seat-1',
+    selection,
+    state: 'idle',
+    attachedClientIds: ['client-1'],
+  },
+  lastSequence: 0,
+  replay: [],
+};
+
+function build(): { runtime: HarnessChatRuntime; calls: RecordedCalls } {
+  const calls: RecordedCalls = { attach: [], detach: [], send: [], subscribeFrom: [] };
+  const service: HarnessConversationService = {
+    attach: (input) => {
+      calls.attach.push(input);
+      return Promise.resolve(snapshot);
+    },
+    detach: (input) => {
+      calls.detach.push(input);
+      return Promise.resolve();
+    },
+    send: (input) => {
+      calls.send.push(input);
+      // The service echoes only the requested tuple; there is no representable substitute.
+      const receipt: TurnReceipt = {
+        conversationId: input.conversationId,
+        turnId: 'turn-server',
+        correlationId: input.correlationId,
+        state: 'accepted',
+        selection: input.selection,
+      };
+      return Promise.resolve(receipt);
+    },
+    subscribeFrom: (id, afterSequence) => {
+      calls.subscribeFrom.push({ conversationId: id, afterSequence });
+
+      return (async function* (): AsyncIterable<HarnessEventEnvelope> {
+        return;
+      })();
+    },
+  };
+  return { runtime: new HarnessChatRuntime(service), calls };
+}
+
+describe('HarnessChatRuntime', () => {
+  it('is the harness runtime kind and needs only a HarnessConversationService', () => {
+    const { runtime } = build();
+    expect(runtime.kind).toBe('harness');
+  });
+
+  it('delegates send to the conversation service with the exact tuple and idempotency key', async () => {
+    const { runtime, calls } = build();
+
+    const receipt = await runtime.send(sendInput);
+
+    expect(calls.send).toHaveLength(1);
+    const firstSend = calls.send[0]!;
+    expect(firstSend).toEqual(sendInput);
+    expect(firstSend.idempotencyKey).toBe(idempotencyKey);
+    expect(firstSend.selection).toEqual(selection);
+    // The runtime must not substitute an effective tuple onto the receipt.
+    expect(receipt.selection).toEqual(selection);
+  });
+
+  it('delegates attach to the conversation service and returns its snapshot', async () => {
+    const { runtime, calls } = build();
+
+    const result = await runtime.attach(attachInput);
+
+    expect(calls.attach).toHaveLength(1);
+    expect(calls.attach[0]).toEqual(attachInput);
+    expect(result).toBe(snapshot);
+  });
+
+  it('delegates detach to the conversation service', async () => {
+    const { runtime, calls } = build();
+
+    await runtime.detach(detachInput);
+
+    expect(calls.detach).toHaveLength(1);
+    expect(calls.detach[0]).toEqual(detachInput);
+  });
+
+  it('delegates subscribeFrom to the conversation service journal replay', async () => {
+    const { runtime, calls } = build();
+
+    const iterable = runtime.subscribeFrom(conversationId, 7);
+    // Drain to prove it is the service-backed async iterable, not a fabricated one.
+    const drained: unknown[] = [];
+    for await (const event of iterable) {
+      drained.push(event);
+    }
+    expect(drained).toHaveLength(0);
+
+    expect(calls.subscribeFrom).toHaveLength(1);
+    expect(calls.subscribeFrom[0]).toEqual({ conversationId, afterSequence: 7 });
+  });
+});

apps/gateway/src/chat/harness-chat.runtime.ts

@@ -0,0 +1,47 @@
+import type {
+  AttachConversation,
+  ConversationSnapshot,
+  DetachConversation,
+  HarnessConversationService,
+  HarnessEventEnvelope,
+  SendHarnessTurn,
+  TurnReceipt,
+} from '@mosaicstack/types';
+import type { ChatRuntime } from './chat-runtime.js';
+
+/**
+ * The `pi-rpc` chat runtime. It executes browser chat exclusively through the
+ * harness-neutral {@link HarnessConversationService} RPC boundary — it never
+ * touches the embedded `AgentService`/`ProviderService`/`RoutingEngineService`
+ * stack, and it forwards the caller's exact selection tuple and idempotency key
+ * without substitution.
+ *
+ * It owns no state and adds no policy: every method forwards the caller's exact
+ * argument to the injected {@link HarnessConversationService} and returns its
+ * result unchanged, so the requested selection tuple and idempotency key can
+ * never be substituted on the way through.
+ */
+export class HarnessChatRuntime implements ChatRuntime {
+  readonly kind = 'harness' as const;
+
+  constructor(private readonly conversations: HarnessConversationService) {}
+
+  attach(input: AttachConversation & { afterSequence?: number }): Promise<ConversationSnapshot> {
+    return this.conversations.attach(input);
+  }
+
+  detach(input: DetachConversation): Promise<void> {
+    return this.conversations.detach(input);
+  }
+
+  send(input: SendHarnessTurn & { idempotencyKey: string }): Promise<TurnReceipt> {
+    return this.conversations.send(input);
+  }
+
+  subscribeFrom(
+    conversationId: string,
+    afterSequence: number,
+  ): AsyncIterable<HarnessEventEnvelope> {
+    return this.conversations.subscribeFrom(conversationId, afterSequence);
+  }
+}

apps/gateway/src/conversations/conversations-harness-fence.spec.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ChatRuntimeMode } from '../chat/chat-runtime.js';
+import { ConversationsController } from './conversations.controller.js';
+
+/**
+ * Task 5 harness fence for the conversations REST write path.
+ *
+ * Under `pi-rpc` the durable/harness conversation path (Task 15) owns message persistence, so the
+ * legacy direct-repository write via `POST /api/conversations/:id/messages` must be refused with a
+ * fixed typed `runtime_unsupported` BEFORE the repository is touched — never a duplicate write.
+ * Under `legacy` the endpoint keeps its current behaviour and writes through `brain.conversations`.
+ *
+ * Item 3 (single runtime-mode source of truth): the mode is the router's ONE init-time resolution,
+ * injected into the controller and read as `router.runtimeMode`. It is NOT re-derived from
+ * `process.env` at request time. The two "env is flipped after construction" tests below are the
+ * load-bearing guard: they pass only because the controller reads the fixed injected mode, and turn
+ * RED the instant the fence is reverted to `resolveChatRuntimeMode(process.env)`.
+ */
+const CONVERSATION_ID = '22222222-2222-4222-8222-222222222222';
+const USER = { id: 'user-1' };
+
+function sendMessageDto() {
+  return {
+    role: 'user' as const,
+    content: 'hello from the legacy REST write path',
+    metadata: undefined,
+  };
+}
+
+function brainWithMessageSpy() {
+  const addMessage = vi.fn().mockResolvedValue({
+    id: 'message-1',
+    conversationId: CONVERSATION_ID,
+    role: 'user',
+    content: 'hello from the legacy REST write path',
+  });
+  return {
+    brain: { conversations: { addMessage } } as never,
+    addMessage,
+  };
+}
+
+/** The controller only needs the router's immutable `runtimeMode`; supply exactly that. */
+function routerFixedTo(mode: ChatRuntimeMode) {
+  return { runtimeMode: mode };
+}
+
+let priorMode: string | undefined;
+
+describe('conversations REST write path — Task 5 harness fence', () => {
+  beforeEach(() => {
+    priorMode = process.env['CHAT_HARNESS_RUNTIME'];
+  });
+
+  afterEach(() => {
+    if (priorMode === undefined) delete process.env['CHAT_HARNESS_RUNTIME'];
+    else process.env['CHAT_HARNESS_RUNTIME'] = priorMode;
+  });
+
+  it('refuses the legacy repository write when the router resolved pi-rpc, before any write', async () => {
+    const { brain, addMessage } = brainWithMessageSpy();
+    const controller = new ConversationsController(brain, routerFixedTo('pi-rpc'));
+
+    await expect(
+      controller.addMessage(CONVERSATION_ID, sendMessageDto(), USER),
+    ).rejects.toMatchObject({ code: 'runtime_unsupported' });
+
+    // Load-bearing: the durable/harness path owns pi-rpc persistence — the legacy repo must not be
+    // written, so no duplicate message can be produced.
+    expect(addMessage).not.toHaveBeenCalled();
+  });
+
+  it('writes through the repository when the router resolved legacy (GREEN control)', async () => {
+    const { brain, addMessage } = brainWithMessageSpy();
+    const controller = new ConversationsController(brain, routerFixedTo('legacy'));
+
+    const result = await controller.addMessage(CONVERSATION_ID, sendMessageDto(), USER);
+
+    expect(addMessage).toHaveBeenCalledWith(
+      {
+        conversationId: CONVERSATION_ID,
+        role: 'user',
+        content: 'hello from the legacy REST write path',
+        metadata: undefined,
+      },
+      USER.id,
+    );
+    expect(result).toMatchObject({ id: 'message-1', conversationId: CONVERSATION_ID });
+  });
+
+  it('keeps refusing under a pi-rpc router even when CHAT_HARNESS_RUNTIME is flipped to legacy after startup', async () => {
+    // The runtime mode is fixed at module init. A later env mutation must not reopen the fence:
+    // a request-time `resolveChatRuntimeMode(process.env)` read would see `legacy` and wrongly write.
+    process.env['CHAT_HARNESS_RUNTIME'] = 'legacy';
+    const { brain, addMessage } = brainWithMessageSpy();
+    const controller = new ConversationsController(brain, routerFixedTo('pi-rpc'));
+
+    await expect(
+      controller.addMessage(CONVERSATION_ID, sendMessageDto(), USER),
+    ).rejects.toMatchObject({ code: 'runtime_unsupported' });
+
+    expect(addMessage).not.toHaveBeenCalled();
+  });
+
+  it('keeps writing under a legacy router even when CHAT_HARNESS_RUNTIME is flipped to pi-rpc after startup', async () => {
+    // Symmetric guard: a legacy-resolved router must keep writing regardless of the live env, so a
+    // request-time env read of `pi-rpc` cannot spuriously refuse a legitimate legacy write.
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    const { brain, addMessage } = brainWithMessageSpy();
+    const controller = new ConversationsController(brain, routerFixedTo('legacy'));
+
+    await controller.addMessage(CONVERSATION_ID, sendMessageDto(), USER);
+
+    expect(addMessage).toHaveBeenCalledTimes(1);
+  });
+});

apps/gateway/src/conversations/conversations.controller.ts

@@ -6,6 +6,7 @@ import {
   ForbiddenException,
   Get,
   HttpCode,
+  HttpException,
   HttpStatus,
   Inject,
   NotFoundException,
@@ -19,6 +20,7 @@ import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
+import { ChatRuntimeRouter } from '../chat/chat-runtime-router.js';
 import {
   CreateConversationDto,
   UpdateConversationDto,
@@ -26,10 +28,41 @@ import {
   SearchMessagesDto,
 } from './conversations.dto.js';
 
+/**
+ * Under `pi-rpc` the durable/harness conversation path (Task 15) owns message persistence, so the
+ * legacy direct-repository write must fail closed with a fixed typed `runtime_unsupported` before
+ * the repository is touched — never a duplicate write. The `code` field is exposed at the top level
+ * so callers can discriminate the refusal while the 503 status carries the browser-safe surface.
+ */
+class HarnessRuntimeWriteUnsupportedException extends HttpException {
+  readonly code = 'runtime_unsupported' as const;
+
+  constructor() {
+    super(
+      {
+        code: 'runtime_unsupported',
+        message:
+          'Conversation message writes are handled by the harness runtime on this deployment.',
+      },
+      HttpStatus.SERVICE_UNAVAILABLE,
+    );
+  }
+}
+
 @Controller('api/conversations')
 @UseGuards(AuthGuard)
 export class ConversationsController {
-  constructor(@Inject(BRAIN) private readonly brain: Brain) {}
+  /**
+   * `router` supplies the ONE immutable runtime mode resolved at module init (Task 5, item 3).
+   * The pre-write fence reads `router.runtimeMode`, never `resolveChatRuntimeMode(process.env)` at
+   * request time — a single source of truth, so the controller cannot disagree with the router
+   * about the live runtime if the environment is mutated after startup. Narrowed to `runtimeMode`
+   * so this class depends on nothing else the router exposes.
+   */
+  constructor(
+    @Inject(BRAIN) private readonly brain: Brain,
+    @Inject(ChatRuntimeRouter) private readonly router: Pick<ChatRuntimeRouter, 'runtimeMode'>,
+  ) {}
 
   @Get()
   async list(@CurrentUser() user: { id: string }) {
@@ -94,6 +127,13 @@ export class ConversationsController {
     @Body() dto: SendMessageDto,
     @CurrentUser() user: { id: string },
   ) {
+    // Fail the legacy repository write closed under pi-rpc BEFORE touching the repository — the
+    // harness path owns persistence there, so a direct write would duplicate the message. The mode
+    // comes from the router's init-time resolution, not a request-time env read.
+    if (this.router.runtimeMode === 'pi-rpc') {
+      throw new HarnessRuntimeWriteUnsupportedException();
+    }
+
     const message = await this.brain.conversations.addMessage(
       {
         conversationId: id,

apps/gateway/src/conversations/conversations.module.ts

@@ -1,7 +1,14 @@
 import { Module } from '@nestjs/common';
+import { ChatModule } from '../chat/chat.module.js';
 import { ConversationsController } from './conversations.controller.js';
 
+/**
+ * Imports {@link ChatModule} solely to inject its exported {@link ChatRuntimeRouter} into
+ * {@link ConversationsController}, so the REST write fence reads the same init-time runtime mode the
+ * router resolved — one source of truth, no duplicate provider, no global token, no AppModule edit.
+ */
 @Module({
+  imports: [ChatModule],
   controllers: [ConversationsController],
 })
 export class ConversationsModule {}

apps/gateway/src/federation/__tests__/enrollment.service.spec.ts

@@ -245,9 +245,21 @@ describe('EnrollmentService.createToken', () => {
     const after = Date.now();
 
     const expiresMs = new Date(result.expiresAt).getTime();
-    // Should be at most 900s from now
-    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + 100);
+
+    // The property under test is CLAMPING: a 9999s request must come back as 900s.
+    // The gap between clamped and unclamped is 9_099_000 ms, so the tolerance below
+    // only has to exceed CI scheduling jitter — it does not need to be tight to keep
+    // the assertion discriminating. A 5s allowance consumes 0.05% of that margin and
+    // an unclamped result still misses by three orders of magnitude.
+    //
+    // It was 100ms and failed on a loaded agent at 900_106 — 6ms over (#1090). A
+    // wall-clock budget sized to a fast machine is a flake, not a tighter test.
+    const CI_JITTER_MS = 5_000;
+    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + CI_JITTER_MS);
     expect(expiresMs - after).toBeGreaterThanOrEqual(0);
+    // Explicitly pin the clamp itself, independent of any timing allowance:
+    // unclamped (9999s) would exceed this by ~9_099_000 ms.
+    expect(expiresMs - before).toBeLessThan(1_000_000);
   });
 });
 

apps/gateway/src/harness/harness-selection.controller.spec.ts

@@ -0,0 +1,164 @@
+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 } from 'vitest';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { HarnessRegistry } from './harness.registry.js';
+import { HARNESS_REGISTRY } from './harness.tokens.js';
+import { HarnessSelectionRepository } from './harness-selection.repository.js';
+import { FakeHarnessAdapter } from './testing/fake-harness.adapter.js';
+// Import the REAL module (not a hand-listed controllers+mocks list) so an
+// unresolved provider fails at app.init() — the #1145-class DI-boot guard.
+import { HarnessModule } from './harness.module.js';
+
+// A known-available tuple from the fake adapter's default catalog.
+const VALID = { harnessId: 'fake', providerId: 'fake-openai', modelId: 'fake-mini' };
+// A tuple whose provider/model are not in any catalog.
+const UNKNOWN = { harnessId: 'fake', providerId: 'ghost-provider', modelId: 'ghost-model' };
+// A tuple that is known in the catalog but flagged unavailable.
+const UNAVAILABLE = { harnessId: 'fake', providerId: 'fake-openai', modelId: 'fake-legacy' };
+
+const authGuard: CanActivate = {
+  canActivate(context: ExecutionContext): boolean {
+    const requestContext = context.switchToHttp().getRequest<{ user?: { id: string } }>();
+    requestContext.user = { id: 'user-1' };
+    return true;
+  },
+};
+
+function registryWithFake(): HarnessRegistry {
+  const registry = new HarnessRegistry();
+  registry.register(new FakeHarnessAdapter({ id: 'fake' }));
+  return registry;
+}
+
+describe('Harness selection HTTP surface', () => {
+  let app: INestApplication;
+  let repository: HarnessSelectionRepository;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [HarnessModule],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(authGuard)
+      .overrideProvider(HARNESS_REGISTRY)
+      .useValue(registryWithFake())
+      .compile();
+
+    // Real in-memory repository from the module graph — proves the module wired it.
+    repository = moduleRef.get(HarnessSelectionRepository);
+
+    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(() => {
+    // Reset owner-scoped state between tests via the public API surface.
+    repository.set({ userId: 'user-1', tenantId: 'user-1' }, VALID);
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('GET selection is server-scoped and ignores caller-supplied scope in the query', async () => {
+    const response = await request(app.getHttpServer())
+      .get('/api/chat/preferences/selection')
+      .query({ userId: 'attacker', tenantId: 'attacker-tenant', seatId: 'attacker-seat' });
+
+    expect(response.status).toBe(200);
+    // The returned selection is user-1's (guard-derived scope), not the query's.
+    expect(response.body.selection).toEqual(VALID);
+  });
+
+  it('PUT with a valid structured tuple persists and round-trips via GET', async () => {
+    const next = { harnessId: 'fake', providerId: 'fake-openai', modelId: 'fake-pro' };
+
+    const put = await request(app.getHttpServer())
+      .put('/api/chat/preferences/selection')
+      .send(next)
+      .set('Content-Type', 'application/json');
+    expect(put.status).toBe(200);
+    expect(put.body.selection).toEqual(next);
+
+    const get = await request(app.getHttpServer()).get('/api/chat/preferences/selection');
+    expect(get.status).toBe(200);
+    expect(get.body.selection).toEqual(next);
+  });
+
+  it('PUT with FREE TEXT is rejected 400 and does not mutate the stored selection', async () => {
+    const response = await request(app.getHttpServer())
+      .put('/api/chat/preferences/selection')
+      .send({ selection: 'gpt-4o' })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(400);
+
+    const get = await request(app.getHttpServer()).get('/api/chat/preferences/selection');
+    expect(get.body.selection).toEqual(VALID);
+  });
+
+  it.each([
+    ['seatId', { ...VALID, seatId: 'attacker-seat' }],
+    ['tenantId', { ...VALID, tenantId: 'attacker-tenant' }],
+    ['userId', { ...VALID, userId: 'attacker' }],
+    ['nativeSessionPath', { ...VALID, nativeSessionPath: '/var/native/x.jsonl' }],
+    ['executable', { ...VALID, executable: '/usr/bin/evil' }],
+    ['home', { ...VALID, home: '/home/attacker' }],
+    ['cwd', { ...VALID, cwd: '/tmp/attacker' }],
+  ])(
+    'PUT with an extra authority-bearing field (%s) is rejected 400 and does not mutate stored selection',
+    async (_name, body) => {
+      const response = await request(app.getHttpServer())
+        .put('/api/chat/preferences/selection')
+        .send(body)
+        .set('Content-Type', 'application/json');
+
+      expect(response.status).toBe(400);
+
+      const get = await request(app.getHttpServer()).get('/api/chat/preferences/selection');
+      expect(get.body.selection).toEqual(VALID);
+    },
+  );
+
+  it('PUT with an UNKNOWN tuple returns selection_invalid, unchanged and echoed unchanged (no fallback)', async () => {
+    const response = await request(app.getHttpServer())
+      .put('/api/chat/preferences/selection')
+      .send(UNKNOWN)
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(422);
+    expect(response.body.code).toBe('selection_invalid');
+    // Echoed back unchanged: no first-row / first-provider substitution.
+    expect(response.body.selection).toEqual(UNKNOWN);
+
+    const get = await request(app.getHttpServer()).get('/api/chat/preferences/selection');
+    expect(get.body.selection).toEqual(VALID);
+  });
+
+  it('PUT with a KNOWN-but-UNAVAILABLE tuple returns model_unavailable, unchanged (distinct from selection_invalid)', async () => {
+    const response = await request(app.getHttpServer())
+      .put('/api/chat/preferences/selection')
+      .send(UNAVAILABLE)
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(422);
+    expect(response.body.code).toBe('model_unavailable');
+    expect(response.body.selection).toEqual(UNAVAILABLE);
+
+    const get = await request(app.getHttpServer()).get('/api/chat/preferences/selection');
+    expect(get.body.selection).toEqual(VALID);
+  });
+});

apps/gateway/src/harness/harness-selection.controller.ts

@@ -0,0 +1,46 @@
+import { Body, Controller, Get, HttpException, HttpStatus, Put, UseGuards } from '@nestjs/common';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
+import { HarnessOperationError } from './harness.registry.js';
+import { HarnessSelectionService } from './harness-selection.service.js';
+import { HarnessSelectionInputDto, type SelectionResponseDto } from './harness.dto.js';
+
+/**
+ * Chat-preferences selection surface. The scope is ALWAYS derived on the server
+ * from the authenticated user (`scopeFromUser(CurrentUser)`); the request body and
+ * query string can never name another user, tenant, or seat. A typed selection
+ * failure (unknown tuple → `selection_invalid`, known-but-unavailable →
+ * `model_unavailable`) is returned as 422 with the requested tuple echoed back
+ * unchanged, and never mutates the stored selection.
+ */
+@Controller('api/chat/preferences/selection')
+@UseGuards(AuthGuard)
+export class HarnessSelectionController {
+  constructor(private readonly selection: HarnessSelectionService) {}
+
+  @Get()
+  get(@CurrentUser() user: AuthenticatedUserLike): SelectionResponseDto {
+    return { selection: this.selection.getSelection(scopeFromUser(user)) };
+  }
+
+  @Put()
+  async put(
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Body() dto: HarnessSelectionInputDto,
+  ): Promise<SelectionResponseDto> {
+    try {
+      const stored = await this.selection.setSelection(scopeFromUser(user), {
+        harnessId: dto.harnessId,
+        providerId: dto.providerId,
+        modelId: dto.modelId,
+      });
+      return { selection: stored };
+    } catch (error) {
+      if (error instanceof HarnessOperationError) {
+        throw new HttpException(error.dto, HttpStatus.UNPROCESSABLE_ENTITY);
+      }
+      throw error;
+    }
+  }
+}

apps/gateway/src/harness/harness-selection.service.ts

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import type { HarnessSelection } from '@mosaicstack/types';
+import type { ActorTenantScope } from '../auth/session-scope.js';
+import {
+  HarnessAdapterUnavailableError,
+  HarnessRegistry,
+  operationError,
+} from './harness.registry.js';
+import { HARNESS_REGISTRY } from './harness.tokens.js';
+import { readContextFromScope } from './harness.dto.js';
+import { HarnessSelectionRepository } from './harness-selection.repository.js';
+
+/**
+ * Selection logic for the Slice-Zero chat-preferences surface. It validates the
+ * requested harness/provider/model tuple against the live catalog with NO
+ * fallback substitution, then persists it owner-scoped. The stored selection is
+ * only ever mutated when the tuple is valid AND available.
+ */
+@Injectable()
+export class HarnessSelectionService {
+  constructor(
+    @Inject(HARNESS_REGISTRY) private readonly registry: HarnessRegistry,
+    private readonly repository: HarnessSelectionRepository,
+  ) {}
+
+  getSelection(scope: ActorTenantScope): HarnessSelection | null {
+    return this.repository.get(scope);
+  }
+
+  async setSelection(
+    scope: ActorTenantScope,
+    selection: HarnessSelection,
+  ): Promise<HarnessSelection> {
+    // Throws HarnessOperationError (selection_invalid / model_unavailable) with the
+    // requested tuple echoed back unchanged. The store is untouched on any throw.
+    await this.assertSelectionAvailable(scope, selection);
+    return this.repository.set(scope, selection);
+  }
+
+  private async assertSelectionAvailable(
+    scope: ActorTenantScope,
+    selection: HarnessSelection,
+  ): Promise<void> {
+    const correlationId = randomUUID();
+
+    let adapter;
+    try {
+      adapter = this.registry.get(selection.harnessId);
+    } catch (error) {
+      if (error instanceof HarnessAdapterUnavailableError) {
+        // An unknown harness makes the whole tuple invalid — no fallback adapter.
+        throw operationError(
+          'selection_invalid',
+          'The requested harness/provider/model tuple is not in the catalog.',
+          selection,
+          correlationId,
+        );
+      }
+      throw error;
+    }
+
+    const catalog = await adapter.catalog(readContextFromScope(scope));
+    const entry = catalog.models.find(
+      (candidate) =>
+        candidate.harnessId === selection.harnessId &&
+        candidate.providerId === selection.providerId &&
+        candidate.modelId === selection.modelId,
+    );
+
+    if (!entry) {
+      // No first-row / first-provider fallback: reject the requested tuple unchanged.
+      throw operationError(
+        'selection_invalid',
+        'The requested harness/provider/model tuple is not in the catalog.',
+        selection,
+        correlationId,
+      );
+    }
+    if (entry.availability === 'unavailable') {
+      throw operationError(
+        'model_unavailable',
+        'The requested model is currently unavailable.',
+        selection,
+        correlationId,
+        true,
+      );
+    }
+  }
+}

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

@@ -0,0 +1,138 @@
+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, describe, expect, it } from 'vitest';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { HarnessRegistry } from './harness.registry.js';
+import { HARNESS_REGISTRY } from './harness.tokens.js';
+import { FakeHarnessAdapter } from './testing/fake-harness.adapter.js';
+// The real module under test — importing it (not a hand-listed controllers/mocks
+// list) is what makes an unresolved provider fail loudly at app.init() (#1145 guard).
+import { HarnessModule } from './harness.module.js';
+
+// Fields that must NEVER surface on a browser-facing catalog/list response.
+const FORBIDDEN_KEYS = [
+  'executable',
+  'executablePath',
+  'home',
+  'homeDir',
+  'cwd',
+  'workingDir',
+  'workingDirectory',
+  'nativeSessionPath',
+  'sessionPath',
+  'env',
+  'secret',
+  'secrets',
+  'token',
+  'apiKey',
+];
+
+function assertNoForbiddenLeak(payload: unknown): void {
+  const serialized = JSON.stringify(payload).toLowerCase();
+  for (const key of FORBIDDEN_KEYS) {
+    expect(serialized).not.toContain(key.toLowerCase());
+  }
+}
+
+const authGuard: CanActivate = {
+  canActivate(context: ExecutionContext): boolean {
+    const requestContext = context.switchToHttp().getRequest<{ user?: { id: string } }>();
+    requestContext.user = { id: 'user-1' };
+    return true;
+  },
+};
+
+function registryWithFake(): HarnessRegistry {
+  const registry = new HarnessRegistry();
+  registry.register(new FakeHarnessAdapter({ id: 'fake' }));
+  return registry;
+}
+
+describe('Harness catalog HTTP surface', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [HarnessModule],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(authGuard)
+      .overrideProvider(HARNESS_REGISTRY)
+      .useValue(registryWithFake())
+      .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();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('boots the real HarnessModule so all providers resolve at app.init()', () => {
+    // If HarnessModule failed to resolve a provider, beforeAll's app.init() would
+    // have thrown and this suite would never reach here.
+    expect(app).toBeDefined();
+  });
+
+  it('GET /api/harnesses returns 200 with safe fields only', async () => {
+    const response = await request(app.getHttpServer()).get('/api/harnesses');
+
+    expect(response.status).toBe(200);
+    expect(Array.isArray(response.body)).toBe(true);
+    expect(response.body.length).toBeGreaterThan(0);
+    const summary = response.body[0];
+    expect(Object.keys(summary).sort()).toEqual(['capabilities', 'displayName', 'id']);
+    expect(summary.id).toBe('fake');
+    expect(typeof summary.displayName).toBe('string');
+    expect(Array.isArray(summary.capabilities)).toBe(true);
+    assertNoForbiddenLeak(response.body);
+  });
+
+  it('GET /api/harnesses/:harnessId/catalog returns 200 with safe catalog fields only', async () => {
+    const response = await request(app.getHttpServer()).get('/api/harnesses/fake/catalog');
+
+    expect(response.status).toBe(200);
+    expect(response.body.harnessId).toBe('fake');
+    expect(typeof response.body.version).toBe('string');
+    expect(typeof response.body.fingerprint).toBe('string');
+    expect(Array.isArray(response.body.models)).toBe(true);
+    expect(response.body.models.length).toBeGreaterThan(0);
+    const entry = response.body.models[0];
+    // Whitelisted catalog-entry fields only (no executables/paths/secrets).
+    expect(Object.keys(entry).sort()).toEqual(
+      [
+        'authState',
+        'availability',
+        'displayName',
+        'harnessId',
+        'inputTypes',
+        'modelId',
+        'providerId',
+        'reasoningCapability',
+      ].sort(),
+    );
+    assertNoForbiddenLeak(response.body);
+  });
+
+  it('GET catalog for an unknown harnessId returns a typed adapter_unavailable error, never a fallback catalog', async () => {
+    const response = await request(app.getHttpServer()).get('/api/harnesses/ghost-harness/catalog');
+
+    expect(response.status).toBe(404);
+    expect(response.body.code).toBe('adapter_unavailable');
+    // A fallback catalog would carry a models array; a typed error must not.
+    expect(response.body.models).toBeUndefined();
+  });
+});

apps/gateway/src/harness/harness.controller.ts

@@ -0,0 +1,65 @@
+import {
+  Controller,
+  Get,
+  HttpException,
+  HttpStatus,
+  Inject,
+  Param,
+  UseGuards,
+} from '@nestjs/common';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
+import { HarnessAdapterUnavailableError, HarnessRegistry } from './harness.registry.js';
+import { HARNESS_REGISTRY } from './harness.tokens.js';
+import {
+  readContextFromScope,
+  toHarnessSummary,
+  toSafeCatalog,
+  type HarnessCatalogDto,
+  type HarnessSummaryDto,
+} from './harness.dto.js';
+
+/**
+ * Generic harness catalog surface. It exposes only harness-neutral, browser-safe
+ * fields (identity, capabilities, provider/model catalog) — never executables,
+ * native paths, home/cwd, env, or secrets. There is NO provider-probe route here;
+ * `/api/providers` and `POST /api/providers/test` are intentionally out of scope.
+ */
+@Controller('api/harnesses')
+@UseGuards(AuthGuard)
+export class HarnessController {
+  constructor(@Inject(HARNESS_REGISTRY) private readonly registry: HarnessRegistry) {}
+
+  @Get()
+  async list(@CurrentUser() user: AuthenticatedUserLike): Promise<HarnessSummaryDto[]> {
+    const context = readContextFromScope(scopeFromUser(user));
+    const summaries: HarnessSummaryDto[] = [];
+    for (const adapter of this.registry.list()) {
+      summaries.push(toHarnessSummary(await adapter.describe(context)));
+    }
+    return summaries;
+  }
+
+  @Get(':harnessId/catalog')
+  async catalog(
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Param('harnessId') harnessId: string,
+  ): Promise<HarnessCatalogDto> {
+    const context = readContextFromScope(scopeFromUser(user));
+    let adapter;
+    try {
+      adapter = this.registry.get(harnessId);
+    } catch (error) {
+      if (error instanceof HarnessAdapterUnavailableError) {
+        // Typed failure — NEVER a fallback catalog for an unknown harness id.
+        throw new HttpException(
+          { code: error.code, message: error.message, harnessId },
+          HttpStatus.NOT_FOUND,
+        );
+      }
+      throw error;
+    }
+    return toSafeCatalog(await adapter.catalog(context));
+  }
+}

apps/gateway/src/harness/harness.dto.ts

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import { IsNotEmpty, IsString } from 'class-validator';
+import type {
+  HarnessActorContext,
+  HarnessAuthState,
+  HarnessCapability,
+  HarnessCatalog,
+  HarnessCatalogEntry,
+  HarnessDescriptor,
+  HarnessInputType,
+  HarnessModelAvailability,
+  HarnessSelection,
+} from '@mosaicstack/types';
+import type { ActorTenantScope } from '../auth/session-scope.js';
+
+/**
+ * Structured selection tuple accepted on `PUT /api/chat/preferences/selection`.
+ *
+ * The body is a STRUCTURED tuple (harness + provider + model), never a free-text
+ * model string. With `ValidationPipe({ whitelist: true, forbidNonWhitelisted: true })`
+ * any extra property — including smuggled server-authority fields such as
+ * `seatId`, `tenantId`, `userId`, `nativeSessionPath`, `executable`, `home`, `cwd` —
+ * is rejected with 400. There is deliberately no field through which a caller can
+ * name a scope; scope is derived on the server from the authenticated session.
+ */
+export class HarnessSelectionInputDto {
+  @IsString()
+  @IsNotEmpty()
+  harnessId!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  providerId!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  modelId!: string;
+}
+
+/** Browser-safe harness summary — identity and capabilities only. */
+export interface HarnessSummaryDto {
+  readonly id: string;
+  readonly displayName: string;
+  readonly capabilities: readonly HarnessCapability[];
+}
+
+/** Browser-safe catalog entry — no executables, paths, secrets, or env. */
+export interface HarnessCatalogEntryDto {
+  readonly harnessId: string;
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly displayName: string;
+  readonly reasoningCapability: boolean;
+  readonly inputTypes: readonly HarnessInputType[];
+  readonly authState: HarnessAuthState;
+  readonly availability: HarnessModelAvailability;
+}
+
+/** Browser-safe catalog envelope. */
+export interface HarnessCatalogDto {
+  readonly harnessId: string;
+  readonly version: string;
+  readonly fingerprint: string;
+  readonly models: readonly HarnessCatalogEntryDto[];
+}
+
+/** Response envelope for the caller's current selection (null when unset). */
+export interface SelectionResponseDto {
+  readonly selection: HarnessSelection | null;
+}
+
+/**
+ * Derive a server-trusted {@link HarnessActorContext} for read operations from the
+ * session-derived {@link ActorTenantScope}. All authority originates on the server;
+ * nothing here is caller-supplied. A fresh correlation id is minted per call.
+ */
+export function readContextFromScope(scope: ActorTenantScope): HarnessActorContext {
+  return {
+    actorId: scope.userId,
+    tenantId: scope.tenantId,
+    seatId: scope.userId,
+    correlationId: randomUUID(),
+  };
+}
+
+/** Project a descriptor onto the browser-safe summary shape (whitelist by construction). */
+export function toHarnessSummary(descriptor: HarnessDescriptor): HarnessSummaryDto {
+  return {
+    id: descriptor.id,
+    displayName: descriptor.displayName,
+    capabilities: [...descriptor.capabilities],
+  };
+}
+
+/** Project a catalog onto the browser-safe shape (whitelist by construction). */
+export function toSafeCatalog(catalog: HarnessCatalog): HarnessCatalogDto {
+  return {
+    harnessId: catalog.harnessId,
+    version: catalog.version,
+    fingerprint: catalog.fingerprint,
+    models: catalog.models.map(toSafeCatalogEntry),
+  };
+}
+
+function toSafeCatalogEntry(entry: HarnessCatalogEntry): HarnessCatalogEntryDto {
+  return {
+    harnessId: entry.harnessId,
+    providerId: entry.providerId,
+    modelId: entry.modelId,
+    displayName: entry.displayName,
+    reasoningCapability: entry.reasoningCapability,
+    inputTypes: [...entry.inputTypes],
+    authState: entry.authState,
+    availability: entry.availability,
+  };
+}

apps/gateway/src/harness/harness.module.ts

@@ -0,0 +1,37 @@
+import { Module } from '@nestjs/common';
+import { HarnessRegistry } from './harness.registry.js';
+import { HarnessService } from './harness.service.js';
+import {
+  HARNESS_CONVERSATION_SERVICE,
+  HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+  HARNESS_REGISTRY,
+  HARNESS_SERVICE,
+} from './harness.tokens.js';
+import { HarnessController } from './harness.controller.js';
+import { HarnessSelectionController } from './harness-selection.controller.js';
+import { HarnessSelectionService } from './harness-selection.service.js';
+import { HarnessSelectionRepository } from './harness-selection.repository.js';
+
+/**
+ * Wires the harness-neutral registry/service (Task Two) together with the
+ * Slice-Zero catalog and selection HTTP surfaces (Task Three).
+ *
+ * The registry is provided empty here; real harness adapters are registered in a
+ * later task. Because the controllers/services resolve their collaborators through
+ * this real module graph, an unresolved provider fails loudly at `app.init()`.
+ */
+@Module({
+  controllers: [HarnessController, HarnessSelectionController],
+  providers: [
+    { provide: HARNESS_REGISTRY, useFactory: () => new HarnessRegistry() },
+    { provide: HARNESS_SERVICE, useClass: HarnessService },
+    // Task Five: bind the conversation-service token to its explicit "not yet bound"
+    // sentinel. The pi-rpc router treats this as a hard, typed startup failure; Task 14
+    // replaces it with a real service. Exported so ChatModule's router can inject it.
+    { provide: HARNESS_CONVERSATION_SERVICE, useValue: HARNESS_CONVERSATION_SERVICE_UNAVAILABLE },
+    HarnessSelectionRepository,
+    HarnessSelectionService,
+  ],
+  exports: [HARNESS_REGISTRY, HARNESS_SERVICE, HARNESS_CONVERSATION_SERVICE],
+})
+export class HarnessModule {}

apps/gateway/src/harness/harness.tokens.ts

@@ -4,8 +4,42 @@
  * String tokens follow the existing Gateway convention (see `memory/memory.tokens.ts`)
  * and remain valid Nest `InjectionToken`s for `@Inject(...)`.
  */
+import type { HarnessConversationService } from '@mosaicstack/types';
+
 export const HARNESS_REGISTRY = 'HARNESS_REGISTRY' as const;
 export const HARNESS_SERVICE = 'HARNESS_SERVICE' as const;
 
 export type HarnessRegistryToken = typeof HARNESS_REGISTRY;
 export type HarnessServiceToken = typeof HARNESS_SERVICE;
+
+/**
+ * Token for the {@link HarnessConversationService} that {@link HarnessChatRuntime}
+ * depends on. Until Task 14 provides a real implementation, `HarnessModule` binds
+ * the {@link HARNESS_CONVERSATION_SERVICE_UNAVAILABLE} sentinel here, and the
+ * `pi-rpc` router treats that sentinel as a hard, typed startup failure.
+ */
+export const HARNESS_CONVERSATION_SERVICE = 'HARNESS_CONVERSATION_SERVICE' as const;
+
+export type HarnessConversationServiceToken = typeof HARNESS_CONVERSATION_SERVICE;
+
+/**
+ * Explicit "not yet bound" value for {@link HARNESS_CONVERSATION_SERVICE}. It is a
+ * distinct sentinel — never `null`/`undefined` — so an unbound service is an
+ * intentional, checkable state rather than an accidental nil that could read as
+ * "present". Replaced by a real service in Task 14.
+ */
+export const HARNESS_CONVERSATION_SERVICE_UNAVAILABLE: unique symbol = Symbol(
+  'HARNESS_CONVERSATION_SERVICE_UNAVAILABLE',
+);
+
+/** A binding for {@link HARNESS_CONVERSATION_SERVICE}: a real service or the sentinel. */
+export type HarnessConversationServiceBinding =
+  | HarnessConversationService
+  | typeof HARNESS_CONVERSATION_SERVICE_UNAVAILABLE;
+
+/** Narrows a binding to a usable service, excluding the unavailable sentinel. */
+export function isHarnessConversationServiceAvailable(
+  binding: HarnessConversationServiceBinding,
+): binding is HarnessConversationService {
+  return binding !== HARNESS_CONVERSATION_SERVICE_UNAVAILABLE;
+}

apps/gateway/src/plugin/discord-ingress.security.spec.ts

@@ -12,6 +12,10 @@ import { RuntimeProviderService } from '../agent/runtime-provider-registry.servi
 import { ChatGateway } from '../chat/chat.gateway.js';
 import { CommandAuthorizationService } from '../commands/command-authorization.service.js';
 import { validateDiscordServiceToken } from '../chat/chat.gateway-auth.js';
+import { ChatRuntimeRouter } from '../chat/chat-runtime-router.js';
+import { EmbeddedChatRuntime } from '../chat/embedded-chat.runtime.js';
+import { HarnessChatRuntime } from '../chat/harness-chat.runtime.js';
+import { HarnessRegistry } from '../harness/harness.registry.js';
 import { DiscordReplayProtector } from './discord-replay-protector.js';
 
 const SERVICE_TOKEN = 'test-service-token';
@@ -25,6 +29,7 @@ const ENV_KEYS = [
   'DISCORD_ALLOWED_USER_IDS',
   'MOSAIC_AGENT_NAME',
   'MOSAIC_AGENT_CONFIG_ID',
+  'CHAT_HARNESS_RUNTIME',
 ] as const;
 const savedEnv = new Map<string, string | undefined>();
 
@@ -150,6 +155,57 @@ function createPayload(overrides: Partial<DiscordIngressPayload> = {}): DiscordI
   };
 }
 
+/**
+ * Task 5 fence (C): the Discord SEND path runs through the exclusive {@link ChatRuntimeRouter},
+ * constructed here in `pi-rpc` mode with a fully-resolved runtime (`active` = harness). A verified
+ * Discord *service* turn must nonetheless execute on the {@link EmbeddedChatRuntime} — never the
+ * harness, never the routing engine — per the Q1/Q2 adjudication: the router owns a dedicated
+ * verified-ingress dispatch that delegates to embedded regardless of mode, with zero harness
+ * fallback. The gateway is given the router in the former direct-`AgentService` constructor slot.
+ *
+ * RED today: production still reads that slot as a bare `AgentService`, so `this.agentService`
+ * resolves to the router, `getSession(...)` is not a function, the send path throws and is caught
+ * (an `error` is emitted and the handler returns) BEFORE it ever reaches the embedded runtime. The
+ * failure is behavioural wiring — collection, DI, and `onModuleInit` all succeed. GREEN re-routes
+ * the verified Discord dispatch through the router into the embedded runtime, satisfying the
+ * preserved create/prompt assertions without weakening any control. `harnessConversations.append`
+ * proves the harness path is never touched even though the pi-rpc router resolved it as `active`.
+ *
+ * Correction #4 is proved behaviourally, not by naming an accessor: the verified-ingress dispatch
+ * is reachable only from the fully-verified `discordService` branch (the create/prompt tests below)
+ * and never from a browser-emittable socket event (the browser-forgery refusal test).
+ */
+function readyPiRpcRegistry(): HarnessRegistry {
+  const registry = new HarnessRegistry();
+  // A registered 'pi' adapter + an available (non-sentinel) conversation service let the pi-rpc
+  // router resolve `active` = harness instead of failing closed at init, so these tests model the
+  // real hostile condition — the harness runtime IS live — rather than a degraded router.
+  registry.register({ id: 'pi' } as never);
+  return registry;
+}
+
+function piRpcRouterFronting(
+  agentService: unknown,
+  harnessConversations: { append: ReturnType<typeof vi.fn> },
+): ChatRuntimeRouter {
+  const routerConversationServiceTripwire = {
+    append: () => {
+      throw new Error('router conversation service must not be resolved on the Discord path');
+    },
+  };
+  const embedded = new EmbeddedChatRuntime(agentService as never);
+  const harness = new HarnessChatRuntime(harnessConversations as never);
+  const router = new ChatRuntimeRouter(
+    readyPiRpcRegistry(),
+    routerConversationServiceTripwire as never,
+    embedded,
+    harness,
+    'pi-rpc',
+  );
+  router.onModuleInit();
+  return router;
+}
+
 describe('Discord ingress security', () => {
   it('keeps legacy role-only bindings valid while withholding privileged actor identity', () => {
     const [binding] = parseDiscordInteractionBindings(
@@ -433,6 +489,7 @@ describe('Discord ingress security', () => {
 
   it("selects each binding's trusted logical-agent config when creating Discord sessions", async () => {
     configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
     process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001,channel-002';
     process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
       {
@@ -489,8 +546,9 @@ describe('Discord ingress security', () => {
       },
     };
     const routingEngine = { resolve: vi.fn() };
+    const harnessConversations = { append: vi.fn() };
     const gateway = new ChatGateway(
-      agentService as never,
+      piRpcRouterFronting(agentService, harnessConversations) as never,
       {} as never,
       brain as never,
       {} as never,
@@ -531,6 +589,575 @@ describe('Discord ingress security', () => {
       expect.objectContaining({ agentConfigId: 'agent-config-orion' }),
     );
     expect(routingEngine.resolve).not.toHaveBeenCalled();
+    // Even though the pi-rpc router resolved the harness as `active`, verified Discord ingress must
+    // never touch it — the create path stays on the embedded runtime.
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+  });
+
+  it('dispatches a verified Discord SEND once and drops a byte-identical replay with zero additional dispatch/persist/ack (Task 5 G4)', async () => {
+    configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
+        guildId: 'guild-001',
+        channelId: 'channel-001',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+    ]);
+    const session = {
+      provider: 'configured-provider',
+      modelId: 'configured-model',
+      agentConfigId: 'agent-config-nova',
+      agentName: 'Nova',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const createSession = vi.fn().mockResolvedValue(session);
+    const prompt = vi.fn().mockResolvedValue(undefined);
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(undefined),
+      createSession,
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt,
+    };
+    const addMessage = vi.fn().mockResolvedValue({ id: 'discord-persisted-message' });
+    const brain = {
+      agents: { findById: vi.fn((id: string) => Promise.resolve({ id, name: 'Nova' })) },
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        findMessages: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage,
+      },
+    };
+    const harnessConversations = { append: vi.fn() };
+    const gateway = new ChatGateway(
+      piRpcRouterFronting(agentService, harnessConversations) as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      { resolve: vi.fn() } as never,
+    );
+    const client = {
+      id: 'discord-client-replay',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+    const ackCount = (): number =>
+      client.emit.mock.calls.filter((call) => call[0] === 'message:ack').length;
+
+    // One fully-valid signed envelope; the replay reuses the SAME object (same messageId).
+    const envelope = ingressEnvelope('verified once', 'discord-replay-001', {
+      conversationId: 'Nova:discord:channel-001',
+    });
+
+    // First delivery: the verified-Discord SEND runs the full embedded dispatch exactly once.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+
+    // Byte-identical replay: the messageId is already claimed, so resolveDiscordIngress returns
+    // null and the SEND handler bails before dispatch/persist/ack. Every effect stays at exactly one.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+    // The harness runtime is never touched on either delivery.
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+  });
+
+  it('a verified SEND that fails the configured service identity consumes no replay claim, so a corrected byte-identical retry dispatches/persists/acks exactly once and a later duplicate stays fail-closed (Task 5 item 4 — claim ordering)', async () => {
+    configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
+        guildId: 'guild-001',
+        channelId: 'channel-001',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+    ]);
+    const session = {
+      provider: 'configured-provider',
+      modelId: 'configured-model',
+      agentConfigId: 'agent-config-nova',
+      agentName: 'Nova',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const createSession = vi.fn().mockResolvedValue(session);
+    const prompt = vi.fn().mockResolvedValue(undefined);
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(undefined),
+      createSession,
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt,
+    };
+    const addMessage = vi.fn().mockResolvedValue({ id: 'discord-persisted-message' });
+    const brain = {
+      agents: { findById: vi.fn((id: string) => Promise.resolve({ id, name: 'Nova' })) },
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        findMessages: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage,
+      },
+    };
+    const harnessConversations = { append: vi.fn() };
+    const gateway = new ChatGateway(
+      piRpcRouterFronting(agentService, harnessConversations) as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      { resolve: vi.fn() } as never,
+    );
+    const client = {
+      id: 'discord-client-claim-ordering',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+    const ackCount = (): number =>
+      client.emit.mock.calls.filter((call) => call[0] === 'message:ack').length;
+
+    // A single fully-valid signed envelope, reused byte-for-byte across all three deliveries.
+    const envelope = ingressEnvelope('verified once with late identity', 'discord-order-001', {
+      conversationId: 'Nova:discord:channel-001',
+    });
+
+    // (1) Configured service identity is MISSING. The envelope is validly signed and passes the
+    //     binding + route checks, but the SEND must refuse at the identity gate BEFORE any claim
+    //     or effect. If the claim fires ahead of that gate, this delivery silently burns the
+    //     replay claim for `discord-order-001` even though nothing dispatched.
+    delete process.env['DISCORD_SERVICE_USER_ID'];
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(0);
+    expect(prompt).toHaveBeenCalledTimes(0);
+    expect(addMessage).toHaveBeenCalledTimes(0);
+    expect(ackCount()).toBe(0);
+
+    // (2) Identity is now configured; the operator resends the SAME envelope byte-for-byte. Because
+    //     step (1) consumed no claim, this corrected retry claims once and runs the full embedded
+    //     dispatch exactly once. (Under the pre-fix ordering the claim was already spent in step (1),
+    //     so this retry is dropped as a replay and never dispatches — the RED this test drives.)
+    process.env['DISCORD_SERVICE_USER_ID'] = 'discord-service';
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+
+    // (3) A genuine duplicate after a committed turn stays fail-closed: the claim taken in step (2)
+    //     blocks it, so every effect remains at exactly one.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+  });
+
+  it('a verified SEND whose configured agent record fails reconciliation consumes no replay claim, so a corrected byte-identical retry dispatches/persists/acks exactly once (Task 5 finding 3)', async () => {
+    configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
+        guildId: 'guild-001',
+        channelId: 'channel-001',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+    ]);
+    const session = {
+      provider: 'configured-provider',
+      modelId: 'configured-model',
+      agentConfigId: 'agent-config-nova',
+      agentName: 'Nova',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const createSession = vi.fn().mockResolvedValue(session);
+    const prompt = vi.fn().mockResolvedValue(undefined);
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(undefined),
+      createSession,
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt,
+    };
+    const addMessage = vi.fn().mockResolvedValue({ id: 'discord-persisted-message' });
+    // The durable agent record does not reconcile on the first delivery (its name no longer matches
+    // the verified binding's instance id), then reconciles cleanly on the corrected retry.
+    const findAgent = vi
+      .fn()
+      .mockResolvedValueOnce({ id: 'agent-config-nova', name: 'Renamed-Away' })
+      .mockResolvedValue({ id: 'agent-config-nova', name: 'Nova' });
+    const brain = {
+      agents: { findById: findAgent },
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        findMessages: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage,
+      },
+    };
+    const harnessConversations = { append: vi.fn() };
+    const gateway = new ChatGateway(
+      piRpcRouterFronting(agentService, harnessConversations) as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      { resolve: vi.fn() } as never,
+    );
+    const client = {
+      id: 'discord-client-reconcile',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+    const ackCount = (): number =>
+      client.emit.mock.calls.filter((call) => call[0] === 'message:ack').length;
+
+    const envelope = ingressEnvelope(
+      'verified once with stale agent record',
+      'discord-reconcile-001',
+      {
+        conversationId: 'Nova:discord:channel-001',
+      },
+    );
+
+    // (1) The configured-agent reconcile runs BEFORE the replay claim. A mismatch refuses the turn
+    //     and, crucially, consumes no claim for discord-reconcile-001 — nothing dispatches.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(0);
+    expect(prompt).toHaveBeenCalledTimes(0);
+    expect(addMessage).toHaveBeenCalledTimes(0);
+    expect(ackCount()).toBe(0);
+
+    // (2) The record now reconciles; because step (1) took no claim, this byte-identical retry claims
+    //     once and runs the full embedded dispatch exactly once. (Pre-fix, the claim was spent ahead
+    //     of the reconcile in step (1), so this retry was dropped as a replay — the RED this drives.)
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+
+    // (3) A genuine duplicate after the committed turn stays fail-closed.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+  });
+
+  it('a verified SEND refuses to reuse a same-scope embedded session minted under a different configured identity, with zero prompt/persist/ack (Task 5 finding 3)', async () => {
+    configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
+        guildId: 'guild-001',
+        channelId: 'channel-001',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+    ]);
+    // A live session already exists for this conversation/scope, but it was minted under a DIFFERENT
+    // configured agent (Orion). The verified binding reconciles to Nova, so reusing this session would
+    // execute one agent's turn under another agent's verified label — the reuse guard must refuse it.
+    const foreignIdentitySession = {
+      provider: 'configured-provider',
+      modelId: 'configured-model',
+      agentConfigId: 'agent-config-orion',
+      agentName: 'Orion',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const prompt = vi.fn().mockResolvedValue(undefined);
+    const createSession = vi.fn().mockResolvedValue(foreignIdentitySession);
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(foreignIdentitySession),
+      createSession,
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt,
+    };
+    const addMessage = vi.fn().mockResolvedValue({ id: 'discord-persisted-message' });
+    const brain = {
+      agents: { findById: vi.fn((id: string) => Promise.resolve({ id, name: 'Nova' })) },
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        findMessages: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage,
+      },
+    };
+    const harnessConversations = { append: vi.fn() };
+    const gateway = new ChatGateway(
+      piRpcRouterFronting(agentService, harnessConversations) as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      { resolve: vi.fn() } as never,
+    );
+    const client = {
+      id: 'discord-client-identity-swap',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+
+    await gateway.handleMessage(
+      client as never,
+      ingressEnvelope('reuse under a different identity', 'discord-identity-swap-001', {
+        conversationId: 'Nova:discord:channel-001',
+      }),
+    );
+
+    // Refused at the embedded reuse guard: no prompt, no persist, no ack — only a typed refusal.
+    expect(prompt).not.toHaveBeenCalled();
+    expect(addMessage).not.toHaveBeenCalled();
+    expect(client.emit).not.toHaveBeenCalledWith('message:ack', expect.anything());
+    expect(client.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: 'Nova:discord:channel-001' }),
+    );
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+  });
+
+  it('a verified SEND whose configured agent record resolves under a different id fails reconciliation, consumes no replay claim, and a corrected byte-identical retry dispatches/persists/acks exactly once (Task 5 finding 3 — id axis)', async () => {
+    configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
+        guildId: 'guild-001',
+        channelId: 'channel-001',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+    ]);
+    const session = {
+      provider: 'configured-provider',
+      modelId: 'configured-model',
+      agentConfigId: 'agent-config-nova',
+      agentName: 'Nova',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const createSession = vi.fn().mockResolvedValue(session);
+    const prompt = vi.fn().mockResolvedValue(undefined);
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(undefined),
+      createSession,
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt,
+    };
+    const addMessage = vi.fn().mockResolvedValue({ id: 'discord-persisted-message' });
+    // The name matches the verified binding, but the record's own id is a DIFFERENT agent config —
+    // an aliased/substituted lookup. Exact-id reconciliation must refuse it on the first delivery,
+    // then admit the corrected record whose id matches the binding.
+    const findAgent = vi
+      .fn()
+      .mockResolvedValueOnce({ id: 'agent-config-elsewhere', name: 'Nova' })
+      .mockResolvedValue({ id: 'agent-config-nova', name: 'Nova' });
+    const brain = {
+      agents: { findById: findAgent },
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        findMessages: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage,
+      },
+    };
+    const harnessConversations = { append: vi.fn() };
+    const gateway = new ChatGateway(
+      piRpcRouterFronting(agentService, harnessConversations) as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      { resolve: vi.fn() } as never,
+    );
+    const client = {
+      id: 'discord-client-reconcile-id',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+    const ackCount = (): number =>
+      client.emit.mock.calls.filter((call) => call[0] === 'message:ack').length;
+
+    const envelope = ingressEnvelope(
+      'verified once with aliased agent id',
+      'discord-reconcile-id-001',
+      {
+        conversationId: 'Nova:discord:channel-001',
+      },
+    );
+
+    // (1) The record's id differs from the binding's agentConfigId. Exact-id reconcile refuses the
+    //     turn BEFORE the replay claim, so nothing dispatches and the claim stays available.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(0);
+    expect(prompt).toHaveBeenCalledTimes(0);
+    expect(addMessage).toHaveBeenCalledTimes(0);
+    expect(ackCount()).toBe(0);
+
+    // (2) The record now reconciles on both id and name; because step (1) took no claim, this
+    //     byte-identical retry claims once and runs the full embedded dispatch exactly once.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+
+    // (3) A genuine duplicate after the committed turn stays fail-closed.
+    await gateway.handleMessage(client as never, envelope);
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).toHaveBeenCalledTimes(1);
+    expect(addMessage).toHaveBeenCalledTimes(1);
+    expect(ackCount()).toBe(1);
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+  });
+
+  it('a verified SEND refuses a freshly minted same-scope session whose identity differs from the reconciled configured agent, with zero prompt/persist/ack (Task 5 finding 3 — post-create)', async () => {
+    configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
+        guildId: 'guild-001',
+        channelId: 'channel-001',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+    ]);
+    // No live session exists for this scope, so the runtime MINTS one — but createSession returns a
+    // session carrying a DIFFERENT configured identity (Orion) than the reconciled binding (Nova).
+    // The post-create identity recheck must refuse it rather than dispatch one agent's turn under
+    // another agent's verified label. (The existing reuse test covers the getSession path; this
+    // covers the createSession path scrappy flagged as unvalidated.)
+    const mintedForeignSession = {
+      provider: 'configured-provider',
+      modelId: 'configured-model',
+      agentConfigId: 'agent-config-orion',
+      agentName: 'Orion',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const prompt = vi.fn().mockResolvedValue(undefined);
+    const createSession = vi.fn().mockResolvedValue(mintedForeignSession);
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(undefined),
+      createSession,
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt,
+    };
+    const addMessage = vi.fn().mockResolvedValue({ id: 'discord-persisted-message' });
+    const brain = {
+      agents: { findById: vi.fn((id: string) => Promise.resolve({ id, name: 'Nova' })) },
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        findMessages: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage,
+      },
+    };
+    const harnessConversations = { append: vi.fn() };
+    const gateway = new ChatGateway(
+      piRpcRouterFronting(agentService, harnessConversations) as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      { resolve: vi.fn() } as never,
+    );
+    const client = {
+      id: 'discord-client-postcreate-mismatch',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+
+    await gateway.handleMessage(
+      client as never,
+      ingressEnvelope('mint under a different identity', 'discord-postcreate-001', {
+        conversationId: 'Nova:discord:channel-001',
+      }),
+    );
+
+    // The freshly minted session failed the post-create identity recheck: refused with a typed
+    // error, no prompt, no persist, no ack.
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(prompt).not.toHaveBeenCalled();
+    expect(addMessage).not.toHaveBeenCalled();
+    expect(client.emit).not.toHaveBeenCalledWith('message:ack', expect.anything());
+    expect(client.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: 'Nova:discord:channel-001' }),
+    );
+    expect(harnessConversations.append).not.toHaveBeenCalled();
   });
 
   it('retains validated persisted attachments in resumed conversation history', async () => {
@@ -593,11 +1220,16 @@ describe('Discord ingress security', () => {
 
   it('preserves authenticated attachment metadata through persistence and agent dispatch', async () => {
     configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
     const prompt = vi.fn().mockResolvedValue(undefined);
-    const addMessage = vi.fn().mockResolvedValue(undefined);
+    const addMessage = vi.fn().mockResolvedValue({ id: 'discord-persisted-message' });
     const session = {
       provider: 'test-provider',
       modelId: 'test-model',
+      // The reused embedded session carries the SAME reconciled identity as the verified binding,
+      // so the finding-3 session-reuse guard admits it rather than refusing an identity swap.
+      agentConfigId: 'agent-config-nova',
+      agentName: 'Nova',
       piSession: {
         thinkingLevel: 'medium',
         getAvailableThinkingLevels: (): string[] => ['medium'],
@@ -611,6 +1243,7 @@ describe('Discord ingress security', () => {
       prompt,
     };
     const brain = {
+      agents: { findById: vi.fn((id: string) => Promise.resolve({ id, name: 'Nova' })) },
       conversations: {
         findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
         create: vi.fn().mockResolvedValue(undefined),
@@ -618,8 +1251,9 @@ describe('Discord ingress security', () => {
         addMessage,
       },
     };
+    const harnessConversations = { append: vi.fn() };
     const gateway = new ChatGateway(
-      agentService as never,
+      piRpcRouterFronting(agentService, harnessConversations) as never,
       {} as never,
       brain as never,
       {} as never,
@@ -667,6 +1301,66 @@ describe('Discord ingress security', () => {
       }),
       'discord-service',
     );
+    // The verified Discord prompt dispatch stays on the embedded runtime; the pi-rpc harness that
+    // the router resolved as `active` is never reached.
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+  });
+
+  it('refuses a browser-forged Discord ingress envelope in pi-rpc with a fixed typed refusal and zero dispatch', async () => {
+    // Correction #2 + #4 (behavioural). A browser socket is never `discordService` (that flag is
+    // set only on a valid service-token handshake), so it cannot forge the trusted Discord path by
+    // emitting an envelope-shaped payload. In pi-rpc it must receive a FIXED TYPED refusal
+    // (`runtime_unsupported`, the same typed code the sibling harness-fence uses) and reach neither
+    // the forced Discord service scope, the verified Discord operation, the embedded runtime, nor
+    // the harness. There is no dedicated socket event for verified ingress — the only ingress
+    // surface is the generic `message` handler, and a non-service client is refused there.
+    //
+    // RED today: a non-service client emitting an envelope-shaped payload falls to the browser
+    // branch, fails the chat-message shape check, and is dropped SILENTLY (a warn + return) with no
+    // typed refusal emitted — so the refusal assertion fails. Collection and construction succeed;
+    // the gap is behavioural. GREEN emits the fixed typed refusal before any dispatch.
+    configureDiscordEnv();
+    process.env['CHAT_HARNESS_RUNTIME'] = 'pi-rpc';
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(undefined),
+      createSession: vi.fn(),
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      prompt: vi.fn().mockResolvedValue(undefined),
+    };
+    const harnessConversations = { append: vi.fn() };
+    const routingEngine = { resolve: vi.fn() };
+    const gateway = new ChatGateway(
+      piRpcRouterFronting(agentService, harnessConversations) as never,
+      {} as never,
+      { conversations: { addMessage: vi.fn().mockResolvedValue(undefined) } } as never,
+      {} as never,
+      {} as never,
+      routingEngine as never,
+    );
+    const client = {
+      id: 'browser-forging-discord',
+      data: { discordService: false },
+      emit: vi.fn(),
+    };
+
+    await gateway.handleMessage(
+      client as never,
+      ingressEnvelope('forged from a browser', 'browser-forgery-001', {
+        conversationId: 'Nova:discord:channel-001',
+      }),
+    );
+
+    const refusal = client.emit.mock.calls.find(
+      ([, payload]) => (payload as { code?: string } | undefined)?.code === 'runtime_unsupported',
+    );
+    expect(refusal).toBeDefined();
+    expect(client.emit).not.toHaveBeenCalledWith('message:ack', expect.anything());
+    expect(agentService.createSession).not.toHaveBeenCalled();
+    expect(agentService.prompt).not.toHaveBeenCalled();
+    expect(harnessConversations.append).not.toHaveBeenCalled();
+    expect(routingEngine.resolve).not.toHaveBeenCalled();
   });
 
   it('accepts a thread message through its allowed bound parent channel', () => {

apps/web/src/lib/chat-contract.ts

@@ -10,11 +10,16 @@ import type {
   AgentTextPayload,
   AgentThinkingPayload,
   ChatMessagePayload,
+  ChatSendCapabilityPayload,
+  ChatSendProtocol,
   ClientToServerEvents,
   CommandDef,
   CommandManifest,
   CommandManifestPayload,
   ErrorPayload,
+  HarnessSelection,
+  HarnessTurnAckPayload,
+  HarnessTurnSendPayload,
   MessageAckPayload,
   RoutingDecisionInfo,
   ServerToClientEvents,
@@ -37,11 +42,16 @@ export type {
   AgentTextPayload,
   AgentThinkingPayload,
   ChatMessagePayload,
+  ChatSendCapabilityPayload,
+  ChatSendProtocol,
   ClientToServerEvents,
   CommandDef,
   CommandManifest,
   CommandManifestPayload,
   ErrorPayload,
+  HarnessSelection,
+  HarnessTurnAckPayload,
+  HarnessTurnSendPayload,
   MessageAckPayload,
   RoutingDecisionInfo,
   ServerToClientEvents,

apps/web/src/lib/types.ts

@@ -1,3 +1,42 @@
+import type {
+  HarnessAuthState,
+  HarnessModelAvailability,
+  HarnessSelection,
+} from '@mosaicstack/types';
+
+// The exact harness/provider/model tuple and its closed enum companions are the
+// shared domain types — re-exported here so web consumers (and the runtime
+// guards) import one shape, never a divergent local redefinition.
+export type { HarnessSelection, HarnessAuthState, HarnessModelAvailability };
+
+/** Harness summary row from `GET /api/harnesses` (the `HarnessSummaryDto`). The
+ * harness id is kept distinct from any provider id — they are never merged. */
+export interface HarnessSummary {
+  id: string;
+  displayName: string;
+  capabilities: string[];
+}
+
+/** One selectable model in a harness catalog. Extends the `{harnessId,
+ * providerId, modelId}` tuple with the display/availability metadata the UI
+ * needs; `inputTypes` is kept as a plain `string[]` on the client boundary
+ * because it arrives from untrusted JSON and is only ever displayed. */
+export interface HarnessCatalogEntry extends HarnessSelection {
+  displayName: string;
+  reasoningCapability: boolean;
+  inputTypes: string[];
+  authState: HarnessAuthState;
+  availability: HarnessModelAvailability;
+}
+
+/** Harness-scoped catalog from `GET /api/harnesses/:harnessId/catalog`. */
+export interface HarnessCatalog {
+  harnessId: string;
+  version: string;
+  fingerprint: string;
+  models: HarnessCatalogEntry[];
+}
+
 /** Conversation returned by the gateway API. */
 export interface Conversation {
   id: string;

apps/web/src/spa/chat/chat-api.spec.ts

@@ -0,0 +1,195 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  fetchCatalog,
+  fetchHarnesses,
+  fetchPersistedSelection,
+  persistSelection,
+} from './chat-api';
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+function stubFetch(): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+/** Every URL the client actually requested, across all calls. */
+function requestedUrls(fetchMock: ReturnType<typeof vi.fn>): string[] {
+  return fetchMock.mock.calls.map((call) => String(call[0]));
+}
+
+describe('chat-api', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('fetchHarnesses GETs /api/harnesses and returns typed summaries (harness id separate from provider)', async () => {
+    const fetchMock = stubFetch();
+    fetchMock.mockResolvedValue(
+      json([
+        { id: 'pi', displayName: 'Pi', capabilities: ['chat', 'tools'] },
+        { id: 'openai', displayName: 'OpenAI', capabilities: ['chat'] },
+      ]),
+    );
+
+    const harnesses = await fetchHarnesses();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('/api/harnesses');
+    expect(harnesses).toEqual([
+      { id: 'pi', displayName: 'Pi', capabilities: ['chat', 'tools'] },
+      { id: 'openai', displayName: 'OpenAI', capabilities: ['chat'] },
+    ]);
+  });
+
+  it('fetchCatalog GETs the harness-scoped catalog and returns only its model entries', async () => {
+    const fetchMock = stubFetch();
+    fetchMock.mockResolvedValue(
+      json({
+        harnessId: 'pi',
+        version: '2026-08-11',
+        fingerprint: 'abc123',
+        models: [
+          {
+            harnessId: 'pi',
+            providerId: 'openai',
+            modelId: 'gpt-5',
+            displayName: 'GPT-5',
+            reasoningCapability: true,
+            inputTypes: ['text'],
+            authState: 'ready',
+            availability: 'available',
+          },
+        ],
+      }),
+    );
+
+    const result = await fetchCatalog('pi');
+
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('/api/harnesses/pi/catalog');
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('expected ok catalog');
+    expect(result.catalog.harnessId).toBe('pi');
+    expect(result.catalog.models).toHaveLength(1);
+    expect(result.catalog.models[0]).toMatchObject({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+      availability: 'available',
+    });
+  });
+
+  it('normalizes a catalog 404 into a typed catalog_unavailable result without surfacing the raw body', async () => {
+    const fetchMock = stubFetch();
+    fetchMock.mockResolvedValue(
+      json(
+        {
+          code: 'adapter_unavailable',
+          message: 'raw gateway detail that must not leak verbatim',
+          harnessId: 'attacker-echo',
+          extra: { hostile: 'blob' },
+        },
+        404,
+      ),
+    );
+
+    const result = await fetchCatalog('ghost');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('expected unavailable result');
+    expect(result.code).toBe('catalog_unavailable');
+    // harnessId comes from the request, never the (untrusted) response body.
+    expect(result.harnessId).toBe('ghost');
+    expect(typeof result.message).toBe('string');
+    // The raw response body is never rendered/returned verbatim.
+    expect(JSON.stringify(result)).not.toContain('hostile');
+    expect(JSON.stringify(result)).not.toContain('attacker-echo');
+  });
+
+  it('fetchPersistedSelection returns the stored tuple, or null when unset', async () => {
+    const fetchMock = stubFetch();
+    fetchMock.mockResolvedValueOnce(
+      json({ selection: { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' } }),
+    );
+    await expect(fetchPersistedSelection()).resolves.toEqual({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+    });
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('/api/chat/preferences/selection');
+
+    fetchMock.mockResolvedValueOnce(json({ selection: null }));
+    await expect(fetchPersistedSelection()).resolves.toBeNull();
+  });
+
+  it('persistSelection PUTs the structured tuple (not free text) and returns the confirmed selection', async () => {
+    const fetchMock = stubFetch();
+    fetchMock.mockResolvedValue(
+      json({ selection: { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' } }),
+    );
+
+    const result = await persistSelection({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+    });
+
+    expect(result.ok).toBe(true);
+    const call = fetchMock.mock.calls[0];
+    expect(String(call?.[0])).toBe('/api/chat/preferences/selection');
+    const init = call?.[1] as RequestInit;
+    expect(String(init.method).toUpperCase()).toBe('PUT');
+    // The body is exactly the structured tuple — harness/provider/model kept distinct.
+    expect(JSON.parse(String(init.body))).toEqual({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+    });
+  });
+
+  it('normalizes a selection 422 into a typed error preserving the requested tuple exactly', async () => {
+    const fetchMock = stubFetch();
+    fetchMock.mockResolvedValue(
+      json(
+        {
+          code: 'model_unavailable',
+          message: 'raw detail that must not leak',
+          selection: { harnessId: 'x', providerId: 'y', modelId: 'z' },
+        },
+        422,
+      ),
+    );
+
+    const requested = { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' };
+    const result = await persistSelection(requested);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('expected failed persist');
+    expect(['selection_invalid', 'model_unavailable']).toContain(result.code);
+    // The requested tuple is preserved unchanged — not replaced by the body's echo.
+    expect(result.requested).toEqual(requested);
+    expect(JSON.stringify(result)).not.toContain('raw detail');
+  });
+
+  it('never requests any /api/providers* endpoint', async () => {
+    const fetchMock = stubFetch();
+    fetchMock.mockResolvedValue(json([]));
+    await fetchHarnesses();
+    fetchMock.mockResolvedValue(
+      json({ harnessId: 'pi', version: '1', fingerprint: 'f', models: [] }),
+    );
+    await fetchCatalog('pi');
+    fetchMock.mockResolvedValue(json({ selection: null }));
+    await fetchPersistedSelection();
+
+    for (const url of requestedUrls(fetchMock)) {
+      expect(url).not.toContain('/api/providers');
+    }
+  });
+});

apps/web/src/spa/chat/chat-api.ts

@@ -0,0 +1,132 @@
+/**
+ * Typed fetch wrappers for the Task-3 harness HTTP contract the chat selection
+ * UI depends on. Every response body is untrusted and is normalized through the
+ * runtime guards before it reaches state — a 404 (catalog) and a 422 (selection)
+ * are mapped to typed, body-free error results so a raw gateway body is never
+ * rendered, and the caller's requested tuple is preserved verbatim on failure.
+ *
+ * This module talks ONLY to the harness/chat-preferences endpoints. It never
+ * calls `/api/providers*` — provider identity lives inside the harness catalog.
+ */
+import { asHarnessCatalog, asHarnessSelection, asHarnessSummaries } from './runtime-guards';
+import type { HarnessCatalog, HarnessSelection, HarnessSummary } from '@/lib/types';
+
+/** A catalog fetch either yields the typed catalog or a typed unavailability —
+ * never a thrown raw body. */
+export type CatalogResult =
+  | { ok: true; catalog: HarnessCatalog }
+  | { ok: false; code: 'catalog_unavailable'; harnessId: string; message: string };
+
+export type SelectionErrorCode = 'selection_invalid' | 'model_unavailable';
+
+/** A persist either confirms the stored tuple or reports a typed domain failure
+ * that echoes back the exact tuple the caller requested. */
+export type SelectionPersistResult =
+  | { ok: true; selection: HarnessSelection }
+  | { ok: false; code: SelectionErrorCode; message: string; requested: HarnessSelection };
+
+/** A safe, generic message for an unavailable catalog — the raw 404 body is
+ * never surfaced. */
+const CATALOG_UNAVAILABLE_MESSAGE = 'This harness catalog is currently unavailable.';
+
+/** A safe, generic message for a rejected selection. The untrusted 422 body's
+ * own `message` is deliberately NEVER surfaced — only this fixed copy — so a
+ * raw gateway detail can never leak into the UI. Only the closed `code` enum is
+ * read from the body. */
+const SELECTION_REJECTED_MESSAGE = 'This selection was rejected.';
+
+async function readJson(response: Response): Promise<unknown> {
+  return response.json().catch(() => null);
+}
+
+function safeSelectionCode(body: unknown): SelectionErrorCode {
+  if (typeof body === 'object' && body !== null && 'code' in body) {
+    const code = (body as { code: unknown }).code;
+    if (code === 'selection_invalid' || code === 'model_unavailable') return code;
+  }
+  // Default to the more conservative "invalid" classification for anything
+  // unrecognized rather than guessing "model_unavailable".
+  return 'selection_invalid';
+}
+
+/** `GET /api/harnesses` → the list of harness summaries. A non-OK response
+ * normalizes to an empty list (the UI then has no harness to select). */
+export async function fetchHarnesses(): Promise<HarnessSummary[]> {
+  const response = await fetch('/api/harnesses', {
+    credentials: 'include',
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) return [];
+  return asHarnessSummaries(await readJson(response));
+}
+
+/** `GET /api/harnesses/:harnessId/catalog` → the harness-scoped catalog. A 404
+ * (or any non-OK) becomes a typed `catalog_unavailable` result rather than a
+ * fallback catalog or a rendered raw body. */
+export async function fetchCatalog(harnessId: string): Promise<CatalogResult> {
+  const response = await fetch(`/api/harnesses/${encodeURIComponent(harnessId)}/catalog`, {
+    credentials: 'include',
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) {
+    return {
+      ok: false,
+      code: 'catalog_unavailable',
+      // Scoped to the requested harness id, never the untrusted body's echo.
+      harnessId,
+      message: CATALOG_UNAVAILABLE_MESSAGE,
+    };
+  }
+  return { ok: true, catalog: asHarnessCatalog(await readJson(response), harnessId) };
+}
+
+/** `GET /api/chat/preferences/selection` → the persisted tuple, or null when
+ * unset or malformed. */
+export async function fetchPersistedSelection(): Promise<HarnessSelection | null> {
+  const response = await fetch('/api/chat/preferences/selection', {
+    credentials: 'include',
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) return null;
+  const body = await readJson(response);
+  if (typeof body !== 'object' || body === null) return null;
+  return asHarnessSelection((body as { selection?: unknown }).selection);
+}
+
+/** `PUT /api/chat/preferences/selection` with the structured tuple as the body.
+ * On success returns the confirmed selection; on a typed domain failure (422)
+ * or validation error, returns a typed result carrying the EXACT requested
+ * tuple — never the body's echo — and never the raw body text. */
+export async function persistSelection(
+  selection: HarnessSelection,
+): Promise<SelectionPersistResult> {
+  const requested: HarnessSelection = {
+    harnessId: selection.harnessId,
+    providerId: selection.providerId,
+    modelId: selection.modelId,
+  };
+  const response = await fetch('/api/chat/preferences/selection', {
+    method: 'PUT',
+    credentials: 'include',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(requested),
+  });
+  if (!response.ok) {
+    const body = await readJson(response);
+    return {
+      ok: false,
+      code: safeSelectionCode(body),
+      // Fixed copy only — the untrusted body's message is never surfaced.
+      message: SELECTION_REJECTED_MESSAGE,
+      requested,
+    };
+  }
+  const body = await readJson(response);
+  const confirmed =
+    typeof body === 'object' && body !== null
+      ? asHarnessSelection((body as { selection?: unknown }).selection)
+      : null;
+  // A malformed 2xx body is treated as a confirmation of exactly what we sent —
+  // the server accepted the tuple, so the requested tuple is the source of truth.
+  return { ok: true, selection: confirmed ?? requested };
+}

apps/web/src/spa/chat/composer.tsx

@@ -1,7 +1,9 @@
 import { useState, type KeyboardEvent, type ReactElement } from 'react';
+import type { HarnessSelection } from '@/lib/types';
+import type { HarnessSelectionValue } from './use-harness-selection';
 
 interface ComposerProps {
-  onSend: (input: { content: string; provider?: string; modelId?: string }) => void;
+  onSend: (input: { content: string; selection: HarnessSelection }) => boolean;
   onStop: () => void;
   streaming: boolean;
   /** True from local send time through server turn startup/ack and
@@ -9,6 +11,23 @@ interface ComposerProps {
    * pre-ack window where a second send could otherwise slip through. */
   sending: boolean;
   hasConversation: boolean;
+  /** Structured harness/provider/model selection state. The composer never
+   * accepts free-text provider/model — every sendable tuple is a validated,
+   * persisted catalog entry, and the send projection is derived from it. */
+  harness: HarnessSelectionValue;
+}
+
+/** The distinct provider ids present in the current catalog, in first-seen
+ * order — the provider select is catalog-derived, never a hardcoded list. */
+function providerOptions(harness: HarnessSelectionValue): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const model of harness.catalog?.models ?? []) {
+    if (seen.has(model.providerId)) continue;
+    seen.add(model.providerId);
+    out.push(model.providerId);
+  }
+  return out;
 }
 
 export function Composer({
@@ -17,22 +36,26 @@ export function Composer({
   streaming,
   sending,
   hasConversation,
+  harness,
 }: ComposerProps): ReactElement {
   const [content, setContent] = useState('');
-  const [provider, setProvider] = useState('');
-  const [modelId, setModelId] = useState('');
   const busy = streaming || sending;
 
   function submit(): void {
     if (busy) return;
+    // Send is gated on a validated, persisted catalog tuple — a draft or unset
+    // selection can never emit, so provider/model never travel as free text.
+    if (!harness.canSend || harness.persistedSelection === null) return;
     const trimmed = content.trim();
     if (!trimmed) return;
-    onSend({
-      content: trimmed,
-      provider: provider.trim() || undefined,
-      modelId: modelId.trim() || undefined,
-    });
-    setContent('');
+    // Pass the validated, persisted selection tuple only. The hook derives the
+    // wire projection (legacy `message` provider/model, or `turn:send`) from the
+    // negotiated `chat:send-capability` protocol — never from flat caller input.
+    const selection = harness.persistedSelection;
+    const ok = onSend({ content: trimmed, selection });
+    // Clear the input only when the send was accepted — a refused turn (e.g. a
+    // failed idempotency mint) must retain the user's text so it is not lost.
+    if (ok) setContent('');
   }
 
   function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>): void {
@@ -42,6 +65,19 @@ export function Composer({
     }
   }
 
+  // Scope the model options to the intentionally selected provider. With no
+  // provider chosen (`providerId === ''`) nothing matches, so the model select
+  // offers only the placeholder — never a cross-provider row.
+  const models = (harness.catalog?.models ?? []).filter(
+    (model) => model.providerId === harness.providerId,
+  );
+  // A collision-safe composite option identity covering the full provider+model
+  // tuple. The controlled select mirrors the same identity so the exact catalog
+  // row highlights (a bare modelId would collide across providers).
+  const modelOptionValue = (model: { providerId: string; modelId: string }): string =>
+    `${model.providerId}:${model.modelId}`;
+  const selectedModelValue = harness.modelId ? `${harness.providerId}:${harness.modelId}` : '';
+
   return (
     <form
       onSubmit={(event) => {
@@ -51,21 +87,68 @@ export function Composer({
       className="flex flex-col gap-2 border-t p-4"
     >
       <div className="flex flex-wrap gap-2">
-        <input
+        <select
+          aria-label="Harness"
+          value={harness.harnessId}
+          onChange={(event) => harness.selectHarness(event.target.value)}
+          className="rounded border px-2 py-1 text-xs"
+        >
+          <option value="">Select a harness…</option>
+          {harness.harnesses.map((item) => (
+            <option key={item.id} value={item.id}>
+              {item.displayName}
+            </option>
+          ))}
+        </select>
+        <select
           aria-label="Provider"
-          value={provider}
-          onChange={(event) => setProvider(event.target.value)}
-          placeholder="Provider (optional)"
+          value={harness.providerId}
+          onChange={(event) => harness.selectProvider(event.target.value)}
+          disabled={harness.catalogUnavailable || providerOptions(harness).length === 0}
           className="rounded border px-2 py-1 text-xs"
-        />
-        <input
+        >
+          <option value="">Select a provider…</option>
+          {providerOptions(harness).map((providerId) => (
+            <option key={providerId} value={providerId}>
+              {providerId}
+            </option>
+          ))}
+        </select>
+        <select
           aria-label="Model"
-          value={modelId}
-          onChange={(event) => setModelId(event.target.value)}
-          placeholder="Model (optional)"
+          value={selectedModelValue}
+          onChange={(event) => {
+            // Resolve the composite option identity back to the exact catalog
+            // row and persist that row's own provider+model — never a bare id.
+            const selected = models.find((model) => modelOptionValue(model) === event.target.value);
+            if (selected) harness.selectModel(selected.providerId, selected.modelId);
+          }}
+          disabled={harness.catalogUnavailable || models.length === 0}
           className="rounded border px-2 py-1 text-xs"
-        />
+        >
+          <option value="">Select a model…</option>
+          {models.map((model) => (
+            <option key={modelOptionValue(model)} value={modelOptionValue(model)}>
+              {model.displayName}
+            </option>
+          ))}
+        </select>
       </div>
+      {harness.catalogUnavailable ? (
+        <p role="status" className="text-xs opacity-70">
+          This harness catalog is currently unavailable.
+        </p>
+      ) : null}
+      {harness.isStale ? (
+        <p role="status" className="text-xs opacity-70">
+          The saved model is no longer available — pick another to continue.
+        </p>
+      ) : null}
+      {harness.persistError ? (
+        <p role="alert" className="text-xs">
+          {harness.persistError.message}
+        </p>
+      ) : null}
       <div className="flex items-end gap-2">
         <textarea
           aria-label="Message"
@@ -78,7 +161,7 @@ export function Composer({
         />
         <button
           type="submit"
-          disabled={!content.trim() || busy}
+          disabled={!content.trim() || busy || !harness.canSend}
           className="rounded px-3 py-2 text-sm font-medium"
         >
           Send

apps/web/src/spa/chat/runtime-guards.ts

@@ -5,6 +5,14 @@
  * a non-array, `.toFixed` on a non-number) or render an object as a React
  * child.
  */
+import type {
+  HarnessAuthState,
+  HarnessCatalog,
+  HarnessCatalogEntry,
+  HarnessModelAvailability,
+  HarnessSelection,
+  HarnessSummary,
+} from '@/lib/types';
 
 export function asString(value: unknown, fallback = ''): string {
   return typeof value === 'string' ? value : fallback;
@@ -38,6 +46,99 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
+/**
+ * The HTTP harness/catalog/selection JSON bodies are as untrusted as the socket
+ * payloads above — a misbehaving or compromised gateway can send anything. The
+ * guards below normalize those bodies into the typed client shapes without ever
+ * rendering a raw body, so a 404/422/malformed response can never inject an
+ * object into React or a non-tuple into the selection state.
+ */
+
+/** Normalizes an untrusted `authState` to the closed set, defaulting to the
+ * safest value (`unavailable`) for anything unrecognized. */
+export function asHarnessAuthState(value: unknown): HarnessAuthState {
+  return value === 'ready' || value === 'auth_required' || value === 'unavailable'
+    ? value
+    : 'unavailable';
+}
+
+/** Normalizes an untrusted `availability` to the closed set, defaulting to
+ * `unavailable` so a malformed row can never present as sendable. */
+export function asHarnessAvailability(value: unknown): HarnessModelAvailability {
+  return value === 'available' ? 'available' : 'unavailable';
+}
+
+/** A tuple is valid only when all three ids are non-empty strings — a partial
+ * or malformed selection is rejected (null) rather than half-adopted. */
+export function asHarnessSelection(value: unknown): HarnessSelection | null {
+  if (!isRecord(value)) return null;
+  const harnessId = value.harnessId;
+  const providerId = value.providerId;
+  const modelId = value.modelId;
+  if (
+    typeof harnessId !== 'string' ||
+    typeof providerId !== 'string' ||
+    typeof modelId !== 'string' ||
+    harnessId.length === 0 ||
+    providerId.length === 0 ||
+    modelId.length === 0
+  ) {
+    return null;
+  }
+  return { harnessId, providerId, modelId };
+}
+
+/** Normalizes an untrusted array into typed harness summaries, dropping any row
+ * without a usable id. */
+export function asHarnessSummaries(value: unknown): HarnessSummary[] {
+  if (!Array.isArray(value)) return [];
+  const out: HarnessSummary[] = [];
+  for (const item of value) {
+    if (!isRecord(item)) continue;
+    const id = asString(item.id);
+    if (id.length === 0) continue;
+    out.push({
+      id,
+      displayName: asNonEmptyString(item.displayName, id),
+      capabilities: asStringArray(item.capabilities),
+    });
+  }
+  return out;
+}
+
+function asHarnessCatalogEntry(value: unknown): HarnessCatalogEntry | null {
+  const selection = asHarnessSelection(value);
+  if (selection === null || !isRecord(value)) return null;
+  return {
+    ...selection,
+    displayName: asNonEmptyString(value.displayName, selection.modelId),
+    reasoningCapability: value.reasoningCapability === true,
+    inputTypes: asStringArray(value.inputTypes),
+    authState: asHarnessAuthState(value.authState),
+    availability: asHarnessAvailability(value.availability),
+  };
+}
+
+/** Normalizes an untrusted catalog body into the typed client catalog. The
+ * caller supplies `harnessId` (from the request path) so the returned catalog
+ * is scoped to the harness that was actually requested, never a body-echoed id.
+ * Malformed model rows are dropped rather than invalidating the whole catalog. */
+export function asHarnessCatalog(value: unknown, harnessId: string): HarnessCatalog {
+  const record = isRecord(value) ? value : {};
+  const rawModels = Array.isArray(record.models) ? record.models : [];
+  const models: HarnessCatalogEntry[] = [];
+  for (const row of rawModels) {
+    const entry = asHarnessCatalogEntry(row);
+    if (entry !== null) models.push(entry);
+  }
+  return {
+    harnessId,
+    version: asString(record.version),
+    fingerprint: asString(record.fingerprint),
+    models,
+  };
+}
+
 /** The single point of truth for what counts as a valid conversation ID
  * anywhere a scoped server event may adopt one into state — a non-empty
  * string, nothing else. Every site that establishes or compares

apps/web/src/spa/chat/test-support/fake-chat-socket.ts

@@ -14,6 +14,10 @@ export interface EmittedEvent<K extends ClientEvent = ClientEvent> {
 /** The subset of a Socket.IO `ChatSocket` that `useChatConnection` drives. */
 export interface FakeChatSocket {
   connected: boolean;
+  /** Mirrors socket.io-client's `Socket.id`: the connection identity the server
+   * echoes in a `chat:send-capability` payload. The generation-bound send
+   * protocol accepts an advertisement only when `payload.connectionId === id`. */
+  id: string;
   connect(): FakeChatSocket;
   on<K extends ServerEvent>(event: K, handler: ServerHandler<K>): FakeChatSocket;
   off<K extends ServerEvent>(event: K, handler: ServerHandler<K>): FakeChatSocket;
@@ -51,8 +55,10 @@ export function createFakeChatSocket(): {
   /** Simulates socket.io-client's automatic reconnect of the *same*
    * instance after a transient disconnect: marks the socket connected again
    * and fires any handler(s) registered via `socket.on('connect', ...)`,
-   * without clearing or replacing any listeners. */
-  simulateReconnect(): void;
+   * without clearing or replacing any listeners. A real reconnect is assigned
+   * a fresh `Socket.id`; pass `nextId` to model that new connection identity
+   * (defaults to the current id so existing callers are unaffected). */
+  simulateReconnect(nextId?: string): void;
 } {
   const listeners = new Map<ServerEvent, Set<(payload: never) => void>>();
   const emitted: EmittedEvent[] = [];
@@ -63,6 +69,7 @@ export function createFakeChatSocket(): {
   // type-checked against ServerToClientEvents/ClientToServerEvents.
   const socket = {
     connected: false,
+    id: 'socket-a',
     connect: vi.fn(function connect(this: void) {
       socket.connected = true;
       return socket;
@@ -105,8 +112,9 @@ export function createFakeChatSocket(): {
     }
   }
 
-  function simulateReconnect(): void {
+  function simulateReconnect(nextId: string = socket.id): void {
     socket.connected = true;
+    socket.id = nextId;
     const lifecycleKey = 'connect' satisfies LifecycleEvent as unknown as ServerEvent;
     for (const handler of listeners.get(lifecycleKey) ?? []) {
       (handler as () => void)();

apps/web/src/spa/chat/use-chat-connection.spec.tsx

@@ -21,6 +21,7 @@ vi.mock('@/lib/socket', () => ({
   destroySocket: destroySocketMock,
 }));
 
+import type { ChatSendProtocol, HarnessSelection } from '@mosaicstack/types';
 import { useChatConnection, type ChatConnectionValue } from './use-chat-connection';
 
 let fake: ReturnType<typeof createFakeChatSocket>;
@@ -33,6 +34,126 @@ function Harness(): null {
   return null;
 }
 
+/**
+ * Task Five, Step Two (web send path) red-first support. These probe the FUTURE
+ * pi-rpc send contract against the CURRENT implementation, so the desired API is
+ * expressed here as a localized cast — production types stay untouched until Step
+ * Three. The reds fail on behaviour (legacy `message` emitted instead of
+ * `turn:send`; no nested selection; no idempotency key; void return; no
+ * conversation-id gating), never on a missing module or type.
+ */
+interface HarnessTurnSendInput {
+  readonly content: string;
+  readonly selection: HarnessSelection;
+}
+type HarnessSendMessage = (input: HarnessTurnSendInput) => boolean;
+
+function harnessSend(): HarnessSendMessage {
+  return latest?.actions.sendMessage as unknown as HarnessSendMessage;
+}
+
+/**
+ * Task Five MAJOR-1 (browser send-protocol negotiation) support. The Gateway
+ * advertises how this connection may send via a server-to-client-only
+ * `chat:send-capability` (already part of the typed `ServerToClientEvents`
+ * contract, so this uses the fake's typed `serverEmit` — no cast); the hook
+ * holds the advertised protocol and routes `sendMessage` through an exhaustive
+ * switch on it, never inferring it from conversation/selection. When no listener
+ * is registered yet (CURRENT impl), the emit is an inert no-op, so the reds
+ * below fail on BEHAVIOUR — the current send path still infers a protocol and
+ * emits regardless of any advertisement — not on a missing module or type.
+ */
+function advertiseCapability(protocol: ChatSendProtocol, connectionId: string): void {
+  fake.serverEmit('chat:send-capability', { protocol, connectionId });
+}
+
+/**
+ * Install a controllable `crypto.randomUUID` on the global crypto object and
+ * return a restore fn. Uses defineProperty on the instance so it works whether
+ * or not the native method is configurable (it lives on the prototype, so an own
+ * property simply shadows it).
+ */
+function installRandomUUID(fn: () => string): () => void {
+  const g = globalThis as { crypto?: { randomUUID?: () => string } };
+  if (!g.crypto) {
+    Object.defineProperty(g, 'crypto', { configurable: true, writable: true, value: {} });
+  }
+  const cryptoObj = g.crypto as { randomUUID?: () => string };
+  const original = Object.getOwnPropertyDescriptor(cryptoObj, 'randomUUID');
+  Object.defineProperty(cryptoObj, 'randomUUID', {
+    configurable: true,
+    writable: true,
+    value: fn,
+  });
+  return () => {
+    if (original) {
+      Object.defineProperty(cryptoObj, 'randomUUID', original);
+    } else {
+      Reflect.deleteProperty(cryptoObj, 'randomUUID');
+    }
+  };
+}
+
+/**
+ * Force `crypto.randomUUID` to read as ABSENT by shadowing it with an own
+ * `undefined` property. The native method lives on `Crypto.prototype`, so a
+ * bare delete of the (non-existent) own property would leave the inherited
+ * method visible — the shadow is what actually makes the call site see no
+ * secure generator. Returns a restore fn.
+ */
+function removeRandomUUID(): () => void {
+  const g = globalThis as { crypto?: { randomUUID?: () => string } };
+  if (!g.crypto) {
+    Object.defineProperty(g, 'crypto', { configurable: true, writable: true, value: {} });
+  }
+  const cryptoObj = g.crypto as { randomUUID?: () => string };
+  const original = Object.getOwnPropertyDescriptor(cryptoObj, 'randomUUID');
+  Object.defineProperty(cryptoObj, 'randomUUID', {
+    configurable: true,
+    writable: true,
+    value: undefined,
+  });
+  return () => {
+    if (original) {
+      Object.defineProperty(cryptoObj, 'randomUUID', original);
+    } else {
+      Reflect.deleteProperty(cryptoObj, 'randomUUID');
+    }
+  };
+}
+
+/**
+ * Task Five, Step Two group 4/5 support — the FUTURE `turn:ack` receipt surface
+ * and the FUTURE fixed idempotency/rejection notice, expressed as a localized
+ * read-only view over `state`. Production `ChatConnectionState` gains
+ * `turnReceipt` at Step Three; the cast keeps production types untouched until
+ * then, so a success assertion against it fails on BEHAVIOUR (no turn:ack
+ * handler runs), never on a missing module. `error` already exists on state.
+ */
+interface HarnessTurnReceiptView {
+  readonly idempotencyKey: string;
+  readonly receiptId: string;
+  readonly selection: HarnessSelection;
+}
+interface HarnessTurnStateView {
+  readonly turnReceipt: HarnessTurnReceiptView | null | undefined;
+  readonly error: string | null;
+}
+function harnessTurnState(): HarnessTurnStateView {
+  return latest?.state as unknown as HarnessTurnStateView;
+}
+
+/**
+ * Emit a server `turn:ack` the CURRENT hook has no listener for — a safe no-op
+ * today (the fake iterates an empty handler set), so the group-4 reds fail
+ * because nothing is surfaced, not because this throws. The event name is cast
+ * past the compile-time `ServerToClientEvents` contract exactly as the
+ * `turn:send` client cast is; the typed event map lands at Step Three.
+ */
+function serverEmitTurnAck(payload: unknown): void {
+  fake.serverEmitRaw('turn:ack' as unknown as Parameters<typeof fake.serverEmitRaw>[0], payload);
+}
+
 beforeAll(() => {
   Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
     configurable: true,
@@ -67,6 +188,20 @@ afterEach(async () => {
 });
 
 describe('useChatConnection', () => {
+  // Task Five MAJOR-1: the send path is PROTOCOL-driven — `sendMessage` routes
+  // only on the negotiated `chat:send-capability`, never on inferred
+  // conversation/selection state. These pre-existing cases exercise the legacy
+  // `message` branch, so the connection is advertised `legacy-message` once here
+  // (server-to-client, for this exact socket id) after the mount registers its
+  // listener. Sub-describes that need the pi turn-runtime reset the generation
+  // and re-advertise `turn-send`; the capability describe resets to the
+  // unadvertised `unavailable` baseline and drives the protocol itself.
+  beforeEach(async () => {
+    await act(async () => {
+      advertiseCapability('legacy-message', fake.socket.id);
+    });
+  });
+
   it('establishes the active conversation from the first message:ack when message omitted conversationId', async () => {
     await act(async () => {
       fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
@@ -344,7 +479,10 @@ describe('useChatConnection', () => {
 
   it('sendMessage emits optional conversationId/provider/modelId and appends an optimistic user turn', async () => {
     await act(async () => {
-      latest?.actions.sendMessage({ content: 'hello', provider: 'anthropic', modelId: 'claude' });
+      latest?.actions.sendMessage({
+        content: 'hello',
+        selection: { harnessId: 'pi', providerId: 'anthropic', modelId: 'claude' },
+      });
     });
 
     expect(fake.emitted).toContainEqual({
@@ -373,6 +511,408 @@ describe('useChatConnection', () => {
     });
   });
 
+  describe('turn:send harness routing (Task Five, Step Two red-first)', () => {
+    const selection: HarnessSelection = {
+      harnessId: 'pi',
+      providerId: 'anthropic',
+      modelId: 'claude',
+    };
+    const UUID = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+
+    // The pi turn-runtime routes sends through `turn:send`. Reset the generation
+    // (clearing the outer `legacy-message` advertisement + first-wins lock) and
+    // advertise `turn-send` for this exact connection, so every send below takes
+    // the turn-runtime branch.
+    beforeEach(async () => {
+      await act(async () => {
+        fake.simulateReconnect();
+      });
+      await act(async () => {
+        advertiseCapability('turn-send', fake.socket.id);
+      });
+    });
+
+    async function establishConversation(): Promise<void> {
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+    }
+
+    it('emits a single turn:send with the nested selection tuple and a UUID idempotencyKey — never the legacy message event', async () => {
+      const restore = installRandomUUID(() => UUID);
+      try {
+        await establishConversation();
+        await act(async () => {
+          harnessSend()({ content: 'hello', selection });
+        });
+      } finally {
+        restore();
+      }
+
+      const sends = fake.emitted.filter((e) => e.event === 'turn:send');
+      expect(sends).toHaveLength(1);
+      expect(sends[0]?.payload).toEqual({
+        conversationId: 'c1',
+        content: 'hello',
+        selection,
+        idempotencyKey: UUID,
+      });
+      // The pi-rpc sender must not fall back to the embedded `message` event.
+      expect(fake.emitted.some((e) => e.event === 'message')).toBe(false);
+    });
+
+    it('generates the idempotencyKey with exactly one crypto.randomUUID() call per accepted send', async () => {
+      const gen = vi.fn(() => UUID);
+      const restore = installRandomUUID(gen);
+      try {
+        await establishConversation();
+        await act(async () => {
+          harnessSend()({ content: 'first', selection });
+        });
+        await act(async () => {
+          harnessSend()({ content: 'second', selection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(gen).toHaveBeenCalledTimes(2);
+      const keys = fake.emitted
+        .filter((e) => e.event === 'turn:send')
+        .map((e) => (e.payload as { idempotencyKey: string }).idempotencyKey);
+      expect(keys).toEqual([UUID, UUID]);
+    });
+
+    it('does not send before an active conversation id exists (no first-send auto-create)', async () => {
+      const restore = installRandomUUID(() => UUID);
+      let returned: boolean | undefined;
+      try {
+        await act(async () => {
+          returned = harnessSend()({ content: 'too early', selection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(returned).toBe(false);
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(false);
+      expect(fake.emitted.some((e) => e.event === 'message')).toBe(false);
+      // Nothing optimistically appended when the send is refused.
+      expect(latest?.state.messages.some((m) => m.text === 'too early')).toBe(false);
+    });
+
+    it('returns true when it emits and false when the send is refused', async () => {
+      const restore = installRandomUUID(() => UUID);
+      let refusedEarly: boolean | undefined;
+      let acceptedAfter: boolean | undefined;
+      try {
+        await act(async () => {
+          refusedEarly = harnessSend()({ content: 'early', selection });
+        });
+        await establishConversation();
+        await act(async () => {
+          acceptedAfter = harnessSend()({ content: 'now', selection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(refusedEarly).toBe(false);
+      expect(acceptedAfter).toBe(true);
+    });
+
+    it('when secure UUID generation throws: emits nothing, appends nothing, releases the lock, and a later send succeeds', async () => {
+      await establishConversation();
+
+      const failing = installRandomUUID(() => {
+        throw new Error('secure random unavailable');
+      });
+      let firstReturn: boolean | undefined;
+      try {
+        await act(async () => {
+          firstReturn = harnessSend()({ content: 'blocked', selection });
+        });
+      } finally {
+        failing();
+      }
+
+      expect(firstReturn).toBe(false);
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(false);
+      expect(latest?.state.messages.some((m) => m.text === 'blocked')).toBe(false);
+
+      // The send lock must have been released, so a subsequent valid send works.
+      const restore = installRandomUUID(() => UUID);
+      let secondReturn: boolean | undefined;
+      try {
+        await act(async () => {
+          secondReturn = harnessSend()({ content: 'retry', selection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(secondReturn).toBe(true);
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(true);
+    });
+  });
+
+  describe('turn:ack receipt + rejection contract (Task Five, Step Two group 4)', () => {
+    const selection: HarnessSelection = {
+      harnessId: 'pi',
+      providerId: 'anthropic',
+      modelId: 'claude',
+    };
+    const UUID = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+
+    // turn:ack is the receipt for a `turn:send`, so these establish under the pi
+    // turn-runtime: reset the generation (clearing the outer `legacy-message`
+    // advertisement + lock) and advertise `turn-send` for this connection.
+    beforeEach(async () => {
+      await act(async () => {
+        fake.simulateReconnect();
+      });
+      await act(async () => {
+        advertiseCapability('turn-send', fake.socket.id);
+      });
+    });
+
+    // Establish the conversation and send one accepted turn under a controlled
+    // idempotency key. Returns the crypto restore fn so callers unwind it.
+    async function establishAndSend(): Promise<() => void> {
+      const restore = installRandomUUID(() => UUID);
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+      await act(async () => {
+        harnessSend()({ content: 'hello', selection });
+      });
+      return restore;
+    }
+
+    it('surfaces a turn:ack receipt echoing the exact idempotencyKey, server receiptId, and requested selection tuple', async () => {
+      const restore = await establishAndSend();
+      try {
+        await act(async () => {
+          serverEmitTurnAck({
+            conversationId: 'c1',
+            idempotencyKey: UUID,
+            receiptId: 'r1',
+            selection,
+          });
+        });
+      } finally {
+        restore();
+      }
+
+      // RED anchor: no turn:ack handler exists, so nothing is recorded. Green
+      // only when Step Three echoes the exact tuple back into state — never a
+      // substituted or fabricated one.
+      expect(harnessTurnState().turnReceipt).toEqual({
+        idempotencyKey: UUID,
+        receiptId: 'r1',
+        selection,
+      });
+    });
+
+    it('on a rejected turn:ack surfaces a visible safe notice, never the raw internal error, and fabricates no receipt tuple', async () => {
+      const restore = await establishAndSend();
+      try {
+        await act(async () => {
+          serverEmitTurnAck({
+            conversationId: 'c1',
+            idempotencyKey: UUID,
+            ok: false,
+            code: 'runtime_unsupported',
+            error: 'ADAPTER_BOOM internal stack: pi adapter unavailable at 0xdeadbeef',
+          });
+        });
+      } finally {
+        restore();
+      }
+
+      // RED anchor: a rejected ack must surface a visible notice; today no
+      // handler runs, so state.error stays null.
+      expect(harnessTurnState().error).toBeTruthy();
+      // The raw internal exception text must never reach the browser surface.
+      expect(harnessTurnState().error ?? '').not.toContain('ADAPTER_BOOM');
+      expect(harnessTurnState().error ?? '').not.toContain('0xdeadbeef');
+      // A rejection must not fabricate a success receipt tuple.
+      expect(harnessTurnState().turnReceipt ?? null).toBeNull();
+    });
+
+    it('uses one fixed safe rejection notice regardless of the internal cause (frozen union, not a passthrough)', async () => {
+      const firstRestore = await establishAndSend();
+      try {
+        await act(async () => {
+          serverEmitTurnAck({
+            conversationId: 'c1',
+            idempotencyKey: UUID,
+            ok: false,
+            code: 'runtime_unsupported',
+            error: 'cause-ALPHA adapter_unavailable',
+          });
+        });
+      } finally {
+        firstRestore();
+      }
+      const firstNotice = harnessTurnState().error;
+
+      // A fresh turn on the same conversation, rejected for a DIFFERENT internal
+      // reason, must surface the identical fixed notice.
+      const secondRestore = installRandomUUID(() => UUID);
+      try {
+        await act(async () => {
+          harnessSend()({ content: 'again', selection });
+        });
+        await act(async () => {
+          serverEmitTurnAck({
+            conversationId: 'c1',
+            idempotencyKey: UUID,
+            ok: false,
+            code: 'runtime_unsupported',
+            error: 'cause-BRAVO conversation_service_unavailable',
+          });
+        });
+      } finally {
+        secondRestore();
+      }
+      const secondNotice = harnessTurnState().error;
+
+      // RED anchor: both are null today; green requires a single frozen safe
+      // string surfaced for both distinct internal causes.
+      expect(firstNotice).toBeTruthy();
+      expect(secondNotice).toBeTruthy();
+      expect(firstNotice).toBe(secondNotice);
+      expect(firstNotice ?? '').not.toContain('ALPHA');
+      expect(secondNotice ?? '').not.toContain('BRAVO');
+    });
+  });
+
+  describe('idempotency-key failure semantics (Task Five, Step Two group 5)', () => {
+    const selection: HarnessSelection = {
+      harnessId: 'pi',
+      providerId: 'anthropic',
+      modelId: 'claude',
+    };
+    const UUID_A = '11111111-1111-4111-8111-111111111111';
+    const UUID_B = '22222222-2222-4222-9222-222222222222';
+    const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+    // The idempotency key is minted only on the pi turn-runtime `turn:send`
+    // branch: reset the generation (clearing the outer `legacy-message`
+    // advertisement + lock) and advertise `turn-send` for this connection.
+    beforeEach(async () => {
+      await act(async () => {
+        fake.simulateReconnect();
+      });
+      await act(async () => {
+        advertiseCapability('turn-send', fake.socket.id);
+      });
+    });
+
+    async function establish(): Promise<void> {
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+    }
+
+    it('mints a DISTINCT UUID-v4 idempotencyKey for each of two accepted turns — a key is never reused across turns', async () => {
+      const keys = [UUID_A, UUID_B];
+      let call = 0;
+      const restore = installRandomUUID(() => keys[call++] ?? UUID_A);
+      try {
+        await establish();
+        await act(async () => {
+          harnessSend()({ content: 'first', selection });
+        });
+        await act(async () => {
+          harnessSend()({ content: 'second', selection });
+        });
+      } finally {
+        restore();
+      }
+
+      const sent = fake.emitted
+        .filter((e) => e.event === 'turn:send')
+        .map((e) => (e.payload as { idempotencyKey: string }).idempotencyKey);
+      // RED anchor: current sendMessage emits the legacy `message`, so no
+      // turn:send keys exist at all.
+      expect(sent).toHaveLength(2);
+      expect(sent[0]).toMatch(UUID_V4);
+      expect(sent[1]).toMatch(UUID_V4);
+      expect(sent[0]).not.toBe(sent[1]);
+    });
+
+    it('when crypto.randomUUID is ABSENT: surfaces a visible fixed idempotency-unavailable notice, emits nothing, appends nothing, releases the lock synchronously, and a later valid send succeeds', async () => {
+      await establish();
+
+      const restoreCrypto = removeRandomUUID();
+      let firstReturn: boolean | undefined;
+      try {
+        await act(async () => {
+          firstReturn = harnessSend()({ content: 'no-secure-random', selection });
+        });
+      } finally {
+        restoreCrypto();
+      }
+
+      // RED anchors: a refused send returns false and surfaces a visible notice.
+      expect(firstReturn).toBe(false);
+      expect(harnessTurnState().error).toBeTruthy();
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(false);
+      expect(latest?.state.messages.some((m) => m.text === 'no-secure-random')).toBe(false);
+
+      // The lock released synchronously (no server event needed): a later valid
+      // send goes through.
+      const restore = installRandomUUID(() => UUID_A);
+      let secondReturn: boolean | undefined;
+      try {
+        await act(async () => {
+          secondReturn = harnessSend()({ content: 'recovered', selection });
+        });
+      } finally {
+        restore();
+      }
+      expect(secondReturn).toBe(true);
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(true);
+    });
+
+    it('surfaces the SAME fixed idempotency-unavailable notice whether randomUUID is absent or throws, never leaking the thrown message', async () => {
+      // Case 1: absent.
+      await establish();
+      const restoreAbsent = removeRandomUUID();
+      try {
+        await act(async () => {
+          harnessSend()({ content: 'absent', selection });
+        });
+      } finally {
+        restoreAbsent();
+      }
+      const absentNotice = harnessTurnState().error;
+
+      // Case 2: throws with a distinctive internal message.
+      const failing = installRandomUUID(() => {
+        throw new Error('SECURE_RANDOM_BOOM entropy pool drained');
+      });
+      try {
+        await act(async () => {
+          harnessSend()({ content: 'throws', selection });
+        });
+      } finally {
+        failing();
+      }
+      const throwNotice = harnessTurnState().error;
+
+      // RED anchor: both are null today.
+      expect(absentNotice).toBeTruthy();
+      expect(throwNotice).toBeTruthy();
+      expect(absentNotice).toBe(throwNotice);
+      // The thrown internal detail must never reach the browser surface.
+      expect(throwNotice ?? '').not.toContain('SECURE_RANDOM_BOOM');
+      expect(throwNotice ?? '').not.toContain('entropy pool');
+    });
+  });
+
   it('abort emits abort with the active conversationId', async () => {
     await act(async () => {
       fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
@@ -684,7 +1224,16 @@ describe('useChatConnection', () => {
     expect(latest?.state.approvalRequestPending).toBe(false);
 
     // The send lock must also be released — a subsequent sendMessage after
-    // reconnect must not be permanently blocked by the interrupted turn.
+    // reconnect must not be permanently blocked by the interrupted turn. The
+    // disconnect also voids the negotiated send protocol (MAJOR-1), so model the
+    // reconnect handshake — the socket reconnects and the server re-advertises
+    // how this connection may send — before probing the released lock.
+    await act(async () => {
+      fake.simulateReconnect();
+    });
+    await act(async () => {
+      advertiseCapability('legacy-message', fake.socket.id);
+    });
     await act(async () => {
       latest?.actions.sendMessage({ content: 'after reconnect' });
     });
@@ -1665,4 +2214,319 @@ describe('useChatConnection', () => {
     }
     expect(destroySocketMock).toHaveBeenCalledOnce();
   });
+
+  describe('chat:send-capability protocol negotiation (Task Five MAJOR-1, red-first)', () => {
+    const capSelection: HarnessSelection = {
+      harnessId: 'pi',
+      providerId: 'anthropic',
+      modelId: 'claude',
+    };
+    const UUID = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
+    // The one fixed, safe user-facing notice the hook must surface (code
+    // `send_protocol_unavailable`) when a send is attempted on a connection whose
+    // advertised protocol is `unavailable`/unknown/absent. Contract-frozen string.
+    const UNAVAILABLE_NOTICE = 'Chat sending is unavailable on this connection.';
+
+    // These tests each drive the protocol negotiation themselves, so they must
+    // start from a clean, unadvertised generation. Reconnect resets protocolRef
+    // to `unavailable` and clears the outer `legacy-message` first-wins lock
+    // WITHOUT advertising — no client emit, so `fake.emitted` stays empty and the
+    // "starts unavailable" premise holds.
+    beforeEach(async () => {
+      await act(async () => {
+        fake.simulateReconnect();
+      });
+    });
+
+    async function establishConversation(): Promise<void> {
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+    }
+
+    function connectCalls(): number {
+      return (fake.socket.connect as unknown as { mock: { calls: unknown[] } }).mock.calls.length;
+    }
+
+    it('starts with no advertised protocol: a send is refused, emits nothing, mints no key, and surfaces the fixed unavailable notice', async () => {
+      // No `chat:send-capability` has arrived, so the connection has not been told
+      // it may send at all. The current impl infers "selection + no conversation +
+      // no flat provider/model → return false" but SURFACES NOTHING — the red is
+      // that the fixed `send_protocol_unavailable` notice is never set.
+      let uuidCalls = 0;
+      const restore = installRandomUUID(() => {
+        uuidCalls += 1;
+        return UUID;
+      });
+      let returned: boolean | undefined;
+      try {
+        await act(async () => {
+          returned = harnessSend()({ content: 'hi', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(returned).toBe(false);
+      expect(fake.emitted).toHaveLength(0);
+      expect(latest?.state.error).toBe(UNAVAILABLE_NOTICE);
+      // The test's name promises "mints no key": the unavailable branch must not
+      // reach the idempotency mint at all. Without this assertion a defect that
+      // mints a key before refusing survives.
+      expect(uuidCalls).toBe(0);
+      // ...and no user content may be optimistically appended on refusal.
+      expect(latest?.state.messages.some((m) => m.text === 'hi')).toBe(false);
+    });
+
+    it('legacy-message advertised overrides conversation-inference: an established conversation still routes the legacy message event, never turn:send', async () => {
+      // Same inputs the inference impl routes to `turn:send` (selection + active
+      // conversation). The advertised protocol is authoritative: it must emit the
+      // legacy `message` event instead. Red: current impl emits turn:send.
+      const restore = installRandomUUID(() => UUID);
+      try {
+        await establishConversation();
+        await act(async () => {
+          advertiseCapability('legacy-message', fake.socket.id);
+        });
+        await act(async () => {
+          harnessSend()({ content: 'hi', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(fake.emitted.filter((e) => e.event === 'turn:send')).toHaveLength(0);
+      expect(fake.emitted).toContainEqual({
+        event: 'message',
+        payload: { conversationId: 'c1', content: 'hi', provider: 'anthropic', modelId: 'claude' },
+      });
+    });
+
+    it('legacy-message advertised with no conversation: derives provider/model from the selection tuple and emits one message', async () => {
+      // The flat provider/modelId caller inputs are gone; the legacy branch must
+      // source them from the confirmed persisted selection. Red: current impl
+      // refuses a bare harness send (selection + no flat fields → return false).
+      let returned: boolean | undefined;
+      const restore = installRandomUUID(() => UUID);
+      try {
+        await act(async () => {
+          advertiseCapability('legacy-message', fake.socket.id);
+        });
+        await act(async () => {
+          returned = harnessSend()({ content: 'first', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(returned).toBe(true);
+      expect(fake.emitted).toContainEqual({
+        event: 'message',
+        payload: {
+          conversationId: undefined,
+          content: 'first',
+          provider: 'anthropic',
+          modelId: 'claude',
+        },
+      });
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(false);
+    });
+
+    it('unavailable advertised: refuses even with an active conversation and selection, emits nothing, surfaces the fixed notice', async () => {
+      // Red: current impl ignores the advertisement and emits turn:send.
+      let uuidCalls = 0;
+      const restore = installRandomUUID(() => {
+        uuidCalls += 1;
+        return UUID;
+      });
+      let returned: boolean | undefined;
+      try {
+        await establishConversation();
+        await act(async () => {
+          advertiseCapability('unavailable', fake.socket.id);
+        });
+        await act(async () => {
+          returned = harnessSend()({ content: 'nope', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(returned).toBe(false);
+      expect(fake.emitted).toHaveLength(0);
+      expect(latest?.state.error).toBe(UNAVAILABLE_NOTICE);
+      // Refusal must not optimistically append the user's turn to the transcript
+      // (a distinct leak from the emit): the unavailable branch appends nothing.
+      expect(latest?.state.messages.some((m) => m.text === 'nope')).toBe(false);
+      // ...and must not mint an idempotency key on the refused path.
+      expect(uuidCalls).toBe(0);
+    });
+
+    it('ignores an advertisement whose connectionId does not match the socket id: protocol stays unavailable and the send is refused', async () => {
+      // A capability minted for a different (stale/foreign) connection must never
+      // arm this one. Red: current impl has no connection-id gate and emits
+      // turn:send off the inferred path.
+      const restore = installRandomUUID(() => UUID);
+      let returned: boolean | undefined;
+      try {
+        await establishConversation();
+        await act(async () => {
+          advertiseCapability('legacy-message', 'a-different-connection');
+        });
+        await act(async () => {
+          returned = harnessSend()({ content: 'spoof', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(returned).toBe(false);
+      expect(fake.emitted).toHaveLength(0);
+      expect(latest?.state.error).toBe(UNAVAILABLE_NOTICE);
+    });
+
+    it('accepts only the first advertisement for the generation: a later conflicting protocol is ignored', async () => {
+      // legacy-message wins; the subsequent turn-send is a replay/conflict and is
+      // dropped. Red: current impl ignores both and infers turn:send.
+      const restore = installRandomUUID(() => UUID);
+      try {
+        await establishConversation();
+        await act(async () => {
+          advertiseCapability('legacy-message', fake.socket.id);
+        });
+        await act(async () => {
+          advertiseCapability('turn-send', fake.socket.id);
+        });
+        await act(async () => {
+          harnessSend()({ content: 'hi', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(fake.emitted.filter((e) => e.event === 'turn:send')).toHaveLength(0);
+      expect(fake.emitted).toContainEqual({
+        event: 'message',
+        payload: { conversationId: 'c1', content: 'hi', provider: 'anthropic', modelId: 'claude' },
+      });
+    });
+
+    it('resets to unavailable on disconnect: a later send is refused and never reconnects the socket', async () => {
+      // Disconnect voids the advertised protocol for the generation. The send must
+      // refuse and MUST NOT call socket.connect() to force a reconnection. Red:
+      // current impl keeps the conversation, infers turn:send, and its turn:send
+      // branch calls socket.connect() when the socket is disconnected.
+      const restore = installRandomUUID(() => UUID);
+      let returned: boolean | undefined;
+      let connectsDuringSend = 0;
+      try {
+        await establishConversation();
+        await act(async () => {
+          advertiseCapability('legacy-message', fake.socket.id);
+        });
+        await act(async () => {
+          fake.simulateDisconnect();
+        });
+        const before = connectCalls();
+        await act(async () => {
+          returned = harnessSend()({ content: 'after-drop', selection: capSelection });
+        });
+        connectsDuringSend = connectCalls() - before;
+      } finally {
+        restore();
+      }
+
+      expect(returned).toBe(false);
+      expect(fake.emitted).toHaveLength(0);
+      expect(latest?.state.error).toBe(UNAVAILABLE_NOTICE);
+      expect(connectsDuringSend).toBe(0);
+    });
+
+    it('resets on reconnect to a fresh generation: refuses until re-advertised, then honors the new advertisement', async () => {
+      // A reconnect mints a new Socket.id and a new generation; the prior
+      // advertisement (bound to the old id) is stale and must not carry over. The
+      // hook only trusts a fresh advertisement for the new connection. Red:
+      // current impl has no connect listener and keeps inferring turn:send.
+      const restore = installRandomUUID(() => UUID);
+      let refusedAfterReconnect: boolean | undefined;
+      try {
+        await establishConversation();
+        await act(async () => {
+          advertiseCapability('legacy-message', fake.socket.id);
+        });
+        await act(async () => {
+          fake.simulateReconnect('socket-b');
+        });
+        await act(async () => {
+          refusedAfterReconnect = harnessSend()({ content: 'stale', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(refusedAfterReconnect).toBe(false);
+      expect(fake.emitted).toHaveLength(0);
+      expect(latest?.state.error).toBe(UNAVAILABLE_NOTICE);
+
+      // A fresh advertisement for the reconnected id (socket-b) re-arms sending.
+      const restore2 = installRandomUUID(() => UUID);
+      try {
+        await act(async () => {
+          advertiseCapability('legacy-message', 'socket-b');
+        });
+        await act(async () => {
+          harnessSend()({ content: 'welcome-back', selection: capSelection });
+        });
+      } finally {
+        restore2();
+      }
+
+      expect(fake.emitted).toContainEqual({
+        event: 'message',
+        payload: {
+          conversationId: 'c1',
+          content: 'welcome-back',
+          provider: 'anthropic',
+          modelId: 'claude',
+        },
+      });
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(false);
+    });
+
+    it('routes on the synchronous protocol ref, not the batched reducer mirror: an advertisement and a send in the SAME tick still route by the just-advertised protocol', async () => {
+      // An advertisement lands and a send is issued within one synchronous tick,
+      // before React commits the reducer's `sendProtocol` mirror. The send is
+      // captured from the pre-advertisement render, so its closed-over reducer
+      // state still reads `sendProtocol === 'unavailable'`; the capability
+      // handler, however, has already set the synchronous `protocolRef` to
+      // `legacy-message`. The hook must route on that ref. Red (against a
+      // stale-mirror routing that reads `state.sendProtocol`): the send reads the
+      // pre-advertisement `unavailable` and refuses instead of emitting `message`.
+      const restore = installRandomUUID(() => UUID);
+      try {
+        await act(async () => {
+          // Bound to the CURRENT (pre-advertisement) render — its closure still
+          // sees the reset `unavailable` mirror even after the advert dispatches.
+          const sendBeforeCommit = harnessSend();
+          advertiseCapability('legacy-message', fake.socket.id);
+          // Same tick, no await: React has not committed the new mirror yet, so
+          // only `protocolRef` reflects `legacy-message`.
+          sendBeforeCommit({ content: 'same-tick', selection: capSelection });
+        });
+      } finally {
+        restore();
+      }
+
+      expect(fake.emitted).toContainEqual({
+        event: 'message',
+        payload: {
+          conversationId: undefined,
+          content: 'same-tick',
+          provider: 'anthropic',
+          modelId: 'claude',
+        },
+      });
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(false);
+    });
+  });
 });

apps/web/src/spa/chat/use-chat-connection.ts

@@ -12,6 +12,7 @@ import {
 import {
   asConversationId,
   asFiniteNumber,
+  asHarnessSelection,
   asString,
   asStringArray,
   isRecord,
@@ -21,10 +22,14 @@ import type {
   AgentStartPayload,
   AgentTextPayload,
   AgentThinkingPayload,
+  ChatSendCapabilityPayload,
+  ChatSendProtocol,
   CommandDef,
   CommandManifest,
   CommandManifestPayload,
   ErrorPayload,
+  HarnessSelection,
+  HarnessTurnAckPayload,
   MessageAckPayload,
   SessionInfoPayload,
   SessionUsagePayload,
@@ -130,6 +135,42 @@ const CONVERSATION_START_FAILURE = 'Unable to start this conversation. Please tr
  * dropped. */
 const APPROVAL_LIMIT_MESSAGE = 'Approval limit reached for this session. This command was not run.';
 
+/** Fixed, browser-safe notice surfaced when the harness runtime rejects a turn
+ * (`turn:ack` with `ok:false`). It is deliberately generic: the raw server
+ * `code`/`message`/`error` can carry adapter internals or entropy-source detail,
+ * so no rejection ever leaks its cause into the UI — every distinct rejection
+ * shows this same string. */
+const TURN_REJECTED_NOTICE = 'This turn could not be sent. Please try again.';
+
+/** Fixed, browser-safe notice surfaced when a turn is refused because the
+ * idempotency-key mint failed closed (`crypto.randomUUID` absent or throwing).
+ * Like {@link TURN_REJECTED_NOTICE}, it never carries the thrown message. */
+const IDEMPOTENCY_UNAVAILABLE_NOTICE = 'This turn could not be sent. Please try again.';
+
+/** The single fixed, browser-safe notice surfaced (with safe code
+ * `send_protocol_unavailable`) when a send is attempted on a connection whose
+ * negotiated send protocol is `unavailable` — the server never advertised a
+ * usable `chat:send-capability`, advertised `unavailable` (e.g. a pi-rpc runtime
+ * in this slice), or the advertisement was rejected (wrong connection id, replay,
+ * or an unknown protocol). It carries no dynamic detail. */
+const SEND_PROTOCOL_UNAVAILABLE_NOTICE = 'Chat sending is unavailable on this connection.';
+
+/** Mints a single idempotency key for one accepted `turn:send`, fail-closed.
+ * Returns a fresh RFC-4122 UUID from `crypto.randomUUID`, or `null` when that
+ * source is absent (not a function) or throws — the caller then refuses the turn
+ * rather than falling back to any non-cryptographic source (Math.random, a
+ * clock, or a counter would all be forgeable/collision-prone). Never throws. */
+function mintIdempotencyKey(): string | null {
+  try {
+    const c: unknown = globalThis.crypto;
+    if (!isRecord(c) || typeof c.randomUUID !== 'function') return null;
+    const key = (c.randomUUID as () => unknown)();
+    return typeof key === 'string' && key.length > 0 ? key : null;
+  } catch {
+    return null;
+  }
+}
+
 /** True only for the narrow case a malformed-conversationId `error`/`agent:end`
  * must be treated as a terminal startup failure: no conversation has ever been
  * established yet, and a send is still pending one. Once a conversation is
@@ -236,6 +277,14 @@ export interface PendingApproval {
   args?: string;
 }
 
+/** Receipt captured from an accepted harness `turn:ack` — the minimal record proving the
+ * server accepted this exact turn under its minted idempotency key and selection tuple. */
+export interface HarnessTurnReceipt {
+  idempotencyKey: string;
+  receiptId: string;
+  selection: HarnessSelection;
+}
+
 export interface ChatConnectionState {
   conversationId: string | null;
   /** True once a message has been sent while no conversation is active yet, so the
@@ -268,6 +317,18 @@ export interface ChatConnectionState {
   approvalRequestPending: boolean;
   systemReload: SystemReloadPayload | null;
   error: string | null;
+  /** How this connection is currently permitted to send, negotiated via the
+   * server-to-client-only `chat:send-capability` advertisement. Starts and resets
+   * to `'unavailable'` on every (re)connect and disconnect — a fresh or dropped
+   * connection has no usable protocol until the server (re-)advertises. This is
+   * the reactive/UI mirror of the synchronous `protocolRef` that `sendMessage`
+   * actually reads; the ref is authoritative because an advertisement and a send
+   * can occur in the same tick before React re-renders. */
+  sendProtocol: ChatSendProtocol;
+  /** Receipt from the most recently accepted harness `turn:ack`, or null before any
+   * turn has been accepted. A rejected turn:ack surfaces via `error` and leaves this
+   * untouched (a prior accepted receipt is not erased by a later rejection). */
+  turnReceipt: HarnessTurnReceipt | null;
   messages: ChatTranscriptMessage[];
   /** Monotonically increasing counter used to mint transcript message ids —
    * never reset while retained messages remain, so ids stay unique across the
@@ -308,7 +369,7 @@ export interface ChatConnectionState {
 }
 
 export interface ChatConnectionActions {
-  sendMessage: (input: { content: string; provider?: string; modelId?: string }) => void;
+  sendMessage: (input: { content: string; selection?: HarnessSelection }) => boolean;
   abort: () => void;
   setThinking: (level: string) => void;
   executeCommand: (input: { command: string; args?: string }) => void;
@@ -341,6 +402,8 @@ const initialState: ChatConnectionState = {
   approvalRequestPending: false,
   systemReload: null,
   error: null,
+  sendProtocol: 'unavailable',
+  turnReceipt: null,
   messages: [],
   messageSeq: 0,
   toolSeq: 0,
@@ -361,7 +424,12 @@ type Action =
   | { type: 'server/command:approval'; payload: SlashCommandApprovalResultPayload }
   | { type: 'server/system:reload'; payload: SystemReloadPayload }
   | { type: 'server/error'; payload: ErrorPayload }
+  | { type: 'server/turn:ack'; payload: HarnessTurnAckPayload }
   | { type: 'local/send'; content: string }
+  | { type: 'local/capability'; protocol: ChatSendProtocol }
+  | { type: 'local/reset-protocol' }
+  | { type: 'local/send-unavailable' }
+  | { type: 'local/turn-idempotency-unavailable' }
   | { type: 'local/approve-request'; command: string; args?: string }
   | { type: 'local/consume-approval' }
   | { type: 'local/approval-saturated' }
@@ -778,6 +846,30 @@ function reduce(state: ChatConnectionState, action: Action): ChatConnectionState
       };
     }
 
+    case 'server/turn:ack': {
+      // The harness runtime's turn acknowledgement. The success shape carries a
+      // receipt id + minted idempotencyKey + echoed selection; the failure shape
+      // is discriminated on `ok === false`. Every field is runtime-untrusted (the
+      // top-of-reducer guard already rejected a non-object payload).
+      const record = action.payload as Record<string, unknown>;
+      if (record.ok === false) {
+        // A rejected turn surfaces a FIXED browser-safe notice — never the raw
+        // server `message`/`error`/`code`, which can carry adapter internals — and
+        // does not disturb any previously accepted receipt.
+        return { ...state, error: TURN_REJECTED_NOTICE };
+      }
+      const idempotencyKey = asString(record.idempotencyKey);
+      // The web ack uses `receiptId`; fall back to the frozen contract's `turnId`.
+      const receiptId = asString(record.receiptId) || asString(record.turnId);
+      const selection = asHarnessSelection(record.selection);
+      if (idempotencyKey.length === 0 || receiptId.length === 0 || selection === null) {
+        // A malformed success frame is ignored outright rather than recorded as a
+        // half-populated receipt.
+        return state;
+      }
+      return { ...state, turnReceipt: { idempotencyKey, receiptId, selection } };
+    }
+
     case 'local/send': {
       const message: ChatTranscriptMessage = {
         // Sourced from the reducer-owned `messageSeq` counter — see the
@@ -802,6 +894,39 @@ function reduce(state: ChatConnectionState, action: Action): ChatConnectionState
       };
     }
 
+    case 'local/capability': {
+      // The FIRST valid `chat:send-capability` for this connection generation has
+      // been accepted (connection-id gating + first-wins enforced in the handler);
+      // record how this connection may now send. This is the reactive mirror of
+      // the synchronous `protocolRef` the send path reads.
+      return { ...state, sendProtocol: action.protocol };
+    }
+
+    case 'local/reset-protocol': {
+      // A (re)connect or disconnect voids any negotiated protocol: a fresh or
+      // dropped connection has no usable send capability until the server
+      // (re-)advertises. Reset to `unavailable` so no stale advertisement can
+      // authorize a send across a connection boundary.
+      if (state.sendProtocol === 'unavailable') return state;
+      return { ...state, sendProtocol: 'unavailable' };
+    }
+
+    case 'local/send-unavailable': {
+      // A send was attempted while the negotiated protocol is `unavailable`
+      // (never advertised / advertised unavailable / rejected advertisement).
+      // Surface the single FIXED safe notice — nothing was emitted, minted,
+      // appended, or locked.
+      return { ...state, error: SEND_PROTOCOL_UNAVAILABLE_NOTICE };
+    }
+
+    case 'local/turn-idempotency-unavailable': {
+      // The idempotency-key mint failed closed (crypto.randomUUID absent or
+      // throwing), so the turn was refused before emit. Surface a FIXED notice —
+      // never the underlying thrown message, which can leak entropy-source
+      // internals.
+      return { ...state, error: IDEMPOTENCY_UNAVAILABLE_NOTICE };
+    }
+
     case 'local/disconnect': {
       // A transient socket disconnect must not leave the UI stuck waiting on
       // a turn/approval/send that will never resolve on this connection.
@@ -882,6 +1007,20 @@ export function useChatConnection(): ChatConnectionValue {
     approveLockRef.current = state.approvalRequestPending;
   }, [state.approvalRequestPending]);
 
+  // Synchronous, generation-bound send protocol. `state.sendProtocol` drives the
+  // reactive UI, but reducer updates are batched/async — a `chat:send-capability`
+  // advertisement and a `sendMessage` can land in the same tick before React
+  // re-renders — so this ref is the source of truth the send path reads. Unlike
+  // sendLockRef/approveLockRef (synchronized FROM the reducer), this ref is
+  // written directly by the socket lifecycle/capability handlers below, which
+  // also dispatch the reducer mirror. It is NOT synchronized from state, because
+  // its whole purpose is to be correct BEFORE the reducer has re-rendered.
+  const protocolRef = useRef<ChatSendProtocol>('unavailable');
+  // True once the first valid advertisement for the CURRENT connection generation
+  // has been accepted; every later advertisement (a conflicting or replayed one)
+  // is ignored until the next (re)connect/disconnect resets the generation.
+  const protocolLockedRef = useRef(false);
+
   useEffect(() => {
     const socket = getSocket();
 
@@ -913,7 +1052,45 @@ export function useChatConnection(): ChatConnectionValue {
     const onError = (payload: ErrorPayload): void => {
       dispatch({ type: 'server/error', payload });
     };
+    const onTurnAck = (payload: HarnessTurnAckPayload): void =>
+      dispatch({ type: 'server/turn:ack', payload });
+
+    // Void the negotiated send protocol at every connection-lifecycle boundary.
+    // A fresh or dropped connection has no usable capability until the server
+    // (re-)advertises, so no advertisement bound to a prior connection may carry
+    // across the boundary and authorize a send. Both write the synchronous ref
+    // AND unlock first-wins, then dispatch the reducer mirror.
+    const resetSendProtocol = (): void => {
+      protocolRef.current = 'unavailable';
+      protocolLockedRef.current = false;
+      dispatch({ type: 'local/reset-protocol' });
+    };
+    const onConnect = (): void => {
+      resetSendProtocol();
+    };
+    const onCapability = (payload: ChatSendCapabilityPayload): void => {
+      // Server-to-client-only advertisement of how THIS connection may send.
+      // Accept only the FIRST valid one per generation, and only when it names
+      // this exact connection (`connectionId === socket.id`): a capability minted
+      // for another or stale connection must never arm this one. The payload is
+      // runtime-untrusted despite its compile-time type, so every field is
+      // guard-checked and an unknown protocol is dropped (leaving `unavailable`).
+      if (protocolLockedRef.current) return;
+      if (!isRecord(payload)) return;
+      const { protocol, connectionId } = payload as {
+        protocol?: unknown;
+        connectionId?: unknown;
+      };
+      if (typeof connectionId !== 'string' || connectionId !== socket.id) return;
+      if (protocol !== 'legacy-message' && protocol !== 'turn-send' && protocol !== 'unavailable') {
+        return;
+      }
+      protocolLockedRef.current = true;
+      protocolRef.current = protocol;
+      dispatch({ type: 'local/capability', protocol });
+    };
     const onDisconnect = (): void => {
+      resetSendProtocol();
       dispatch({ type: 'local/disconnect' });
     };
 
@@ -930,6 +1107,11 @@ export function useChatConnection(): ChatConnectionValue {
     socket.on('command:approval', onCommandApproval);
     socket.on('system:reload', onSystemReload);
     socket.on('error', onError);
+    socket.on('turn:ack', onTurnAck);
+    // Registered BEFORE connect so the initial post-auth advertisement (and any
+    // reconnect) can never race ahead of its listener.
+    socket.on('connect', onConnect);
+    socket.on('chat:send-capability', onCapability);
     socket.on('disconnect', onDisconnect);
 
     if (!socket.connected) {
@@ -950,24 +1132,79 @@ export function useChatConnection(): ChatConnectionValue {
       socket.off('command:approval', onCommandApproval);
       socket.off('system:reload', onSystemReload);
       socket.off('error', onError);
+      socket.off('turn:ack', onTurnAck);
+      socket.off('connect', onConnect);
+      socket.off('chat:send-capability', onCapability);
       socket.off('disconnect', onDisconnect);
       destroySocket();
     };
   }, []);
 
   const actions: ChatConnectionActions = {
-    sendMessage: ({ content, provider, modelId }) => {
-      if (sendLockRef.current || state.streaming || state.sending) return;
-      sendLockRef.current = true;
-      const socket = getSocket();
-      if (!socket.connected) socket.connect();
-      dispatch({ type: 'local/send', content });
-      socket.emit('message', {
-        conversationId: state.conversationId ?? undefined,
-        content,
-        provider,
-        modelId,
-      });
+    sendMessage: ({ content, selection }) => {
+      // Routing is PROTOCOL-driven, never inferred from conversation/selection/
+      // provider/local mode: the server advertised, once per connection, exactly
+      // how this connection may send, and that advertisement is authoritative.
+      // The exhaustive switch maps each protocol to its ONE event; the send path
+      // never reconnects the socket (a dropped connection has already reset the
+      // protocol to `unavailable`, so no emit branch is reachable while offline).
+      switch (protocolRef.current) {
+        case 'legacy-message': {
+          // Embedded/legacy runtime: EVERY browser turn — the first (which
+          // creates the conversation) and every later one — is the `message`
+          // event. provider/model are sourced ONLY from the confirmed persisted
+          // selection tuple, never from separate flat caller inputs.
+          if (sendLockRef.current || state.streaming || state.sending) return false;
+          sendLockRef.current = true;
+          const socket = getSocket();
+          dispatch({ type: 'local/send', content });
+          socket.emit('message', {
+            conversationId: state.conversationId ?? undefined,
+            content,
+            provider: selection?.providerId,
+            modelId: selection?.modelId,
+          });
+          return true;
+        }
+        case 'turn-send': {
+          // Pi turn-runtime: the exclusive `turn:send` contract. Requires an
+          // already-established conversation AND a confirmed persisted selection
+          // tuple; it is lock-independent (no send lock, no optimistic append),
+          // and mints exactly one idempotency key per accepted turn, failing the
+          // turn closed if the mint fails. A premature send (no conversation yet,
+          // or no selection) is refused with no emit and no notice.
+          if (selection == null || state.conversationId === null) return false;
+          const idempotencyKey = mintIdempotencyKey();
+          if (idempotencyKey === null) {
+            dispatch({ type: 'local/turn-idempotency-unavailable' });
+            return false;
+          }
+          const socket = getSocket();
+          socket.emit('turn:send', {
+            conversationId: state.conversationId,
+            content,
+            selection,
+            idempotencyKey,
+          });
+          return true;
+        }
+        case 'unavailable': {
+          // No usable protocol negotiated for this connection: refuse without
+          // emitting, minting, appending, or acquiring the lock, and surface the
+          // one fixed safe notice (code `send_protocol_unavailable`).
+          dispatch({ type: 'local/send-unavailable' });
+          return false;
+        }
+        default: {
+          // Exhaustiveness guard: every ChatSendProtocol member is handled above.
+          // An unknown value can never arm a send — refuse exactly as
+          // `unavailable` rather than falling through to any emit.
+          const _exhaustive: never = protocolRef.current;
+          void _exhaustive;
+          dispatch({ type: 'local/send-unavailable' });
+          return false;
+        }
+      }
     },
 
     abort: () => {

apps/web/src/spa/chat/use-harness-selection.spec.tsx

@@ -0,0 +1,450 @@
+import { act, type ReactElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useHarnessSelection, type HarnessSelectionValue } from './use-harness-selection';
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+interface Scenario {
+  harnesses?: unknown;
+  catalog?: { body: unknown; status?: number };
+  selection?: unknown;
+  /** When set, the PUT resolves only when this is called (for race tests). */
+  deferPut?: boolean;
+}
+
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+}
+
+function defer<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+let putBodies: unknown[] = [];
+let putDeferred: Deferred<Response> | null = null;
+
+function installFetch(scenario: Scenario): ReturnType<typeof vi.fn> {
+  putBodies = [];
+  putDeferred = scenario.deferPut ? defer<Response>() : null;
+  const fetchMock = vi.fn(async (input: unknown, init?: RequestInit) => {
+    const url = String(input);
+    const method = String(init?.method ?? 'GET').toUpperCase();
+    if (url === '/api/harnesses') return json(scenario.harnesses ?? []);
+    if (url.startsWith('/api/harnesses/') && url.endsWith('/catalog')) {
+      const spec = scenario.catalog ?? {
+        body: { harnessId: 'pi', version: '1', fingerprint: 'f', models: [] },
+      };
+      return json(spec.body, spec.status ?? 200);
+    }
+    if (url === '/api/chat/preferences/selection' && method === 'GET') {
+      return json({ selection: scenario.selection ?? null });
+    }
+    if (url === '/api/chat/preferences/selection' && method === 'PUT') {
+      putBodies.push(JSON.parse(String(init?.body)));
+      const ok = json({ selection: JSON.parse(String(init?.body)) });
+      if (putDeferred) return putDeferred.promise;
+      return ok;
+    }
+    return new Response('not found', { status: 404 });
+  });
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+let latest: HarnessSelectionValue | null = null;
+
+function Probe(): ReactElement | null {
+  latest = useHarnessSelection();
+  return null;
+}
+
+let root: Root | null;
+let container: HTMLElement;
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+beforeEach(() => {
+  latest = null;
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  vi.unstubAllGlobals();
+});
+
+async function mount(): Promise<void> {
+  await act(async () => {
+    root?.render(<Probe />);
+  });
+  await flush();
+}
+
+async function flush(times = 5): Promise<void> {
+  for (let i = 0; i < times; i += 1) {
+    await act(async () => {
+      await Promise.resolve();
+    });
+  }
+}
+
+function value(): HarnessSelectionValue {
+  if (!latest) throw new Error('hook value not captured');
+  return latest;
+}
+
+const PI_CATALOG = {
+  harnessId: 'pi',
+  version: '2026-08-11',
+  fingerprint: 'fp',
+  models: [
+    {
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+      displayName: 'GPT-5',
+      reasoningCapability: true,
+      inputTypes: ['text'],
+      authState: 'ready',
+      availability: 'available',
+    },
+    {
+      harnessId: 'pi',
+      providerId: 'anthropic',
+      modelId: 'claude',
+      displayName: 'Claude',
+      reasoningCapability: true,
+      inputTypes: ['text'],
+      authState: 'ready',
+      availability: 'available',
+    },
+  ],
+};
+
+describe('useHarnessSelection', () => {
+  it('loads harnesses and, once a harness is chosen, the model options come only from its catalog', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: PI_CATALOG },
+      selection: null,
+    });
+    await mount();
+
+    expect(value().harnesses).toEqual([{ id: 'pi', displayName: 'Pi', capabilities: [] }]);
+    expect(value().catalog).toBeNull();
+
+    await act(async () => {
+      value().selectHarness('pi');
+    });
+    await flush();
+
+    expect(value().catalog?.harnessId).toBe('pi');
+    expect(value().catalog?.models.map((m) => m.modelId)).toEqual(['gpt-5', 'claude']);
+  });
+
+  it('does not auto-select any catalog row when there is no persisted selection (no first-row fallback)', async () => {
+    const fetchMock = installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: PI_CATALOG },
+      selection: null,
+    });
+    await mount();
+    await act(async () => {
+      value().selectHarness('pi');
+    });
+    await flush();
+
+    expect(value().modelId).toBe('');
+    expect(value().persistedSelection).toBeNull();
+    expect(value().canSend).toBe(false);
+    // Nothing was persisted — no PUT fired for an unset selection.
+    const putCalls = fetchMock.mock.calls.filter(
+      (c) => String((c[1] as RequestInit)?.method).toUpperCase() === 'PUT',
+    );
+    expect(putCalls).toHaveLength(0);
+  });
+
+  it('persists the structured tuple and only enables send AFTER the PUT resolves (no race ahead of persistence)', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: PI_CATALOG },
+      selection: null,
+      deferPut: true,
+    });
+    await mount();
+    await act(async () => {
+      value().selectHarness('pi');
+    });
+    await flush();
+    await act(async () => {
+      value().selectProvider('openai');
+    });
+    await act(async () => {
+      value().selectModel('openai', 'gpt-5');
+    });
+    await flush();
+
+    // PUT is in flight (deferred) — send MUST NOT be enabled yet.
+    expect(value().canSend).toBe(false);
+
+    await act(async () => {
+      putDeferred?.resolve(
+        json({ selection: { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' } }),
+      );
+    });
+    await flush();
+
+    expect(putBodies).toContainEqual({ harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' });
+    expect(value().persistedSelection).toEqual({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+    });
+    expect(value().canSend).toBe(true);
+    // Task Five: the composer sends the nested `persistedSelection` tuple directly.
+    // The Task-Four compat flat `projection` ({provider, modelId}) is removed — the
+    // harnessId must never be dropped on the way to the wire.
+    expect('projection' in value()).toBe(false);
+  });
+
+  it('keeps a stale/unavailable persisted selection visibly displayed rather than silently dropping it', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: PI_CATALOG },
+      selection: { harnessId: 'pi', providerId: 'openai', modelId: 'retired-model' },
+    });
+    await mount();
+
+    // The persisted tuple is displayed even though its model is gone from the catalog.
+    expect(value().persistedSelection).toEqual({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'retired-model',
+    });
+    expect(value().modelId).toBe('retired-model');
+    expect(value().isStale).toBe(true);
+    // A stale model is not a valid catalog option, so send stays disabled.
+    expect(value().canSend).toBe(false);
+  });
+
+  it('disables send for an empty catalog (no viable model) and never fabricates one', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: { harnessId: 'pi', version: '1', fingerprint: 'f', models: [] } },
+      selection: null,
+    });
+    await mount();
+    await act(async () => {
+      value().selectHarness('pi');
+    });
+    await flush();
+
+    expect(value().catalog?.models ?? []).toHaveLength(0);
+    expect(value().canSend).toBe(false);
+  });
+
+  it('marks the catalog unavailable and disables send when the catalog request 404s', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: {
+        body: { code: 'adapter_unavailable', message: 'x', harnessId: 'pi' },
+        status: 404,
+      },
+      selection: null,
+    });
+    await mount();
+    await act(async () => {
+      value().selectHarness('pi');
+    });
+    await flush();
+
+    expect(value().catalogUnavailable).toBe(true);
+    expect(value().canSend).toBe(false);
+  });
+
+  it('on a 422 persist, keeps the requested tuple visible, surfaces a typed error, and leaves send disabled', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: {
+        body: {
+          ...PI_CATALOG,
+          models: [{ ...PI_CATALOG.models[0], availability: 'unavailable' }],
+        },
+      },
+      selection: null,
+    });
+    // Override PUT to 422.
+    const fetchMock = vi.fn(async (input: unknown, init?: RequestInit) => {
+      const url = String(input);
+      const method = String(init?.method ?? 'GET').toUpperCase();
+      if (url === '/api/harnesses')
+        return json([{ id: 'pi', displayName: 'Pi', capabilities: [] }]);
+      if (url.endsWith('/catalog')) return json(PI_CATALOG);
+      if (url === '/api/chat/preferences/selection' && method === 'GET')
+        return json({ selection: null });
+      if (url === '/api/chat/preferences/selection' && method === 'PUT') {
+        return json(
+          {
+            code: 'model_unavailable',
+            message: 'nope',
+            selection: { harnessId: 'a', providerId: 'b', modelId: 'c' },
+          },
+          422,
+        );
+      }
+      return new Response('nf', { status: 404 });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await mount();
+    await act(async () => {
+      value().selectHarness('pi');
+    });
+    await flush();
+    await act(async () => {
+      value().selectProvider('openai');
+    });
+    await act(async () => {
+      value().selectModel('openai', 'gpt-5');
+    });
+    await flush();
+
+    expect(value().modelId).toBe('gpt-5');
+    expect(value().persistError?.code).toBe('model_unavailable');
+    expect(value().persistError?.requested).toEqual({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+    });
+    expect(value().persistedSelection).toBeNull();
+    expect(value().canSend).toBe(false);
+  });
+
+  it('invalidates the model on a provider change and keeps send disabled until the new tuple persists', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: PI_CATALOG },
+      selection: null,
+    });
+    await mount();
+    await act(async () => {
+      value().selectHarness('pi');
+    });
+    await flush();
+    await act(async () => {
+      value().selectProvider('openai');
+    });
+    await act(async () => {
+      value().selectModel('openai', 'gpt-5');
+    });
+    await flush();
+    // A valid provider-A tuple has persisted.
+    expect(value().canSend).toBe(true);
+    expect(value().persistedSelection).toEqual({
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+    });
+
+    // Switching provider clears the model that no longer belongs to it.
+    await act(async () => {
+      value().selectProvider('anthropic');
+    });
+    expect(value().modelId).toBe('');
+    expect(value().canSend).toBe(false);
+
+    // Send stays disabled until the new exact provider-B tuple persists.
+    await act(async () => {
+      value().selectModel('anthropic', 'claude');
+    });
+    await flush();
+    expect(value().canSend).toBe(true);
+    expect(value().persistedSelection).toEqual({
+      harnessId: 'pi',
+      providerId: 'anthropic',
+      modelId: 'claude',
+    });
+    // Task Five: no compat flat projection — the nested persistedSelection is the wire tuple.
+    expect('projection' in value()).toBe(false);
+  });
+
+  it('does not enable send on a model pick until the PUT for that exact new tuple resolves', async () => {
+    installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: PI_CATALOG },
+      selection: { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' },
+      deferPut: true,
+    });
+    await mount();
+    // The persisted, in-catalog tuple is sendable after mount (no PUT needed).
+    expect(value().canSend).toBe(true);
+
+    await act(async () => {
+      value().selectProvider('anthropic');
+    });
+    expect(value().modelId).toBe('');
+    expect(value().canSend).toBe(false);
+
+    await act(async () => {
+      value().selectModel('anthropic', 'claude');
+    });
+    await flush();
+    // PUT for the new tuple is still in flight — send MUST stay disabled.
+    expect(value().canSend).toBe(false);
+
+    await act(async () => {
+      putDeferred?.resolve(
+        json({ selection: { harnessId: 'pi', providerId: 'anthropic', modelId: 'claude' } }),
+      );
+    });
+    await flush();
+    expect(value().canSend).toBe(true);
+    // Task Five: no compat flat projection — the nested persistedSelection is the wire tuple.
+    expect('projection' in value()).toBe(false);
+  });
+
+  it('never requests any /api/providers* endpoint across the whole flow', async () => {
+    const fetchMock = installFetch({
+      harnesses: [{ id: 'pi', displayName: 'Pi', capabilities: [] }],
+      catalog: { body: PI_CATALOG },
+      selection: { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' },
+    });
+    await mount();
+    await act(async () => {
+      value().selectProvider('anthropic');
+    });
+    await act(async () => {
+      value().selectModel('anthropic', 'claude');
+    });
+    await flush();
+
+    for (const call of fetchMock.mock.calls) {
+      expect(String(call[0])).not.toContain('/api/providers');
+    }
+  });
+});

apps/web/src/spa/chat/use-harness-selection.ts

@@ -0,0 +1,208 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  fetchCatalog,
+  fetchHarnesses,
+  fetchPersistedSelection,
+  persistSelection,
+  type SelectionErrorCode,
+} from './chat-api';
+import type { HarnessCatalog, HarnessSelection, HarnessSummary } from '@/lib/types';
+
+export interface HarnessPersistError {
+  code: SelectionErrorCode;
+  message: string;
+  /** The exact tuple the user requested — preserved so the failed selection
+   * stays visible rather than being silently dropped. */
+  requested: HarnessSelection;
+}
+
+export interface HarnessSelectionValue {
+  harnesses: HarnessSummary[];
+  catalog: HarnessCatalog | null;
+  /** True when the selected harness has no usable catalog (404/error). */
+  catalogUnavailable: boolean;
+  /** The working (displayed) selection, kept as three distinct ids. Empty
+   * strings mean "not chosen yet" — there is deliberately no first-row default. */
+  harnessId: string;
+  providerId: string;
+  modelId: string;
+  /** The last tuple confirmed persisted by the server, or null. */
+  persistedSelection: HarnessSelection | null;
+  /** True when a persisted selection references a model no longer present as an
+   * available catalog entry — it stays visibly displayed rather than dropped. */
+  isStale: boolean;
+  /** True ONLY once a full tuple has been confirmed persisted AND it is a
+   * currently-available catalog entry. Send stays disabled otherwise, so a send
+   * can never race ahead of successful persistence. */
+  canSend: boolean;
+  persistError: HarnessPersistError | null;
+  selectHarness: (harnessId: string) => void;
+  selectProvider: (providerId: string) => void;
+  /** Persist the EXACT catalog row's `{providerId, modelId}` — the caller
+   * resolves the composite option identity to the real entry and passes both
+   * ids, so a bare model id is never combined with ambient provider state. */
+  selectModel: (providerId: string, modelId: string) => void;
+}
+
+/** A tuple is a currently-usable catalog option only when the catalog holds a
+ * matching, available entry — the single gate that keeps a stale/unavailable
+ * model from ever counting as sendable. */
+function isAvailableInCatalog(
+  selection: HarnessSelection | null,
+  catalog: HarnessCatalog | null,
+): boolean {
+  if (selection === null || catalog === null) return false;
+  return catalog.models.some(
+    (model) =>
+      model.providerId === selection.providerId &&
+      model.modelId === selection.modelId &&
+      model.availability === 'available',
+  );
+}
+
+function tuplesEqual(a: HarnessSelection | null, b: HarnessSelection | null): boolean {
+  if (a === null || b === null) return a === b;
+  return a.harnessId === b.harnessId && a.providerId === b.providerId && a.modelId === b.modelId;
+}
+
+/**
+ * Owns the harness/catalog/selection state for the chat composer: loads the
+ * harness list and any persisted tuple on mount, loads a harness's catalog when
+ * chosen, and PUT-persists the full `{harnessId, providerId, modelId}` tuple
+ * when a model is picked. It never auto-selects a catalog row, keeps a
+ * stale/unavailable persisted tuple visible, and only reports `canSend` true
+ * once a full tuple has actually persisted as an available catalog entry.
+ */
+export function useHarnessSelection(): HarnessSelectionValue {
+  const [harnesses, setHarnesses] = useState<HarnessSummary[]>([]);
+  const [catalog, setCatalog] = useState<HarnessCatalog | null>(null);
+  const [catalogUnavailable, setCatalogUnavailable] = useState(false);
+  const [harnessId, setHarnessId] = useState('');
+  const [providerId, setProviderId] = useState('');
+  const [modelId, setModelId] = useState('');
+  const [persistedSelection, setPersistedSelection] = useState<HarnessSelection | null>(null);
+  const [persistError, setPersistError] = useState<HarnessPersistError | null>(null);
+
+  // Monotonic request ids so a slow in-flight catalog/persist response can never
+  // overwrite the result of a newer request the user has since triggered.
+  const catalogRequestRef = useRef(0);
+  const persistRequestRef = useRef(0);
+
+  const loadCatalog = useCallback(async (id: string): Promise<void> => {
+    const requestId = catalogRequestRef.current + 1;
+    catalogRequestRef.current = requestId;
+    setCatalog(null);
+    setCatalogUnavailable(false);
+    const result = await fetchCatalog(id);
+    if (catalogRequestRef.current !== requestId) return;
+    if (result.ok) {
+      setCatalog(result.catalog);
+      setCatalogUnavailable(false);
+    } else {
+      setCatalog(null);
+      setCatalogUnavailable(true);
+    }
+  }, []);
+
+  useEffect(() => {
+    let active = true;
+    void (async (): Promise<void> => {
+      const [list, persisted] = await Promise.all([fetchHarnesses(), fetchPersistedSelection()]);
+      if (!active) return;
+      setHarnesses(list);
+      if (persisted !== null) {
+        // Adopt the persisted tuple as the displayed selection and load its
+        // catalog. If the model has since been retired, it still shows (stale).
+        setHarnessId(persisted.harnessId);
+        setProviderId(persisted.providerId);
+        setModelId(persisted.modelId);
+        setPersistedSelection(persisted);
+        await loadCatalog(persisted.harnessId);
+      }
+      // No persisted selection → nothing is auto-selected; the user must choose.
+    })();
+    return () => {
+      active = false;
+    };
+  }, [loadCatalog]);
+
+  const selectHarness = useCallback(
+    (id: string): void => {
+      setHarnessId(id);
+      // Changing harness invalidates the provider/model draft — never carry a
+      // model across harnesses.
+      setProviderId('');
+      setModelId('');
+      setPersistError(null);
+      void loadCatalog(id);
+    },
+    [loadCatalog],
+  );
+
+  const selectProvider = useCallback((id: string): void => {
+    setProviderId(id);
+    // A new provider invalidates the chosen model — no cross-provider carryover.
+    setModelId('');
+    setPersistError(null);
+  }, []);
+
+  const selectModel = useCallback(
+    (selectedProviderId: string, selectedModelId: string): void => {
+      // Bind the model to the EXACT catalog row's provider — never to ambient
+      // provider state — so two providers exposing the same modelId can never
+      // collide or mis-resolve. Keep the displayed provider consistent with the
+      // resolved row.
+      setProviderId(selectedProviderId);
+      setModelId(selectedModelId);
+      setPersistError(null);
+      const requested: HarnessSelection = {
+        harnessId,
+        providerId: selectedProviderId,
+        modelId: selectedModelId,
+      };
+      const requestId = persistRequestRef.current + 1;
+      persistRequestRef.current = requestId;
+      void (async (): Promise<void> => {
+        const result = await persistSelection(requested);
+        if (persistRequestRef.current !== requestId) return;
+        if (result.ok) {
+          setPersistedSelection(result.selection);
+          setPersistError(null);
+        } else {
+          // Leave persistedSelection unchanged (send stays disabled) and surface
+          // the typed error carrying the exact requested tuple.
+          setPersistError({
+            code: result.code,
+            message: result.message,
+            requested: result.requested,
+          });
+        }
+      })();
+    },
+    [harnessId],
+  );
+
+  const draft: HarnessSelection = { harnessId, providerId, modelId };
+  const isStale = persistedSelection !== null && !isAvailableInCatalog(persistedSelection, catalog);
+  const canSend =
+    persistedSelection !== null &&
+    !catalogUnavailable &&
+    tuplesEqual(draft, persistedSelection) &&
+    isAvailableInCatalog(persistedSelection, catalog);
+
+  return {
+    harnesses,
+    catalog,
+    catalogUnavailable,
+    harnessId,
+    providerId,
+    modelId,
+    persistedSelection,
+    isStale,
+    canSend,
+    persistError,
+    selectHarness,
+    selectProvider,
+    selectModel,
+  };
+}

apps/web/src/spa/pages/chat.spec.tsx

@@ -38,6 +38,128 @@ function findButton(container: HTMLElement, text: string): HTMLButtonElement {
   return button;
 }
 
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+const DEFAULT_CATALOG = {
+  harnessId: 'pi',
+  version: '2026-08-11',
+  fingerprint: 'fp',
+  models: [
+    {
+      harnessId: 'pi',
+      providerId: 'openai',
+      modelId: 'gpt-5',
+      displayName: 'GPT-5',
+      reasoningCapability: true,
+      inputTypes: ['text'],
+      authState: 'ready',
+      availability: 'available',
+    },
+    {
+      harnessId: 'pi',
+      providerId: 'anthropic',
+      modelId: 'claude',
+      displayName: 'Claude',
+      reasoningCapability: true,
+      inputTypes: ['text'],
+      authState: 'ready',
+      availability: 'available',
+    },
+  ],
+};
+
+/** A harness/catalog/selection HTTP stub for the chat-api the selection hook
+ * drives. `selection` seeds the persisted tuple returned by the GET (a valid
+ * in-catalog tuple by default, so `canSend` settles true after mount). */
+function harnessFetch(
+  selection: unknown = { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' },
+): typeof fetch {
+  return vi.fn(async (input: unknown, init?: RequestInit) => {
+    const url = String(input);
+    const method = String(init?.method ?? 'GET').toUpperCase();
+    if (url === '/api/harnesses') {
+      return jsonResponse([{ id: 'pi', displayName: 'Pi', capabilities: [] }]);
+    }
+    if (url.startsWith('/api/harnesses/') && url.endsWith('/catalog')) {
+      return jsonResponse(DEFAULT_CATALOG);
+    }
+    if (url === '/api/chat/preferences/selection' && method === 'GET') {
+      return jsonResponse({ selection });
+    }
+    if (url === '/api/chat/preferences/selection' && method === 'PUT') {
+      return jsonResponse({ selection: JSON.parse(String(init?.body)) });
+    }
+    return new Response('not found', { status: 404 });
+  }) as unknown as typeof fetch;
+}
+
+/** Drains the selection hook's chained mount fetches (harnesses → selection →
+ * catalog) and any pending PUT so derived `canSend` settles before assertions. */
+async function flushAsync(times = 5): Promise<void> {
+  for (let i = 0; i < times; i += 1) {
+    await act(async () => {
+      await Promise.resolve();
+    });
+  }
+}
+
+/** Deterministic idempotency key for the Task Five red-first page send test. */
+const PAGE_UUID = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
+
+/** Install a controllable `crypto.randomUUID` and return a restore fn. Uses
+ * defineProperty on the crypto instance so it works whether or not the native
+ * method is configurable (it lives on the prototype; an own property shadows it). */
+function installRandomUUID(fn: () => string): () => void {
+  const g = globalThis as { crypto?: { randomUUID?: () => string } };
+  if (!g.crypto) {
+    Object.defineProperty(g, 'crypto', { configurable: true, writable: true, value: {} });
+  }
+  const cryptoObj = g.crypto as { randomUUID?: () => string };
+  const original = Object.getOwnPropertyDescriptor(cryptoObj, 'randomUUID');
+  Object.defineProperty(cryptoObj, 'randomUUID', {
+    configurable: true,
+    writable: true,
+    value: fn,
+  });
+  return () => {
+    if (original) {
+      Object.defineProperty(cryptoObj, 'randomUUID', original);
+    } else {
+      Reflect.deleteProperty(cryptoObj, 'randomUUID');
+    }
+  };
+}
+
+/**
+ * Task Five MAJOR-1: the send path is PROTOCOL-driven — the browser may send only
+ * as the server advertised, once per connection, over the server-to-client-only
+ * `chat:send-capability`. Model that advertisement for THIS connection id so the
+ * page send tests take the intended branch. `legacy-message` is the default
+ * (advertised in `beforeEach`/`remountWithFetch`); the pi turn-runtime tests
+ * reset the generation and re-advertise `turn-send` via the helper below.
+ */
+function advertiseSendCapability(protocol: 'legacy-message' | 'turn-send' | 'unavailable'): void {
+  fake.serverEmit('chat:send-capability', { protocol, connectionId: fake.socket.id });
+}
+
+/** Reset the negotiated protocol to a fresh, unlocked generation (clearing the
+ * default `legacy-message` advertisement + first-wins lock), then advertise the
+ * pi turn-runtime `turn:send` protocol for this connection. The per-test override
+ * for the page send tests that route through `turn:send`. */
+async function advertiseTurnSendGeneration(): Promise<void> {
+  await act(async () => {
+    fake.simulateReconnect();
+  });
+  await act(async () => {
+    advertiseSendCapability('turn-send');
+  });
+}
+
 let fake: ReturnType<typeof createFakeChatSocket>;
 let root: Root | null;
 let container: HTMLElement;
@@ -57,12 +179,22 @@ beforeEach(async () => {
   fake = createFakeChatSocket();
   getSocketMock.mockReset().mockReturnValue(fake.socket);
   destroySocketMock.mockReset();
+  vi.stubGlobal('fetch', harnessFetch());
   container = document.createElement('div');
   document.body.append(container);
   root = createRoot(container);
   await act(async () => {
     root?.render(<ChatPage />);
   });
+  // Settle the selection hook's mount fetches so the default in-catalog tuple
+  // persists and `canSend` is true for the existing send-path tests.
+  await flushAsync();
+  // Model the server's post-auth send-capability advertisement (MAJOR-1). Most
+  // page send tests exercise the legacy `message` branch; the pi turn-runtime
+  // tests override to `turn-send` via advertiseTurnSendGeneration().
+  await act(async () => {
+    advertiseSendCapability('legacy-message');
+  });
 });
 
 afterEach(async () => {
@@ -70,8 +202,28 @@ afterEach(async () => {
     root?.unmount();
   });
   document.body.replaceChildren();
+  vi.unstubAllGlobals();
 });
 
+/** Re-mounts ChatPage against a custom fetch stub (e.g. an unset selection) for
+ * tests that need a non-default selection scenario. */
+async function remountWithFetch(fetchImpl: typeof fetch): Promise<void> {
+  await act(async () => {
+    root?.unmount();
+  });
+  vi.stubGlobal('fetch', fetchImpl);
+  root = createRoot(container);
+  await act(async () => {
+    root?.render(<ChatPage />);
+  });
+  await flushAsync();
+  // Re-advertise on the remounted connection — the prior generation's capability
+  // does not carry across a remount (fresh hook instance, unadvertised protocol).
+  await act(async () => {
+    advertiseSendCapability('legacy-message');
+  });
+}
+
 describe('ChatPage', () => {
   it('streams agent:text and agent:thinking, shows tool status, and finalizes on agent:end with usage', async () => {
     await act(async () => {
@@ -390,24 +542,62 @@ describe('ChatPage', () => {
     expect(container.querySelector('[role="alert"]')).toBeTruthy();
   });
 
-  it('sends a message with optional provider/model fields and emits abort from the Stop control', async () => {
+  it('renders harness and provider as separate selects (not merged) and no free-text provider/model inputs', async () => {
+    // The old free-text inputs are gone.
+    expect(container.querySelector('input[aria-label="Provider"]')).toBeNull();
+    expect(container.querySelector('input[aria-label="Model"]')).toBeNull();
+
+    const harnessSelect = container.querySelector(
+      'select[aria-label="Harness"]',
+    ) as HTMLSelectElement;
+    const providerSelect = container.querySelector(
+      'select[aria-label="Provider"]',
+    ) as HTMLSelectElement;
+    const modelSelect = container.querySelector('select[aria-label="Model"]') as HTMLSelectElement;
+    expect(harnessSelect).toBeTruthy();
+    expect(providerSelect).toBeTruthy();
+    expect(modelSelect).toBeTruthy();
+    // Harness and provider are distinct controls carrying distinct identifiers.
+    expect(harnessSelect).not.toBe(providerSelect);
+    expect([...harnessSelect.options].map((o) => o.value)).toContain('pi');
+    expect([...providerSelect.options].map((o) => o.value)).toContain('openai');
+    expect([...providerSelect.options].map((o) => o.value)).toContain('anthropic');
+    // The model options are catalog-derived (not hardcoded) and scoped to the
+    // selected provider (openai, from the persisted tuple) using a collision-safe
+    // composite identity — the anthropic row is absent, not a bare 'claude'.
+    const modelValues = [...modelSelect.options].map((o) => o.value);
+    expect(modelValues).toContain('openai:gpt-5');
+    expect(modelValues).not.toContain('anthropic:claude');
+    expect(modelValues).not.toContain('claude');
+  });
+
+  it('sends provider/model derived from the persisted catalog tuple (never free text) and emits abort from Stop', async () => {
     const textarea = container.querySelector(
       'textarea[aria-label="Message"]',
     ) as HTMLTextAreaElement;
-    const providerInput = container.querySelector(
-      'input[aria-label="Provider"]',
-    ) as HTMLInputElement;
-    const modelInput = container.querySelector('input[aria-label="Model"]') as HTMLInputElement;
 
     const stopButtonBefore = container.querySelector(
       'button[aria-label="Stop"]',
     ) as HTMLButtonElement;
     expect(stopButtonBefore.disabled).toBe(true);
 
+    // Choose a fresh tuple from the catalog and let it persist.
+    const providerSelect = container.querySelector(
+      'select[aria-label="Provider"]',
+    ) as HTMLSelectElement;
+    await act(async () => {
+      selectValue(providerSelect, 'anthropic');
+    });
+    const modelSelect = container.querySelector('select[aria-label="Model"]') as HTMLSelectElement;
+    await act(async () => {
+      // Composite provider+model option identity (provider was switched to
+      // anthropic above); the bare 'claude' no longer identifies an option.
+      selectValue(modelSelect, 'anthropic:claude');
+    });
+    await flushAsync();
+
     await act(async () => {
       setValue(textarea, 'hello there');
-      setValue(providerInput, 'anthropic');
-      setValue(modelInput, 'claude');
     });
     await act(async () => {
       textarea.dispatchEvent(
@@ -415,6 +605,7 @@ describe('ChatPage', () => {
       );
     });
 
+    // The projected provider/model come from the validated persisted tuple.
     expect(fake.emitted).toContainEqual({
       event: 'message',
       payload: {
@@ -443,6 +634,178 @@ describe('ChatPage', () => {
     expect(fake.emitted).toContainEqual({ event: 'abort', payload: { conversationId: 'c1' } });
   });
 
+  it('emits turn:send with the nested persisted selection tuple and a UUID idempotency key (never the legacy message event)', async () => {
+    await advertiseTurnSendGeneration();
+    const restore = installRandomUUID(() => PAGE_UUID);
+    try {
+      // Send is disabled without an active conversation — establish one first.
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+
+      const textarea = container.querySelector(
+        'textarea[aria-label="Message"]',
+      ) as HTMLTextAreaElement;
+      await act(async () => {
+        setValue(textarea, 'hello there');
+      });
+      await act(async () => {
+        textarea.dispatchEvent(
+          new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+        );
+      });
+    } finally {
+      restore();
+    }
+
+    const sends = fake.emitted.filter((e) => e.event === 'turn:send');
+    expect(sends).toHaveLength(1);
+    expect(sends[0]?.payload).toEqual({
+      conversationId: 'c1',
+      content: 'hello there',
+      selection: { harnessId: 'pi', providerId: 'openai', modelId: 'gpt-5' },
+      idempotencyKey: PAGE_UUID,
+    });
+    // The pi-rpc page send must not emit the embedded `message` event, and must
+    // never send a flat {provider, modelId} that drops the harnessId.
+    expect(fake.emitted.some((e) => e.event === 'message')).toBe(false);
+  });
+
+  it('keeps the composer content and emits nothing when the send cannot mint an idempotency key, so the user can retry (composer clears only on success) — Task Five group 5', async () => {
+    await advertiseTurnSendGeneration();
+    const failing = installRandomUUID(() => {
+      throw new Error('secure random unavailable');
+    });
+    try {
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+      const textarea = container.querySelector(
+        'textarea[aria-label="Message"]',
+      ) as HTMLTextAreaElement;
+      await act(async () => {
+        setValue(textarea, 'keep me');
+      });
+      await act(async () => {
+        textarea.dispatchEvent(
+          new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+        );
+      });
+
+      // No wire traffic: neither the harness turn nor the legacy message.
+      expect(fake.emitted.some((e) => e.event === 'turn:send')).toBe(false);
+      expect(fake.emitted.some((e) => e.event === 'message')).toBe(false);
+      // The composer retained its content — it clears ONLY on a successful send,
+      // so the user can retry without retyping.
+      expect(textarea.value).toBe('keep me');
+      // A visible, safe notice explains why nothing was sent.
+      expect(container.querySelector('[role="alert"]')).toBeTruthy();
+    } finally {
+      failing();
+    }
+  });
+
+  it('clears the composer after a successful turn:send and never falls back to the legacy message event — Task Five group 5', async () => {
+    await advertiseTurnSendGeneration();
+    const restore = installRandomUUID(() => PAGE_UUID);
+    try {
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+      const textarea = container.querySelector(
+        'textarea[aria-label="Message"]',
+      ) as HTMLTextAreaElement;
+      await act(async () => {
+        setValue(textarea, 'ship it');
+      });
+      await act(async () => {
+        textarea.dispatchEvent(
+          new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+        );
+      });
+
+      const sends = fake.emitted.filter((e) => e.event === 'turn:send');
+      expect(sends).toHaveLength(1);
+      expect(fake.emitted.some((e) => e.event === 'message')).toBe(false);
+      // On a successful send the composer clears.
+      expect(textarea.value).toBe('');
+    } finally {
+      restore();
+    }
+  });
+
+  it('sends the freshly persisted selection as a nested turn:send tuple after the user changes provider/model — never a stale default or flat fields — Task Five group 5', async () => {
+    await advertiseTurnSendGeneration();
+    const restore = installRandomUUID(() => PAGE_UUID);
+    try {
+      // Change the selection away from the mount default and let it persist.
+      const providerSelect = container.querySelector(
+        'select[aria-label="Provider"]',
+      ) as HTMLSelectElement;
+      await act(async () => {
+        selectValue(providerSelect, 'anthropic');
+      });
+      const modelSelect = container.querySelector(
+        'select[aria-label="Model"]',
+      ) as HTMLSelectElement;
+      await act(async () => {
+        selectValue(modelSelect, 'anthropic:claude');
+      });
+      await flushAsync();
+
+      await act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      });
+      const textarea = container.querySelector(
+        'textarea[aria-label="Message"]',
+      ) as HTMLTextAreaElement;
+      await act(async () => {
+        setValue(textarea, 'routed');
+      });
+      await act(async () => {
+        textarea.dispatchEvent(
+          new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+        );
+      });
+
+      const sends = fake.emitted.filter((e) => e.event === 'turn:send');
+      expect(sends).toHaveLength(1);
+      // The nested tuple reflects the CURRENTLY persisted selection, not the
+      // mount default {openai, gpt-5}, and never flat provider/model fields.
+      expect(sends[0]?.payload).toEqual({
+        conversationId: 'c1',
+        content: 'routed',
+        selection: { harnessId: 'pi', providerId: 'anthropic', modelId: 'claude' },
+        idempotencyKey: PAGE_UUID,
+      });
+      expect(fake.emitted.some((e) => e.event === 'message')).toBe(false);
+    } finally {
+      restore();
+    }
+  });
+
+  it('disables send until a selection has persisted — no send with an unset selection', async () => {
+    await remountWithFetch(harnessFetch(null));
+
+    const sendButton = findButton(container, 'Send');
+    const textarea = container.querySelector(
+      'textarea[aria-label="Message"]',
+    ) as HTMLTextAreaElement;
+
+    await act(async () => {
+      setValue(textarea, 'should not send');
+    });
+    // Content present, but no selection persisted → Send stays disabled.
+    expect(sendButton.disabled).toBe(true);
+
+    await act(async () => {
+      textarea.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+    });
+    expect(fake.emitted.filter((e) => e.event === 'message')).toHaveLength(0);
+  });
+
   it('renders the session panel from a pre-ack session:info and keeps it visible after the later ack', async () => {
     const textarea = container.querySelector(
       'textarea[aria-label="Message"]',
@@ -620,6 +983,134 @@ describe('ChatPage', () => {
     expect(fake.emitted.filter((e) => e.event === 'message')).toHaveLength(1);
   });
 
+  it('scopes the model options to the intentionally selected provider (cross-provider models absent)', async () => {
+    await remountWithFetch(harnessFetch(null));
+
+    const harnessSelect = container.querySelector(
+      'select[aria-label="Harness"]',
+    ) as HTMLSelectElement;
+    await act(async () => {
+      selectValue(harnessSelect, 'pi');
+    });
+    await flushAsync();
+
+    const providerSelect = container.querySelector(
+      'select[aria-label="Provider"]',
+    ) as HTMLSelectElement;
+    await act(async () => {
+      selectValue(providerSelect, 'openai');
+    });
+
+    const modelSelect = container.querySelector('select[aria-label="Model"]') as HTMLSelectElement;
+    const optionValues = [...modelSelect.options].map((o) => o.value).filter((v) => v !== '');
+    // Only the selected provider's models are offered — provider B's model
+    // (anthropic:claude) is absent, so a user cannot pick across providers.
+    expect(optionValues).toEqual(['openai:gpt-5']);
+    expect(optionValues).not.toContain('anthropic:claude');
+  });
+
+  it('keeps identical modelIds under two providers distinct and resolves the pick to the exact tuple', async () => {
+    const COLLIDING_CATALOG = {
+      harnessId: 'pi',
+      version: '2026-08-11',
+      fingerprint: 'fp',
+      models: [
+        {
+          harnessId: 'pi',
+          providerId: 'alpha',
+          modelId: 'gpt-x',
+          displayName: 'Alpha GPT-X',
+          reasoningCapability: true,
+          inputTypes: ['text'],
+          authState: 'ready',
+          availability: 'available',
+        },
+        {
+          harnessId: 'pi',
+          providerId: 'beta',
+          modelId: 'gpt-x',
+          displayName: 'Beta GPT-X',
+          reasoningCapability: true,
+          inputTypes: ['text'],
+          authState: 'ready',
+          availability: 'available',
+        },
+      ],
+    };
+    const collidingFetch = vi.fn(async (input: unknown, init?: RequestInit) => {
+      const url = String(input);
+      const method = String(init?.method ?? 'GET').toUpperCase();
+      if (url === '/api/harnesses') {
+        return jsonResponse([{ id: 'pi', displayName: 'Pi', capabilities: [] }]);
+      }
+      if (url.startsWith('/api/harnesses/') && url.endsWith('/catalog')) {
+        return jsonResponse(COLLIDING_CATALOG);
+      }
+      if (url === '/api/chat/preferences/selection' && method === 'GET') {
+        return jsonResponse({ selection: null });
+      }
+      if (url === '/api/chat/preferences/selection' && method === 'PUT') {
+        return jsonResponse({ selection: JSON.parse(String(init?.body)) });
+      }
+      return new Response('not found', { status: 404 });
+    }) as unknown as typeof fetch;
+
+    await remountWithFetch(collidingFetch);
+
+    const harnessSelect = container.querySelector(
+      'select[aria-label="Harness"]',
+    ) as HTMLSelectElement;
+    await act(async () => {
+      selectValue(harnessSelect, 'pi');
+    });
+    await flushAsync();
+
+    const providerSelect = container.querySelector(
+      'select[aria-label="Provider"]',
+    ) as HTMLSelectElement;
+    await act(async () => {
+      selectValue(providerSelect, 'alpha');
+    });
+
+    const modelSelect = container.querySelector('select[aria-label="Model"]') as HTMLSelectElement;
+    // The colliding modelId is provider-qualified in the option value, never a
+    // bare id, so the two providers' 'gpt-x' rows are uniquely identifiable.
+    const optionValues = [...modelSelect.options].map((o) => o.value).filter((v) => v !== '');
+    expect(optionValues).toEqual(['alpha:gpt-x']);
+
+    await act(async () => {
+      selectValue(modelSelect, 'alpha:gpt-x');
+    });
+    await flushAsync();
+
+    // The controlled select highlights the alpha row via the composite identity.
+    expect(modelSelect.value).toBe('alpha:gpt-x');
+
+    const textarea = container.querySelector(
+      'textarea[aria-label="Message"]',
+    ) as HTMLTextAreaElement;
+    await act(async () => {
+      setValue(textarea, 'ping');
+    });
+    await act(async () => {
+      textarea.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+    });
+
+    // The persisted/sent tuple resolves to provider alpha — NOT beta — even
+    // though the bare modelId 'gpt-x' exists under both providers.
+    expect(fake.emitted).toContainEqual({
+      event: 'message',
+      payload: {
+        conversationId: undefined,
+        content: 'ping',
+        provider: 'alpha',
+        modelId: 'gpt-x',
+      },
+    });
+  });
+
   it('removes socket handlers and tears down the socket on unmount, with no network calls', async () => {
     expect(fake.listeners.size).toBeGreaterThan(0);
 

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

@@ -6,6 +6,7 @@ import { asFiniteNumberOrNull, asString } from '@/spa/chat/runtime-guards';
 import { SessionPanel } from '@/spa/chat/session-panel';
 import { ToolCallList } from '@/spa/chat/tool-call-list';
 import { useChatConnection } from '@/spa/chat/use-chat-connection';
+import { useHarnessSelection } from '@/spa/chat/use-harness-selection';
 
 /** Renders a real value normally, but an honest "unavailable" label instead
  * of a fabricated `0` for a missing/malformed count — a real `0 tokens` and
@@ -23,6 +24,7 @@ function formatCost(value: unknown): string {
 
 export function ChatPage(): ReactElement {
   const { state, actions } = useChatConnection();
+  const harness = useHarnessSelection();
   const hasConversation = state.conversationId !== null;
 
   return (
@@ -86,6 +88,7 @@ export function ChatPage(): ReactElement {
         streaming={state.streaming}
         sending={state.sending}
         hasConversation={hasConversation}
+        harness={harness}
       />
     </div>
   );

docs/PRD.md

@@ -1,5 +1,14 @@
 # PRD: Mosaic Stack v0.1.0
 
+## Current addendum: #1194 — Installed framework-tool drift detection
+
+- Compare the framework tools shipped with the executing Mosaic package against the deployed `$MOSAIC_HOME/tools` tree by content hash.
+- Treat every shipped `tools/**` file as framework-owned/required according to `framework-manifest.txt`, while excluding the explicit operator-owned credential carve-out and preserving installed-only operator/unknown files.
+- Distinguish and count `IN_SYNC`, `STALE`, `NOT_INSTALLED`, and installed-only classifications; fail non-zero when shipped tools are stale or absent and refuse self-comparison that would make drift unobservable.
+- Surface the observational check through `mosaic doctor`; do not refresh files, restart seats, or mutate live tooling.
+- Document identity/messaging/gate behavior changes in the current stale set, the reviewed quiet-window keep-mode refresh command, and post-refresh probes against the installed path.
+- Prove by construction that a stale and missing deployed tool are detected; that regression must fail before this checker exists.
+
 ## Metadata
 
 - **Owner:** Jason Woltje
@@ -102,6 +111,128 @@ Context compaction, session replacement, and same-PID runtime reloads can leave
 
 ---
 
+## Pi Persistent Goal Loop (#1150)
+
+### Problem and objective
+
+A Pi agent can stop after a plausible-looking answer even when the operator's broader objective is
+not complete, and ordinary compaction can weaken or omit the original objective. Mosaic needs an
+optional, operator-controlled goal loop that keeps a Pi session oriented, checks progress at native
+lifecycle boundaries, and resumes work until completion is verified or a bounded safety state is
+reached.
+
+The objective is a Mosaic-owned Pi extension deployed from the framework into
+`~/.config/mosaic/runtime/pi/`. It must not install into or depend on `~/.pi/agent/extensions/`.
+
+### Scope
+
+#### In scope
+
+1. `PGL-REQ-01`: The framework SHALL ship a dedicated Pi goal extension under
+   `packages/mosaic/framework/runtime/pi/`, seed it under `$MOSAIC_HOME/runtime/pi/`, and make
+   `mosaic pi` load it alongside the core Mosaic extension when present.
+2. `PGL-REQ-02`: `/goal` SHALL support setting a goal plus status, pause, resume, cancel, and help
+   operations without silently replacing an active goal.
+3. `PGL-REQ-03`: Active branch-specific goal state SHALL be persisted in Pi custom session entries,
+   restored on session start and tree navigation, and never rely on a compaction summary as its
+   source of truth.
+4. `PGL-REQ-04`: A hidden goal contract SHALL be injected through Pi's `context` event before every
+   model request so it remains effective across tool turns, retries, and post-compaction requests.
+5. `PGL-REQ-05`: The harness SHALL inspect every `turn_end` and successful `session_compact` event.
+   A structured terminating goal-report tool SHALL capture `continue`, evidence-bearing `achieved`,
+   or `blocked` status without requiring a redundant model turn.
+6. `PGL-REQ-06`: An achievement claim SHALL remain provisional until a second consecutive
+   evidence-bearing verification report. Any continuation report or successful compaction during
+   verification SHALL reset the verification sequence.
+7. `PGL-REQ-07`: Continuation SHALL be initiated at safe lifecycle boundaries, primarily
+   `agent_settled`; manual compaction and restored active sessions may schedule a deferred idle
+   continuation without re-entering compaction handlers.
+8. `PGL-REQ-08`: The loop SHALL have operator cancellation plus bounded turn and repeated-no-progress
+   limits. Exhausted or blocked goals pause rather than continuing indefinitely.
+9. `PGL-REQ-09`: Framework installation and update SHALL preserve normal manifest ownership: the
+   goal extension is framework-owned under `runtime/**`, while no goal extension or configuration
+   asset is created or modified under the operator's main Pi configuration. Pi remains the owner of
+   its native session files used by `appendEntry()`.
+
+#### Out of scope
+
+1. A mathematical guarantee that an arbitrary natural-language goal is semantically complete.
+2. Automatically executing user-supplied shell predicates or accepting executable validation code in
+   `/goal` arguments.
+3. Restarting Pi after process, host, or supervisor failure; the existing Mosaic fleet/runtime
+   supervisor owns process durability.
+4. Gateway, database, web UI, Discord, or cross-harness goal orchestration in this slice.
+
+### User and stakeholder requirements
+
+- An operator can start a goal from Pi and see its current phase, evidence, limits, and latest report.
+- The agent remains oriented after each turn and compaction until verified, paused, blocked,
+  exhausted, or cancelled.
+- Local testing uses a file under `~/.config/mosaic/runtime/pi/`; the feature never writes an
+  extension asset to `~/.pi/agent/extensions/`.
+- Framework updates deploy the same reviewed extension source through Mosaic's existing manifest
+  sync path.
+
+### Non-functional requirements
+
+1. **Safety:** bounded continuation, explicit cancellation, no arbitrary command execution, and no
+   completion without non-empty reported evidence.
+2. **Reliability:** serialized continuation scheduling, branch-aware restoration, compaction-safe
+   context injection, and stale-timer cancellation on session shutdown.
+3. **Performance:** no extra nested judge-model request on every turn; structured reporting uses the
+   active agent's final terminating tool call.
+4. **Observability:** Pi status/notifications expose phase and bounded counters without recording
+   credentials or hidden model reasoning.
+5. **Maintainability:** the state machine is deterministic and behavior-tested independently from Pi
+   provider/network access.
+
+### Acceptance criteria
+
+1. `AC-PGL-01`: A framework-sync fixture installs the extension at
+   `$MOSAIC_HOME/runtime/pi/goal-extension.ts`, and launcher tests prove both Mosaic Pi extensions are
+   emitted in deterministic order while absent optional files remain backward-compatible.
+2. `AC-PGL-02`: Command tests prove set/status/pause/resume/cancel behavior, active-goal replacement
+   refusal, and bounded input handling.
+3. `AC-PGL-03`: Lifecycle tests prove every turn is recorded, active context is injected on every
+   request, two evidence-bearing achievement reports are required, and `agent_settled` continues an
+   unmet goal without duplicate scheduling.
+4. `AC-PGL-04`: Compaction and restoration tests prove goal state survives, verification is reset and
+   rechecked after compaction, manual compaction continuation is deferred until idle, and tree/session
+   branch state is reconstructed correctly.
+5. `AC-PGL-05`: Limit tests prove max-turn and repeated-no-progress exhaustion stop autonomous
+   continuation, while pause/cancel/blocked states do not restart.
+6. `AC-PGL-06`: Focused tests, package typecheck/lint/test, repository quality gates, a local Pi load
+   smoke test from `~/.config/mosaic/runtime/pi/`, independent review, and terminal-green CI pass before
+   issue #1150 closes.
+
+### Constraints, risks, and assumptions
+
+- Dependency: Pi's extension API must continue to provide `registerCommand`, `registerTool`,
+  `context`, `turn_end`, `agent_settled`, `session_compact`, session custom entries, and terminating
+  tool results.
+- Risk: the working agent can overstate completion. Mitigation: structured evidence, a mandatory
+  second verification pass, explicit semantic limitations, and operator-visible reports.
+- Risk: an impossible goal can consume unbounded resources. Mitigation: hard turn/no-progress bounds
+  and paused terminal states.
+- Risk: automatic continuation can race compaction or session replacement. Mitigation: drive from
+  `agent_settled`, defer idle restarts, generation-check timers, and clear timers on shutdown.
+- `ASSUMPTION:` Two consecutive evidence-bearing reports are the initial local verification policy;
+  rationale: it provides a real recheck without doubling every turn's model cost. Future policy may
+  add independent or deterministic validators.
+- `ASSUMPTION:` Default limits are 40 turns and 6 repeated no-progress reports, configurable only by
+  bounded Mosaic environment settings; rationale: useful persistence with a finite autonomous budget.
+- `ASSUMPTION:` Documentation remains canonical in-repo for this slice; no external docs publication
+  is requested.
+
+### Testing and delivery intent
+
+Use TDD for the deterministic controller and lifecycle invariants. Test with fake Pi lifecycle
+objects first, then run a local load/smoke test from the deployed Mosaic path. Deliver source, tests,
+launcher wiring, framework/runtime documentation, user/developer guides, and sitemap updates in one
+reviewed squash PR to `main` with terminal-green CI.
+
+---
+
 ## Fleet Declarative Configuration Management Workstream (FCM, #758)
 
 ### Problem and objective
@@ -146,6 +277,68 @@ lands. M0 consists only of these normative requirements, the complete task DAG,
 documentation IA checklist, and the legacy example/profile disposition inventory. Subsequent cards
 are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
 
+### Fleet git identity launch propagation (#1043)
+
+#### Problem and objective
+
+A fleet seat can have a registered per-agent Git credential while its launched runtime process lacks
+`MOSAIC_GIT_IDENTITY`. The credential resolver then cannot select the seat identity reliably, which
+blocks repository operations on fail-closed estates and can fall through to an unrelated identity on
+estates where that refusal is not active. The objective is to make Git identity a deterministic,
+roster-derived part of the generated launch projection and prove it reaches the launched process.
+
+#### Normative requirements
+
+1. `FGI-REQ-01`: Every generated fleet agent projection SHALL declare
+   `MOSAIC_GIT_IDENTITY=<MOSAIC_AGENT_NAME>`; a differing or unsafe identity SHALL fail closed before
+   tmux launch.
+2. `FGI-REQ-02`: The clean `/usr/bin/env -i` pane boundary SHALL pass every variable declared by the
+   generated projection, including `MOSAIC_GIT_IDENTITY`, to the launched runtime process.
+3. `FGI-REQ-03`: A behavioral integration test SHALL set-compare the complete generated projection
+   against the launched process environment. Source-text/string-presence assertions are insufficient.
+4. `FGI-REQ-04`: Verification SHALL include RED-first evidence and a delete-the-subject mutation that
+   removes Git-identity pane propagation and makes the behavioral test fail.
+
+#### Acceptance criteria
+
+1. `AC-FGI-01`: A launched seat process contains every key/value pair declared by its generated
+   environment projection, including the roster-derived Git identity.
+2. `AC-FGI-02`: Missing, unsafe, or split Git identity is rejected before a tmux session is created.
+3. `AC-FGI-03`: Focused launcher and generated-environment tests, repository quality gates,
+   independent review, and the required RED/green/R7 evidence are recorded before push.
+
+### Framework shell assertion portability (#1098)
+
+#### Problem and objective
+
+The blocking framework-shell chain can report that a pane command omitted `/usr/bin/env -i` even when
+`-i` matched successfully. A short-circuiting `grep -q` under `set -o pipefail` may close its pipe after
+the match and cause an upstream producer to exit with SIGPIPE, turning a valid semantic result into a
+nonzero aggregate pipeline. The objective is to inspect the captured NUL-delimited argv directly and
+make failures carry the observed records needed for diagnosis.
+
+#### Normative requirements
+
+1. `FSP-REQ-01`: The pane-boundary test SHALL validate an adjacent `/usr/bin/env`, `-i` argv pair from
+   the authoritative NUL-delimited tmux capture without a short-circuit pipeline whose upstream status
+   can override a successful match.
+2. `FSP-REQ-02`: Missing, reversed, or non-adjacent boundary tokens SHALL fail, while valid boundaries
+   SHALL remain valid regardless of trailing argv size, pipe capacity, process scheduling, or host/CI
+   utility implementation.
+3. `FSP-REQ-03`: A failed boundary check SHALL print stable indexed, shell-escaped observed argv records
+   before exiting nonzero; the fixture SHALL continue to contain generated non-secret launch data only.
+4. `FSP-REQ-04`: Verification SHALL include RED-first large-payload evidence, negative token-order
+   controls, the complete focused launcher suite, canonical Woodpecker CI, and independent review.
+
+#### Acceptance criteria
+
+1. `AC-FSP-01`: A large captured argv with adjacent `/usr/bin/env`, `-i` passes even when the former
+   `grep -q` pipeline returns nonzero from an upstream SIGPIPE.
+2. `AC-FSP-02`: Missing executable, missing flag, and detached/reversed flag fixtures return nonzero and
+   emit the indexed observed argv.
+3. `AC-FSP-03`: The focused suite passes on the development host and CI image, and the merged-main
+   Woodpecker pipeline is terminal green before #1098 closes.
+
 ---
 
 ## Exact Cross-Harness Fleet Communications Contract (#766)
@@ -1345,6 +1538,59 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
 
 ---
 
+## Workspace placement guard hardening (#1174)
+
+### Problem and objective
+
+The Bash pre-tool guard must prevent Git checkouts and repository state from being placed under
+`$HOME` without refusing ordinary Git commands merely because a source, option value, branch name,
+or metadata mentions `$HOME`. A guard that over-blocks routine work is unsafe because operators
+will route around it.
+
+### Scope and requirements
+
+1. `WPG-REQ-01`: `git clone` and `git worktree add` placement SHALL be judged from their placement
+   operands, not from every HOME-shaped word in the command.
+2. `WPG-REQ-02`: Clone sources, references, templates, environment assignments, and non-placement
+   worktree metadata MAY resolve under HOME when all placement operands resolve elsewhere.
+3. `WPG-REQ-03`: Both attached and separate-value `--separate-git-dir` forms SHALL remain placement
+   operands and SHALL be refused when they resolve under HOME.
+4. `WPG-REQ-04`: Option classification SHALL account for Git's rule-generated boolean negations
+   without relying on an enumerable allowlist of flag spellings.
+5. `WPG-REQ-05`: Quote removal, escapes, shell command boundaries, redirections, and end-of-options
+   handling SHALL preserve existing fail-closed checkout coverage.
+6. `WPG-REQ-06`: Absolute placement aliases SHALL resolve shell-known HOME spellings, dot segments,
+   repeated separators, and existing symlink parents before the HOME boundary comparison.
+7. Relative targets whose effective path depends on the shell cwd are out of scope and tracked by
+   #1197.
+
+### Acceptance and verification
+
+1. Git's own option parser accepts each tested flag, including generated `--no-*` forms, while the
+   guard allows a HOME-valued source with an explicit safe destination.
+2. Equivalent clone and worktree fixtures cover rule-generated negations and remain discriminating
+   against the prior head where the defect existed.
+3. Real HOME destinations and both `--separate-git-dir` forms remain blocked, including placements
+   after shell command boundaries.
+4. The full hermetic guard suite, syntax/static checks, adversarial probes, independent review, and
+   terminal-green CI pass before merge.
+5. Any option-classification residual is documented with its deliberate failure direction.
+
+### Constraints, risks, and assumptions
+
+- Security and usability are co-equal: neither a placement bypass nor routine over-block is an
+  acceptable repair.
+- `ASSUMPTION:` The value-taking option surface exposed by the installed Git version is closed and
+  measurable through Git's own parser/help output; rationale: boolean flags are rule-generated,
+  while separate-value options have explicit grammar and must be classified as such.
+- Risk: a future Git release may add a new value-taking placement option. Mitigation: document the
+  chosen residual direction and pin every currently supported placement option in behavior tests.
+- Risk: a symlink can be replaced after pre-execution canonicalization. Mitigation: resolve every
+  existing parent physically and document the remaining inherent TOCTOU window; the worktree helper
+  remains the authoritative path-derivation mechanism, with atomic closure tracked by #1199.
+
+---
+
 ## Assumptions
 
 1. RESOLVED: **pgvector is sufficient** for semantic search at v0.1.0 scale (personal/family/team = thousands to low hundreds-of-thousands of vectors). `@mosaicstack/memory` defines a `VectorStore` interface with pgvector as the default adapter. The interface boundary makes Qdrant a drop-in migration if PG resource contention or scale demands it later. Zero additional infrastructure for v0.1.0. Rationale: Reduces ops burden; pgvector HNSW indexes are fast at this scale; interface abstraction costs almost nothing now.

docs/SITEMAP.md

@@ -14,6 +14,13 @@
 - [Skill registration user guide](guides/user-guide.md#claude-code-skill-registration) — register, unregister, list statuses, automatic install/update reconciliation, and Claude reload behavior.
 - [Skill bridge developer guide](guides/dev-guide.md#claude-code-skill-bridge) — path-validation, ownership, clobber-protection, install/update wiring, tests, and Pi/Codex scope notes.
 
+## Pi persistent goals
+
+- [Persistent goal user guide](guides/user-guide.md#pi-persistent-goals) — `/goal` commands, verification behavior, limits, compaction/resume semantics, and limitations.
+- [Goal extension developer guide](guides/dev-guide.md#pi-persistent-goal-extension) — framework ownership, launcher ordering, lifecycle design, tests, and local Mosaic-path smoke workflow.
+- [Goal loop operations](guides/admin-guide.md#pi-goal-loop-operations) — deployment ownership, bounded settings, pause/resume procedures, and supervisor boundary.
+- [Pi runtime reference](../packages/mosaic/framework/runtime/pi/RUNTIME.md#extensions) — deployed paths, command summary, and bounded environment settings.
+
 ## Fleet configuration management
 
 - [Fleet configuration entry point](fleet/README.md) — desired-versus-observed decision tree and complete operator link map.

docs/fleet/FLEET-LAUNCH.md

@@ -5,14 +5,14 @@ Generated environment files are rebuildable projections, not an operator-editabl
 
 ## Launch chain
 
-| 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.                          |
-| 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.             |
+| Layer               | Responsibility                                                                                                                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket; Git identity is derived from the exact agent name. |
+| 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.                                                                |
 
 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,
@@ -24,6 +24,7 @@ secret-like key names, duplicate keys, comments, quoted/export syntax, and unsaf
 
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
+MOSAIC_GIT_IDENTITY=<roster name>
 MOSAIC_AGENT_CLASS=<roster class>
 MOSAIC_AGENT_RUNTIME=<roster runtime>
 MOSAIC_AGENT_MODEL=<roster model hint>
@@ -33,8 +34,10 @@ 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
-rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
+`MOSAIC_GIT_IDENTITY` is not independently configurable: it must equal `MOSAIC_AGENT_NAME`, preventing
+split runtime and repository identity authority. 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.
 

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

@@ -3,11 +3,12 @@
 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.
+2. Render deterministic <name>.env.generated data from that roster, including `MOSAIC_GIT_IDENTITY` derived exactly from the roster agent name.
 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.
+5. Reject a Git identity that is unsafe or differs from the generated agent name.
+6. Derive the runtime command from validated runtime/model/reasoning data and pass every generated projection entry through the clean process environment boundary.
+7. Target only the exact configured tmux socket and roster session after ownership checks.
 
 ## File precedence and ownership
 

docs/fleet/reference/generated-env-boundary.md

@@ -35,6 +35,7 @@ values, credential material, or command text.
 
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
+MOSAIC_GIT_IDENTITY=<roster name>
 MOSAIC_AGENT_CLASS=<roster class>
 MOSAIC_AGENT_RUNTIME=<roster runtime>
 MOSAIC_AGENT_MODEL=<roster model hint>
@@ -44,8 +45,9 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
 
-The generated launch contract supports only `claude`, `codex`, `opencode`, and `pi`. fleet add
-uses that same runtime authority and rejects any other runtime before it writes the roster or changes
+`MOSAIC_GIT_IDENTITY` is derived from and must equal `MOSAIC_AGENT_NAME`; it is not a separate
+operator-controlled identity authority. The generated launch contract supports only `claude`, `codex`,
+`opencode`, and `pi`. fleet add uses that same runtime authority and rejects any other runtime before it writes the roster or changes
 projection, local, or quarantine files. The legacy dogfood stub on its separate `mosaic-factory`
 socket remains an observability canary; it has no generated-launch adapter and cannot be added through
 this projection path.

docs/guides/admin-guide.md

@@ -7,7 +7,8 @@
 3. [Provider Configuration](#provider-configuration)
 4. [MCP Server Configuration](#mcp-server-configuration)
 5. [Environment Variables Reference](#environment-variables-reference)
-6. [Local Fleet Canary](./fleet-local-canary.md)
+6. [Pi Goal Loop Operations](#pi-goal-loop-operations)
+7. [Local Fleet Canary](./fleet-local-canary.md)
 
 ---
 
@@ -264,6 +265,16 @@ Each OIDC provider requires its client ID, client secret, and issuer URL togethe
 | `AGENT_SYSTEM_PROMPT`    | —               | Platform-level system prompt injected into all sessions |
 | `AGENT_USER_TOOLS`       | all tools       | Comma-separated allowlist of tools for non-admin users  |
 
+### Mosaic Pi goal loop
+
+| Variable                      | Default | Description                                                          |
+| ----------------------------- | ------- | -------------------------------------------------------------------- |
+| `MOSAIC_GOAL_MAX_TURNS`       | `40`    | Per-goal autonomous turn limit; accepted range `1..500`              |
+| `MOSAIC_GOAL_MAX_NO_PROGRESS` | `6`     | Consecutive identical progress-report limit; accepted range `1..100` |
+
+These variables are consumed by the framework-owned Pi goal extension at goal creation. Invalid or
+out-of-range values fall back to the defaults; they do not disable the bounds.
+
 ### Providers
 
 | Variable                  | Default                      | Description                                      |
@@ -374,3 +385,29 @@ Session cleanup is scoped to one session identifier and only removes that sessio
 | Variable                | Default                       | Description                                |
 | ----------------------- | ----------------------------- | ------------------------------------------ |
 | `MOSAIC_WORKSPACE_ROOT` | monorepo root (auto-detected) | Root path for mission workspace operations |
+
+---
+
+## Pi Goal Loop Operations
+
+The reviewed runtime asset is deployed at
+`~/.config/mosaic/runtime/pi/goal-extension.ts` by framework install/update. Do not install another
+copy under `~/.pi/agent/extensions/`; duplicate registration can create suffixed commands and two
+competing lifecycle controllers.
+
+Operational checks:
+
+1. Run `mosaic pi` and verify `/goal help` is available.
+2. Use `/goal status` to inspect phase, turn/no-progress limits, compaction checks, and evidence.
+   Reports persist in Pi session data; controller-owned state redacts common credential shapes, but
+   Pi's model/tool-call history is separate. Operators must not place secrets or raw sensitive output
+   in goals, pause reasons, or evidence.
+3. Use `/goal pause <reason>` before planned maintenance or manual investigation. Pause and cancel
+   abort the current goal-driven run when Pi is busy.
+4. Use `/goal resume` only after addressing a blocker; counters restart with the configured bounds.
+5. Use `/goal cancel` before replacing an unfinished goal.
+
+A blocked or exhausted goal remains stopped and visible; Mosaic does not automatically raise its
+limits or restart the process. Framework sync owns file deployment, while Pi's native session file
+owns branch replay. Process/host restart remains the responsibility of the existing runtime or fleet
+supervisor.

docs/guides/dev-guide.md

@@ -9,8 +9,9 @@
 5. [Adding New MCP Tools](#adding-new-mcp-tools)
 6. [Database Schema and Migrations](#database-schema-and-migrations)
 7. [Claude Code Skill Bridge](#claude-code-skill-bridge)
-8. [API Endpoint Reference](#api-endpoint-reference)
-9. [Local Fleet Canary](./fleet-local-canary.md)
+8. [Pi Persistent Goal Extension](#pi-persistent-goal-extension)
+9. [API Endpoint Reference](#api-endpoint-reference)
+10. [Local Fleet Canary](./fleet-local-canary.md)
 
 ---
 
@@ -396,6 +397,85 @@ M1 intentionally manages Claude Code only. Pi's Mosaic launcher can discover the
 canonical root directly. Codex still relies on the existing full skill-sync
 linker and needs separate parity analysis before this lifecycle API is extended.
 
+## Pi Persistent Goal Extension
+
+The source of the Mosaic-owned Pi goal controller is:
+
+```text
+packages/mosaic/framework/runtime/pi/goal-extension.ts
+```
+
+The framework manifest classifies `runtime/**` as framework-owned. Both the bash installer and the
+TypeScript file adapter therefore deploy the same reviewed source to:
+
+```text
+$MOSAIC_HOME/runtime/pi/goal-extension.ts
+# default: ~/.config/mosaic/runtime/pi/goal-extension.ts
+```
+
+Do not copy or link this extension into `~/.pi/agent/extensions/`. The launcher function
+`discoverPiExtensionArgs()` emits the core `mosaic-extension.ts` first and the optional
+`goal-extension.ts` second, preserving compatibility with an older installed framework that does
+not have the goal file yet.
+
+### Lifecycle design
+
+| Pi API                         | Goal-controller responsibility                                                    |
+| ------------------------------ | --------------------------------------------------------------------------------- |
+| `registerCommand('goal')`      | Set, inspect, pause, resume, or cancel one branch-specific goal                   |
+| `registerTool(...)`            | Record a terminating structured progress report with evidence                     |
+| `context`                      | Inject the active goal contract before every provider request                     |
+| `turn_end`                     | Record every turn, reject mixed final reports, and enforce the turn bound         |
+| `agent_settled`                | Start one deduplicated continuation only after Pi has no retry/compact/queue work |
+| `session_compact`              | Record the compact check, reset provisional verification, and defer idle work     |
+| `session_start`/`session_tree` | Rebuild state from custom entries on the active branch                            |
+| `session_shutdown`             | Invalidate deferred callbacks and clear UI state                                  |
+
+State is appended as `mosaic-goal-state` custom entries, which do not enter model context. The
+`context` hook creates a fresh hidden `mosaic-goal-context` message for each request instead of
+trusting compaction summaries. The `mosaic_goal_report` result uses `terminate: true`; when it is the
+sole final tool call, Pi avoids an unnecessary model response before the controller decides whether
+to verify, continue, or stop.
+
+Before state is appended or displayed, the controller applies bounded credential-pattern redaction
+to the goal statement, report summary/evidence/next step, and stop reason. Fingerprints are computed
+over redacted report content. Pi session entries are append-only, so a credential-bearing legacy
+entry cannot honestly be erased by the extension: restoration fails closed, emits a warning, and
+requires removal of the affected session before setting a new goal. This is defense-in-depth rather
+than a secret-storage contract, and it does not rewrite Pi's separate model-message/tool-call
+history. Goal prompts tell the agent not to submit credentials or raw sensitive output, and tests use
+canaries to prove known forms do not reach new custom entries, status text, context, or tool details
+while ordinary typed fields such as `token: string` remain intact.
+
+Completion remains evidence-gated but semantic: two consecutive `achieved` reports are required,
+and the second run is explicitly a verification pass. This avoids an extra judge-model request after
+every turn. Deterministic validator commands are intentionally not accepted as `/goal` input in this
+slice, so never describe this mechanism as proof of arbitrary natural-language completion.
+
+### Tests and local smoke workflow
+
+```bash
+pnpm --filter @mosaicstack/mosaic exec vitest run \
+  src/runtime/pi-goal-extension.spec.ts \
+  src/commands/launch.spec.ts \
+  src/config/file-adapter.test.ts
+
+bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
+```
+
+For an additive local smoke test without reseeding unrelated live framework files:
+
+```bash
+install -D -m 0644 \
+  packages/mosaic/framework/runtime/pi/goal-extension.ts \
+  ~/.config/mosaic/runtime/pi/goal-extension.ts
+
+pi --extension ~/.config/mosaic/runtime/pi/goal-extension.ts
+```
+
+Use `/goal help`, `/goal set ...`, and `/goal status` in that test session. A released framework
+sync installs the file, and a released Mosaic CLI loads it automatically through `mosaic pi`.
+
 ## API Endpoint Reference
 
 All endpoints are served by the gateway at `http://localhost:14242` by default.

docs/guides/user-guide.md

@@ -8,9 +8,10 @@
 4. [Tasks](#tasks)
 5. [Settings](#settings)
 6. [CLI Usage](#cli-usage)
-7. [Sub-package Commands](#sub-package-commands)
-8. [Telemetry](#telemetry)
-9. [Local Fleet Canary](./fleet-local-canary.md)
+7. [Pi Persistent Goals](#pi-persistent-goals)
+8. [Sub-package Commands](#sub-package-commands)
+9. [Telemetry](#telemetry)
+10. [Local Fleet Canary](./fleet-local-canary.md)
 
 ---
 
@@ -317,6 +318,57 @@ mosaic prdy
 mosaic quality-rails
 ```
 
+## Pi Persistent Goals
+
+`mosaic pi` loads a Mosaic-owned goal extension from
+`~/.config/mosaic/runtime/pi/goal-extension.ts`. It is deliberately not installed in
+`~/.pi/agent/extensions/`; framework installation and updates manage it with the rest of the Mosaic
+runtime assets.
+
+Start Pi, then set a goal:
+
+```text
+/goal set Deliver the feature, tests, documentation, and verification evidence
+# Shorthand:
+/goal Deliver the feature, tests, documentation, and verification evidence
+```
+
+Control and inspect the loop with:
+
+| Command                | Behavior                                                           |
+| ---------------------- | ------------------------------------------------------------------ |
+| `/goal status`         | Show phase, limits, compaction checks, latest report, and evidence |
+| `/goal pause [reason]` | Stop autonomous continuation while preserving the goal             |
+| `/goal resume`         | Resume with fresh turn and no-progress counters                    |
+| `/goal cancel`         | Cancel the goal and remove its active status                       |
+| `/goal help`           | Show command help                                                  |
+
+While a goal is active, Mosaic injects its contract before every Pi model request and checks every
+completed model/tool turn. The agent ends each work cycle with the structured
+`mosaic_goal_report` tool. `achieved` is provisional until a second consecutive report rechecks the
+whole goal with evidence. A continuation report or a successful compaction resets provisional
+verification.
+
+Goal statements and reports are stored in Pi session data. Mosaic redacts common credential shapes
+before appending its goal-state entries and before goal tool output or `/goal status`, but
+pattern-based redaction is not a secret store. Pi's own model-message and tool-call records are
+outside that redactor. Never put tokens, passwords, private keys, connection strings, or raw
+sensitive output in a goal or report; cite the command, artifact, and pass/fail result instead.
+
+The loop stops instead of running forever when it is paused, blocked, cancelled, verified, reaches
+its turn limit, or repeats the same no-progress report too many times. Defaults are 40 turns and 6
+repeated no-progress reports. Operators may lower or raise them within enforced bounds before
+launching Pi:
+
+```bash
+MOSAIC_GOAL_MAX_TURNS=60 MOSAIC_GOAL_MAX_NO_PROGRESS=8 mosaic pi
+```
+
+Goal state is branch-specific Pi session data. It survives compaction and session resume, but Pi's
+process still must be relaunched or supervised after a process/host failure. This initial verifier
+checks structured evidence twice; it cannot mathematically prove every arbitrary natural-language
+goal. Use explicit acceptance criteria and inspect `/goal status` for consequential work.
+
 ---
 
 ### Claude Code Skill Registration

docs/reports/quality/1099-pipefail-sweep.md

@@ -0,0 +1,83 @@
+# #1099 pipefail + early-exit sweep
+
+Baseline: `df4c591ab42aa1ae62c12935fdc0e772684864a0`
+
+This is a site inventory, not a risk count. `FIXED` means the early-exiting consumer no longer has a piped upstream process whose SIGPIPE can become the result under `pipefail`. `NOT-LOAD-BEARING` means the pipeline status is explicitly discarded. `UNREACHABLE-AND-WHY` describes designed input, not a payload-size safety claim.
+
+## Tranche 1 — runtime and general scripts
+
+| Baseline site | Verdict | Construction / reason |
+| --- | --- | --- |
+| `tools/matrix-presence-harness/run.sh:38` | FIXED | nullglob array selects the first path; no pipeline |
+| `tools/e2e-install-test.sh:139` | FIXED | capture help completely, then grep via redirection |
+| `tools/install.sh:312` | FIXED | NUL `mapfile` reads all roots; count != 1 reaches the named malformed-archive diagnostic |
+| `scripts/analysis/reflect-board-history.sh:76` | FIXED | capture Git history completely, then grep via redirection |
+| `scripts/analysis/reflect-git-history.sh:67` | FIXED | grep reads from a here-string |
+| `scripts/analysis/reflect-git-history.sh:69` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/authentik/user-create.sh:72` | FIXED | jq `first(...)` reads the response directly |
+| `packages/mosaic/framework/tools/git/mutate-push-guard.sh:87` | FIXED | grep `-m1` reads the file directly; downstream `cut` consumes its complete scalar output |
+| `packages/mosaic/framework/tools/orchestrator/session-resume.sh:94` | FIXED | `mapfile` plus bounded indexed loop replaces `head` pipeline |
+| `packages/mosaic/framework/tools/prdy/prdy-status.sh:69` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:172` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:173` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:174` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:175` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:176` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:177` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:178` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/typecheck-hook.sh:16` | FIXED | Bash regex extracts the first field without a pipeline |
+| `packages/mosaic/framework/tools/qa/typecheck-hook.sh:56` | FIXED | grep and bounded sed each read from a here-string |
+| `packages/mosaic/framework/tools/tmux/send-message.sh:113` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/tmux/send-message.sh:124` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/wake/detector.sh:126` | FIXED | one awk reads the manifest directly and exits after the first exact key |
+| `packages/mosaic/framework/tools/wake/detector.sh:270` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/wake/detector.sh:278` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/wake/digest.sh:647` | FIXED | capture complete locator output, then select first line by parameter expansion |
+| `packages/mosaic/framework/tools/wake/reconcile.sh:149` | FIXED | one awk reads the manifest directly and exits after the first exact key |
+
+## Explicit withdrawn / non-load-bearing sites
+
+| Baseline site | Verdict | Reason |
+| --- | --- | --- |
+| `tools/install.sh:182` | NOT-LOAD-BEARING | `|| true` explicitly discards lookup status |
+| `tools/install.sh:356` | UNREACHABLE-AND-WHY | `pnpm pack` writes one matching CLI tarball into a fresh directory immediately before lookup; citation withdrawn in #1099 |
+| `tools/install.sh:357` | UNREACHABLE-AND-WHY | same fresh-directory invariant for gateway tarball; citation withdrawn in #1099 |
+| `tools/install.sh:627` | NOT-LOAD-BEARING | `|| true` explicitly discards lookup status |
+| `scripts/agent/session-start.sh:70` | NOT-LOAD-BEARING | optional scratchpad lookup has `|| true` |
+| `packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh:58` | NOT-LOAD-BEARING | optional scratchpad lookup has `|| true` |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:25` | UNREACHABLE-AND-WHY | withdrawn in #1099 after designed-input reachability measurement; preserved without re-litigation |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:27` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:30` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:32` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:34` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+
+## Tranche 2 — non-wake test harnesses
+
+All 22 baseline sites below are `FIXED`; the checked-in tranche fixture is passed through the same scanner and asserts all 22 occurrences and 21 normalized identities (the same response-split line occurs twice).
+
+| Baseline site(s) | Verdict | Construction |
+| --- | --- | --- |
+| `systemd/user/test-fleet-units.sh:148` | FIXED | capture tmux output, then grep via redirection |
+| `git/test-issue-comment-readback.sh:283,302` | FIXED | parameter expansion splits status/body without `head` |
+| `git/test-pr-review-gitea-comment.sh:228` | FIXED | parameter expansion splits status/body |
+| `git/test-lane-brief-pr-linkage.sh:72` | FIXED | grep reads from a here-string |
+| `git/test-pr-review-repo-host-override.sh:225-226` | FIXED | grep reads from a here-string |
+| `orchestrator/smoke-test.sh:67,72` | FIXED | parameter expansion selects first line |
+| `orchestrator/test-board-roll.sh:99-100` | FIXED | grep reads from a here-string |
+| `quality/scripts/test-upgrade-durable-snapshot.sh:180` | FIXED | complete sorted output is read with `mapfile`, then indexed |
+| `quality/scripts/test-upgrade-rollback.sh:339,356` | FIXED | direct `grep -m1` file reads; cleanup captures before testing |
+| `tmux/test-send-message-socket.sh:37,38,44-46,68,72` | FIXED | capture commands complete before redirected grep assertions |
+| `tmux/test-send-message-verdict.sh:34` | FIXED | grep reads from a here-string |
+
+## Tranche 3 — wake validation harnesses
+
+All 26 baseline occurrences (25 normalized identities; one preimage selector occurs twice) are `FIXED` and mechanically bound through the wake fixture and shared scanner.
+
+| Baseline site(s) | Verdict | Construction |
+| --- | --- | --- |
+| `wake/test-wake-digest-quarantine.sh:567` | FIXED | complete match populations are captured, then first line selected by parameter expansion |
+| `wake/test-wake-preimage.sh:182-183,346-347` | FIXED | jq `first(...)` reads each JSONL file directly |
+| `wake/validate-973/microtest-wake-assert.sh:153,170-171,176,204-209,233-234,251-252,286-287` | FIXED | scalar assertions use here-strings; diagnostics use non-early sed ranges; source line captured before matching |
+| `wake/validate-973/validate-973.sh:110,119,180,182,187` | FIXED | scalar assertions use here-strings; diagnostic truncation uses consuming sed ranges |
+
+The scoped inventory is complete: 26 runtime/general + 22 non-wake tests + 26 wake tests fixed; 11 explicitly withdrawn or non-load-bearing sites retain their documented verdicts.

docs/scratchpads/1019-zero-timeout-harness.md

@@ -0,0 +1,71 @@
+# #1019 — Zero-timeout queue-guard harness race
+
+- **Issue:** #1019 (parent status remains `believed-fixed, pending jarvis validation`; do not close)
+- **Branch:** `fix/1019-ci-queue-timeout-harness`
+- **Owner:** `be-coder-08`
+- **Base:** `origin/main` at `5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc`
+- **Charter:** `/home/hermes/agent-work/tl-mosaic/CHARTER-1019-HARNESS-FIX.md`
+
+## Objective
+
+Make `test-ci-queue-wait-tristate.sh` deterministic without changing any asserted outcome. Remove the indiscriminate zero-timeout race, require every status-classification case to prove the provider was observed, and prove the harness-controlled virtual clock is active.
+
+## Scope
+
+- In scope: `packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` only, plus this evidence scratchpad.
+- Out of scope: guard parsers, D2/D3 behavior, installer/reseed staleness, PR #1060, and issue closure.
+
+## Acceptance criteria
+
+1. RED deterministically reproduces deadline pre-emption before the provider call.
+2. Every case that intends status classification positively proves provider observation.
+3. Pending observes `pending` before deterministic virtual-time expiration.
+4. The virtual clock has a positive interception control; a broken-clock mutant makes the suite red.
+5. The exact CI-base image passes the final harness repeatedly with zero failures.
+6. Baseline gates, independent code/security review, exact-head CI, and coordinator-authorized squash merge pass.
+
+## Plan
+
+1. Add deterministic RED instrumentation for the known merge/provider-unreachable pre-emption.
+2. Replace global `-t 0` with a nonzero timeout interpreted under an event-driven virtual clock; stub sleep without wall waiting.
+3. Add provider-observation and virtual-clock positive controls without changing outcome assertions.
+4. Run focused shell checks, repeat in exact CI-base image, baseline gates, and independent reviews.
+5. Commit with both identity layers, queue-guard plus direct Woodpecker terminal-state verification, push, self-post PR, verify poster/head/CI, obtain coordinator merge authorization, then squash merge without closing #1019.
+
+## Budget
+
+- No explicit token cap supplied. Keep scope to one harness file and one scratchpad; stop/report at the charter's 60% context gate.
+
+## Evidence
+
+- RED, deterministic pre-provider expiry: `evidence/1019-harness-fix/red-pre-provider-expiry.log` — rc 1; merge/provider-unreachable got rc 124 instead of 75, omitted CANNOT_ASSERT, did not observe the status provider, and wrote no additional audit record (four named failures).
+- GREEN host focused harness: `evidence/1019-harness-fix/green-host.log` — rc 0, all outcome classes passed.
+- Load-bearing clock negative control: a temporary same-directory mutant replaced the virtual `date` body with `/bin/date`; `evidence/1019-harness-fix/red-clock-not-intercepted.log` — rc 1 with named `virtual clock interception did not run` failures. The mutant file was removed after the run.
+- Exact CI-base repeat: `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`, repository mounted read-only, harness work under container `/tmp`; `evidence/1019-harness-fix/ci-image-repeat/summary.log` — **100 pass / 0 fail / 100 total**.
+- Synchronization design: provider-status observation creates the event marker; virtual time is 1000 before the event and 1002 afterward. Pending alone reaches the stubbed no-op sleep and a post-observation deadline check. `-t 1` is uniquely load-bearing because removing it restores the 900-second default deadline at virtual time 1900, which 1002 does not cross. The numeric timeout is subject semantics under virtual time, not a wall-clock synchronization duration.
+
+## Review remediation — semantic timeout vs. liveness bound
+
+Security review found that virtual time remained at 1000 forever before provider observation and stubbed sleep never waited. A regression looping before the status endpoint—or blocking in the first provider call—therefore could prevent `run_guard` from returning, so the post-return provider assertion could never fire.
+
+**General rule:** A timeout usually serves two purposes: semantics and liveness. Removing wall time from semantic synchronization can silently remove the only independent hang bound. Preserve deterministic virtual time for subject semantics, but provide a separately implemented real-clock liveness watchdog and prove that watchdog fires.
+
+Remediation:
+
+- Every guard subject invocation is launched by absolute `/usr/bin/python3` in a new session. Python's internal monotonic `wait(timeout=...)` provides real-clock liveness independently of PATH; expiry kills the entire isolated process group, so neither PATH-front shims nor a blocked provider descendant can retain the capture pipe.
+- Watchdog expiry returns distinct harness rc 90 plus `FAIL HANG watchdog`, separate from subject timeout rc 124.
+- A first attempt using absolute `/usr/bin/timeout -s KILL` passed on GNU coreutils but failed in the exact Alpine CI-base image: BusyBox killed the immediate wrapper while the guard/provider descendants survived and retained the command-substitution pipe. The process-group kill is therefore required behavior, not portability polish.
+- A committed positive control hangs the branch-provider stub before the status endpoint. It must terminate through the watchdog, emit the hang-specific diagnostic, return rc 90, and prove the status provider was never reached.
+- RED before remediation: a temporary ordinary-success mutant hung before provider observation; only an external control could kill the suite (rc 137), and there was no internal hang-specific diagnostic (`red-watchdog-absent.log`).
+- The watchdog mutant/control is load-bearing: removing the internal watchdog leaves the control unable to produce its required rc 90 and diagnostic.
+
+Post-review evidence:
+
+- Host focused harness with process-group watchdog: rc 0 (`green-watchdog-process-group-host.log`).
+- Exact Alpine CI-base focused harness with process-group watchdog: rc 0 (`green-watchdog-ci-image.log`).
+- Hanging ordinary-success mutant: suite rc 1; success returned rc 90, emitted `FAIL HANG watchdog`, and loudly reported that provider/clock observation did not occur (`red-watchdog-fires.log`).
+- Removed-`-t 1` mutant: suite rc 1; pending was terminated by the watchdog instead of producing `ASSERTED_NOT_READY`, proving the explicit timeout is load-bearing (`red-timeout-argument-removed.log`).
+
+## 60% context hold
+
+Stopped before baseline/review/commit as required by the charter. Remaining: inspect final diff, shell/static/baseline gates, independent code/security review, remediation if any, identity-bound commit/trailer verification, mandatory queue guard plus direct terminal Woodpecker `mosaic` enumeration, push, self-posted PR/provider poster read-back, exact-head terminal-green CI, coordinator merge authorization, squash merge, main CI verification, and leave #1019 unclosed as `believed-fixed, pending jarvis validation`.

docs/scratchpads/1043-pane-git-identity.md

@@ -0,0 +1,229 @@
+# #1043 — Fleet pane git-identity propagation
+
+## Objective
+
+Ensure a fleet seat's launched runtime process receives its roster-derived `MOSAIC_GIT_IDENTITY`, and lock the complete generated-environment propagation boundary with an enumerated set comparison.
+
+## Tracking
+
+- External issue: `mosaicstack/stack#1043`
+- Branch: `fix/1043-pane-git-identity`
+- Coordinator: `tl-mosaic`
+- `docs/TASKS.md`: read-only by project worker contract; not modified.
+
+## Constraints
+
+- RED-first bug reproducer is mandatory.
+- R7 delete-the-subject mutation must turn the behavioral test red.
+- Assert launched-process environment, not source text.
+- One push only; do not poll CI after push.
+- Run the CI queue guard immediately before push and report its `state=` line as state, not evidence.
+- Do not modify a live host launcher or obtain/copy another credential.
+- Self-post the PR, verify provider attribution, then stop.
+- Final status wording: `believed-fixed, pending jarvis validation`.
+
+## Scope inventory
+
+Re-derived against `origin/main` at `85d2108e`:
+
+- Launch consumer: `packages/mosaic/framework/tools/fleet/start-agent-session.sh`
+- Behavioral launch test: `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
+- Generated-environment contract/parser: `packages/mosaic/src/fleet/generated-env-boundary.ts`
+- Roster projection producers:
+  - `packages/mosaic/src/commands/fleet.ts`
+  - `packages/mosaic/src/fleet/fleet-reconciler.ts`
+  - `packages/mosaic/src/fleet/fleet-agent-crud.ts`
+  - `packages/mosaic/src/fleet/v1-v2-migration.ts`
+- Contract and producer tests discovered by repository search.
+- Generated-environment operator/developer docs and their executable documentation contract test.
+
+Discrepancy sent to `tl-mosaic`: current main no longer contains the charter's `PANE_SHELL_SNIPPET`; #772 replaced it with an `/usr/bin/env -i` argv launch boundary, and current generated projections do not declare git identity. Code-read inventory is **NOT MEASURED** behavior.
+
+## Plan
+
+1. Add the process-environment set-comparison regression first and record RED.
+2. Add roster-derived `MOSAIC_GIT_IDENTITY=<agent name>` to the complete generated projection contract.
+3. Validate identity syntax and equality with `MOSAIC_AGENT_NAME`; pass it through the clean pane environment.
+4. Update affected projection tests and generated-environment docs.
+5. Run focused and baseline gates.
+6. Perform R7 by deleting the pane propagation entry, prove RED, restore, and prove GREEN.
+7. Run independent review, remediate, commit, queue guard, one push, self-post PR, verify provider attribution, and stop without CI polling.
+
+## Budget
+
+No explicit token cap was provided. Working cap: one narrow logical unit, no dependency installation unless existing tooling requires it, no unrelated refactor.
+
+## Evidence log
+
+### TDD and mutation evidence
+
+- RED-first, repository launcher: `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` exited 64 on pre-fix source with `code=unknown-key key=MOSAIC_GIT_IDENTITY`. The generated seat could not launch with the required declared identity.
+- GREEN: the same repository launcher test emitted `ok - start-agent-session generated environment boundary`.
+- R7 delete-the-subject: removed only `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"` from the repository launch array; the same test exited 1 with `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
+- R7 restoration: restored that launch entry; the same test returned green.
+- Launcher under test is explicitly `packages/mosaic/framework/tools/fleet/start-agent-session.sh` through the test's `$START`, **not** the stale installed host copy.
+
+### Situational and focused tests
+
+- Repository launcher boundary: green, including set comparison of all nine generated projection entries and fail-before-tmux cases for missing, unsafe, mismatched, and local-shadow Git identity.
+- Fleet systemd launcher integration: `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` — green.
+- Focused Mosaic Vitest set: 6 files, 311 tests — green.
+- `bash -n` on changed shell files — green.
+- `git diff --check` — green.
+
+### Baseline gates
+
+- `pnpm typecheck` — 45/45 tasks green.
+- `pnpm lint` — 25/25 tasks green.
+- `pnpm format:check` — green.
+- `pnpm test:checkout` — green.
+- Repository-wide Vitest under a hermetic current-version npm prefix: Mosaic 81/81 files and 1510/1510 tests green; other workspace test tasks shown green before the framework-shell phase.
+- Canonical `pnpm test` is not fully green on this host for unrelated environment-sensitive gates:
+  1. the first two runs exposed the globally installed Mosaic 0.0.48 update banner in three CLI smoke tests expecting empty stderr;
+  2. after isolating that global-version input, the framework wake assertion aborted at the known `#973` Bash `BASH_LINENO` convention check (exit 97; observed `[3 5]`, expected `[3 4]`).
+  No tests were weakened or bypassed; focused changed-surface tests are green. CI remains the canonical clean-environment result and is intentionally not polled after push per charter.
+
+### Independent review
+
+- Codex code review first pass: request changes for missing shell rejection-path coverage.
+- Remediation: added table-driven missing/unsafe/mismatch/local-shadow launcher cases, each asserting no tmux call.
+- Codex code re-review: **approve**, no findings, confidence 0.88.
+- Codex security review: risk `none`, no findings, confidence 0.97.
+
+### Acceptance criteria mapping
+
+| Acceptance criterion | Evidence |
+| --- | --- |
+| AC-FGI-01: launched process receives every generated key/value | Repository launcher process-environment `comm -23` set comparison; GREEN and R7 RED evidence above |
+| AC-FGI-02: missing, unsafe, or split identity fails before tmux | Table-driven shell cases plus TypeScript generated-boundary tests |
+| AC-FGI-03: focused/baseline/review evidence recorded | Commands and review outcomes above; host-sensitive full-suite limitations stated explicitly |
+
+### Documentation checklist
+
+- PRD updated with #1043 requirements and acceptance criteria.
+- Fleet launch runbook, generated-env concept, and generated-env reference updated.
+- No API/OpenAPI, sitemap, user publishing target, deployment, or external docs publication change applies.
+- `docs/TASKS.md` remains unmodified per its single-writer project contract.
+
+## Round 2 — PR #1073 review 97 remediation
+
+### Review blocker
+
+The launched-process suite was signed-excluded from CI enumeration. Manual GREEN/R7 evidence therefore did not prove a PR workflow could detect regression.
+
+### RED-first and canonical wiring
+
+1. Removed the suite's signed exclusion before adding a CI execution path.
+2. `check-test-enumeration.sh` went RED with exact `UNENUMERATED` output for `test-start-agent-session.sh`: population 49, enumerated 30, excluded 18.
+3. Added both `framework/tools/fleet/test-start-agent-session.sh` and `framework/systemd/user/test-fleet-units.sh` to `@mosaicstack/mosaic`'s canonical `test:framework-shell` chain.
+4. The guard returned GREEN: population 49, enumerated 32, excluded 18, surfaces 45. The systemd suite is outside the guard's tools-only population but now has the same explicit canonical execution disposition.
+
+### Workflow-level R7
+
+- Deleted only the pane launch entry `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"`.
+- Ran the exact `.woodpecker/ci.yml` test-step command, `pnpm test`, with only a temporary PATH-scoped npm shim reporting the checkout's current 0.0.49 version so the unrelated global 0.0.48 banner could not preempt the shell chain.
+- Result: exit 1 at `@mosaicstack/mosaic#test`, with the enumeration guard GREEN followed by `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
+- Restored the launch entry. The canonical `test:framework-shell` chain then reached both newly wired suites and printed both GREEN markers before the known unrelated #973 host-only `BASH_LINENO` abort.
+- An actual provider PR workflow on the intentionally broken mutant is **NOT MEASURED**: the one-push constraint forbids pushing a red mutant and then a repaired head. Local execution proves the exact PR workflow command and dependency chain go RED on the subject deletion; CI on the repaired pushed head remains canonical.
+
+### Workflow population
+
+- **DEFINED:** 3 workflows (`ci.yml`, `ci-image.yml`, `publish.yml`).
+- **ELIGIBLE for `pull_request`:** 1/3 (`ci.yml`), based on top-level `when:` clauses.
+- **REPORTED:** Round-1 exact-head provider read reported 1/1 eligible context (`ci/woodpecker/pr/ci`). Post-remediation-head reported count is **NOT MEASURED** by this seat because CI polling is prohibited; workflow definitions and eligibility did not change.
+
+### Independent remediation review
+
+- First Round-2 review identified a CI-image blocker: the newly wired launcher suite used Perl, which the Alpine CI base does not install.
+- Replaced the suite's three Perl-only fixture mutations with POSIX/BusyBox-compatible `sed -i` substitutions; production behavior and assertions are unchanged.
+- Codex re-review: **APPROVE**, confidence 0.93, no findings.
+
+### Vitest denominator reconciliation
+
+The PR's `311/311` is correct for its explicitly named six-file command at both the original and remediation worktrees:
+
+- generated environment boundary: 24
+- fleet documentation: 23
+- Tess service profile: 6
+- fleet regen command: 27
+- fleet agent CRUD command: 22
+- fleet command: 209
+- total: **311**
+
+Review 97 reported 312/312 without naming its six files. That is a different or miscounted population and cannot replace the command-scoped 311 denominator; the PR follow-up will name the exact files and arithmetic.
+
+## Round 3 — Alpine stale-marker portability
+
+### Objective and plan
+
+- Replace the GNU-only relative-date fixture with a deterministic POSIX/BusyBox timestamp while preserving the required stale-marker assertion.
+- Re-run the launcher suite in the canonical `ci-base:latest` Alpine image, then run applicable repository gates and independent review.
+- Update the PR body to name the repeated GNU-host/Alpine-CI portability pattern, run the mandatory queue guard, push once, verify provider attribution, and stop without CI polling.
+- Working budget: 8K tokens; scope is one fixture line plus delivery evidence. No production behavior changes.
+
+### RED-first evidence
+
+Before the fix, the canonical CI image command
+`docker run --rm -v "$PWD:/work" -w /work git.mosaicstack.dev/mosaicstack/stack/ci-base:latest bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
+exited 1 at the stale-marker setup with exact BusyBox output
+`touch: invalid date '10 seconds ago'`. The prior fresh-marker assertions had already executed, matching pipeline 2233's failure location.
+
+### Root cause and fix
+
+The test used GNU `touch -d` relative-date parsing although the PR workflow runs on Alpine/BusyBox. The fixture now uses POSIX `touch -t 200001010000.00`, a fixed timestamp that is unconditionally stale; the stale assertion remains mandatory and was not made tolerant of missing timestamp metadata.
+
+### Structural pattern
+
+This is the third GNU-host/Alpine-CI portability defect in the lane: GNU `grep` multi-match counting, Perl-only fixture mutation, and GNU `touch -d` date parsing. The repeated cause is shell suites authored on a GNU host but executed in an Alpine CI image; durable prevention belongs in CI-image execution or portability lint, not assertion weakening.
+
+### GREEN and quality evidence
+
+- Focused launcher suite in `ci-base:latest`: exit 0, `ok - start-agent-session generated environment boundary`.
+- Canonical test step in `ci-base:latest` with the pipeline's `pgvector/pgvector:pg17` service, readiness check, migration, and `pnpm test`: exit 0; 46/46 Turbo tasks; Mosaic 81/81 files and 1510/1510 tests; Gateway 57 passed/5 skipped files and 629 passed/11 skipped tests; enumeration 49 population / 32 enumerated / 18 signed exclusions / 45 named surfaces.
+- The first image-only `pnpm test` attempt lacked the pipeline PostgreSQL service and failed only on connection refusal after the launcher suite was GREEN. The rerun supplied the canonical service precondition and passed.
+- Canonical-image baseline: typecheck 45/45 tasks, lint 25/25 tasks, format check GREEN; `git diff --check` GREEN.
+- Independent Codex code review: APPROVE, confidence 0.96, 2/2 Round-3 files, no findings.
+- Independent Codex security review: risk none, confidence 0.99, 2/2 Round-3 files, no findings.
+
+### Re-derived inventory and denominators
+
+- Round-3 git delta: **2/2 files** — launcher suite and task scratchpad; 25 insertions / 1 deletion before evidence finalization.
+- Full PR path inventory against `origin/main` at `85d2108e`: **19/19 changed paths**; Round 3 adds no new PR path.
+- Workflow definition population: **1/3 pull-request-eligible** (`ci.yml` of `ci.yml`, `ci-image.yml`, `publish.yml`).
+- Do not re-litigate the settled 311/312 populations; both are valid for their separately named Tess6 and CRUD-core7 sets.
+
+## Round 4 — bound stale-marker observation
+
+### Objective and plan
+
+- Make the heartbeat assertion discriminate an initially stale native marker from a fresh marker without changing the production staleness threshold or shortening the polling window.
+- Freeze only the sidecar's numeric observation clock during the stale-fixture arm so elapsed assertion time cannot turn a fresh mutant stale.
+- Prove two independent mutants RED: disable production stale-marker detection while retaining the stale fixture; replace the stale fixture with a fresh marker. Restore the tree and prove GREEN in the canonical Alpine image.
+- Re-derive the changed-path inventory, run applicable quality and independent review gates, commit with environment-only author/committer identity, queue-guard, push once, verify provider attribution using curl stdin config, and stop without CI polling.
+- Working budget: 8K tokens. Scope is the launcher test and its scratchpad evidence; production launcher behavior remains unchanged.
+
+### Root cause and bounded observation
+
+The 30 × 0.1-second assertion window overlaps the production `now - marker > interval * 2 + 1` threshold at interval 1. Depending on second boundaries and load, a fresh marker can age past the threshold before the assertion ends. A focused pre-fix fresh-mutant attempt returned RED while Review 101's full-suite run returned GREEN; the differing result is itself timing dependence, not a discriminating assertion.
+
+The test now supplies a fixed numeric epoch only to the stale-fixture sidecar. Its real marker mtime is still read from the filesystem, but assertion runtime cannot advance `now`. Date formatting still delegates to the image's real `/bin/date`. Neither the production threshold nor the 30 × 0.1-second polling window changed.
+
+### Two-mutant RED / restored GREEN
+
+All three runs used `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`:
+
+1. **Stale-detection mutant RED:** replaced only the production stale-age predicate with `false` while retaining the fixed stale marker; suite exit 1 with `FAIL: heartbeat sidecar did not resume after native marker became stale or absent`.
+2. **Fresh-marker mutant RED:** replaced only `touch -t 200001010000.00` with fresh `touch`; suite exit 1 with the same failed stale-resumption assertion. The fixed observation epoch kept the mutant fresh throughout all 30 polls.
+3. **Restored tree GREEN:** suite exit 0 with `ok - start-agent-session generated environment boundary`.
+
+### Re-derived inventory
+
+- Round-4 delta: **2/2 files** — launcher test plus task scratchpad; production launcher delta is empty.
+- Full PR inventory against `origin/main`: **19/19 paths**; Round 4 adds no path.
+- Production stale threshold remains `now - marker > iv * 2 + 1`; assertion polling remains 30 × 0.1 seconds.
+- Review 101's confirmed enumeration/workflow/CI and attribution evidence is accepted without re-polling or re-derivation.
+
+## Residual risk
+
+- Landing on `main` does not update the currently installed host launcher. Host framework installation/reseed and Jarvis live-seat validation are separate downstream events.
+- Canonical CI result is pending and will not be polled by this seat.

docs/scratchpads/1098-framework-shell-portability.md

@@ -0,0 +1,97 @@
+# #1098 — Framework shell portability / red main
+
+## Objective
+
+Restore terminal-green `main` by making the `test-start-agent-session.sh` clean-environment assertion semantic and portable without removing either newly enumerated framework-shell suite.
+
+## Scope
+
+- Tracking issue: `mosaicstack/stack#1098`
+- Branch: `fix/framework-shell-portability`
+- Base: `origin/main` at `4fa2768962702d53e16e8b67ee6ad52ebcb0910e`
+- Primary file: `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
+- Requirements source: `docs/PRD.md` § Framework shell assertion portability (#1098)
+- Out of scope: deployed files under `~/.config/mosaic`, pnpm-store cleanup, checkout deletion, and changes to the launcher’s `/usr/bin/env -i` behavior.
+
+## Acceptance criteria
+
+1. The test inspects the captured NUL-delimited tmux argv semantically and accepts an adjacent `/usr/bin/env`, `-i` pair regardless of trailing payload size or pipe scheduling.
+2. Missing `/usr/bin/env`, missing `-i`, and non-adjacent `-i` remain failures.
+3. Failure output includes the observed argv records with stable indexes and shell escaping; it exposes no credentials because this fixture supplies only generated non-secret launch data.
+4. The focused suite passes on the dev host and in the repository CI image; the blocking PR/main pipeline returns terminal green.
+5. Independent review passes; PR is squash-merged and #1098 is closed only after merged-main CI is terminal green.
+
+## Budget
+
+- ASSUMPTION: 30K-token working budget; rationale: one shell-test defect plus full PR/CI lifecycle.
+- Auto-reduction: focused shell and package gates first; rely on canonical Woodpecker for the full monorepo suite rather than duplicating a dependency install under constrained `/home`.
+- Disk baseline before clone/build: `/home` 7.1G free (99% used), `/tmp` 2.4G free (92% used).
+
+## Investigation
+
+### First-hand CI evidence
+
+- Public log: `GET https://ci.mosaicstack.dev/api/repos/47/logs/2269/53041`
+- Decoded 1,436 entries (11 null `data` entries treated as empty log rows), 190,756 bytes.
+- Failure: `FAIL: pane command did not clear its environment` immediately after the expected pane-PID warning.
+- BusyBox primitives, complete assertion pipeline, real CI image, stale/current image digests, Turbo cache masking, gateway failure, and heartbeat-sidecar concurrent writing were independently excluded.
+
+### Root cause
+
+The assertion ends in:
+
+```bash
+printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i'
+```
+
+The script has `set -o pipefail`. `grep -q` exits as soon as it finds the valid `-i` record. Upstream `tail`/`printf` can then receive SIGPIPE, making the aggregate pipeline nonzero even though grep returned 0 and the semantic property is true. This depends on payload size, pipe capacity, and scheduling, explaining a local/image pass with a CI failure.
+
+Discriminating stress control with `/usr/bin/env` followed immediately by `-i`:
+
+- 8,192-byte trailing payload: `printf=0 tail=0 grep=0`, aggregate 0.
+- 16,384-byte trailing payload: `printf=0 tail=141 grep=0`, aggregate 141.
+- 32,768+ bytes: `printf=141 tail=141 grep=0`, aggregate 141.
+- A full-reading `grep -xF` control remained 0 for every payload.
+
+This is a third branch omitted by the earlier present-vs-corrupted split: the pair can be present and intact while `pipefail` reports an upstream SIGPIPE.
+
+## TDD plan
+
+1. RED: preserve the one-off stress reproducer above and add an automated large-argv semantic regression that fails under the current pipeline implementation.
+2. GREEN: parse the authoritative NUL-delimited capture into a Bash array and search for an adjacent `/usr/bin/env`, `-i` pair without a short-circuit pipeline.
+3. Add negative controls for missing, detached, and reversed tokens.
+4. On failure, print indexed `%q` argv records before returning nonzero.
+5. Run focused suite, mutation controls, shell syntax/format checks, then repository baseline gates feasible without dependency installation.
+6. Independent review, queue guard, push, PR, CI, coordinator merge authorization, squash merge, merged-main CI, issue close.
+
+## Progress
+
+- [x] Checkout created and based on `origin/main` `4fa27689`.
+- [x] CI log decoded directly.
+- [x] Root-cause stress control reproduced semantic match + aggregate pipeline failure.
+- [x] RED evidence: intact `/usr/bin/env`, `-i` fixture produced component statuses `0/141/0` and aggregate 141 under the former `grep -q` pipeline; full-reading semantic control stayed 0.
+- [x] GREEN implementation: direct NUL-argv adjacency parser, indexed diagnostics, and full-reading scalar predicates replace all load-bearing early-exit pipelines in this test.
+- [x] Baseline/situational tests:
+  - focused launcher suite: PASS on GNU host and cached Alpine CI image;
+  - paired `test-fleet-units.sh`: PASS;
+  - enumeration guard: PASS (`population=53`, `enumerated=36`, `excluded=18`), 14/14 mutation needles;
+  - `bash -n`, ShellCheck, `git diff --check`: PASS;
+  - static denominator after change: zero load-bearing `grep -q`/`head`/`-m1` pipeline candidates in `test-start-agent-session.sh`;
+  - delete-the-subject mutation removing production `-i`: RED with 78 indexed argv records, byte count, and explicit boundary failure.
+- [x] Independent review:
+  - first Codex review: request changes — negative fixtures did not each assert diagnostics;
+  - remediation: centralized predicate + diagnostic wrapper and exercised all four negative fixtures;
+  - second Codex review: APPROVE, 0 blockers/should-fix/suggestions;
+  - Codex security review: risk none, 0 findings.
+- [ ] PR CI, formal fleet review, merge, merged-main CI, issue closure.
+
+## Documentation disposition
+
+- Updated canonical `docs/PRD.md` with FSP requirements and acceptance criteria.
+- This is an internal test/reliability change with no API, user workflow, deployment, navigation, or publishing-surface change; no user/admin/API/sitemap update is required.
+- `docs/TASKS.md` remains unchanged because the project contract makes it orchestrator-only.
+
+## Risks
+
+- The CI failure did not print its captured argv, so the exact CI payload is unavailable. The stress control proves the assertion is non-portable and can emit the exact false verdict; branch CI is the canonical confirmation that replacing it resolves pipeline 2269’s failure class.
+- Printing fixture argv is safe only while this test’s projection remains non-secret. The diagnostic must stay scoped to the test capture and shell-escaped.

docs/scratchpads/1099-pipefail-sweep.md

@@ -0,0 +1,41 @@
+# #1099 — pipefail + early-exit sweep
+
+## Scope and decisions
+
+- Baseline `df4c591ab42aa1ae62c12935fdc0e772684864a0`, after #1100 removed its 35 sites.
+- Split into review-sized non-closing tranches: runtime/general; tmux/git/quality tests; wake validation/tests.
+- Do not equate class membership with demonstrated risk. Do not use payload size or pipeline stage count as a safety proxy.
+- Preserve the issue's withdrawn findings for `qa-hook-stdin.sh` and the two fresh-directory `pnpm pack` lookups. Fix `install.sh:312` because malformed multi-root input must reach its named handler.
+
+## Tranche 1 TDD
+
+RED-first control: `node --test scripts/pipefail-early-exit.test.mjs` reported exactly 26 non-accepted runtime/general sites, including `install.sh:312`, and exited 1. A checked-in fixture generated from immutable baseline `df4c591a` records all 26 normalized sites; the control passes every fixture entry through the same scanner, asserts exact identity/count/uniqueness, and separately requires zero findings in the current tree. It also inventories accepted sites rather than silently excluding whole files.
+
+Construction choices:
+
+- here-string/file redirection for scalar grep assertions;
+- full capture then parameter expansion for first-line selection;
+- arrays/`mapfile` for complete populations;
+- direct jq/awk/grep selection where one tool can express the property;
+- no `|| true` added to a load-bearing assertion.
+
+Site-by-site verdicts: `docs/reports/quality/1099-pipefail-sweep.md`.
+
+## Tranche 2 TDD
+
+Expanded the unconditional scanner over 11 non-wake test harnesses. RED named exactly 22 source lines; a second immutable-baseline fixture now asserts those 22 entries through the same scanner. Rewrites preserve command status by capturing producers before redirected assertions, use parameter expansion for line selection, and use complete `mapfile` populations where ordering matters. Current-tree finding count is zero for tranches 1 and 2.
+
+## Tranche 3 TDD
+
+Expanded the shared scanner over four wake validation harnesses. RED named 26 occurrences. The wake fixture asserts 26 occurrences / 25 normalized identities through the same scanner; all scalar assertions now use redirection, direct jq selection, complete capture, or consuming diagnostic ranges. Current-tree finding count is zero across the full scoped population.
+
+## Verification so far
+
+- `bash -n` on every changed shell script: pass.
+- structural Node control: pass.
+- `test-mutate-push-guard.sh`: 8/8 pass.
+- `test-send-message-verdict.sh`: 3/3 pass.
+- `test-send-message-socket.sh`: pass.
+- Independent review 143 found two semantic regressions: a help-probe `|| true` changed the failure truth table, and an unguarded Git capture changed non-Git data-dir behavior from rc 0 + JSON to silent rc 128. Both received RED-first regressions before correction; help status is now separate and required, and Git status remains condition-guarded.
+- Wake static inventory remains aligned at 261/261 after line-neutral rewrites; no static-set mismatch. Wake detector/reconcile/digest/preimage suites terminate at their existing fail-closed #973 `BASH_LINENO` environment probe (exit 97, observed `[3 5]`, expected `[3 4]`) before subject tests. No bypass or skip was used; canonical CI remains required.
+- ShellCheck reports only pre-existing source-following, unused-variable, and untouched `ls | head` findings; no new diagnostic was introduced.

docs/scratchpads/1150-pi-goal-extension.md

@@ -0,0 +1,156 @@
+# #1150 — Pi persistent goal extension
+
+- **Task ID:** ISSUE-1150 (no `docs/TASKS.md` row; that file is orchestrator-only)
+- **Issue:** #1150 — `pi: add persistent /goal controller extension to Mosaic framework`
+- **Branch:** `feat/1150-pi-goal-extension`
+- **Mode:** Delivery
+- **Status:** in progress
+
+## Objective
+
+Build and locally validate a Mosaic-owned Pi `/goal` extension. Source must ship from
+`packages/mosaic/framework/runtime/pi/`, framework sync must deploy it under
+`~/.config/mosaic/runtime/pi/`, and no extension/configuration asset may be written into `~/.pi`.
+Pi's native session manager remains the owner of session entries.
+
+## Scope and acceptance source
+
+- Canonical requirements: `docs/PRD.md`, section **Pi Persistent Goal Loop (#1150)**.
+- User intent: continuous goal orientation and status checking after each Pi turn and compaction,
+  tested locally before framework delivery.
+- Documentation target: canonical in-repo user/developer/runtime docs; no external publication.
+
+## Assumptions
+
+- `ASSUMPTION:` Initial semantic verification uses two consecutive structured, evidence-bearing
+  reports from the working agent rather than a second model request after every turn. This keeps the
+  loop testable and avoids doubling model cost while making the limitation explicit.
+- `ASSUMPTION:` Default autonomous bounds are 40 turns and 6 repeated no-progress reports, with only
+  bounded numeric environment overrides.
+- `ASSUMPTION:` A local smoke copy to `~/.config/mosaic/runtime/pi/goal-extension.ts` is authorized by
+  the user's explicit request. Full framework reseed into the live home is not required for the smoke
+  test and would touch unrelated framework-owned files.
+
+## Budget
+
+- Working estimate: 30K implementation/review tokens.
+- Hard user cap: none stated.
+- Cost control: deterministic fake-Pi tests; no nested evaluator calls; only bounded arithmetic/load
+  smoke workflows against the installed runtime.
+
+## Plan
+
+1. Update PRD and create tracking/scratchpad artifacts.
+2. Read launcher, installer ownership, Pi extension, and documentation surfaces.
+3. TDD: add fake-Pi behavior tests for commands, state restoration, turn checks, compaction, limits,
+   verification, and continuation deduplication.
+4. Implement `runtime/pi/goal-extension.ts` and deterministic launcher discovery.
+5. Add framework-sync/deployment acceptance coverage.
+6. Update user, developer, runtime, framework README, and sitemap documentation.
+7. Run focused tests, local Mosaic-path smoke test, then baseline repository gates.
+8. Run independent review, remediate, commit, push/PR/CI/merge/issue closure per delivery gates.
+
+## TDD decision
+
+Applied. The continuation state machine and lifecycle scheduling are control-path logic where a race
+or false terminal state can cause unbounded work or premature completion.
+
+## Progress checkpoints
+
+- [x] Issue #1150 created through Mosaic wrapper.
+- [x] Isolated worktree created from `origin/main`.
+- [x] PRD requirements and acceptance criteria added.
+- [x] Task scratchpad created.
+- [x] RED controller and security-regression tests written and observed failing before implementation.
+- [x] Goal controller, launcher discovery, framework deployment coverage, and bounded state machine
+      implemented.
+- [x] User, admin, developer, runtime, adapter, README, and sitemap documentation updated.
+- [x] Final source copied additively to `~/.config/mosaic/runtime/pi/goal-extension.ts`; source and
+      deployed SHA-256 are identical.
+- [x] Live Pi RPC smoke from the exact Mosaic path reached `achieved` with two verification passes and
+      no extension errors.
+- [x] Baseline and situational checks completed, except the explicitly documented unavailable
+      PostgreSQL-only root integration case.
+- [x] Independent code and OWASP/security reviews completed; all findings remediated and re-reviewed.
+- [ ] Commit, push, PR, terminal-green CI, squash merge, and issue closure complete.
+
+## Tests and evidence
+
+### Situational
+
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/runtime/pi-goal-extension.spec.ts`
+  - final: 25 passed.
+  - Covers commands, per-turn checks, context injection, two-pass verification, mixed-report
+    rejection, bounded limits, compaction, branch restore, stale timers, credential redaction,
+    typed-field false-positive protection, and append-only legacy-state fail-closed behavior.
+- Final focused launcher/controller/file-adapter run: 3 files / 67 tests passed.
+- Final V8 coverage for `framework/runtime/pi/goal-extension.ts`:
+  - 99.17% statements/lines, 93.78% branches, 100% functions.
+- Installer migration fixture: 24 passed and byte-compared the deployed framework asset.
+- Standalone extension TypeScript check against installed Pi 0.84.1 types passed:
+  `pnpm --filter @mosaicstack/mosaic exec tsc --noEmit --pretty false --module NodeNext
+  --moduleResolution NodeNext --target ES2022 --skipLibCheck framework/runtime/pi/goal-extension.ts`.
+- Live deployment/load evidence:
+  - source/deployed SHA-256:
+    `1f0a3806e0948ad5f49684273a7e535e9880c148f7fd16d13ee487fcd601f637`.
+  - `get_commands` identified `/goal` as an extension command sourced from
+    `~/.config/mosaic/runtime/pi/goal-extension.ts`; `/goal help` succeeded; zero extension errors.
+  - live arithmetic goal ended `achieved`, verification `2/2`, with 3 goal reports / 3 agent starts
+    and zero extension errors.
+  - no goal extension exists under `~/.pi` extension paths.
+
+### Baseline
+
+- `pnpm build`: passed before the final framework-only redaction remediation; the extension is not a
+  package build input and its final source passed the standalone Pi type check.
+- `pnpm typecheck`: 45/45 tasks passed.
+- `pnpm lint`: 25/25 tasks passed.
+- `pnpm format:check`: passed.
+- Final Mosaic package components:
+  - Vitest: 82 files / 1,539 tests passed.
+  - full `test:framework-shell` harness passed.
+  - the discovered pre-existing tmux loader-marker race was reproduced with constructor PID
+    evidence, fixed with a pane readiness/FIFO barrier, passed 3 consecutive focused runs, and passed
+    in the full shell harness.
+  - one combined rerun encountered the separate existing real-lease probe TOCTOU in
+    `install-ordering-guard.spec.ts`; an earlier final Vitest run was fully green and the changed
+    focused suites remained green.
+- Gateway safe baseline excluding the prohibited PostgreSQL-only fixture: 55 files / 600 tests passed
+  (6 files / 12 tests skipped by their existing environment gates).
+- Root `pnpm test` reached 43 successful workspace tasks and all changed-package Vitest tests, but
+  the unchanged `apps/gateway/src/__tests__/cross-user-isolation.test.ts` afterAll hook retried a
+  PostgreSQL connection and failed authentication (`28P01`). This checkout explicitly forbids local
+  PostgreSQL startup/access; the failure is unrelated to #1150 and cannot be remediated by starting
+  the database. The gateway suite excluding that PostgreSQL-only file and required CI are used as
+  the safe verification paths.
+
+### Independent review
+
+- Codex code review: approved, 0 findings across 15 files.
+- Initial Codex security review: one medium CWE-532/A09 finding for raw report persistence.
+- Remediation added central credential-pattern redaction, prompt/docs guidance, canary tests, typed
+  field false-positive guards, and sticky fail-closed restore for credential-bearing append-only
+  history.
+- Codex security re-review: risk `none`, 0 findings, confidence 0.87.
+- Focused remediation review findings were fixed; final focused re-review verdict: `APPROVE`.
+- Focused independent review of the tmux readiness barrier: `APPROVE`, no actionable findings.
+
+## Risks and blockers
+
+- Live `~/.config/mosaic` is shared by active Pi/fleet processes. Local deployment remained a single
+  additive framework file and did not reload or restart unrelated sessions.
+- Completion verification is semantic, not mathematical: the active agent supplies structured
+  evidence twice. Operators must still inspect consequential outcomes.
+- Credential redaction is pattern-based defense-in-depth, not a secret store. It covers
+  controller-owned state/status/tool details, not Pi's separate model-message/tool-call history.
+  Goals and reports must never contain real secrets or raw sensitive output. Because Pi session
+  entries are append-only, a detected credential-bearing legacy branch fails closed and the affected
+  session must be removed.
+- Current installed Pi is newer than the repository's historical gateway Pi dependency. The
+  extension was checked and smoke-tested against installed Pi 0.84.1 using stable documented APIs.
+- Local root testing cannot safely execute the unchanged PostgreSQL-only integration fixture under
+  the checkout's explicit database safety constraints. Terminal-green PR CI remains mandatory before
+  merge.
+- The unchanged real-lease default-probe test can observe different broker availability across its two
+  sequential probes; one combined package rerun hit that existing TOCTOU. The same final Vitest suite
+  passed in a separate run, and CI remains the merge authority.

docs/scratchpads/1174-wrapper-guard-round10.md

@@ -0,0 +1,89 @@
+# #1174 — Wrapper guard rounds 10–11
+
+## Objective
+
+Make checkout enforcement judge Git placement operands rather than every HOME-shaped word in the command, without reopening `--separate-git-dir` placement under HOME.
+
+## Plan
+
+1. Reproduce the four over-blocks and the placement-option control at head `20d86e39`.
+2. Add RED fixtures before production changes.
+3. Extract clone/worktree placement operands from the existing shell-aware normalized stream.
+4. Run the full guard corpus, historical-head discrimination, syntax/static checks, probes, review, and CI.
+
+## Progress and evidence
+
+- Reproduced: `NOTE=$HOME`, `--reference=$HOME`, `GIT_DIR=$HOME/x`, and `--template=$HOME/t` all blocked despite explicit `/src/wt` destinations.
+- RED at `20d86e39`: expanded suite had 8 failures, all HOME-valued non-placement cases.
+- GREEN: expanded suite passes 242/242.
+- Round-10 probes: 7/7 placement expectations and 4/4 placement-option controls pass.
+- Earlier path probes remain green: 60/60, 24/24, and 17/17.
+- Historical discrimination with the 242-fixture suite:
+  - `3d0a882a`: 216 pass / 26 fail.
+  - `4b8eba95`: 222 pass / 20 fail.
+  - `20d86e39`: 234 pass / 8 fail.
+- `bash -n`, ShellCheck warning-or-higher, and `git diff --check`: pass.
+
+## Residual / risk
+
+- Relative destinations whose effective path depends on cwd are tracked separately by #1197 and remain out of scope.
+- Unknown future Git options with a separate following value fail closed when that value is HOME-shaped. This may require classification when Git adds an unrelated path-taking option, but prevents a new placement option from silently bypassing the guard.
+
+## Round 11 objective and intake
+
+- **Issue / PR:** #1174.
+- **Objective:** Remove the finite boolean-flag allowlists that turn accepted clone/worktree flags into fake placement operands, while preserving all real HOME placement blocks.
+- **Scope:** `wrapper-guard.sh`, its hermetic fixtures, and task documentation. Relative cwd-dependent destinations remain in #1197.
+- **Surfaces:** security-sensitive Bash hook behavior and shell/Git option grammar; no API, DB, UI, auth, deploy, or dependency changes.
+- **Budget assumption:** 25K working tokens; reduce exploratory matrices before reducing acceptance coverage.
+
+### Round 11 plan
+
+1. Use Git itself to classify accepted/rejected clone and worktree options, and Bash itself to resolve path-word expectations.
+2. Add RED fixtures for all six reported clone flags, generated negations, and equivalent worktree grammar.
+3. Replace the open-ended unknown-option fail-closed fallback with a parser based on the closed value-taking option surface; keep explicit placement options special.
+4. Run the full corpus, historical discrimination, shell/static checks, targeted probes, independent code/security review, one push, and exact-head CI.
+
+### Root-cause evidence
+
+- Git 2.39.5 accepts all six reported clone flags and the broader generated family measured in the brief: `--bare`, `--mirror`, `--ipv4`, `--ipv6`, `-4`, `-6`, `--no-local`, `--no-reject-shallow`, `--no-bare`, `--no-sparse`, `--no-dissociate`, `--no-shallow-submodules`, `--no-quiet`, `--no-progress`, and `--no-recurse-submodules`; it rejects `--relative-paths` as unknown.
+- Git 2.39.5 accepts worktree negations including `--no-force`, `--no-detach`, `--no-lock`, `--no-guess-remote`, and `--no-track`; the current finite worktree flag list does not describe that generated family.
+- `bash -c "printf '%s' <word>"` resolves `$HOME/source`, `${HOME}/source`, and `"$HOME"/source` under HOME while `/src/wt` remains outside it.
+- **Hypothesis:** only separate-value options need positive classification. Treat every other option token as a no-value flag unless it is the explicit placement option; this matches Git's non-enumerable boolean family and confines the residual to genuinely new future value-taking options.
+
+### TDD and verification checkpoints
+
+- RED against the unmodified `91cc37bc` guard: 253 pass / 22 fail in the initial expanded 275-fixture suite. Failures include all 15 accepted clone flags, accepted long abbreviations, short value-taking bundles, abbreviated placement, worktree metadata abbreviation, and both directions of bundled worktree branch parsing.
+- An exploratory fail-closed residual test drove emission of every worktree positional. Re-review correctly showed that this over-blocked HOME-shaped commit-ish metadata; a new commit-ish fixture failed RED against that intermediate implementation (278 pass / 2 fail, including one transient message assertion) and the parser was restored to emit only the actual path.
+- GREEN after remediation: 280/280.
+- Ultron's 13-shape option probe: 13/13 correct, including the six reported over-blocks, HOME destinations, end-of-options, worktree controls, and a later-command placement.
+- Round-10 probes remain green: 7/7 subject-placement expectations and 4/4 `--separate-git-dir` controls.
+- Earlier shell/path probes remain green: 60/60, 24/24, and 17/17.
+- `bash -n`, ShellCheck warning-or-higher, and `git diff --check`: pass.
+
+### Deliberate residual
+
+A future Git release could add a new separate-value option absent from the closed value grammar. It defaults to no-value flag parsing, which leaves the following word positional. For clone, this can fail open if that future option itself creates repository state at its value. For worktree, it can shift which word is read as the path. This hypothetical future ambiguity is accepted deliberately because failing closed on every unclassified option is proven to over-block Git's open-ended present-day boolean/`--no-*` family. Every value-taking and placement option Git currently supports is classified, including accepted abbreviations of `--separate-git-dir`. Relative cwd-dependent targets remain in #1197.
+
+### Independent review checkpoint
+
+- Initial Codex code/security review raised `--orphan` as value-taking. Upstream Git `master` contradicts that premise: the synopsis is `[--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]`, and the prose derives the branch from the path when `-b`/`-B` is absent. `--orphan` is therefore correctly handled as a boolean flag.
+- The security review separately identified the generic future worktree shift residual. An attempted fail-closed remediation emitted every positional, but code re-review correctly rejected it because valid grammar has only one placement positional and an optional commit-ish. Final behavior checks only the path and documents the hypothetical future option shift deliberately; paired actual-grammar `--orphan` fixtures cover safe/HOME paths and `-b` metadata.
+- Security re-review initially had no findings. Code re-review's commit-ish blocker was remediated with a RED fixture and path-only restoration; final code re-review approved with no findings.
+- Final security review then found non-canonical absolute and symlink aliases. Eight lexical fixtures failed RED against the prior implementation, followed by three symlink fixtures failing RED. Remediation expands only shell-visible HOME tokens, resolves the longest existing directory prefix physically, and lexically normalizes the nonexistent suffix. The suite is now 292/292.
+- Inherent residual: a symlink can be replaced between pre-tool inspection and Git execution. Existing aliases are resolved; eliminating the race requires enforcement inside the filesystem mutation path rather than a text pre-hook. Security review classified this medium, and architectural closure is tracked in #1199.
+- Final independent code review: APPROVE, 0 findings. Final security review: no critical/high findings; the single medium TOCTOU residual is explicitly tracked in #1199.
+
+### Final local evidence
+
+- Final hermetic suite: 292/292; the same suite against `91cc37bc` discriminates at 256 pass / 36 fail.
+- Ultron option probe: 13/13; round-10 probes: 7/7 plus 4/4 controls; earlier shell/path probes: 60/60, 24/24, and 17/17.
+- `bash -n`, ShellCheck warning-or-higher, `git diff --check`, sanitization gate, and test-enumeration gate (population 55; 38 enumerated; 18 signed exclusions): pass.
+- Independent code review: APPROVE, 0 findings. Security review's remaining medium TOCTOU architecture residual is tracked in #1199; no critical/high findings remain.
+- Repository-wide TypeScript gates require dependencies absent from this worktree; the canonical Woodpecker pipeline will run them against the pushed exact head.
+
+### Documentation checklist
+
+- `docs/PRD.md` updated with WPG requirements, acceptance, canonicalization, and residual risk.
+- Task scratchpad updated in the same logical change set; `docs/TASKS.md` remains orchestrator-only.
+- No API, auth, UI, navigation, deployment, user-guide, or admin-guide surface changed; OpenAPI, endpoint index, sitemap, and publishing are not applicable.

docs/scratchpads/1194-framework-tool-drift.md

@@ -0,0 +1,71 @@
+# #1194 — Installed framework-tool drift detection and refresh analysis
+
+## Decision
+
+The reported queue-guard source defect was already fixed on `main` by `58b971ab`; the live failure came from a stale `~/.config/mosaic/tools/git/ci-queue-wait.sh`. The durable fix is therefore a detector, not a duplicate queue-guard patch.
+
+`mosaic doctor` now compares the framework tools bundled with the executing Mosaic package against the deployed tools tree. Doctor is the selected visibility boundary because it is observational and operator-invoked: unlike session start, it does not add a repository/network scan to every seat launch, and it cannot silently replace identity or messaging tools while seats are active. It reports drift without changing files. `--fail-on-warn` converts detected drift into a non-zero doctor result.
+
+## Classification
+
+The existing `framework-manifest.txt` is authoritative. The detector invokes the canonical shared `tools/_lib/manifest.sh classify` implementation over the complete source census and refuses missing, unreadable, malformed, incomplete, or zero-framework ownership output. Policy is therefore read rather than duplicated:
+
+- Current policy classifies source files under `tools/**` as framework-owned and required in the deployed tools tree.
+- Current policy explicitly classifies `tools/_lib/credentials.json` operator-owned and excludes it from byte comparison; future policy changes take effect without a detector edit.
+- A file present only in the deployed tools tree is operator-owned/unknown by the manifest's fail-safe default. The detector reports it as `INSTALLED_ONLY operator-or-unknown` under `--verbose` but does not fail or delete it.
+- Empty/partial source traversal, unreadable directories/files, symlinked census entries, root aliases, and descendant source aliases all return `CANNOT_ASSERT` rather than manufacturing agreement.
+
+This means `NOT_INSTALLED` is not suppressed by filename guesses such as “test” or “README”: if it ships below source `tools/**`, the installer contract says it should be installed. Source-only implementation files outside `tools/**` are outside this detector population by construction.
+
+## Current host analysis (observation only; no refresh performed)
+
+A direct source-vs-installed census showed broad drift, including identity and messaging behavior:
+
+- Identity/provider operations: stale `git/detect-platform.sh`, `issue-comment.sh`, `issue-create.sh`, `issue-close.sh`, `issue-view.sh`, `pr-create.sh`, `pr-merge.sh`, `pr-review.sh`, `pr-metadata.sh`; missing `pr-edit.sh` and several identity/read-back regression tools.
+- Messaging/session: stale `tmux/agent-send.sh`, `tmux/send-message.sh`, their regressions, and `fleet/start-agent-session.sh`.
+- Gate enforcement: stale `git/ci-queue-wait.sh`; missing the queue tri-state/process-level suites and terminal-green verifier.
+- Lease/QA behavior: stale lease-broker launch/mutation/receipt tools and QA hooks.
+
+Counts vary with source head and installed local/operator files; the detector prints measured counts every run rather than baking this snapshot into policy.
+
+## Reviewed refresh command — analyse only, do not run during active seats
+
+Use the package/release updater's manifest-driven keep-mode sync during a quiet maintenance window:
+
+```bash
+MOSAIC_SYNC_ONLY=1 \
+MOSAIC_INSTALL_MODE=keep \
+MOSAIC_HOME="$HOME/.config/mosaic" \
+bash /path/to/reviewed/@mosaicstack/mosaic/framework/install.sh
+```
+
+For the globally installed package, resolve the reviewed installer rather than guessing its path:
+
+```bash
+PACKAGE_ROOT="$(dirname "$(node -p "require.resolve('@mosaicstack/mosaic/package.json')")")"
+MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep MOSAIC_HOME="$HOME/.config/mosaic" \
+  bash "$PACKAGE_ROOT/framework/install.sh"
+```
+
+Do not run this while agent seats are active: the stale set includes identity selection, provider mutation, messaging, queue/merge guards, lease enforcement, and session launch. Syncing those files in place can change behavior between a seat's preflight and mutation.
+
+## Post-refresh verification
+
+1. Run `mosaic doctor --fail-on-warn`; require `stale=0 not-installed=0` from the framework drift summary (other unrelated doctor warnings must also be adjudicated).
+2. Re-run the constructed process-level queue probes against the **installed path**, not the source checkout. Use the source suite while overriding its subject path in a reviewed scratch copy, or reproduce these exact observations:
+   - pending provider payload: guard must print `state=pending`, print the pending context, wait, and exit non-zero/timeout — never return immediately with rc 0;
+   - malformed payload: guard must print `state=malformed` and exit non-zero;
+   - unsupported but valid status vocabulary: guard must print `state=unknown` and exit non-zero.
+3. Run provider author read-back for one deliberately low-risk wrapper operation before resuming fleet mutation work; wrapper self-report is not identity evidence.
+4. Relaunch seats only after the quiet-window verification, because existing processes retain loaded environment/context.
+
+## Probe evidence
+
+The detector regression constructs a stale installed tool plus a missing shipped tool and observes rc 1 with distinct `STALE` and `NOT_INSTALLED` lines. That case would pass or be invisible before this change because no installed-vs-shipped comparison existed. Additional review-red controls prove:
+
+- empty and unreadable source censuses return `CANNOT_ASSERT` (they returned clean rc 0 at the first PR head);
+- deleting the manifest returns `CANNOT_ASSERT`, while changing manifest ownership changes the verdict through the canonical resolver (the first head never opened the manifest);
+- root and descendant symlink/source aliases cannot return clean (the first head returned clean for a source-backed installed subtree);
+- a checker hung during doctor is terminated by a bounded watchdog, emits `CANNOT_ASSERT`, and doctor reaches its final warnings line (the first head hung and suppressed the remaining audit).
+
+Controls retain byte-identical success, exact credential carve-out behavior, and installed-only preservation.

docs/scratchpads/lease-remediation/dispatch/measure-W-B.md

@@ -0,0 +1,93 @@
+# W-B — Measure Pi's real tool registry
+
+- **Task / internal ref:** W-B from the lease-remediation orchestrator brief (no matching `docs/TASKS.md` row; workers do not modify that file)
+- **Objective:** identify the exact tool names emitted as `event.toolName` by the installed Pi runtime and compare them with the broker's Pi read-only carve-out.
+- **Scope:** measurement and report only; no broker or runtime source changes. W-C is out of scope.
+- **Budget:** no explicit token cap; constrained to this scratchpad and one local commit.
+- **Installed runtime:** `@earendil-works/pi-coding-agent` / `pi` `0.84.1`.
+
+## Method
+
+I created a throwaway extension at `/tmp/measure-pi-tool-registry.ts` (not in the worktree). On `session_start` it recorded `pi.getAllTools()` and `pi.getActiveTools()`; on every `tool_call` it appended the exact `event.toolName`. I then launched an isolated, ephemeral Pi session with all built-ins explicitly selected:
+
+```text
+PI_OFFLINE=1 pi --mode print --no-session --no-approve \
+  --no-context-files --no-skills --no-prompt-templates --no-extensions \
+  -e /tmp/measure-pi-tool-registry.ts \
+  --tools read,bash,edit,write,grep,find,ls <deterministic probe prompt>
+```
+
+The prompt exercised file read, content search, file search, directory listing, shell execution, file write, and file edit. Pi exited `0`; every selected tool produced one `tool_call`. The write/edit control artifact ended with exact content `after`, proving the mutating calls executed in order.
+
+This runtime observation was cross-checked against the installed distribution's canonical registry at `dist/core/tools/index.js:17`, which declares the same seven names. The gate consumes the measured field directly at `packages/mosaic/framework/runtime/pi/mosaic-extension.ts:368`.
+
+## Exact distinct built-in set
+
+The installed Pi built-in registry is exactly:
+
+```text
+{bash, edit, find, grep, ls, read, write}
+```
+
+| Tool | Runtime registry observation | `tool_call` observation | Installed definition |
+| --- | --- | --- | --- |
+| `read` | `<builtin:read>` | observed once | `dist/core/tools/read.js:138` |
+| `bash` | `<builtin:bash>` | observed once | `dist/core/tools/bash.js:231` |
+| `edit` | `<builtin:edit>` | observed once | `dist/core/tools/edit.js:170` |
+| `write` | `<builtin:write>` | observed once | `dist/core/tools/write.js:138` |
+| `grep` | `<builtin:grep>` | observed once | `dist/core/tools/grep.js:79` |
+| `find` | `<builtin:find>` | observed once | `dist/core/tools/find.js:79` |
+| `ls` | `<builtin:ls>` | observed once | `dist/core/tools/ls.js:61` |
+
+The raw distinct `event.toolName` result was:
+
+```json
+["bash", "edit", "find", "grep", "ls", "read", "write"]
+```
+
+Pi registers all seven, but its default active set is only `read`, `bash`, `edit`, and `write` (`dist/core/sdk.js:132`). The probe explicitly activated all seven so the three search/list tools could be observed at the hook.
+
+## Positive control
+
+The known `read` tool was the control. The method surfaced it twice:
+
+1. `pi.getAllTools()` returned `read` with source path `<builtin:read>`.
+2. Reading `/tmp/pi-registry-probe/seed.txt`, which contained `CONTROL_TOKEN`, produced one hook record with `event.toolName === "read"`.
+
+The control was therefore positive; the seven-name result is measured, not an empty-probe inference.
+
+## Carve-out comparison and collision result
+
+The broker currently declares `{"read", "grep", "find", "ls"}` at `packages/mosaic/framework/tools/lease-broker/daemon.py:54`.
+
+- `read`: real built-in.
+- `grep`: real built-in.
+- `find`: real built-in.
+- `ls`: real built-in.
+
+All four carve-out names are exact, case-sensitive Pi tool names.
+
+The general execution/writing tool names are `bash`, `edit`, and `write`. Their intersection with the carve-out is empty:
+
+```text
+{bash, edit, write} ∩ {read, grep, find, ls} = ∅
+```
+
+Therefore no general shell-exec or file-mutating Pi tool shares a name with a carve-out entry. `grep` and `find` may invoke constrained search helpers internally, but neither exposes an arbitrary command interface; the arbitrary command tool is distinctly named `bash`.
+
+The Mosaic extension separately registers the non-built-in custom tool `mosaic_context_recover` at `packages/mosaic/framework/runtime/pi/mosaic-extension.ts:379`; the broker handles that identity through its dedicated recovery exemption rather than the read-only set (`daemon.py:722`). Unknown or third-party custom tools are not part of Pi's built-in seven-name registry and remain outside the carve-out.
+
+## Verification evidence
+
+- `pi --version` → `0.84.1`.
+- Isolated probe exit → `0`.
+- Runtime `getAllTools()` count → `7`, all with `sourceInfo.source === "builtin"`.
+- Distinct hook names → `bash`, `edit`, `find`, `grep`, `ls`, `read`, `write`.
+- Hook counts → exactly one call for each of the seven names.
+- Mutation artifact after `write` then `edit` → exact content `after`.
+- Installed registry source → `allToolNames = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"])`.
+
+## Risks / limitations
+
+- The probe deliberately disabled all other extensions, so extension-defined third-party tools were excluded from the built-in registry measurement. The production gate still receives those names and treats names outside the broker carve-out as mutating/fail-closed.
+- Explicit `--tools` activation was required to exercise `grep`, `find`, and `ls`; this does not imply they are active in Pi's default four-tool configuration.

docs/scratchpads/pr-merge-message-field.md

@@ -0,0 +1,99 @@
+# PR merge squash message field
+
+- **Charter:** `/home/hermes/agent-work/CHARTER-PRMERGE-MESSAGE-FIELD.md`
+- **Owner:** `be-coder-08`
+- **Branch:** `fix/pr-merge-message-field`
+- **Base:** remote `main` / local `origin/main` at `85d2108e4ed15c744ad3b87a5b629e7b2d39405a`
+- **Estate:** HOMELAB tooling shared by HOMELAB and USC
+
+## Objective
+
+Add an optional, identity-checked Gitea squash message to `pr-merge.sh` so genuine multi-author PRs retain non-poster branch authors without weakening hardcoded squash behavior.
+
+## Binding requirements
+
+1. `Do` remains hardcoded to `squash`; no provider/repository default may select merge style.
+2. A verified trailer uses a PR commit's linked `author.login` and that same commit's author email. No `/users/{login}` primary-email lookup occurs. Recorded rationale: this asks only what the provider can answer.
+3. A commit with `author.login` null blocks before merge, prints both the null provider fact and commit email fact, and names the escalation principal.
+4. The BLOCK arm must be observed firing; a normal canonical single-author API payload remains explicit squash plus its reviewed `head_commit_id`.
+5. Every provider mutation is read back from the provider; no real PR is merged during tests.
+
+## Derived interface decisions
+
+- Add `--co-author-trailers` rather than accepting arbitrary message text. The wrapper enumerates PR commits and constructs trailers, making an unchecked `Co-authored-by` line unexpressible.
+- Require `--escalate-to PRINCIPAL` with `--co-author-trailers`, so the BLOCK diagnostic always names a principal rather than a generic role.
+- Do not expose `MergeTitleField` separately. When trailers exist, set it from the provider PR title and set `MergeMessageField` only to construction-generated trailers. This preserves one provider source for the title and avoids an unrelated caller-controlled degree of freedom.
+- Preserve first-commit order and emit one trailer per distinct non-poster `author.login`, using that first linked commit's own email.
+
+## Canonical delivery plan
+
+1. Port the capability into the installed source of truth, `packages/mosaic/framework/tools/git/pr-merge.sh`; do not retain `infra/fleet/tools/git` as a second copy.
+2. Preserve canonical `--expect-head`, exact head branch/repository/SHA queue inspection, Gitea atomic head pinning, GitHub `--match-head-commit`, and delete-after-merge semantics.
+3. Do not port the deployed-only `--skip-queue-guard` bypass. Add the focused harness to the canonical framework-shell suite and re-establish RED/GREEN on the packaged baseline.
+4. Deliver through a reviewed package release followed by `mosaic update` with its default framework reseed. The installer snapshots, manifest-syncs framework-owned `tools/**`, and rolls back on failure.
+5. Before either estate relies on the change, require installed/package hash equality, `MergeMessageField` presence, and a green focused harness. Release/reseed ownership is currently unassigned and blocks activation after source merge.
+
+## Evidence
+
+- RED against the byte-identical deployed baseline (`sha256 08a65e8584c5…`): rc 1 with eight named failures. The wrapper rejected `--co-author-trailers`; the null-login path emitted none of the required BLOCK facts/principal; and both verified/ordinary API paths failed the stdin-config credential assertion (ordinary path exposed the fixture token through curl argv). Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-red.log`.
+- GREEN on the deployed-baseline candidate: verified linked multi-author payload, null-login BLOCK, required named principal, explicit squash, stdin-config token transport, and absence of `/users` lookup all passed. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-green.log`.
+- RED against canonical packaged baseline `c581ef48…`: rc 1 with 32 assertions. It rejects the new option, and the first harness version did not satisfy canonical head branch/repository/SHA metadata. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-packaged-baseline-red.log`. The port adapts the fixture rather than weakening canonical head controls.
+- Provider capability probe against `git.mosaicstack.dev`: authenticated `be-coder-08` POST to deliberately nonexistent PR `2147483647` with both message fields returned JSON HTTP 404; the unauthenticated same request returned JSON HTTP 401 (not the charter's predicted 403). The authenticated-vs-unauthenticated differential proves write authorization resolved while no mergeable subject existed. `tl-mosaic` ruled the literal non-load-bearing: preserve the observed 404/401 pair and do not manufacture a 403 case. No cause was inferred and no real PR was targeted.
+- Provider-generated trailer behavior is not treated as exclusive or absent. The wrapper's VERIFIED/BLOCK decision binds each requested non-poster trailer to commit `author.login` plus that commit's email; it does not assume `MergeMessageField` is the squash's only trailer source. The poster is omitted from the constructed list because the resulting squash author already records the poster; any additional provider-generated trailer is outside this change's unmeasured mechanism.
+- An early candidate SHA-256 `5de32876990e4f26920448cb3220cc7f1146d558b4dd2bc1ee1a2abee2f2cbe6` passed the initial harness, then author-side review found credential-fallback and argv-exposure defects. The live deployed wrapper was atomically restored to baseline SHA-256 `08a65e8584c52c6d41ea1c686f8b95585c21e4b37320a2447eba09359a0e02c1`; the remediated candidate remains only in the worktree.
+
+## Remediation and current review state
+
+1. Token and Basic Auth now use stdin curl configuration, not argv. PR title, contributor email, and the JSON payload also remain out of child argv.
+2. Each credential attempt binds commit inspection and merge. A token failure during either inspection or mutation causes Basic fallback to repeat inspection before mutation; the payload pins the inspected `head_commit_id`.
+3. Focused tests cover token-resolution fail-closed behavior, both HTTP-401 fallback seams, metadata/credential argv absence, null-login BLOCK, explicit squash, canonical reviewed-head binding, unchanged ordinary payload, and retained log-safe provider diagnostics. Token-resolution RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-token-resolution-red.log`.
+4. Codex review rounds 3–5 requested retained provider error text, log-safe provider diagnostics, fail-closed credential fallback, stable value-option parsing, and PR-title trailer-injection prevention. These are remediated with regression assertions. A post-remediation independent review is still required.
+5. **Accepted linkage limitation:** `author.login` resolution proves that the commit address maps to a registered provider account. It does not prove that the named principal authored the commit because Git author metadata is self-asserted. This gate checks attribution linkage, not authorship; commit signing is out of scope and currently unadopted. Coordinators explicitly ruled that this does not add a third state.
+6. Codex's sandbox could not execute the harness because its checkout was read-only; that environmental limitation is recorded separately from host-side test results.
+
+## Disposable provider fixture acceptance
+
+- Use a retained scratch repository only, with two branch authors and `author != committer` on at least one commit.
+- Arm A supplies a message-field trailer for one non-poster; record whether that value lands without forcing the partial-pair result into under-specified `APPENDS`/`REPLACES` labels. Demonstrate an absence control.
+- Arm B includes a registered trailer for a different non-poster on a branch commit; record whether it survives or drops. Verify identity through an existing commit whose `author.login` resolves and demonstrate an absence control.
+- Parse landed trailers key-agnostically with `^[A-Za-z-]+-[Bb]y:` and record generated poster pair presence/absence plus resulting poster attribution.
+- Record `/users/<login>` status and raw email only as non-gating estate telemetry. Never read `active`, `visibility`, or any profile field as an identity gate.
+- Use distinct principals: poster `be-coder-08`, merger `Mos`, Arm A `be-coder-07`, and Arm B `be-coder-06`. Capture every trailer-shaped line verbatim and in order. Zero trailer lines means the generator did not fire and the run is `VOID`, not evidence that either arm dropped.
+- Report the same read-back evidence to `mos-claude` on socket `default` and `tl-mosaic` on socket `mosaic-fleet`. Report values rather than mechanism inferences and stop on any poster-attribution regression.
+
+## Fixture preflight
+
+- Retained public repository: `mosaicstack/prmerge-trailer-fixture`; PR `#1`, posted by `be-coder-08` and reserved for merge by `Mos`.
+- Existing `mosaicstack/stack` commits resolve `be-coder-07` and `be-coder-06` through `author.login`; exact addresses are `[email protected]` and `[email protected]`.
+- Non-gating HOMELAB telemetry for authenticated reader `be-coder-08`: `/api/v1/users/be-coder-06` returned HTTP 200 with raw `email` value `[email protected]`.
+- Provider preflight showed PR commit enumeration is newest-first. A new RED test proved that deriving `head_commit_id` from the final array element selected the wrong commit. The candidate now reads `.head.sha` from the authenticated PR endpoint before enumeration, verifies it appears in the commit set, and atomically pins that SHA in the explicit squash payload. RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-head-order-red.log`.
+- Fixture PR head `f6ba6e5105031fa21f5ff7bd8e4379d99c16e1de` has `author.login=be-coder-07`, `committer.login=be-coder-08`, and branch-message trailer `Co-authored-by: be-coder-06 <[email protected]>`.
+
+## Fixture result
+
+- `Mos` merged retained fixture PR `#1` through staged candidate SHA-256 `60e779a85fd13b729d859ea7c986d1e9b1641b97991611329226c1b3113ffb6e`; resulting squash commit: `3f550715d9bc716426fd355a65fe997b3a90fa7d` with one parent.
+- Provider read-back: poster/commit author `be-coder-08`, committer/merger `Mos`. The run is non-void.
+- Trailer-shaped lines, verbatim and in order:
+  1. `Co-authored-by: be-coder-07 <[email protected]>`
+  2. `Co-authored-by: be-coder-08 <[email protected]>`
+- Arm A supplied field value (`be-coder-07`) landed. Arm B branch trailer (`be-coder-06`) dropped. Both fabricated absence controls remained absent. No `Co-committed-by:` line landed.
+- The candidate payload construction explicitly excludes the poster and supplied only the Arm A `be-coder-07` line. Therefore the landed poster line was provider-generated, not candidate-composed. The raw result supports `FIELD LANDS`, `BRANCH DROPS`, and `POSTER GENERATED`; it does not support a claim that candidate code supplied the poster. Evidence: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-fixture-readback.log` and the retained provider object.
+- Retained fixture PR `#2` measured the N=2 shape needed by `#1030`: supplied `be-coder-07` then `be-coder-06`; both landed in that order, followed by the provider-generated poster line. No truncation or dedup occurred at N=2. Resulting squash: `39db9d13aed0…`.
+
+## Current hold point
+
+PR `mosaicstack/stack#1066` is open. Its first frozen head `f4b162fa…` was terminal-green in Woodpecker `mosaic` pipeline `#2225`, but that evidence becomes stale when the canonical port moves the head. The deployed wrapper remains baseline `08a65e85…`; no manual copy will occur. Canonical port tests, commit amendment, rebase, one guarded force-with-lease, exact-head CI, and new independent review remain. Even after source merge, activation remains blocked on an assigned package-release/reseed owner and installed-byte read-back.
+
+## Security review 96 remediation
+
+Exact reviewed predecessor head: `1ceb11058f64dd7f4a817ceb2124f980a1c4dd23`.
+
+RED-first focused harness produced 10 named failures: all curl calls lacked size/time/connect bounds; raw ESC email reached mutation; oversized and stalled curl failures were discarded and reached mutation; nonempty Basic output with resolver rc 91 authorized mutation.
+
+Security remediation:
+
+- Removed the cross-principal HTTP-401 Basic fallback. Both inspection-401 and merge-401 paths now refuse without Basic resolution or mutation; `get_gitea_basic_auth` references in the merge subject are 0.
+- Applied `--max-filesize`, `--max-time`, and `--connect-timeout` to all 3/3 provider curl sites and fail closed on curl transport rc at all 3/3 sites.
+- Required linked email bytes to be ASCII and printable before constructing `MergeMessageField`; guarded construction sites 1/1.
+
+GREEN: message-field, exact-head, empty-UID/API, queue branch/repository/SHA, bash syntax, ShellCheck, and diff check pass. R7 total-removal mutants went RED: email guard 3 rows; bound switches 1 row; transport-rc guards 4 rows; HTTP-401 refusal 3 rows. R7 bound: mutants prove total removal only; explicit denominators above prove site coverage.

packages/mosaic/framework/adapters/pi.md

@@ -13,7 +13,8 @@ Pi is the native Mosaic agent runtime. The `mosaic pi` launcher:
 
 1. Injects the full runtime contract via `--append-system-prompt`
 2. Loads Mosaic skills via `--skill` flags
-3. Loads the Mosaic extension via `--extension` for lifecycle hooks
+3. Loads framework-owned `mosaic-extension.ts` and `goal-extension.ts` from
+   `~/.config/mosaic/runtime/pi/` via ordered `--extension` flags
 4. Detects active missions and injects initial prompts
 
 ## Capabilities vs Other Runtimes
@@ -22,6 +23,7 @@ Pi is the native Mosaic agent runtime. The `mosaic pi` launcher:
 - Native thinking levels replace sequential-thinking MCP
 - Native skill discovery compatible with Mosaic SKILL.md format
 - Native extension system for lifecycle hooks (TypeScript, not bash shims)
+- Bounded persistent `/goal` loop with per-turn, post-compaction, and two-pass evidence checks
 - Native session persistence and resume
 - Model-agnostic (Anthropic, OpenAI, Google, Ollama, custom providers)
 

packages/mosaic/framework/defaults/AGENTS.md

@@ -39,6 +39,7 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
 | TypeScript strict typing                           | `guides/TYPESCRIPT.md`             |
 | QA / test strategy                                 | `guides/QA-TESTING.md`             |
 | Documentation (any code/API/auth/infra change)     | `guides/DOCUMENTATION.md`          |
+| Writing style (docs, comms, any prose)             | `guides/WRITING-STYLE.md`          |
 | Secrets / vault usage                              | `guides/VAULT-SECRETS.md`          |
 | Tool/credential reference (service CLIs, wrappers) | `guides/TOOLS-REFERENCE.md`        |
 | Memory protocol (OpenBrain capture/recall)         | `guides/MEMORY.md`                 |

packages/mosaic/framework/defaults/README.md

@@ -104,7 +104,14 @@ The launcher:
 1. Verifies `~/.config/mosaic` exists
 2. Verifies `SOUL.md` exists (auto-runs `mosaic init` if missing)
 3. Injects `AGENTS.md` into the runtime
-4. Forwards all arguments to the runtime CLI
+4. For Pi, loads the framework-owned core and persistent-goal extensions from
+   `~/.config/mosaic/runtime/pi/`
+5. Forwards all arguments to the runtime CLI
+
+Inside `mosaic pi`, `/goal set <statement>` starts a bounded persistent goal loop. Use `/goal status`,
+`/goal pause`, `/goal resume`, or `/goal cancel` to control it. The extension remains part of Mosaic
+under `~/.config/mosaic/runtime/pi/goal-extension.ts`; it is not installed in Pi's main extension
+directory.
 
 You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtime adapters will tell the agent to read `~/.config/mosaic/AGENTS.md`.
 
@@ -124,7 +131,7 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
 │   ├── claude/            ← CLAUDE.md, RUNTIME.md, settings.json, hooks
 │   ├── codex/             ← instructions.md, RUNTIME.md
 │   ├── opencode/          ← AGENTS.md, RUNTIME.md
-│   ├── pi/                ← RUNTIME.md, mosaic-extension.ts
+│   ├── pi/                ← RUNTIME.md, mosaic-extension.ts, goal-extension.ts
 │   └── mcp/               ← MCP server configs
 ├── skills/                ← Universal skills (synced from mosaic/agent-skills)
 ├── skills-local/          ← Local cross-runtime skills
@@ -136,7 +143,7 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
 
 | Launch method       | Injection mechanism                                                                       |
 | ------------------- | ----------------------------------------------------------------------------------------- |
-| `mosaic pi`         | `--append-system-prompt` with composed runtime contract + skills + extension              |
+| `mosaic pi`         | `--append-system-prompt` with composed runtime contract + skills + Mosaic extensions      |
 | `mosaic claude`     | `--append-system-prompt` with composed runtime contract (`AGENTS.md` + runtime reference) |
 | `mosaic codex`      | Writes composed runtime contract to `~/.codex/instructions.md` before launch              |
 | `mosaic opencode`   | Writes composed runtime contract to `~/.config/opencode/AGENTS.md` before launch          |

packages/mosaic/framework/defaults/STANDARDS.md

@@ -27,6 +27,14 @@ Master/slave model:
 - Do not perform destructive git/file actions without explicit instruction.
 - Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.
 
+### Output standards (writing + code)
+
+- Technical documentation follows **MOS-STE** (Mosaic Simplified Technical English — an adapted ASD-STE100 profile): short sentences, one instruction per sentence, active voice, one word per meaning, one term per concept. Full rules: `~/.config/mosaic/guides/WRITING-STYLE.md`.
+- Apply MOS-STE **hardest to verification artifacts** (acceptance criteria, witness predicates, gate/alarm conditions). There an ambiguous term produces a false green, not just a confused reader.
+- Source code follows the **Google Style Guide** for the language.
+- User-facing comms follow the user's declared `communicationStyle` in `USER.md` "Communication Preferences" (`direct` | `friendly` | `formal`, default `direct`); `guides/WRITING-STYLE.md` §5 maps each value to output. The documentation standard does not change with user preference.
+- **Carve-out:** MOS-STE does NOT apply to content that must carry a specific human voice (letters, personal or marketing prose, voice-matched output). A declared voice profile wins.
+
 ### Secrets handling (HARD RULE)
 
 - Vault is the canonical source-of-truth for every secret in every environment. No exceptions.
@@ -52,6 +60,52 @@ If a repo does not expose these scripts, run equivalent local workflow commands
 - Do not auto-resolve data conflicts in shared state files.
 - Keep commits scoped to a single logical change set.
 
+## Model Tiering
+
+Model choice is a standard, not a preference. Delegating a mechanical grep to a
+frontier reasoning model wastes budget; sending a security review to a cheap tier
+produces a review that passes and proves nothing. Both are defects.
+
+Tiers are named by **capability class**, so the standard survives a model
+generation. An operator binds each class to a concrete model id.
+
+| Class         | Use for                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `search`      | grep/glob, file location, status and health checks, one-line mechanical edits             |
+| `build`       | feature implementation, test writing, bugfixes, routine refactors                         |
+| `judge`       | code review, planning, API/compat-sensitive changes                                       |
+| `adversarial` | security review, ambiguous architecture, anything where a wrong "looks fine" is expensive |
+
+Rules:
+
+1. **Start at the cheapest class that can do the task; escalate on evidence, not
+   on nerves.** Omitting a tier is not neutral — it inherits the caller's model,
+   which is usually the most expensive one.
+2. **Compat-sensitive work escalates one class.** A change that must interoperate
+   with an existing contract is judged, not just built.
+3. **A tier assignment is benchmarked, not asserted.** Move a task class to a
+   cheaper tier only against a blind A/B on real work from this codebase, ranked
+   by someone other than the author. "It seemed fine" is not evidence.
+4. **Reviewer independence beats reviewer size.** An `adversarial` verdict from
+   the model that wrote the code is not a second opinion (see Constitution gate 16).
+
+### Where the binding lives
+
+The class→model map is operator configuration, never framework source: model
+availability, cost, and quotas differ per operator and per host.
+
+Resolution order, first hit wins:
+
+1. the config service (DB-backed, surfaced and editable in the Mosaic webUI)
+2. a local operator file (`STANDARDS.local.md`, or `policy/` where the runtime
+   injects it)
+3. the framework default — the class names above, with no binding
+
+Only layer 1 is auditable across a fleet, so it is the target end state; layers 2
+and 3 exist so a host with no config service still runs. A local override that
+silently disagrees with the config service is drift — the same failure class the
+tool-index gate exists to catch, and it belongs in `mosaic doctor`.
+
 ## Prompting Contract
 
 All runtime adapters should inject:

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

@@ -11,22 +11,106 @@ All tool suites are located at `~/.config/mosaic/tools/`.
 
 Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
 
+This index is complete and is kept complete mechanically: `tools/quality/scripts/check-tools-index.sh`
+fails CI when a wrapper ships without an entry here, or when an entry here names a wrapper that no
+longer exists. A wrapper missing from this list is, from inside an agent session, indistinguishable
+from a wrapper that was never written — which is how the APPROVE/APPROVED incident below happened.
+
+Every command takes `--help`. All of them accept `--login <account>` to pin the acting identity;
+supply it explicitly on any host where the provider CLI's default account is an admin.
+
+| Issues             |                                   |
+| ------------------ | --------------------------------- |
+| `issue-create.sh`  | Create an issue (Gitea or GitHub) |
+| `issue-view.sh`    | Show one issue                    |
+| `issue-list.sh`    | List issues                       |
+| `issue-edit.sh`    | Edit title/body/labels/milestone  |
+| `issue-comment.sh` | Add a comment                     |
+| `issue-assign.sh`  | Assign or unassign                |
+| `issue-close.sh`   | Close an issue                    |
+| `issue-reopen.sh`  | Reopen a closed issue             |
+
+| Pull requests    |                                                           |
+| ---------------- | --------------------------------------------------------- |
+| `pr-create.sh`   | Open a pull request                                       |
+| `pr-edit.sh`     | Edit PR title, body, base branch, or draft/ready state    |
+| `pr-view.sh`     | Show one PR                                               |
+| `pr-list.sh`     | List PRs                                                  |
+| `pr-diff.sh`     | Fetch a PR's diff                                         |
+| `pr-metadata.sh` | PR metadata as JSON (head SHA, base, state, mergeability) |
+| `pr-review.sh`   | **Place a review verdict — see the dialect note below**   |
+| `pr-ci-wait.sh`  | Block until the PR's CI reaches a terminal state          |
+| `pr-merge.sh`    | Merge a PR                                                |
+| `pr-close.sh`    | Close a PR without merging                                |
+
+| Milestones            |                    |
+| --------------------- | ------------------ |
+| `milestone-create.sh` | Create a milestone |
+| `milestone-list.sh`   | List milestones    |
+| `milestone-close.sh`  | Close a milestone  |
+
+| Gates and guards        |                                                                                                           |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `ci-queue-wait.sh`      | CI queue guard — required before push/merge (see below)                                                   |
+| `push-guard.sh`         | Refuse verifications that pass for the wrong reason (e.g. green against an unpushed tree)                 |
+| `mutate-push-guard.sh`  | Regenerate the guard's mutation-coverage table from measurement, so the table cannot drift from the guard |
+| `verify-clean-clone.sh` | Prove the **committed** artifact runs, from a clean clone — not the working tree                          |
+
+| Context              |                                                                                          |
+| -------------------- | ---------------------------------------------------------------------------------------- |
+| `detect-platform.sh` | Resolve the provider (Gitea vs GitHub) for the current repo; every other wrapper uses it |
+| `lane-brief.sh`      | Live dispatch brief for a repo "lane" (milestone/label) straight from the provider       |
+
+| Workspace            |                                                                          |
+| -------------------- | ------------------------------------------------------------------------ |
+| `mosaic-worktree.sh` | Create/list/remove git worktrees — **the only supported way**; see below |
+| `wrapper-guard.sh`   | PreToolUse hook that enforces the two rules above; not called by hand    |
+
+**Workspace placement is derived, not chosen.** `mosaic-worktree.sh new <branch>` takes a branch
+name and nothing else. Every path comes out of `git worktree list --porcelain` — main worktree,
+repo name, parent dir, then `<parent>/<repo>-worktrees/<branch-slug>`. There is no placement flag
+because a decision an agent has to make is a decision that drifts: the rule "big work goes on a work
+filesystem" already existed in prose and 255 GB accumulated in `$HOME` across 842 directories
+anyway, under five simultaneous conventions on a single host.
+
 ```bash
-# Issues
-~/.config/mosaic/tools/git/issue-create.sh
-~/.config/mosaic/tools/git/issue-close.sh
+~/.config/mosaic/tools/git/mosaic-worktree.sh new <branch> [--from <base>]
+~/.config/mosaic/tools/git/mosaic-worktree.sh path <branch>   # derived path, no side effect
+~/.config/mosaic/tools/git/mosaic-worktree.sh list            # this repo's worktrees + state
+~/.config/mosaic/tools/git/mosaic-worktree.sh rm <branch>     # removal is part of the task
+~/.config/mosaic/tools/git/mosaic-worktree.sh gc [--apply]    # reclaim clean + fully-pushed ones
+```
 
-# PRs
-~/.config/mosaic/tools/git/pr-create.sh
-~/.config/mosaic/tools/git/pr-merge.sh
+Worktrees rather than clones, because `git worktree list` makes every checkout enumerable — a bare
+clone dropped somewhere on disk can never be safely reclaimed, so it is never reclaimed. `rm` and
+`gc` decide by **evidence, never by size or age**: a worktree is reclaimable only when
+`git status --porcelain` is empty _and_ `git rev-list --count HEAD --not --remotes` is 0. Anything
+else is preserved and reported. `--force` exists and is yours to type deliberately.
 
-# Milestones
-~/.config/mosaic/tools/git/milestone-create.sh
+`wrapper-guard.sh` is registered as a Claude Code `PreToolUse` hook on `Bash` (see
+`runtime/claude/settings.json`). It blocks exactly three things and lets everything else through:
+a `git clone`/`git worktree add` targeting `$HOME`; a raw provider-API **write** to an endpoint that
+already has a wrapper above (reads are untouched — they are how you gather evidence); and the
+literal `"event": "APPROVE"`. For a genuine gap no wrapper can express, prefix
+`MOSAIC_WRAPPER_OVERRIDE=1`. Reaching for the override twice for the same call means the wrapper has
+a missing flag — extend the wrapper.
+
+```bash
+~/.config/mosaic/tools/git/issue-create.sh --help
+~/.config/mosaic/tools/git/pr-review.sh --pr 42 --event APPROVED --body "..."
 
 # CI queue guard (required before push/merge; defaults to the checked-out branch)
 ~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
 ```
 
+**Review dialect — the reason `pr-review.sh` is not optional.** Gitea's approve event is
+`APPROVED`; GitHub's is `APPROVE`. Send GitHub's spelling to a Gitea host and it answers **HTTP
+200**, files the review as PENDING, and then rejects the submit with `422 review stay pending` — the
+verdict looks placed and is not. (`REQUEST_CHANGES` is spelled identically on both, so only the
+approve path carries the trap.) `pr-review.sh` sends the correct token for the detected provider.
+Whatever you use, re-read `GET /pulls/{n}/reviews` and assert the state before reporting a verdict
+placed.
+
 The guard exits nonzero for any provider-asserted non-green, missing, or malformed CI state. If credentials or the provider are unavailable, it emits `CANNOT_ASSERT` and writes a JSONL audit record. Push degrades to exit 0 so recovery work is not bricked; merge holds with retryable exit 75 until the provider recovers, then self-clears without manual reset. Neither outcome is evidence that CI was clear. `pr-merge.sh` automatically inspects the exact PR head repository and full commit SHA rather than its `main` base; this also handles fork PRs without branch-name ambiguity. Pass `--expect-head <approved-full-sha>` to bind a commit-specific review or merge-gate verdict; Gitea uses atomic `head_commit_id` and GitHub uses `--match-head-commit`.
 
 ### Code Review (Codex)

packages/mosaic/framework/guides/WRITING-STYLE.md

@@ -0,0 +1,134 @@
+# Writing Style Standard — MOS-STE (MANDATORY)
+
+This guide defines how agents write. It sets one style standard per output type.
+It is written in the standard it defines, as a worked example.
+
+**Adapted, not compliant.** MOS-STE (Mosaic Simplified Technical English) is an
+adapted profile of ASD-STE100. Mosaic does not license or certify against
+ASD-STE100. Mosaic uses the load-bearing rules and fits them to agent work. This
+is the same stance Mosaic takes toward DO-178B/C: use the rigor, do not claim the
+certification.
+
+## Scope — which standard governs which output
+
+| Output type                                                                                                   | Standard                                                                    |
+| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Technical documentation (READMEs, runbooks, PRDs, procedures, ADRs, guides, acceptance criteria, design docs) | **MOS-STE** (this guide)                                                    |
+| Source code and code comments                                                                                 | **Google Style Guide** for the language (§4)                                |
+| Inter-agent comms                                                                                             | MOS-STE by default (concise, structured)                                    |
+| User-facing comms                                                                                             | **Per-user style choice** — read `USER.md` "Communication Preferences" (§5) |
+| End-user prose the user owns (marketing, letters, personal writing, voice-matched content)                    | The user's declared voice. MOS-STE does NOT apply.                          |
+
+**The user-voice carve-out is absolute.** Do not apply MOS-STE to content that
+must carry a specific human voice (for example a cover letter, a personal
+message, or marketing copy). That content needs the user's voice. MOS-STE would
+damage it. When a project declares a voice profile, that profile wins.
+
+## 1. Why one standard
+
+Agent documentation drifts across projects. Different agents use different terms,
+sentence styles, and structures for the same concept. Readers lose time.
+Assumptions hide in ambiguous prose. One standard gives agents a clear target. It
+gives reviewers a clear test.
+
+## 2. Where MOS-STE matters most — verification artifacts
+
+Apply MOS-STE hardest to acceptance criteria, witness predicates, gate
+definitions, and alarm conditions. In prose, an ambiguous term produces a
+confused reader. In a verification artifact, an ambiguous term produces a false
+green — a check that passes without testing the claim.
+
+The one-term-one-concept rule (rule 9) is the guard. When one word names two
+concepts in one predicate, the check can test the wrong concept and still pass.
+
+**Worked failure.** A rename used a witness predicate with three clauses: ref A
+present, ref B absent, tip committed from this host. Every clause tested the git
+_ref_ (the channel). The claim under test was about a _field inside the payload_.
+The word "beacon" named two concepts in one sentence. Deleting ref B was the next
+scheduled step. That step flips the last clause green and certifies a state in
+which the payload still names the wrong host. The predicate was one planned action
+away from a false green on its normal path. The payload field was never tested.
+
+Rule: when N failure modes share one observable, the observable is not a
+diagnostic. In a verification artifact, that ambiguity does not confuse a reader —
+it certifies the defect.
+
+## 3. MOS-STE rules
+
+### 3.1 Sentence rules
+
+1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or
+   fewer for a description. (Reasoning and doctrine prose relaxes this limit —
+   see §3.4. A future lint enforces §3.1, not §3.4.)
+2. Write one instruction per sentence. In a procedure, give one command per step.
+3. Use the active voice. Write "Run the script." Do not write "The script should
+   be run."
+4. Use the imperative for instructions. Start the sentence with the verb.
+5. Use simple verb tenses. Prefer the present tense. Avoid the perfect and
+   progressive tenses when a simple tense works.
+6. Do not use an `-ing` form when it makes the meaning unclear.
+7. Write positive statements. State what to do, not only what to avoid.
+
+### 3.2 Word rules
+
+8. Use one word for one meaning. Do not use the same word in two senses.
+9. Use one term for one concept. Do not use synonyms for variety. Example: choose
+   `secret`, `credential`, or `key` for each concept, and keep it.
+10. Use articles (`a`, `the`). Do not drop words to save space.
+11. Keep an approved-terms glossary per project. Add each domain noun and each
+    chosen verb. Technical names (for example `Vault`, `cgroup`, `systemd`) are
+    always allowed.
+12. Define an abbreviation at its first use. Then use it consistently.
+
+### 3.3 Structure rules
+
+13. Use a list for parallel items or sequential steps. Do not put them in one long
+    sentence.
+14. Use a table for data with more than two dimensions.
+15. Use parallel structure in headings and steps.
+16. Repeat the noun. Do not use a pronoun when the reference is unclear.
+
+### 3.4 Adaptation notes (where MOS-STE deviates from ASD-STE100, and why)
+
+- **No licensed dictionary.** ASD-STE100 ships a controlled dictionary under
+  copyright. MOS-STE uses per-project glossaries instead (rule 11).
+- **Domain terms are allowed.** MOS-STE keeps every term the work needs.
+- **Reasoning prose gets structure, not amputation.** Apply the sentence and word
+  rules to design and doctrine writing. Allow the length a subtle argument needs.
+  Readable-first beats rule-strict when the two conflict.
+
+## 4. Code — Google Style Guide
+
+Write source code to the Google Style Guide for the language (Python, TypeScript,
+Shell, Go, and so on). Match the existing file when a local convention already
+exists. Keep code comments to the MOS-STE sentence and word rules.
+
+## 5. User-facing comms — a per-user choice
+
+Mosaic is multi-user. Different users want different comms styles. The framework
+already carries the selectable setting: `communicationStyle` (`direct` |
+`friendly` | `formal`, default `direct`). `mosaic init` writes it, and the
+builder renders it into the generated `USER.md` "Communication Preferences"
+section. This guide adds the OUTPUT meaning of each value; do not invent new
+values.
+
+The builder renders the style as prose bullets, not the token name, so match on
+the leading bullet the generated `USER.md` actually contains:
+
+| `USER.md` leading bullet      | Style              | User-facing output                                                     |
+| ----------------------------- | ------------------ | ---------------------------------------------------------------------- |
+| "Direct and concise"          | `direct` (default) | MOS-STE structure — short, active, defined terms, tables for overview. |
+| "Warm and conversational"     | `friendly`         | Warmer register. Full sentences, explain reasoning, fewer tables.      |
+| "Professional and structured" | `formal`           | Professional and structured. Thorough, with explicit recommendations.  |
+
+This setting governs **user-facing comms only**. It does not change the
+documentation standard (§3), which is always MOS-STE regardless of the value.
+
+## 6. Enforcement
+
+- **Now:** human review only. **No mechanical prose check exists today.** The
+  pre-push gate runs typecheck, lint, build, and tests; it inspects no prose.
+  Reviewers check output against the scope table and the MOS-STE rules by hand.
+- **Future:** an MOS-STE lint check (built from the §3.1 sentence rules) and a
+  Google-style linter in the pre-push gate. A future linter enforces §3.1, not
+  §3.4 — see the note at rule 1.

packages/mosaic/framework/runtime/claude/commands/mosaic-promote.md

@@ -0,0 +1 @@
+Mosaic lease promotion was processed mechanically; no action is needed.

packages/mosaic/framework/runtime/claude/lease-overlay.json

@@ -0,0 +1,89 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$HOME/.config/mosaic/tools/lease-broker/revoke-lease.py\" --runtime claude --reason pre-compact"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$HOME/.config/mosaic/tools/lease-broker/revoke-lease.py\" --runtime claude --reason session-start-compact"
+          }
+        ]
+      },
+      {
+        "matcher": "resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$HOME/.config/mosaic/tools/lease-broker/revoke-lease.py\" --runtime claude --reason session-start-rollover --bump-generation"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "^/mosaic-promote$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.config/mosaic/tools/lease-broker/promote-begin.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.config/mosaic/tools/qa/prevent-memory-write.sh",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.config/mosaic/tools/lease-broker/mutator-gate.py --runtime claude --recovery-command ~/.config/mosaic/tools/lease-broker/recover-context.py",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.config/mosaic/tools/qa/reflect-stop-hook.sh",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.config/mosaic/tools/lease-broker/receipt-observer-client.py --runtime claude --latest-entry; observer_status=$?; python3 ~/.config/mosaic/tools/lease-broker/promote-complete.py; exit $observer_status",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

packages/mosaic/framework/runtime/claude/settings.json

@@ -1,48 +1,7 @@
 {
   "model": "opus",
   "hooks": {
-    "PreCompact": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"$HOME/.config/mosaic/tools/lease-broker/revoke-lease.py\" --runtime claude --reason pre-compact"
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"$HOME/.config/mosaic/tools/lease-broker/revoke-lease.py\" --runtime claude --reason session-start-compact"
-          }
-        ]
-      },
-      {
-        "matcher": "resume|clear",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"$HOME/.config/mosaic/tools/lease-broker/revoke-lease.py\" --runtime claude --reason session-start-rollover --bump-generation"
-          }
-        ]
-      }
-    ],
     "PreToolUse": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ~/.config/mosaic/tools/lease-broker/mutator-gate.py --runtime claude --recovery-command ~/.config/mosaic/tools/lease-broker/recover-context.py",
-            "timeout": 3
-          }
-        ]
-      },
       {
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [
@@ -52,6 +11,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.config/mosaic/tools/git/wrapper-guard.sh",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -79,11 +48,6 @@
     "Stop": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ~/.config/mosaic/tools/lease-broker/receipt-observer-client.py --runtime claude --latest-entry",
-            "timeout": 3
-          },
           {
             "type": "command",
             "command": "~/.config/mosaic/tools/qa/reflect-stop-hook.sh",
@@ -303,5 +267,11 @@
     "cpan",
     "nohup"
   ],
-  "enableAllMcpTools": true
+  "enableAllMcpTools": true,
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
 }

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

@@ -51,12 +51,26 @@ Skills are discovered from:
 
 ### Extensions
 
-The Mosaic Pi extension (`~/.config/mosaic/runtime/pi/mosaic-extension.ts`) handles:
+`mosaic pi` loads framework-owned extensions directly from `~/.config/mosaic/runtime/pi/` in this
+order:
 
-- Session start/end lifecycle hooks
-- Active mission detection and context injection
-- Memory routing to `~/.config/mosaic/memory/`
-- MACP queue status reporting
+1. `mosaic-extension.ts` — session lifecycle, mission context, memory routing, lease/mutator gates,
+   and fleet heartbeat reporting.
+2. `goal-extension.ts` — optional persistent `/goal` controller with per-turn and post-compaction
+   checks.
+
+The goal extension is deployed by Mosaic and MUST NOT be copied into `~/.pi/agent/extensions/`.
+Use `/goal set <statement>` (or `/goal <statement>`) to start, then `/goal status`, `/goal pause`,
+`/goal resume`, or `/goal cancel` to control it. An active goal is injected before every model
+request, restored from branch-specific session entries, and considered achieved only after two
+consecutive evidence-bearing reports. Common credential shapes are redacted before controller-owned
+goal-state entries are persisted or
+displayed; Pi's own model/tool-call history is separate. Goals and reports must contain references
+and pass/fail summaries rather than secrets or raw sensitive output.
+
+- `MOSAIC_GOAL_MAX_TURNS` — autonomous turn limit, default `40`, accepted range `1..500`.
+- `MOSAIC_GOAL_MAX_NO_PROGRESS` — identical no-progress report limit, default `6`, accepted range
+  `1..100`.
 
 ### Sessions
 

packages/mosaic/framework/systemd/user/test-fleet-units.sh

@@ -66,7 +66,10 @@ if command -v tmux >/dev/null 2>&1 && command -v cc >/dev/null 2>&1; then
   trap 'tmux -L "$TEST_SOCKET" kill-server >/dev/null 2>&1 || true; rm -rf "$TEST_ROOT"' EXIT
   MARKER="$TEST_ROOT/loader-marker"
   LIBRARY="$TEST_ROOT/marker.so"
+  FIXTURE_READY="$TEST_ROOT/loader-ready"
+  FIXTURE_FIFO="$TEST_ROOT/loader-block"
   HOLDER_HOME="$TEST_ROOT/holder-home"
+  mkfifo "$FIXTURE_FIFO"
   mkdir -p "$HOLDER_HOME/.config/mosaic/fleet/run"
   chmod 700 "$HOLDER_HOME/.config" "$HOLDER_HOME/.config/mosaic" \
     "$HOLDER_HOME/.config/mosaic/fleet" "$HOLDER_HOME/.config/mosaic/fleet/run"
@@ -87,7 +90,17 @@ __attribute__((constructor)) static void mark_loader(void) {
 EOF
   cc -shared -fPIC -o "$LIBRARY" "$TEST_ROOT/marker.c"
   MOSAIC_LOADER_MARKER="$MARKER" LD_PRELOAD="$LIBRARY" \
-    tmux -L "$TEST_SOCKET" new-session -d -s _holder 'sleep 60'
+    tmux -L "$TEST_SOCKET" new-session -d -s _holder \
+      "touch '$FIXTURE_READY'; read _ < '$FIXTURE_FIFO'"
+  # tmux starts the pane asynchronously. Wait until its contaminated shell has
+  # loaded the constructor and reached a builtin-only FIFO barrier before
+  # clearing the marker; otherwise that expected constructor can race with the
+  # clean holder assertion below and create a false failure.
+  for _attempt in {1..100}; do
+    [ -e "$FIXTURE_READY" ] && break
+    sleep 0.01
+  done
+  [ -e "$FIXTURE_READY" ] || fail "contaminated fixture pane did not become ready"
   [ -s "$MARKER" ] || fail "contaminated fixture did not execute loader constructor"
   server_pid=$(tmux -L "$TEST_SOCKET" display-message -p '#{pid}')
   : > "$MARKER"
@@ -112,6 +125,7 @@ EOF
   chmod 700 "$AGENT_HOME/fleet/agents"
   cat > "$AGENT_HOME/fleet/agents/$AGENT_NAME.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$AGENT_NAME
+MOSAIC_GIT_IDENTITY=$AGENT_NAME
 MOSAIC_AGENT_CLASS=code
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=
@@ -144,7 +158,8 @@ EOF
   /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin \
     MOSAIC_TMUX_SOCKET="$TEST_SOCKET" MOSAIC_TMUX_HOLDER=_holder "$HOLDER_START"
   tmux -L "$TEST_SOCKET" has-session -t '=_holder:0.0' || fail "fresh holder was not created"
-  if tmux -L "$TEST_SOCKET" show-environment -g LD_PRELOAD 2>/dev/null | grep -q '^LD_PRELOAD='; then
+  ld_preload_env="$(tmux -L "$TEST_SOCKET" show-environment -g LD_PRELOAD 2>/dev/null)" || true
+  if grep -q '^LD_PRELOAD=' <<<"$ld_preload_env"; then
     fail "fresh holder retained LD_PRELOAD"
   fi
   /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin MOSAIC_HOME="$AGENT_HOME" \

packages/mosaic/framework/tools/_lib/manifest.sh

@@ -69,7 +69,7 @@ _manifest_glob_to_ere() {
           out="$out.*"
         fi
       else
-        out="$out[^/]*"
+        out="${out}[^/]*"
       fi
     else
       case "$c" in
@@ -87,7 +87,8 @@ _manifest_compile_one() {
   local norm; norm="$(_manifest_norm "$1")"
   [[ -n "$norm" ]] || return 0
   if [[ "$norm" == *"*"* ]]; then
-    local re="^$(_manifest_glob_to_ere "$norm")\$"
+    local re
+    re="^$(_manifest_glob_to_ere "$norm")\$"
     if [[ "$2" == F ]]; then
       _MF_KIND+=(re); _MF_EXACT+=(""); _MF_RE+=("$re")
     else
@@ -183,7 +184,10 @@ _mo_matches() {
   for (( i = 0; i < n; i++ )); do
     if [[ "${_MO_KIND[i]}" == exact ]]; then
       pat="${_MO_EXACT[i]}"
-      [[ "$path" == "$pat" || "$path" == "$pat/"* ]] && return 0
+      # Operator exact entries are file carve-outs, not implicit directory
+      # prefixes. Subtree ownership must be declared explicitly as `dir/**`;
+      # otherwise one bare directory entry can hide all drift beneath it.
+      [[ "$path" == "$pat" ]] && return 0
     else
       re="${_MO_RE[i]}"
       [[ "$path" =~ $re ]] && return 0

packages/mosaic/framework/tools/_scripts/mosaic-doctor

@@ -153,6 +153,38 @@ warn_if_symlink_tree_present() {
 
 echo "[mosaic-doctor] Mosaic home: $MOSAIC_HOME"
 
+# Compare the framework tools that this CLI/package ships with the deployed
+# ~/.config copy that direct wrappers and systemd units actually execute. Doctor
+# is the right boundary: observational, operator-invoked, and already designed
+# to report drift without mutating live tooling or restarting active seats.
+framework_drift_checker="$(cd -- "$(dirname -- "$0")/../quality/scripts" && pwd)/framework-drift-check.py"
+if [[ -f "$framework_drift_checker" ]]; then
+  echo "[mosaic-doctor] Checking installed framework-tool drift..."
+  drift_timeout="${MOSAIC_DOCTOR_DRIFT_TIMEOUT_SEC:-15}"
+  if ! [[ "$drift_timeout" =~ ^[1-9][0-9]*$ ]]; then
+    warn "Invalid MOSAIC_DOCTOR_DRIFT_TIMEOUT_SEC='$drift_timeout' (expected positive integer); using 15s"
+    drift_timeout=15
+  fi
+  if command -v timeout >/dev/null 2>&1; then
+    set +e
+    timeout -s TERM -k 2 "${drift_timeout}s" \
+      python3 "$framework_drift_checker" --installed-root "$MOSAIC_HOME/tools"
+    drift_rc=$?
+    set -e
+    if [[ "$drift_rc" -eq 0 ]]; then
+      pass "Installed framework tools match shipped source"
+    elif [[ "$drift_rc" -eq 124 || "$drift_rc" -eq 137 || "$drift_rc" -eq 143 ]]; then
+      warn "CANNOT_ASSERT framework drift checker timed out after ${drift_timeout}s; continuing remaining doctor checks"
+    else
+      warn "Installed framework-tool drift detected (checker exit $drift_rc; no files changed)"
+    fi
+  else
+    warn "CANNOT_ASSERT timeout utility unavailable; refusing unbounded framework drift check and continuing remaining doctor checks"
+  fi
+else
+  warn "Framework drift checker is absent from the shipped tools tree"
+fi
+
 # Canonical Mosaic checks
 expect_file "$MOSAIC_HOME/STANDARDS.md"
 expect_file "$MOSAIC_HOME/USER.md"

packages/mosaic/framework/tools/_scripts/mosaic-ensure-sequential-thinking

@@ -5,6 +5,7 @@ MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 MODE="apply"
 RUNTIME="all"
 STRICT_CHECK=0
+CLAUDE_CONFIG_DIR=""
 
 PKG="@modelcontextprotocol/server-sequential-thinking"
 
@@ -29,6 +30,14 @@ while [[ $# -gt 0 ]]; do
       STRICT_CHECK=1
       shift
       ;;
+    --claude-config-dir)
+      if [[ $# -lt 2 ]]; then
+        err "--claude-config-dir requires an absolute seat config directory"
+        exit 2
+      fi
+      CLAUDE_CONFIG_DIR="$2"
+      shift 2
+      ;;
     *)
       err "Unknown argument: $1"
       exit 2
@@ -67,11 +76,19 @@ warm_package() {
 }
 
 check_claude_config() {
-  python3 - <<'PY'
+  CLAUDE_CONFIG_DIR="$CLAUDE_CONFIG_DIR" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".claude" / "settings.json"
-if not p.exists():
+# Claude reads MCP definitions from .claude.json, not settings.json. The
+# settings.json fallback preserves legacy operator flows until their config is migrated.
+config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
+p = Path(config_dir) / ".claude.json" if config_dir else Path.home() / ".claude.json"
+if not p.exists() and not config_dir:
+    p = Path.home() / ".claude" / "settings.json"
+# Only explicit fleet seats require a private, non-symlink config. Operator
+# config remains compatible with pre-existing permission conventions.
+if not p.exists() or p.is_symlink() or (config_dir and (p.stat().st_mode & 0o077) != 0):
     raise SystemExit(1)
 try:
     data = json.loads(p.read_text(encoding="utf-8"))
@@ -92,10 +109,15 @@ PY
 }
 
 apply_claude_config() {
-  python3 - <<'PY'
+  CLAUDE_CONFIG_DIR="$CLAUDE_CONFIG_DIR" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".claude" / "settings.json"
+# Claude reads MCP definitions from .claude.json for both operator and
+# explicitly isolated fleet config dirs. The checker retains a settings.json
+# fallback only to avoid breaking legacy operator configurations.
+config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
+p = Path(config_dir) / ".claude.json" if config_dir else Path.home() / ".claude.json"
 p.parent.mkdir(parents=True, exist_ok=True)
 if p.exists():
     try:
@@ -117,7 +139,7 @@ PY
 }
 
 check_codex_config() {
-  local cfg="$HOME/.codex/config.toml"
+  local cfg="${CODEX_HOME:-$HOME/.codex}/config.toml"
   [[ -f "$cfg" ]] || return 1
   grep -Eq '^\[mcp_servers\.(sequential-thinking|sequential_thinking)\]' "$cfg" && \
   grep -q '^command = "npx"' "$cfg" && \
@@ -125,7 +147,7 @@ check_codex_config() {
 }
 
 apply_codex_config() {
-  local cfg="$HOME/.codex/config.toml"
+  local cfg="${CODEX_HOME:-$HOME/.codex}/config.toml"
   mkdir -p "$(dirname "$cfg")"
   [[ -f "$cfg" ]] || touch "$cfg"
 
@@ -148,10 +170,11 @@ apply_codex_config() {
 }
 
 check_opencode_config() {
-  python3 - <<'PY'
+  XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-}" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".config" / "opencode" / "config.json"
+p = Path(os.environ["XDG_CONFIG_HOME"]) / "opencode" / "config.json" if os.environ.get("XDG_CONFIG_HOME") else Path.home() / ".config" / "opencode" / "config.json"
 if not p.exists():
     raise SystemExit(1)
 try:
@@ -174,10 +197,11 @@ PY
 }
 
 apply_opencode_config() {
-  python3 - <<'PY'
+  XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-}" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".config" / "opencode" / "config.json"
+p = Path(os.environ["XDG_CONFIG_HOME"]) / "opencode" / "config.json" if os.environ.get("XDG_CONFIG_HOME") else Path.home() / ".config" / "opencode" / "config.json"
 p.parent.mkdir(parents=True, exist_ok=True)
 if p.exists():
     try:

packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets

@@ -233,6 +233,14 @@ for runtime_file in \
   copy_file_managed "$src" "$HOME/.claude/$runtime_file"
 done
 
+if [[ -d "$MOSAIC_HOME/runtime/claude/commands" ]]; then
+  mkdir -p "$HOME/.claude/commands"
+  for command_file in "$MOSAIC_HOME/runtime/claude/commands/"*; do
+    [[ -f "$command_file" ]] || continue
+    copy_file_managed "$command_file" "$HOME/.claude/commands/$(basename "$command_file")"
+  done
+fi
+
 # OpenCode runtime adapter (thin pointer to AGENTS.md)
 opencode_adapter="$MOSAIC_HOME/runtime/opencode/AGENTS.md"
 if [[ -f "$opencode_adapter" ]]; then

packages/mosaic/framework/tools/_scripts/mosaic-sync-skills

@@ -153,7 +153,24 @@ if [[ $link_only -eq 1 ]]; then
   exit 0
 fi
 
+# Skills are linked into the MOSAIC-OWNED harness homes, never a base install.
+# Paths mirror the config-dir env vars the launcher injects (HARNESS_HOME_ENV in
+# commands/launch.js):
+#   claude   CLAUDE_CONFIG_DIR      -> <home>/skills
+#   pi       PI_CODING_AGENT_DIR    -> <home>/skills   (replaces ~/.pi/agent)
+#   codex    CODEX_HOME             -> <home>/skills
+#   opencode XDG_CONFIG_HOME        -> <home>/opencode/skills  (XDG adds a level)
 link_targets=(
+  "$MOSAIC_HOME/.claude/skills"
+  "$MOSAIC_HOME/.codex/skills"
+  "$MOSAIC_HOME/.opencode/opencode/skills"
+  "$MOSAIC_HOME/.pi/skills"
+)
+
+# Pre-isolation installs planted the same symlink farm directly in the operator's
+# base installs. Those are now orphaned: the launcher no longer reads them, but
+# they persist and make a "clean" base install look mosaic-managed.
+legacy_link_targets=(
   "$HOME/.claude/skills"
   "$HOME/.codex/skills"
   "$HOME/.config/opencode/skills"
@@ -245,13 +262,72 @@ prune_stale_links_in_target() {
     # -m resolves lexical dangling targets too. If resolution fails, ownership
     # is unproven and the link must be preserved.
     resolved="$(readlink -m "$link_path" 2>/dev/null || true)"
-    if [[ -n "$resolved" && "$resolved" == "$canonical_real/"* ]]; then
+    # $canonical_real must be length-checked BEFORE use as a prefix: if it were
+    # ever empty, "$resolved" == "$canonical_real/"* collapses to == "/"* and
+    # matches every absolute path. Combined with the is_mosaic_skill_name skip
+    # above, that inverts the function precisely — it would delete exactly the
+    # FOREIGN symlinks and keep the mosaic ones. (#1087, reported by mos-claude.)
+    if [[ -n "$resolved" && -n "$canonical_real" && "$resolved" == "$canonical_real/"* ]]; then
       rm -f "$link_path"
       echo "[mosaic-skills] Removed stale retired skill link: $link_path"
     fi
   done < <(find "$target_dir" -mindepth 1 -maxdepth 1 -type l -print0)
 }
 
+# Remove mosaic-owned symlinks left in a base install by a pre-isolation sync.
+#
+# Ownership is proven by RESOLUTION, not by name: only links resolving inside the
+# canonical or local skills dirs are removed. Anything else — a real directory, a
+# link elsewhere, an unresolvable link — is left untouched. This mirrors the
+# refusal in commands/skill.js ("only symlinks pointing inside the Mosaic skills
+# directory are managed") and preserves e.g. codex's own `.system` dir.
+#
+# The directory itself is kept: mosaic-doctor warns when ~/.pi/agent/skills is
+# missing, and an empty dir is the correct end state, not an absent one.
+cleanup_legacy_target() {
+  local target_dir="$1"
+  local removed=0 kept=0
+
+  [[ -d "$target_dir" ]] || return 0
+
+  while IFS= read -r -d '' link_path; do
+    local resolved owned=0
+    resolved="$(readlink -m "$link_path" 2>/dev/null || true)"
+
+    # Guard the empty-prefix trap: an unset *_real would make "$resolved" == "/"*
+    # match every absolute path and delete foreign links.
+    if [[ -n "$resolved" ]]; then
+      if [[ -n "$canonical_real" && "$resolved" == "$canonical_real/"* ]]; then
+        owned=1
+      elif [[ -n "$local_real" && "$resolved" == "$local_real/"* ]]; then
+        owned=1
+      fi
+    fi
+
+    if [[ $owned -eq 1 ]]; then
+      rm -f "$link_path"
+      removed=$((removed + 1))
+    else
+      kept=$((kept + 1))
+    fi
+  done < <(find "$target_dir" -mindepth 1 -maxdepth 1 -type l -print0)
+
+  if [[ $removed -gt 0 ]]; then
+    echo "[mosaic-skills] Legacy cleanup: removed $removed mosaic symlink(s) from $target_dir (preserved $kept foreign)"
+  fi
+}
+
+for legacy in "${legacy_link_targets[@]}"; do
+  # Skip anything that is also a current target, so isolation can never
+  # self-destruct if the two lists ever overlap.
+  skip=0
+  for target in "${link_targets[@]}"; do
+    [[ "$legacy" == "$target" ]] && skip=1
+  done
+  [[ $skip -eq 1 ]] && continue
+  cleanup_legacy_target "$legacy"
+done
+
 for target in "${link_targets[@]}"; do
   mkdir -p "$target"
 

packages/mosaic/framework/tools/authentik/user-create.sh

@@ -69,7 +69,7 @@ if [[ -n "$GROUP" ]]; then
   group_response=$(curl -sk \
     -H "Authorization: Bearer $TOKEN" \
     "${AUTHENTIK_URL}/api/v3/core/groups/?search=${GROUP}")
-  group_pk=$(echo "$group_response" | jq -r ".results[] | select(.name == \"$GROUP\") | .pk" | head -1)
+  group_pk=$(jq -r "first(.results[] | select(.name == \"$GROUP\") | .pk) // empty" <<<"$group_response")
   if [[ -n "$group_pk" ]]; then
     payload=$(echo "$payload" | jq --arg gk "$group_pk" '. + {groups: [$gk]}')
   else

packages/mosaic/framework/tools/fleet/start-agent-session.sh

@@ -97,7 +97,7 @@ is_sensitive_key() {
 
 is_generated_key() {
   case "$1" in
-    MOSAIC_AGENT_NAME|MOSAIC_AGENT_CLASS|MOSAIC_AGENT_RUNTIME|MOSAIC_AGENT_MODEL|MOSAIC_AGENT_REASONING|MOSAIC_AGENT_TOOL_POLICY|MOSAIC_AGENT_WORKDIR|MOSAIC_TMUX_SOCKET) return 0 ;;
+    MOSAIC_AGENT_NAME|MOSAIC_GIT_IDENTITY|MOSAIC_AGENT_CLASS|MOSAIC_AGENT_RUNTIME|MOSAIC_AGENT_MODEL|MOSAIC_AGENT_REASONING|MOSAIC_AGENT_TOOL_POLICY|MOSAIC_AGENT_WORKDIR|MOSAIC_TMUX_SOCKET) return 0 ;;
     *) return 1 ;;
   esac
 }
@@ -114,6 +114,7 @@ validate_generated_value() {
   local value="$2"
   case "$key" in
     MOSAIC_AGENT_NAME) safe_agent_name "$value" || fail_env unsafe-agent-name "$key" "$value" ;;
+    MOSAIC_GIT_IDENTITY) safe_agent_name "$value" || fail_env unsafe-git-identity "$key" "$value" ;;
     MOSAIC_AGENT_CLASS) safe_policy_name "$value" || fail_env unsafe-class "$key" "$value" ;;
     MOSAIC_AGENT_RUNTIME)
       case "$value" in claude|codex|opencode|pi) ;; *) fail_env unsupported-runtime "$key" "$value" ;; esac
@@ -175,7 +176,7 @@ load_environment_file() {
 
 load_environment_file "$GENERATED_ENV" generated
 for required_key in \
-  MOSAIC_AGENT_NAME MOSAIC_AGENT_CLASS MOSAIC_AGENT_RUNTIME MOSAIC_AGENT_MODEL \
+  MOSAIC_AGENT_NAME MOSAIC_GIT_IDENTITY MOSAIC_AGENT_CLASS MOSAIC_AGENT_RUNTIME MOSAIC_AGENT_MODEL \
   MOSAIC_AGENT_REASONING MOSAIC_AGENT_TOOL_POLICY MOSAIC_AGENT_WORKDIR MOSAIC_TMUX_SOCKET; do
   [ -n "${GENERATED_VALUES[$required_key]+set}" ] || fail_env missing-key "$required_key" ''
 done
@@ -183,12 +184,15 @@ load_environment_file "$LOCAL_ENV" local
 
 [ "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}" = "$AGENT_NAME" ] || \
   fail_env agent-name-mismatch MOSAIC_AGENT_NAME "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}"
+[ "${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}" = "$AGENT_NAME" ] || \
+  fail_env git-identity-mismatch MOSAIC_GIT_IDENTITY "${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}"
 
 MOSAIC_TMUX_SOCKET=${GENERATED_VALUES[MOSAIC_TMUX_SOCKET]}
 MOSAIC_AGENT_RUNTIME=${GENERATED_VALUES[MOSAIC_AGENT_RUNTIME]}
 MOSAIC_AGENT_MODEL=${GENERATED_VALUES[MOSAIC_AGENT_MODEL]}
 MOSAIC_AGENT_REASONING=${GENERATED_VALUES[MOSAIC_AGENT_REASONING]}
 MOSAIC_AGENT_WORKDIR=${GENERATED_VALUES[MOSAIC_AGENT_WORKDIR]}
+MOSAIC_GIT_IDENTITY=${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}
 MOSAIC_AGENT_CLASS=${GENERATED_VALUES[MOSAIC_AGENT_CLASS]}
 MOSAIC_AGENT_TOOL_POLICY=${GENERATED_VALUES[MOSAIC_AGENT_TOOL_POLICY]}
 MOSAIC_RUNTIME_BIN=${LOCAL_VALUES[MOSAIC_RUNTIME_BIN]:-}
@@ -286,12 +290,24 @@ _build_runtime_bin_prefix() {
 MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
 PANE_PATH=${MOSAIC_RUNTIME_BIN_PREFIX:+${MOSAIC_RUNTIME_BIN_PREFIX}:}/usr/local/bin:/usr/bin:/bin
 
+# A seat scaffolded by `mosaic fleet agent new` owns its harness home, settings
+# overlay and auth bundle; launching it through `mosaic fleet launch` is what makes
+# ~/.mosaic real for a roster-started pane instead of a directory nothing reads.
+# Detection uses $PANE_HOME/.mosaic because the pane environment is cleared below,
+# so `mosaic fleet launch` resolves the same root from HOME and the two agree.
+FLEET_SEAT_DIR="$PANE_HOME/.mosaic/fleet/agents/$AGENT_NAME"
+FLEET_SEAT=0
+[ -f "$FLEET_SEAT_DIR/profile.json" ] && FLEET_SEAT=1
+
 _ensure_claude_workdir_trusted() {
   local workdir="$1"
+  local claude_json="$2"
   local resolved
   resolved=$(cd "$workdir" 2>/dev/null && pwd -P) || resolved="$workdir"
-  local claude_json="${MOSAIC_CLAUDE_JSON:-${CLAUDE_CONFIG_DIR:+$CLAUDE_CONFIG_DIR/.claude.json}}"
-  claude_json="${claude_json:-$HOME/.claude.json}"
+  if [ -z "$claude_json" ]; then
+    claude_json="${MOSAIC_CLAUDE_JSON:-${CLAUDE_CONFIG_DIR:+$CLAUDE_CONFIG_DIR/.claude.json}}"
+    claude_json="${claude_json:-$HOME/.claude.json}"
+  fi
   command -v python3 >/dev/null 2>&1 || return 1
   MOSAIC_CJ="$claude_json" MOSAIC_TRUST_DIR="$resolved" python3 - <<'PY'
 import json, os, sys, tempfile
@@ -325,11 +341,23 @@ PY
 }
 
 if [ "$MOSAIC_AGENT_RUNTIME" = claude ]; then
-  _ensure_claude_workdir_trusted "$MOSAIC_AGENT_WORKDIR" || \
+  # Trust belongs to the home the seat will actually run in. Writing it to the
+  # operator's ~/.claude.json would leave the seat prompting on its first turn.
+  SEAT_CLAUDE_JSON=""
+  if [ "$FLEET_SEAT" = 1 ] && [ -d "$FLEET_SEAT_DIR/.claude" ]; then
+    SEAT_CLAUDE_JSON="$FLEET_SEAT_DIR/.claude/.claude.json"
+  fi
+  _ensure_claude_workdir_trusted "$MOSAIC_AGENT_WORKDIR" "$SEAT_CLAUDE_JSON" || \
     echo "WARNING: could not pre-trust workdir for claude agent $AGENT_NAME" >&2
 fi
 
-LAUNCH_COMMAND=(mosaic yolo "$MOSAIC_AGENT_RUNTIME")
+if [ "$FLEET_SEAT" = 1 ]; then
+  # --dangerous keeps the seat on the same permissions footing `mosaic yolo` gave it;
+  # the composition, not the roster, decides harness home, bundle and settings.
+  LAUNCH_COMMAND=(mosaic fleet launch "$AGENT_NAME" --dangerous)
+else
+  LAUNCH_COMMAND=(mosaic yolo "$MOSAIC_AGENT_RUNTIME")
+fi
 if [ -n "$MOSAIC_AGENT_MODEL" ]; then LAUNCH_COMMAND+=(--model "$MOSAIC_AGENT_MODEL"); fi
 if [ -n "$MOSAIC_AGENT_REASONING" ]; then LAUNCH_COMMAND+=(--thinking "$MOSAIC_AGENT_REASONING"); fi
 
@@ -343,6 +371,7 @@ LAUNCH_ENV=(
   "PATH=$PANE_PATH"
   "MOSAIC_HOME=$MOSAIC_HOME"
   "MOSAIC_AGENT_NAME=$AGENT_NAME"
+  "MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"
   "MOSAIC_AGENT_CLASS=$MOSAIC_AGENT_CLASS"
   "MOSAIC_AGENT_RUNTIME=$MOSAIC_AGENT_RUNTIME"
   "MOSAIC_AGENT_MODEL=$MOSAIC_AGENT_MODEL"

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh

@@ -14,6 +14,82 @@ fail() {
   exit 1
 }
 
+pane_command_clears_environment() {
+  local calls_file="$1"
+  local -a argv=()
+  local index
+  mapfile -d '' -t argv < "$calls_file"
+  for ((index = 0; index + 1 < ${#argv[@]}; index++)); do
+    if [ "${argv[$index]}" = /usr/bin/env ] && [ "${argv[$((index + 1))]}" = -i ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+print_pane_argv() {
+  local calls_file="$1"
+  local -a argv=()
+  local bytes index
+  mapfile -d '' -t argv < "$calls_file"
+  bytes=$(wc -c < "$calls_file")
+  printf 'observed pane argv: records=%s bytes=%s\n' "${#argv[@]}" "$bytes" >&2
+  for ((index = 0; index < ${#argv[@]}; index++)); do
+    printf '  [%03d] %q\n' "$index" "${argv[$index]}" >&2
+  done
+}
+
+check_pane_environment_boundary() {
+  local calls_file="$1"
+  if pane_command_clears_environment "$calls_file"; then
+    return 0
+  fi
+  print_pane_argv "$calls_file"
+  return 1
+}
+
+contains_literal() {
+  grep -F -- "$2" <<< "$1" >/dev/null
+}
+
+contains_line() {
+  grep -xF -- "$2" <<< "$1" >/dev/null
+}
+
+# Portability regression: inspect the authoritative NUL-delimited argv instead
+# of piping a newline reconstruction through `grep -q` under pipefail. The old
+# pipeline could report failure after a successful match when an upstream
+# producer received SIGPIPE. A large trailing argument keeps that failure class
+# covered without making stream size part of the semantic contract.
+PORTABILITY_CALLS="$ROOT/portability-calls"
+printf -v PORTABILITY_PADDING '%*s' 32768 ''
+PORTABILITY_PADDING=${PORTABILITY_PADDING// /x}
+printf '%s\0' /usr/bin/env -i "$PORTABILITY_PADDING" > "$PORTABILITY_CALLS"
+pane_command_clears_environment "$PORTABILITY_CALLS" || \
+  fail "valid large pane argv was rejected by the environment-boundary assertion"
+
+assert_pane_boundary_rejected() {
+  local case_name="$1"
+  local expected_records="$2"
+  local diagnostic
+  if diagnostic=$(check_pane_environment_boundary "$PORTABILITY_CALLS" 2>&1); then
+    fail "pane boundary accepted invalid $case_name fixture"
+  fi
+  contains_literal "$diagnostic" "records=$expected_records bytes=" || \
+    fail "pane argv diagnostic omitted counts for $case_name fixture"
+  contains_literal "$diagnostic" '[000]' || \
+    fail "pane argv diagnostic omitted indexed arguments for $case_name fixture"
+}
+
+printf '%s\0' tmux -i > "$PORTABILITY_CALLS"
+assert_pane_boundary_rejected missing-env 2
+printf '%s\0' /usr/bin/env HOME=/untrusted > "$PORTABILITY_CALLS"
+assert_pane_boundary_rejected missing-i 2
+printf '%s\0' /usr/bin/env HOME=/untrusted -i > "$PORTABILITY_CALLS"
+assert_pane_boundary_rejected non-adjacent-i 3
+printf '%s\0' -i /usr/bin/env > "$PORTABILITY_CALLS"
+assert_pane_boundary_rejected reversed-boundary 2
+
 cat > "$FAKE_BIN/tmux" <<'SHIM'
 #!/usr/bin/env bash
 set -euo pipefail
@@ -62,6 +138,19 @@ env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
 SHIM
 chmod +x "$FAKE_BIN/mosaic"
 
+# Freeze numeric epoch reads only when a test arm supplies an observation bound.
+# Formatting reads still use the real BusyBox/POSIX date implementation.
+cat > "$FAKE_BIN/date" <<'SHIM'
+#!/usr/bin/env bash
+set -euo pipefail
+if [ -n "${MOSAIC_TEST_FIXED_EPOCH:-}" ] && [ "${1:-}" = '+%s' ]; then
+  printf '%s\n' "$MOSAIC_TEST_FIXED_EPOCH"
+  exit 0
+fi
+exec /bin/date "$@"
+SHIM
+chmod +x "$FAKE_BIN/date"
+
 write_generated() {
   local home="$1"
   local agent="$2"
@@ -71,6 +160,7 @@ write_generated() {
   chmod 600 "$home/fleet/run/holder-owner"
   cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
+MOSAIC_GIT_IDENTITY=$agent
 MOSAIC_AGENT_CLASS=code
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=openai-codex/gpt-5.6-sol
@@ -88,6 +178,7 @@ run_start() {
   local agent="$2"
   HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
     MOSAIC_TEST_PANE_PID="${MOSAIC_TEST_PANE_PID:-}" \
+    MOSAIC_TEST_FIXED_EPOCH="${MOSAIC_TEST_FIXED_EPOCH:-}" \
     MOSAIC_TEST_HOME="$home" \
     MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
     MOSAIC_HOME="$home" "$START" "$agent"
@@ -100,19 +191,55 @@ AGENT_VALID="coder0"
 write_generated "$HOME_VALID" "$AGENT_VALID"
 run_start "$HOME_VALID" "$AGENT_VALID"
 valid_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$valid_args" | grep -qF new-session || fail "valid generated projection did not reach tmux"
-echo "$valid_args" | grep -qF 'mosaic' || fail "fixed mosaic launcher command missing"
-echo "$valid_args" | grep -qF 'yolo' || fail "fixed yolo launcher command missing"
-echo "$valid_args" | grep -qF 'pi' || fail "roster runtime missing"
-if echo "$valid_args" | grep -qF 'bash -c'; then
+contains_literal "$valid_args" new-session || fail "valid generated projection did not reach tmux"
+contains_literal "$valid_args" mosaic || fail "fixed mosaic launcher command missing"
+contains_literal "$valid_args" yolo || fail "fixed yolo launcher command missing"
+contains_literal "$valid_args" pi || fail "roster runtime missing"
+if contains_literal "$valid_args" 'bash -c'; then
   fail "launcher constructed a shell command payload"
 fi
 
 # The pane must start through an absolute clean-environment boundary. Its
 # runtime command remains an argv vector, but no holder/session environment
 # control variable can pass through the pane command.
-echo "$valid_args" | grep -qxF '/usr/bin/env' || fail "pane does not use absolute env"
-echo "$valid_args" | grep -qxF -- '-i' || fail "pane environment is not cleared"
+check_pane_environment_boundary "$TMUX_CALLS" || \
+  fail "pane command did not use an adjacent /usr/bin/env -i boundary"
+
+# Git identity is generated authority, not an optional or independently mutable
+# local value. Each invalid form must fail before fake tmux receives a call.
+assert_git_identity_rejected() {
+  local case_name="$1"
+  local expected_code="$2"
+  local home="$ROOT/git-identity-$case_name"
+  local agent="coder-git-identity-$case_name"
+  local generated="$home/fleet/agents/$agent.env.generated"
+  write_generated "$home" "$agent"
+
+  case "$case_name" in
+    missing) grep -v '^MOSAIC_GIT_IDENTITY=' "$generated" > "$generated.next" && mv "$generated.next" "$generated" ;;
+    unsafe) sed -i 's|^MOSAIC_GIT_IDENTITY=.*$|MOSAIC_GIT_IDENTITY=bad/identity|' "$generated" ;;
+    mismatch) sed -i 's|^MOSAIC_GIT_IDENTITY=.*$|MOSAIC_GIT_IDENTITY=other-agent|' "$generated" ;;
+    local-shadow)
+      printf 'MOSAIC_GIT_IDENTITY=%s\n' "$agent" > "$home/fleet/agents/$agent.env.local"
+      chmod 600 "$home/fleet/agents/$agent.env.local"
+      ;;
+    *) fail "unknown Git identity rejection case: $case_name" ;;
+  esac
+  chmod 600 "$generated"
+
+  : > "$TMUX_CALLS"
+  if output=$(run_start "$home" "$agent" 2>&1); then
+    fail "Git identity case $case_name was accepted"
+  fi
+  [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before Git identity $case_name rejection"
+  contains_literal "$output" "code=$expected_code" || \
+    fail "Git identity $case_name diagnostic omitted code $expected_code"
+}
+
+assert_git_identity_rejected missing missing-key
+assert_git_identity_rejected unsafe unsafe-git-identity
+assert_git_identity_rejected mismatch git-identity-mismatch
+assert_git_identity_rejected local-shadow generated-key-shadow
 
 # The generated-file parent is a security boundary too: even a private regular
 # file is untrusted if its parent can be replaced or written by another user.
@@ -125,7 +252,7 @@ if output=$(run_start "$HOME_UNSAFE_PARENT" coder-parent 2>&1); then
   fail "generated file under a world-writable parent was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before unsafe parent rejection"
-echo "$output" | grep -qF 'code=unsafe-permissions' || fail "unsafe parent diagnostic missing"
+contains_literal "$output" 'code=unsafe-permissions' || fail "unsafe parent diagnostic missing"
 
 : > "$TMUX_CALLS"
 HOME_SYMLINK_PARENT="$ROOT/symlink-parent"
@@ -136,7 +263,7 @@ if output=$(run_start "$HOME_SYMLINK_PARENT" coder-symlink-parent 2>&1); then
   fail "generated file under a symlinked parent was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before symlinked parent rejection"
-echo "$output" | grep -qF 'code=unsafe-directory' || fail "symlinked parent diagnostic missing"
+contains_literal "$output" 'code=unsafe-directory' || fail "symlinked parent diagnostic missing"
 
 # Every managed ancestor is a boundary: MOSAIC_HOME, fleet, and agents. A
 # symlink or group/world-writable ancestor must fail before environment parsing,
@@ -174,8 +301,8 @@ assert_managed_ancestor_rejected() {
   fi
   [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before $hazard $ancestor rejection"
   [ ! -e "$home/work" ] || fail "workdir was created before $hazard $ancestor rejection"
-  echo "$output" | grep -qF "code=unsafe-" || fail "managed ancestor diagnostic missing"
-  if echo "$output" | grep -qF 'key=MOSAIC_AGENT_COMMAND'; then
+  contains_literal "$output" 'code=unsafe-' || fail "managed ancestor diagnostic missing"
+  if contains_literal "$output" 'key=MOSAIC_AGENT_COMMAND'; then
     fail "environment parsing ran before $hazard $ancestor rejection"
   fi
 }
@@ -196,9 +323,9 @@ if output=$(run_start "$HOME_SHADOW" coder1 2>&1); then
   fail "generated-key shadow was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before generated-key shadow rejection"
-echo "$output" | grep -qF 'key=MOSAIC_AGENT_RUNTIME' || fail "shadow diagnostic omitted key"
-echo "$output" | grep -qF 'sha256=' || fail "shadow diagnostic omitted hash"
-if echo "$output" | grep -qF 'codex'; then
+contains_literal "$output" 'key=MOSAIC_AGENT_RUNTIME' || fail "shadow diagnostic omitted key"
+contains_literal "$output" 'sha256=' || fail "shadow diagnostic omitted hash"
+if contains_literal "$output" codex; then
   fail "shadow diagnostic leaked value"
 fi
 
@@ -214,9 +341,9 @@ if output=$(run_start "$HOME_COMMAND" coder2 2>&1); then
   fail "arbitrary command override was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before command rejection"
-echo "$output" | grep -qF 'key=MOSAIC_AGENT_COMMAND' || fail "command diagnostic omitted key"
-echo "$output" | grep -qF 'sha256=' || fail "command diagnostic omitted hash"
-if echo "$output" | grep -qF "$COMMAND_VALUE"; then
+contains_literal "$output" 'key=MOSAIC_AGENT_COMMAND' || fail "command diagnostic omitted key"
+contains_literal "$output" 'sha256=' || fail "command diagnostic omitted hash"
+if contains_literal "$output" "$COMMAND_VALUE"; then
   fail "command diagnostic leaked command value"
 fi
 
@@ -230,7 +357,7 @@ if output=$(run_start "$HOME_PERMS" coder3 2>&1); then
   fail "world-readable local input was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before permissions rejection"
-echo "$output" | grep -qF 'code=unsafe-permissions' || fail "permission diagnostic missing"
+contains_literal "$output" 'code=unsafe-permissions' || fail "permission diagnostic missing"
 
 # A unit/holder-like clean bootstrap must yield a pane with trusted HOME and
 # computed PATH only. The pane command itself must not carry loader, shell
@@ -260,25 +387,35 @@ PATH="$PANE_STALE_PATH" \
     MOSAIC_TEST_EXECUTE_PANE=1 \
     "$START" coder-pane-boundary
 pane_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$pane_args" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
+contains_line "$pane_args" "HOME=$PANE_TRUSTED_HOME" || \
   fail "pane did not restore trusted HOME"
-echo "$pane_args" | grep -qF "HOME=$PANE_STALE_HOME" && \
+contains_literal "$pane_args" "HOME=$PANE_STALE_HOME" && \
   fail "pane inherited stale HOME"
-echo "$pane_args" | grep -qF "$PANE_STALE_PATH" && fail "pane inherited stale PATH"
+contains_literal "$pane_args" "$PANE_STALE_PATH" && fail "pane inherited stale PATH"
 for blocked in LD_PRELOAD= BASH_ENV= MOSAIC_UNTRUSTED_SENTINEL=; do
-  echo "$pane_args" | grep -qF "$blocked" && fail "pane inherited $blocked"
+  contains_literal "$pane_args" "$blocked" && fail "pane inherited $blocked"
 done
 
-after_pane_env=$(printf '%s\n' "$pane_args" | grep -n -m1 -F '/usr/bin/env' | cut -d: -f1)
-[ -n "$after_pane_env" ] || fail "pane command did not use absolute env"
-printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i' || \
-  fail "pane command did not clear its environment"
+check_pane_environment_boundary "$TMUX_CALLS" || \
+  fail "pane command did not use an adjacent /usr/bin/env -i boundary"
 pane_environment=$(tr '\0' '\n' < "$HOME_PANE_BOUNDARY/fleet/pane-environment")
-echo "$pane_environment" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
+# Exercise the repository launcher at $START, not the independently installed
+# host copy. Set-compare every declared generated projection entry with the
+# launched process environment so a newly declared identity cannot be omitted
+# by a hand-maintained per-variable assertion.
+declared_generated_environment=$(sort "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.generated")
+missing_or_changed_generated_environment=$(comm -23 \
+  <(printf '%s\n' "$declared_generated_environment") \
+  <(printf '%s\n' "$pane_environment" | sort))
+if [ -n "$missing_or_changed_generated_environment" ]; then
+  missing_or_changed_keys=$(printf '%s\n' "$missing_or_changed_generated_environment" | cut -d= -f1 | paste -sd, -)
+  fail "runtime pane omitted or changed generated environment keys: $missing_or_changed_keys"
+fi
+contains_line "$pane_environment" "HOME=$PANE_TRUSTED_HOME" || \
   fail "runtime pane did not receive trusted HOME"
-echo "$pane_environment" | grep -qF "$PANE_STALE_PATH" && fail "runtime pane received stale PATH"
+contains_literal "$pane_environment" "$PANE_STALE_PATH" && fail "runtime pane received stale PATH"
 for blocked in LD_PRELOAD= BASH_ENV= MOSAIC_UNTRUSTED_SENTINEL=; do
-  echo "$pane_environment" | grep -qF "$blocked" && fail "runtime pane received $blocked"
+  contains_literal "$pane_environment" "$blocked" && fail "runtime pane received $blocked"
 done
 
 write_interaction_generated() {
@@ -290,6 +427,7 @@ write_interaction_generated() {
   chmod 600 "$home/fleet/run/holder-owner"
   cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
+MOSAIC_GIT_IDENTITY=$agent
 MOSAIC_AGENT_CLASS=operator-interaction
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol
@@ -352,8 +490,12 @@ write_generated "$HOME_NATIVE_STALE" "coder-native-stale"
 write_heartbeat_local "$HOME_NATIVE_STALE" "coder-native-stale"
 STALE_HB="$HOME_NATIVE_STALE/run/coder-native-stale.hb"
 printf 'ts=native\npid=1\nstatus=busy\nmodel=stale-model\n' > "$STALE_HB"
-touch -d '10 seconds ago' "$STALE_HB.native"
-MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_STALE" coder-native-stale
+touch -t 200001010000.00 "$STALE_HB.native"
+# Hold the sidecar's observation epoch constant: assertion runtime must not age
+# a fresh-marker mutant into the stale state that this fixture must distinguish.
+STALE_OBSERVATION_EPOCH=$(date +%s)
+MOSAIC_TEST_FIXED_EPOCH="$STALE_OBSERVATION_EPOCH" \
+  MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_STALE" coder-native-stale
 wait_for_sidecar_status "$STALE_HB"
 
 HOME_NATIVE_ABSENT="$ROOT/native-absent"
@@ -374,22 +516,22 @@ if output=$(run_interaction "$HOME_INTERACTION_MALFORMED" interaction-malformed
   fail "interaction wrapper accepted malformed generated data"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before interaction strict-parser rejection"
-echo "$output" | grep -qF 'code=unknown-key' || fail "interaction did not use shared strict parser first"
+contains_literal "$output" 'code=unknown-key' || fail "interaction did not use shared strict parser first"
 
 # A syntactically valid but policy-incompatible projection reaches the pinned
 # interaction policy check only after strict parsing and never starts tmux.
 : > "$TMUX_CALLS"
 HOME_INTERACTION_POLICY="$ROOT/interaction-policy"
 write_interaction_generated "$HOME_INTERACTION_POLICY" "interaction-policy"
-perl -0pi -e 's/MOSAIC_AGENT_RUNTIME=pi/MOSAIC_AGENT_RUNTIME=codex/' \
+sed -i 's|^MOSAIC_AGENT_RUNTIME=pi$|MOSAIC_AGENT_RUNTIME=codex|' \
   "$HOME_INTERACTION_POLICY/fleet/agents/interaction-policy.env.generated"
 if output=$(run_interaction "$HOME_INTERACTION_POLICY" interaction-policy 2>&1); then
   fail "interaction wrapper accepted a policy-incompatible projection"
 fi
 interaction_policy_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$interaction_policy_args" | grep -qF 'new-session' && \
+contains_literal "$interaction_policy_args" new-session && \
   fail "interaction pinned-policy rejection created a tmux session"
-echo "$output" | grep -qF 'operator interaction service requires runtime pi' || \
+contains_literal "$output" 'operator interaction service requires runtime pi' || \
   fail "interaction pinned-policy check did not follow strict parsing"
 
 # Exact stop derives the socket exclusively from the validated generated
@@ -402,11 +544,30 @@ HOME="$HOME_STOP" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
   MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
   MOSAIC_HOME="$HOME_STOP" MOSAIC_TMUX_SOCKET=ambient-socket "$START" --stop coder-stop
 stop_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$stop_args" | grep -qxF 'mosaic-test' || fail "exact stop did not use the validated generated socket"
-echo "$stop_args" | grep -qxF 'kill-session' || fail "exact stop did not request session termination"
-echo "$stop_args" | grep -qxF '=coder-stop' || fail "exact stop did not exact-match the generated agent name"
-if echo "$stop_args" | grep -qF 'ambient-socket'; then
+contains_line "$stop_args" mosaic-test || fail "exact stop did not use the validated generated socket"
+contains_line "$stop_args" kill-session || fail "exact stop did not request session termination"
+contains_line "$stop_args" '=coder-stop' || fail "exact stop did not exact-match the generated agent name"
+if contains_literal "$stop_args" ambient-socket; then
   fail "exact stop trusted an ambient socket"
 fi
 
+# A seat scaffolded under ~/.mosaic owns its harness home, so the pane launches
+# through the composition instead of the operator's own home. --dangerous keeps the
+# seat on the permissions footing `mosaic yolo` gave it.
+: > "$TMUX_CALLS"
+HOME_SEAT="$ROOT/seat"
+write_generated "$HOME_SEAT" "coder-seat"
+mkdir -p "$HOME_SEAT/.mosaic/fleet/agents/coder-seat"
+printf '{"schema":1,"harness":"pi","bundle":"primary"}\n' \
+  > "$HOME_SEAT/.mosaic/fleet/agents/coder-seat/profile.json"
+run_start "$HOME_SEAT" "coder-seat"
+seat_args=$(tr '\0' '\n' < "$TMUX_CALLS")
+echo "$seat_args" | grep -qxF 'fleet' || fail "scaffolded seat did not launch through fleet launch"
+echo "$seat_args" | grep -qxF 'launch' || fail "scaffolded seat did not launch through fleet launch"
+echo "$seat_args" | grep -qxF 'coder-seat' || fail "fleet launch did not name the seat"
+echo "$seat_args" | grep -qxF -- '--dangerous' || fail "scaffolded seat lost dangerous permissions"
+if echo "$seat_args" | grep -qxF 'yolo'; then
+  fail "scaffolded seat still launched through mosaic yolo"
+fi
+
 echo 'ok - start-agent-session generated environment boundary'

packages/mosaic/framework/tools/git/detect-platform.sh

@@ -5,7 +5,10 @@
 
 detect_platform() {
     local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null)
+    # `|| true` is load-bearing under `set -e`: outside a git repo this returns 128 and
+    # kills the CALLER before the -z check below can run, so the error message that is
+    # already written here was unreachable. Same idiom as get_gitea_repo_args() below.
+    remote_url=$(git remote get-url origin 2>/dev/null) || true
 
     if [[ -z "$remote_url" ]]; then
         echo "error: not a git repository or no origin remote" >&2
@@ -39,7 +42,10 @@ detect_platform() {
 
 get_repo_info() {
     local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null)
+    # `|| true` is load-bearing under `set -e`: outside a git repo this returns 128 and
+    # kills the CALLER before the -z check below can run, so the error message that is
+    # already written here was unreachable. Same idiom as get_gitea_repo_args() below.
+    remote_url=$(git remote get-url origin 2>/dev/null) || true
 
     if [[ -z "$remote_url" ]]; then
         echo "error: not a git repository or no origin remote" >&2
@@ -240,6 +246,21 @@ PY
     } >&2
 }
 
+# Explain tea's most misleading failure. `user does not exist [uid: 0, name: ]` reads
+# as a missing account; it almost always means a REVOKED OR STALE TOKEN. `tea login`
+# keeps its OWN COPY of the token, so rotating the credential store does not update it.
+# Diagnostic only -- stderr, no control flow, no exit.
+explain_tea_user_does_not_exist() {
+    cat >&2 <<'MSG'
+NOTE: `user does not exist [uid: 0, name: ]` from tea usually means a REVOKED OR STALE TOKEN,
+      not a missing account. A `tea login` stores its OWN COPY of the token; rotating the
+      credential store does NOT update it.
+      CHECK: the login's cached copy (`tea login list` -- read the FULL table, never `| head`),
+             then re-register that login against the current token.
+      DO NOT probe capability with a mutating request; a POST is the action, not a check.
+MSG
+}
+
 get_gitea_login_for_host() {
     local host="${1:-}"
     local login

packages/mosaic/framework/tools/git/issue-close.sh

@@ -91,13 +91,32 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
     GITEA_LOGIN_NAME=$(get_gitea_login || true)
     if [[ -n "$GITEA_LOGIN_NAME" ]]; then
         if [[ -n "$COMMENT" ]]; then
-            tea issue comment "$ISSUE_NUMBER" "$COMMENT" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
+            # `tea issue comment` is NOT a subcommand -- tea 0.11.x lists only
+            # list/create/edit/reopen/close under `tea issue`. Comments are the
+            # TOP-LEVEL `tea comment`, which takes the same --repo/--login flags.
+            # The old call therefore always failed, was unchecked, and the script
+            # closed the issue anyway, losing the record of WHY.
+            #
+            # Use `tea comment` rather than the API helper so the comment and the
+            # close are made by the SAME principal ($GITEA_LOGIN_NAME). Routing the
+            # comment through the token-authenticated helper here would attribute the
+            # comment to the token holder and the close to the tea login -- two
+            # principals for one operation.
+            tea comment "$ISSUE_NUMBER" "$COMMENT" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME" || {
+                echo "Error: failed to post comment on #$ISSUE_NUMBER -- NOT closing (fail closed)." >&2
+                exit 1
+            }
         fi
         tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
     else
         echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
         if [[ -n "$COMMENT" ]]; then
-            gitea_issue_comment_api
+            # Fail closed here too: an unchecked comment lets the issue close without its
+            # audit trail, which is the same defect as the tea path above.
+            gitea_issue_comment_api || {
+                echo "Error: failed to post comment on #$ISSUE_NUMBER -- NOT closing (fail closed)." >&2
+                exit 1
+            }
         fi
         gitea_issue_close_api
     fi

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -254,15 +254,32 @@ from urllib.parse import urlparse
 
 
 def _origin_and_path(url):
-    # Normalize a URL to (scheme, host, effective-port) + comment path. The port
-    # defaults to the scheme's default (80 http / 443 otherwise) so an implicit
-    # port and its explicit default form compare equal.
+    # Normalize a URL to (scheme-class, host, distinguishing-port) + comment path.
+    #
+    # #991: http and https collapse into ONE scheme class ("web"). A Gitea whose
+    # ROOT_URL is configured http:// returns http:// object URLs even when every
+    # client reaches it over https://, so a scheme-strict comparison rejects the
+    # provider's own correct answer about a write that landed — a deterministic
+    # false negative on every comment posted against such a deployment. The
+    # scheme is also not what this check defends: the forgeries it exists to
+    # catch (look-alike host, decoy path prefix, wrong owner/repo/number) all
+    # vary the HOST or the PATH, both of which stay strict below. Any OTHER
+    # scheme (file:, ftp:, javascript:) remains distinguishing and is rejected.
+    #
+    # Port: an implicit port and its own scheme's default compare equal, so
+    # http://h == https://h. An EXPLICIT non-default port still distinguishes,
+    # because a different port is a different service on the same host.
     parsed = urlparse(url or "")
     scheme = (parsed.scheme or "").lower()
     host = (parsed.hostname or "").lower()
-    default_port = 80 if scheme == "http" else 443
-    port = parsed.port if parsed.port is not None else default_port
-    return (scheme, host, port), parsed.path.rstrip("/")
+    if scheme in ("http", "https"):
+        scheme_class = "web"
+        default_port = 80 if scheme == "http" else 443
+        port = None if parsed.port in (None, default_port) else parsed.port
+    else:
+        scheme_class = scheme
+        port = parsed.port
+    return (scheme_class, host, port), parsed.path.rstrip("/")
 
 
 try:

packages/mosaic/framework/tools/git/issue-create.sh

@@ -156,6 +156,7 @@ case "$PLATFORM" in
                 exit 0
             fi
             echo "Warning: tea issue create failed, trying Gitea API fallback..." >&2
+            { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
         fi
         gitea_issue_create_api
         ;;

packages/mosaic/framework/tools/git/issue-view.sh

@@ -71,6 +71,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             exit 0
         fi
         echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
+        { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
     fi
     gitea_issue_view_api
 else

packages/mosaic/framework/tools/git/mosaic-worktree.sh

@@ -0,0 +1,306 @@
+#!/usr/bin/env bash
+# mosaic-worktree.sh — the only supported way to create and dispose of a git
+# worktree on a fleet host.
+#
+# Why this exists as a helper and not as a rule: the rule already existed, in
+# the framework's own words ("Big work → /var/tmp"), and 255 GB accumulated in
+# $HOME across 842 directories anyway. Five placement conventions were live on
+# one fleet host simultaneously. Every one was a decision an agent had to make,
+# and a decision an agent has to make is a decision that drifts.
+#
+# So this script makes NO placement decision available. The caller supplies a
+# branch name. Every path is DERIVED:
+#
+#   main worktree   <- git worktree list --porcelain (never cwd, which may
+#                      itself already be a worktree)
+#   REPO_NAME       <- basename of the main worktree
+#   REPO_PARENT     <- dirname  of the main worktree
+#   WT_ROOT         <- $REPO_PARENT/$REPO_NAME-worktrees
+#   SLUG            <- branch with '/' replaced by '-'
+#   WT_PATH         <- $WT_ROOT/$SLUG
+#
+# The derivation puts the worktree on the same filesystem as the object store
+# it shares, as a sibling of the repo, under one root per repo. Those are the
+# properties that make the checkout cheap and — via `git worktree list` —
+# enumerable, which is the only reason automated cleanup can ever be safe.
+#
+# Usage:
+#   mosaic-worktree.sh new <branch> [--from <base>]   create (branch may exist)
+#   mosaic-worktree.sh path <branch>                  print derived path, no side effect
+#   mosaic-worktree.sh list                           this repo's worktrees + state
+#   mosaic-worktree.sh rm <branch> [--force]          remove; refuses to lose work
+#   mosaic-worktree.sh gc [--apply]                   report/remove clean+pushed worktrees
+#
+# `rm` and `gc` refuse to delete a worktree with uncommitted changes, with
+# commits absent from every remote, or holding ignored files that are not of the
+# well-known regenerable kind (a `.env` is ignored so it is never committed,
+# which is also why nothing else holds a copy). That check is by EVIDENCE, never
+# by size or age. --force overrides it and is yours to type deliberately.
+#
+# Run from anywhere inside the repo, or pass --repo <path>.
+
+set -euo pipefail
+
+die() { printf 'mosaic-worktree: %s\n' "$*" >&2; exit 1; }
+
+REPO_HINT=""
+ARGS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO_HINT="${2:-}"; shift 2 ;;
+    *) ARGS+=("$1"); shift ;;
+  esac
+done
+set -- "${ARGS[@]+"${ARGS[@]}"}"
+
+CMD="${1:-}"
+[ -n "$CMD" ] || die "no command. Try: new | path | list | rm | gc"
+shift || true
+
+# ---- mechanical derivation -------------------------------------------------
+# The FIRST entry of `git worktree list --porcelain` is always the main
+# worktree, regardless of which worktree we are standing in. Deriving from cwd
+# would nest worktrees inside worktrees.
+resolve_repo() {
+  local start="${REPO_HINT:-$PWD}"
+  git -C "$start" rev-parse --git-dir >/dev/null 2>&1 \
+    || die "not inside a git repository: $start"
+  # Take the first entry WITHOUT closing the pipe early. `awk ... exit` on the
+  # first match closes the read end while git is still writing, git takes SIGPIPE,
+  # and under `set -euo pipefail` the command substitution returns 141 and this
+  # function aborts SILENTLY — no message, no worktree, and `new` exits 141 while
+  # printing nothing at all.
+  #
+  # Whether it happens depends on how much git still had to write when awk left,
+  # so the failure is a function of REPO SIZE: fine on a repo with three
+  # worktrees, reliably broken on one with seventy. That is backwards — the repos
+  # this helper exists to serve are exactly the ones that accumulated worktrees,
+  # and it silently did nothing on those while working everywhere it was tried.
+  # Measured on a repo with 73 worktrees (10 KB of porcelain): rc=141, no output.
+  #
+  # The file's own comment block below already names this class for `head -200`
+  # and removed that cap for the same reason. The `exit` here is the same defect
+  # in the same file, so the rule is now uniform: nothing in this script closes a
+  # git pipe early. Dropping `exit` costs one pass over a few KB.
+  MAIN_WT="$(git -C "$start" worktree list --porcelain | awk '/^worktree /&&!seen{print substr($0,10); seen=1}')"
+  [ -n "$MAIN_WT" ] || die "could not resolve the main worktree"
+  REPO_NAME="$(basename -- "$MAIN_WT")"
+  REPO_PARENT="$(dirname -- "$MAIN_WT")"
+  WT_ROOT="$REPO_PARENT/$REPO_NAME-worktrees"
+}
+
+slugify() { printf '%s' "$1" | tr '/' '-'; }
+
+derive_path() {
+  local branch="$1"
+  [ -n "$branch" ] || die "branch name required"
+  printf '%s/%s' "$WT_ROOT" "$(slugify "$branch")"
+}
+
+# A worktree root under $HOME defeats the entire point: wrong filesystem, and
+# $HOME is for configuration and state, not work products. Refuse rather than
+# silently produce the layout we are trying to eliminate.
+assert_not_home() {
+  local p="$1" home_real repo_real
+  home_real="$(cd "$HOME" && pwd -P)"
+  repo_real="$(cd "$(dirname -- "$p")" 2>/dev/null && pwd -P || dirname -- "$p")"
+  case "$repo_real/" in
+    "$home_real"/*)
+      die "refusing: derived path is under \$HOME ($p).
+The repo itself lives under \$HOME, so its worktrees would too. Move the repo
+to a work filesystem (e.g. /src/$REPO_NAME) and re-run. \$HOME holds
+configuration, credentials, state and caches — not checkouts." ;;
+  esac
+}
+
+# ---- work-loss evidence ----------------------------------------------------
+# Two independent questions, both answered from git, neither from size or age:
+#   dirty    — anything uncommitted in the tree
+#   unpushed — commits reachable from HEAD that no remote ref contains
+#   precious — IGNORED files git will not mention and will not miss
+#
+# The third question is not obvious and was missed on the first pass. An
+# independent reviewer demonstrated it in four commands: a pushed, clean
+# worktree whose .gitignore covers `*.secret`, holding one `local.secret`.
+# `git status --porcelain` is empty, `rev-list --count HEAD --not --remotes` is
+# 0 — the evidence reads SAFE — and `git worktree remove` deletes the file. The
+# same shape covers `.env`, credentials, scratch notes, downloaded fixtures:
+# precisely the files that are ignored BECAUSE they must not be committed, which
+# is also why nothing else is holding a copy.
+#
+# So ignored files count as work unless they are the well-known regenerable
+# kind. Getting that set wrong is asymmetric: an over-broad list preserves a
+# worktree that could have been reclaimed (cheap, visible, fixable by --force),
+# an over-narrow one deletes the only copy of a secret (silent, permanent).
+# The list stays short and conservative for that reason.
+DISPOSABLE_RE='(^|/)(node_modules|\.venv|venv|__pycache__|\.mypy_cache|\.pytest_cache|\.ruff_cache|\.turbo|\.cache|\.parcel-cache|\.gradle|dist|build|out|target|coverage|\.next|\.nuxt|\.svelte-kit)(/|$)|\.(pyc|pyo|o|class)$'
+
+# These three run under `set -euo pipefail` inside command substitution, which
+# makes any nonzero exit ANYWHERE in the pipeline abort the calling function
+# silently. Two ways that bites, one of which shipped:
+#
+#   * `grep -v` exits 1 when it filters everything out. A worktree whose only
+#     ignored entry is `node_modules/` is exactly the SAFE case, and it made
+#     `rm` exit 1 with no message and no removal — found by review.
+#   * `head -200` closes the pipe, SIGPIPEs the producer, and turns a worktree
+#     with 201 dirty files into the same silent abort. Not reported; it is the
+#     same defect one step upstream, so the cap is gone. Counting is cheap;
+#     the cap only ever protected output that is now never printed.
+#
+# Every one of them therefore ends in a total, and every stage that can
+# legitimately exit nonzero says so explicitly.
+wt_dirty() {
+  local out
+  out="$(git -C "$1" status --porcelain 2>/dev/null || true)"
+  if [ -n "$out" ]; then printf '%s\n' "$out" | wc -l; else printf '0'; fi
+}
+
+wt_unpushed() { git -C "$1" rev-list --count HEAD --not --remotes 2>/dev/null || printf '?'; }
+
+# Default --ignored (not =matching) so a 40k-file node_modules collapses to one
+# directory entry instead of being enumerated and then discarded.
+wt_precious() {
+  local ignored
+  ignored="$(git -C "$1" status --porcelain --ignored 2>/dev/null \
+             | awk '/^!! /{print substr($0,4)}' || true)"
+  [ -n "$ignored" ] || { printf '0'; return 0; }
+  printf '%s\n' "$ignored" | grep -Ecv "$DISPOSABLE_RE" || true
+}
+
+wt_state() {
+  local wt="$1" d u p
+  d="$(wt_dirty "$wt")"; u="$(wt_unpushed "$wt")"; p="$(wt_precious "$wt")"
+  if [ "$d" -eq 0 ] && [ "$u" = "0" ] && [ "$p" -eq 0 ]; then
+    printf 'SAFE\tclean; 0 unpushed; no ignored files worth keeping'
+  else
+    printf 'PRESERVE\t%s uncommitted; %s unpushed; %s ignored-but-not-disposable' "$d" "$u" "$p"
+  fi
+}
+
+# ---- commands --------------------------------------------------------------
+cmd_path() { resolve_repo; derive_path "${1:-}"; echo; }
+
+cmd_new() {
+  local branch="${1:-}" base=""
+  shift || true
+  while [ $# -gt 0 ]; do
+    case "$1" in --from) base="${2:-}"; shift 2 ;; *) die "unknown flag: $1" ;; esac
+  done
+  [ -n "$branch" ] || die "usage: mosaic-worktree.sh new <branch> [--from <base>]"
+
+  resolve_repo
+  local path; path="$(derive_path "$branch")"
+  assert_not_home "$path"
+
+  if [ -e "$path" ]; then
+    echo "exists: $path"
+    echo "(already checked out — reuse it, or 'rm' it first)"
+    return 0
+  fi
+
+  mkdir -p "$WT_ROOT"
+
+  # Existing branch -> check it out. New branch -> create from base (default:
+  # the remote's default branch if resolvable, else current HEAD).
+  if git -C "$MAIN_WT" show-ref --verify --quiet "refs/heads/$branch" \
+     || git -C "$MAIN_WT" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
+    git -C "$MAIN_WT" worktree add "$path" "$branch"
+  else
+    if [ -z "$base" ]; then
+      base="$(git -C "$MAIN_WT" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+      [ -n "$base" ] || base="HEAD"
+    fi
+    git -C "$MAIN_WT" worktree add -b "$branch" "$path" "$base"
+  fi
+
+  cat <<EOF
+
+worktree: $path
+branch:   $branch
+
+Removal is part of this task, not a later chore. When the work is pushed:
+  mosaic-worktree.sh rm $branch
+EOF
+}
+
+cmd_list() {
+  resolve_repo
+  printf 'repo: %s\nroot: %s\n\n' "$MAIN_WT" "$WT_ROOT"
+  git -C "$MAIN_WT" worktree list --porcelain \
+    | awk '/^worktree /{print substr($0,10)}' \
+    | while read -r wt; do
+        [ "$wt" = "$MAIN_WT" ] && { printf '%-10s %s (main)\n' "-" "$wt"; continue; }
+        printf '%-10s %s\t%s\n' "$(wt_state "$wt" | cut -f1)" "$wt" "$(wt_state "$wt" | cut -f2)"
+      done
+}
+
+cmd_rm() {
+  local branch="${1:-}" force=0
+  shift || true
+  while [ $# -gt 0 ]; do
+    case "$1" in --force) force=1; shift ;; *) die "unknown flag: $1" ;; esac
+  done
+  [ -n "$branch" ] || die "usage: mosaic-worktree.sh rm <branch> [--force]"
+
+  resolve_repo
+  local path; path="$(derive_path "$branch")"
+  [ -d "$path" ] || die "no worktree at $path"
+
+  local d u p
+  d="$(wt_dirty "$path")"; u="$(wt_unpushed "$path")"; p="$(wt_precious "$path")"
+  if [ "$force" -eq 0 ] && { [ "$d" -ne 0 ] || [ "$u" != "0" ] || [ "$p" -ne 0 ]; }; then
+    die "refusing to remove $path
+  uncommitted files:            $d
+  unpushed commits:             $u
+  ignored, not disposable:      $p
+Commit and push first — that is the contract. Ignored files are counted because
+git will neither report them nor miss them: a .env or a *.secret is ignored
+precisely so it is never committed, which is also why nothing else holds a copy.
+List them with:  git -C $path status --porcelain --ignored | grep '^!!'
+If this work is genuinely disposable, re-run with --force."
+  fi
+
+  # NB: ${force:+--force} would expand for force=0 too ("0" is non-empty).
+  if [ "$force" -eq 1 ]; then
+    git -C "$MAIN_WT" worktree remove --force "$path"
+  else
+    git -C "$MAIN_WT" worktree remove "$path"
+  fi
+  git -C "$MAIN_WT" worktree prune
+  echo "removed: $path"
+  rmdir "$WT_ROOT" 2>/dev/null || true
+}
+
+cmd_gc() {
+  local apply=0
+  [ "${1:-}" = "--apply" ] && apply=1
+  resolve_repo
+  git -C "$MAIN_WT" worktree prune
+  git -C "$MAIN_WT" worktree list --porcelain \
+    | awk '/^worktree /{print substr($0,10)}' \
+    | while read -r wt; do
+        [ "$wt" = "$MAIN_WT" ] && continue
+        local_state="$(wt_state "$wt")"
+        case "$local_state" in
+          SAFE*)
+            if [ "$apply" -eq 1 ]; then
+              git -C "$MAIN_WT" worktree remove "$wt" && echo "removed: $wt"
+            else
+              echo "reclaimable (clean + fully pushed): $wt"
+            fi ;;
+          *) echo "preserved: $wt  [$(printf '%s' "$local_state" | cut -f2)]" ;;
+        esac
+      done
+  git -C "$MAIN_WT" worktree prune
+  [ "$apply" -eq 1 ] || echo $'\n(report only — re-run with --apply to remove the reclaimable ones)'
+}
+
+case "$CMD" in
+  new)  cmd_new  "$@" ;;
+  path) cmd_path "$@" ;;
+  list) cmd_list "$@" ;;
+  rm)   cmd_rm   "$@" ;;
+  gc)   cmd_gc   "$@" ;;
+  -h|--help|help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//' ;;
+  *) die "unknown command: $CMD (new | path | list | rm | gc)" ;;
+esac

packages/mosaic/framework/tools/git/mutate-push-guard.sh

@@ -84,7 +84,7 @@ cp "$TARGET" "$BAK"
 export MOSAIC_TEST_WORK_DIR="$WORK/.work"
 
 # --- where the prose lives: usage() { ... EOF ---------------------------------
-PROSE_LO="$(grep -n '^usage() {' "$BAK" | head -1 | cut -d: -f1)"
+PROSE_LO="$(grep -n -m1 '^usage() {' "$BAK" | cut -d: -f1)"
 PROSE_HI="$(awk -v lo="$PROSE_LO" 'NR > lo && /^EOF$/ { print NR; exit }' "$BAK")"
 if [[ -z "$PROSE_LO" || -z "$PROSE_HI" ]]; then
     echo "!! cannot locate the usage() heredoc -- the prose guard would be inert; refusing" >&2

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

@@ -219,6 +219,7 @@ case "$PLATFORM" in
             exit 0
         fi
         echo "Warning: tea pr create failed, trying Gitea API fallback..." >&2
+        { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
         gitea_pr_create_api
         ;;
     *)

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

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# pr-edit.sh - Edit a pull request on GitHub or Gitea
+# Usage: pr-edit.sh -n <pr_number> [-t <title>] [-b <body>] [-B <base>] [--draft|--ready] [--login <name>] [-r owner/repo] [-H host]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=detect-platform.sh
+source "$SCRIPT_DIR/detect-platform.sh"
+
+PR_NUMBER=""
+TITLE=""
+BODY=""
+BASE_BRANCH=""
+DRAFT_MODE=""
+LOGIN_OVERRIDE=""
+REPO_OVERRIDE=""
+HOST_OVERRIDE=""
+AUTH_CONFIG=""
+
+cleanup() {
+    [[ -z "$AUTH_CONFIG" ]] || rm -f -- "$AUTH_CONFIG"
+}
+terminate() {
+    local signal="$1"
+    trap - "$signal"
+    cleanup
+    kill -s "$signal" "$$"
+}
+trap cleanup EXIT
+trap 'terminate HUP' HUP
+trap 'terminate INT' INT
+trap 'terminate TERM' TERM
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [OPTIONS]
+
+Edit a pull request on the current repository (Gitea or GitHub).
+
+Options:
+    -n, --number NUMBER    Pull request number (required)
+    -t, --title TITLE      New title
+    -b, --body BODY        New body/description
+    -B, --base BRANCH      New base branch
+        --draft            Mark the pull request as draft
+        --ready            Mark the pull request ready for review
+    -l, --login NAME       Gitea login (must authenticate as MOSAIC_GIT_IDENTITY)
+    -r, --repo OWNER/REPO  Explicit target repository
+    -H, --host HOST        Explicit Gitea host (required with --repo off-host)
+    -h, --help             Show this help message
+EOF
+    exit "${1:-1}"
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -n|--number) PR_NUMBER="${2:-}"; shift 2 ;;
+        -t|--title) TITLE="${2:-}"; shift 2 ;;
+        -b|--body) BODY="${2:-}"; shift 2 ;;
+        -B|--base) BASE_BRANCH="${2:-}"; shift 2 ;;
+        --draft)
+            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
+            DRAFT_MODE="draft"; shift ;;
+        --ready)
+            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
+            DRAFT_MODE="ready"; shift ;;
+        -l|--login) LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
+        -r|--repo) REPO_OVERRIDE="${2:-}"; shift 2 ;;
+        -H|--host) HOST_OVERRIDE="${2:-}"; shift 2 ;;
+        -h|--help) usage 0 ;;
+        *) echo "Unknown option: $1" >&2; usage ;;
+    esac
+done
+
+[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 1; }
+[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 1; }
+if [[ -z "$TITLE" && -z "$BODY" && -z "$BASE_BRANCH" && -z "$DRAFT_MODE" ]]; then
+    echo "Error: At least one edit option is required" >&2
+    exit 1
+fi
+[[ -z "$REPO_OVERRIDE" || "$REPO_OVERRIDE" =~ ^[^/[:space:]]+/[^/[:space:]]+$ ]] || {
+    echo "Error: --repo must be OWNER/REPO" >&2
+    exit 1
+}
+
+if [[ -n "$HOST_OVERRIDE" || -n "$REPO_OVERRIDE" ]]; then
+    PLATFORM="gitea"
+else
+    PLATFORM=$(detect_platform)
+fi
+
+case "$PLATFORM" in
+    github)
+        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 1; }
+        if [[ -n "$TITLE" || -n "$BODY" || -n "$BASE_BRANCH" ]]; then
+            CMD=(gh pr edit "$PR_NUMBER")
+            [[ -n "$TITLE" ]] && CMD+=(--title "$TITLE")
+            [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
+            [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
+            "${CMD[@]}"
+        fi
+        if [[ "$DRAFT_MODE" == "draft" ]]; then
+            gh pr ready "$PR_NUMBER" --undo
+        elif [[ "$DRAFT_MODE" == "ready" ]]; then
+            gh pr ready "$PR_NUMBER"
+        fi
+        ;;
+    gitea)
+        IDENTITY="${MOSAIC_GIT_IDENTITY:-}"
+        [[ -n "$IDENTITY" ]] || {
+            echo "Error: MOSAIC_GIT_IDENTITY is required for a mutating Gitea operation" >&2
+            exit 1
+        }
+        HOST="${HOST_OVERRIDE:-}"
+        if [[ -z "$HOST" ]]; then
+            HOST=$(get_remote_host) || {
+                echo "Error: Could not resolve Gitea host; pass --host with --repo" >&2
+                exit 1
+            }
+        fi
+        HOST="${HOST#http://}"; HOST="${HOST#https://}"; HOST="${HOST%%/*}"
+        REPO_SLUG="${REPO_OVERRIDE:-}"
+        if [[ -z "$REPO_SLUG" ]]; then
+            REPO_SLUG=$(get_repo_slug) || { echo "Error: Could not resolve Gitea repo slug from remote" >&2; exit 1; }
+        fi
+
+        if [[ -n "$LOGIN_OVERRIDE" ]]; then
+            GITEA_LOGIN_NAME="$LOGIN_OVERRIDE"
+        elif [[ -n "${GITEA_LOGIN:-}" ]]; then
+            GITEA_LOGIN_NAME="$GITEA_LOGIN"
+        else
+            echo "Error: --login (or GITEA_LOGIN) is required; refusing host-first login selection" >&2
+            exit 1
+        fi
+
+        TOKEN=$(get_gitea_token_for_login "$GITEA_LOGIN_NAME" "$HOST") || {
+            echo "Error: login '$GITEA_LOGIN_NAME' is not configured for target host '$HOST'" >&2
+            exit 1
+        }
+        AUTH_CONFIG=$(gitea_write_auth_config "$TOKEN") || {
+            echo "Error: could not stage private Gitea authentication" >&2
+            exit 1
+        }
+        unset TOKEN
+
+        API_BASE="https://${HOST}/api/v1"
+        # Resolve identity through the SAME private curl config used for the
+        # mutation. Tea login names are globally scoped and can be duplicated
+        # across hosts; a separate `tea api --login NAME` could validate another
+        # credential than this host-bound token.
+        AUTHENTICATED_USER=$(curl -fsS --config "$AUTH_CONFIG" -H "User-Agent: mosaic-pr-edit" "$API_BASE/user" \
+            | python3 -c 'import json,sys; value=json.load(sys.stdin).get("login"); print(value) if isinstance(value,str) and value else sys.exit(1)') || {
+            echo "Error: could not authenticate the host-bound credential for '$GITEA_LOGIN_NAME'" >&2
+            exit 1
+        }
+        [[ "$AUTHENTICATED_USER" == "$IDENTITY" ]] || {
+            echo "Error: host-bound credential authenticates as '$AUTHENTICATED_USER', not MOSAIC_GIT_IDENTITY '$IDENTITY'" >&2
+            exit 1
+        }
+
+        REPO_API="$API_BASE/repos/${REPO_SLUG}"
+        curl -fsS --config "$AUTH_CONFIG" -H "User-Agent: mosaic-pr-edit" "$REPO_API" >/dev/null || {
+            echo "Error: target repository preflight failed for https://${HOST}/${REPO_SLUG}" >&2
+            exit 1
+        }
+
+        PAYLOAD=$(TITLE="$TITLE" BODY="$BODY" BASE_BRANCH="$BASE_BRANCH" DRAFT_MODE="$DRAFT_MODE" python3 - <<'PY'
+import json
+import os
+payload = {}
+if os.environ["TITLE"]: payload["title"] = os.environ["TITLE"]
+if os.environ["BODY"]: payload["body"] = os.environ["BODY"]
+if os.environ["BASE_BRANCH"]: payload["base"] = os.environ["BASE_BRANCH"]
+if os.environ["DRAFT_MODE"]: payload["draft"] = os.environ["DRAFT_MODE"] == "draft"
+print(json.dumps(payload))
+PY
+)
+        curl -fsS --config "$AUTH_CONFIG" -X PATCH \
+            -H "User-Agent: mosaic-pr-edit" -H "Content-Type: application/json" \
+            -d "$PAYLOAD" "$REPO_API/pulls/${PR_NUMBER}"
+        echo "Updated Gitea pull request #$PR_NUMBER as '$AUTHENTICATED_USER'" >&2
+        ;;
+    *) echo "Error: Could not detect git platform" >&2; exit 1 ;;
+esac

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

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL]
 
 set -euo pipefail
 
@@ -14,6 +14,8 @@ MERGE_METHOD="squash"
 DELETE_BRANCH=false
 DRY_RUN=false
 EXPECT_HEAD=""
+CO_AUTHOR_TRAILERS=false
+ESCALATE_TO=""
 
 usage() {
     cat <<EOF
@@ -27,12 +29,16 @@ Options:
     -d, --delete-branch     Delete the head branch after merge
         --dry-run           Run metadata/login preflight without merging
         --expect-head SHA   Refuse unless the PR head matches this full commit SHA
+        --co-author-trailers Build verified trailers from linked PR commit authors
+        --escalate-to NAME  Named principal for an unresolved-author BLOCK
     -h, --help              Show this help message
 
 Examples:
     $(basename "$0") -n 42                    # Merge PR #42
     $(basename "$0") -n 42 -m squash          # Squash merge
     $(basename "$0") -n 42 -d                 # Squash merge and delete branch
+    $(basename "$0") -n 42 --expect-head 0123456789abcdef0123456789abcdef01234567
+    $(basename "$0") -n 42 --co-author-trailers --escalate-to tl-mosaic
 EOF
     exit "${1:-1}"
 }
@@ -57,9 +63,25 @@ while [[ $# -gt 0 ]]; do
             shift
             ;;
         --expect-head)
+            if [[ $# -lt 2 ]]; then
+                echo "Error: --expect-head requires one full commit SHA." >&2
+                exit 1
+            fi
             EXPECT_HEAD="$2"
             shift 2
             ;;
+        --co-author-trailers)
+            CO_AUTHOR_TRAILERS=true
+            shift
+            ;;
+        --escalate-to)
+            if [[ $# -lt 2 ]]; then
+                echo "Error: --escalate-to requires one principal name." >&2
+                exit 1
+            fi
+            ESCALATE_TO="$2"
+            shift 2
+            ;;
         -h|--help)
             usage 0
             ;;
@@ -88,17 +110,30 @@ if [[ -n "$EXPECT_HEAD" && ! "$EXPECT_HEAD" =~ ^[0-9a-fA-F]{40}$ ]]; then
     echo "Error: --expect-head must be a full 40-character hexadecimal commit SHA." >&2
     exit 1
 fi
+if [[ "$CO_AUTHOR_TRAILERS" == true && -z "$ESCALATE_TO" ]]; then
+    echo "Error: --co-author-trailers requires --escalate-to with a named principal." >&2
+    exit 1
+fi
+if [[ -n "$ESCALATE_TO" && ! "$ESCALATE_TO" =~ ^[A-Za-z0-9_.-]+$ ]]; then
+    echo "Error: --escalate-to must be one exact principal name." >&2
+    exit 1
+fi
+if [[ "$CO_AUTHOR_TRAILERS" != true && -n "$ESCALATE_TO" ]]; then
+    echo "Error: --escalate-to is valid only with --co-author-trailers." >&2
+    exit 1
+fi
 
 PR_METADATA="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER")"
 BASE_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
 HEAD_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefName") or "").strip())')"
 HEAD_SHA="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefOid") or "").strip())')"
 HEAD_REPO="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("headRepository") or ""; print((value.get("nameWithOwner") or value.get("full_name") or "") if isinstance(value, dict) else str(value).strip())')"
+PR_TITLE="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("title") or "").strip())')"
+PR_AUTHOR="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("author") or ""; print((value.get("login") or "").strip() if isinstance(value, dict) else str(value).strip())')"
 if [[ "$BASE_BRANCH" != "main" && "$BASE_BRANCH" != "next" ]]; then
     echo "Error: Mosaic policy allows merges only for PRs targeting 'main' or 'next' (found '$BASE_BRANCH')." >&2
     exit 1
 fi
-
 if [[ -z "$HEAD_BRANCH" || -z "$HEAD_REPO" || ! "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then
     echo "Error: Could not resolve the PR head branch, repository, and full commit SHA for queue inspection." >&2
     exit 1
@@ -122,70 +157,442 @@ PLATFORM=$(detect_platform)
 OWNER=$(get_repo_owner)
 REPO=$(get_repo_name)
 
-merge_gitea_with_api() {
-    local host="$1" api_url token basic_auth body_file raw_code payload
-    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
-    mkdir -p "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
-    body_file=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-api-response.XXXXXX")
-    payload=$(python3 - "$HEAD_SHA" "$DELETE_BRANCH" <<'PY'
+write_curl_auth_config() {
+    local mode="$1" credential="$2"
+    printf '%s' "$credential" | python3 -c '
+import sys
+mode = sys.argv[1]
+credential = sys.stdin.read()
+if not credential or any(char in credential for char in "\r\n"):
+    raise SystemExit(1)
+escaped = credential.replace("\\", "\\\\").replace("\"", "\\\"")
+if mode == "token":
+    print(f"header = \"Authorization: token {escaped}\"")
+elif mode == "basic":
+    print(f"user = \"{escaped}\"")
+else:
+    raise SystemExit(1)
+' "$mode"
+}
+
+LAST_GITEA_HTTP_CODE="000"
+LAST_GITEA_ERROR=""
+MERGE_TEMP_DIRS=()
+GITEA_CURL_MAX_BYTES="${MOSAIC_GITEA_CURL_MAX_BYTES:-1048576}"
+GITEA_CURL_MAX_TIME="${MOSAIC_GITEA_CURL_MAX_TIME_SEC:-30}"
+GITEA_CURL_CONNECT_TIMEOUT="${MOSAIC_GITEA_CURL_CONNECT_TIMEOUT_SEC:-10}"
+for bound in "$GITEA_CURL_MAX_BYTES" "$GITEA_CURL_MAX_TIME" "$GITEA_CURL_CONNECT_TIMEOUT"; do
+    if [[ ! "$bound" =~ ^[1-9][0-9]*$ ]]; then
+        echo "Error: Gitea curl bounds must be positive integers; refusing request." >&2
+        exit 1
+    fi
+done
+GITEA_CURL_BOUNDS=(
+    --max-filesize "$GITEA_CURL_MAX_BYTES"
+    --max-time "$GITEA_CURL_MAX_TIME"
+    --connect-timeout "$GITEA_CURL_CONNECT_TIMEOUT"
+)
+
+format_gitea_error_response() {
+    local response_file="$1"
+    python3 - "$response_file" <<'PY'
 import json
 import sys
 
-head_sha, delete_branch = sys.argv[1:]
+with open(sys.argv[1], "rb") as handle:
+    raw = handle.read(65536)
+try:
+    response = json.loads(raw.decode("utf-8", errors="replace"))
+except (UnicodeDecodeError, json.JSONDecodeError):
+    message = "non-JSON response omitted"
+else:
+    if isinstance(response, dict):
+        message = response.get("message") or response.get("error")
+        if not message and response.get("errors") is not None:
+            message = json.dumps(response["errors"], separators=(",", ":"))
+    else:
+        message = None
+    if not message:
+        message = "JSON response contained no error message"
+message = str(message)
+if len(message) > 500:
+    message = message[:500] + "..."
+print(ascii(message))
+PY
+}
+
+cleanup_merge_temp_dirs() {
+    local path
+    for path in "${MERGE_TEMP_DIRS[@]}"; do
+        [[ -n "$path" ]] && rm -rf -- "$path"
+    done
+}
+trap cleanup_merge_temp_dirs EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+fetch_gitea_pr_head() {
+    local host="$1" auth_mode="$2" credential="$3" work_root="$4"
+    local response_file raw_code api_url auth_config curl_rc
+    response_file=$(mktemp "$work_root/pr-merge-pr.XXXXXX")
+    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}"
+    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
+        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
+        rm -f "$response_file"
+        return 1
+    fi
+    raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$response_file" \
+        -H "User-Agent: curl/8" "$api_url" <<<"$auth_config")
+    curl_rc=$?
+    LAST_GITEA_HTTP_CODE="${raw_code:-000}"
+    if [[ "$curl_rc" -ne 0 ]]; then
+        LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
+        rm -f "$response_file"
+        return 1
+    fi
+    if [[ ! "$raw_code" =~ ^2 ]]; then
+        LAST_GITEA_ERROR=$(format_gitea_error_response "$response_file")
+        rm -f "$response_file"
+        return 1
+    fi
+    if ! python3 - "$response_file" <<'PY'
+import json
+import re
+import sys
+
+with open(sys.argv[1], encoding="utf-8") as handle:
+    pull = json.load(handle)
+head = pull.get("head") if isinstance(pull, dict) else None
+sha = str(head.get("sha") or "") if isinstance(head, dict) else ""
+if not re.fullmatch(r"[0-9a-fA-F]{40}", sha):
+    raise SystemExit(1)
+print(sha)
+PY
+    then
+        echo "Error: Gitea PR response has no valid head SHA; refusing merge." >&2
+        rm -f "$response_file"
+        return 1
+    fi
+    rm -f "$response_file"
+}
+
+fetch_gitea_pr_commits() {
+    local host="$1" auth_mode="$2" credential="$3" work_root="$4"
+    local page page_file combined_file merged_file raw_code page_count api_url auth_config curl_rc
+    mkdir -p "$work_root"
+    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
+        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
+        return 1
+    fi
+    combined_file=$(mktemp "$work_root/pr-merge-commits.XXXXXX")
+    printf '[]' > "$combined_file"
+
+    page=1
+    while true; do
+        page_file=$(mktemp "$work_root/pr-merge-commits-page.XXXXXX")
+        api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/commits?limit=50&page=${page}"
+        raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$page_file" \
+            -H "User-Agent: curl/8" "$api_url" <<<"$auth_config")
+        curl_rc=$?
+        LAST_GITEA_HTTP_CODE="${raw_code:-000}"
+        if [[ "$curl_rc" -ne 0 ]]; then
+            LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
+            rm -f "$page_file" "$combined_file"
+            return 1
+        fi
+        if [[ ! "$raw_code" =~ ^2 ]]; then
+            LAST_GITEA_ERROR=$(format_gitea_error_response "$page_file")
+            rm -f "$page_file" "$combined_file"
+            return 1
+        fi
+
+        if ! page_count=$(python3 - "$page_file" <<'PY'
+import json
+import sys
+
+with open(sys.argv[1], encoding="utf-8") as handle:
+    page = json.load(handle)
+if not isinstance(page, list):
+    raise SystemExit(1)
+print(len(page))
+PY
+        ); then
+            echo "Error: Gitea PR commits response is not a JSON array; refusing merge." >&2
+            rm -f "$page_file" "$combined_file"
+            return 1
+        fi
+
+        merged_file=$(mktemp "$work_root/pr-merge-commits-merged.XXXXXX")
+        if ! python3 - "$combined_file" "$page_file" > "$merged_file" <<'PY'
+import json
+import sys
+
+with open(sys.argv[1], encoding="utf-8") as handle:
+    combined = json.load(handle)
+with open(sys.argv[2], encoding="utf-8") as handle:
+    page = json.load(handle)
+json.dump(combined + page, sys.stdout, separators=(",", ":"))
+PY
+        then
+            echo "Error: Could not combine paginated PR commit metadata; refusing merge." >&2
+            rm -f "$page_file" "$combined_file" "$merged_file"
+            return 1
+        fi
+        mv "$merged_file" "$combined_file"
+        rm -f "$page_file"
+
+        if [[ "$page_count" -lt 50 ]]; then
+            break
+        fi
+        page=$((page + 1))
+        if [[ "$page" -gt 1000 ]]; then
+            echo "Error: PR commit pagination exceeded 1000 pages; refusing merge." >&2
+            rm -f "$combined_file"
+            return 1
+        fi
+    done
+
+    cat "$combined_file"
+    rm -f "$combined_file"
+}
+
+# LIMITATION: author.login resolution proves the commit address maps to a registered account.
+# It does NOT prove the named principal authored the commit — git author metadata is self-asserted.
+# This gate checks ATTRIBUTION LINKAGE, not AUTHORSHIP. Commit signing is out of scope and unadopted.
+build_coauthor_message_fields() {
+    local commits_file="$1" context_file="$2" head_file="$3"
+    python3 - "$commits_file" "$context_file" "$head_file" <<'PY'
+import json
+import re
+import sys
+
+commits_path, context_path, head_path = sys.argv[1:]
+with open(commits_path, encoding="utf-8") as handle:
+    commits = json.load(handle)
+head_sha = open(head_path, encoding="utf-8").read().strip()
+context_parts = open(context_path, "rb").read().split(b"\0")
+if len(context_parts) != 4 or context_parts[-1] != b"":
+    raise SystemExit(1)
+poster, title, principal = (part.decode("utf-8") for part in context_parts[:3])
+
+if not isinstance(commits, list) or not commits:
+    print(
+        f"BLOCK: provider returned no PR commits; author identity is unmeasurable. "
+        f"Refusing merge; escalate to named principal '{principal}'.",
+        file=sys.stderr,
+    )
+    raise SystemExit(75)
+if not poster:
+    print(
+        f"BLOCK: PR poster login is empty; refusing merge; "
+        f"escalate to named principal '{principal}'.",
+        file=sys.stderr,
+    )
+    raise SystemExit(75)
+
+if not re.fullmatch(r"[0-9a-fA-F]{40}", head_sha):
+    print(
+        f"BLOCK: inspected PR head SHA is invalid; refusing merge; "
+        f"escalate to named principal '{principal}'.",
+        file=sys.stderr,
+    )
+    raise SystemExit(75)
+
+seen = set()
+trailers = []
+head_seen = False
+for item in commits:
+    if not isinstance(item, dict):
+        print(f"BLOCK: malformed PR commit metadata; escalate to named principal '{principal}'.", file=sys.stderr)
+        raise SystemExit(75)
+    sha = str(item.get("sha") or "<unknown>")
+    if sha == head_sha:
+        head_seen = True
+    commit = item.get("commit") if isinstance(item.get("commit"), dict) else {}
+    commit_author = commit.get("author") if isinstance(commit.get("author"), dict) else {}
+    email = str(commit_author.get("email") or "").strip()
+    provider_author = item.get("author") if isinstance(item.get("author"), dict) else {}
+    login = str(provider_author.get("login") or "").strip()
+
+    if not login:
+        diagnostic_email = email or "<missing>"
+        print(
+            f"BLOCK: commit {sha!r} has author.login=NULL while "
+            f"commit.author.email={diagnostic_email!r}; refusing merge; "
+            f"escalate to named principal '{principal}'.",
+            file=sys.stderr,
+        )
+        raise SystemExit(75)
+    if (
+        not email.isascii()
+        or not email.isprintable()
+        or not re.fullmatch(r"[A-Za-z0-9_.-]+", login)
+        or not re.fullmatch(r"[^<>\s]+@[^<>\s]+", email)
+    ):
+        print(
+            f"BLOCK: commit {sha!r} has unusable linked identity "
+            f"author.login={login!r}, commit.author.email={email!r}; refusing merge; "
+            f"escalate to named principal '{principal}'.",
+            file=sys.stderr,
+        )
+        raise SystemExit(75)
+    if login == poster or login in seen:
+        continue
+    seen.add(login)
+    trailers.append(f"Co-authored-by: {login} <{email}>")
+
+if not head_seen:
+    print(
+        f"BLOCK: inspected PR head is absent from commit enumeration; refusing merge; "
+        f"escalate to named principal '{principal}'.",
+        file=sys.stderr,
+    )
+    raise SystemExit(75)
+if not trailers:
+    print("{}")
+    raise SystemExit(0)
+if not title:
+    print(
+        f"BLOCK: PR title is empty; refusing merge; escalate to named principal '{principal}'.",
+        file=sys.stderr,
+    )
+    raise SystemExit(75)
+if not title.isprintable() or re.match(r"^[A-Za-z-]+-[Bb]y:", title):
+    print(
+        f"BLOCK: PR title is not one printable, non-trailer line; refusing merge; "
+        f"escalate to named principal '{principal}'.",
+        file=sys.stderr,
+    )
+    raise SystemExit(75)
+
+print(json.dumps({
+    "MergeTitleField": title,
+    "MergeMessageField": "\n".join(trailers),
+}, separators=(",", ":")))
+PY
+}
+
+merge_gitea_api_attempt() {
+    local host="$1" auth_mode="$2" credential="$3"
+    local api_url attempt_dir body_file raw_code commits_file fields_file context_file head_file payload_file work_root attempt_rc auth_config curl_rc
+    LAST_GITEA_HTTP_CODE="000"
+    LAST_GITEA_ERROR=""
+    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
+    work_root="${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
+    mkdir -p "$work_root"
+    attempt_dir=$(mktemp -d "$work_root/pr-merge-attempt.XXXXXX")
+    chmod 0700 "$attempt_dir"
+    MERGE_TEMP_DIRS+=("$attempt_dir")
+    body_file=$(mktemp "$attempt_dir/api-response.XXXXXX")
+    fields_file=$(mktemp "$attempt_dir/message-fields.XXXXXX")
+    payload_file=$(mktemp "$attempt_dir/payload.XXXXXX")
+    printf '{}' > "$fields_file"
+
+    if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
+        commits_file=$(mktemp "$attempt_dir/pr-merge-commits-input.XXXXXX")
+        context_file=$(mktemp "$attempt_dir/pr-merge-message-context.XXXXXX")
+        head_file=$(mktemp "$attempt_dir/pr-merge-head-input.XXXXXX")
+        printf '%s\0%s\0%s\0' "$PR_AUTHOR" "$PR_TITLE" "$ESCALATE_TO" > "$context_file"
+        if fetch_gitea_pr_head "$host" "$auth_mode" "$credential" "$attempt_dir" > "$head_file"; then
+            :
+        else
+            attempt_rc=$?
+            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
+            return "$attempt_rc"
+        fi
+        if [[ "$(<"$head_file")" != "$HEAD_SHA" ]]; then
+            echo "BLOCK: authenticated PR head moved from reviewed $HEAD_SHA to $(<"$head_file"); refusing merge; escalate to named principal '$ESCALATE_TO'." >&2
+            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
+            return 75
+        fi
+        if fetch_gitea_pr_commits "$host" "$auth_mode" "$credential" "$attempt_dir" > "$commits_file"; then
+            :
+        else
+            attempt_rc=$?
+            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
+            return "$attempt_rc"
+        fi
+        if build_coauthor_message_fields "$commits_file" "$context_file" "$head_file" > "$fields_file"; then
+            :
+        else
+            attempt_rc=$?
+            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
+            return "$attempt_rc"
+        fi
+        rm -f "$commits_file" "$context_file" "$head_file"
+    fi
+
+    if ! python3 - "$fields_file" "$HEAD_SHA" "$DELETE_BRANCH" > "$payload_file" <<'PY'
+import json
+import sys
+
+with open(sys.argv[1], encoding="utf-8") as handle:
+    fields = json.load(handle)
+head_sha, delete_branch = sys.argv[2:]
 payload = {"Do": "squash", "head_commit_id": head_sha}
 if delete_branch == "true":
     payload["delete_branch_after_merge"] = True
+payload.update(fields)
+allowed = {"Do", "head_commit_id", "delete_branch_after_merge", "MergeTitleField", "MergeMessageField"}
+if payload.get("Do") != "squash" or set(payload) - allowed:
+    raise SystemExit(1)
 print(json.dumps(payload, separators=(",", ":")))
 PY
-)
-
-    token=$(get_gitea_token "$host" || true)
-    if [[ -n "$token" ]]; then
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
-            -X POST \
-            -H "User-Agent: curl/8" \
-            -H "Authorization: token $token" \
-            -H 'Content-Type: application/json' \
-            -d "$payload" \
-            "$api_url" || true)
-        if [[ "$raw_code" =~ ^2 ]]; then
-            rm -f "$body_file"
-            return 0
-        fi
+    then
+        rm -f "$body_file" "$fields_file" "$payload_file"
+        return 1
     fi
+    rm -f "$fields_file"
 
-    basic_auth=$(get_gitea_basic_auth "$host" || true)
-    if [[ -n "$basic_auth" ]]; then
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
-            -X POST \
-            -u "$basic_auth" \
-            -H "User-Agent: curl/8" \
-            -H 'Content-Type: application/json' \
-            -d "$payload" \
-            "$api_url" || true)
-        if [[ "$raw_code" =~ ^2 ]]; then
-            rm -f "$body_file"
-            return 0
-        fi
+    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
+        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
+        rm -f "$body_file" "$payload_file"
+        return 1
     fi
+    raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$body_file" \
+        -X POST -H "User-Agent: curl/8" \
+        -H 'Content-Type: application/json' \
+        --data-binary "@$payload_file" "$api_url" <<<"$auth_config")
+    curl_rc=$?
+    LAST_GITEA_HTTP_CODE="${raw_code:-000}"
+    if [[ "$curl_rc" -ne 0 ]]; then
+        LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
+        rm -f "$body_file" "$payload_file"
+        rm -rf -- "$attempt_dir"
+        return 1
+    fi
+    if [[ ! "$raw_code" =~ ^2 ]]; then
+        LAST_GITEA_ERROR=$(format_gitea_error_response "$body_file")
+    fi
+    rm -f "$body_file" "$payload_file"
+    rm -rf -- "$attempt_dir"
+    [[ "$raw_code" =~ ^2 ]]
+}
 
-    python3 - "${raw_code:-000}" "$body_file" <<'PY' >&2
-import json
-import sys
-code, path = sys.argv[1], sys.argv[2]
-try:
-    with open(path, encoding="utf-8", errors="replace") as handle:
-        raw = handle.read(500)
-    data = json.loads(raw) if raw else {}
-    message = data.get("message") or data.get("error") or raw or "empty response"
-except Exception:
-    try:
-        message = open(path, encoding="utf-8", errors="replace").read(500) or "empty response"
-    except Exception:
-        message = "unreadable response"
-print(f"Error: Gitea API merge failed with HTTP {code}: {message}")
-PY
-    rm -f "$body_file"
+merge_gitea_with_api() {
+    local host="$1" token attempt_rc
+
+    if ! token=$(get_gitea_token "$host"); then
+        echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
+        return 1
+    fi
+    if [[ -z "$token" ]]; then
+        echo "Error: Required Gitea token resolved empty; refusing merge without changing principals." >&2
+        return 1
+    fi
+    if merge_gitea_api_attempt "$host" token "$token"; then
+        return 0
+    else
+        attempt_rc=$?
+    fi
+    if [[ "$attempt_rc" -eq 75 ]]; then
+        return 75
+    fi
+    if [[ "$LAST_GITEA_HTTP_CODE" != "401" ]]; then
+        echo "Error: Gitea API merge failed with the identity-bound token (HTTP ${LAST_GITEA_HTTP_CODE:-000}).${LAST_GITEA_ERROR:+ Provider response: $LAST_GITEA_ERROR}" >&2
+        return 1
+    fi
+    echo "Error: Gitea API rejected the identity-bound token with HTTP 401; refusing cross-principal credential fallback." >&2
     return 1
 }
 
@@ -195,11 +602,10 @@ if [[ "$DRY_RUN" == true ]]; then
             echo "Error: Cannot determine host from origin remote URL" >&2
             exit 1
         }
-        TEA_LOGIN="$(get_gitea_login_for_host "$HOST" || true)"
-        if [[ -n "$TEA_LOGIN" ]]; then
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with tea login '$TEA_LOGIN' (base=$BASE_BRANCH, method=squash)."
+        if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
+            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
         else
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with authenticated Gitea API fallback (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
         fi
     else
         echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."
@@ -209,6 +615,10 @@ fi
 
 case "$PLATFORM" in
     github)
+        if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
+            echo "Error: --co-author-trailers currently requires the Gitea REST message-field contract." >&2
+            exit 1
+        fi
         cmd=(gh pr merge "$PR_NUMBER" --squash --match-head-commit "$HEAD_SHA")
         [[ "$DELETE_BRANCH" == true ]] && cmd+=(--delete-branch)
         "${cmd[@]}"
@@ -219,7 +629,7 @@ case "$PLATFORM" in
             exit 1
         }
         # Gitea's API head_commit_id is an atomic compare-and-merge precondition.
-        # tea cannot express it, so exact-head merges use the authenticated API path.
+        # tea cannot express it, so every Gitea merge uses the authenticated API path.
         merge_gitea_with_api "$HOST"
         ;;
     *)

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

@@ -243,15 +243,35 @@ from urllib.parse import urlparse
 
 
 def _origin_and_path(url):
-    # Normalize a URL to (scheme, host, effective-port) + comment path. The port
-    # defaults to the scheme's default (80 http / 443 otherwise) so an implicit
-    # port and its explicit default form compare equal.
+    # Normalize a URL to (scheme-class, host, distinguishing-port) + comment path.
+    #
+    # #991: http and https collapse into ONE scheme class ("web"). A Gitea whose
+    # ROOT_URL is configured http:// returns http:// object URLs even when every
+    # client reaches it over https://, so a scheme-strict comparison rejects the
+    # provider's own correct answer about a comment that landed — a deterministic
+    # false negative on EVERY review comment posted against such a deployment.
+    # That matters more here than anywhere else: on a host where no seat can
+    # create a review OBJECT, the comment-form review record this path produces
+    # is the only gate-16 evidence available, and this check refuses all of it.
+    # The scheme is also not what the check defends: the forgeries it exists to
+    # catch (look-alike host, decoy path prefix, wrong owner/repo/kind/number)
+    # all vary the HOST or the PATH, both of which stay strict below. Any OTHER
+    # scheme (file:, ftp:, javascript:) remains distinguishing and is rejected.
+    #
+    # Port: an implicit port and its own scheme's default compare equal, so
+    # http://h == https://h. An EXPLICIT non-default port still distinguishes,
+    # because a different port is a different service on the same host.
     parsed = urlparse(url or "")
     scheme = (parsed.scheme or "").lower()
     host = (parsed.hostname or "").lower()
-    default_port = 80 if scheme == "http" else 443
-    port = parsed.port if parsed.port is not None else default_port
-    return (scheme, host, port), parsed.path.rstrip("/")
+    if scheme in ("http", "https"):
+        scheme_class = "web"
+        default_port = 80 if scheme == "http" else 443
+        port = None if parsed.port in (None, default_port) else parsed.port
+    else:
+        scheme_class = scheme
+        port = parsed.port
+    return (scheme_class, host, port), parsed.path.rstrip("/")
 
 
 try:

packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh

@@ -9,10 +9,51 @@ WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/ci-queue-wait-tristate}
 REPO_DIR="$WORK_DIR/repo"
 STUB_DIR="$WORK_DIR/stubs"
 AUDIT_LOG="$WORK_DIR/audit/ci-queue-wait.jsonl"
+STATUS_OBSERVED="$WORK_DIR/status-observed"
+CLOCK_LOG="$WORK_DIR/clock.log"
+WATCHDOG_PYTHON="/usr/bin/python3"
+WATCHDOG_SCRIPT="$WORK_DIR/real-clock-watchdog.py"
+WATCHDOG_TIMEOUT_SEC=5
+WATCHDOG_EXIT=90
 FEATURE_BRANCH="fix/rm-03-fixture"
 
+if [[ ! -x "$WATCHDOG_PYTHON" ]]; then
+    echo "FAIL setup: required real-clock watchdog runtime is unavailable at $WATCHDOG_PYTHON" >&2
+    exit 1
+fi
+
 rm -rf "$WORK_DIR"
 mkdir -p "$REPO_DIR" "$STUB_DIR"
+cat > "$WATCHDOG_SCRIPT" <<'PY'
+import os
+import signal
+import subprocess
+import sys
+
+if len(sys.argv) < 3:
+    raise SystemExit(2)
+
+timeout_seconds = float(sys.argv[1])
+process = subprocess.Popen(sys.argv[2:], start_new_session=True)
+try:
+    return_code = process.wait(timeout=timeout_seconds)
+except subprocess.TimeoutExpired:
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    process.wait()
+    print(
+        f"FAIL HANG watchdog: subject exceeded {timeout_seconds:g}s "
+        "before completing its intended path",
+        file=sys.stderr,
+    )
+    raise SystemExit(90)
+
+if return_code < 0:
+    raise SystemExit(128 - return_code)
+raise SystemExit(return_code)
+PY
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" checkout -q -b "$FEATURE_BRANCH"
 git -C "$REPO_DIR" remote add origin https://git.example.test/acme/widgets.git
@@ -33,6 +74,9 @@ printf '%s\n' "$url" >> "${MOSAIC_STUB_URL_LOG:?}"
 
 case "$url" in
     */branches/*)
+        if [[ "${MOSAIC_STUB_BRANCH_MODE:-ok}" == "hang-before-provider" ]]; then
+            while :; do :; done
+        fi
         if [[ "${MOSAIC_STUB_BRANCH_MODE:-ok}" == "unreachable" ]]; then
             exit 7
         fi
@@ -44,6 +88,7 @@ case "$url" in
         fi
         ;;
     */status)
+        : > "${MOSAIC_STUB_STATUS_OBSERVED:?}"
         case "${MOSAIC_STUB_STATUS_MODE:?}" in
             success)   printf '%s' '{"state":"success","statuses":[{"status":"success"}]}' ;;
             pending)   printf '%s' '{"state":"pending","statuses":[{"status":"pending","context":"ci/test"}]}' ;;
@@ -64,7 +109,31 @@ case "$url" in
     *) echo "unexpected curl URL: $url" >&2; exit 2 ;;
 esac
 SH
-chmod +x "$STUB_DIR/curl"
+
+cat > "$STUB_DIR/date" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "$#" -ne 1 || "$1" != "+%s" ]]; then
+    echo "unexpected date invocation: $*" >&2
+    exit 2
+fi
+
+if [[ -e "${MOSAIC_STUB_STATUS_OBSERVED:?}" ]]; then
+    printf 'date-phase=after-status\n' >> "${MOSAIC_STUB_CLOCK_LOG:?}"
+    printf '1002\n'
+else
+    printf 'date-phase=before-status\n' >> "${MOSAIC_STUB_CLOCK_LOG:?}"
+    printf '1000\n'
+fi
+SH
+
+cat > "$STUB_DIR/sleep" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'sleep-after-status=%s\n' "$*" >> "${MOSAIC_STUB_CLOCK_LOG:?}"
+SH
+chmod +x "$STUB_DIR/curl" "$STUB_DIR/date" "$STUB_DIR/sleep"
 
 run_guard() {
     local status_mode="$1"
@@ -84,13 +153,46 @@ run_guard() {
             export GITEA_URL=https://git.example.test
             export MOSAIC_STUB_STATUS_MODE="$status_mode"
         fi
+        rm -f "$STATUS_OBSERVED" "$CLOCK_LOG"
         export MOSAIC_STUB_URL_LOG="$WORK_DIR/urls.log"
+        export MOSAIC_STUB_STATUS_OBSERVED="$STATUS_OBSERVED"
+        export MOSAIC_STUB_CLOCK_LOG="$CLOCK_LOG"
         export MOSAIC_CI_QUEUE_AUDIT_LOG="$audit_log"
-        "$SCRIPT_DIR/ci-queue-wait.sh" --purpose "${MOSAIC_TEST_PURPOSE:-push}" -t 0 -i 0 "$@"
+        # Provider observation is the synchronization event. The one-second
+        # timeout is subject semantics under virtual time, never a wall wait.
+        # The absolute Python runtime uses an internal monotonic wait and kills
+        # the subject's isolated process group. Neither operation can resolve
+        # to the virtual date/sleep stubs at the front of PATH.
+        local subject_rc
+        if "$WATCHDOG_PYTHON" "$WATCHDOG_SCRIPT" "$WATCHDOG_TIMEOUT_SEC" \
+            "$SCRIPT_DIR/ci-queue-wait.sh" --purpose "${MOSAIC_TEST_PURPOSE:-push}" -t 1 -i 1 "$@"; then
+            subject_rc=0
+        else
+            subject_rc=$?
+        fi
+        return "$subject_rc"
     )
 }
 
 failures=0
+assert_provider_observed() {
+    local name="$1" require_expiration="${2:-0}"
+    if [[ ! -e "$STATUS_OBSERVED" ]]; then
+        echo "FAIL $name: status provider was not observed" >&2
+        failures=$((failures + 1))
+    fi
+    if [[ ! -s "$CLOCK_LOG" ]] || ! grep -q '^date-phase=before-status$' "$CLOCK_LOG"; then
+        echo "FAIL $name: virtual clock interception did not run before provider observation" >&2
+        failures=$((failures + 1))
+    fi
+    if [[ "$require_expiration" -eq 1 ]]; then
+        if ! grep -q '^sleep-after-status=' "$CLOCK_LOG" || ! grep -q '^date-phase=after-status$' "$CLOCK_LOG"; then
+            echo "FAIL $name: pending path did not expire after provider observation" >&2
+            failures=$((failures + 1))
+        fi
+    fi
+}
+
 run_assertion() {
     local name="$1" expected_rc="$2" status_mode="$3" required_text="$4"
     local output rc
@@ -125,6 +227,13 @@ run_assertion() {
         printf '%s\n' "$output" >&2
         failures=$((failures + 1))
     fi
+    if [[ "$status_mode" != "credential-unresolvable" ]]; then
+        if [[ "$status_mode" == "pending" ]]; then
+            assert_provider_observed "$name" 1
+        else
+            assert_provider_observed "$name"
+        fi
+    fi
 }
 
 set -e
@@ -150,6 +259,27 @@ MOSAIC_TEST_PURPOSE=merge run_assertion merge-failure nonzero failure 'ASSERTED_
 MOSAIC_TEST_PURPOSE=merge run_assertion merge-no-status nonzero no-status 'ASSERTED_NOT_READY state=no-status'
 MOSAIC_TEST_PURPOSE=merge run_assertion merge-unknown nonzero unknown 'ASSERTED_NOT_READY state=unknown'
 
+# Positive liveness control: a subject mutant hangs before the branch lookup
+# can reach the status provider. Only the independent real-clock watchdog may
+# terminate it, and its failure must be distinct from subject timeout rc=124.
+set +e
+watchdog_output=$(MOSAIC_STUB_BRANCH_MODE=hang-before-provider run_guard success "$AUDIT_LOG" 2>&1)
+watchdog_rc=$?
+set -e
+if [[ "$watchdog_rc" -ne "$WATCHDOG_EXIT" ]]; then
+    echo "FAIL watchdog-control: expected hang-specific rc=$WATCHDOG_EXIT, got rc=$watchdog_rc" >&2
+    failures=$((failures + 1))
+fi
+if [[ "$watchdog_output" != *"FAIL HANG watchdog:"* ]]; then
+    echo "FAIL watchdog-control: expected distinct hang-specific diagnostic" >&2
+    printf '%s\n' "$watchdog_output" >&2
+    failures=$((failures + 1))
+fi
+if [[ -e "$STATUS_OBSERVED" ]]; then
+    echo "FAIL watchdog-control: hanging mutant unexpectedly reached the status provider" >&2
+    failures=$((failures + 1))
+fi
+
 if [[ ! -s "$AUDIT_LOG" ]] || ! grep -q '"outcome":"CANNOT_ASSERT"' "$AUDIT_LOG"; then
     echo "FAIL provider-unreachable-audit: expected durable CANNOT_ASSERT JSONL record" >&2
     failures=$((failures + 1))
@@ -170,6 +300,7 @@ if [[ "$merge_unreachable_output" != *"CANNOT_ASSERT"* ]]; then
     echo "FAIL merge-provider-unreachable: expected loud CANNOT_ASSERT diagnostic" >&2
     failures=$((failures + 1))
 fi
+assert_provider_observed merge-provider-unreachable
 merge_audit_lines_after=$(wc -l < "$AUDIT_LOG")
 if [[ "$merge_audit_lines_after" -le "$merge_audit_lines_before" ]]; then
     echo "FAIL merge-provider-unreachable: expected an additional audit record" >&2
@@ -233,6 +364,7 @@ if [[ "$audit_failure_output" != *"audit"* ]]; then
     echo "FAIL audit-unavailable: expected loud audit failure diagnostic" >&2
     failures=$((failures + 1))
 fi
+assert_provider_observed audit-unavailable
 
 if [[ "$failures" -ne 0 ]]; then
     echo "ci-queue-wait tri-state regression failed ($failures assertions)" >&2