fleet: move directories off managed paths instead of refusing forever

Launch will not delete a real directory sitting where it expects a managed
link -- an auth/<harness>/primary that someone logged into by hand, or a
plugin directory a seat acquired before the central store existed. That
refusal is right and it is also a dead end: the operator gets a composition
error and no way forward.

`mosaic fleet adopt` is the way forward. Bare, it lists every such directory
and the command that resolves it. With a verb, it moves one where it belongs.

Nothing here deletes. A promotion is a rename; an occupied destination is a
refusal, not a merge; a cross-device rename is reported rather than retried as
copy-then-delete, because a copy-then-delete is a delete.

Store adoption stops at the move and does not install the link. The seat's
.mosaic-managed-links.json belongs to launch, and a link written behind it
fails the next composition as an unrecorded symlink -- one refusal traded for
another. The next launch installs and records it when the profile lists the
entry; whether a seat gets a plugin stays `mosaic fleet plugin`'s decision.

W-F3 of docs/plans/2026-08-14_fleet-seats-on-web1.md.

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', () => {
+describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding (router-delegated legacy runtime)', () => {
-  it('does not send a prompt into another owner/tenant session by guessed conversationId', async () => {
+  // TESS test A — REST /api/chat send. The genuine RED is the router-delegation redesign, not a slot
-    const agentService = makeScopedAgentService();
+  // swap: the forbidden directly-injected AgentService must go UNtouched while the server-derived
-    const controller = new ChatController(agentService as never);
+  // 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 });
 
+      // 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.toMatchObject({ status: 404 });
+      ).rejects.toBeDefined();
 
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      // 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,
       });
-    expect(agentService.prompt).not.toHaveBeenCalled();
+
+      // 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', () => {
+describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding (router-delegated legacy runtime)', () => {
-  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 };
-  }
-
   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 () => {
+  // TESS test B — WebSocket send/attach.
-    const { gateway, agentService } = makeGateway();
+  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, {
+      await Promise.resolve(
+        gateway.handleMessage(socket as never, {
           conversationId: CONVERSATION_ID,
           content: 'attach to foreign session',
-    });
+        }),
+      ).catch(() => undefined);
 
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      // 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,
       });
-    expect(agentService.onEvent).not.toHaveBeenCalled();
+      // Foreign session gets zero lease/listener/channel/prompt on EITHER path (holds today and GREEN).
-    expect(agentService.addChannel).not.toHaveBeenCalled();
+      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(
+    expect(harnessConversation.attach).not.toHaveBeenCalled();
-      'error',
+    expect(harnessConversation.send).not.toHaveBeenCalled();
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 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);
+
+    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;
+
+    const first = await lease.dispatch();
+    expect(first).toEqual({ ok: true, value: undefined });
+    expect(svc.prompt).toHaveBeenCalledTimes(1);
+
+    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');
+    });
+    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);
   });
+});
 
-  it('does not mutate thinking level on another owner/tenant session', () => {
+describe('TESS Task-5 embedded REST turn teardown (a prompt rejection frees the timer + listener exactly once)', () => {
-    const { gateway, agentService } = makeGateway();
+  const ctx = ownConversation(CONVERSATION_ID, EMBEDDED_SCOPE);
-    const socket = makeSocket();
 
-    gateway.handleSetThinking(socket as never, { conversationId: CONVERSATION_ID, level: 'high' });
+  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);
 
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+    // A rejected `done` promise firing after completeLegacyRestTurn has already returned would
-      userId: USER_B.id,
+    // surface as an unhandledRejection — the leak this test fences. Capture any that escape.
-      tenantId: USER_B.tenantId,
+    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',
       });
-    expect(socket.emit).toHaveBeenCalledWith(
+
-      'error',
+      // The rejection collapses to a total safe failure (not a timeout) — never throws out of the port.
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+      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('does not terminate another owner/tenant session over WebSocket abort', async () => {
+  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 { gateway, agentService } = makeGateway();
+    const session = makeAgentSession(USER_A);
-    const socket = makeSocket();
+    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);
 
-    await gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID });
+    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;
+
+      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, {
+  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 () => {
-      userId: USER_B.id,
+    const session = makeAgentSession(USER_A);
-      tenantId: USER_B.tenantId,
+    const detach = vi.fn();
+    let rejectPrompt: (reason: unknown) => void = () => undefined;
+    const prompting = new Promise<void>((_resolve, reject) => {
+      rejectPrompt = reject;
     });
-    expect(socket.emit).toHaveBeenCalledWith(
+    const svc = {
-      'error',
+      getSession: vi.fn(() => session),
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+      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/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 done = new Promise<void>((resolve, reject) => {
+    const result = await this.runtime.completeLegacyRestTurn(
-      const timer = setTimeout(() => {
+      ownConversation(conversationId, scope),
-        cleanup();
+      { content: body.content },
-        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 {
+    if (result.ok) {
-      await this.agentService.prompt(conversationId, body.content, scope);
+      return { conversationId, text: result.value.text };
-      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);
     }
 
-    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],
+  providers: [
-  exports: [ChatGateway],
+    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/harness/harness.module.ts

@@ -1,7 +1,12 @@
 import { Module } from '@nestjs/common';
 import { HarnessRegistry } from './harness.registry.js';
 import { HarnessService } from './harness.service.js';
-import { HARNESS_REGISTRY, HARNESS_SERVICE } from './harness.tokens.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';
@@ -20,9 +25,13 @@ import { HarnessSelectionRepository } from './harness-selection.repository.js';
   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],
+  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/spa/chat/composer.tsx

@@ -1,8 +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
@@ -44,11 +45,17 @@ export function Composer({
     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) return;
+    if (!harness.canSend || harness.persistedSelection === null) return;
     const trimmed = content.trim();
     if (!trimmed) return;
-    onSend({ content: trimmed, ...harness.projection });
+    // Pass the validated, persisted selection tuple only. The hook derives the
-    setContent('');
+    // 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 {

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. */
+   * without clearing or replacing any listeners. A real reconnect is assigned
-  simulateReconnect(): void;
+   * 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 }) => {
+    sendMessage: ({ content, selection }) => {
-      if (sendLockRef.current || state.streaming || state.sending) return;
+      // 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();
-      if (!socket.connected) socket.connect();
           dispatch({ type: 'local/send', content });
           socket.emit('message', {
             conversationId: state.conversationId ?? undefined,
             content,
-        provider,
+            provider: selection?.providerId,
-        modelId,
+            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

@@ -226,7 +226,10 @@ describe('useHarnessSelection', () => {
       modelId: 'gpt-5',
     });
     expect(value().canSend).toBe(true);
-    expect(value().projection).toEqual({ provider: 'openai', modelId: 'gpt-5' });
+    // 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 () => {
@@ -386,7 +389,8 @@ describe('useHarnessSelection', () => {
       providerId: 'anthropic',
       modelId: 'claude',
     });
-    expect(value().projection).toEqual({ provider: '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 () => {
@@ -420,7 +424,8 @@ describe('useHarnessSelection', () => {
     });
     await flush();
     expect(value().canSend).toBe(true);
-    expect(value().projection).toEqual({ provider: 'anthropic', modelId: 'claude' });
+    // 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 () => {

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

@@ -42,10 +42,6 @@ export interface HarnessSelectionValue {
    * 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;
-  /** The compatibility `{provider, modelId}` projection for the legacy socket
-   * send path — derived ONLY from the validated persisted tuple, never from any
-   * free-text or unpersisted draft. Empty when nothing is sendable. */
-  projection: { provider?: string; modelId?: string };
 }
 
 /** A tuple is a currently-usable catalog option only when the catalog holds a
@@ -193,9 +189,6 @@ export function useHarnessSelection(): HarnessSelectionValue {
     !catalogUnavailable &&
     tuplesEqual(draft, persistedSelection) &&
     isAvailableInCatalog(persistedSelection, catalog);
-  const projection: { provider?: string; modelId?: string } = canSend
-    ? { provider: persistedSelection.providerId, modelId: persistedSelection.modelId }
-    : {};
 
   return {
     harnesses,
@@ -211,6 +204,5 @@ export function useHarnessSelection(): HarnessSelectionValue {
     selectHarness,
     selectProvider,
     selectModel,
-    projection,
   };
 }

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

@@ -108,6 +108,58 @@ async function flushAsync(times = 5): Promise<void> {
   }
 }
 
+/** 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;
@@ -137,6 +189,12 @@ beforeEach(async () => {
   // 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 () => {
@@ -159,6 +217,11 @@ async function remountWithFetch(fetchImpl: typeof fetch): Promise<void> {
     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', () => {
@@ -571,6 +634,156 @@ 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));
 

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,60 +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"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "^/mosaic-promote$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ~/.config/mosaic/tools/lease-broker/promote-begin.py",
-            "timeout": 15
-          }
-        ]
-      }
-    ],
     "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": [
@@ -91,11 +38,6 @@
     "Stop": [
       {
         "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
-          },
           {
             "type": "command",
             "command": "~/.config/mosaic/tools/qa/reflect-stop-hook.sh",
@@ -315,5 +257,11 @@
     "cpan",
     "nohup"
   ],
-  "enableAllMcpTools": true
+  "enableAllMcpTools": true,
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
 }

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"
+# Claude reads MCP definitions from .claude.json, not settings.json. The
-if not p.exists():
+# 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/fleet/start-agent-session.sh

@@ -286,12 +286,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}}"
+  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 +337,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
 

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

@@ -409,4 +409,23 @@ if echo "$stop_args" | grep -qF '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/src/cli.ts

@@ -25,6 +25,7 @@ import { registerLaunchCommands } from './commands/launch.js';
 import { registerLeaseCapabilityProbe } from './commands/lease-activation-probe.js';
 import { registerInstallOrderingGuardCommand } from './commands/install-ordering-guard.js';
 import { registerAuthCommand } from './commands/auth.js';
+import { registerFleetAuthCommands } from './commands/fleet-auth-command.js';
 import { registerFederationCommand } from './commands/federation.js';
 import { registerGatewayCommand } from './commands/gateway.js';
 import {
@@ -350,7 +351,7 @@ sessionsCmd
 
 // ─── auth ────────────────────────────────────────────────────────────────
 
-registerAuthCommand(program);
+registerFleetAuthCommands(registerAuthCommand(program));
 
 // ─── gateway ──────────────────────────────────────────────────────────
 

packages/mosaic/src/commands/auth.ts

@@ -139,10 +139,11 @@ function printUser(u: UserDto): void {
  * Keeping packages/auth as a pure server-side library avoids adding commander
  * and CLI tooling as dependencies there.
  */
-export function registerAuthCommand(parent: Command): void {
+/** Returns the `auth` command so local (non-gateway) verbs can be attached to it. */
+export function registerAuthCommand(parent: Command): Command {
   const auth = parent
     .command('auth')
-    .description('Manage gateway authentication, users, SSO providers, and sessions')
+    .description('Manage authentication: local credential bundles, and gateway users and sessions')
     .configureHelp({ sortSubcommands: true })
     .action(() => {
       auth.outputHelp();
@@ -328,4 +329,6 @@ export function registerAuthCommand(parent: Command): void {
       );
       void opts;
     });
+
+  return auth;
 }

packages/mosaic/src/commands/fleet-adopt-command.spec.ts

@@ -0,0 +1,196 @@
+import { mkdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { registerFleetAdoptCommand } from './fleet-adopt-command.js';
+
+let root: string | undefined;
+
+interface Harness {
+  readonly home: string;
+  readonly out: string[];
+  readonly err: string[];
+  readonly run: (argv: string[]) => Promise<void>;
+}
+
+beforeEach((): void => {
+  process.exitCode = undefined;
+});
+
+afterEach(async (): Promise<void> => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+async function harness(): Promise<Harness> {
+  root = await mkdtemp(join(tmpdir(), 'mosaic-adopt-cmd-'));
+  const home = join(root, '.mosaic');
+  const out: string[] = [];
+  const err: string[] = [];
+  vi.spyOn(console, 'log').mockImplementation((...parts: unknown[]): void => {
+    out.push(parts.map(String).join(' '));
+  });
+  vi.spyOn(process.stderr, 'write').mockImplementation((chunk: unknown): boolean => {
+    err.push(String(chunk));
+    return true;
+  });
+  const program = new Command();
+  program.exitOverride();
+  const fleet = program.command('fleet');
+  registerFleetAdoptCommand(fleet, { fleetDataHome: home });
+  return {
+    home,
+    out,
+    err,
+    run: async (argv: string[]): Promise<void> => {
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'adopt', ...argv]);
+    },
+  };
+}
+
+function realAliasDirectory(home: string, harnessName: string): string {
+  const path = join(home, 'auth', harnessName, 'primary');
+  mkdirSync(path, { recursive: true });
+  writeFileSync(join(path, '.credentials.json'), '{"token":"kept"}');
+  return path;
+}
+
+function seat(home: string, name: string, profile: Record<string, unknown>): void {
+  const dir = join(home, 'fleet', 'agents', name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'profile.json'), `${JSON.stringify(profile, null, 2)}\n`);
+}
+
+function seatDirectory(home: string, agent: string, plural: string, name: string): string {
+  const path = join(home, 'fleet', 'agents', agent, '.claude', plural, name);
+  mkdirSync(path, { recursive: true });
+  writeFileSync(join(path, 'marker.txt'), 'kept');
+  return path;
+}
+
+describe('mosaic fleet adopt', () => {
+  it('says there is nothing to adopt on a clean host', async () => {
+    const h = await harness();
+
+    await h.run([]);
+
+    expect(h.out.join('\n')).toContain('Nothing to adopt');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  // A read-only listing that exits non-zero is one people stop running, so the scan reports
+  // and stays out of the way.
+  it('lists each finding with the command that resolves it, and exits zero', async () => {
+    const h = await harness();
+    const path = realAliasDirectory(h.home, 'claude');
+
+    await h.run([]);
+
+    const printed = h.out.join('\n');
+    expect(printed).toContain(path);
+    expect(printed).toContain('resolve: mosaic fleet adopt bundle --harness claude --as <account>');
+    expect(printed).toContain('1 found, 0 needing a decision before adoption. Nothing was moved.');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('separates findings it can resolve from findings that need a decision first', async () => {
+    const h = await harness();
+    seat(h.home, 'uc-e6-coder', { schema: 1, harness: 'claude', bundle: 'primary' });
+    seatDirectory(h.home, 'uc-e6-coder', 'plugins', 'reviewer');
+    mkdirSync(join(h.home, 'plugins', 'reviewer'), { recursive: true });
+
+    await h.run([]);
+
+    const printed = h.out.join('\n');
+    expect(printed).toContain('blocked (destination occupied)');
+    expect(printed).toContain('1 found, 1 needing a decision before adoption.');
+  });
+
+  it('adopts a bundle and reports where the credentials went and what the alias points at', async () => {
+    const h = await harness();
+    realAliasDirectory(h.home, 'claude');
+
+    await h.run(['bundle', '--harness', 'claude', '--as', 'jason_woltje.com']);
+
+    const target = join(h.home, 'auth', 'claude', 'jason_woltje.com');
+    expect(readFileSync(join(target, '.credentials.json'), 'utf8')).toBe('{"token":"kept"}');
+    const printed = h.out.join('\n');
+    expect(printed).toContain(`bundle:  ${target}`);
+    expect(printed).toContain('-> jason_woltje.com');
+    // The name is the operator's claim about the account; only a listing shows what is in it.
+    expect(printed).toContain('mosaic auth list --harness claude');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('rejects an unknown harness instead of building a path out of it', async () => {
+    const h = await harness();
+
+    await h.run(['bundle', '--harness', 'nonsense', '--as', 'x']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('--harness must be one of: claude, codex, opencode, pi');
+  });
+
+  it('exits non-zero and names the failure when there is nothing to adopt', async () => {
+    const h = await harness();
+
+    await h.run(['bundle', '--harness', 'pi', '--as', 'jason_woltje.com']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('mosaic fleet adopt bundle failed (nothing-to-adopt)');
+  });
+
+  it('adopts a plugin into the store and says the next launch links it back', async () => {
+    const h = await harness();
+    seat(h.home, 'uc-e6-coder', {
+      schema: 1,
+      harness: 'claude',
+      bundle: 'primary',
+      plugins: ['reviewer'],
+    });
+    seatDirectory(h.home, 'uc-e6-coder', 'plugins', 'reviewer');
+
+    await h.run(['plugin', 'reviewer', '--seat', 'uc-e6-coder']);
+
+    expect(readFileSync(join(h.home, 'plugins', 'reviewer', 'marker.txt'), 'utf8')).toBe('kept');
+    expect(h.out.join('\n')).toContain('next launch links it back from the store');
+  });
+
+  it('says plainly when no seat uses the adopted entry yet', async () => {
+    const h = await harness();
+    seat(h.home, 'uc-e6-coder', { schema: 1, harness: 'claude', bundle: 'primary' });
+    seatDirectory(h.home, 'uc-e6-coder', 'plugins', 'reviewer');
+
+    await h.run(['plugin', 'reviewer', '--seat', 'uc-e6-coder']);
+
+    expect(h.out.join('\n')).toContain("is not listed in uc-e6-coder's profile");
+  });
+
+  it('adopts a skill into the skill store, not the plugin store', async () => {
+    const h = await harness();
+    seat(h.home, 'uc-e6-rev', { schema: 1, harness: 'claude', bundle: 'primary' });
+    seatDirectory(h.home, 'uc-e6-rev', 'skills', 'spec-audit');
+
+    await h.run(['skill', 'spec-audit', '--seat', 'uc-e6-rev']);
+
+    expect(readFileSync(join(h.home, 'skills', 'spec-audit', 'marker.txt'), 'utf8')).toBe('kept');
+  });
+
+  it('leaves an already-linked entry alone and exits non-zero', async () => {
+    const h = await harness();
+    seat(h.home, 'uc-e6-coder', { schema: 1, harness: 'claude', bundle: 'primary' });
+    mkdirSync(join(h.home, 'plugins', 'reviewer'), { recursive: true });
+    const installRoot = join(h.home, 'fleet', 'agents', 'uc-e6-coder', '.claude', 'plugins');
+    mkdirSync(installRoot, { recursive: true });
+    symlinkSync(join(h.home, 'plugins', 'reviewer'), join(installRoot, 'reviewer'));
+
+    await h.run(['plugin', 'reviewer', '--seat', 'uc-e6-coder']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('already a link into the store');
+  });
+});

packages/mosaic/src/commands/fleet-adopt-command.ts

@@ -0,0 +1,137 @@
+/**
+ * `mosaic fleet adopt` -- resolve the real directories that sit where a managed link belongs.
+ *
+ * Launch refuses to delete anything an operator put on a managed path, which is right, but on
+ * its own it leaves the operator holding a composition error and no way forward. This command
+ * is the way forward: bare, it lists every such directory and the command that resolves it;
+ * with a verb, it moves one of them where it belongs.
+ *
+ * The bare scan reads only, and exits zero whatever it finds. It is meant to be safe to run
+ * out of curiosity, and a non-zero exit from a read-only listing would make it something
+ * people avoid running.
+ */
+
+import type { Command } from 'commander';
+import {
+  AdoptionError,
+  type StoreKind,
+  promoteBundleAlias,
+  promoteStoreEntry,
+  scanAdoptions,
+} from '../fleet/adoption.js';
+import type { CredentialHarness } from '../fleet/credential-sharing.js';
+import { defaultFleetDataHome } from '../fleet/fleet-agent-scaffold.js';
+
+const HARNESSES: readonly CredentialHarness[] = ['claude', 'codex', 'opencode', 'pi'];
+
+export interface FleetAdoptCommandDeps {
+  /** Test seam for the user-owned ~/.mosaic root. */
+  readonly fleetDataHome?: string;
+}
+
+function requireHarness(value: string | undefined): CredentialHarness {
+  if (value === undefined || !HARNESSES.includes(value as CredentialHarness)) {
+    throw new AdoptionError('invalid-request', `--harness must be one of: ${HARNESSES.join(', ')}`);
+  }
+  return value as CredentialHarness;
+}
+
+function requireSeat(value: string | undefined): string {
+  if (value === undefined || value.trim() === '') {
+    throw new AdoptionError(
+      'invalid-request',
+      'give the seat this directory belongs to: --seat <agent>',
+    );
+  }
+  return value;
+}
+
+function fail(error: unknown, verb: string): void {
+  process.exitCode = 1;
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error instanceof AdoptionError ? error.code : 'failed';
+  process.stderr.write(
+    `mosaic fleet adopt${verb === '' ? '' : ` ${verb}`} failed (${code}): ${message}\n`,
+  );
+}
+
+/** Registers the adoption scan and its three promotion verbs. */
+export function registerFleetAdoptCommand(
+  fleetCommand: Command,
+  deps: FleetAdoptCommandDeps = {},
+): void {
+  const dataHome = (): string => deps.fleetDataHome ?? defaultFleetDataHome();
+
+  const adopt = fleetCommand
+    .command('adopt')
+    .description('Find and resolve real directories occupying paths the fleet manages with links')
+    .action((): void => {
+      try {
+        const findings = scanAdoptions(dataHome());
+        if (findings.length === 0) {
+          console.log('Nothing to adopt: no real directory occupies a managed path.');
+          return;
+        }
+        for (const finding of findings) {
+          console.log(finding.path);
+          console.log(`  ${finding.reason}`);
+          console.log(
+            finding.blocked === undefined
+              ? `  resolve: ${finding.remedy}`
+              : `  blocked (${finding.blocked}): ${finding.remedy}`,
+          );
+        }
+        const blocked = findings.filter((finding) => finding.blocked !== undefined).length;
+        console.log(
+          `\n${String(findings.length)} found, ${String(blocked)} needing a decision before adoption. Nothing was moved.`,
+        );
+      } catch (error: unknown) {
+        fail(error, '');
+      }
+    });
+
+  adopt
+    .command('bundle')
+    .description(`Adopt a real directory on the "primary" alias path as a named bundle`)
+    .requiredOption('--harness <harness>', `Harness: ${HARNESSES.join(', ')}`)
+    .requiredOption('--as <bundle>', 'Account this directory holds, e.g. jason_woltje.com')
+    .action((options: { harness?: string; as: string }): void => {
+      try {
+        const result = promoteBundleAlias(dataHome(), requireHarness(options.harness), options.as);
+        console.log(`Adopted ${result.from}`);
+        console.log(`  bundle:  ${result.to}`);
+        console.log(`  alias:   ${result.alias} -> ${result.bundle}`);
+        console.log(
+          `\nCheck the account it actually holds before trusting the name:\n  mosaic auth list --harness ${result.harness}`,
+        );
+      } catch (error: unknown) {
+        fail(error, 'bundle');
+      }
+    });
+
+  for (const store of ['plugin', 'skill'] as const) {
+    adopt
+      .command(`${store} <name>`)
+      .description(`Move a real ${store} directory out of a seat and into the central store`)
+      .requiredOption('--seat <agent>', 'Seat the directory currently sits in')
+      .action((name: string, options: { seat?: string }): void => {
+        try {
+          const result = promoteStoreEntry(
+            dataHome(),
+            requireSeat(options.seat),
+            store as StoreKind,
+            name,
+          );
+          console.log(`Adopted ${result.from}`);
+          console.log(`  store: ${result.to}`);
+          console.log(
+            result.listedInProfile
+              ? `\n"${result.name}" is listed in ${result.agent}'s profile, so its next launch links it back from the store.`
+              : `\n"${result.name}" is not listed in ${result.agent}'s profile, so no seat uses it yet. It is now vetted store content any seat can be given.`,
+          );
+        } catch (error: unknown) {
+          fail(error, store);
+        }
+      });
+  }
+}

packages/mosaic/src/commands/fleet-agent-scaffold-command.spec.ts

@@ -0,0 +1,297 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import {
+  lstat,
+  mkdtemp,
+  readFile,
+  readdir,
+  readlink,
+  rm,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { registerFleetAgentScaffoldCommand } from './fleet-agent-scaffold-command.js';
+
+let root: string | undefined;
+
+afterEach(async (): Promise<void> => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+async function fleetDataHome(): Promise<string> {
+  root = await mkdtemp(join(tmpdir(), 'mosaic-fleet-agent-new-'));
+  return join(root, '.mosaic');
+}
+
+function program(dataHome: string): Command {
+  const result = new Command();
+  result.exitOverride();
+  const fleet = result.command('fleet');
+  const mosaicHome = join(root!, 'installed-mosaic');
+  mkdirSync(join(mosaicHome, 'runtime', 'claude'), { recursive: true });
+  writeFileSync(
+    join(mosaicHome, 'runtime', 'claude', 'settings.json'),
+    JSON.stringify({
+      mcpServers: {
+        'sequential-thinking': {
+          command: 'npx',
+          args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+        },
+      },
+    }),
+  );
+  registerFleetAgentScaffoldCommand(fleet, {
+    fleetDataHome: dataHome,
+    mosaicHomeFor: () => mosaicHome,
+  });
+  return result;
+}
+
+async function files(rootDir: string, prefix = ''): Promise<string[]> {
+  const result: string[] = [];
+  for (const entry of await readdir(join(rootDir, prefix), { withFileTypes: true })) {
+    const path = join(prefix, entry.name);
+    if (entry.isDirectory()) result.push(...(await files(rootDir, path)));
+    else result.push(path);
+  }
+  return result.sort();
+}
+
+describe('mosaic fleet agent new', (): void => {
+  it('creates the exact authored user-data scaffold under a temp ~/.mosaic root', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    await program(dataHome).parseAsync(['node', 'mosaic', 'fleet', 'agent', 'new', 'mira']);
+    const agent = join(dataHome, 'fleet', 'agents', 'mira');
+
+    // Claude reaches its bundle through CLAUDE_SECURESTORAGE_CONFIG_DIR at launch,
+    // so no credential link is planted in the seat home.
+    expect(await files(agent)).toEqual([
+      '.claude/.claude.json',
+      '.claude/.mosaic-managed-links.json',
+      '.claude/CLAUDE.md',
+      'SOUL.md',
+      'overlay.json',
+      'profile.json',
+    ]);
+    expect(JSON.parse(await readFile(join(agent, 'profile.json'), 'utf8'))).toEqual({
+      schema: 1,
+      harness: 'claude',
+      bundle: 'primary',
+      overlay: 'overlay.json',
+      env: { MOSAIC_AGENT_NAME: 'mira' },
+    });
+    expect(await readFile(join(agent, 'SOUL.md'), 'utf8')).toContain('## Identity');
+    expect(JSON.parse(await readFile(join(agent, '.claude', '.claude.json'), 'utf8'))).toEqual({
+      hasCompletedOnboarding: true,
+      theme: 'dark',
+      mcpServers: {
+        'sequential-thinking': {
+          command: 'npx',
+          args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+        },
+      },
+    });
+    expect(
+      JSON.parse(await readFile(join(agent, '.claude', '.mosaic-managed-links.json'), 'utf8')),
+    ).toEqual({ links: {} });
+  });
+
+  it('plants a managed credential link for a harness that is not shared by environment', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    await program(dataHome).parseAsync([
+      'node',
+      'mosaic',
+      'fleet',
+      'agent',
+      'new',
+      'pi-seat',
+      '--harness',
+      'pi',
+    ]);
+    const agent = join(dataHome, 'fleet', 'agents', 'pi-seat');
+    const credentialTarget = join(dataHome, 'auth', 'pi', 'primary', 'auth.json');
+
+    expect(await readlink(join(agent, '.pi', 'auth.json'))).toBe(credentialTarget);
+    expect(
+      JSON.parse(await readFile(join(agent, '.pi', '.mosaic-managed-links.json'), 'utf8')),
+    ).toEqual({ links: { [join(agent, '.pi', 'auth.json')]: credentialTarget } });
+  });
+
+  it('creates a Pi home without Claude onboarding state', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    await program(dataHome).parseAsync([
+      'node',
+      'mosaic',
+      'fleet',
+      'agent',
+      'new',
+      'pi-seat',
+      '--harness',
+      'pi',
+    ]);
+    expect(await files(join(dataHome, 'fleet', 'agents', 'pi-seat'))).toEqual([
+      '.pi/.mosaic-managed-links.json',
+      '.pi/AGENTS.md',
+      '.pi/auth.json',
+      'SOUL.md',
+      'overlay.json',
+      'profile.json',
+    ]);
+  });
+
+  it('round-trips quotes, backticks, and shell-looking input literally', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    const name = 'seat"`$(literal)`';
+    const bundle = 'bundle"`$(literal)`';
+    const model = 'model"`$(literal)`';
+    await program(dataHome).parseAsync([
+      'node',
+      'mosaic',
+      'fleet',
+      'agent',
+      'new',
+      name,
+      '--harness',
+      'pi',
+      '--bundle',
+      bundle,
+      '--model',
+      model,
+    ]);
+    const agent = join(dataHome, 'fleet', 'agents', name);
+    expect(JSON.parse(await readFile(join(agent, 'profile.json'), 'utf8'))).toMatchObject({
+      harness: 'pi',
+      bundle,
+      model,
+      env: { MOSAIC_AGENT_NAME: name },
+    });
+    expect(await readFile(join(agent, 'SOUL.md'), 'utf8')).toContain(`You are ${name},`);
+    expect(await readlink(join(agent, '.pi', 'auth.json'))).toBe(
+      join(dataHome, 'auth', 'pi', bundle, 'auth.json'),
+    );
+  });
+
+  it.each(['', '../outside', '/absolute', 'a/b', 'a\\b'])(
+    'rejects unsafe agent name %j with a non-zero outcome',
+    async (name: string): Promise<void> => {
+      const dataHome = await fleetDataHome();
+      const error = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+      try {
+        await program(dataHome).parseAsync(['node', 'mosaic', 'fleet', 'agent', 'new', name]);
+      } catch {
+        // Commander rejects a missing positional before the action. That is also
+        // a non-zero CLI failure; all other unsafe names reach the scaffold.
+        process.exitCode = 1;
+      }
+      expect(process.exitCode).toBe(1);
+      if (name !== '')
+        expect(error).toHaveBeenCalledWith(expect.stringContaining('invalid-request'));
+    },
+  );
+
+  it.each([
+    ['--harness', 'codex'],
+    ['--bundle', '../outside'],
+    ['--model', ''],
+  ])(
+    'returns non-zero for invalid %s input',
+    async (option: string, value: string): Promise<void> => {
+      const dataHome = await fleetDataHome();
+      const error = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+      await program(dataHome).parseAsync([
+        'node',
+        'mosaic',
+        'fleet',
+        'agent',
+        'new',
+        'mira',
+        option,
+        value,
+      ]);
+      expect(process.exitCode).toBe(1);
+      expect(error).toHaveBeenCalledWith(expect.stringContaining('invalid-request'));
+    },
+  );
+
+  it('is idempotent for byte-identical content and refuses a changed user file', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    const command = ['node', 'mosaic', 'fleet', 'agent', 'new', 'mira'];
+    await program(dataHome).parseAsync(command);
+    await program(dataHome).parseAsync(command);
+    expect(process.exitCode).toBeUndefined();
+
+    const soul = join(dataHome, 'fleet', 'agents', 'mira', 'SOUL.md');
+    await writeFile(soul, '# user-owned change\n');
+    const error = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    await program(dataHome).parseAsync(command);
+    expect(process.exitCode).toBe(1);
+    expect(error).toHaveBeenCalledWith(expect.stringContaining('SOUL.md'));
+    expect(await readFile(soul, 'utf8')).toBe('# user-owned change\n');
+  });
+
+  it('does not follow a managed credential link while comparing existing content', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    const command = ['node', 'mosaic', 'fleet', 'agent', 'new', 'pi-seat', '--harness', 'pi'];
+    await program(dataHome).parseAsync(command);
+    const credential = join(dataHome, 'fleet', 'agents', 'pi-seat', '.pi', 'auth.json');
+    expect((await lstat(credential)).isSymbolicLink()).toBe(true);
+    await program(dataHome).parseAsync(command);
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('tolerates a credential link left by a scaffold that predates environment sharing', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    const command = ['node', 'mosaic', 'fleet', 'agent', 'new', 'mira'];
+    await program(dataHome).parseAsync(command);
+    const seatHome = join(dataHome, 'fleet', 'agents', 'mira', '.claude');
+    const credential = join(seatHome, '.credentials.json');
+    const target = join(dataHome, 'auth', 'claude', 'primary', '.credentials.json');
+    await symlink(target, credential);
+    await writeFile(
+      join(seatHome, '.mosaic-managed-links.json'),
+      `${JSON.stringify({ links: { [credential]: target } }, null, 2)}\n`,
+    );
+
+    await program(dataHome).parseAsync(command);
+
+    expect(process.exitCode).toBeUndefined();
+    expect((await lstat(credential)).isSymbolicLink()).toBe(true);
+  });
+
+  it('scaffolds against canonical settings that declare no mcpServers', async (): Promise<void> => {
+    // The framework's shipped runtime/claude/settings.json has no mcpServers key, so
+    // requiring one refused to scaffold any Claude seat on a clean install. Measured on a
+    // greenfield Debian 13 VM against framework main.
+    const dataHome = await fleetDataHome();
+    const command = program(dataHome);
+    const settings = join(root!, 'installed-mosaic', 'runtime', 'claude', 'settings.json');
+    await writeFile(settings, JSON.stringify({ model: 'opus', hooks: {} }));
+
+    await command.parseAsync(['node', 'mosaic', 'fleet', 'agent', 'new', 'mira']);
+
+    expect(process.exitCode).toBeUndefined();
+    const claudeJson = join(dataHome, 'fleet', 'agents', 'mira', '.claude', '.claude.json');
+    expect(JSON.parse(await readFile(claudeJson, 'utf8'))).toEqual({
+      hasCompletedOnboarding: true,
+      theme: 'dark',
+      mcpServers: {},
+    });
+  });
+
+  it('still refuses canonical settings whose mcpServers is the wrong shape', async (): Promise<void> => {
+    const dataHome = await fleetDataHome();
+    const command = program(dataHome);
+    const settings = join(root!, 'installed-mosaic', 'runtime', 'claude', 'settings.json');
+    await writeFile(settings, JSON.stringify({ mcpServers: ['sequential-thinking'] }));
+
+    await command.parseAsync(['node', 'mosaic', 'fleet', 'agent', 'new', 'mira']);
+
+    expect(process.exitCode).toBe(1);
+  });
+});

packages/mosaic/src/commands/fleet-agent-scaffold-command.ts

@@ -0,0 +1,59 @@
+import type { Command } from 'commander';
+import { FleetAgentScaffoldError, scaffoldFleetAgent } from '../fleet/fleet-agent-scaffold.js';
+
+export interface FleetAgentScaffoldCommandDeps {
+  /** Test seam for the user-owned ~/.mosaic root. */
+  readonly fleetDataHome?: string;
+  /** Resolves the active installed Mosaic root that owns the canonical runtime base. */
+  readonly mosaicHomeFor?: () => string;
+}
+
+interface NewAgentOptions {
+  readonly harness?: string;
+  readonly bundle?: string;
+  readonly model?: string;
+}
+
+/** Registers the user-data seat scaffolder, distinct from roster-v2 CRUD. */
+export function registerFleetAgentScaffoldCommand(
+  fleetCommand: Command,
+  deps: FleetAgentScaffoldCommandDeps = {},
+): void {
+  const agent = fleetCommand
+    .command('agent')
+    .description('Manage user-owned fleet agent harness homes');
+
+  agent
+    .command('new <name>')
+    .description('Create an additive-or-refuse fleet agent harness home')
+    .option('--harness <harness>', 'Harness: claude or pi', 'claude')
+    .option('--bundle <bundle>', 'Auth bundle selector', 'primary')
+    .option('--model <model>', 'Optional harness-native model')
+    .action(async (name: string, options: NewAgentOptions): Promise<void> => {
+      try {
+        const result = await scaffoldFleetAgent({
+          name,
+          harness: options.harness,
+          bundle: options.bundle,
+          model: options.model,
+          ...(deps.fleetDataHome === undefined ? {} : { dataHome: deps.fleetDataHome }),
+          ...(deps.mosaicHomeFor === undefined ? {} : { mosaicHome: deps.mosaicHomeFor() }),
+        });
+        console.log(
+          result.idempotent
+            ? `Fleet agent "${name}" already matches the scaffold.`
+            : `Created fleet agent "${name}" at ${result.agentDir}.`,
+        );
+        if (!result.credentialTargetExists) {
+          console.log(
+            `Notice: auth bundle "${result.profile['bundle']}" is not enrolled yet, so no credential exists at ${result.credentialTarget}. The seat will refuse to launch until it does.`,
+          );
+        }
+      } catch (error: unknown) {
+        process.exitCode = 1;
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof FleetAgentScaffoldError ? error.code : 'scaffold-failed';
+        process.stderr.write(`mosaic fleet agent new failed (${code}): ${message}\n`);
+      }
+    });
+}

packages/mosaic/src/commands/fleet-auth-command.spec.ts

@@ -0,0 +1,365 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { registerFleetAuthCommands, type FleetAuthCommandDeps } from './fleet-auth-command.js';
+
+let root: string | undefined;
+
+afterEach(async (): Promise<void> => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+interface Harness {
+  readonly home: string;
+  readonly out: string[];
+  readonly err: string[];
+  readonly logins: Array<{ command: string; args: readonly string[]; env: Record<string, string> }>;
+  run: (argv: string[]) => Promise<void>;
+}
+
+async function harness(
+  overrides: Omit<FleetAuthCommandDeps, 'fleetDataHome'> = {},
+): Promise<Harness> {
+  root = await mkdtemp(join(tmpdir(), 'mosaic-auth-cmd-'));
+  const home = join(root, '.mosaic');
+  const out: string[] = [];
+  const err: string[] = [];
+  const logins: Harness['logins'] = [];
+
+  vi.spyOn(console, 'log').mockImplementation((...parts: unknown[]): void => {
+    out.push(parts.map(String).join(' '));
+  });
+  vi.spyOn(process.stderr, 'write').mockImplementation((chunk: unknown): boolean => {
+    err.push(String(chunk));
+    return true;
+  });
+
+  // Every login is recorded regardless of which behaviour the test supplied, so a test can
+  // assert on what the harness was actually handed as well as on what it wrote.
+  const inner = overrides.runLogin ?? ((): number => 0);
+  const program = new Command();
+  program.exitOverride();
+  const auth = program.command('auth');
+  registerFleetAuthCommands(auth, {
+    ...overrides,
+    fleetDataHome: home,
+    runLogin: (command, args, env): number | null => {
+      logins.push({ command, args, env: { ...env } });
+      return inner(command, args, env);
+    },
+  });
+
+  return {
+    home,
+    out,
+    err,
+    logins,
+    run: async (argv: string[]): Promise<void> => {
+      await program.parseAsync(['node', 'mosaic', 'auth', ...argv]);
+    },
+  };
+}
+
+/**
+ * A login that behaves: writes the credential where the harness would write it, using only the
+ * environment it was handed — the same way a real harness finds its home.
+ */
+function goodLogin(email?: string, status = 0): NonNullable<FleetAuthCommandDeps['runLogin']> {
+  return (command, _args, env): number => {
+    const dir =
+      command === 'claude'
+        ? (env['CLAUDE_SECURESTORAGE_CONFIG_DIR'] ?? '')
+        : (env['PI_CODING_AGENT_DIR'] ?? env['CODEX_HOME'] ?? env['XDG_CONFIG_HOME'] ?? '');
+    writeFileSync(join(dir, command === 'claude' ? '.credentials.json' : 'auth.json'), '{}', {
+      mode: 0o600,
+    });
+    if (email !== undefined) {
+      writeFileSync(
+        join(dir, command === 'claude' ? '.claude.json' : 'auth.json'),
+        JSON.stringify(
+          command === 'claude' ? { oauthAccount: { emailAddress: email } } : { account: { email } },
+        ),
+      );
+    }
+    return status;
+  };
+}
+
+function scaffoldSeat(
+  home: string,
+  name: string,
+  profile: Record<string, unknown> = { schema: 1, harness: 'claude', bundle: 'primary' },
+): string {
+  const dir = join(home, 'fleet', 'agents', name);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, 'profile.json');
+  writeFileSync(path, `${JSON.stringify(profile, null, 2)}\n`);
+  return path;
+}
+
+describe('mosaic auth enroll', () => {
+  it('runs the harness login against the bundle directory and reports what landed', async () => {
+    const h = await harness({ runLogin: goodLogin('[email protected]') });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'jason_woltje.com']);
+
+    expect(process.exitCode).toBeUndefined();
+    const bundleDir = join(h.home, 'auth', 'claude', 'jason_woltje.com');
+    expect(h.out.join('\n')).toContain(bundleDir);
+    expect(h.out.join('\n')).toContain('account: [email protected]');
+    const recorded = JSON.parse(await readFile(join(bundleDir, 'account.json'), 'utf8')) as Record<
+      string,
+      unknown
+    >;
+    expect(recorded['emailAddress']).toBe('[email protected]');
+  });
+
+  it('hands the harness its own home and credential directory, never an empty value', async () => {
+    const h = await harness({ runLogin: goodLogin() });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'jason_woltje.com']);
+
+    const bundleDir = join(h.home, 'auth', 'claude', 'jason_woltje.com');
+    expect(h.logins).toEqual([
+      {
+        command: 'claude',
+        args: [],
+        // An empty CLAUDE_SECURESTORAGE_CONFIG_DIR is not "unset" -- Claude resolves it to
+        // ~/.claude, the operator's own account -- so exporting one would quietly log the
+        // operator in over their own credentials instead of enrolling the seat's.
+        env: { CLAUDE_CONFIG_DIR: bundleDir, CLAUDE_SECURESTORAGE_CONFIG_DIR: bundleDir },
+      },
+    ]);
+  });
+
+  it('forwards login arguments to the harness', async () => {
+    const h = await harness({ runLogin: goodLogin() });
+    await h.run([
+      'enroll',
+      '--harness',
+      'pi',
+      '--bundle',
+      'jason_woltje.com',
+      '--login-arg',
+      '/login',
+    ]);
+
+    expect(h.logins[0]?.args).toEqual(['/login']);
+    expect(h.logins[0]?.env).toEqual({
+      PI_CODING_AGENT_DIR: join(h.home, 'auth', 'pi', 'jason_woltje.com'),
+    });
+  });
+
+  it('exits non-zero when the account that logged in is not the account the bundle claims', async () => {
+    const h = await harness({ runLogin: goodLogin('[email protected]') });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'reviewer_example.com']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('[email protected]');
+    expect(h.err.join('')).toContain('one principal wearing two names');
+  });
+
+  it('fails clearly when the harness is not installed', async () => {
+    const h = await harness({ runLogin: (): null => null });
+    await h.run(['enroll', '--harness', 'pi', '--bundle', 'someone_example.com']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('could not start "pi"');
+  });
+
+  it('reports a login that wrote nothing rather than calling the bundle enrolled', async () => {
+    const h = await harness({ runLogin: (): number => 0 });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'jason_woltje.com']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('login left no credential');
+    expect(h.err.join('')).toContain('nothing was assigned');
+  });
+
+  it('still checks the bundle when the harness exits non-zero on quit', async () => {
+    // Several harnesses exit non-zero on a normal quit after a successful login. The
+    // credential on disk is the fact that matters, not the exit status.
+    const h = await harness({ runLogin: goodLogin('[email protected]', 130) });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'jason_woltje.com']);
+
+    expect(process.exitCode).toBeUndefined();
+    expect(h.out.join('\n')).toContain('account: [email protected]');
+  });
+
+  it('creates the directory and stops when the operator will run the login themselves', async () => {
+    const h = await harness();
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'jason_woltje.com', '--no-login']);
+
+    expect(h.logins).toHaveLength(0);
+    expect(process.exitCode).toBeUndefined();
+    expect(h.out.join('\n')).toContain('CLAUDE_SECURESTORAGE_CONFIG_DIR=');
+  });
+
+  it('rejects a harness it does not know', async () => {
+    const h = await harness();
+    await h.run(['enroll', '--harness', 'emacs', '--bundle', 'x']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('--harness must be one of');
+  });
+});
+
+describe('mosaic auth assign', () => {
+  it('pegs a seat to a bundle and leaves every other profile field alone', async () => {
+    const h = await harness();
+    const path = scaffoldSeat(h.home, 'uc-e6-rev', {
+      schema: 1,
+      harness: 'claude',
+      bundle: 'primary',
+      model: 'opus',
+      overlay: 'overlay.json',
+      env: { MOSAIC_AGENT_NAME: 'uc-e6-rev' },
+    });
+
+    await h.run(['assign', 'uc-e6-rev', '--bundle', 'reviewer_example.com']);
+
+    const written = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>;
+    expect(written).toEqual({
+      schema: 1,
+      harness: 'claude',
+      bundle: 'reviewer_example.com',
+      model: 'opus',
+      overlay: 'overlay.json',
+      env: { MOSAIC_AGENT_NAME: 'uc-e6-rev' },
+    });
+    expect(h.out.join('\n')).toContain('uc-e6-rev: primary -> reviewer_example.com');
+  });
+
+  it('says the bundle is not enrolled, because the seat will refuse to launch until it is', async () => {
+    const h = await harness();
+    scaffoldSeat(h.home, 'uc-e6-rev');
+
+    await h.run(['assign', 'uc-e6-rev', '--bundle', 'reviewer_example.com']);
+
+    expect(h.out.join('\n')).toContain('is not enrolled for claude');
+  });
+
+  it('is quiet about enrolment when the bundle really is enrolled', async () => {
+    const h = await harness({ runLogin: goodLogin('[email protected]') });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'reviewer_example.com']);
+    scaffoldSeat(h.home, 'uc-e6-rev');
+    h.out.length = 0;
+
+    await h.run(['assign', 'uc-e6-rev', '--bundle', 'reviewer_example.com']);
+
+    expect(h.out.join('\n')).not.toContain('is not enrolled');
+  });
+
+  it('reports an unchanged seat instead of rewriting it', async () => {
+    const h = await harness();
+    scaffoldSeat(h.home, 'seat', { schema: 1, harness: 'pi', bundle: 'held_example.com' });
+
+    await h.run(['assign', 'seat', '--bundle', 'held_example.com']);
+
+    expect(h.out.join('\n')).toContain('seat: already held_example.com (pi)');
+  });
+
+  it('assigns every scaffolded seat with --all', async () => {
+    const h = await harness();
+    scaffoldSeat(h.home, 'a');
+    scaffoldSeat(h.home, 'b', { schema: 1, harness: 'pi', bundle: 'primary' });
+
+    await h.run(['assign', '--all', '--bundle', 'shared_example.com']);
+
+    for (const name of ['a', 'b']) {
+      const written = JSON.parse(
+        await readFile(join(h.home, 'fleet', 'agents', name, 'profile.json'), 'utf8'),
+      ) as Record<string, unknown>;
+      expect(written['bundle']).toBe('shared_example.com');
+    }
+  });
+
+  it('refuses an ambiguous target rather than guessing', async () => {
+    const h = await harness();
+    scaffoldSeat(h.home, 'a');
+
+    await h.run(['assign', 'a', '--all', '--bundle', 'x']);
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('exactly one of');
+
+    process.exitCode = undefined;
+    h.err.length = 0;
+    await h.run(['assign', '--bundle', 'x']);
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('exactly one of');
+  });
+
+  it('names the seat that does not exist', async () => {
+    const h = await harness();
+    await h.run(['assign', 'ghost', '--bundle', 'x']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('no such fleet agent');
+    expect(h.err.join('')).toContain('mosaic fleet agent new ghost');
+  });
+
+  it('refuses to rewrite a profile that is already invalid', async () => {
+    const h = await harness();
+    // Re-serializing a broken profile would produce a file that looks repaired and still
+    // fails at launch, with the original damage no longer visible.
+    scaffoldSeat(h.home, 'broken', { schema: 1, harness: 'claude', nonsense: true });
+
+    await h.run(['assign', 'broken', '--bundle', 'x']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('unknown profile key "nonsense"');
+  });
+});
+
+describe('mosaic auth list', () => {
+  it('says where bundles would live on a host that has none', async () => {
+    const h = await harness();
+    await h.run(['list']);
+
+    expect(h.out.join('\n')).toContain(join(h.home, 'auth'));
+    expect(h.out.join('\n')).toContain('mosaic auth enroll');
+  });
+
+  it('shows each bundle with its enrolment state and account', async () => {
+    const h = await harness({ runLogin: goodLogin('[email protected]') });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'jason_woltje.com']);
+    h.out.length = 0;
+
+    await h.run(['list', '--harness', 'claude']);
+
+    const text = h.out.join('\n');
+    expect(text).toContain('jason_woltje.com');
+    expect(text).toContain('enrolled');
+    expect(text).toContain('[email protected]');
+  });
+});
+
+describe('mosaic auth default', () => {
+  it('moves the primary alias to a bundle', async () => {
+    const h = await harness({ runLogin: goodLogin('[email protected]') });
+    await h.run(['enroll', '--harness', 'claude', '--bundle', 'jason_woltje.com']);
+    h.out.length = 0;
+
+    await h.run(['default', 'jason_woltje.com', '--harness', 'claude']);
+
+    expect(process.exitCode).toBeUndefined();
+    expect(h.out.join('\n')).toContain('primary -> jason_woltje.com');
+    h.out.length = 0;
+    await h.run(['list', '--harness', 'claude']);
+    expect(h.out.join('\n')).toContain('primary -> jason_woltje.com');
+  });
+
+  it('refuses a bundle that was never enrolled', async () => {
+    const h = await harness();
+    mkdirSync(join(h.home, 'auth', 'claude'), { recursive: true });
+
+    await h.run(['default', 'missing_example.com', '--harness', 'claude']);
+
+    expect(process.exitCode).toBe(1);
+    expect(h.err.join('')).toContain('no such bundle');
+  });
+});

packages/mosaic/src/commands/fleet-auth-command.ts

@@ -0,0 +1,326 @@
+/**
+ * `mosaic auth enroll | assign | list | default` -- the operator surface for credential bundles.
+ *
+ * These are local commands. They never talk to the gateway, unlike the rest of `mosaic auth`,
+ * and they work on a host where the gateway is down. What they do is give one host more than
+ * one account per harness and let each seat be pegged to one of them.
+ *
+ * Enroll does not reimplement any harness's login. It creates a private bundle directory,
+ * points the harness's own home at it by environment, and runs the harness. Whatever the
+ * harness writes is then checked: credential present, owner-only, and the account it belongs
+ * to recorded. Logging into the wrong account is the failure this catches -- it is otherwise
+ * silent, and it collapses two principals back into one.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import {
+  AuthBundleError,
+  PRIMARY_ALIAS,
+  completeEnrollment,
+  listBundles,
+  prepareEnrollment,
+  setDefaultBundle,
+} from '../fleet/auth-bundles.js';
+import type { CredentialHarness } from '../fleet/credential-sharing.js';
+import { defaultFleetDataHome } from '../fleet/fleet-agent-scaffold.js';
+import { FleetLaunchError, parseFleetAgentProfile } from './fleet-launch-command.js';
+
+const HARNESSES: readonly CredentialHarness[] = ['claude', 'codex', 'opencode', 'pi'];
+
+export interface FleetAuthCommandDeps {
+  /** Test seam for the user-owned ~/.mosaic root. */
+  readonly fleetDataHome?: string;
+  /**
+   * Test seam for running the harness login. Returns the harness's exit status; `null` means
+   * the harness could not be started at all.
+   */
+  readonly runLogin?: (
+    command: string,
+    args: readonly string[],
+    env: Readonly<Record<string, string>>,
+  ) => number | null;
+}
+
+function requireHarness(value: string | undefined): CredentialHarness {
+  if (value === undefined || !HARNESSES.includes(value as CredentialHarness)) {
+    throw new AuthBundleError(
+      'invalid-request',
+      `--harness must be one of: ${HARNESSES.join(', ')}`,
+    );
+  }
+  return value as CredentialHarness;
+}
+
+function defaultRunLogin(
+  command: string,
+  args: readonly string[],
+  env: Readonly<Record<string, string>>,
+): number | null {
+  const result = spawnSync(command, [...args], {
+    stdio: 'inherit',
+    env: { ...process.env, ...env },
+  });
+  if (result.error !== undefined) return null;
+  return result.status;
+}
+
+function fail(error: unknown, verb: string): void {
+  process.exitCode = 1;
+  const message = error instanceof Error ? error.message : String(error);
+  const code =
+    error instanceof AuthBundleError
+      ? error.code
+      : error instanceof FleetLaunchError
+        ? error.code
+        : 'failed';
+  process.stderr.write(`mosaic auth ${verb} failed (${code}): ${message}\n`);
+}
+
+// ─── assign ──────────────────────────────────────────────────────────────────
+
+interface AssignOutcome {
+  readonly agent: string;
+  readonly harness: CredentialHarness;
+  readonly from: string;
+  readonly to: string;
+  readonly changed: boolean;
+}
+
+function agentsRoot(dataHome: string): string {
+  return join(dataHome, 'fleet', 'agents');
+}
+
+function listAgents(dataHome: string): string[] {
+  try {
+    return readdirSync(agentsRoot(dataHome), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+/**
+ * Rewrite one seat's `bundle`, leaving every other field byte-identical where possible.
+ *
+ * The profile is re-parsed before writing rather than patched blind: an already-invalid
+ * profile should be reported as invalid here, not silently re-serialized into something that
+ * looks fine and still fails at launch.
+ */
+function assignOne(dataHome: string, agent: string, bundle: string): AssignOutcome {
+  const path = join(agentsRoot(dataHome), agent, 'profile.json');
+  let source: string;
+  try {
+    source = readFileSync(path, 'utf8');
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new AuthBundleError(
+        'invalid-request',
+        `no such fleet agent: ${path} — scaffold it first: mosaic fleet agent new ${agent}`,
+      );
+    }
+    throw error;
+  }
+  const profile = parseFleetAgentProfile(source);
+  const harness = profile.harness as CredentialHarness;
+  const raw = JSON.parse(source) as Record<string, unknown>;
+  const from = profile.bundle;
+  if (from === bundle) return { agent, harness, from, to: bundle, changed: false };
+  raw['bundle'] = bundle;
+  writeFileSync(path, `${JSON.stringify(raw, null, 2)}\n`);
+  return { agent, harness, from, to: bundle, changed: true };
+}
+
+// ─── registration ────────────────────────────────────────────────────────────
+
+/** Adds the local bundle verbs onto the existing `mosaic auth` command. */
+export function registerFleetAuthCommands(
+  authCommand: Command,
+  deps: FleetAuthCommandDeps = {},
+): void {
+  const dataHome = (): string => deps.fleetDataHome ?? defaultFleetDataHome();
+  const runLogin = deps.runLogin ?? defaultRunLogin;
+
+  authCommand
+    .command('enroll')
+    .description('Enrol a credential bundle by running a harness login into a private directory')
+    .requiredOption('--harness <harness>', `Harness: ${HARNESSES.join(', ')}`)
+    .requiredOption('--bundle <bundle>', 'Bundle name, normally the account email with @ as _')
+    .option('--login-arg <arg...>', 'Arguments to pass to the harness login invocation')
+    .option('--no-login', 'Only create the bundle directory; run the login yourself')
+    .action(
+      (options: {
+        harness?: string;
+        bundle: string;
+        loginArg?: string[];
+        login?: boolean;
+      }): void => {
+        try {
+          const harness = requireHarness(options.harness);
+          const plan = prepareEnrollment(dataHome(), harness, options.bundle);
+
+          console.log(`Bundle directory: ${plan.bundleDir}`);
+          if (plan.hadCredential) {
+            console.log('A credential is already present. Logging in again replaces it.');
+          }
+          for (const [key, value] of Object.entries(plan.env)) {
+            console.log(`  ${key}=${value}`);
+          }
+
+          if (options.login === false) {
+            console.log(
+              `\nRun the ${harness} login with the environment above, then verify with:\n  mosaic auth list --harness ${harness}`,
+            );
+            return;
+          }
+
+          console.log(
+            `\nStarting ${harness} against that directory. Complete the login inside it, then exit.`,
+          );
+          const status = runLogin(harness, options.loginArg ?? [], plan.env);
+          if (status === null) {
+            throw new AuthBundleError(
+              'invalid-request',
+              `could not start "${harness}" — is it installed and on PATH?`,
+            );
+          }
+          // A non-zero login is reported but still checked: some harnesses exit non-zero on
+          // a normal quit after a successful login, and the credential on disk is the fact
+          // that matters, not the exit status.
+          if (status !== 0) {
+            console.log(`\nNote: ${harness} exited ${String(status)}. Checking the bundle anyway.`);
+          }
+
+          const result = completeEnrollment(plan);
+          console.log(`\nEnrolled ${harness} bundle "${result.bundle}".`);
+          console.log(`  credential: ${result.credentialPath}`);
+          if (result.tightened) {
+            console.log('  permissions: tightened to owner-only');
+          }
+          if (result.email !== undefined) {
+            console.log(`  account: ${result.email}`);
+          } else {
+            console.log(
+              '  account: could not be determined from what the harness wrote; the bundle name is not verified against the logged-in account',
+            );
+          }
+          if (result.identityMismatch !== undefined) {
+            process.exitCode = 1;
+            process.stderr.write(
+              `\nWARNING: this bundle is named "${result.bundle}" but the account that logged in is "${result.email ?? 'unknown'}", which implies "${result.identityMismatch}".\n` +
+                'Two seats pointed at bundles that hold the same account are one principal wearing two names. Re-enrol under the right name, or delete this bundle.\n',
+            );
+            return;
+          }
+          console.log(
+            `\nAssign it to a seat with:\n  mosaic auth assign <agent> --bundle ${result.bundle}`,
+          );
+        } catch (error: unknown) {
+          fail(error, 'enroll');
+        }
+      },
+    );
+
+  authCommand
+    .command('assign [agent]')
+    .description('Peg a fleet seat to a credential bundle')
+    .requiredOption('--bundle <bundle>', 'Bundle name to assign')
+    .option('--all', 'Assign every scaffolded seat')
+    .action((agent: string | undefined, options: { bundle: string; all?: boolean }): void => {
+      try {
+        const home = dataHome();
+        if ((agent === undefined) === (options.all !== true)) {
+          throw new AuthBundleError(
+            'invalid-request',
+            'give exactly one of: an agent name, or --all',
+          );
+        }
+        const targets = options.all === true ? listAgents(home) : [agent as string];
+        if (targets.length === 0) {
+          console.log('No scaffolded fleet agents found; nothing to assign.');
+          return;
+        }
+        // Assignment does not require the bundle to be enrolled -- scaffolding a seat before
+        // its account exists is a normal order of operations -- but an unenrolled bundle is
+        // worth saying out loud, because the seat will refuse to launch until it is. The
+        // check is per harness: the same bundle name under a different harness is a
+        // different bundle.
+        const unenrolled = new Set<CredentialHarness>();
+        for (const target of targets) {
+          const outcome = assignOne(home, target, options.bundle);
+          console.log(
+            outcome.changed
+              ? `${outcome.agent}: ${outcome.from} -> ${outcome.to} (${outcome.harness})`
+              : `${outcome.agent}: already ${outcome.to} (${outcome.harness})`,
+          );
+          const enrolled = listBundles(home, outcome.harness).some(
+            (entry) => entry.name === options.bundle && entry.enrolled,
+          );
+          if (!enrolled) unenrolled.add(outcome.harness);
+        }
+        for (const harness of unenrolled) {
+          console.log(
+            `\nNotice: "${options.bundle}" is not enrolled for ${harness}, so those seats will refuse to launch until it is.\n  mosaic auth enroll --harness ${harness} --bundle ${options.bundle}`,
+          );
+        }
+      } catch (error: unknown) {
+        fail(error, 'assign');
+      }
+    });
+
+  authCommand
+    .command('list')
+    .description('List local credential bundles and which accounts they hold')
+    .option('--harness <harness>', `Limit to one harness: ${HARNESSES.join(', ')}`)
+    .action((options: { harness?: string }): void => {
+      try {
+        const home = dataHome();
+        const harnesses =
+          options.harness === undefined ? HARNESSES : [requireHarness(options.harness)];
+        let found = 0;
+        for (const harness of harnesses) {
+          const bundles = listBundles(home, harness);
+          if (bundles.length === 0) continue;
+          found += bundles.length;
+          console.log(`${harness}:`);
+          for (const bundle of bundles) {
+            const parts = [
+              bundle.alias ? `${bundle.name} -> ${bundle.target ?? '(dangling)'}` : bundle.name,
+              bundle.enrolled ? 'enrolled' : 'NOT ENROLLED',
+            ];
+            if (bundle.email !== undefined) parts.push(bundle.email);
+            console.log(`  ${parts.join('  ')}`);
+          }
+        }
+        if (found === 0) {
+          console.log(
+            `No credential bundles under ${join(home, 'auth')}.\nEnrol one with: mosaic auth enroll --harness <harness> --bundle <account>`,
+          );
+        }
+      } catch (error: unknown) {
+        fail(error, 'list');
+      }
+    });
+
+  authCommand
+    .command('default <bundle>')
+    .description(`Point the movable "${PRIMARY_ALIAS}" alias at a bundle`)
+    .requiredOption('--harness <harness>', `Harness: ${HARNESSES.join(', ')}`)
+    .action((bundle: string, options: { harness?: string }): void => {
+      try {
+        const harness = requireHarness(options.harness);
+        const alias = setDefaultBundle(dataHome(), harness, bundle);
+        console.log(`${alias} -> ${bundle}`);
+        console.log(
+          `Seats with "bundle": "${PRIMARY_ALIAS}" now use ${bundle} at their next launch. Seats pinned to a named bundle are unaffected.`,
+        );
+      } catch (error: unknown) {
+        fail(error, 'default');
+      }
+    });
+}

packages/mosaic/src/commands/fleet-launch-command.spec.ts

@@ -0,0 +1,892 @@
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  applyFleetLaunchComposition,
+  deepMergeSettings,
+  FleetLaunchError,
+  formatFleetLaunchDryRun,
+  parseFleetAgentProfile,
+  registerFleetLaunchCommand,
+  resolveFleetLaunchComposition,
+} from './fleet-launch-command.js';
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function fixture(profile: Record<string, unknown> = { schema: 1, harness: 'claude' }): {
+  root: string;
+  systemHome: string;
+  userHome: string;
+  agentDir: string;
+  namedBundleDir: string;
+  credentialName: string;
+} {
+  const harness = String(profile.harness ?? 'claude');
+  const credentialName = harness === 'claude' ? '.credentials.json' : 'auth.json';
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-fleet-launch-'));
+  roots.push(root);
+  const systemHome = join(root, 'system');
+  const userHome = join(root, 'user');
+  const agentDir = join(userHome, 'fleet', 'agents', 'fred');
+  const namedBundleDir = join(userHome, 'auth', harness, 'fred_example.com');
+  mkdirSync(join(systemHome, 'runtime', harness), { recursive: true });
+  mkdirSync(agentDir, { recursive: true });
+  mkdirSync(namedBundleDir, { recursive: true });
+  writeFileSync(join(systemHome, 'runtime', harness, 'settings.json'), '{}\n');
+  writeFileSync(join(agentDir, 'profile.json'), `${JSON.stringify(profile, null, 2)}\n`);
+  writeFileSync(join(namedBundleDir, credentialName), '{}\n', { mode: 0o600 });
+  writeFileSync(
+    join(namedBundleDir, 'account.json'),
+    '{"oauthAccount":{"emailAddress":"[email protected]"}}\n',
+  );
+  symlinkSync('fred_example.com', join(userHome, 'auth', harness, 'primary'), 'dir');
+  return { root, systemHome, userHome, agentDir, namedBundleDir, credentialName };
+}
+
+describe('fleet launch profile schema 1', () => {
+  it('rejects an unknown key and names it', () => {
+    expect(() =>
+      parseFleetAgentProfile('{"schema":1,"harness":"claude","pluigns":[]}'),
+    ).toThrowError(/unknown profile key "pluigns"/);
+  });
+
+  it('uses a dedicated SCHEMA_TOO_NEW error with an upgrade hint', () => {
+    try {
+      parseFleetAgentProfile('{"schema":2,"harness":"claude"}');
+      throw new Error('expected parse to fail');
+    } catch (error) {
+      expect(error).toBeInstanceOf(FleetLaunchError);
+      expect((error as FleetLaunchError).code).toBe('SCHEMA_TOO_NEW');
+      expect((error as Error).message).toMatch(/upgrade Mosaic/i);
+    }
+  });
+});
+
+describe('three-layer settings merge', () => {
+  it('keeps base-only settings', () => {
+    expect(deepMergeSettings({ base: { enabled: true } })).toEqual({ base: { enabled: true } });
+  });
+
+  it('uses the last layer for scalar conflicts', () => {
+    expect(deepMergeSettings({ model: 'base' }, { model: 'user' })).toEqual({ model: 'user' });
+  });
+
+  it('replaces arrays instead of appending', () => {
+    expect(deepMergeSettings({ hooks: ['base'] }, { hooks: ['user'] })).toEqual({
+      hooks: ['user'],
+    });
+  });
+
+  it('uses null as a key-deleting tombstone', () => {
+    expect(
+      deepMergeSettings({ nested: { keep: true, remove: true } }, { nested: { remove: null } }),
+    ).toEqual({ nested: { keep: true } });
+  });
+
+  it('replaces a hook event array wholesale with the higher layer', () => {
+    const qaStop = { hooks: [{ type: 'command', command: 'qa-stop.sh' }] };
+    const leaseStop = { hooks: [{ type: 'command', command: 'receipt-observer.py' }] };
+    const qaPre = { matcher: 'Write', hooks: [{ type: 'command', command: 'qa-pre.sh' }] };
+    expect(
+      deepMergeSettings(
+        { hooks: { Stop: [qaStop], PreToolUse: [qaPre] } },
+        { hooks: { Stop: [leaseStop] } },
+      ),
+    ).toEqual({ hooks: { Stop: [leaseStop], PreToolUse: [qaPre] } });
+  });
+
+  it('reconstructs every gated hook event from the base and lease overlay', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', overlay: 'lease-overlay.json' });
+    const frameworkRuntime = join(process.cwd(), 'framework', 'runtime', 'claude');
+    writeFileSync(
+      join(fx.systemHome, 'runtime', 'claude', 'settings.json'),
+      readFileSync(join(frameworkRuntime, 'settings.json'), 'utf8'),
+    );
+    writeFileSync(
+      join(fx.agentDir, 'lease-overlay.json'),
+      readFileSync(join(frameworkRuntime, 'lease-overlay.json'), 'utf8'),
+    );
+
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+
+    expect(plan.settings.merged['hooks']).toEqual({
+      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,
+            },
+          ],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: 'Edit|MultiEdit|Write',
+          hooks: [
+            {
+              type: 'command',
+              command: '~/.config/mosaic/tools/qa/qa-hook-stdin.sh',
+              timeout: 60,
+            },
+          ],
+        },
+        {
+          matcher: 'Edit|MultiEdit|Write',
+          hooks: [
+            {
+              type: 'command',
+              command: '~/.config/mosaic/tools/qa/typecheck-hook.sh',
+              timeout: 30,
+            },
+          ],
+        },
+      ],
+      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,
+            },
+          ],
+        },
+      ],
+      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,
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('still deletes a whole hook event via the null tombstone', () => {
+    expect(
+      deepMergeSettings(
+        { hooks: { Stop: [{ hooks: [{ type: 'command', command: 'qa-stop.sh' }] }] } },
+        { hooks: { Stop: null } },
+      ),
+    ).toEqual({ hooks: {} });
+  });
+
+  it('replaces an allowedCommands-shaped non-hook array wholesale', () => {
+    expect(
+      deepMergeSettings(
+        { allowedCommands: ['pnpm', 'git'], nested: { hooks: { Stop: ['base'] } } },
+        { allowedCommands: ['node'], nested: { hooks: { Stop: ['user'] } } },
+      ),
+    ).toEqual({ allowedCommands: ['node'], nested: { hooks: { Stop: ['user'] } } });
+  });
+
+  it('deep-merges all three layers in precedence order', () => {
+    expect(
+      deepMergeSettings(
+        { nested: { system: true, shared: 'system' }, list: [1] },
+        { nested: { user: true, shared: 'user' }, list: [2] },
+        { nested: { agent: true, shared: 'agent' }, list: [3] },
+      ),
+    ).toEqual({
+      nested: { system: true, user: true, agent: true, shared: 'agent' },
+      list: [3],
+    });
+  });
+});
+
+describe('profile-selected overlay', () => {
+  it('defaults to no overlay when the optional profile field is omitted', () => {
+    const fx = fixture();
+    writeFileSync(join(fx.agentDir, 'overlay.json'), '{"mustNotLoad":true}\n');
+
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    expect(plan.settings.merged).toEqual({});
+    expect(plan.settings.layers[2]?.present).toBe(false);
+  });
+});
+
+describe('system settings layer on a real install', () => {
+  it('composes a harness whose runtime ships no settings.json', () => {
+    // Measured on a greenfield Debian 13 VM against framework main: the install ships
+    // runtime/<harness>/ for claude, codex, opencode and pi but a settings.json only for
+    // claude. Requiring the file made every pi seat unlaunchable.
+    const fx = fixture({ schema: 1, harness: 'pi' });
+    rmSync(join(fx.systemHome, 'runtime', 'pi', 'settings.json'));
+    writeFileSync(join(fx.systemHome, 'runtime', 'pi', 'RUNTIME.md'), '# pi\n');
+
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    expect(plan.settings.layers[0]?.present).toBe(false);
+    expect(plan.settings.merged).toEqual({});
+  });
+
+  it('still refuses a harness the framework does not carry', () => {
+    const fx = fixture({ schema: 1, harness: 'pi' });
+    rmSync(join(fx.systemHome, 'runtime', 'pi'), { recursive: true });
+
+    try {
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      });
+      throw new Error('expected resolution to fail');
+    } catch (error: unknown) {
+      const launchError = error as FleetLaunchError;
+      expect(launchError.code).toBe('COMPOSITION_FAILED');
+      expect(launchError.message).toMatch(/harness runtime is not installed/);
+    }
+  });
+});
+
+describe('never-enrolled hosts', () => {
+  it('names the enroll command instead of reporting a shape violation', () => {
+    // A host that has simply never logged in has no ~/.mosaic/auth at all. Reusing the
+    // wrong-shape wording there told the operator their auth directory "must be a real,
+    // non-symlink directory", which reads as tampering rather than "enroll a bundle".
+    const fx = fixture();
+    rmSync(join(fx.userHome, 'auth'), { recursive: true });
+
+    try {
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      });
+      throw new Error('expected resolution to fail');
+    } catch (error: unknown) {
+      const launchError = error as FleetLaunchError;
+      expect(launchError.code).toBe('COMPOSITION_FAILED');
+      expect(launchError.message).toMatch(/does not exist/);
+      expect(launchError.message).toMatch(/mosaic auth enroll/);
+      expect(launchError.message).not.toMatch(/non-symlink/);
+    }
+  });
+});
+
+describe('unscaffolded agent names', () => {
+  it('points an unscaffolded name at mosaic fleet agent new', () => {
+    const fx = fixture();
+    try {
+      resolveFleetLaunchComposition('ghost', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      });
+      throw new Error('expected resolution to fail');
+    } catch (error: unknown) {
+      const launchError = error as FleetLaunchError;
+      expect(launchError.code).toBe('AGENT_NOT_SCAFFOLDED');
+      expect(launchError.message).toContain("no such fleet agent 'ghost'");
+      expect(launchError.message).toContain('mosaic fleet agent new ghost');
+    }
+  });
+});
+
+describe('A3 credential validation', () => {
+  it('refuses a symlinked bundle credential file', () => {
+    const fx = fixture();
+    rmSync(join(fx.namedBundleDir, '.credentials.json'));
+    const outside = join(fx.root, 'outside-credentials.json');
+    writeFileSync(outside, '{}\n');
+    symlinkSync(outside, join(fx.namedBundleDir, '.credentials.json'));
+
+    expect(() =>
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      }),
+    ).toThrowError(/real, non-symlink credential file/);
+  });
+
+  it('refuses an auth ancestor symlink that relocates the credential trust root', () => {
+    const fx = fixture();
+    rmSync(join(fx.userHome, 'auth'), { recursive: true, force: true });
+    const outsideAuth = join(fx.root, 'outside-auth');
+    const outsideBundle = join(outsideAuth, 'claude', 'fred_example.com');
+    mkdirSync(outsideBundle, { recursive: true });
+    writeFileSync(join(outsideBundle, '.credentials.json'), '{}\n', { mode: 0o600 });
+    writeFileSync(
+      join(outsideBundle, 'account.json'),
+      '{"oauthAccount":{"emailAddress":"[email protected]"}}\n',
+    );
+    symlinkSync('fred_example.com', join(outsideAuth, 'claude', 'primary'), 'dir');
+    symlinkSync(outsideAuth, join(fx.userHome, 'auth'), 'dir');
+
+    expect(() =>
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      }),
+    ).toThrowError(/auth directory must be a real, non-symlink directory/);
+  });
+
+  it('refuses a group- or world-readable credential file', () => {
+    const fx = fixture();
+    chmodSync(join(fx.namedBundleDir, '.credentials.json'), 0o644);
+
+    expect(() =>
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      }),
+    ).toThrowError(/credential file must not grant group or other permissions/);
+  });
+
+  it('accepts a real private credential file contained in the harness auth root', () => {
+    const fx = fixture();
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+
+    expect(plan.credential.target).toBe(join(fx.namedBundleDir, '.credentials.json'));
+    expect(plan.bundle.display).toBe('primary -> fred_example.com ([email protected])');
+  });
+
+  it('refuses first-auth state when a real file occupies the seat link', () => {
+    const fx = fixture();
+    const seatHome = join(fx.agentDir, '.claude');
+    mkdirSync(seatHome, { recursive: true });
+    writeFileSync(join(seatHome, '.credentials.json'), '{"private":true}\n');
+
+    expect(() =>
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      }),
+    ).toThrowError(/first-auth.*refusing to delete or overwrite/i);
+    expect(lstatSync(join(seatHome, '.credentials.json')).isSymbolicLink()).toBe(false);
+  });
+
+  it('points Claude at the resolved bundle directory and plans no credential link', () => {
+    const fx = fixture();
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+
+    expect(plan.credential.link).toBeUndefined();
+    expect(plan.credential.dir).toBe(fx.namedBundleDir);
+    // An empty value resolves to ~/.claude, which is the operator's own account,
+    // so the exported value must always be the absolute bundle path.
+    expect(plan.env['CLAUDE_SECURESTORAGE_CONFIG_DIR']).toBe(fx.namedBundleDir);
+    expect(plan.env['CLAUDE_SECURESTORAGE_CONFIG_DIR']).not.toBe('');
+  });
+
+  it('keeps the managed credential link for a harness with no credential-directory variable', () => {
+    const fx = fixture({ schema: 1, harness: 'pi' });
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+
+    expect(plan.credential.link).toBe(join(fx.agentDir, '.pi', 'auth.json'));
+    expect(plan.credential.target).toBe(join(fx.namedBundleDir, 'auth.json'));
+    expect(Object.keys(plan.env)).not.toContain('CLAUDE_SECURESTORAGE_CONFIG_DIR');
+  });
+});
+
+describe('managed plugin and skill links', () => {
+  it('refuses an unrecorded foreign symlink without mutating it', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: [] });
+    const pluginHome = join(fx.agentDir, '.claude', 'plugins');
+    const foreign = join(fx.root, 'foreign-plugin');
+    mkdirSync(pluginHome, { recursive: true });
+    mkdirSync(foreign, { recursive: true });
+    symlinkSync(foreign, join(pluginHome, 'foreign'), 'dir');
+
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    expect(() => applyFleetLaunchComposition(plan)).toThrowError(
+      /unrecorded or retargeted symlink/,
+    );
+    expect(readlinkSync(join(pluginHome, 'foreign'))).toBe(foreign);
+  });
+
+  it('performs no writes when a late foreign install link is refused', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: ['keep'] });
+    const target = join(fx.userHome, 'plugins', 'keep');
+    const link = join(fx.agentDir, '.claude', 'plugins', 'keep');
+    mkdirSync(target, { recursive: true });
+    mkdirSync(join(link, '..'), { recursive: true });
+    writeFileSync(join(fx.agentDir, '.claude', '.mosaic-managed-links.json'), '{"links":{}}\n');
+    symlinkSync(target, link, 'dir');
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    const snapshot = join(fx.agentDir, 'settings.generated.json');
+    const temp = join(fx.agentDir, '.claude', '.mosaic-managed-links.json.tmp');
+
+    expect(() => applyFleetLaunchComposition(plan)).toThrowError(
+      /unrecorded or retargeted symlink/,
+    );
+    expect(existsSync(snapshot)).toBe(false);
+    expect(existsSync(temp)).toBe(false);
+    expect(readlinkSync(link)).toBe(target);
+  });
+
+  it('prunes a recorded matching stale symlink', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: ['old'] });
+    mkdirSync(join(fx.userHome, 'plugins', 'old'), { recursive: true });
+    const initial = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    applyFleetLaunchComposition(initial);
+
+    writeFileSync(
+      join(fx.agentDir, 'profile.json'),
+      '{"schema":1,"harness":"claude","plugins":[]}\n',
+    );
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    const pluginHome = join(fx.agentDir, '.claude', 'plugins');
+    expect(plan.prune).toEqual([join(pluginHome, 'old')]);
+    applyFleetLaunchComposition(plan);
+
+    expect(() => lstatSync(join(pluginHome, 'old'))).toThrow();
+  });
+
+  it('refuses a recorded link retargeted after composition and leaves it intact', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: ['old'] });
+    const managedTarget = join(fx.userHome, 'plugins', 'old');
+    const foreignTarget = join(fx.root, 'foreign-plugin');
+    mkdirSync(managedTarget, { recursive: true });
+    mkdirSync(foreignTarget, { recursive: true });
+    const initial = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    applyFleetLaunchComposition(initial);
+
+    writeFileSync(
+      join(fx.agentDir, 'profile.json'),
+      '{"schema":1,"harness":"claude","plugins":[]}\n',
+    );
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    const link = join(fx.agentDir, '.claude', 'plugins', 'old');
+    rmSync(link);
+    symlinkSync(foreignTarget, link, 'dir');
+
+    expect(() => applyFleetLaunchComposition(plan)).toThrowError(
+      /unrecorded or retargeted symlink/,
+    );
+    expect(readlinkSync(link)).toBe(foreignTarget);
+  });
+
+  it('refuses a tampered manifest entry outside this seat and leaves it intact', () => {
+    const fx = fixture({ schema: 1, harness: 'claude' });
+    const seatHome = join(fx.agentDir, '.claude');
+    mkdirSync(seatHome, { recursive: true });
+    const manifest = join(seatHome, '.mosaic-managed-links.json');
+    const crossSeat = join(fx.userHome, 'fleet', 'agents', 'other', '.claude', 'plugins', 'keep');
+    writeFileSync(
+      manifest,
+      JSON.stringify({ links: { [crossSeat]: join(fx.userHome, 'plugins', 'keep') } }),
+    );
+
+    expect(() =>
+      resolveFleetLaunchComposition('fred', { systemHome: fx.systemHome, userHome: fx.userHome }),
+    ).toThrowError(/escapes an approved seat\/store root/);
+    expect(readFileSync(manifest, 'utf8')).toContain(crossSeat);
+  });
+
+  it('refuses a symlinked manifest temporary path without modifying its target', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: ['keep'] });
+    const target = join(fx.userHome, 'plugins', 'keep');
+    const sentinel = join(fx.root, 'sentinel.json');
+    mkdirSync(target, { recursive: true });
+    mkdirSync(join(fx.agentDir, '.claude'), { recursive: true });
+    writeFileSync(sentinel, 'unchanged\n', { mode: 0o600 });
+    symlinkSync(sentinel, join(fx.agentDir, '.claude', '.mosaic-managed-links.json.tmp'), 'file');
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+
+    expect(() => applyFleetLaunchComposition(plan)).toThrowError(/cannot be created exclusively/);
+    expect(readFileSync(sentinel, 'utf8')).toBe('unchanged\n');
+  });
+
+  // Credential links exist only for harnesses that are not pointed at their bundle
+  // by environment, so the containment rules are exercised on one of those.
+  it('refuses an exact-target unrecorded credential symlink', () => {
+    const fx = fixture({ schema: 1, harness: 'pi' });
+    const seatHome = join(fx.agentDir, '.pi');
+    const link = join(seatHome, fx.credentialName);
+    mkdirSync(seatHome, { recursive: true });
+    symlinkSync(join(fx.namedBundleDir, fx.credentialName), link, 'file');
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+
+    expect(() => applyFleetLaunchComposition(plan)).toThrowError(
+      /unrecorded or retargeted symlink/,
+    );
+    expect(readlinkSync(link)).toBe(join(fx.namedBundleDir, fx.credentialName));
+  });
+
+  it.each(['plugins', 'skills'] as const)(
+    'refuses an exact-target unrecorded %s symlink',
+    (kind) => {
+      const fx = fixture({ schema: 1, harness: 'claude', [kind]: ['keep'] });
+      const target = join(fx.userHome, kind, 'keep');
+      const link = join(fx.agentDir, '.claude', kind, 'keep');
+      mkdirSync(target, { recursive: true });
+      mkdirSync(join(link, '..'), { recursive: true });
+      writeFileSync(join(fx.agentDir, '.claude', '.mosaic-managed-links.json'), '{"links":{}}\n');
+      symlinkSync(target, link, 'dir');
+      const plan = resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      });
+
+      expect(() => applyFleetLaunchComposition(plan)).toThrowError(
+        /unrecorded or retargeted symlink/,
+      );
+      expect(readlinkSync(link)).toBe(target);
+    },
+  );
+
+  it('refuses an unrecorded mismatched credential symlink', () => {
+    const fx = fixture({ schema: 1, harness: 'pi' });
+    const seatHome = join(fx.agentDir, '.pi');
+    const foreignCredential = join(fx.root, 'foreign-credential.json');
+    mkdirSync(seatHome, { recursive: true });
+    writeFileSync(foreignCredential, '{}\n', { mode: 0o600 });
+    symlinkSync(foreignCredential, join(seatHome, fx.credentialName), 'file');
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+
+    expect(() => applyFleetLaunchComposition(plan)).toThrowError(
+      /unrecorded or retargeted symlink/,
+    );
+    expect(readFileSync(join(seatHome, fx.credentialName), 'utf8')).toBe('{}\n');
+  });
+
+  it('tolerates harness metadata files in the install root and still refuses real directories', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: [] });
+    const pluginHome = join(fx.agentDir, '.claude', 'plugins');
+    mkdirSync(pluginHome, { recursive: true });
+    writeFileSync(join(pluginHome, 'installed_plugins.json'), '{}\n');
+
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    expect(plan.prune).toEqual([]);
+    expect(readFileSync(join(pluginHome, 'installed_plugins.json'), 'utf8')).toBe('{}\n');
+
+    mkdirSync(join(pluginHome, 'stray-plugin'), { recursive: true });
+    expect(() =>
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      }),
+    ).toThrowError(/real plugin directory occupies managed install root.*refusing to prune/i);
+  });
+
+  it('surfaces a real directory at a managed link path without deleting it', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: ['keep'] });
+    mkdirSync(join(fx.userHome, 'plugins', 'keep'), { recursive: true });
+    const occupied = join(fx.agentDir, '.claude', 'plugins', 'keep');
+    mkdirSync(occupied, { recursive: true });
+
+    expect(() =>
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      }),
+    ).toThrowError(/real plugin directory.*refusing to delete/i);
+    expect(lstatSync(occupied).isDirectory()).toBe(true);
+  });
+});
+
+describe('fleet launch command outcomes', () => {
+  it('--dry-run prints without writing or invoking the launcher', () => {
+    const fx = fixture();
+    const program = new Command().exitOverride();
+    const fleet = program.command('fleet');
+    const launcher = vi.fn();
+    const stdout = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    registerFleetLaunchCommand(fleet, () => fx.systemHome, {
+      userHome: fx.userHome,
+      launcher,
+    });
+
+    try {
+      program.parse(['node', 'mosaic', 'fleet', 'launch', 'fred', '--dry-run']);
+      expect(stdout).toHaveBeenCalledWith(
+        expect.stringContaining('mosaic fleet launch fred --dry-run'),
+      );
+      expect(launcher).not.toHaveBeenCalled();
+      expect(() => lstatSync(join(fx.agentDir, '.claude'))).toThrow();
+    } finally {
+      stdout.mockRestore();
+    }
+  });
+
+  it('applies the plan and invokes the existing launch seam with declared values', () => {
+    const fx = fixture({
+      schema: 1,
+      harness: 'claude',
+      model: 'opus',
+      env: { SEAT_FLAG: 'yes' },
+    });
+    const program = new Command().exitOverride();
+    const fleet = program.command('fleet');
+    const launcher = vi.fn();
+    registerFleetLaunchCommand(fleet, () => fx.systemHome, {
+      userHome: fx.userHome,
+      launcher,
+    });
+
+    program.parse(['node', 'mosaic', 'fleet', 'launch', 'fred']);
+
+    expect(launcher).toHaveBeenCalledWith(
+      'claude',
+      ['--model', 'opus'],
+      {
+        CLAUDE_CONFIG_DIR: join(fx.agentDir, '.claude'),
+        CLAUDE_SECURESTORAGE_CONFIG_DIR: fx.namedBundleDir,
+        MOSAIC_AGENT_NAME: 'fred',
+        SEAT_FLAG: 'yes',
+      },
+      { agentDir: fx.agentDir, mosaicHome: fx.systemHome },
+      false,
+    );
+    // The bundle is reached by environment, so nothing is planted at the seat path.
+    expect(existsSync(join(fx.agentDir, '.claude', '.credentials.json'))).toBe(false);
+  });
+
+  it('asks for dangerous permissions only when the caller does', () => {
+    const fx = fixture({ schema: 1, harness: 'claude' });
+    const program = new Command().exitOverride();
+    const fleet = program.command('fleet');
+    const launcher = vi.fn();
+    registerFleetLaunchCommand(fleet, () => fx.systemHome, { userHome: fx.userHome, launcher });
+
+    program.parse(['node', 'mosaic', 'fleet', 'launch', 'fred', '--dangerous']);
+
+    expect(launcher).toHaveBeenCalledWith('claude', [], expect.anything(), expect.anything(), true);
+  });
+
+  it('lets a caller-supplied --model replace the profile model instead of duplicating it', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', model: 'opus' });
+    const program = new Command().exitOverride();
+    const fleet = program.command('fleet');
+    const launcher = vi.fn();
+    registerFleetLaunchCommand(fleet, () => fx.systemHome, { userHome: fx.userHome, launcher });
+
+    program.parse(['node', 'mosaic', 'fleet', 'launch', 'fred', '--model', 'sonnet']);
+
+    expect(launcher).toHaveBeenCalledWith(
+      'claude',
+      ['--model', 'sonnet'],
+      expect.anything(),
+      expect.anything(),
+      false,
+    );
+  });
+
+  it('sets a non-zero exit code and never invokes the launcher', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', unknown: true });
+    const program = new Command().exitOverride();
+    const fleet = program.command('fleet');
+    const launcher = vi.fn();
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const priorExitCode = process.exitCode;
+    process.exitCode = 0;
+    registerFleetLaunchCommand(fleet, () => fx.systemHome, {
+      userHome: fx.userHome,
+      launcher,
+    });
+
+    try {
+      program.parse(['node', 'mosaic', 'fleet', 'launch', 'fred']);
+      expect(process.exitCode).toBe(1);
+      expect(launcher).not.toHaveBeenCalled();
+      expect(stderr).toHaveBeenCalledWith(expect.stringContaining('unknown profile key "unknown"'));
+    } finally {
+      process.exitCode = priorExitCode;
+      stderr.mockRestore();
+    }
+  });
+});
+
+describe('dry-run composition', () => {
+  it('renders a deterministic full composition and writes nothing', () => {
+    const fx = fixture({
+      schema: 1,
+      harness: 'claude',
+      bundle: 'primary',
+      model: 'opus',
+      overlay: 'overlay.json',
+      plugins: ['code-review'],
+      skills: ['mosaic-tools'],
+      env: { SEAT_FLAG: 'yes' },
+    });
+    writeFileSync(
+      join(fx.systemHome, 'runtime', 'claude', 'settings.json'),
+      '{"theme":"dark","hooks":["system"],"nested":{"system":true}}\n',
+    );
+    mkdirSync(join(fx.userHome, 'config', 'claude'), { recursive: true });
+    writeFileSync(
+      join(fx.userHome, 'config', 'claude', 'settings.json'),
+      '{"hooks":["user"],"nested":{"user":true}}\n',
+    );
+    writeFileSync(join(fx.agentDir, 'overlay.json'), '{"theme":null,"nested":{"agent":true}}\n');
+    mkdirSync(join(fx.userHome, 'plugins', 'code-review'), { recursive: true });
+    mkdirSync(join(fx.userHome, 'skills', 'mosaic-tools'), { recursive: true });
+
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    const output = formatFleetLaunchDryRun(plan).replaceAll(fx.root, '<ROOT>');
+
+    expect(output).toMatchInlineSnapshot(`
+      "mosaic fleet launch fred --dry-run
+      profile: <ROOT>/user/fleet/agents/fred/profile.json (schema 1)
+      harness: claude
+      seat-home: <ROOT>/user/fleet/agents/fred/.claude
+      settings sources:
+        system: <ROOT>/system/runtime/claude/settings.json
+        user: <ROOT>/user/config/claude/settings.json
+        agent: <ROOT>/user/fleet/agents/fred/overlay.json
+        output: <ROOT>/user/fleet/agents/fred/.claude/settings.json
+        snapshot: <ROOT>/user/fleet/agents/fred/settings.generated.json
+      merged settings:
+      {
+        "hooks": [
+          "user"
+        ],
+        "nested": {
+          "agent": true,
+          "system": true,
+          "user": true
+        }
+      }
+      bundle: primary -> fred_example.com (fred@example.com)
+      credential: <ROOT>/user/auth/claude/fred_example.com/.credentials.json
+      symlinks:
+        plugin code-review: <ROOT>/user/fleet/agents/fred/.claude/plugins/code-review -> <ROOT>/user/plugins/code-review
+        skill mosaic-tools: <ROOT>/user/fleet/agents/fred/.claude/skills/mosaic-tools -> <ROOT>/user/skills/mosaic-tools
+      declared env:
+        CLAUDE_CONFIG_DIR=<ROOT>/user/fleet/agents/fred/.claude
+        CLAUDE_SECURESTORAGE_CONFIG_DIR=<ROOT>/user/auth/claude/fred_example.com
+        MOSAIC_AGENT_NAME=fred
+        SEAT_FLAG=yes
+      argv: ["claude","--model","opus"]"
+    `);
+    expect(() => readFileSync(join(fx.agentDir, '.claude', 'settings.json'), 'utf8')).toThrow();
+
+    applyFleetLaunchComposition(plan);
+    expect(JSON.parse(readFileSync(plan.settings.output, 'utf8'))).toEqual({
+      hooks: ['user'],
+      nested: { agent: true, system: true, user: true },
+    });
+    expect(readFileSync(plan.settings.snapshot, 'utf8')).toBe(
+      readFileSync(plan.settings.output, 'utf8'),
+    );
+    expect(plan.credential.link).toBeUndefined();
+    expect(plan.credential.dir).toBe(fx.namedBundleDir);
+  });
+});

packages/mosaic/src/commands/fleet.spec.ts

@@ -82,6 +82,8 @@ describe('registerFleetCommand', () => {
     expect(fleet).toBeDefined();
     expect(fleet!.commands.map((command) => command.name()).sort()).toEqual([
       'add',
+      'adopt',
+      'agent',
       'apply',
       'backlog',
       'create',
@@ -91,6 +93,7 @@ describe('registerFleetCommand', () => {
       'init',
       'install',
       'install-systemd',
+      'launch',
       'migrate-v1',
       'persona',
       'plan',

packages/mosaic/src/commands/fleet.ts

@@ -38,6 +38,11 @@ import {
   registerFleetAgentCrudCommands,
   type FleetAgentCrudCommandDeps,
 } from './fleet-agent-crud-command.js';
+import {
+  registerFleetAgentScaffoldCommand,
+  type FleetAgentScaffoldCommandDeps,
+} from './fleet-agent-scaffold-command.js';
+import { registerFleetAdoptCommand } from './fleet-adopt-command.js';
 import {
   registerFleetMigrationCommand,
   type FleetMigrationCommandDeps,
@@ -63,6 +68,7 @@ import { registerFleetBacklogCommand } from './fleet-backlog.js';
 import { registerFleetPersonaCommand } from './fleet-personas.js';
 import { registerFleetProfileCommand } from './fleet-profiles.js';
 import { registerFleetProvisionCommand } from './fleet-provision.js';
+import { registerFleetLaunchCommand, type FleetLaunchCommandDeps } from './fleet-launch-command.js';
 
 /**
  * A function that spawns a command with inherited stdio (TTY passthrough).
@@ -97,6 +103,10 @@ export interface FleetCommandDeps {
    */
   sleepFn?: SleepFn;
   mosaicHome?: string;
+  /** User-owned fleet/auth/config root. Defaults to ~/.mosaic. */
+  mosaicUserHome?: string;
+  /** Test/embedding seam for the final process-replacing fleet launch. */
+  fleetLauncher?: FleetLaunchCommandDeps['launcher'];
   frameworkRoot?: string;
   /**
    * Injectable TTY check for `fleet init` wizard. Defaults to process.stdin.isTTY.
@@ -104,6 +114,8 @@ export interface FleetCommandDeps {
    */
   isStdinTTY?: boolean;
   projectionApplier?: FleetAgentCrudCommandDeps['projectionApplier'];
+  /** Test-only user-data root for `fleet agent new` (production: ~/.mosaic). */
+  fleetDataHome?: FleetAgentScaffoldCommandDeps['fleetDataHome'];
   reconcileDeps?: FleetReconcilerCommandDeps['reconcileDeps'];
   migrationDeps?: Omit<FleetMigrationCommandDeps, 'mosaicHome'>;
 }
@@ -2041,6 +2053,14 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
   // fleet/ directory as the roster and heartbeats.
   registerFleetBacklogCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
 
+  // User-facing per-agent profile.json is the launch-composition SSOT. It is
+  // intentionally independent of roster-v2, whose lifecycle/topology registry
+  // does not model auth bundles, overlays, plugins, skills, or seat env.
+  registerFleetLaunchCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome, {
+    ...(deps.mosaicUserHome === undefined ? {} : { userHome: deps.mosaicUserHome }),
+    ...(deps.fleetLauncher === undefined ? {} : { launcher: deps.fleetLauncher }),
+  });
+
   // System-type profiles (H2): declarative persona roster + topology, resolved
   // from <mosaicHome>/fleet/profiles/*.yaml using the same --mosaic-home flag.
   registerFleetProfileCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
@@ -2054,6 +2074,18 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
   // profile. DRY-RUN by default; --write persists under the same --mosaic-home.
   registerFleetProvisionCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
 
+  // `fleet agent new` owns user-data harness homes under ~/.mosaic. The
+  // existing roster-v2 CRUD remains direct fleet control-plane CRUD, so there
+  // is one `agent` namespace but deliberately separate state authorities.
+  registerFleetAgentScaffoldCommand(cmd, {
+    ...(deps.fleetDataHome === undefined ? {} : { fleetDataHome: deps.fleetDataHome }),
+    mosaicHomeFor: () => cmd.opts<{ mosaicHome: string }>().mosaicHome,
+  });
+  // The counterpart to launch's refusals: launch will not delete a real directory sitting on
+  // a managed path, and this is how one gets moved out of the way instead.
+  registerFleetAdoptCommand(cmd, {
+    ...(deps.fleetDataHome === undefined ? {} : { fleetDataHome: deps.fleetDataHome }),
+  });
   // Roster-v2 desired-state mutations belong directly to the fleet control
   // plane; they do not share the root `mosaic agent` gateway-backed surface.
   registerFleetAgentCrudCommands(cmd, deps);

packages/mosaic/src/commands/launch.spec.ts

@@ -1,6 +1,17 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
 import { Command } from 'commander';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  symlinkSync,
+  rmSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -8,6 +19,8 @@ import {
   enumerateSkillDirs,
   piForceSkillNames,
   registerRuntimeLaunchers,
+  checkSequentialThinking,
+  launchFleetRuntimeForTest,
   type RuntimeLaunchHandler,
   type ClaudexLaunchHandler,
 } from './launch.js';
@@ -86,6 +99,285 @@ describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
   });
 });
 
+describe('checkSequentialThinking', () => {
+  it('runs the real fleet launch preflight against the injected seat, not HOME', () => {
+    const home = mkdtempSync(join(tmpdir(), 'mosaic-seq-home-'));
+    const agentDir = mkdtempSync(join(tmpdir(), 'mosaic-seq-seat-'));
+    const installed = mkdtempSync(join(tmpdir(), 'mosaic-seq-installed-'));
+    const checker = join(installed, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+    try {
+      expect(
+        JSON.parse(
+          readFileSync(
+            join(process.cwd(), 'framework', 'runtime', 'claude', 'settings.json'),
+            'utf8',
+          ),
+        ).mcpServers['sequential-thinking'],
+      ).toEqual({
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+      });
+      mkdirSync(join(installed, 'tools', '_scripts'), { recursive: true });
+      copyFileSync(
+        join(process.cwd(), 'framework', 'tools', '_scripts', 'mosaic-ensure-sequential-thinking'),
+        checker,
+      );
+      writeFileSync(join(agentDir, 'SOUL.md'), '# SOUL\n');
+      mkdirSync(join(agentDir, '.claude'), { recursive: true });
+      writeFileSync(
+        join(agentDir, '.claude', '.claude.json'),
+        JSON.stringify({
+          mcpServers: {
+            'sequential-thinking': {
+              command: 'npx',
+              args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+            },
+          },
+        }),
+        { mode: 0o600 },
+      );
+      vi.stubEnv('HOME', home);
+      const final = vi.fn((): never => {
+        throw new Error('final runtime boundary');
+      });
+      expect(() =>
+        launchFleetRuntimeForTest('claude', [], {}, { agentDir, mosaicHome: installed }, final),
+      ).toThrow('final runtime boundary');
+      expect(final).toHaveBeenCalledOnce();
+    } finally {
+      vi.unstubAllEnvs();
+      rmSync(home, { recursive: true, force: true });
+      rmSync(agentDir, { recursive: true, force: true });
+      rmSync(installed, { recursive: true, force: true });
+    }
+  });
+
+  it('fails the real fleet launch preflight when only operator HOME is seeded', () => {
+    const home = mkdtempSync(join(tmpdir(), 'mosaic-seq-home-'));
+    const agentDir = mkdtempSync(join(tmpdir(), 'mosaic-seq-seat-'));
+    const installed = mkdtempSync(join(tmpdir(), 'mosaic-seq-installed-'));
+    const checker = join(installed, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+    const exit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
+    try {
+      mkdirSync(join(installed, 'tools', '_scripts'), { recursive: true });
+      copyFileSync(
+        join(process.cwd(), 'framework', 'tools', '_scripts', 'mosaic-ensure-sequential-thinking'),
+        checker,
+      );
+      writeFileSync(
+        join(home, '.claude.json'),
+        JSON.stringify({
+          mcpServers: {
+            'sequential-thinking': {
+              command: 'npx',
+              args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+            },
+          },
+        }),
+      );
+      // Scaffolded seat, unconfigured harness: the seat's own identity is present so this
+      // still fails on the missing MCP configuration rather than on a missing SOUL.md.
+      writeFileSync(join(agentDir, 'SOUL.md'), '# SOUL\n');
+      vi.stubEnv('HOME', home);
+      expect(() =>
+        launchFleetRuntimeForTest('claude', [], {}, { agentDir, mosaicHome: installed }, () => {
+          throw new Error('must not execute');
+        }),
+      ).toThrow('process.exit called');
+    } finally {
+      exit.mockRestore();
+      vi.unstubAllEnvs();
+      rmSync(home, { recursive: true, force: true });
+      rmSync(agentDir, { recursive: true, force: true });
+      rmSync(installed, { recursive: true, force: true });
+    }
+  });
+
+  it('passes with a seeded seat even when operator HOME has no MCP configuration', () => {
+    const home = mkdtempSync(join(tmpdir(), 'mosaic-seq-home-'));
+    const agentDir = mkdtempSync(join(tmpdir(), 'mosaic-seq-seat-'));
+    const installed = mkdtempSync(join(tmpdir(), 'mosaic-seq-installed-'));
+    const checker = join(installed, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+    try {
+      mkdirSync(join(installed, 'tools', '_scripts'), { recursive: true });
+      copyFileSync(
+        join(process.cwd(), 'framework', 'tools', '_scripts', 'mosaic-ensure-sequential-thinking'),
+        checker,
+      );
+      writeFileSync(join(agentDir, 'SOUL.md'), '# SOUL\n');
+      mkdirSync(join(agentDir, '.claude'), { recursive: true });
+      writeFileSync(
+        join(agentDir, '.claude', '.claude.json'),
+        JSON.stringify({
+          mcpServers: {
+            'sequential-thinking': {
+              command: 'npx',
+              args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+            },
+          },
+        }),
+        { mode: 0o600 },
+      );
+      vi.stubEnv('MOSAIC_HOME', installed);
+      vi.stubEnv('HOME', home);
+      expect(() =>
+        checkSequentialThinking('claude', { agentDir, mosaicHome: installed }),
+      ).not.toThrow();
+    } finally {
+      vi.unstubAllEnvs();
+      rmSync(home, { recursive: true, force: true });
+      rmSync(agentDir, { recursive: true, force: true });
+      rmSync(installed, { recursive: true, force: true });
+    }
+  });
+
+  it('repairs a legacy seat config in place without using operator HOME', () => {
+    const home = mkdtempSync(join(tmpdir(), 'mosaic-seq-home-'));
+    const agentDir = mkdtempSync(join(tmpdir(), 'mosaic-seq-seat-'));
+    const installed = mkdtempSync(join(tmpdir(), 'mosaic-seq-installed-'));
+    const checker = join(installed, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+    const bin = join(installed, 'bin');
+    try {
+      mkdirSync(join(installed, 'tools', '_scripts'), { recursive: true });
+      writeFileSync(join(agentDir, 'SOUL.md'), '# SOUL\n');
+      mkdirSync(join(agentDir, '.claude'), { recursive: true });
+      mkdirSync(bin, { recursive: true });
+      copyFileSync(
+        join(process.cwd(), 'framework', 'tools', '_scripts', 'mosaic-ensure-sequential-thinking'),
+        checker,
+      );
+      for (const name of ['node', 'npx']) {
+        writeFileSync(join(bin, name), '#!/usr/bin/env bash\nexit 0\n');
+        chmodSync(join(bin, name), 0o755);
+      }
+      writeFileSync(
+        join(agentDir, '.claude', '.claude.json'),
+        JSON.stringify({ hasCompletedOnboarding: true, theme: 'dark' }),
+        { mode: 0o600 },
+      );
+      const env = { ...process.env, HOME: home, PATH: `${bin}:${process.env.PATH}` };
+      expect(
+        spawnSync(
+          checker,
+          ['--runtime', 'claude', '--claude-config-dir', join(agentDir, '.claude')],
+          {
+            env,
+          },
+        ).status,
+      ).toBe(0);
+      expect(
+        spawnSync(
+          checker,
+          ['--check', '--runtime', 'claude', '--claude-config-dir', join(agentDir, '.claude')],
+          { env },
+        ).status,
+      ).toBe(0);
+      expect(
+        JSON.parse(readFileSync(join(agentDir, '.claude', '.claude.json'), 'utf8')),
+      ).toMatchObject({
+        hasCompletedOnboarding: true,
+        theme: 'dark',
+        mcpServers: { 'sequential-thinking': { command: 'npx' } },
+      });
+      expect(existsSync(join(home, '.claude.json'))).toBe(false);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+      rmSync(agentDir, { recursive: true, force: true });
+      rmSync(installed, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses an unscaffolded seat instead of opening the interactive setup wizard', () => {
+    // Measured on a greenfield VM: a roster-started seat whose host had no system SOUL.md
+    // reached checkSoul(), which spawns `mosaic wizard` with inherited stdio. With nobody at
+    // the pane the seat parked on the wizard's menu -- tmux session live, unit reporting
+    // fine, no agent ever launched. A fleet seat's identity is its own SOUL.md, and an
+    // unattended launch must fail loudly rather than wait for a keystroke.
+    const home = mkdtempSync(join(tmpdir(), 'mosaic-soul-home-'));
+    const agentDir = mkdtempSync(join(tmpdir(), 'mosaic-soul-seat-'));
+    const installed = mkdtempSync(join(tmpdir(), 'mosaic-soul-installed-'));
+    const exit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    try {
+      vi.stubEnv('HOME', home);
+      expect(() =>
+        launchFleetRuntimeForTest('claude', [], {}, { agentDir, mosaicHome: installed }, () => {
+          throw new Error('must not execute');
+        }),
+      ).toThrow('process.exit called');
+      expect(exit).toHaveBeenCalledWith(1);
+      expect(error).toHaveBeenCalledWith(expect.stringContaining(join(agentDir, 'SOUL.md')));
+      expect(error).toHaveBeenCalledWith(expect.stringContaining('mosaic fleet agent new'));
+    } finally {
+      error.mockRestore();
+      exit.mockRestore();
+      vi.unstubAllEnvs();
+      rmSync(home, { recursive: true, force: true });
+      rmSync(agentDir, { recursive: true, force: true });
+      rmSync(installed, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects a group-writable installed helper root', () => {
+    const agentDir = mkdtempSync(join(tmpdir(), 'mosaic-seq-seat-'));
+    const installed = mkdtempSync(join(tmpdir(), 'mosaic-seq-installed-'));
+    const checker = join(installed, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+    try {
+      mkdirSync(join(installed, 'tools', '_scripts'), { recursive: true });
+      copyFileSync(
+        join(process.cwd(), 'framework', 'tools', '_scripts', 'mosaic-ensure-sequential-thinking'),
+        checker,
+      );
+      chmodSync(installed, 0o770);
+      expect(() => checkSequentialThinking('claude', { agentDir, mosaicHome: installed })).toThrow(
+        /not a trusted installed file/,
+      );
+    } finally {
+      chmodSync(installed, 0o700);
+      rmSync(agentDir, { recursive: true, force: true });
+      rmSync(installed, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses an empty seat even when operator HOME is configured', () => {
+    const home = mkdtempSync(join(tmpdir(), 'mosaic-seq-home-'));
+    const agentDir = mkdtempSync(join(tmpdir(), 'mosaic-seq-seat-'));
+    const installed = mkdtempSync(join(tmpdir(), 'mosaic-seq-installed-'));
+    const checker = join(installed, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+    const exit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
+    try {
+      mkdirSync(join(installed, 'tools', '_scripts'), { recursive: true });
+      copyFileSync(
+        join(process.cwd(), 'framework', 'tools', '_scripts', 'mosaic-ensure-sequential-thinking'),
+        checker,
+      );
+      writeFileSync(
+        join(home, '.claude.json'),
+        JSON.stringify({
+          mcpServers: {
+            'sequential-thinking': {
+              command: 'npx',
+              args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+            },
+          },
+        }),
+      );
+      vi.stubEnv('MOSAIC_HOME', installed);
+      vi.stubEnv('HOME', home);
+      expect(() => checkSequentialThinking('claude', { agentDir, mosaicHome: installed })).toThrow(
+        'process.exit called',
+      );
+      expect(exit).toHaveBeenCalledWith(1);
+    } finally {
+      exit.mockRestore();
+      vi.unstubAllEnvs();
+      rmSync(home, { recursive: true, force: true });
+      rmSync(agentDir, { recursive: true, force: true });
+      rmSync(installed, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('buildPiSkillArgs', () => {
   it('disables auto-discovery but force-loads fleet-critical skills by default', () => {
     expect(buildPiSkillArgs([], {}, fakeSkills, fakeForced)).toEqual([

packages/mosaic/src/commands/launch.ts

@@ -8,6 +8,7 @@
 import { execFileSync, execSync, spawnSync } from 'node:child_process';
 import {
   existsSync,
+  lstatSync,
   mkdirSync,
   readFileSync,
   writeFileSync,
@@ -19,14 +20,14 @@ import {
 import { createHash, randomBytes } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { homedir, hostname } from 'node:os';
-import { join, dirname } from 'node:path';
+import { isAbsolute, join, dirname, relative, resolve, sep } from 'node:path';
 import type { Command } from 'commander';
 import {
   buildResolvedFleetCommsBlock,
   renderToolsContractStatus,
   resolveFleetIdentity,
 } from '../fleet/comms-onboarding.js';
-import { readRegularFileSecure } from '../fleet/secure-file.js';
+import { assertNoSymlinkAncestors, readRegularFileSecure } from '../fleet/secure-file.js';
 import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
 import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
@@ -35,7 +36,14 @@ import { runLeaseEnforcementDoctorCheck } from './lease-doctor-check.js';
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 const MAX_INSTALLED_TOOLS_BYTES = 256 * 1024;
 
-type RuntimeName = 'claude' | 'codex' | 'opencode' | 'pi';
+export type RuntimeName = 'claude' | 'codex' | 'opencode' | 'pi';
+
+/** Fleet context for the single harness-home resolution seam. */
+export interface FleetHarnessContext {
+  readonly agentDir: string;
+  /** Active installed Mosaic root for fleet-specific helper resolution. */
+  readonly mosaicHome?: string;
+}
 
 const RUNTIME_LABELS: Record<RuntimeName, string> = {
   claude: 'Claude Code',
@@ -64,19 +72,19 @@ const HARNESS_HOME_ENV: Record<RuntimeName, string> = {
   opencode: 'XDG_CONFIG_HOME',
 };
 
-/** Dedicated mosaic-owned home for a runtime: ~/.config/mosaic/.<runtime> */
+/** Dedicated runtime home, optionally scoped to a user fleet agent. */
-function harnessHome(runtime: RuntimeName): string {
+export function harnessHome(runtime: RuntimeName, fleet?: FleetHarnessContext): string {
-  return join(MOSAIC_HOME, `.${runtime}`);
+  return join(fleet?.agentDir ?? MOSAIC_HOME, `.${runtime}`);
 }
 
 /**
  * Env overlay pointing a runtime at its mosaic-owned home. The directory is
  * created on demand so a first launch does not fail on a missing path.
  */
-function harnessEnv(runtime: RuntimeName): Record<string, string> {
+function harnessEnv(runtime: RuntimeName, fleet?: FleetHarnessContext): Record<string, string> {
   const key = HARNESS_HOME_ENV[runtime];
   if (!key) return {};
-  const home = harnessHome(runtime);
+  const home = harnessHome(runtime, fleet);
   mkdirSync(home, { recursive: true });
   return { [key]: home };
 }
@@ -162,7 +170,13 @@ function redactArgv(argv: string[]): string[] {
   );
 }
 
-function recordLaunch(runtime: RuntimeName, cliArgs: string[], yolo: boolean): void {
+function recordLaunch(
+  runtime: RuntimeName,
+  cliArgs: string[],
+  yolo: boolean,
+  fleet?: FleetHarnessContext,
+  launchEnv: NodeJS.ProcessEnv = process.env,
+): void {
   try {
     mkdirSync(LAUNCH_LEDGER_DIR, { recursive: true, mode: 0o700 });
     // Correlation id for the lease.register half. Set into process.env so it
@@ -180,13 +194,13 @@ function recordLaunch(runtime: RuntimeName, cliArgs: string[], yolo: boolean): v
       mode: yolo ? 'yolo' : 'normal',
       cwd: process.cwd(),
       cli_version: CLI_VERSION,
-      config_home: harnessHome(runtime),
+      config_home: harnessHome(runtime, fleet),
       config_home_isolated: true,
       config_home_env: HARNESS_HOME_ENV[runtime] ?? null,
       argv: redactArgv(cliArgs),
       normative_fragments: normativeFragmentDigests(runtime),
       // names only — values are never recorded
-      mosaic_env_present: Object.keys(process.env)
+      mosaic_env_present: Object.keys(launchEnv)
         .filter((k) => k.startsWith('MOSAIC_'))
         .sort(),
     };
@@ -230,7 +244,22 @@ function checkRuntime(cmd: string): void {
   }
 }
 
-function checkSoul(): void {
+function checkSoul(fleet?: FleetHarnessContext): void {
+  // A fleet seat carries its own identity -- `mosaic fleet agent new` writes SOUL.md into the
+  // seat home -- so the operator's system-wide SOUL.md is not the file to check, and the
+  // interactive wizard is never the right answer for an unattended seat. Measured on a
+  // greenfield VM: a seat launched into tmux parked on the wizard's menu with nobody at the
+  // pane. The session was live, the unit reported fine, and no agent ever started.
+  if (fleet) {
+    const seatSoul = join(fleet.agentDir, 'SOUL.md');
+    if (!existsSync(seatSoul)) {
+      console.error(`[mosaic] ERROR: seat identity not found: ${seatSoul}`);
+      console.error('[mosaic] Scaffold the seat first: mosaic fleet agent new <name>');
+      process.exit(1);
+    }
+    return;
+  }
+
   const soulPath = join(MOSAIC_HOME, 'SOUL.md');
   if (!existsSync(soulPath)) {
     console.log('[mosaic] SOUL.md not found. Running setup wizard...');
@@ -262,9 +291,9 @@ interface SettingsAudit {
   warnings: string[];
 }
 
-function auditClaudeSettings(): SettingsAudit {
+function auditClaudeSettings(fleet?: FleetHarnessContext): SettingsAudit {
   const warnings: string[] = [];
-  const settingsPath = join(harnessHome('claude'), 'settings.json');
+  const settingsPath = join(harnessHome('claude', fleet), 'settings.json');
   const settings = readJson(settingsPath);
 
   if (!settings) {
@@ -332,13 +361,98 @@ function printSettingsWarnings(audit: SettingsAudit): void {
   );
 }
 
-function checkSequentialThinking(runtime: string): void {
+function resolveExecutable(name: string): string {
-  const checker = fwScript('mosaic-ensure-sequential-thinking');
+  const result = spawnSync('which', [name], { encoding: 'utf8' });
+  const path = result.status === 0 ? result.stdout.trim() : '';
+  if (!path || !isAbsolute(path) || !existsSync(path)) {
+    throw new Error(`required helper executable is unavailable: ${name}`);
+  }
+  return path;
+}
+
+function trustedFleetHelper(mosaicHome: string): string {
+  const root = resolve(mosaicHome);
+  const checker = join(root, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+  try {
+    assertNoSymlinkAncestors(checker);
+    const owner = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    let cursor = root;
+    for (const component of relative(root, checker).split(sep).filter(Boolean)) {
+      const info = lstatSync(cursor);
+      if (
+        !info.isDirectory() ||
+        info.isSymbolicLink() ||
+        (info.mode & 0o022) !== 0 ||
+        (owner !== undefined && info.uid !== owner && info.uid !== 0)
+      ) {
+        throw new Error('helper directory has unsafe type, owner, or permissions');
+      }
+      cursor = join(cursor, component);
+    }
+    const helperInfo = lstatSync(checker);
+    if (
+      !helperInfo.isFile() ||
+      helperInfo.isSymbolicLink() ||
+      (helperInfo.mode & 0o022) !== 0 ||
+      (helperInfo.mode & 0o111) === 0 ||
+      (owner !== undefined && helperInfo.uid !== owner && helperInfo.uid !== 0)
+    ) {
+      throw new Error('helper has unsafe type, owner, or permissions');
+    }
+  } catch (error: unknown) {
+    throw new Error(
+      `fleet sequential-thinking helper is not a trusted installed file under ${root}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return checker;
+}
+
+export function checkSequentialThinking(runtime: RuntimeName, fleet?: FleetHarnessContext): void {
+  // Fleet launch must use the active --mosaic-home installation. Non-fleet
+  // launches retain the package/deployed helper resolver.
+  const checker = fleet?.mosaicHome
+    ? trustedFleetHelper(fleet.mosaicHome)
+    : fwScript('mosaic-ensure-sequential-thinking');
   if (!existsSync(checker)) return; // Skip if checker doesn't exist
-  const result = spawnSync(checker, ['--check', '--runtime', runtime], { stdio: 'ignore' });
+  const fleetClaudeConfig =
+    runtime === 'claude' && fleet ? harnessHome('claude', fleet) : undefined;
+  const fleetCodexHome = runtime === 'codex' && fleet ? harnessHome('codex', fleet) : undefined;
+  const fleetOpenCodeHome =
+    runtime === 'opencode' && fleet ? harnessHome('opencode', fleet) : undefined;
+  const python = resolveExecutable('python3');
+  const node = resolveExecutable('node');
+  const npx = resolveExecutable('npx');
+  const capabilityPath = [...new Set([dirname(python), dirname(node), dirname(npx)])].join(':');
+  const result = spawnSync(
+    checker,
+    [
+      '--check',
+      '--runtime',
+      runtime,
+      ...(fleetClaudeConfig === undefined ? [] : ['--claude-config-dir', fleetClaudeConfig]),
+    ],
+    {
+      stdio: 'ignore',
+      env: {
+        HOME: process.env['HOME'] ?? '',
+        PATH: capabilityPath,
+        LANG: process.env['LANG'] ?? 'C.UTF-8',
+        ...(process.env['MOSAIC_SEQ_CHECK_WARM'] === undefined
+          ? {}
+          : { MOSAIC_SEQ_CHECK_WARM: process.env['MOSAIC_SEQ_CHECK_WARM'] }),
+        ...(process.env['MOSAIC_SEQ_WARM_TIMEOUT_SEC'] === undefined
+          ? {}
+          : { MOSAIC_SEQ_WARM_TIMEOUT_SEC: process.env['MOSAIC_SEQ_WARM_TIMEOUT_SEC'] }),
+        ...(fleetCodexHome === undefined ? {} : { CODEX_HOME: fleetCodexHome }),
+        ...(fleetOpenCodeHome === undefined ? {} : { XDG_CONFIG_HOME: fleetOpenCodeHome }),
+      },
+    },
+  );
   if (result.status !== 0) {
     console.error('[mosaic] ERROR: sequential-thinking MCP is required but not configured.');
-    console.error(`[mosaic] Fix: ${checker} --runtime ${runtime}`);
+    const repairArgs =
+      fleetClaudeConfig === undefined ? '' : ` --claude-config-dir ${fleetClaudeConfig}`;
+    console.error(`[mosaic] Fix: ${checker} --runtime ${runtime}${repairArgs}`);
     process.exit(1);
   }
 }
@@ -483,7 +597,11 @@ function buildPrdBlock(): string {
  * `mosaicHome` is parameterized for testability; production callers use the
  * module-level default.
  */
-export function composeContract(runtime: RuntimeName, mosaicHome: string = MOSAIC_HOME): string {
+export function composeContract(
+  runtime: RuntimeName,
+  mosaicHome: string = MOSAIC_HOME,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
   const runtimeContractPaths: Record<RuntimeName, string> = {
     claude: join(mosaicHome, 'runtime', 'claude', 'RUNTIME.md'),
     codex: join(mosaicHome, 'runtime', 'codex', 'RUNTIME.md'),
@@ -540,13 +658,13 @@ For required push/merge/issue-close/release actions, execute without routine con
     parts.push('\n\n## Operator Overlay (USER.local.md)\n\n' + userLocal);
   }
 
-  const fleetIdentity = resolveFleetIdentity(mosaicHome, process.env['MOSAIC_AGENT_NAME']);
+  const fleetIdentity = resolveFleetIdentity(mosaicHome, env['MOSAIC_AGENT_NAME']);
   if (!fleetIdentity.ok) {
     throw new Error(`Fleet communications contract unavailable: ${fleetIdentity.error}`);
   }
   const canonicalMember = fleetIdentity.identity?.member;
-  if (canonicalMember && process.env['MOSAIC_AGENT_CLASS']?.trim()) {
+  if (canonicalMember && env['MOSAIC_AGENT_CLASS']?.trim()) {
-    const ambientClass = canonicalizeRoleClass(process.env['MOSAIC_AGENT_CLASS']).canonicalClass;
+    const ambientClass = canonicalizeRoleClass(env['MOSAIC_AGENT_CLASS']).canonicalClass;
     if (ambientClass !== canonicalMember.className) {
       throw new Error(
         `Ambient MOSAIC_AGENT_CLASS resolves to "${ambientClass}" but canonical roster member "${canonicalMember.name}" resolves to "${canonicalMember.className}". Refusing split identity authority.`,
@@ -583,13 +701,13 @@ For required push/merge/issue-close/release actions, execute without routine con
   // Fleet launches derive every identity projection from the one canonical roster
   // member resolved above. Non-fleet launches retain the legacy ambient persona
   // and tool-policy behavior.
-  const personaClass = canonicalMember?.className ?? process.env['MOSAIC_AGENT_CLASS'];
+  const personaClass = canonicalMember?.className ?? env['MOSAIC_AGENT_CLASS'];
   const persona = readPersonaContractBlock(mosaicHome, personaClass);
   if (persona) parts.push('\n\n' + persona);
 
   const toolPolicyName = canonicalMember
     ? canonicalMember.toolPolicy
-    : process.env['MOSAIC_AGENT_TOOL_POLICY'];
+    : env['MOSAIC_AGENT_TOOL_POLICY'];
   const toolPolicy = readFleetToolPolicyBlock(toolPolicyName);
   if (toolPolicy) parts.push('\n\n' + toolPolicy);
 
@@ -613,8 +731,8 @@ function readFleetToolPolicyBlock(policy: string | undefined): string {
 }
 
 /** @deprecated internal alias — use composeContract. Retained for call-site clarity. */
-function buildRuntimePrompt(runtime: RuntimeName): string {
+function buildRuntimePrompt(runtime: RuntimeName, env: NodeJS.ProcessEnv = process.env): string {
-  return composeContract(runtime);
+  return composeContract(runtime, MOSAIC_HOME, env);
 }
 
 // ─── Session lock ────────────────────────────────────────────────────────────
@@ -695,8 +813,12 @@ function checkResumableSession(): void {
 
 // ─── Write config for runtimes that read from fixed paths ────────────────────
 
-function ensureRuntimeConfig(runtime: RuntimeName, destPath: string): void {
+function ensureRuntimeConfig(
-  const prompt = buildRuntimePrompt(runtime);
+  runtime: RuntimeName,
+  destPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  const prompt = buildRuntimePrompt(runtime, env);
   mkdirSync(dirname(destPath), { recursive: true });
   const existing = readOptional(destPath);
   if (existing !== prompt) {
@@ -889,15 +1011,51 @@ function getMissionPrompt(): string {
   return `Active mission detected: ${mission.name}. Read the mission state files and report status.`;
 }
 
-function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): never {
+interface RuntimeLaunchContext {
+  readonly fleet?: FleetHarnessContext;
+  readonly declaredEnv?: Readonly<Record<string, string>>;
+  /** Test seam: bypass only final runtime binary discovery. */
+  readonly runtimeCheck?: (runtime: RuntimeName) => void;
+  /** Test seam: receives the fully composed final runtime invocation. */
+  readonly finalExecutor?: (runtime: RuntimeName, args: string[], env: NodeJS.ProcessEnv) => void;
+  readonly recordLaunch?: boolean;
+}
+
+function minimalLaunchEnv(declared: Readonly<Record<string, string>>): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const name of [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'TERM',
+    'COLORTERM',
+    'LANG',
+    'LC_ALL',
+    'TMPDIR',
+    'XDG_RUNTIME_DIR',
+  ]) {
+    const value = process.env[name];
+    if (value !== undefined) env[name] = value;
+  }
+  return { ...env, ...declared };
+}
+
+function launchRuntime(
+  runtime: RuntimeName,
+  args: string[],
+  yolo: boolean,
+  context: RuntimeLaunchContext = {},
+): never {
   checkMosaicHome();
   checkFile(join(MOSAIC_HOME, 'AGENTS.md'), 'AGENTS.md');
-  checkSoul();
+  checkSoul(context.fleet);
-  checkRuntime(runtime);
+  (context.runtimeCheck ?? checkRuntime)(runtime);
 
   // Pi doesn't need sequential-thinking (has native thinking levels)
   if (runtime !== 'pi') {
-    checkSequentialThinking(runtime);
+    checkSequentialThinking(runtime, context.fleet);
   }
 
   checkResumableSession();
@@ -909,14 +1067,32 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
   const missionStr = hasMissionNoArgs ? ' (active mission detected)' : '';
 
   writeSessionLock(runtime);
+  const launchEnv =
+    context.declaredEnv === undefined ? process.env : minimalLaunchEnv(context.declaredEnv);
+  // A per-agent profile is the launch SSOT and intentionally does not require a
+  // second roster registry. Keep roster-v1 identity composition for legacy
+  // launches, but remove its identity keys from the contract-build environment
+  // for a profile-backed seat. The declared identity is still exported to the
+  // harness process below.
+  const contractEnv =
+    context.declaredEnv === undefined
+      ? launchEnv
+      : Object.fromEntries(
+          Object.entries(launchEnv).filter(
+            ([name]) =>
+              name !== 'MOSAIC_AGENT_NAME' &&
+              name !== 'MOSAIC_AGENT_CLASS' &&
+              name !== 'MOSAIC_AGENT_TOOL_POLICY',
+          ),
+        );
 
   switch (runtime) {
     case 'claude': {
       // Audit Claude Code settings and warn about missing hooks/plugins
-      const settingsAudit = auditClaudeSettings();
+      const settingsAudit = auditClaudeSettings(context.fleet);
       printSettingsWarnings(settingsAudit);
 
-      const prompt = buildRuntimePrompt('claude');
+      const prompt = buildRuntimePrompt('claude', contractEnv);
       const cliArgs: string[] = [];
       cliArgs.push('--append-system-prompt', prompt);
       if (hasMissionNoArgs) {
@@ -925,13 +1101,25 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
         cliArgs.push(...args);
       }
       console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
-      recordLaunch('claude', cliArgs, yolo);
+      if (context.recordLaunch !== false)
-      execLeaseGatedRuntime('claude', cliArgs, process.env, yolo);
+        recordLaunch('claude', cliArgs, yolo, context.fleet, launchEnv);
+      if (process.env['MOSAIC_LAUNCH_ID']) {
+        launchEnv['MOSAIC_LAUNCH_ID'] = process.env['MOSAIC_LAUNCH_ID'];
+      }
+      if (context.finalExecutor) {
+        context.finalExecutor('claude', cliArgs, launchEnv);
+      } else {
+        execLeaseGatedRuntime('claude', cliArgs, launchEnv, yolo, context.fleet);
+      }
       break;
     }
 
     case 'codex': {
-      ensureRuntimeConfig('codex', join(harnessHome('codex'), 'instructions.md'));
+      ensureRuntimeConfig(
+        'codex',
+        join(harnessHome('codex', context.fleet), 'instructions.md'),
+        contractEnv,
+      );
       const cliArgs = yolo ? ['--dangerously-bypass-approvals-and-sandbox'] : [];
       if (hasMissionNoArgs) {
         cliArgs.push(missionPrompt);
@@ -939,22 +1127,38 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
         cliArgs.push(...args);
       }
       console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
-      recordLaunch('codex', cliArgs, yolo);
+      recordLaunch('codex', cliArgs, yolo, context.fleet, launchEnv);
-      execRuntime('codex', cliArgs, { ...process.env, ...harnessEnv('codex') });
+      execRuntime('codex', cliArgs, {
+        ...launchEnv,
+        ...harnessEnv('codex', context.fleet),
+        ...(process.env['MOSAIC_LAUNCH_ID']
+          ? { MOSAIC_LAUNCH_ID: process.env['MOSAIC_LAUNCH_ID'] }
+          : {}),
+      });
       break;
     }
 
     case 'opencode': {
       // opencode follows XDG, so its config resolves to $XDG_CONFIG_HOME/opencode.
-      ensureRuntimeConfig('opencode', join(harnessHome('opencode'), 'opencode', 'AGENTS.md'));
+      ensureRuntimeConfig(
+        'opencode',
+        join(harnessHome('opencode', context.fleet), 'opencode', 'AGENTS.md'),
+        contractEnv,
+      );
       console.log(`[mosaic] Launching ${label}${modeStr}...`);
-      recordLaunch('opencode', args, yolo);
+      recordLaunch('opencode', args, yolo, context.fleet, launchEnv);
-      execRuntime('opencode', args, { ...process.env, ...harnessEnv('opencode') });
+      execRuntime('opencode', args, {
+        ...launchEnv,
+        ...harnessEnv('opencode', context.fleet),
+        ...(process.env['MOSAIC_LAUNCH_ID']
+          ? { MOSAIC_LAUNCH_ID: process.env['MOSAIC_LAUNCH_ID'] }
+          : {}),
+      });
       break;
     }
 
     case 'pi': {
-      const prompt = buildRuntimePrompt('pi');
+      const prompt = buildRuntimePrompt('pi', contractEnv);
       const cliArgs = ['--append-system-prompt', prompt];
       cliArgs.push(...buildPiSkillArgs(args));
       cliArgs.push(...discoverPiExtension());
@@ -964,8 +1168,11 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
         cliArgs.push(...args);
       }
       console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
-      recordLaunch('pi', cliArgs, yolo);
+      recordLaunch('pi', cliArgs, yolo, context.fleet, launchEnv);
-      execLeaseGatedRuntime('pi', cliArgs);
+      if (process.env['MOSAIC_LAUNCH_ID']) {
+        launchEnv['MOSAIC_LAUNCH_ID'] = process.env['MOSAIC_LAUNCH_ID'];
+      }
+      execLeaseGatedRuntime('pi', cliArgs, launchEnv, false, context.fleet);
       break;
     }
   }
@@ -993,6 +1200,7 @@ function execLeaseGatedRuntime(
   args: string[],
   baseEnv: NodeJS.ProcessEnv = process.env,
   dangerous = false,
+  fleet?: FleetHarnessContext,
 ): void {
   const launcher = resolveTool('lease-broker', 'launch-runtime.py');
   const dangerousArgs = dangerous ? ['--dangerous'] : [];
@@ -1001,13 +1209,41 @@ function execLeaseGatedRuntime(
     [launcher, ...dangerousArgs, '--runtime', runtime, '--', runtime, ...args],
     {
       ...baseEnv,
-      ...harnessEnv(runtime),
+      ...harnessEnv(runtime, fleet),
       MOSAIC_LEASE_BROKER_SOCKET: defaultLeaseBrokerSocket(baseEnv),
       MOSAIC_RUNTIME_GENERATION: baseEnv['MOSAIC_RUNTIME_GENERATION'] ?? '1',
     },
   );
 }
 
+/** Fleet entry point reusing the normative runtime launch and exec path. */
+export function launchFleetRuntime(
+  runtime: RuntimeName,
+  args: string[],
+  declaredEnv: Readonly<Record<string, string>>,
+  fleet: FleetHarnessContext,
+  dangerous = false,
+): never {
+  return launchRuntime(runtime, args, dangerous, { fleet, declaredEnv });
+}
+
+/** Bounded production-path test seam; all preflight and composition remain real. */
+export function launchFleetRuntimeForTest(
+  runtime: RuntimeName,
+  args: string[],
+  declaredEnv: Readonly<Record<string, string>>,
+  fleet: FleetHarnessContext,
+  finalExecutor: NonNullable<RuntimeLaunchContext['finalExecutor']>,
+): never {
+  return launchRuntime(runtime, args, false, {
+    fleet,
+    declaredEnv,
+    runtimeCheck: () => undefined,
+    finalExecutor,
+    recordLaunch: false,
+  });
+}
+
 /** exec into the runtime, replacing the current process. */
 function execRuntime(cmd: string, args: string[], env: NodeJS.ProcessEnv = process.env): void {
   try {

packages/mosaic/src/fleet/adoption.spec.ts

@@ -0,0 +1,341 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { AdoptionError, promoteBundleAlias, promoteStoreEntry, scanAdoptions } from './adoption.js';
+
+let root: string | undefined;
+
+afterEach(async (): Promise<void> => {
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+async function userHome(): Promise<string> {
+  root = await mkdtemp(join(tmpdir(), 'mosaic-adopt-'));
+  return join(root, '.mosaic');
+}
+
+/** A real directory where the primary alias belongs, with something inside worth not losing. */
+function realAliasDirectory(
+  home: string,
+  harness: string,
+  credential = '.credentials.json',
+): string {
+  const path = join(home, 'auth', harness, 'primary');
+  mkdirSync(path, { recursive: true });
+  writeFileSync(join(path, credential), '{"token":"kept"}');
+  return path;
+}
+
+function seat(
+  home: string,
+  name: string,
+  profile: Record<string, unknown> = { schema: 1, harness: 'claude', bundle: 'primary' },
+): string {
+  const dir = join(home, 'fleet', 'agents', name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'profile.json'), `${JSON.stringify(profile, null, 2)}\n`);
+  return dir;
+}
+
+/** A real plugin/skill directory inside a seat, where a link into the store belongs. */
+function seatDirectory(
+  home: string,
+  agent: string,
+  harness: string,
+  plural: string,
+  name: string,
+): string {
+  const path = join(home, 'fleet', 'agents', agent, `.${harness}`, plural, name);
+  mkdirSync(path, { recursive: true });
+  writeFileSync(join(path, 'marker.txt'), 'kept');
+  return path;
+}
+
+describe('scanAdoptions', () => {
+  it('finds nothing on a host that has no ~/.mosaic at all', async () => {
+    expect(scanAdoptions(await userHome())).toEqual([]);
+  });
+
+  it('finds a real directory on the primary alias path and names the command that resolves it', async () => {
+    const home = await userHome();
+    const path = realAliasDirectory(home, 'claude');
+
+    const findings = scanAdoptions(home);
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.kind).toBe('bundle-alias');
+    expect(findings[0]?.path).toBe(path);
+    expect(findings[0]?.harness).toBe('claude');
+    expect(findings[0]?.blocked).toBeUndefined();
+    expect(findings[0]?.remedy).toBe('mosaic fleet adopt bundle --harness claude --as <account>');
+  });
+
+  it('ignores a primary alias that is already a symlink', async () => {
+    const home = await userHome();
+    mkdirSync(join(home, 'auth', 'claude', 'jason_woltje.com'), { recursive: true });
+    symlinkSync('jason_woltje.com', join(home, 'auth', 'claude', 'primary'));
+
+    expect(scanAdoptions(home)).toEqual([]);
+  });
+
+  it('finds a real plugin directory inside a seat', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+    const path = seatDirectory(home, 'uc-e6-coder', 'claude', 'plugins', 'reviewer');
+
+    const findings = scanAdoptions(home);
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      kind: 'store-entry',
+      path,
+      agent: 'uc-e6-coder',
+      store: 'plugin',
+      name: 'reviewer',
+    });
+    expect(findings[0]?.remedy).toBe('mosaic fleet adopt plugin reviewer --seat uc-e6-coder');
+  });
+
+  it('finds skills the same way it finds plugins', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-rev');
+    seatDirectory(home, 'uc-e6-rev', 'claude', 'skills', 'spec-audit');
+
+    const findings = scanAdoptions(home);
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.store).toBe('skill');
+    expect(findings[0]?.remedy).toBe('mosaic fleet adopt skill spec-audit --seat uc-e6-rev');
+  });
+
+  // Scanning the wrong directory name would report nothing on a pi seat while launch keeps
+  // refusing to compose it, which is worse than not having the scan.
+  it('looks in the seat home the launcher uses, not always the claude one', async () => {
+    const home = await userHome();
+    seat(home, 'terra', { schema: 1, harness: 'pi', bundle: 'primary' });
+    const path = seatDirectory(home, 'terra', 'pi', 'plugins', 'notes');
+
+    expect(scanAdoptions(home).map((finding) => finding.path)).toEqual([path]);
+  });
+
+  it('does not report a link that is already pointing into the store', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+    mkdirSync(join(home, 'plugins', 'reviewer'), { recursive: true });
+    const installRoot = join(home, 'fleet', 'agents', 'uc-e6-coder', '.claude', 'plugins');
+    mkdirSync(installRoot, { recursive: true });
+    symlinkSync(join(home, 'plugins', 'reviewer'), join(installRoot, 'reviewer'));
+
+    expect(scanAdoptions(home)).toEqual([]);
+  });
+
+  it('marks the finding blocked when the store already holds that name', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+    seatDirectory(home, 'uc-e6-coder', 'claude', 'plugins', 'reviewer');
+    mkdirSync(join(home, 'plugins', 'reviewer'), { recursive: true });
+
+    const findings = scanAdoptions(home);
+
+    expect(findings[0]?.blocked).toBe('destination occupied');
+    expect(findings[0]?.remedy).toContain('compare the two');
+  });
+
+  // One malformed profile hiding every finding behind it would make the scan useless exactly
+  // on the hosts that need it most.
+  it('reports an unreadable seat as a gap and keeps scanning the others', async () => {
+    const home = await userHome();
+    mkdirSync(join(home, 'fleet', 'agents', 'broken'), { recursive: true });
+    writeFileSync(join(home, 'fleet', 'agents', 'broken', 'profile.json'), 'not json');
+    seat(home, 'working');
+    const path = seatDirectory(home, 'working', 'claude', 'plugins', 'reviewer');
+
+    const findings = scanAdoptions(home);
+
+    expect(findings.map((finding) => finding.kind)).toEqual(['unreadable-seat', 'store-entry']);
+    expect(findings[0]?.blocked).toBe('unreadable profile');
+    expect(findings[1]?.path).toBe(path);
+  });
+});
+
+describe('promoteBundleAlias', () => {
+  it('moves the directory to its account name and points the alias at it', async () => {
+    const home = await userHome();
+    const from = realAliasDirectory(home, 'claude');
+
+    const result = promoteBundleAlias(home, 'claude', 'jason_woltje.com');
+
+    expect(result.to).toBe(join(home, 'auth', 'claude', 'jason_woltje.com'));
+    expect(result.from).toBe(from);
+    // The credential travelled with the directory; adoption is a move, never a re-creation.
+    expect(readFileSync(join(result.to, '.credentials.json'), 'utf8')).toBe('{"token":"kept"}');
+    const alias = lstatSync(result.alias);
+    expect(alias.isSymbolicLink()).toBe(true);
+    expect(scanAdoptions(home)).toEqual([]);
+  });
+
+  it('refuses when the alias path is already a symlink', async () => {
+    const home = await userHome();
+    mkdirSync(join(home, 'auth', 'pi', 'jason_woltje.com'), { recursive: true });
+    symlinkSync('jason_woltje.com', join(home, 'auth', 'pi', 'primary'));
+
+    expect(() => promoteBundleAlias(home, 'pi', 'other')).toThrow(
+      /already an alias symlink.*mosaic auth default/su,
+    );
+  });
+
+  it('refuses when there is nothing on the alias path', async () => {
+    const home = await userHome();
+    expect(() => promoteBundleAlias(home, 'claude', 'jason_woltje.com')).toThrow(AdoptionError);
+  });
+
+  it('refuses to adopt a directory as the alias name itself', async () => {
+    const home = await userHome();
+    realAliasDirectory(home, 'claude');
+
+    expect(() => promoteBundleAlias(home, 'claude', 'primary')).toThrow(
+      /that is the alias being freed/u,
+    );
+  });
+
+  it('refuses a name that would escape the auth root', async () => {
+    const home = await userHome();
+    realAliasDirectory(home, 'claude');
+
+    expect(() => promoteBundleAlias(home, 'claude', '../elsewhere')).toThrow(
+      /not a safe bundle name/u,
+    );
+    expect(existsSync(join(home, 'auth', 'claude', 'primary', '.credentials.json'))).toBe(true);
+  });
+
+  // The failure that would cost data: an occupied destination silently merged into, or worse,
+  // replaced. Both directories must still be exactly where they were.
+  it('refuses an occupied destination and moves nothing', async () => {
+    const home = await userHome();
+    realAliasDirectory(home, 'claude');
+    const occupied = join(home, 'auth', 'claude', 'jason_woltje.com');
+    mkdirSync(occupied, { recursive: true });
+    writeFileSync(join(occupied, '.credentials.json'), '{"token":"other"}');
+
+    expect(() => promoteBundleAlias(home, 'claude', 'jason_woltje.com')).toThrow(
+      /already exists and will not be overwritten/u,
+    );
+    expect(readFileSync(join(home, 'auth', 'claude', 'primary', '.credentials.json'), 'utf8')).toBe(
+      '{"token":"kept"}',
+    );
+    expect(readFileSync(join(occupied, '.credentials.json'), 'utf8')).toBe('{"token":"other"}');
+  });
+});
+
+describe('promoteStoreEntry', () => {
+  it('moves the directory into the central store, creating the store root', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder', {
+      schema: 1,
+      harness: 'claude',
+      bundle: 'primary',
+      plugins: ['reviewer'],
+    });
+    const from = seatDirectory(home, 'uc-e6-coder', 'claude', 'plugins', 'reviewer');
+
+    const result = promoteStoreEntry(home, 'uc-e6-coder', 'plugin', 'reviewer');
+
+    expect(result.to).toBe(join(home, 'plugins', 'reviewer'));
+    expect(readFileSync(join(result.to, 'marker.txt'), 'utf8')).toBe('kept');
+    expect(existsSync(from)).toBe(false);
+    expect(result.listedInProfile).toBe(true);
+  });
+
+  // Installing the link here would fail the next launch as an unrecorded symlink, because the
+  // seat's .mosaic-managed-links.json is launch's to write. Adoption stops at the move.
+  it('leaves the seat path empty rather than installing the link itself', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder', {
+      schema: 1,
+      harness: 'claude',
+      bundle: 'primary',
+      plugins: ['reviewer'],
+    });
+    const from = seatDirectory(home, 'uc-e6-coder', 'claude', 'plugins', 'reviewer');
+
+    promoteStoreEntry(home, 'uc-e6-coder', 'plugin', 'reviewer');
+
+    expect(existsSync(from)).toBe(false);
+    expect(() => lstatSync(from)).toThrow();
+  });
+
+  it('says when the seat does not list the entry, because then nothing links it back', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+    seatDirectory(home, 'uc-e6-coder', 'claude', 'plugins', 'reviewer');
+
+    expect(promoteStoreEntry(home, 'uc-e6-coder', 'plugin', 'reviewer').listedInProfile).toBe(
+      false,
+    );
+  });
+
+  it('refuses an occupied destination and moves nothing', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+    const from = seatDirectory(home, 'uc-e6-coder', 'claude', 'plugins', 'reviewer');
+    mkdirSync(join(home, 'plugins', 'reviewer'), { recursive: true });
+    writeFileSync(join(home, 'plugins', 'reviewer', 'marker.txt'), 'store copy');
+
+    expect(() => promoteStoreEntry(home, 'uc-e6-coder', 'plugin', 'reviewer')).toThrow(
+      /already exists and will not be overwritten/u,
+    );
+    expect(readFileSync(join(from, 'marker.txt'), 'utf8')).toBe('kept');
+    expect(readFileSync(join(home, 'plugins', 'reviewer', 'marker.txt'), 'utf8')).toBe(
+      'store copy',
+    );
+  });
+
+  it('refuses an entry that is already a link into the store', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+    mkdirSync(join(home, 'plugins', 'reviewer'), { recursive: true });
+    const installRoot = join(home, 'fleet', 'agents', 'uc-e6-coder', '.claude', 'plugins');
+    mkdirSync(installRoot, { recursive: true });
+    symlinkSync(join(home, 'plugins', 'reviewer'), join(installRoot, 'reviewer'));
+
+    expect(() => promoteStoreEntry(home, 'uc-e6-coder', 'plugin', 'reviewer')).toThrow(
+      /already a link into the store/u,
+    );
+  });
+
+  it('refuses a name that would escape the store root', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+
+    expect(() => promoteStoreEntry(home, 'uc-e6-coder', 'plugin', '../escape')).toThrow(
+      /not a safe plugin name/u,
+    );
+  });
+
+  it('names the profile it could not read rather than guessing the seat home', async () => {
+    const home = await userHome();
+
+    expect(() => promoteStoreEntry(home, 'ghost', 'plugin', 'reviewer')).toThrow(
+      /ghost.*profile\.json.*cannot be located/su,
+    );
+  });
+
+  it('reports a missing directory as nothing to adopt', async () => {
+    const home = await userHome();
+    seat(home, 'uc-e6-coder');
+
+    expect(() => promoteStoreEntry(home, 'uc-e6-coder', 'skill', 'absent')).toThrow(
+      /no such skill directory/u,
+    );
+  });
+});

packages/mosaic/src/fleet/adoption.ts

@@ -0,0 +1,380 @@
+/**
+ * Adopting real directories that sit where the fleet expects a managed link.
+ *
+ * A host used before the fleet arrived -- or an operator who ran a login by hand -- ends up
+ * with a real directory on a path launch reserves for a link: `auth/<harness>/primary`, or a
+ * plugin/skill directory inside a seat's home. Launch refuses those on purpose, because the
+ * only way to make a link fit there is to delete whatever is already there.
+ *
+ * This module is the other half of that refusal. It finds those directories and moves them
+ * where they belong. Nothing here deletes anything: a promotion is a rename, and an occupied
+ * destination is a refusal rather than a merge or an overwrite. Cross-device renames are
+ * surfaced instead of being retried as copy-then-delete, because a copy-then-delete is a
+ * delete and this module does not do that.
+ *
+ * Link creation is deliberately NOT done here. Seat store links are recorded in the seat's
+ * `.mosaic-managed-links.json`, and that manifest is owned by launch -- a link installed
+ * behind its back reads as "unrecorded symlink occupies managed path" on the next launch,
+ * which trades one refusal for another. So a promoted plugin lands in the central store and
+ * the next launch links it, provided the seat's profile lists it. Whether a seat gets a
+ * plugin is `mosaic fleet plugin`'s decision, not this one's.
+ *
+ * The auth alias is different: it lives in the auth root, no manifest covers it, and
+ * setDefaultBundle() already owns installing it. So a bundle promotion finishes the job.
+ */
+
+import { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, type Stats } from 'node:fs';
+import { join } from 'node:path';
+import { PRIMARY_ALIAS, assertSafeBundleName, authRoot, setDefaultBundle } from './auth-bundles.js';
+import type { CredentialHarness } from './credential-sharing.js';
+
+/** Mirrors the harness list the auth and launch surfaces accept. */
+const HARNESSES: readonly CredentialHarness[] = ['claude', 'codex', 'opencode', 'pi'];
+
+/** Store kinds a seat can hold, and the directory name each uses in both trees. */
+const STORE_DIRECTORY: Record<StoreKind, string> = { plugin: 'plugins', skill: 'skills' };
+
+/** Same charset as a bundle name; anything with a separator or a dot-dot never reaches a join. */
+const ENTRY_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@-]*$/;
+
+export type StoreKind = 'plugin' | 'skill';
+
+export type AdoptionErrorCode =
+  | 'invalid-request'
+  | 'nothing-to-adopt'
+  | 'destination-occupied'
+  | 'cross-device'
+  | 'unsafe-shape';
+
+export class AdoptionError extends Error {
+  readonly code: AdoptionErrorCode;
+
+  constructor(code: AdoptionErrorCode, message: string) {
+    super(message);
+    this.name = 'AdoptionError';
+    this.code = code;
+  }
+}
+
+export interface AdoptionFinding {
+  /** `bundle-alias` and `store-entry` are adoptable; `unreadable-seat` is a scan gap. */
+  readonly kind: 'bundle-alias' | 'store-entry' | 'unreadable-seat';
+  /** The real directory that a launch would refuse to touch. */
+  readonly path: string;
+  /** What this is, in one line. */
+  readonly reason: string;
+  /** The exact command that resolves it, or what to look at when nothing can. */
+  readonly remedy: string;
+  readonly harness?: CredentialHarness;
+  readonly agent?: string;
+  readonly store?: StoreKind;
+  readonly name?: string;
+  /** Set when the promotion cannot run as-is; the remedy then describes the obstacle. */
+  readonly blocked?: string;
+}
+
+export interface BundlePromotion {
+  readonly harness: CredentialHarness;
+  /** Where the adopted directory now lives. */
+  readonly bundle: string;
+  readonly from: string;
+  readonly to: string;
+  /** The alias path now pointing at it. */
+  readonly alias: string;
+}
+
+export interface StorePromotion {
+  readonly agent: string;
+  readonly store: StoreKind;
+  readonly name: string;
+  readonly from: string;
+  readonly to: string;
+  /** True when the seat's profile lists this entry, so the next launch will link it back. */
+  readonly listedInProfile: boolean;
+}
+
+function lstatIfPresent(path: string): Stats | undefined {
+  try {
+    return lstatSync(path);
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function isRealDirectory(path: string): boolean {
+  const info = lstatIfPresent(path);
+  return info !== undefined && info.isDirectory() && !info.isSymbolicLink();
+}
+
+function assertSafeEntryName(name: string, store: StoreKind): void {
+  if (!ENTRY_NAME.test(name)) {
+    throw new AdoptionError(
+      'invalid-request',
+      `"${name}" is not a safe ${store} name; use letters, digits, and . _ @ -`,
+    );
+  }
+}
+
+function agentsRoot(dataHome: string): string {
+  return join(dataHome, 'fleet', 'agents');
+}
+
+/**
+ * A seat's harness home, by the same rule launch uses (`harnessHome()` in commands/launch.ts).
+ * Scanning by any other rule finds directories launch never looks at and misses the ones it
+ * refuses on.
+ */
+function seatHome(dataHome: string, agent: string, harness: CredentialHarness): string {
+  return join(agentsRoot(dataHome), agent, `.${harness}`);
+}
+
+interface SeatProfile {
+  readonly harness: CredentialHarness;
+  readonly plugins: readonly string[];
+  readonly skills: readonly string[];
+}
+
+/**
+ * Read only what adoption needs out of a seat profile, leniently.
+ *
+ * A scan that dies on one malformed profile hides every finding behind it, so an unreadable
+ * profile is reported as a scan gap and the walk continues. Strictness belongs at launch,
+ * which validates the whole profile and refuses to run the seat.
+ */
+function readSeatProfile(dataHome: string, agent: string): SeatProfile | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(join(agentsRoot(dataHome), agent, 'profile.json'), 'utf8'));
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;
+  const raw = parsed as Record<string, unknown>;
+  const harness = raw['harness'];
+  if (typeof harness !== 'string' || !HARNESSES.includes(harness as CredentialHarness)) {
+    return undefined;
+  }
+  const names = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+  return {
+    harness: harness as CredentialHarness,
+    plugins: names(raw['plugins']),
+    skills: names(raw['skills']),
+  };
+}
+
+function listDirectory(path: string): string[] {
+  try {
+    return readdirSync(path, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+function listAgents(dataHome: string): string[] {
+  try {
+    return readdirSync(agentsRoot(dataHome), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+/**
+ * Everything under `~/.mosaic` that occupies a path the fleet manages with a link.
+ *
+ * Read-only. Every finding carries the command that resolves it, because the value of the
+ * scan is that an operator does not have to work out what a composition refusal meant.
+ */
+export function scanAdoptions(dataHome: string): AdoptionFinding[] {
+  const findings: AdoptionFinding[] = [];
+
+  for (const harness of HARNESSES) {
+    const alias = join(authRoot(dataHome, harness), PRIMARY_ALIAS);
+    if (!isRealDirectory(alias)) continue;
+    findings.push({
+      kind: 'bundle-alias',
+      path: alias,
+      harness,
+      reason: `a real directory occupies the ${PRIMARY_ALIAS} alias path; ${harness} seats pointed at "${PRIMARY_ALIAS}" cannot launch`,
+      remedy: `mosaic fleet adopt bundle --harness ${harness} --as <account>`,
+    });
+  }
+
+  for (const agent of listAgents(dataHome)) {
+    const profile = readSeatProfile(dataHome, agent);
+    if (profile === undefined) {
+      findings.push({
+        kind: 'unreadable-seat',
+        path: join(agentsRoot(dataHome), agent, 'profile.json'),
+        agent,
+        reason:
+          'profile could not be read, or names no known harness, so this seat was not scanned',
+        remedy: `mosaic fleet agent get ${agent}`,
+        blocked: 'unreadable profile',
+      });
+      continue;
+    }
+    for (const store of ['plugin', 'skill'] as const) {
+      const plural = STORE_DIRECTORY[store];
+      const installRoot = join(seatHome(dataHome, agent, profile.harness), plural);
+      for (const name of listDirectory(installRoot)) {
+        const destination = join(dataHome, plural, name);
+        const occupied = lstatIfPresent(destination) !== undefined;
+        findings.push({
+          kind: 'store-entry',
+          path: join(installRoot, name),
+          agent,
+          store,
+          name,
+          reason: `a real ${store} directory sits where the seat expects a link into the central store`,
+          remedy: occupied
+            ? `${destination} already exists; compare the two and remove or rename one by hand`
+            : `mosaic fleet adopt ${store} ${name} --seat ${agent}`,
+          ...(occupied ? { blocked: 'destination occupied' } : {}),
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Move a directory, refusing every case where the move would cost data.
+ *
+ * EXDEV is surfaced rather than handled: the fallback for a cross-device rename is copy then
+ * delete, and this module does not delete.
+ */
+function movePreservingBoth(from: string, to: string, label: string): void {
+  if (lstatIfPresent(to) !== undefined) {
+    throw new AdoptionError(
+      'destination-occupied',
+      `${label} destination already exists and will not be overwritten: ${to}`,
+    );
+  }
+  try {
+    renameSync(from, to);
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'EXDEV') {
+      throw new AdoptionError(
+        'cross-device',
+        `${from} and ${to} are on different filesystems, so this cannot be a rename. Copy it across yourself and remove the original once you have checked the copy: ${to}`,
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Adopt a real directory sitting on the `primary` alias path as a named bundle.
+ *
+ * The directory is moved to its account name first and the alias installed second. That order
+ * is the one that survives a failure: if the alias cannot be created, the credentials are
+ * intact under their own name and the error says where they are. The reverse order would have
+ * a window where the alias points at nothing.
+ */
+export function promoteBundleAlias(
+  dataHome: string,
+  harness: CredentialHarness,
+  as: string,
+): BundlePromotion {
+  assertSafeBundleName(as);
+  if (as === PRIMARY_ALIAS) {
+    throw new AdoptionError(
+      'invalid-request',
+      `--as must be the account this directory holds, not "${PRIMARY_ALIAS}" — that is the alias being freed`,
+    );
+  }
+  const root = authRoot(dataHome, harness);
+  const alias = join(root, PRIMARY_ALIAS);
+  const info = lstatIfPresent(alias);
+  if (info === undefined) {
+    throw new AdoptionError('nothing-to-adopt', `nothing at ${alias}; there is nothing to adopt`);
+  }
+  if (info.isSymbolicLink()) {
+    throw new AdoptionError(
+      'nothing-to-adopt',
+      `${alias} is already an alias symlink. Retarget it with: mosaic auth default --harness ${harness} <bundle>`,
+    );
+  }
+  if (!info.isDirectory()) {
+    throw new AdoptionError(
+      'unsafe-shape',
+      `${alias} is neither a directory nor a symlink; adoption only moves directories`,
+    );
+  }
+
+  const destination = join(root, as);
+  movePreservingBoth(alias, destination, 'bundle');
+  return {
+    harness,
+    bundle: as,
+    from: alias,
+    to: destination,
+    alias: setDefaultBundle(dataHome, harness, as),
+  };
+}
+
+/**
+ * Adopt a real plugin/skill directory out of a seat and into the central store.
+ *
+ * No link is installed. The seat's link manifest belongs to launch, and a link this command
+ * created behind it would fail the next composition as an unrecorded symlink. The next launch
+ * installs and records the link itself when the seat's profile lists the entry -- and when it
+ * does not, the entry is now vetted store content that any seat can be given deliberately,
+ * which is the outcome that was wanted anyway.
+ */
+export function promoteStoreEntry(
+  dataHome: string,
+  agent: string,
+  store: StoreKind,
+  name: string,
+): StorePromotion {
+  assertSafeEntryName(name, store);
+  const profile = readSeatProfile(dataHome, agent);
+  if (profile === undefined) {
+    throw new AdoptionError(
+      'invalid-request',
+      `cannot read a harness out of ${join(agentsRoot(dataHome), agent, 'profile.json')}, so the seat's home cannot be located`,
+    );
+  }
+  const plural = STORE_DIRECTORY[store];
+  const source = join(seatHome(dataHome, agent, profile.harness), plural, name);
+  const info = lstatIfPresent(source);
+  if (info === undefined) {
+    throw new AdoptionError('nothing-to-adopt', `no such ${store} directory: ${source}`);
+  }
+  if (info.isSymbolicLink()) {
+    throw new AdoptionError(
+      'nothing-to-adopt',
+      `${source} is already a link into the store; there is nothing to adopt`,
+    );
+  }
+  if (!info.isDirectory()) {
+    throw new AdoptionError(
+      'unsafe-shape',
+      `${source} is not a directory; adoption only moves directories`,
+    );
+  }
+
+  mkdirSync(join(dataHome, plural), { recursive: true });
+  const destination = join(dataHome, plural, name);
+  movePreservingBoth(source, destination, store);
+  return {
+    agent,
+    store,
+    name,
+    from: source,
+    to: destination,
+    listedInProfile: (store === 'plugin' ? profile.plugins : profile.skills).includes(name),
+  };
+}

packages/mosaic/src/fleet/auth-bundles.spec.ts

@@ -0,0 +1,294 @@
+import { chmodSync, lstatSync, mkdirSync, symlinkSync, writeFileSync } from 'node:fs';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  AuthBundleError,
+  bundleNameForEmail,
+  completeEnrollment,
+  listBundles,
+  prepareEnrollment,
+  readBundleIdentity,
+  setDefaultBundle,
+} from './auth-bundles.js';
+
+let root: string | undefined;
+
+afterEach(async (): Promise<void> => {
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+async function userHome(): Promise<string> {
+  root = await mkdtemp(join(tmpdir(), 'mosaic-auth-'));
+  return join(root, '.mosaic');
+}
+
+describe('prepareEnrollment', () => {
+  it('creates the bundle directory owner-only and names the environment the login needs', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+
+    expect(plan.created).toBe(true);
+    expect(plan.hadCredential).toBe(false);
+    expect(plan.bundleDir).toBe(join(home, 'auth', 'claude', 'jason_woltje.com'));
+    expect(plan.credentialPath).toBe(join(plan.bundleDir, '.credentials.json'));
+    // Claude reaches its bundle by CLAUDE_SECURESTORAGE_CONFIG_DIR because rename() replaces
+    // a symlink rather than following it; the login has to write into the bundle directly.
+    expect(plan.env).toEqual({
+      CLAUDE_CONFIG_DIR: plan.bundleDir,
+      CLAUDE_SECURESTORAGE_CONFIG_DIR: plan.bundleDir,
+    });
+
+    for (const path of [home, join(home, 'auth'), join(home, 'auth', 'claude'), plan.bundleDir]) {
+      expect(lstatSync(path).mode & 0o077).toBe(0);
+    }
+  });
+
+  it('gives a harness without a credential-directory variable only its home variable', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'pi', 'jason_woltje.com');
+
+    expect(plan.credentialPath).toBe(join(plan.bundleDir, 'auth.json'));
+    expect(plan.env).toEqual({ PI_CODING_AGENT_DIR: plan.bundleDir });
+  });
+
+  it('refuses to enrol into the primary alias and says what to do instead', async () => {
+    const home = await userHome();
+    // `primary` is a movable pointer, not storage. Enrolling into it would turn the alias
+    // into a real directory and there would no longer be a default to move.
+    expect(() => prepareEnrollment(home, 'claude', 'primary')).toThrow(
+      /movable alias, not a bundle/u,
+    );
+    expect(() => prepareEnrollment(home, 'claude', 'primary')).toThrow(AuthBundleError);
+  });
+
+  it('refuses a bundle name that could escape the auth root', async () => {
+    const home = await userHome();
+    expect(() => prepareEnrollment(home, 'claude', '../elsewhere')).toThrow(/not a safe bundle/u);
+  });
+
+  it('tightens an existing world-readable bundle directory rather than trusting it', async () => {
+    const home = await userHome();
+    const bundleDir = join(home, 'auth', 'claude', 'loose');
+    mkdirSync(bundleDir, { recursive: true });
+    chmodSync(bundleDir, 0o755);
+
+    const plan = prepareEnrollment(home, 'claude', 'loose');
+
+    expect(plan.created).toBe(false);
+    expect(lstatSync(plan.bundleDir).mode & 0o077).toBe(0);
+  });
+
+  it('reports an existing credential so a re-login is not mistaken for a first enrolment', async () => {
+    const home = await userHome();
+    const first = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+    writeFileSync(first.credentialPath, '{}', { mode: 0o600 });
+
+    expect(prepareEnrollment(home, 'claude', 'jason_woltje.com').hadCredential).toBe(true);
+  });
+});
+
+describe('completeEnrollment', () => {
+  it('fails when the login exited without writing a credential', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+
+    // The directory exists and looks fine; only the credential proves a login happened. Without
+    // this check the failure surfaces much later, at composition, blaming the missing file
+    // rather than the login that never completed.
+    expect(() => completeEnrollment(plan)).toThrow(/login left no credential/u);
+    try {
+      completeEnrollment(plan);
+    } catch (error: unknown) {
+      expect((error as AuthBundleError).code).toBe('credential-missing');
+    }
+  });
+
+  it('tightens a credential the harness wrote with group or other permissions', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+    writeFileSync(plan.credentialPath, '{}');
+    chmodSync(plan.credentialPath, 0o644);
+
+    const result = completeEnrollment(plan);
+
+    expect(result.tightened).toBe(true);
+    expect(lstatSync(plan.credentialPath).mode & 0o077).toBe(0);
+  });
+
+  it('records the logged-in account so the bundle can say who it holds', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+    writeFileSync(plan.credentialPath, '{}', { mode: 0o600 });
+    writeFileSync(
+      join(plan.bundleDir, '.claude.json'),
+      JSON.stringify({ oauthAccount: { emailAddress: '[email protected]' } }),
+    );
+
+    const result = completeEnrollment(plan);
+
+    expect(result.email).toBe('[email protected]');
+    expect(result.identityMismatch).toBeUndefined();
+    const recorded = JSON.parse(
+      await readFile(join(plan.bundleDir, 'account.json'), 'utf8'),
+    ) as Record<string, unknown>;
+    expect(recorded['emailAddress']).toBe('[email protected]');
+    expect(lstatSync(join(plan.bundleDir, 'account.json')).mode & 0o077).toBe(0);
+  });
+
+  it('flags a bundle whose name does not match the account that logged into it', async () => {
+    const home = await userHome();
+    // This is the failure the whole two-principal model rests on. If an operator enrolling a
+    // reviewer bundle logs in as the author's account by habit, both seats end up holding one
+    // principal, the review is self-review, and nothing else in the system notices.
+    const plan = prepareEnrollment(home, 'claude', 'reviewer_example.com');
+    writeFileSync(plan.credentialPath, '{}', { mode: 0o600 });
+    writeFileSync(
+      join(plan.bundleDir, '.claude.json'),
+      JSON.stringify({ oauthAccount: { emailAddress: '[email protected]' } }),
+    );
+
+    const result = completeEnrollment(plan);
+
+    expect(result.email).toBe('[email protected]');
+    expect(result.identityMismatch).toBe('author_example.com');
+  });
+
+  it('enrols a harness whose files carry no identity, without inventing one', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'pi', 'someone_example.com');
+    writeFileSync(plan.credentialPath, JSON.stringify({ token: 'x' }), { mode: 0o600 });
+
+    const result = completeEnrollment(plan);
+
+    expect(result.email).toBeUndefined();
+    expect(result.identityMismatch).toBeUndefined();
+  });
+});
+
+describe('bundleNameForEmail', () => {
+  it('maps an account to its bundle name', () => {
+    expect(bundleNameForEmail('[email protected]')).toBe('jason.woltje_uscllc.com');
+  });
+});
+
+describe('readBundleIdentity', () => {
+  it('prefers the recorded account over whatever the harness left lying around', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+    writeFileSync(join(plan.bundleDir, 'account.json'), JSON.stringify({ emailAddress: '[email protected]' }));
+    writeFileSync(
+      join(plan.bundleDir, '.claude.json'),
+      JSON.stringify({ oauthAccount: { emailAddress: '[email protected]' } }),
+    );
+
+    expect(readBundleIdentity(plan.bundleDir, 'claude')).toBe('[email protected]');
+  });
+
+  it('returns nothing rather than guessing when the files are unreadable', async () => {
+    const home = await userHome();
+    const plan = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+    writeFileSync(join(plan.bundleDir, '.claude.json'), 'not json');
+
+    expect(readBundleIdentity(plan.bundleDir, 'claude')).toBeUndefined();
+  });
+});
+
+describe('listBundles', () => {
+  it('is empty on a host that has never enrolled anything', async () => {
+    expect(listBundles(await userHome(), 'claude')).toEqual([]);
+  });
+
+  it('reports enrolment state, the alias, and which account each bundle holds', async () => {
+    const home = await userHome();
+    const enrolled = prepareEnrollment(home, 'claude', 'jason_woltje.com');
+    writeFileSync(enrolled.credentialPath, '{}', { mode: 0o600 });
+    writeFileSync(
+      join(enrolled.bundleDir, 'account.json'),
+      JSON.stringify({ emailAddress: '[email protected]' }),
+    );
+    prepareEnrollment(home, 'claude', 'empty_example.com');
+    setDefaultBundle(home, 'claude', 'jason_woltje.com');
+
+    const bundles = listBundles(home, 'claude');
+
+    expect(bundles.map((b) => b.name)).toEqual([
+      'empty_example.com',
+      'jason_woltje.com',
+      'primary',
+    ]);
+    expect(bundles.find((b) => b.name === 'jason_woltje.com')).toMatchObject({
+      alias: false,
+      enrolled: true,
+      email: '[email protected]',
+    });
+    expect(bundles.find((b) => b.name === 'empty_example.com')).toMatchObject({
+      alias: false,
+      enrolled: false,
+    });
+    expect(bundles.find((b) => b.name === 'primary')).toMatchObject({
+      alias: true,
+      target: 'jason_woltje.com',
+      enrolled: true,
+    });
+  });
+
+  it('shows a dangling alias instead of failing the whole listing', async () => {
+    const home = await userHome();
+    mkdirSync(join(home, 'auth', 'claude'), { recursive: true });
+    symlinkSync('gone', join(home, 'auth', 'claude', 'primary'));
+
+    expect(listBundles(home, 'claude')).toEqual([
+      {
+        name: 'primary',
+        path: join(home, 'auth', 'claude', 'primary'),
+        resolved: join(home, 'auth', 'claude', 'primary'),
+        alias: true,
+        enrolled: false,
+      },
+    ]);
+  });
+});
+
+describe('setDefaultBundle', () => {
+  it('retargets an existing alias without writing through into the old bundle', async () => {
+    const home = await userHome();
+    for (const name of ['one_example.com', 'two_example.com']) {
+      const plan = prepareEnrollment(home, 'claude', name);
+      writeFileSync(plan.credentialPath, '{}', { mode: 0o600 });
+    }
+    setDefaultBundle(home, 'claude', 'one_example.com');
+    setDefaultBundle(home, 'claude', 'two_example.com');
+
+    expect(listBundles(home, 'claude').find((b) => b.name === 'primary')?.target).toBe(
+      'two_example.com',
+    );
+    // The bundle it used to point at is untouched, not emptied by the retarget.
+    expect(
+      lstatSync(join(home, 'auth', 'claude', 'one_example.com', '.credentials.json')).isFile(),
+    ).toBe(true);
+  });
+
+  it('refuses to point the alias at a bundle that does not exist', async () => {
+    const home = await userHome();
+    mkdirSync(join(home, 'auth', 'claude'), { recursive: true });
+
+    expect(() => setDefaultBundle(home, 'claude', 'missing_example.com')).toThrow(
+      /no such bundle/u,
+    );
+  });
+
+  it('will not delete a real directory that occupies the alias path', async () => {
+    const home = await userHome();
+    prepareEnrollment(home, 'claude', 'real_example.com');
+    mkdirSync(join(home, 'auth', 'claude', 'primary'), { recursive: true });
+
+    // A real `primary` directory means someone enrolled into the alias by hand and their
+    // credentials are inside it. Deleting it to install a symlink would destroy an account.
+    expect(() => setDefaultBundle(home, 'claude', 'real_example.com')).toThrow(
+      /will not be deleted/u,
+    );
+  });
+});

packages/mosaic/src/fleet/auth-bundles.ts

@@ -0,0 +1,415 @@
+/**
+ * Credential bundles under `~/.mosaic/auth/<harness>/<bundle>/`.
+ *
+ * A bundle is one account's credentials for one harness. Seats point at a bundle by name in
+ * their `profile.json`, so two seats can hold genuinely different principals on one host --
+ * which is the whole reason the fleet can run an author seat and a reviewer seat without the
+ * review being self-review wearing two hats.
+ *
+ * Enrolling does not reimplement any harness's login. It creates the bundle directory, points
+ * the harness at it by environment, and runs the harness's own login. What this module owns is
+ * everything around that: that the directory is a real directory nobody can read but its owner,
+ * that the credential actually landed, and that the account you logged in as is the account the
+ * bundle claims to hold.
+ *
+ * Composition-side reader: commands/fleet-launch-command.ts resolveCredential().
+ */
+
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+  type Stats,
+} from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import {
+  CREDENTIAL_DIR_ENV,
+  CREDENTIAL_FILE_NAMES,
+  type CredentialHarness,
+} from './credential-sharing.js';
+
+/** Mirrors BUNDLE_NAME in commands/fleet-launch-command.ts; drift here is a launch failure. */
+const BUNDLE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@-]*$/;
+
+/**
+ * The movable alias. `"bundle": "primary"` in a profile follows whatever this points at; a
+ * named bundle stays pinned. It is the only symlink launch tolerates in an auth root.
+ */
+export const PRIMARY_ALIAS = 'primary';
+
+/** Where each harness expects its own home, so login writes into the bundle we just made. */
+const HOME_ENV_NAME: Record<CredentialHarness, string> = {
+  claude: 'CLAUDE_CONFIG_DIR',
+  pi: 'PI_CODING_AGENT_DIR',
+  codex: 'CODEX_HOME',
+  opencode: 'XDG_CONFIG_HOME',
+};
+
+/**
+ * Files a harness writes that carry the logged-in account's identity, and the paths within
+ * them to try. Best effort by design: a harness we cannot read an identity from still enrolls,
+ * it just cannot be checked against its bundle name.
+ */
+const IDENTITY_SOURCES: Record<CredentialHarness, ReadonlyArray<readonly [string, string[]]>> = {
+  claude: [
+    ['.claude.json', ['oauthAccount.emailAddress', 'oauthAccount.email']],
+    ['.credentials.json', ['claudeAiOauth.emailAddress']],
+  ],
+  pi: [['auth.json', ['account.email', 'email', 'user.email']]],
+  codex: [['auth.json', ['tokens.id_token.email', 'account.email', 'email']]],
+  opencode: [['auth.json', ['account.email', 'email']]],
+};
+
+export type AuthBundleErrorCode =
+  | 'invalid-request'
+  | 'bundle-not-found'
+  | 'bundle-exists'
+  | 'credential-missing'
+  | 'unsafe-shape';
+
+export class AuthBundleError extends Error {
+  readonly code: AuthBundleErrorCode;
+
+  constructor(code: AuthBundleErrorCode, message: string) {
+    super(message);
+    this.name = 'AuthBundleError';
+    this.code = code;
+  }
+}
+
+export interface BundleInfo {
+  readonly name: string;
+  /** Absolute path of the entry as named, before alias resolution. */
+  readonly path: string;
+  /** Where it actually lives. Differs from `path` only for the primary alias. */
+  readonly resolved: string;
+  /** True when this entry is the movable primary alias rather than a real bundle. */
+  readonly alias: boolean;
+  /** Alias target's bundle name, when this is the alias. */
+  readonly target?: string;
+  /** True when the harness's credential file is present in the resolved bundle. */
+  readonly enrolled: boolean;
+  /** Account identity recorded at enrollment, when one could be determined. */
+  readonly email?: string;
+}
+
+export interface EnrollmentPlan {
+  readonly harness: CredentialHarness;
+  readonly bundle: string;
+  readonly bundleDir: string;
+  /** Absolute path the harness must end up writing its credential to. */
+  readonly credentialPath: string;
+  /** True when the directory did not exist before this call. */
+  readonly created: boolean;
+  /** True when a credential was already present -- a re-login, not a first enrollment. */
+  readonly hadCredential: boolean;
+  /**
+   * Environment the harness login must run under. Every value is an absolute path; Claude
+   * reads an empty credential-dir value as ~/.claude, the operator's own account, so an
+   * empty value is never produced here.
+   */
+  readonly env: Readonly<Record<string, string>>;
+}
+
+export interface EnrollmentResult {
+  readonly harness: CredentialHarness;
+  readonly bundle: string;
+  readonly bundleDir: string;
+  readonly credentialPath: string;
+  /** Identity read back out of what the harness wrote, when it could be determined. */
+  readonly email?: string;
+  /**
+   * Set when an identity was found and it does not match the bundle name. Logging into the
+   * wrong account is silent otherwise, and it is the failure that quietly collapses two
+   * principals back into one.
+   */
+  readonly identityMismatch?: string;
+  /** True when the credential file's permissions had to be tightened to owner-only. */
+  readonly tightened: boolean;
+}
+
+function lstatIfPresent(path: string): Stats | undefined {
+  try {
+    return lstatSync(path);
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function assertContained(root: string, candidate: string, label: string): void {
+  const rel = relative(resolve(root), resolve(candidate));
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new AuthBundleError('unsafe-shape', `${label} resolves outside ${root}: ${candidate}`);
+  }
+}
+
+/** Reject a name before it is ever joined onto a path. */
+export function assertSafeBundleName(bundle: string): void {
+  if (!BUNDLE_NAME.test(bundle)) {
+    throw new AuthBundleError(
+      'invalid-request',
+      `"${bundle}" is not a safe bundle name; use letters, digits, and . _ @ -`,
+    );
+  }
+}
+
+/** `~/.mosaic/auth/<harness>`. */
+export function authRoot(userHome: string, harness: CredentialHarness): string {
+  return join(userHome, 'auth', harness);
+}
+
+/**
+ * Create the auth root chain with owner-only permissions, refusing anything that is not a
+ * real directory. An explicit mode on mkdir is not enough on its own -- it is masked by the
+ * ambient umask -- so each level is chmod'ed after creation.
+ */
+function ensurePrivateDirectory(path: string, label: string): boolean {
+  const info = lstatIfPresent(path);
+  if (info) {
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new AuthBundleError(
+        'unsafe-shape',
+        `${label} must be a real, non-symlink directory: ${path}`,
+      );
+    }
+    if ((info.mode & 0o077) !== 0) chmodSync(path, 0o700);
+    return false;
+  }
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  chmodSync(path, 0o700);
+  return true;
+}
+
+function readJson(path: string): Record<string, unknown> | undefined {
+  const info = lstatIfPresent(path);
+  if (!info?.isFile() || info.isSymbolicLink()) return undefined;
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+    return value as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function dig(source: Record<string, unknown>, dotted: string): string | undefined {
+  let cursor: unknown = source;
+  for (const key of dotted.split('.')) {
+    if (typeof cursor !== 'object' || cursor === null || Array.isArray(cursor)) return undefined;
+    cursor = (cursor as Record<string, unknown>)[key];
+  }
+  return typeof cursor === 'string' && cursor.trim() !== '' ? cursor.trim() : undefined;
+}
+
+/** Best-effort account identity from whatever the harness wrote into the bundle. */
+export function readBundleIdentity(
+  bundleDir: string,
+  harness: CredentialHarness,
+): string | undefined {
+  const recorded = readJson(join(bundleDir, 'account.json'));
+  if (recorded) {
+    for (const path of ['emailAddress', 'email', 'oauthAccount.emailAddress']) {
+      const found = dig(recorded, path);
+      if (found) return found;
+    }
+  }
+  for (const [file, paths] of IDENTITY_SOURCES[harness]) {
+    const source = readJson(join(bundleDir, file));
+    if (!source) continue;
+    for (const path of paths) {
+      const found = dig(source, path);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The bundle name an email implies. Bundles are named by account identity so that a roster
+ * row's `"bundle"` says who the seat is, not merely which slot it uses.
+ */
+export function bundleNameForEmail(email: string): string {
+  return email.trim().toLowerCase().replace(/@/gu, '_');
+}
+
+/**
+ * Create the bundle directory and describe the environment its login must run under.
+ *
+ * This deliberately stops short of running anything. The caller runs the harness's own login
+ * under `plan.env`, then calls completeEnrollment() to check what landed.
+ */
+export function prepareEnrollment(
+  userHome: string,
+  harness: CredentialHarness,
+  bundle: string,
+): EnrollmentPlan {
+  assertSafeBundleName(bundle);
+  if (bundle === PRIMARY_ALIAS) {
+    throw new AuthBundleError(
+      'invalid-request',
+      `"${PRIMARY_ALIAS}" is a movable alias, not a bundle. Enroll a bundle named for the account (for example: mosaic auth enroll --harness ${harness} --bundle jason_woltje.com), then point the alias at it with: mosaic auth default --harness ${harness} <bundle>`,
+    );
+  }
+
+  ensurePrivateDirectory(userHome, 'user Mosaic root');
+  ensurePrivateDirectory(join(userHome, 'auth'), 'auth directory');
+  const root = authRoot(userHome, harness);
+  ensurePrivateDirectory(root, `${harness} auth root`);
+
+  const bundleDir = join(root, bundle);
+  assertContained(realpathSync(root), resolve(bundleDir), 'credential bundle');
+  const created = ensurePrivateDirectory(bundleDir, 'credential bundle');
+
+  const credentialPath = join(bundleDir, CREDENTIAL_FILE_NAMES[harness]);
+  const credentialDirEnvName = CREDENTIAL_DIR_ENV[harness];
+  return {
+    harness,
+    bundle,
+    bundleDir,
+    credentialPath,
+    created,
+    hadCredential: lstatIfPresent(credentialPath)?.isFile() === true,
+    env: {
+      [HOME_ENV_NAME[harness]]: bundleDir,
+      ...(credentialDirEnvName === undefined ? {} : { [credentialDirEnvName]: bundleDir }),
+    },
+  };
+}
+
+/**
+ * Check what the harness login actually left behind, tighten it, and record the identity.
+ *
+ * A login that exits zero having written nothing is the failure worth catching here: the seat
+ * would then fail much later, at composition, with a message about a missing credential and no
+ * hint that the login was the thing that did not work.
+ */
+export function completeEnrollment(plan: EnrollmentPlan): EnrollmentResult {
+  const info = lstatIfPresent(plan.credentialPath);
+  if (!info?.isFile() || info.isSymbolicLink()) {
+    throw new AuthBundleError(
+      'credential-missing',
+      `login left no credential at ${plan.credentialPath}. The bundle directory exists but is not enrolled; nothing was assigned.`,
+    );
+  }
+  let tightened = false;
+  if ((info.mode & 0o077) !== 0) {
+    chmodSync(plan.credentialPath, 0o600);
+    tightened = true;
+  }
+
+  const email = readBundleIdentity(plan.bundleDir, plan.harness);
+  if (email !== undefined) {
+    writeFileSync(
+      join(plan.bundleDir, 'account.json'),
+      `${JSON.stringify({ emailAddress: email, harness: plan.harness }, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+    chmodSync(join(plan.bundleDir, 'account.json'), 0o600);
+  }
+
+  const expected = email === undefined ? undefined : bundleNameForEmail(email);
+  return {
+    harness: plan.harness,
+    bundle: plan.bundle,
+    bundleDir: plan.bundleDir,
+    credentialPath: plan.credentialPath,
+    ...(email === undefined ? {} : { email }),
+    ...(expected === undefined || expected === plan.bundle.toLowerCase()
+      ? {}
+      : { identityMismatch: expected }),
+    tightened,
+  };
+}
+
+/** Every entry in a harness's auth root, alias included, with enrollment state. */
+export function listBundles(userHome: string, harness: CredentialHarness): BundleInfo[] {
+  const root = authRoot(userHome, harness);
+  const info = lstatIfPresent(root);
+  if (!info) return [];
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new AuthBundleError(
+      'unsafe-shape',
+      `${harness} auth root must be a real, non-symlink directory: ${root}`,
+    );
+  }
+
+  const entries: BundleInfo[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  )) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const path = join(root, entry.name);
+    let resolved: string;
+    try {
+      resolved = realpathSync(path);
+    } catch {
+      // A dangling alias is real state worth showing rather than a reason to fail the listing.
+      entries.push({ name: entry.name, path, resolved: path, alias: true, enrolled: false });
+      continue;
+    }
+    const alias = entry.isSymbolicLink();
+    const credential = join(resolved, CREDENTIAL_FILE_NAMES[harness]);
+    const email = readBundleIdentity(resolved, harness);
+    entries.push({
+      name: entry.name,
+      path,
+      resolved,
+      alias,
+      ...(alias ? { target: resolved.slice(resolved.lastIndexOf(sep) + 1) } : {}),
+      enrolled: lstatIfPresent(credential)?.isFile() === true,
+      ...(email === undefined ? {} : { email }),
+    });
+  }
+  return entries;
+}
+
+/**
+ * Point the movable `primary` alias at a real bundle.
+ *
+ * Relative so the whole `~/.mosaic` tree stays relocatable, and replaced rather than followed
+ * so retargeting never writes through into the old bundle.
+ */
+export function setDefaultBundle(
+  userHome: string,
+  harness: CredentialHarness,
+  bundle: string,
+): string {
+  assertSafeBundleName(bundle);
+  if (bundle === PRIMARY_ALIAS) {
+    throw new AuthBundleError('invalid-request', `the ${PRIMARY_ALIAS} alias cannot target itself`);
+  }
+  const root = authRoot(userHome, harness);
+  const target = join(root, bundle);
+  const info = lstatIfPresent(target);
+  if (!info) {
+    throw new AuthBundleError(
+      'bundle-not-found',
+      `no such bundle: ${target} — enroll it first: mosaic auth enroll --harness ${harness} --bundle ${bundle}`,
+    );
+  }
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new AuthBundleError(
+      'unsafe-shape',
+      `the ${PRIMARY_ALIAS} alias may only target a real bundle directory: ${target}`,
+    );
+  }
+
+  const alias = join(root, PRIMARY_ALIAS);
+  const existing = lstatIfPresent(alias);
+  if (existing && !existing.isSymbolicLink()) {
+    throw new AuthBundleError(
+      'unsafe-shape',
+      `a real directory occupies the ${PRIMARY_ALIAS} alias path and will not be deleted: ${alias}. Move it aside, or enroll under its own name.`,
+    );
+  }
+  if (existing) rmSync(alias);
+  symlinkSync(bundle, alias);
+  return alias;
+}

packages/mosaic/src/fleet/credential-sharing.ts

@@ -0,0 +1,44 @@
+/**
+ * How each harness reaches the credential stored in its auth bundle.
+ *
+ * Scaffolding and launch both act on this, so it lives in one module: a seat whose
+ * scaffold planted a credential symlink that launch never maintains (or the reverse)
+ * fails in a way that only shows up at the first token refresh.
+ */
+
+/** Mirrors RuntimeName in commands/launch.ts; assignability is asserted there. */
+export type CredentialHarness = 'claude' | 'codex' | 'opencode' | 'pi';
+
+/** Credential file each harness reads, relative to its credential directory. */
+export const CREDENTIAL_FILE_NAMES: Record<CredentialHarness, string> = {
+  claude: '.credentials.json',
+  pi: 'auth.json',
+  codex: 'auth.json',
+  opencode: 'auth.json',
+};
+
+/**
+ * Harnesses that can be pointed at a shared credential directory by environment,
+ * and the variable that does it.
+ *
+ * Claude Code saves credentials by writing a sibling temp file and rename()-ing it
+ * over the target. rename() replaces a symlink rather than following it, so a managed
+ * link at the seat's credential path is destroyed by the first token refresh and the
+ * seat silently forks its credentials. CLAUDE_SECURESTORAGE_CONFIG_DIR resolves the
+ * credential directory independently of CLAUDE_CONFIG_DIR, which keeps both the temp
+ * file and the rename inside the bundle where they belong. Evidence:
+ * docs/reports/harness/claude-credential-write-path-2026-08-14.md (jarvis-brain).
+ *
+ * The value is always an absolute bundle path. Claude reads an empty value as
+ * ~/.claude — the operator's own account — so an empty value must never be exported.
+ *
+ * Harnesses absent from this map keep the managed-link mechanism.
+ */
+export const CREDENTIAL_DIR_ENV: Partial<Record<CredentialHarness, string>> = {
+  claude: 'CLAUDE_SECURESTORAGE_CONFIG_DIR',
+};
+
+/** True when the harness reaches its bundle by environment instead of a seat-local link. */
+export function sharesCredentialDirByEnv(harness: CredentialHarness): boolean {
+  return CREDENTIAL_DIR_ENV[harness] !== undefined;
+}

packages/mosaic/src/fleet/fleet-agent-scaffold.ts

@@ -0,0 +1,346 @@
+import { readFileSync } from 'node:fs';
+import { lstat, mkdir, readFile, readdir, readlink, symlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+
+import { CREDENTIAL_FILE_NAMES, sharesCredentialDirByEnv } from './credential-sharing.js';
+
+export type FleetAgentHarness = 'claude' | 'pi';
+
+export interface FleetAgentScaffoldOptions {
+  readonly dataHome?: string;
+  /** Active installed Mosaic root; supplies the canonical authored runtime base. */
+  readonly mosaicHome?: string;
+  readonly name: string;
+  readonly harness?: string;
+  readonly bundle?: string;
+  readonly model?: string;
+}
+
+export interface FleetAgentScaffoldResult {
+  readonly agentDir: string;
+  readonly profile: Readonly<Record<string, unknown>>;
+  readonly idempotent: boolean;
+  readonly credentialTarget: string;
+  readonly credentialTargetExists: boolean;
+}
+
+export class FleetAgentScaffoldError extends Error {
+  readonly code: 'invalid-request' | 'agent-exists-different';
+
+  constructor(code: FleetAgentScaffoldError['code'], message: string) {
+    super(message);
+    this.name = 'FleetAgentScaffoldError';
+    this.code = code;
+  }
+}
+
+/** User-owned data root, deliberately distinct from the update-owned mosaic home. */
+export function defaultFleetDataHome(): string {
+  return process.env['MOSAIC_DATA_HOME'] ?? join(homedir(), '.mosaic');
+}
+
+/**
+ * Materialize one fleet seat from authored, deterministic template content.
+ * Settings composition intentionally does not happen here: launch owns the
+ * three-layer settings merge and writes the generated settings.json then.
+ */
+export async function scaffoldFleetAgent(
+  options: FleetAgentScaffoldOptions,
+): Promise<FleetAgentScaffoldResult> {
+  const name = requireSafeName(options.name);
+  const harness = requireHarness(options.harness ?? 'claude');
+  const bundle = requireBundle(options.bundle ?? 'primary');
+  const model = optionalNonEmpty(options.model, '--model');
+  const dataHome = resolve(options.dataHome ?? defaultFleetDataHome());
+  const mosaicHome = resolve(options.mosaicHome ?? join(homedir(), '.config', 'mosaic'));
+  const agentDir = join(dataHome, 'fleet', 'agents', name);
+  const homeName = harness === 'claude' ? '.claude' : '.pi';
+  const credentialName = CREDENTIAL_FILE_NAMES[harness];
+  const credentialTarget = join(dataHome, 'auth', harness, bundle, credentialName);
+  const profile: Record<string, unknown> = {
+    schema: 1,
+    harness,
+    bundle,
+    overlay: 'overlay.json',
+    ...(model === undefined ? {} : { model }),
+    env: { MOSAIC_AGENT_NAME: name },
+  };
+  const credentialLink = join(agentDir, homeName, credentialName);
+  const sharesByEnv = sharesCredentialDirByEnv(harness);
+  const entries: [string, ExpectedFile][] = [
+    ['profile.json', { type: 'file', content: json(profile) }],
+    ['SOUL.md', { type: 'file', content: soul(name) }],
+    ['overlay.json', { type: 'file', content: '{}\n' }],
+    [
+      join(homeName, harness === 'claude' ? 'CLAUDE.md' : 'AGENTS.md'),
+      { type: 'file', content: identityBootstrap(name) },
+    ],
+    ...(sharesByEnv
+      ? []
+      : ([[join(homeName, credentialName), { type: 'symlink', target: credentialTarget }]] as [
+          string,
+          ExpectedFile,
+        ][])),
+    [
+      join(homeName, '.mosaic-managed-links.json'),
+      {
+        type: 'file',
+        content: json({ links: sharesByEnv ? {} : { [credentialLink]: credentialTarget } }),
+      },
+    ],
+  ];
+  if (harness === 'claude') {
+    entries.push([
+      join(homeName, '.claude.json'),
+      { type: 'file', content: json(onboardingState(mosaicHome)) },
+    ]);
+  }
+  const files = new Map<string, ExpectedFile>(entries);
+
+  // Seats scaffolded before the harness moved to an environment-shared credential
+  // directory still hold a credential symlink and name it in their manifest. The link
+  // is inert once the harness resolves its credential directory from the environment,
+  // so it is tolerated rather than reported as a foreign file or silently rewritten.
+  const legacyCredentialShape = sharesByEnv
+    ? {
+        path: join(homeName, credentialName),
+        manifestPath: join(homeName, '.mosaic-managed-links.json'),
+        manifestContent: json({ links: { [credentialLink]: credentialTarget } }),
+      }
+    : undefined;
+
+  const differences = await findDifferences(agentDir, files, legacyCredentialShape);
+  if (differences.length > 0) {
+    throw new FleetAgentScaffoldError(
+      'agent-exists-different',
+      `Agent "${name}" already exists with different user-owned file(s): ${differences.join(', ')}. Refusing to overwrite.`,
+    );
+  }
+
+  const idempotent = await pathExists(agentDir);
+  if (!idempotent) {
+    for (const [file, expected] of files) {
+      const path = join(agentDir, file);
+      await mkdir(join(path, '..'), { recursive: true, mode: 0o700 });
+      if (expected.type === 'file') {
+        await writeFile(path, expected.content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      } else {
+        // A dangling link is intentional before enrollment. It makes absent auth
+        // visible at launch instead of silently selecting another account.
+        await symlink(expected.target, path);
+      }
+    }
+  }
+
+  return {
+    agentDir,
+    profile,
+    idempotent,
+    credentialTarget,
+    credentialTargetExists: await pathExists(credentialTarget),
+  };
+}
+
+type ExpectedFile =
+  | { readonly type: 'file'; readonly content: string }
+  | { readonly type: 'symlink'; readonly target: string };
+
+interface LegacyCredentialShape {
+  /** Seat-relative path of the now-unused credential symlink. */
+  readonly path: string;
+  readonly manifestPath: string;
+  /** Manifest content written when that link was still maintained. */
+  readonly manifestContent: string;
+}
+
+async function findDifferences(
+  agentDir: string,
+  expected: ReadonlyMap<string, ExpectedFile>,
+  legacy?: LegacyCredentialShape,
+): Promise<string[]> {
+  let root;
+  try {
+    root = await lstat(agentDir);
+  } catch (error: unknown) {
+    if (isMissing(error)) return [];
+    throw error;
+  }
+  if (!root.isDirectory() || root.isSymbolicLink()) return ['.'];
+
+  const actual = await listRelativeEntries(agentDir);
+  const expectedDirs = new Set<string>();
+  for (const path of expected.keys()) {
+    const parent = relative('.', join(path, '..'));
+    if (parent !== '') expectedDirs.add(parent);
+  }
+  const paths = new Set([
+    ...expected.keys(),
+    ...actual.filter((path: string): boolean => !expectedDirs.has(path)),
+  ]);
+  const differences: string[] = [];
+  for (const path of [...paths].sort()) {
+    if (legacy && path === legacy.path) continue;
+    const required = expected.get(path);
+    if (!required) {
+      differences.push(path);
+      continue;
+    }
+    try {
+      const info = await lstat(join(agentDir, path));
+      if (required.type === 'file') {
+        const content = info.isFile() ? await readFile(join(agentDir, path), 'utf8') : undefined;
+        const acceptable =
+          legacy && path === legacy.manifestPath
+            ? [required.content, legacy.manifestContent]
+            : [required.content];
+        if (
+          !info.isFile() ||
+          info.isSymbolicLink() ||
+          content === undefined ||
+          !acceptable.includes(content)
+        ) {
+          differences.push(path);
+        }
+      } else if (
+        !info.isSymbolicLink() ||
+        (await readlink(join(agentDir, path))) !== required.target
+      ) {
+        differences.push(path);
+      }
+    } catch (error: unknown) {
+      if (isMissing(error)) differences.push(path);
+      else throw error;
+    }
+  }
+  return differences;
+}
+
+async function listRelativeEntries(root: string, prefix = ''): Promise<string[]> {
+  const result: string[] = [];
+  for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
+    const path = join(prefix, entry.name);
+    if (entry.isDirectory() && !entry.isSymbolicLink()) {
+      result.push(path, ...(await listRelativeEntries(root, path)));
+    } else {
+      result.push(path);
+    }
+  }
+  return result;
+}
+
+function requireSafeName(value: string): string {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value === '.' ||
+    value === '..' ||
+    value.includes('/') ||
+    value.includes('\\') ||
+    value.includes('\0') ||
+    isAbsolute(value)
+  ) {
+    throw new FleetAgentScaffoldError(
+      'invalid-request',
+      'Agent name must be one non-empty path component (not absolute or traversal).',
+    );
+  }
+  return value;
+}
+
+function requireHarness(value: string): FleetAgentHarness {
+  if (value === 'claude' || value === 'pi') return value;
+  throw new FleetAgentScaffoldError('invalid-request', '--harness must be claude or pi.');
+}
+
+function requireBundle(value: string): string {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value === '.' ||
+    value === '..' ||
+    value.includes('/') ||
+    value.includes('\\') ||
+    value.includes('\0') ||
+    isAbsolute(value)
+  ) {
+    throw new FleetAgentScaffoldError(
+      'invalid-request',
+      '--bundle must be one non-empty auth-bundle path component.',
+    );
+  }
+  return value;
+}
+
+function optionalNonEmpty(value: string | undefined, option: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (value.length === 0 || value.includes('\0')) {
+    throw new FleetAgentScaffoldError('invalid-request', `${option} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function onboardingState(mosaicHome: string): Record<string, unknown> {
+  const settingsPath = join(mosaicHome, 'runtime', 'claude', 'settings.json');
+  let authored: unknown;
+  try {
+    authored = JSON.parse(readFileSync(settingsPath, 'utf8')) as unknown;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new FleetAgentScaffoldError(
+      'invalid-request',
+      `canonical Claude settings are unavailable or invalid at ${settingsPath}: ${detail}`,
+    );
+  }
+  if (typeof authored !== 'object' || authored === null || Array.isArray(authored)) {
+    throw new FleetAgentScaffoldError(
+      'invalid-request',
+      `canonical Claude settings must be a JSON object: ${settingsPath}`,
+    );
+  }
+  // The shipped settings.json has no mcpServers key at all, so demanding one refused to
+  // scaffold any Claude seat on a clean install. Absent and empty mean the same thing here:
+  // no MCP servers. A present-but-wrong-typed key is still an error -- that is a real
+  // mistake in the file rather than a section the author had nothing to put in.
+  const servers = 'mcpServers' in authored ? authored.mcpServers : {};
+  if (typeof servers !== 'object' || servers === null || Array.isArray(servers)) {
+    throw new FleetAgentScaffoldError(
+      'invalid-request',
+      `canonical Claude settings have a non-object mcpServers: ${settingsPath}`,
+    );
+  }
+  return { hasCompletedOnboarding: true, theme: 'dark', mcpServers: servers };
+}
+
+function soul(name: string): string {
+  return `# SOUL\n\n## Identity\n\nYou are ${name}, a Mosaic fleet agent seat.\n\nRole: _Describe this seat's role._\n`;
+}
+
+/** Identity is materialized by value so restricted harness modes never need to read SOUL.md. */
+function identityBootstrap(name: string): string {
+  return `# Mosaic Fleet Agent Identity\n\nYou are ${name}, a Mosaic fleet agent seat.\n\nYour mechanical identity is ${name} (MOSAIC_AGENT_NAME). Keep this identity when working in repositories with other personas.\n`;
+}
+
+function json(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error: unknown) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+function isMissing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException).code === 'ENOENT';
+}
+
+/** Guardrail kept explicit for callers that construct paths from untrusted text. */
+export function isContainedInFleetDataHome(dataHome: string, path: string): boolean {
+  const rel = relative(resolve(dataHome), resolve(path));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}

packages/mosaic/src/lease-broker/promotion_trigger_unittest.py

@@ -23,6 +23,7 @@ COMPLETE_PATH = TOOLS / "promote-complete.py"
 OBSERVER_CLIENT_PATH = TOOLS / "receipt-observer-client.py"
 RECEIPT_CHALLENGE_PATH = TOOLS / "receipt_challenge.py"
 CLAUDE_SETTINGS = FRAMEWORK / "runtime/claude/settings.json"
+CLAUDE_LEASE_OVERLAY = FRAMEWORK / "runtime/claude/lease-overlay.json"
 CLAUDE_COMMAND = FRAMEWORK / "runtime/claude/commands/mosaic-promote.md"
 SESSION_ID = "a" * 64
 CHALLENGE = "b" * 64
@@ -569,8 +570,15 @@ class PromotionCompleteTest(PromotionHookFixture):
 
 class PromotionTemplateWiringTest(unittest.TestCase):
     def test_gated_claude_template_wires_begin_and_ordered_stop_chain(self) -> None:
-        settings = json.loads(CLAUDE_SETTINGS.read_text(encoding="utf-8"))
+        base = json.loads(CLAUDE_SETTINGS.read_text(encoding="utf-8"))
-        hooks = settings["hooks"]
+        overlay = json.loads(CLAUDE_LEASE_OVERLAY.read_text(encoding="utf-8"))
+        # A launched seat composes base + lease overlay; hook event arrays
+        # concatenate with base entries first, so wiring is asserted against
+        # the composed view rather than either file alone.
+        hooks: dict[str, list] = {}
+        for layer in (base["hooks"], overlay["hooks"]):
+            for event, groups in layer.items():
+                hooks.setdefault(event, []).extend(groups)
         submit_commands = [
             hook["command"]
             for group in hooks["UserPromptSubmit"]

packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts

@@ -6,6 +6,7 @@ import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { afterEach, describe, expect, test } from 'vitest';
 
 import { launchClaudex, type ClaudexHarnessAdapter } from '../commands/claudex.js';
+import { deepMergeSettings } from '../commands/fleet-launch-command.js';
 import {
   observeAndPromoteReceiptChallenge,
   requestBrokerReply,
@@ -42,6 +43,19 @@ const launcherPath = join(frameworkRoot, 'tools/lease-broker/launch-runtime.py')
 const revokerPath = join(frameworkRoot, 'tools/lease-broker/revoke-lease.py');
 const compactionThreatPath = join(repositoryRoot, 'docs/architecture/compaction-revocation.md');
 const claudeSettingsPath = join(frameworkRoot, 'runtime/claude/settings.json');
+const claudeLeaseOverlayPath = join(frameworkRoot, 'runtime/claude/lease-overlay.json');
+
+// The gated seat contract is the COMPOSITION of the ungated base and the
+// lease overlay (gap-7 split); assertions about lease wiring must read that
+// composed view, produced by the same merge the launcher uses.
+async function readGatedClaudeSettings(): Promise<Record<string, unknown>> {
+  const base = JSON.parse(await readFile(claudeSettingsPath, 'utf8')) as Record<string, unknown>;
+  const overlay = JSON.parse(await readFile(claudeLeaseOverlayPath, 'utf8')) as Record<
+    string,
+    unknown
+  >;
+  return deepMergeSettings(base, overlay);
+}
 const piExtensionPath = join(frameworkRoot, 'runtime/pi/mosaic-extension.ts');
 const piLifecyclePath = join(frameworkRoot, 'runtime/pi/lease-lifecycle.ts');
 const prdyInitPath = join(frameworkRoot, 'tools/prdy/prdy-init.sh');
@@ -364,7 +378,7 @@ describe('whole mutator-class lease gate', () => {
     expect(parserResult.status).toBe(0);
     expect(JSON.parse(parserResult.stdout)).toMatchObject({ gated: 0, total: 0 });
 
-    const settings = JSON.parse(await readFile(claudeSettingsPath, 'utf8')) as {
+    const settings = (await readGatedClaudeSettings()) as unknown as {
       hooks: { PreToolUse: Array<{ matcher: string; hooks: Array<{ command: string }> }> };
     };
     const allToolsHook = settings.hooks.PreToolUse.find((hook) => hook.matcher === '.*');
@@ -660,7 +674,7 @@ describe('whole mutator-class lease gate', () => {
   });
 
   test('Claude and Pi compaction observer wiring is complete and fail-closed', async () => {
-    const settings = JSON.parse(await readFile(claudeSettingsPath, 'utf8')) as {
+    const settings = (await readGatedClaudeSettings()) as unknown as {
       hooks: Record<string, Array<{ matcher?: string; hooks: Array<{ command: string }> }>>;
     };
     expect(
@@ -956,7 +970,7 @@ raise SystemExit(0 if len(session_id) == 64 and hook_present and observers_prese
     await promote(socket, sessionId, pending.receipt_challenge!);
     expect(runRuntimeGate(socket, sessionId, 'claude', 'Bash').status).toBe(0);
 
-    const settings = JSON.parse(await readFile(claudeSettingsPath, 'utf8')) as {
+    const settings = (await readGatedClaudeSettings()) as unknown as {
       hooks: { PreToolUse: Array<{ matcher?: string; hooks: Array<{ command: string }> }> };
     };
     expect(

packages/mosaic/src/runtime/claude-settings-base.spec.ts

@@ -0,0 +1,165 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+type JsonObject = { [key: string]: Json };
+
+const frameworkRoot = fileURLToPath(new URL('../../framework/', import.meta.url));
+const basePath = `${frameworkRoot}runtime/claude/settings.json`;
+const overlayPath = `${frameworkRoot}runtime/claude/lease-overlay.json`;
+const gatedFixturePath = fileURLToPath(
+  new URL('./fixtures/claude-settings.gated.pre-split.json', import.meta.url),
+);
+
+function readJson(path: string): JsonObject {
+  return JSON.parse(readFileSync(path, 'utf8')) as JsonObject;
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Production composition uses universal last-layer-wins array replacement. The
+// lease overlay therefore carries complete affected event arrays, including the
+// two QA carry-forward entries needed to avoid dropping non-lease hooks.
+function deepMerge(base: Json, overlay: Json): Json {
+  if (Array.isArray(base) && Array.isArray(overlay)) return overlay;
+  if (isObject(base) && isObject(overlay)) {
+    const merged: JsonObject = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+      merged[key] = key in merged ? deepMerge(merged[key]!, value) : value;
+    }
+    return merged;
+  }
+  return overlay;
+}
+
+function normalize(value: Json): Json {
+  if (Array.isArray(value)) {
+    return value
+      .map(normalize)
+      .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  }
+  if (isObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, normalize(nested)]),
+    );
+  }
+  return value;
+}
+
+function hookCommands(settings: JsonObject): string[] {
+  const hooks = settings['hooks'];
+  if (!isObject(hooks)) return [];
+
+  return Object.values(hooks).flatMap((event) => {
+    if (!Array.isArray(event)) return [];
+    return event.flatMap((entry) => {
+      if (!isObject(entry) || !Array.isArray(entry['hooks'])) return [];
+      return entry['hooks'].flatMap((hook) =>
+        isObject(hook) && typeof hook['command'] === 'string' ? [hook['command']] : [],
+      );
+    });
+  });
+}
+
+const sequentialThinking: JsonObject = {
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+};
+
+describe('canonical Claude base and lease-promotion overlay', () => {
+  it('keeps every lease command out of the ungated base', () => {
+    const base = readJson(basePath);
+    const commands = hookCommands(base);
+
+    for (const marker of ['mutator-gate', 'receipt-observer', 'promote-', 'revoke-lease']) {
+      expect(
+        commands.some((command) => command.includes(marker)),
+        marker,
+      ).toBe(false);
+    }
+  });
+
+  it('reconstructs the pre-split gated hooks while retaining the canonical MCP correction', () => {
+    const base = readJson(basePath);
+    const overlay = readJson(overlayPath);
+    const preSplit = readJson(gatedFixturePath);
+    const expected: JsonObject = {
+      ...preSplit,
+      hooks: {
+        ...(preSplit['hooks'] as JsonObject),
+        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,
+              },
+            ],
+          },
+        ],
+      },
+      mcpServers: { 'sequential-thinking': sequentialThinking },
+    };
+
+    expect(normalize(deepMerge(base, overlay))).toEqual(normalize(expected));
+  });
+
+  it('ships sequential-thinking in the base', () => {
+    const base = readJson(basePath);
+    expect(base['mcpServers']).toEqual({ 'sequential-thinking': sequentialThinking });
+  });
+
+  it('carries six lease commands plus exactly two deliberate QA carry-forward commands', () => {
+    const overlay = readJson(overlayPath);
+    expect(Object.keys(overlay)).toEqual(['hooks']);
+
+    const commands = hookCommands(overlay);
+    const lease = commands.filter((command) =>
+      /mutator-gate|receipt-observer|promote-|revoke-lease/.test(command),
+    );
+    const qa = commands.filter((command) => /prevent-memory-write|reflect-stop/.test(command));
+    expect(lease).toHaveLength(6);
+    expect(qa).toHaveLength(2);
+    expect(commands).toHaveLength(8);
+  });
+
+  it.each(['prevent-memory-write', 'reflect-stop'])(
+    'fails lossless reconstruction if QA carry-forward %s is removed',
+    (marker) => {
+      const base = readJson(basePath);
+      const overlay = readJson(overlayPath);
+      const expected = {
+        ...readJson(gatedFixturePath),
+        mcpServers: { 'sequential-thinking': sequentialThinking },
+      };
+      const hooks = overlay['hooks'] as JsonObject;
+      const mutated: JsonObject = {
+        hooks: Object.fromEntries(
+          Object.entries(hooks).map(([event, entries]) => [
+            event,
+            Array.isArray(entries)
+              ? entries.filter((entry) => !JSON.stringify(entry).includes(marker))
+              : entries,
+          ]),
+        ),
+      };
+      expect(normalize(deepMerge(base, mutated))).not.toEqual(normalize(expected));
+    },
+  );
+});

packages/mosaic/src/runtime/fixtures/claude-settings.gated.pre-split.json

@@ -0,0 +1,319 @@
+{
+  "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"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "^/mosaic-promote$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.config/mosaic/tools/lease-broker/promote-begin.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "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": [
+          {
+            "type": "command",
+            "command": "~/.config/mosaic/tools/qa/prevent-memory-write.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.config/mosaic/tools/qa/qa-hook-stdin.sh",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.config/mosaic/tools/qa/typecheck-hook.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "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
+          },
+          {
+            "type": "command",
+            "command": "~/.config/mosaic/tools/qa/reflect-stop-hook.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {
+    "frontend-design@claude-plugins-official": true,
+    "feature-dev@claude-plugins-official": true,
+    "code-review@claude-plugins-official": true,
+    "pr-review-toolkit@claude-plugins-official": true
+  },
+  "skipDangerousModePermissionPrompt": true,
+  "allowedCommands": [
+    "npm",
+    "npm install",
+    "npm run",
+    "npm test",
+    "npm build",
+    "npm start",
+    "npm run dev",
+    "npm run build",
+    "npm run lint",
+    "npm run typecheck",
+    "npm run test:ci",
+    "npm run test:e2e",
+    "npm run test:unit",
+    "npm run test:integration",
+    "npm run test:cov",
+    "npm run test:security",
+    "npm run security:scan",
+    "npm run security:audit",
+    "npm run performance:benchmark",
+    "npm run build:dev",
+    "npm run build:prod",
+    "npm run test",
+    "npm run test:watch",
+    "npm run migrate",
+    "npm run migrate:rollback",
+    "npm run db:seed",
+    "npm run db:reset",
+    "node",
+    "yarn",
+    "pnpm",
+    "npx",
+    "npx tsc",
+    "npx eslint",
+    "npx prettier",
+    "npx jest",
+    "npx vitest",
+    "git",
+    "git add",
+    "git commit",
+    "git push",
+    "git pull",
+    "git status",
+    "git diff",
+    "git log",
+    "git branch",
+    "git checkout",
+    "git merge",
+    "git init",
+    "git remote",
+    "git fetch",
+    "git reset",
+    "git rebase",
+    "git stash",
+    "git tag",
+    "git show",
+    "git config",
+    "gh",
+    "gh issue",
+    "gh pr",
+    "gh repo",
+    "gh api",
+    "docker",
+    "docker build",
+    "docker run",
+    "docker ps",
+    "docker logs",
+    "docker exec",
+    "docker stop",
+    "docker start",
+    "docker pull",
+    "docker push",
+    "docker-compose",
+    "docker-compose up",
+    "docker-compose down",
+    "docker-compose build",
+    "docker-compose logs",
+    "docker-compose ps",
+    "docker-compose exec",
+    "kubectl",
+    "kubectl get",
+    "kubectl describe",
+    "kubectl logs",
+    "kubectl apply",
+    "kubectl delete",
+    "kubectl port-forward",
+    "mkdir",
+    "touch",
+    "chmod",
+    "chown",
+    "ls",
+    "cd",
+    "pwd",
+    "cp",
+    "mv",
+    "rm",
+    "cat",
+    "echo",
+    "head",
+    "tail",
+    "grep",
+    "grep -E",
+    "grep -r",
+    "find",
+    "find -name",
+    "find -type",
+    "find -path",
+    "find -exec",
+    "find . -type f",
+    "find . -type d",
+    "wc",
+    "sort",
+    "uniq",
+    "curl",
+    "wget",
+    "ping",
+    "netstat",
+    "ss",
+    "lsof",
+    "psql",
+    "pg_dump",
+    "pg_restore",
+    "sqlite3",
+    "jest",
+    "vitest",
+    "playwright",
+    "cypress",
+    "artillery",
+    "lighthouse",
+    "tsc",
+    "eslint",
+    "prettier",
+    "snyk",
+    "semgrep",
+    "tar",
+    "gzip",
+    "unzip",
+    "zip",
+    "which",
+    "whoami",
+    "id",
+    "env",
+    "export",
+    "source",
+    "sleep",
+    "date",
+    "uptime",
+    "df",
+    "du",
+    "free",
+    "top",
+    "htop",
+    "ps",
+    "tree",
+    "jq",
+    "sed",
+    "awk",
+    "xargs",
+    "tee",
+    "test",
+    "true",
+    "false",
+    "basename",
+    "dirname",
+    "realpath",
+    "readlink",
+    "stat",
+    "file",
+    "make",
+    "cmake",
+    "gcc",
+    "g++",
+    "clang",
+    "python",
+    "python3",
+    "pip",
+    "pip3",
+    "pip install",
+    "poetry",
+    "pipenv",
+    "go",
+    "go build",
+    "go test",
+    "go run",
+    "go mod",
+    "cargo",
+    "rustc",
+    "ruby",
+    "gem",
+    "bundle",
+    "rake",
+    "java",
+    "javac",
+    "mvn",
+    "gradle",
+    "dotnet",
+    "msbuild",
+    "php",
+    "composer",
+    "perl",
+    "cpan",
+    "nohup"
+  ],
+  "enableAllMcpTools": true
+}

packages/types/src/chat/events.ts

@@ -6,6 +6,7 @@ import type {
   SlashCommandResultPayload,
   SystemReloadPayload,
 } from '../commands/index.js';
+import type { HarnessErrorCode, HarnessSelection, HarnessTurnState } from '../harness/index.js';
 
 export interface MessageAckPayload {
   conversationId: string;
@@ -107,8 +108,70 @@ export interface AbortPayload {
   conversationId: string;
 }
 
+/**
+ * The frozen P3 `turn:send` wire contract (Task Five; reused unchanged by Tasks 15 and 16).
+ * Accepts no attachments or authority-bearing fields in Slice Zero. Gateway validation
+ * requires a UUID conversation id, non-empty bounded content, a nested selection with exactly
+ * `harnessId`/`providerId`/`modelId` (each 1..255 chars), and a UUID-v4 idempotency key; it
+ * rejects unknown fields, top-level `provider`/`modelId`, malformed nesting, and empty values
+ * before any runtime dispatch.
+ */
+export interface HarnessTurnSendPayload {
+  readonly conversationId: string; // UUID; required before send
+  readonly content: string; // trimmed, 1..10_000 characters
+  readonly selection: HarnessSelection; // nested; exactly three ids
+  readonly idempotencyKey: string; // browser-generated UUID v4
+}
+
+/**
+ * The frozen `turn:ack` wire contract. Success echoes the accepted idempotency key and the
+ * exact requested selection tuple; failure carries only fixed/safe text and never a
+ * substituted effective selection or raw exception text.
+ */
+export type HarnessTurnAckPayload =
+  | {
+      readonly ok: true;
+      readonly conversationId: string;
+      readonly idempotencyKey: string;
+      readonly turnId: string;
+      readonly correlationId: string;
+      readonly state: HarnessTurnState;
+      readonly selection: HarnessSelection;
+    }
+  | {
+      readonly ok: false;
+      readonly conversationId?: string;
+      readonly idempotencyKey?: string;
+      readonly code: HarnessErrorCode | 'request_invalid' | 'runtime_unsupported';
+      readonly message: string; // fixed/safe text only
+      readonly retryable: boolean;
+      readonly correlationId: string;
+      /** Present only when a complete tuple was validated; always the requested tuple. */
+      readonly selection?: HarnessSelection;
+    };
+
+/**
+ * The frozen browser send-protocol advertisement (Task Five; server → client only).
+ *
+ * A conversation id or a harness selection never proves that the connected Gateway actually
+ * handles a given wire event, so after BetterAuth authenticates a browser Socket connection the
+ * Gateway advertises — exactly once, targeted to that socket — which send event the client may
+ * use. `legacy-message` in legacy mode, `unavailable` in `pi-rpc` (including test-ready Pi
+ * graphs); Task Five never advertises `turn-send` (its authenticated handler lands in Task 15).
+ * Capability is routing information, never authorization: every server handler still enforces
+ * authentication, ownership, DTO, mode, and runtime checks.
+ */
+export type ChatSendProtocol = 'legacy-message' | 'turn-send' | 'unavailable';
+
+export interface ChatSendCapabilityPayload {
+  readonly protocol: ChatSendProtocol;
+  /** Exact Socket.IO id for the authenticated browser connection this advertisement is bound to. */
+  readonly connectionId: string;
+}
+
 /** Socket.IO typed event map: server → client */
 export interface ServerToClientEvents {
+  'chat:send-capability': (payload: ChatSendCapabilityPayload) => void;
   'message:ack': (payload: MessageAckPayload) => void;
   'agent:start': (payload: AgentStartPayload) => void;
   'agent:end': (payload: AgentEndPayload) => void;
@@ -121,12 +184,14 @@ export interface ServerToClientEvents {
   'command:result': (payload: SlashCommandResultPayload) => void;
   'command:approval': (payload: SlashCommandApprovalResultPayload) => void;
   'system:reload': (payload: SystemReloadPayload) => void;
+  'turn:ack': (payload: HarnessTurnAckPayload) => void;
   error: (payload: ErrorPayload) => void;
 }
 
 /** Socket.IO typed event map: client → server */
 export interface ClientToServerEvents {
   message: (data: ChatMessagePayload) => void;
+  'turn:send': (data: HarnessTurnSendPayload) => void;
   'set:thinking': (data: SetThinkingPayload) => void;
   'command:execute': (data: SlashCommandPayload) => void;
   'command:approve': (data: SlashCommandPayload) => void;

packages/types/src/chat/index.ts

@@ -14,6 +14,10 @@ export type {
   AbortPayload,
   ErrorPayload,
   ChatMessagePayload,
+  HarnessTurnSendPayload,
+  HarnessTurnAckPayload,
+  ChatSendProtocol,
+  ChatSendCapabilityPayload,
   ServerToClientEvents,
   ClientToServerEvents,
 } from './events.js';