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.
fleet: give one host several accounts per harness, and peg each seat to one
2026-08-14 19:38:41 -05:00 · 2026-08-14 19:23:19 -05:00 · 2026-08-14 19:03:30 -05:00 · 2026-08-14 18:35:11 -05:00 · 2026-08-14 18:20:54 -05:00 · 2026-08-13 15:37:32 -05:00
65 changed files with 13891 additions and 801 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -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,
@@ -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,
@@ -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,
@@ -1,6 +1,8 @@
+import 'reflect-metadata';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import { Test, type TestingModule } from '@nestjs/testing';
 import { describe, expect, it, vi } from 'vitest';

 vi.mock('../agent.service.js', () => ({ AgentService: class AgentService {} }));
@@ -12,10 +14,25 @@ vi.mock('../routing/routing-engine.service.js', () => ({
 }));

 import { SessionsController } from '../sessions.controller.js';
+import { AgentService } from '../agent.service.js';
 import { ChatController } from '../../chat/chat.controller.js';
 import { ChatGateway } from '../../chat/chat.gateway.js';
 import type { AgentSession } from '../agent.service.js';
 import type { SessionInfoDto } from '../session.dto.js';
+import type { HarnessAdapter, HarnessConversationService } from '@mosaicstack/types';
+import { AuthGuard } from '../../auth/auth.guard.js';
+import { AUTH } from '../../auth/auth.tokens.js';
+import { BRAIN } from '../../brain/brain.tokens.js';
+import { CommandRegistryService } from '../../commands/command-registry.service.js';
+import { CommandExecutorService } from '../../commands/command-executor.service.js';
+import { RoutingEngineService } from '../routing/routing-engine.service.js';
+import { ChatRuntimeRouter } from '../../chat/chat-runtime-router.js';
+import { EmbeddedChatRuntime } from '../../chat/embedded-chat.runtime.js';
+import { ownConversation } from '../../chat/chat-runtime.js';
+import type { LegacyRuntimeStream } from '../../chat/chat-runtime.js';
+import { HarnessChatRuntime } from '../../chat/harness-chat.runtime.js';
+import { HarnessRegistry } from '../../harness/harness.registry.js';
+import { HARNESS_CONVERSATION_SERVICE_UNAVAILABLE } from '../../harness/harness.tokens.js';

 const USER_A = { id: 'user-a', tenantId: 'tenant-a' };
 const USER_B = { id: 'user-b', tenantId: 'tenant-b' };
@@ -74,6 +91,12 @@ function makeAgentSession(owner = USER_A): AgentSession {
  };
 }

+/**
+ * A shape-complete, non-throwing AgentService fake scoped so that USER_B (a foreign owner guessing
+ * USER_A's conversation id) is never granted the session. Because every method exists and no method
+ * throws for a wrong shape, production runs to its real ownership decision — the RED never comes from
+ * a `getSession is not a function` TypeError, only from a router-boundary/scope assertion mismatch.
+ */
 function makeScopedAgentService() {
  const foreign = makeAgentSession(USER_A);
  return {
@@ -87,7 +110,7 @@ function makeScopedAgentService() {
    getSession: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
      scope?.userId === USER_B.id ? undefined : foreign,
    ),
-    createSession: vi.fn().mockRejectedValue(new ForbiddenException('Session scope mismatch')),
+    createSession: vi.fn().mockRejectedValue(new NotFoundException('Session scope mismatch')),
    onEvent: vi.fn(() => vi.fn()),
    addChannel: vi.fn(),
    removeChannel: vi.fn(),
@@ -96,6 +119,201 @@ function makeScopedAgentService() {
  };
 }

+type ScopedAgentService = ReturnType<typeof makeScopedAgentService>;
+
+/**
+ * A structurally-complete harness conversation service that throws if any method is invoked.
+ * Fronted behind the legacy runtime's harness slot: the legacy path must never reach it.
+ */
+const failIfUsedConversationService = {
+  attach: () => {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+  detach: () => {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+  send: () => {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+
+  subscribeFrom: async function* () {
+    throw new Error('harness conversation service must not be reached on the legacy path');
+  },
+} as unknown as HarnessConversationService;
+
+/** A structurally-complete, non-sentinel conversation service used to satisfy the pi-rpc readiness gate. */
+const boundConversationService = {
+  attach: () => Promise.reject(new Error('unused')),
+  detach: () => Promise.reject(new Error('unused')),
+  send: () => Promise.reject(new Error('unused')),
+
+  subscribeFrom: async function* () {
+    throw new Error('unused');
+  },
+} as unknown as HarnessConversationService;
+
+function registryWith(adapterIds: readonly string[]): HarnessRegistry {
+  const registry = new HarnessRegistry();
+  for (const id of adapterIds) {
+    registry.register({
+      id,
+      describe: () => Promise.reject(new Error('unused')),
+      catalog: () => Promise.reject(new Error('unused')),
+      create: () => Promise.reject(new Error('unused')),
+      resume: () => Promise.reject(new Error('unused')),
+    } as HarnessAdapter);
+  }
+  return registry;
+}
+
+/**
+ * Build the real legacy-mode {@link ChatRuntimeRouter} fronting a real {@link EmbeddedChatRuntime}
+ * that holds the scoped AgentService fake. This is the ONLY path server-derived scope may travel to
+ * reach an AgentService: controller/gateway → ChatRuntimeRouter → EmbeddedChatRuntime → AgentService.
+ * The `embeddedAgentService` handed here is a SEPARATE instance from the directly-injected fake, so a
+ * call landing on it proves the router-delegation redesign is live rather than the old direct path.
+ */
+function legacyRouterFronting(agentService: unknown): ChatRuntimeRouter {
+  const embedded = new EmbeddedChatRuntime(agentService as never);
+  const harness = new HarnessChatRuntime(failIfUsedConversationService);
+  const router = new ChatRuntimeRouter(
+    new HarnessRegistry(),
+    HARNESS_CONVERSATION_SERVICE_UNAVAILABLE,
+    embedded,
+    harness,
+    'legacy',
+  );
+  router.onModuleInit();
+  return router;
+}
+
+/**
+ * The AgentService method names the controller/gateway must NEVER drive on the runtime at the
+ * delegation boundary. An AgentService-shaped router shim (a method-for-method mirror) would record
+ * one of these instead of the frozen legacy op, so asserting their ABSENCE from the observed runtime
+ * call set defeats the shim on INVOCATION evidence — never satisfiable by dead source text.
+ */
+const FORBIDDEN_AGENT_OPS = [
+  'getSession',
+  'createSession',
+  'onEvent',
+  'addChannel',
+  'prompt',
+  'setThinking',
+  'abort',
+] as const;
+
+/**
+ * Wrap a real {@link ChatRuntimeRouter} in a call-recording Proxy. Every property access that yields
+ * an OWN/inherited callable is returned as a thin wrapper that appends the method name to `calls` at
+ * INVOCATION time and forwards to the real method (bound to the real target, so the router's internal
+ * delegation to the embedded runtime runs untouched below this boundary). Non-function and MISSING
+ * properties are returned verbatim via Reflect.get — the observer NEVER fabricates a value, returns a
+ * canned outcome, or delegates a not-yet-implemented named op, so it cannot itself become a shim.
+ *
+ * The result is a RUNTIME call set of exactly the methods the controller/gateway invoke ON the router
+ * at the delegation seam. Only an actual call can enter it; a dead method, comment, or string in the
+ * production source cannot. This replaces the earlier `source.toContain('<frozen op>')` proof — which
+ * a dead declaration could satisfy while production still executed a shim — with invocation evidence.
+ */
+function makeRecordingRouter(target: ChatRuntimeRouter, calls: string[]): ChatRuntimeRouter {
+  return new Proxy(target, {
+    get(t, prop) {
+      const value = Reflect.get(t, prop);
+      if (typeof value === 'function' && typeof prop === 'string') {
+        return (...args: unknown[]) => {
+          calls.push(prop);
+          return (value as (...a: unknown[]) => unknown).apply(t, args);
+        };
+      }
+      return value;
+    },
+  }) as ChatRuntimeRouter;
+}
+
+/**
+ * Real Nest DI dual-provider fixture (mirrors the blessed group-3 pattern in chat-security.test.ts).
+ *
+ * BOTH an `AgentService` provider (the FORBIDDEN direct dependency) and a `ChatRuntimeRouter` provider
+ * (fronting a real EmbeddedChatRuntime over a SEPARATE scoped AgentService) are registered. Production
+ * resolves whichever its constructor declares:
+ *   - RED today: the controller/gateway `@Inject(AgentService)` → the direct fake is consulted, the
+ *     router (and its embedded fake) is never reached.
+ *   - GREEN later: the controller/gateway inject `ChatRuntimeRouter` → the direct fake is never
+ *     touched (stays at zero) and scope is observed inside the embedded fake behind the router.
+ * The SAME test body reds today and greens later; a method-for-method AgentService shim on the router
+ * records a FORBIDDEN op (and never the frozen legacy op) in the observed runtime call set, and
+ * restoring the direct injection cannot satisfy the "direct fake at zero" / "embedded fake observed
+ * scope" / "frozen op invoked on the router" anchors. The router is wrapped by {@link
+ * makeRecordingRouter} so those anchors are runtime invocation evidence, not source substrings.
+ */
+function buildRestModule(
+  directAgentService: ScopedAgentService,
+  embeddedAgentService: ScopedAgentService,
+  routerCalls: string[],
+): Promise<TestingModule> {
+  return (
+    Test.createTestingModule({
+      controllers: [ChatController],
+      providers: [
+        { provide: AgentService, useValue: directAgentService },
+        {
+          provide: ChatRuntimeRouter,
+          useFactory: () =>
+            makeRecordingRouter(legacyRouterFronting(embeddedAgentService), routerCalls),
+        },
+      ],
+    })
+      // ChatController's @UseGuards(AuthGuard) is resolved during instance loading; AuthGuard injects
+      // AUTH, an HTTP-only concern never exercised by a direct handler call. Stub it so the graph
+      // resolves and the test reds on BEHAVIOUR, not on a DI collection error.
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: () => true })
+      .compile()
+  );
+}
+
+function buildGatewayModule(
+  directAgentService: ScopedAgentService,
+  embeddedAgentService: ScopedAgentService,
+  routerCalls: string[],
+): Promise<TestingModule> {
+  const brain = {
+    conversations: {
+      // The sender OWNS this durable conversation, so the browser-send admission gate lets the turn
+      // reach the router seam. Foreignness is asserted downstream at the in-memory agent session
+      // (getSession({USER_B}) -> undefined), not at durable admission — the admission-rejection
+      // property has its own dedicated coverage.
+      findById: vi.fn().mockResolvedValue({ id: CONVERSATION_ID, userId: USER_B.id }),
+      create: vi.fn().mockResolvedValue(undefined),
+      update: vi.fn().mockResolvedValue(undefined),
+      findMessages: vi.fn().mockResolvedValue([]),
+      addMessage: vi.fn().mockResolvedValue({ id: 'persisted-turn' }),
+    },
+  };
+  return Test.createTestingModule({
+    providers: [
+      ChatGateway,
+      { provide: AgentService, useValue: directAgentService },
+      { provide: AUTH, useValue: { api: { getSession: vi.fn().mockResolvedValue(null) } } },
+      { provide: BRAIN, useValue: brain },
+      { provide: CommandRegistryService, useValue: { getManifest: vi.fn().mockReturnValue([]) } },
+      { provide: CommandExecutorService, useValue: { execute: vi.fn() } },
+      {
+        provide: RoutingEngineService,
+        useValue: {
+          resolve: vi.fn().mockResolvedValue({ provider: 'test', model: 'test-model' }),
+        },
+      },
+      {
+        provide: ChatRuntimeRouter,
+        useFactory: () =>
+          makeRecordingRouter(legacyRouterFronting(embeddedAgentService), routerCalls),
+      },
+    ],
+  }).compile();
+}
+
 describe('TESS-M1-SEC-002 AgentService ownership boundary', () => {
  it('requires explicit owner+tenant scope on protected session operations', () => {
    const source = readFileSync(resolve('src/agent/agent.service.ts'), 'utf8');
@@ -152,50 +370,66 @@ describe('TESS-M1-SEC-002 REST session ownership and tenant binding', () => {
  });
 });

-describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding', () => {
-  it('does not send a prompt into another owner/tenant session by guessed conversationId', async () => {
-    const agentService = makeScopedAgentService();
-    const controller = new ChatController(agentService as never);
+describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding (router-delegated legacy runtime)', () => {
+  // TESS test A — REST /api/chat send. The genuine RED is the router-delegation redesign, not a slot
+  // swap: the forbidden directly-injected AgentService must go UNtouched while the server-derived
+  // scope is observed inside the real ChatRuntimeRouter → EmbeddedChatRuntime → AgentService path.
+  it('routes a REST send through completeLegacyRestTurn and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService(); // FORBIDDEN direct dependency
+    const embeddedAgentService = makeScopedAgentService(); // reached ONLY via router → embedded delegation
+    const routerCalls: string[] = []; // runtime call set observed AT the controller → router seam
+    const moduleRef = await buildRestModule(directAgentService, embeddedAgentService, routerCalls);
+    try {
+      const controller = moduleRef.get(ChatController, { strict: false });

-    await expect(
-      controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
-    ).rejects.toMatchObject({ status: 404 });
+      // Foreign ownership is denied (never resolves) — a control that holds today AND at GREEN.
+      await expect(
+        controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
+      ).rejects.toBeDefined();

-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(agentService.prompt).not.toHaveBeenCalled();
+      // Soft anchors so EVERY anchor is evaluated under each mutation, not just the first to fail.
+
+      // RUNTIME anchor A1 — delegation: the controller must INVOKE the frozen legacy op on the router.
+      // Only an actual call enters routerCalls; a dead method/comment/string cannot. RED today (the
+      // controller @Inject(AgentService) and never calls the router). GREEN once it drives the op.
+      expect
+        .soft(routerCalls, 'controller must invoke completeLegacyRestTurn on the router')
+        .toContain('completeLegacyRestTurn');
+      // RUNTIME anchor A2 — nondelegation: the controller must not drive any AgentService-shaped op on
+      // the router. An AgentService-shaped router shim records one of these → RED, defeating the shim
+      // on invocation evidence (not source text). A dead named method added alongside the shim does not
+      // help: it is never invoked, so it never enters routerCalls while a forbidden op still does.
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      // RUNTIME anchor A3 — the forbidden directly-injected AgentService stays at zero (fails today;
+      // restoring the direct injection keeps it failing).
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      // RUNTIME anchor A4 — server-derived scope observed INSIDE the separate embedded fake behind the
+      // router (fails today; the router path is never taken).
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+
+      // Zero foreign mutation on either path (holds today and at GREEN).
+      expect.soft(directAgentService.prompt).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.prompt).not.toHaveBeenCalled();
+
+      // Defense-in-depth (NOT load-bearing; the runtime anchors above carry the anti-mask): the
+      // controller no longer declares the direct embedded AgentService dependency. A negative source
+      // check cannot be satisfied by dead text — it only fails when the injection is present.
+      const controllerSource = readFileSync(resolve('src/chat/chat.controller.ts'), 'utf8');
+      expect.soft(controllerSource).not.toContain('@Inject(AgentService)');
+    } finally {
+      await moduleRef.close();
+    }
  });
 });

-describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding', () => {
-  function makeGateway(agentService = makeScopedAgentService()) {
-    const brain = {
-      conversations: {
-        findById: vi.fn().mockResolvedValue(undefined),
-        create: vi.fn().mockResolvedValue(undefined),
-        update: vi.fn().mockResolvedValue(undefined),
-        findMessages: vi.fn().mockResolvedValue([]),
-        addMessage: vi.fn().mockResolvedValue(undefined),
-      },
-    };
-    const commandRegistry = { getManifest: vi.fn().mockReturnValue([]) };
-    const commandExecutor = { execute: vi.fn() };
-    const routingEngine = {
-      resolve: vi.fn().mockResolvedValue({ provider: 'test', model: 'test-model' }),
-    };
-    const gateway = new ChatGateway(
-      agentService as never,
-      {} as never,
-      brain as never,
-      commandRegistry as never,
-      commandExecutor as never,
-      routingEngine as never,
-    );
-    return { gateway, agentService };
-  }
-
+describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding (router-delegated legacy runtime)', () => {
  function makeSocket() {
    return {
      id: 'socket-b',
@@ -206,57 +440,519 @@ describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding', () =>
    };
  }

-  it('does not attach or send to another owner/tenant session by guessed conversationId', async () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
+  // TESS test B — WebSocket send/attach.
+  it('routes a WebSocket send through prepareLegacySocketTurn and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService();
+    const embeddedAgentService = makeScopedAgentService();
+    const routerCalls: string[] = [];
+    const moduleRef = await buildGatewayModule(
+      directAgentService,
+      embeddedAgentService,
+      routerCalls,
+    );
+    try {
+      const gateway = moduleRef.get(ChatGateway, { strict: false });
+      const socket = makeSocket();

-    await gateway.handleMessage(socket as never, {
-      conversationId: CONVERSATION_ID,
-      content: 'attach to foreign session',
-    });
+      await Promise.resolve(
+        gateway.handleMessage(socket as never, {
+          conversationId: CONVERSATION_ID,
+          content: 'attach to foreign session',
+        }),
+      ).catch(() => undefined);

-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(agentService.onEvent).not.toHaveBeenCalled();
-    expect(agentService.addChannel).not.toHaveBeenCalled();
+      // RUNTIME anchor B1 — delegation: the gateway must invoke the frozen socket op on the router.
+      expect
+        .soft(routerCalls, 'gateway must invoke prepareLegacySocketTurn on the router')
+        .toContain('prepareLegacySocketTurn');
+      // RUNTIME anchor B2 — nondelegation: no AgentService-shaped op on the router (defeats the shim).
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      // RED anchor B3 — forbidden direct AgentService untouched (fails today, gateway injects it).
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      // RED anchor B4 — scope observed inside router → embedded delegation (fails today, never reached).
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+      // Foreign session gets zero lease/listener/channel/prompt on EITHER path (holds today and GREEN).
+      expect.soft(directAgentService.onEvent).not.toHaveBeenCalled();
+      expect.soft(directAgentService.addChannel).not.toHaveBeenCalled();
+      expect.soft(directAgentService.prompt).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.onEvent).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.addChannel).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.prompt).not.toHaveBeenCalled();
+      expect
+        .soft(socket.emit)
+        .toHaveBeenCalledWith(
+          'error',
+          expect.objectContaining({ conversationId: CONVERSATION_ID }),
+        );
+
+      // Defense-in-depth (NOT load-bearing): gateway no longer declares the direct dependency.
+      const gatewaySource = readFileSync(resolve('src/chat/chat.gateway.ts'), 'utf8');
+      expect.soft(gatewaySource).not.toContain('@Inject(AgentService)');
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  // TESS test C — WebSocket set:thinking.
+  it('routes set:thinking through setLegacyThinking and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService();
+    const embeddedAgentService = makeScopedAgentService();
+    const routerCalls: string[] = [];
+    const moduleRef = await buildGatewayModule(
+      directAgentService,
+      embeddedAgentService,
+      routerCalls,
+    );
+    try {
+      const gateway = moduleRef.get(ChatGateway, { strict: false });
+      const socket = makeSocket();
+
+      await Promise.resolve(
+        gateway.handleSetThinking(socket as never, {
+          conversationId: CONVERSATION_ID,
+          level: 'high',
+        }),
+      ).catch(() => undefined);
+
+      // RUNTIME anchor C1 — delegation: the gateway must invoke the frozen thinking op on the router.
+      expect
+        .soft(routerCalls, 'gateway must invoke setLegacyThinking on the router')
+        .toContain('setLegacyThinking');
+      // RUNTIME anchor C2 — nondelegation: no AgentService-shaped op on the router (defeats the shim).
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+      expect
+        .soft(socket.emit)
+        .toHaveBeenCalledWith(
+          'error',
+          expect.objectContaining({ conversationId: CONVERSATION_ID }),
+        );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  // TESS test D — WebSocket abort.
+  it('routes abort through abortLegacyTurn and never the directly-injected AgentService', async () => {
+    const directAgentService = makeScopedAgentService();
+    const embeddedAgentService = makeScopedAgentService();
+    const routerCalls: string[] = [];
+    const moduleRef = await buildGatewayModule(
+      directAgentService,
+      embeddedAgentService,
+      routerCalls,
+    );
+    try {
+      const gateway = moduleRef.get(ChatGateway, { strict: false });
+      const socket = makeSocket();
+
+      await Promise.resolve(
+        gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID }),
+      ).catch(() => undefined);
+
+      // RUNTIME anchor D1 — delegation: the gateway must invoke the frozen abort op on the router.
+      expect
+        .soft(routerCalls, 'gateway must invoke abortLegacyTurn on the router')
+        .toContain('abortLegacyTurn');
+      // RUNTIME anchor D2 — nondelegation: no AgentService-shaped op on the router (defeats the shim).
+      for (const op of FORBIDDEN_AGENT_OPS) {
+        expect
+          .soft(routerCalls, `router seam must not invoke AgentService.${op}`)
+          .not.toContain(op);
+      }
+      expect.soft(directAgentService.getSession).not.toHaveBeenCalled();
+      expect.soft(embeddedAgentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+        userId: USER_B.id,
+        tenantId: USER_B.tenantId,
+      });
+      expect
+        .soft(socket.emit)
+        .toHaveBeenCalledWith(
+          'error',
+          expect.objectContaining({ conversationId: CONVERSATION_ID }),
+        );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  // TESS test E (genuine, unchanged) — pi-rpc browser-legacy refusal.
+  it('rejects a browser legacy raw message in pi-rpc mode with a fixed typed unsupported and executes nothing', async () => {
+    // pi-rpc: the harness runtime is live. The browser legacy `message` path is unsupported and
+    // must be refused with a fixed typed code, touching neither the embedded AgentService nor the
+    // harness conversation service.
+    const agentService = makeScopedAgentService();
+    const embedded = new EmbeddedChatRuntime(agentService as never);
+    const harnessConversation = {
+      attach: vi.fn(),
+      detach: vi.fn(),
+      send: vi.fn(),
+      subscribeFrom: vi.fn(),
+    };
+    const harness = new HarnessChatRuntime(harnessConversation as never);
+    const router = new ChatRuntimeRouter(
+      registryWith(['pi']),
+      boundConversationService,
+      embedded,
+      harness,
+      'pi-rpc',
+    );
+    router.onModuleInit();
+
+    const brain = {
+      conversations: {
+        findById: vi.fn().mockResolvedValue(undefined),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        findMessages: vi.fn().mockResolvedValue([]),
+        addMessage: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+    const gateway = new ChatGateway(
+      router as never,
+      {} as never,
+      brain as never,
+      { getManifest: vi.fn().mockReturnValue([]) } as never,
+      { execute: vi.fn() } as never,
+      { resolve: vi.fn() } as never,
+    );
+    const socket = {
+      id: 'socket-b',
+      connected: true,
+      data: { user: USER_B, session: { id: 'auth-session-b', userId: USER_B.id } },
+      emit: vi.fn(),
+      disconnect: vi.fn(),
+    };
+
+    await Promise.resolve(
+      gateway.handleMessage(socket as never, {
+        conversationId: CONVERSATION_ID,
+        content: 'route me',
+      }),
+    ).catch(() => undefined);
+
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ code: 'runtime_unsupported' }),
+    );
+    expect(agentService.getSession).not.toHaveBeenCalled();
    expect(agentService.prompt).not.toHaveBeenCalled();
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    expect(harnessConversation.attach).not.toHaveBeenCalled();
+    expect(harnessConversation.send).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Task-5 AMEND — embedded runtime lease lifecycle (G1) + ownership collapse (G5).
+// These drive the real EmbeddedChatRuntime directly over a shape-complete AgentService
+// fake (every touched method exists, so a RED can only come from behavior, never a
+// `getSession is not a function` TypeError). Ownership context is minted through the
+// real `ownConversation` factory — the only sanctioned way to reach a port op.
+// ---------------------------------------------------------------------------
+
+const EMBEDDED_SCOPE = { userId: USER_A.id, tenantId: USER_A.tenantId };
+const CONVERSATION_UNAVAILABLE_RESULT = {
+  ok: false,
+  code: 'conversation_unavailable',
+  retryable: false,
+} as const;
+
+/** A stream sink; `channelId` is server-derived, `onEvent` records nothing here. */
+function makeStream(): LegacyRuntimeStream {
+  return { channelId: 'websocket:test-1', onEvent: vi.fn() };
+}
+
+/**
+ * getSession → undefined (session missing), createSession → rejects with `err`. Exercises the
+ * `resolveOrCreate` collapse branch. `prompt` exists so its ABSENCE from the call record proves
+ * the turn short-circuited before any dispatch.
+ */
+function makeCollapsingAgentService(err: Error) {
+  return {
+    getSession: vi.fn(() => undefined),
+    createSession: vi.fn().mockRejectedValue(err),
+    onEvent: vi.fn(() => vi.fn()),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    prompt: vi.fn().mockResolvedValue(undefined),
+    recordTokenUsage: vi.fn(),
+  };
+}
+
+/** getSession → a live owned session, so `resolveOrCreate` succeeds and a lease is built. */
+function makeLeaseAgentService() {
+  const session = makeAgentSession(USER_A);
+  const unsubscribe = vi.fn();
+  const svc = {
+    getSession: vi.fn(() => session),
+    createSession: vi.fn(),
+    onEvent: vi.fn(() => unsubscribe),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    prompt: vi.fn().mockResolvedValue(undefined),
+    recordTokenUsage: vi.fn(),
+  };
+  return { svc, unsubscribe, session };
+}
+
+/**
+ * getSession → a live owned session (REST resolveOrCreate succeeds), onEvent returns a `detach`
+ * spy, and `prompt` REJECTS with a non-timeout error. Drives the REST-turn catch path so the single
+ * idempotent teardown must clear the 120s timeout and detach the listener exactly once.
+ */
+function makeRejectingPromptAgentService() {
+  const session = makeAgentSession(USER_A);
+  const detach = vi.fn();
+  const svc = {
+    getSession: vi.fn(() => session),
+    createSession: vi.fn(),
+    onEvent: vi.fn(() => detach),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    prompt: vi.fn().mockRejectedValue(new Error('agent backend exploded')),
+    recordTokenUsage: vi.fn(),
+  };
+  return { svc, detach };
+}
+
+describe('TESS Task-5 embedded ownership collapse (missing and foreign are indistinguishable, never throw)', () => {
+  const ctx = ownConversation(CONVERSATION_ID, EMBEDDED_SCOPE);
+
+  it('collapses a foreign (Forbidden) create to conversation_unavailable and never throws', async () => {
+    const svc = makeCollapsingAgentService(new ForbiddenException('foreign owner'));
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const result = await runtime.completeLegacyRestTurn(ctx, { content: 'take over' });
+
+    expect(result).toEqual(CONVERSATION_UNAVAILABLE_RESULT);
+    expect(svc.prompt).not.toHaveBeenCalled();
+  });
+
+  it('collapses a missing (NotFound) create to conversation_unavailable and never throws', async () => {
+    const svc = makeCollapsingAgentService(new NotFoundException('no such conversation'));
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const result = await runtime.completeLegacyRestTurn(ctx, { content: 'hello' });
+
+    expect(result).toEqual(CONVERSATION_UNAVAILABLE_RESULT);
+    expect(svc.prompt).not.toHaveBeenCalled();
+  });
+
+  it('returns the IDENTICAL collapse for foreign and missing so neither can be distinguished', async () => {
+    const foreign = new EmbeddedChatRuntime(
+      makeCollapsingAgentService(new ForbiddenException('foreign owner')) as never,
    );
+    const missing = new EmbeddedChatRuntime(
+      makeCollapsingAgentService(new NotFoundException('no such conversation')) as never,
+    );
+
+    const foreignResult = await foreign.completeLegacyRestTurn(ctx, { content: 'x' });
+    const missingResult = await missing.completeLegacyRestTurn(ctx, { content: 'x' });
+
+    expect(foreignResult).toEqual(missingResult);
+    expect(foreignResult).toEqual(CONVERSATION_UNAVAILABLE_RESULT);
  });
+});
+
+describe('TESS Task-5 embedded socket lease lifecycle (one-shot dispatch, idempotent dispose, partial-setup rollback)', () => {
+  const ctx = ownConversation(CONVERSATION_ID, EMBEDDED_SCOPE);
+
+  it('dispatches the turn exactly once; a second dispatch is a no-op turn_already_dispatched', async () => {
+    const { svc } = makeLeaseAgentService();
+    const runtime = new EmbeddedChatRuntime(svc as never);

-  it('does not mutate thinking level on another owner/tenant session', () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
+    const prepared = await runtime.prepareLegacySocketTurn(ctx, { content: 'first' }, makeStream());
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) throw new Error('prepareLegacySocketTurn should succeed');
+    const lease = prepared.value;

-    gateway.handleSetThinking(socket as never, { conversationId: CONVERSATION_ID, level: 'high' });
+    const first = await lease.dispatch();
+    expect(first).toEqual({ ok: true, value: undefined });
+    expect(svc.prompt).toHaveBeenCalledTimes(1);

-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
+    const second = await lease.dispatch();
+    expect(second).toEqual({ ok: false, code: 'turn_already_dispatched', retryable: false });
+    // Zero additional effect — the second dispatch must not prompt again.
+    expect(svc.prompt).toHaveBeenCalledTimes(1);
+  });
+
+  it('disposes once; a second dispose is a silent no-op that never re-detaches or destroys the session', async () => {
+    const { svc, unsubscribe, session } = makeLeaseAgentService();
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const prepared = await runtime.prepareLegacySocketTurn(ctx, { content: 'x' }, makeStream());
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) throw new Error('prepareLegacySocketTurn should succeed');
+    const lease = prepared.value;
+
+    await lease.dispose();
+    await lease.dispose();
+
+    // Listener + channel torn down exactly once across two dispose calls.
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+    expect(svc.removeChannel).toHaveBeenCalledTimes(1);
+    // Disposal never terminates the underlying session or process.
+    expect(session.piSession.abort).not.toHaveBeenCalled();
+    expect(session.piSession.dispose).not.toHaveBeenCalled();
+  });
+
+  it('rolls back the acquired listener and returns a total safe failure when channel attach fails mid-setup', async () => {
+    const { svc, unsubscribe } = makeLeaseAgentService();
+    svc.addChannel = vi.fn(() => {
+      throw new Error('channel attach failed');
    });
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
-    );
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    // Must NOT throw out of the port — a partial setup collapses to a total safe failure.
+    const prepared = await runtime.prepareLegacySocketTurn(ctx, { content: 'x' }, makeStream());
+    expect(prepared.ok).toBe(false);
+    // Exactly what was acquired (the event listener) is rolled back.
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('TESS Task-5 embedded REST turn teardown (a prompt rejection frees the timer + listener exactly once)', () => {
+  const ctx = ownConversation(CONVERSATION_ID, EMBEDDED_SCOPE);
+
+  it('clears the 120s timeout and detaches the listener exactly once when prompt() rejects, leaving no timer to reject the abandoned done-promise later (Task 5 finding 6)', async () => {
+    const { svc, detach } = makeRejectingPromptAgentService();
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    // A rejected `done` promise firing after completeLegacyRestTurn has already returned would
+    // surface as an unhandledRejection — the leak this test fences. Capture any that escape.
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on('unhandledRejection', onUnhandled);
+    vi.useFakeTimers();
+    try {
+      const result = await runtime.completeLegacyRestTurn(ctx, {
+        content: 'trigger a backend failure',
+      });
+
+      // The rejection collapses to a total safe failure (not a timeout) — never throws out of the port.
+      expect(result).toEqual({ ok: false, code: 'operation_failed', retryable: false });
+      // The single idempotent dispose ran in the catch: listener detached exactly once.
+      expect(detach).toHaveBeenCalledTimes(1);
+
+      // dispose() cleared the REST timeout, so advancing far past it (120s) fires nothing: no second
+      // detach, and — the actual leak — no live timer left to reject the now-abandoned `done` promise.
+      vi.advanceTimersByTime(600_000);
+      expect(detach).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+    // Let any scheduled rejection surface on a real macrotask, then confirm none did.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.off('unhandledRejection', onUnhandled);
+    expect(unhandled).toHaveLength(0);
  });
+
+  it('bounds a hung prompt: when prompt() never settles and no agent_end arrives, the 120s timeout ends the turn with a timeout result and exactly one teardown, no unhandledRejection (Task 5 finding 6 — pending-prompt timeout)', async () => {
+    const session = makeAgentSession(USER_A);
+    const detach = vi.fn();
+    const svc = {
+      getSession: vi.fn(() => session),
+      createSession: vi.fn(),
+      onEvent: vi.fn(() => detach),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      // The prompt never resolves or rejects — a hung agent backend. Under the pre-fix sequential
+      // `await prompt()` the timer could never even be observed, so the turn hung forever.
+      prompt: vi.fn(() => new Promise<void>(() => undefined)),
+      recordTokenUsage: vi.fn(),
+    };
+    const runtime = new EmbeddedChatRuntime(svc as never);

-  it('does not terminate another owner/tenant session over WebSocket abort', async () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on('unhandledRejection', onUnhandled);
+    vi.useFakeTimers();
+    try {
+      const resultPromise = runtime.completeLegacyRestTurn(ctx, {
+        content: 'a prompt that never returns',
+      });
+      // No agent_end, prompt still pending: only the 120s timeout can end the turn. Promise.all
+      // installed a handler on `done` synchronously, so the timer bounds the turn while prompt hangs.
+      await vi.advanceTimersByTimeAsync(200_000);
+      const result = await resultPromise;

-    await gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID });
+      expect(result).toEqual({ ok: false, code: 'timeout', retryable: true });
+      // The single idempotent dispose ran on the timeout path: listener detached exactly once.
+      expect(detach).toHaveBeenCalledTimes(1);
+      // Advancing far past the deadline fires nothing more: dispose cleared the timer.
+      vi.advanceTimersByTime(600_000);
+      expect(detach).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.off('unhandledRejection', onUnhandled);
+    expect(unhandled).toHaveLength(0);
+  });

-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
+  it('when the 120s timeout fires while prompt() is still pending, returns timeout with one teardown, and a later prompt rejection surfaces no unhandledRejection (Task 5 finding 6 — timeout/prompt race)', async () => {
+    const session = makeAgentSession(USER_A);
+    const detach = vi.fn();
+    let rejectPrompt: (reason: unknown) => void = () => undefined;
+    const prompting = new Promise<void>((_resolve, reject) => {
+      rejectPrompt = reject;
    });
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
-    );
+    const svc = {
+      getSession: vi.fn(() => session),
+      createSession: vi.fn(),
+      onEvent: vi.fn(() => detach),
+      addChannel: vi.fn(),
+      removeChannel: vi.fn(),
+      prompt: vi.fn(() => prompting),
+      recordTokenUsage: vi.fn(),
+    };
+    const runtime = new EmbeddedChatRuntime(svc as never);
+
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on('unhandledRejection', onUnhandled);
+    vi.useFakeTimers();
+    try {
+      const resultPromise = runtime.completeLegacyRestTurn(ctx, {
+        content: 'prompt settles after the deadline',
+      });
+      // The timeout wins the race while prompt is still pending.
+      await vi.advanceTimersByTimeAsync(200_000);
+      const result = await resultPromise;
+
+      expect(result).toEqual({ ok: false, code: 'timeout', retryable: true });
+      expect(detach).toHaveBeenCalledTimes(1);
+
+      // The prompt now rejects LATE — after the turn already returned its timeout result. Because
+      // Promise.all installed a rejection handler on `prompting` synchronously (the fix), this late
+      // rejection is already observed and must not escape as an unhandledRejection.
+      rejectPrompt(new Error('late backend failure'));
+    } finally {
+      vi.useRealTimers();
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.off('unhandledRejection', onUnhandled);
+    expect(unhandled).toHaveLength(0);
  });
 });
@@ -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');
+  });
+});
@@ -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);
+  }
+}
@@ -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;
+}
@@ -3,21 +3,20 @@ import {
  Post,
  Body,
  Logger,
-  ForbiddenException,
  HttpException,
  HttpStatus,
  NotFoundException,
-  Inject,
  UseGuards,
 } from '@nestjs/common';
-import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
 import { Throttle } from '@nestjs/throttler';
-import { AgentService } from '../agent/agent.service.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
 import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
 import { v4 as uuid } from 'uuid';
 import { ChatRequestDto } from './chat.dto.js';
+import { ChatRuntimeRouter } from './chat-runtime-router.js';
+import { ownConversation } from './chat-runtime.js';
+import type { LegacyRuntimeFailure } from './chat-runtime.js';

 interface ChatResponse {
  conversationId: string;
@@ -29,7 +28,7 @@ interface ChatResponse {
 export class ChatController {
  private readonly logger = new Logger(ChatController.name);

-  constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
+  constructor(private readonly runtime: ChatRuntimeRouter) {}

  @Post()
  @Throttle({ default: { limit: 10, ttl: 60_000 } })
@@ -40,68 +39,38 @@ export class ChatController {
    const conversationId = body.conversationId ?? uuid();
    const scope = scopeFromUser(user);

-    try {
-      let agentSession = this.agentService.getSession(conversationId, scope);
-      if (!agentSession) {
-        agentSession = await this.agentService.createSession(conversationId, {
-          userId: scope.userId,
-          tenantId: scope.tenantId,
-        });
-      }
-    } catch (err) {
-      if (err instanceof ForbiddenException) {
-        throw new NotFoundException('Session not found');
-      }
-      this.logger.error(
-        `Session creation failed for conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      throw new HttpException('Agent session unavailable', HttpStatus.SERVICE_UNAVAILABLE);
-    }
-
    this.logger.debug(`Handling chat request for user=${user.id}, conversation=${conversationId}`);

-    let responseText = '';
+    // The one exclusive runtime owns execution. In legacy mode this reaches the embedded runtime;
+    // in pi-rpc it fails closed with `runtime_unsupported` before ever touching embedded execution.
+    const result = await this.runtime.completeLegacyRestTurn(
+      ownConversation(conversationId, scope),
+      { content: body.content },
+    );

-    const done = new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        cleanup();
-        this.logger.error(`Agent response timed out after 120s for conversation=${conversationId}`);
-        reject(new Error('Agent response timed out'));
-      }, 120_000);
-
-      const cleanup = this.agentService.onEvent(
-        conversationId,
-        (event: AgentSessionEvent) => {
-          if (
-            event.type === 'message_update' &&
-            event.assistantMessageEvent.type === 'text_delta'
-          ) {
-            responseText += event.assistantMessageEvent.delta;
-          }
-          if (event.type === 'agent_end') {
-            clearTimeout(timer);
-            cleanup();
-            resolve();
-          }
-        },
-        scope,
-      );
-    });
-
-    try {
-      await this.agentService.prompt(conversationId, body.content, scope);
-      await done;
-    } catch (err) {
-      if (err instanceof HttpException) throw err;
-      const message = err instanceof Error ? err.message : String(err);
-      if (message.includes('timed out')) {
-        throw new HttpException('Agent response timed out', HttpStatus.GATEWAY_TIMEOUT);
-      }
-      this.logger.error(`Chat prompt failed for conversation=${conversationId}`, String(err));
-      throw new HttpException('Agent processing failed', HttpStatus.INTERNAL_SERVER_ERROR);
+    if (result.ok) {
+      return { conversationId, text: result.value.text };
    }

-    return { conversationId, text: responseText };
+    throw this.toHttpException(result, conversationId);
+  }
+
+  /** Maps a total {@link LegacyRuntimeFailure} to the fixed browser-safe HTTP surface. */
+  private toHttpException(failure: LegacyRuntimeFailure, conversationId: string): HttpException {
+    switch (failure.code) {
+      case 'conversation_unavailable':
+        return new NotFoundException('Session not found');
+      case 'request_invalid':
+      case 'thinking_level_invalid':
+        return new HttpException('Invalid chat request', HttpStatus.BAD_REQUEST);
+      case 'timeout':
+        return new HttpException('Agent response timed out', HttpStatus.GATEWAY_TIMEOUT);
+      case 'runtime_unsupported':
+      case 'runtime_unavailable':
+        return new HttpException('Agent runtime unavailable', HttpStatus.SERVICE_UNAVAILABLE);
+      default:
+        this.logger.error(`Chat turn failed for conversation=${conversationId}: ${failure.code}`);
+        return new HttpException('Agent processing failed', HttpStatus.INTERNAL_SERVER_ERROR);
+    }
  }
 }
@@ -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;
+}
@@ -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' }),
+    );
+  });
+});
@@ -1,12 +1,59 @@
 import { forwardRef, Module } from '@nestjs/common';
 import { CommandsModule } from '../commands/commands.module.js';
+import { HarnessModule } from '../harness/harness.module.js';
+import { HarnessRegistry } from '../harness/harness.registry.js';
+import {
+  HARNESS_CONVERSATION_SERVICE,
+  HARNESS_REGISTRY,
+  type HarnessConversationServiceBinding,
+} from '../harness/harness.tokens.js';
+import type { HarnessConversationService } from '@mosaicstack/types';
 import { ChatGateway } from './chat.gateway.js';
 import { ChatController } from './chat.controller.js';
+import { ChatRuntimeRouter } from './chat-runtime-router.js';
+import { EmbeddedChatRuntime } from './embedded-chat.runtime.js';
+import { HarnessChatRuntime } from './harness-chat.runtime.js';

+/**
+ * Task Five wiring. The exclusive {@link ChatRuntimeRouter} is the single chat-execution
+ * authority: the controller and gateway inject only the router, never `AgentService`,
+ * `RoutingEngineService`, or a session/`piSession` handle. The router resolves exactly one
+ * runtime at module init — {@link EmbeddedChatRuntime} in legacy mode, {@link HarnessChatRuntime}
+ * in `pi-rpc` — over the REAL {@link HarnessModule} registry and conversation-service binding.
+ *
+ * The router and the harness runtime are constructed through factories because their
+ * dependencies are interface/union types with no runtime injection token (the registry and
+ * conversation-service arrive via the string tokens exported by `HarnessModule`); the embedded
+ * runtime injects the class-typed `AgentService` and is provided directly.
+ */
@Module({
-  imports: [forwardRef(() => CommandsModule)],
+  imports: [forwardRef(() => CommandsModule), HarnessModule],
  controllers: [ChatController],
-  providers: [ChatGateway],
-  exports: [ChatGateway],
+  providers: [
+    ChatGateway,
+    EmbeddedChatRuntime,
+    {
+      provide: HarnessChatRuntime,
+      useFactory: (conversationService: HarnessConversationServiceBinding) =>
+        new HarnessChatRuntime(conversationService as HarnessConversationService),
+      inject: [HARNESS_CONVERSATION_SERVICE],
+    },
+    {
+      provide: ChatRuntimeRouter,
+      useFactory: (
+        registry: HarnessRegistry,
+        conversationService: HarnessConversationServiceBinding,
+        embedded: EmbeddedChatRuntime,
+        harness: HarnessChatRuntime,
+      ) => new ChatRuntimeRouter(registry, conversationService, embedded, harness),
+      inject: [
+        HARNESS_REGISTRY,
+        HARNESS_CONVERSATION_SERVICE,
+        EmbeddedChatRuntime,
+        HarnessChatRuntime,
+      ],
+    },
+  ],
+  exports: [ChatGateway, ChatRuntimeRouter],
 })
 export class ChatModule {}
@@ -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 };
+}
@@ -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 });
+  });
+});
@@ -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);
+  }
+}
@@ -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);
+  });
+});
@@ -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,
@@ -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 {}
@@ -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 {}
@@ -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;
+}
@@ -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', () => {
@@ -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,
@@ -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 });
-    setContent('');
+    // Pass the validated, persisted selection tuple only. The hook derives the
+    // wire projection (legacy `message` provider/model, or `turn:send`) from the
+    // negotiated `chat:send-capability` protocol — never from flat caller input.
+    const selection = harness.persistedSelection;
+    const ok = onSend({ content: trimmed, selection });
+    // Clear the input only when the send was accepted — a refused turn (e.g. a
+    // failed idempotency mint) must retain the user's text so it is not lost.
+    if (ok) setContent('');
  }

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

-  function simulateReconnect(): void {
+  function simulateReconnect(nextId: string = socket.id): void {
    socket.connected = true;
+    socket.id = nextId;
    const lifecycleKey = 'connect' satisfies LifecycleEvent as unknown as ServerEvent;
    for (const handler of listeners.get(lifecycleKey) ?? []) {
      (handler as () => void)();
@@ -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);
+    });
+  });
 });
@@ -12,6 +12,7 @@ import {
 import {
  asConversationId,
  asFiniteNumber,
+  asHarnessSelection,
  asString,
  asStringArray,
  isRecord,
@@ -21,10 +22,14 @@ import type {
  AgentStartPayload,
  AgentTextPayload,
  AgentThinkingPayload,
+  ChatSendCapabilityPayload,
+  ChatSendProtocol,
  CommandDef,
  CommandManifest,
  CommandManifestPayload,
  ErrorPayload,
+  HarnessSelection,
+  HarnessTurnAckPayload,
  MessageAckPayload,
  SessionInfoPayload,
  SessionUsagePayload,
@@ -130,6 +135,42 @@ const CONVERSATION_START_FAILURE = 'Unable to start this conversation. Please tr
 * dropped. */
 const APPROVAL_LIMIT_MESSAGE = 'Approval limit reached for this session. This command was not run.';

+/** Fixed, browser-safe notice surfaced when the harness runtime rejects a turn
+ * (`turn:ack` with `ok:false`). It is deliberately generic: the raw server
+ * `code`/`message`/`error` can carry adapter internals or entropy-source detail,
+ * so no rejection ever leaks its cause into the UI — every distinct rejection
+ * shows this same string. */
+const TURN_REJECTED_NOTICE = 'This turn could not be sent. Please try again.';
+
+/** Fixed, browser-safe notice surfaced when a turn is refused because the
+ * idempotency-key mint failed closed (`crypto.randomUUID` absent or throwing).
+ * Like {@link TURN_REJECTED_NOTICE}, it never carries the thrown message. */
+const IDEMPOTENCY_UNAVAILABLE_NOTICE = 'This turn could not be sent. Please try again.';
+
+/** The single fixed, browser-safe notice surfaced (with safe code
+ * `send_protocol_unavailable`) when a send is attempted on a connection whose
+ * negotiated send protocol is `unavailable` — the server never advertised a
+ * usable `chat:send-capability`, advertised `unavailable` (e.g. a pi-rpc runtime
+ * in this slice), or the advertisement was rejected (wrong connection id, replay,
+ * or an unknown protocol). It carries no dynamic detail. */
+const SEND_PROTOCOL_UNAVAILABLE_NOTICE = 'Chat sending is unavailable on this connection.';
+
+/** Mints a single idempotency key for one accepted `turn:send`, fail-closed.
+ * Returns a fresh RFC-4122 UUID from `crypto.randomUUID`, or `null` when that
+ * source is absent (not a function) or throws — the caller then refuses the turn
+ * rather than falling back to any non-cryptographic source (Math.random, a
+ * clock, or a counter would all be forgeable/collision-prone). Never throws. */
+function mintIdempotencyKey(): string | null {
+  try {
+    const c: unknown = globalThis.crypto;
+    if (!isRecord(c) || typeof c.randomUUID !== 'function') return null;
+    const key = (c.randomUUID as () => unknown)();
+    return typeof key === 'string' && key.length > 0 ? key : null;
+  } catch {
+    return null;
+  }
+}
+
 /** True only for the narrow case a malformed-conversationId `error`/`agent:end`
 * must be treated as a terminal startup failure: no conversation has ever been
 * established yet, and a send is still pending one. Once a conversation is
@@ -236,6 +277,14 @@ export interface PendingApproval {
  args?: string;
 }

+/** Receipt captured from an accepted harness `turn:ack` — the minimal record proving the
+ * server accepted this exact turn under its minted idempotency key and selection tuple. */
+export interface HarnessTurnReceipt {
+  idempotencyKey: string;
+  receiptId: string;
+  selection: HarnessSelection;
+}
+
 export interface ChatConnectionState {
  conversationId: string | null;
  /** True once a message has been sent while no conversation is active yet, so the
@@ -268,6 +317,18 @@ export interface ChatConnectionState {
  approvalRequestPending: boolean;
  systemReload: SystemReloadPayload | null;
  error: string | null;
+  /** How this connection is currently permitted to send, negotiated via the
+   * server-to-client-only `chat:send-capability` advertisement. Starts and resets
+   * to `'unavailable'` on every (re)connect and disconnect — a fresh or dropped
+   * connection has no usable protocol until the server (re-)advertises. This is
+   * the reactive/UI mirror of the synchronous `protocolRef` that `sendMessage`
+   * actually reads; the ref is authoritative because an advertisement and a send
+   * can occur in the same tick before React re-renders. */
+  sendProtocol: ChatSendProtocol;
+  /** Receipt from the most recently accepted harness `turn:ack`, or null before any
+   * turn has been accepted. A rejected turn:ack surfaces via `error` and leaves this
+   * untouched (a prior accepted receipt is not erased by a later rejection). */
+  turnReceipt: HarnessTurnReceipt | null;
  messages: ChatTranscriptMessage[];
  /** Monotonically increasing counter used to mint transcript message ids —
   * never reset while retained messages remain, so ids stay unique across the
@@ -308,7 +369,7 @@ export interface ChatConnectionState {
 }

 export interface ChatConnectionActions {
-  sendMessage: (input: { content: string; provider?: string; modelId?: string }) => void;
+  sendMessage: (input: { content: string; selection?: HarnessSelection }) => boolean;
  abort: () => void;
  setThinking: (level: string) => void;
  executeCommand: (input: { command: string; args?: string }) => void;
@@ -341,6 +402,8 @@ const initialState: ChatConnectionState = {
  approvalRequestPending: false,
  systemReload: null,
  error: null,
+  sendProtocol: 'unavailable',
+  turnReceipt: null,
  messages: [],
  messageSeq: 0,
  toolSeq: 0,
@@ -361,7 +424,12 @@ type Action =
  | { type: 'server/command:approval'; payload: SlashCommandApprovalResultPayload }
  | { type: 'server/system:reload'; payload: SystemReloadPayload }
  | { type: 'server/error'; payload: ErrorPayload }
+  | { type: 'server/turn:ack'; payload: HarnessTurnAckPayload }
  | { type: 'local/send'; content: string }
+  | { type: 'local/capability'; protocol: ChatSendProtocol }
+  | { type: 'local/reset-protocol' }
+  | { type: 'local/send-unavailable' }
+  | { type: 'local/turn-idempotency-unavailable' }
  | { type: 'local/approve-request'; command: string; args?: string }
  | { type: 'local/consume-approval' }
  | { type: 'local/approval-saturated' }
@@ -778,6 +846,30 @@ function reduce(state: ChatConnectionState, action: Action): ChatConnectionState
      };
    }

+    case 'server/turn:ack': {
+      // The harness runtime's turn acknowledgement. The success shape carries a
+      // receipt id + minted idempotencyKey + echoed selection; the failure shape
+      // is discriminated on `ok === false`. Every field is runtime-untrusted (the
+      // top-of-reducer guard already rejected a non-object payload).
+      const record = action.payload as Record<string, unknown>;
+      if (record.ok === false) {
+        // A rejected turn surfaces a FIXED browser-safe notice — never the raw
+        // server `message`/`error`/`code`, which can carry adapter internals — and
+        // does not disturb any previously accepted receipt.
+        return { ...state, error: TURN_REJECTED_NOTICE };
+      }
+      const idempotencyKey = asString(record.idempotencyKey);
+      // The web ack uses `receiptId`; fall back to the frozen contract's `turnId`.
+      const receiptId = asString(record.receiptId) || asString(record.turnId);
+      const selection = asHarnessSelection(record.selection);
+      if (idempotencyKey.length === 0 || receiptId.length === 0 || selection === null) {
+        // A malformed success frame is ignored outright rather than recorded as a
+        // half-populated receipt.
+        return state;
+      }
+      return { ...state, turnReceipt: { idempotencyKey, receiptId, selection } };
+    }
+
    case 'local/send': {
      const message: ChatTranscriptMessage = {
        // Sourced from the reducer-owned `messageSeq` counter — see the
@@ -802,6 +894,39 @@ function reduce(state: ChatConnectionState, action: Action): ChatConnectionState
      };
    }

+    case 'local/capability': {
+      // The FIRST valid `chat:send-capability` for this connection generation has
+      // been accepted (connection-id gating + first-wins enforced in the handler);
+      // record how this connection may now send. This is the reactive mirror of
+      // the synchronous `protocolRef` the send path reads.
+      return { ...state, sendProtocol: action.protocol };
+    }
+
+    case 'local/reset-protocol': {
+      // A (re)connect or disconnect voids any negotiated protocol: a fresh or
+      // dropped connection has no usable send capability until the server
+      // (re-)advertises. Reset to `unavailable` so no stale advertisement can
+      // authorize a send across a connection boundary.
+      if (state.sendProtocol === 'unavailable') return state;
+      return { ...state, sendProtocol: 'unavailable' };
+    }
+
+    case 'local/send-unavailable': {
+      // A send was attempted while the negotiated protocol is `unavailable`
+      // (never advertised / advertised unavailable / rejected advertisement).
+      // Surface the single FIXED safe notice — nothing was emitted, minted,
+      // appended, or locked.
+      return { ...state, error: SEND_PROTOCOL_UNAVAILABLE_NOTICE };
+    }
+
+    case 'local/turn-idempotency-unavailable': {
+      // The idempotency-key mint failed closed (crypto.randomUUID absent or
+      // throwing), so the turn was refused before emit. Surface a FIXED notice —
+      // never the underlying thrown message, which can leak entropy-source
+      // internals.
+      return { ...state, error: IDEMPOTENCY_UNAVAILABLE_NOTICE };
+    }
+
    case 'local/disconnect': {
      // A transient socket disconnect must not leave the UI stuck waiting on
      // a turn/approval/send that will never resolve on this connection.
@@ -882,6 +1007,20 @@ export function useChatConnection(): ChatConnectionValue {
    approveLockRef.current = state.approvalRequestPending;
  }, [state.approvalRequestPending]);

+  // Synchronous, generation-bound send protocol. `state.sendProtocol` drives the
+  // reactive UI, but reducer updates are batched/async — a `chat:send-capability`
+  // advertisement and a `sendMessage` can land in the same tick before React
+  // re-renders — so this ref is the source of truth the send path reads. Unlike
+  // sendLockRef/approveLockRef (synchronized FROM the reducer), this ref is
+  // written directly by the socket lifecycle/capability handlers below, which
+  // also dispatch the reducer mirror. It is NOT synchronized from state, because
+  // its whole purpose is to be correct BEFORE the reducer has re-rendered.
+  const protocolRef = useRef<ChatSendProtocol>('unavailable');
+  // True once the first valid advertisement for the CURRENT connection generation
+  // has been accepted; every later advertisement (a conflicting or replayed one)
+  // is ignored until the next (re)connect/disconnect resets the generation.
+  const protocolLockedRef = useRef(false);
+
  useEffect(() => {
    const socket = getSocket();

@@ -913,7 +1052,45 @@ export function useChatConnection(): ChatConnectionValue {
    const onError = (payload: ErrorPayload): void => {
      dispatch({ type: 'server/error', payload });
    };
+    const onTurnAck = (payload: HarnessTurnAckPayload): void =>
+      dispatch({ type: 'server/turn:ack', payload });
+
+    // Void the negotiated send protocol at every connection-lifecycle boundary.
+    // A fresh or dropped connection has no usable capability until the server
+    // (re-)advertises, so no advertisement bound to a prior connection may carry
+    // across the boundary and authorize a send. Both write the synchronous ref
+    // AND unlock first-wins, then dispatch the reducer mirror.
+    const resetSendProtocol = (): void => {
+      protocolRef.current = 'unavailable';
+      protocolLockedRef.current = false;
+      dispatch({ type: 'local/reset-protocol' });
+    };
+    const onConnect = (): void => {
+      resetSendProtocol();
+    };
+    const onCapability = (payload: ChatSendCapabilityPayload): void => {
+      // Server-to-client-only advertisement of how THIS connection may send.
+      // Accept only the FIRST valid one per generation, and only when it names
+      // this exact connection (`connectionId === socket.id`): a capability minted
+      // for another or stale connection must never arm this one. The payload is
+      // runtime-untrusted despite its compile-time type, so every field is
+      // guard-checked and an unknown protocol is dropped (leaving `unavailable`).
+      if (protocolLockedRef.current) return;
+      if (!isRecord(payload)) return;
+      const { protocol, connectionId } = payload as {
+        protocol?: unknown;
+        connectionId?: unknown;
+      };
+      if (typeof connectionId !== 'string' || connectionId !== socket.id) return;
+      if (protocol !== 'legacy-message' && protocol !== 'turn-send' && protocol !== 'unavailable') {
+        return;
+      }
+      protocolLockedRef.current = true;
+      protocolRef.current = protocol;
+      dispatch({ type: 'local/capability', protocol });
+    };
    const onDisconnect = (): void => {
+      resetSendProtocol();
      dispatch({ type: 'local/disconnect' });
    };

@@ -930,6 +1107,11 @@ export function useChatConnection(): ChatConnectionValue {
    socket.on('command:approval', onCommandApproval);
    socket.on('system:reload', onSystemReload);
    socket.on('error', onError);
+    socket.on('turn:ack', onTurnAck);
+    // Registered BEFORE connect so the initial post-auth advertisement (and any
+    // reconnect) can never race ahead of its listener.
+    socket.on('connect', onConnect);
+    socket.on('chat:send-capability', onCapability);
    socket.on('disconnect', onDisconnect);

    if (!socket.connected) {
@@ -950,24 +1132,79 @@ export function useChatConnection(): ChatConnectionValue {
      socket.off('command:approval', onCommandApproval);
      socket.off('system:reload', onSystemReload);
      socket.off('error', onError);
+      socket.off('turn:ack', onTurnAck);
+      socket.off('connect', onConnect);
+      socket.off('chat:send-capability', onCapability);
      socket.off('disconnect', onDisconnect);
      destroySocket();
    };
  }, []);

  const actions: ChatConnectionActions = {
-    sendMessage: ({ content, provider, modelId }) => {
-      if (sendLockRef.current || state.streaming || state.sending) return;
-      sendLockRef.current = true;
-      const socket = getSocket();
-      if (!socket.connected) socket.connect();
-      dispatch({ type: 'local/send', content });
-      socket.emit('message', {
-        conversationId: state.conversationId ?? undefined,
-        content,
-        provider,
-        modelId,
-      });
+    sendMessage: ({ content, selection }) => {
+      // Routing is PROTOCOL-driven, never inferred from conversation/selection/
+      // provider/local mode: the server advertised, once per connection, exactly
+      // how this connection may send, and that advertisement is authoritative.
+      // The exhaustive switch maps each protocol to its ONE event; the send path
+      // never reconnects the socket (a dropped connection has already reset the
+      // protocol to `unavailable`, so no emit branch is reachable while offline).
+      switch (protocolRef.current) {
+        case 'legacy-message': {
+          // Embedded/legacy runtime: EVERY browser turn — the first (which
+          // creates the conversation) and every later one — is the `message`
+          // event. provider/model are sourced ONLY from the confirmed persisted
+          // selection tuple, never from separate flat caller inputs.
+          if (sendLockRef.current || state.streaming || state.sending) return false;
+          sendLockRef.current = true;
+          const socket = getSocket();
+          dispatch({ type: 'local/send', content });
+          socket.emit('message', {
+            conversationId: state.conversationId ?? undefined,
+            content,
+            provider: selection?.providerId,
+            modelId: selection?.modelId,
+          });
+          return true;
+        }
+        case 'turn-send': {
+          // Pi turn-runtime: the exclusive `turn:send` contract. Requires an
+          // already-established conversation AND a confirmed persisted selection
+          // tuple; it is lock-independent (no send lock, no optimistic append),
+          // and mints exactly one idempotency key per accepted turn, failing the
+          // turn closed if the mint fails. A premature send (no conversation yet,
+          // or no selection) is refused with no emit and no notice.
+          if (selection == null || state.conversationId === null) return false;
+          const idempotencyKey = mintIdempotencyKey();
+          if (idempotencyKey === null) {
+            dispatch({ type: 'local/turn-idempotency-unavailable' });
+            return false;
+          }
+          const socket = getSocket();
+          socket.emit('turn:send', {
+            conversationId: state.conversationId,
+            content,
+            selection,
+            idempotencyKey,
+          });
+          return true;
+        }
+        case 'unavailable': {
+          // No usable protocol negotiated for this connection: refuse without
+          // emitting, minting, appending, or acquiring the lock, and surface the
+          // one fixed safe notice (code `send_protocol_unavailable`).
+          dispatch({ type: 'local/send-unavailable' });
+          return false;
+        }
+        default: {
+          // Exhaustiveness guard: every ChatSendProtocol member is handled above.
+          // An unknown value can never arm a send — refuse exactly as
+          // `unavailable` rather than falling through to any emit.
+          const _exhaustive: never = protocolRef.current;
+          void _exhaustive;
+          dispatch({ type: 'local/send-unavailable' });
+          return false;
+        }
+      }
    },

    abort: () => {
@@ -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 () => {
@@ -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,
  };
 }
@@ -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));

@@ -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
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -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"]
+    }
+  }
 }
@@ -5,6 +5,7 @@ MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 MODE="apply"
 RUNTIME="all"
 STRICT_CHECK=0
+CLAUDE_CONFIG_DIR=""

 PKG="@modelcontextprotocol/server-sequential-thinking"

@@ -29,6 +30,14 @@ while [[ $# -gt 0 ]]; do
      STRICT_CHECK=1
      shift
      ;;
+    --claude-config-dir)
+      if [[ $# -lt 2 ]]; then
+        err "--claude-config-dir requires an absolute seat config directory"
+        exit 2
+      fi
+      CLAUDE_CONFIG_DIR="$2"
+      shift 2
+      ;;
    *)
      err "Unknown argument: $1"
      exit 2
@@ -67,11 +76,19 @@ warm_package() {
 }

 check_claude_config() {
-  python3 - <<'PY'
+  CLAUDE_CONFIG_DIR="$CLAUDE_CONFIG_DIR" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".claude" / "settings.json"
-if not p.exists():
+# Claude reads MCP definitions from .claude.json, not settings.json. The
+# settings.json fallback preserves legacy operator flows until their config is migrated.
+config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
+p = Path(config_dir) / ".claude.json" if config_dir else Path.home() / ".claude.json"
+if not p.exists() and not config_dir:
+    p = Path.home() / ".claude" / "settings.json"
+# Only explicit fleet seats require a private, non-symlink config. Operator
+# config remains compatible with pre-existing permission conventions.
+if not p.exists() or p.is_symlink() or (config_dir and (p.stat().st_mode & 0o077) != 0):
    raise SystemExit(1)
 try:
    data = json.loads(p.read_text(encoding="utf-8"))
@@ -92,10 +109,15 @@ PY
 }

 apply_claude_config() {
-  python3 - <<'PY'
+  CLAUDE_CONFIG_DIR="$CLAUDE_CONFIG_DIR" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".claude" / "settings.json"
+# Claude reads MCP definitions from .claude.json for both operator and
+# explicitly isolated fleet config dirs. The checker retains a settings.json
+# fallback only to avoid breaking legacy operator configurations.
+config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
+p = Path(config_dir) / ".claude.json" if config_dir else Path.home() / ".claude.json"
 p.parent.mkdir(parents=True, exist_ok=True)
 if p.exists():
    try:
@@ -117,7 +139,7 @@ PY
 }

 check_codex_config() {
-  local cfg="$HOME/.codex/config.toml"
+  local cfg="${CODEX_HOME:-$HOME/.codex}/config.toml"
  [[ -f "$cfg" ]] || return 1
  grep -Eq '^\[mcp_servers\.(sequential-thinking|sequential_thinking)\]' "$cfg" && \
  grep -q '^command = "npx"' "$cfg" && \
@@ -125,7 +147,7 @@ check_codex_config() {
 }

 apply_codex_config() {
-  local cfg="$HOME/.codex/config.toml"
+  local cfg="${CODEX_HOME:-$HOME/.codex}/config.toml"
  mkdir -p "$(dirname "$cfg")"
  [[ -f "$cfg" ]] || touch "$cfg"

@@ -148,10 +170,11 @@ apply_codex_config() {
 }

 check_opencode_config() {
-  python3 - <<'PY'
+  XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-}" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".config" / "opencode" / "config.json"
+p = Path(os.environ["XDG_CONFIG_HOME"]) / "opencode" / "config.json" if os.environ.get("XDG_CONFIG_HOME") else Path.home() / ".config" / "opencode" / "config.json"
 if not p.exists():
    raise SystemExit(1)
 try:
@@ -174,10 +197,11 @@ PY
 }

 apply_opencode_config() {
-  python3 - <<'PY'
+  XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-}" python3 - <<'PY'
 import json
+import os
 from pathlib import Path
-p = Path.home() / ".config" / "opencode" / "config.json"
+p = Path(os.environ["XDG_CONFIG_HOME"]) / "opencode" / "config.json" if os.environ.get("XDG_CONFIG_HOME") else Path.home() / ".config" / "opencode" / "config.json"
 p.parent.mkdir(parents=True, exist_ok=True)
 if p.exists():
    try:
@@ -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}}"
-  claude_json="${claude_json:-$HOME/.claude.json}"
+  if [ -z "$claude_json" ]; then
+    claude_json="${MOSAIC_CLAUDE_JSON:-${CLAUDE_CONFIG_DIR:+$CLAUDE_CONFIG_DIR/.claude.json}}"
+    claude_json="${claude_json:-$HOME/.claude.json}"
+  fi
  command -v python3 >/dev/null 2>&1 || return 1
  MOSAIC_CJ="$claude_json" MOSAIC_TRUST_DIR="$resolved" python3 - <<'PY'
 import json, os, sys, tempfile
@@ -325,11 +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

@@ -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'
@@ -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 ──────────────────────────────────────────────────────────

@@ -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;
 }
@@ -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');
+  });
+});
@@ -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);
+        }
+      });
+  }
+}
@@ -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);
+  });
+});
@@ -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`);
+      }
+    });
+}
@@ -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');
+  });
+});
@@ -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');
+      }
+    });
+}
@@ -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);
+  });
+});
@@ -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',
@@ -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);
@@ -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([
@@ -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> */
-function harnessHome(runtime: RuntimeName): string {
-  return join(MOSAIC_HOME, `.${runtime}`);
+/** Dedicated runtime home, optionally scoped to a user fleet agent. */
+export function harnessHome(runtime: RuntimeName, fleet?: FleetHarnessContext): string {
+  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 {
-  const checker = fwScript('mosaic-ensure-sequential-thinking');
+function resolveExecutable(name: string): string {
+  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()) {
-    const ambientClass = canonicalizeRoleClass(process.env['MOSAIC_AGENT_CLASS']).canonicalClass;
+  if (canonicalMember && env['MOSAIC_AGENT_CLASS']?.trim()) {
+    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 {
-  return composeContract(runtime);
+function buildRuntimePrompt(runtime: RuntimeName, env: NodeJS.ProcessEnv = process.env): string {
+  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 {
-  const prompt = buildRuntimePrompt(runtime);
+function ensureRuntimeConfig(
+  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();
-  checkRuntime(runtime);
+  checkSoul(context.fleet);
+  (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);
-      execLeaseGatedRuntime('claude', cliArgs, process.env, yolo);
+      if (context.recordLaunch !== false)
+        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);
-      execRuntime('codex', cliArgs, { ...process.env, ...harnessEnv('codex') });
+      recordLaunch('codex', cliArgs, yolo, context.fleet, launchEnv);
+      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);
-      execRuntime('opencode', args, { ...process.env, ...harnessEnv('opencode') });
+      recordLaunch('opencode', args, yolo, context.fleet, launchEnv);
+      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);
-      execLeaseGatedRuntime('pi', cliArgs);
+      recordLaunch('pi', cliArgs, yolo, context.fleet, launchEnv);
+      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 {
@@ -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,
+    );
+  });
+});
@@ -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),
+  };
+}
@@ -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,
+    );
+  });
+});
@@ -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;
+}
@@ -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;
+}
@@ -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));
+}
@@ -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"))
-        hooks = settings["hooks"]
+        base = json.loads(CLAUDE_SETTINGS.read_text(encoding="utf-8"))
+        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"]
@@ -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(
@@ -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));
+    },
+  );
+});
@@ -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
+}
@@ -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;
@@ -14,6 +14,10 @@ export type {
  AbortPayload,
  ErrorPayload,
  ChatMessagePayload,
+  HarnessTurnSendPayload,
+  HarnessTurnAckPayload,
+  ChatSendProtocol,
+  ChatSendCapabilityPayload,
  ServerToClientEvents,
  ClientToServerEvents,
 } from './events.js';
Author	SHA1	Message	Date
terra	bf6b245f3c	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.	2026-08-14 19:38:41 -05:00
terraandClaude Opus 5	478e925041	fleet: give one host several accounts per harness, and peg each seat to one `mosaic auth enroll \| assign \| list \| default` (W-F5). Until now a host had one account per harness, so an author seat and a reviewer seat were the same principal wearing two names, and a review carried out under that arrangement is self-review. Bundles under ~/.mosaic/auth/<harness>/<bundle>/ are what a seat's profile.json points at, so two seats on one host can hold genuinely different accounts. Enroll does not reimplement any harness's login. It creates the bundle directory owner-only, points the harness's own home at it by environment, runs the harness, and then checks what landed: credential present, permissions tightened, and the account recorded. Claude is reached through CLAUDE_SECURESTORAGE_CONFIG_DIR rather than a symlink because it writes by rename(2), which replaces a symlink instead of following it. --no-login prints the environment for an operator who would rather run the login themselves. The check worth naming is identity: enroll reads the account back out of what the harness wrote and refuses quietly to accept a bundle named for one account that holds another. That mistake is otherwise silent -- an operator enrolling the reviewer bundle logs in out of habit as the author, both seats collapse to one principal, and nothing else in the system notices. Assign re-parses a seat's profile before rewriting its bundle, so an already broken profile is reported here rather than re-serialized into something that looks repaired and still fails at launch. An unenrolled bundle is assigned but said out loud, because the seat will refuse to launch until the account exists. registerAuthCommand now returns its Command so these local verbs can hang off it. They never talk to the gateway and work on a host where it is down. 41 tests. Each of the load-bearing checks was mutation-tested: nine mutations, each killing exactly the one test that covers it. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1	2026-08-14 19:23:19 -05:00
terraandClaude Opus 5	309a99a600	fleet: fix four defects that made no seat launchable on a clean install Found by rehearsing the full install on a greenfield Debian 13 VM (mosaic-sbx-dev) rather than on a host that already had a working Mosaic tree. Each one is invisible on a developer machine and fatal on a new host. 1. Required system settings layer. The framework ships runtime/<harness>/ for claude, codex, opencode and pi but a settings.json only for claude, so requiring the file made every pi, codex and opencode seat refuse to compose. The system layer is now optional; what must exist is the harness runtime directory, which is the thing that actually proves the framework is installed and carries that harness. 2. Required mcpServers in canonical Claude settings. The shipped settings.json has no such key, so `fleet agent new` refused to scaffold any Claude seat. Absent now means the same as empty. A present but wrong-typed value is still an error. 3. Never-enrolled hosts were told their auth directory "must be a real, non-symlink directory", which reads as a tampering report when the real situation is that nobody has logged in yet. Absent and wrong-shaped are now separate messages, and the absent one names `mosaic auth enroll`. 4. A fleet seat whose host had no system SOUL.md reached checkSoul(), which spawns the interactive `mosaic wizard` with inherited stdio. On a detached tmux seat that parks the pane on a menu with nobody at it: the session is live, the systemd unit reports fine, and no agent ever starts. A seat's identity is its own SOUL.md, written by `fleet agent new`, so the fleet path checks that and fails loudly instead. Each fix has a regression test verified red against the unfixed source. The launch.spec.ts seat fixtures gained a SOUL.md they always should have had -- without it those tests were satisfied by whatever SOUL.md the developer's real ~/.config/mosaic happened to contain. Full suite before and after: the same 5 pre-existing failures in mutator-gate.acceptance.spec.ts and install-ordering-guard.spec.ts, 1585 -> 1591 passing. typecheck and eslint clean. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1	2026-08-14 19:03:30 -05:00
terra	c1a42cdb81	fleet: start a roster pane through its seat when one is scaffolded The roster lane and the harness-homes lane did not touch. start-agent-session.sh ran `mosaic yolo "$RUNTIME"` with HOME set to the operator's home, so every fleet seat on a host shared the operator's harness home and, for Claude, the operator's own ~/.claude credentials. Nothing in framework/ called `mosaic fleet launch` at all, which meant ~/.mosaic was a directory nothing read. The pane now runs `mosaic fleet launch "$AGENT_NAME"` when a scaffolded seat exists at $PANE_HOME/.mosaic/fleet/agents/<name>/profile.json, and the historical command otherwise. Detection uses $PANE_HOME/.mosaic rather than MOSAIC_DATA_HOME because the pane environment is cleared with env -i; the composition resolves the same root from HOME, so the two cannot disagree. Additive by construction: a host with no scaffolded seats launches exactly as before, so this can land ahead of any seat being enrolled. - fleet launch gains --dangerous, threaded to launchFleetRuntime. Without it a seat launched from the roster would drop the permissions footing `mosaic yolo` gave it and prompt at a pane with nobody at it. The roster launcher asks for it explicitly so it stays visible in the process table instead of becoming a profile default. - A caller's --model replaces the profile's instead of being appended after it. The roster carries a model per seat and is the surface operators edit; emitting both flags would leave the choice to each harness's argument parser. - Claude workdir trust is written into the seat's .claude.json when the pane will run in a seat home. It previously always went to the operator's ~/.claude.json, which would leave the seat prompting on its first turn. Covers Jason's scope amendment for web1: without this seam, "multiple authentication accounts and agent pegging to auth" cannot be demonstrated on a roster-managed seat.	2026-08-14 18:35:11 -05:00
terra	a12eeb4786	fleet: share Claude credentials by directory env, not a seat symlink Claude Code saves credentials by writing a sibling temp file and rename()-ing it over the target. rename(2) replaces a symlink rather than following it, so the managed link W-F1/W-F2 planted at <seat>/.claude/.credentials.json is destroyed by the first token refresh and the seat silently forks its credentials. The in-place fallback arm opens with O_NOFOLLOW and would refuse the link anyway. Evidence, quoting the 2.1.232 binary: docs/reports/harness/claude-credential-write-path-2026-08-14.md (jarvis-brain). CLAUDE_SECURESTORAGE_CONFIG_DIR resolves the credential directory independently of CLAUDE_CONFIG_DIR, so the temp file and the rename both land inside the bundle. That is the property the design wanted -- share the credential, never the transcripts -- with no symlink and no privileges. - new fleet/credential-sharing.ts owns the harness -> credential-file and harness -> credential-directory-variable maps, so scaffold and launch cannot disagree about the mechanism. It also removes the duplicate credential-file name table the two already carried. - launch composes CLAUDE_SECURESTORAGE_CONFIG_DIR from the resolved bundle directory and plans no credential link for Claude. The value is always the absolute bundle path: Claude reads an empty value as ~/.claude, which is the operator's own account. - scaffold stops emitting the credential symlink and its manifest entry for Claude, and tolerates one left by an earlier scaffold rather than reporting it as a foreign file or rewriting it. - FIRST_AUTH_REFUSAL still fires when a real file occupies the seat path. - Harnesses absent from the map (pi, codex, opencode) keep managed links; the containment specs now exercise them on pi. Answers promotion gate #1 negatively for the frozen mechanism and positively for the replacement. E3.3 (two seats refreshing one bundle at once) is still open.	2026-08-14 18:20:54 -05:00
terra	326a1a58b5	fix(fleet): harden managed launch composition AMD1213-C: repair stale array consumer, fail closed on foreign link provenance, validate manifests before mutation, and exercise the fleet MCP preflight call path.	2026-08-13 15:37:32 -05:00
terra	2755f86f7b	fix(fleet): seed seat MCP preflight config AMD1213-B5: derive Claude seat MCP configuration from the active installed runtime base and inspect the isolated seat during fleet launch.	2026-08-13 14:38:25 -05:00
terra	fe2cf19461	fix(fleet): preserve managed link provenance AMD1213-B3: record Mosaic-owned links and refuse foreign or retargeted symlink mutations. Out-of-scope review follow-up: settings output/snapshot apply-time TOCTOU remains reported, not patched.	2026-08-13 14:38:25 -05:00
terra	4fde3f622d	fix(fleet): contain credential trust roots AMD1213-B4: reject symlinked auth ancestry and group/world-readable credential artifacts before composition can write.	2026-08-13 14:38:25 -05:00
terra	9de9ffa56b	fix(lease): restore uniform settings array replacement AMD1213-B1: preserve the gated Claude hook composition explicitly in the lease overlay while restoring last-layer-wins arrays and null tombstones.	2026-08-13 14:38:19 -05:00
Jason Woltje	cb960237d3	test(lease): assert promotion wiring against composed base+overlay template ci/woodpecker/pr/ci Pipeline was successful Details The lease-overlay split (`a42d5e2e`) moved the promotion hooks out of the base Claude settings template; the wiring test still read the base alone and failed on the absent UserPromptSubmit event, stopping the whole test:framework-shell chain. The test now composes base + lease overlay the way a launched seat does (hook event arrays concatenate, base first) and asserts the same wiring contract against that view. Reported-by: goals (clean-head probe on `5e154310`)	2026-08-13 12:17:10 -05:00
Jason WoltjeandClaude Fable 5	5e15431027	fix(fleet): tolerate harness metadata files in the managed install root ci/woodpecker/pr/ci Pipeline was canceled Details Claude Code writes installed_plugins.json and other metadata files into the seat's plugins directory during a session, so refusing every real entry made composition fail on each seat's second launch. Only a real directory is an unmanaged entry the pruner would orphan; plain files are harness state and pass through untouched. Found by the in-box hour-gate relaunch of the probe seat. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh	2026-08-13 11:59:31 -05:00
Jason WoltjeandClaude Fable 5	c16256d48c	fix(fleet): compose system settings from the installed flattened home layout The installed ~/.config/mosaic home flattens the repo's packages/mosaic/framework/ prefix: the real file is <home>/runtime/<harness>/settings.json, exactly as launch.ts already resolves it everywhere. The fleet launch composition leaked the repo layout (framework/runtime/...) into the system layer path, so a real installed home failed with COMPOSITION_FAILED while the temp-fixture specs (which mirrored the same wrong prefix) stayed green. Found by the in-box hour-gate dry-run against the installed mos-dev-stage home. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh	2026-08-13 11:52:00 -05:00
Jason WoltjeandClaude Fable 5	92e790ae9d	fix(fleet): additive hook-event merge and gated-composition acceptance reads Integration adjudication (fred, W-F1): the general arrays-replace merge rule conflicts with the gap-7 base/overlay split — base and lease overlay share the PreToolUse and Stop events, so replace semantics would silently drop the base QA hooks from every gated seat. Ruling: hook event arrays directly under the top-level hooks key concatenate (base first); all other arrays keep replace semantics; null tombstones still delete an event. - mutator-gate acceptance now asserts lease wiring against the COMPOSED gated settings (base + lease-overlay via the launcher's own merge), matching the post-split contract. - fleet subcommand canary gains the intended new 'agent' surface from T3. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh	2026-08-13 11:44:58 -05:00
Jason WoltjeandClaude Fable 5	0fdcfa0ff4	fix(fleet): unify user data-home seam and add actionable unscaffolded-agent error Integration reconciliation of T2/T3 seams on feat/wf-fleet-mvp: - fleet launch now resolves the user root through defaultFleetDataHome() (MOSAIC_DATA_HOME), the same seam fleet agent new uses, instead of a divergent MOSAIC_USER_HOME variable. - Launching an unscaffolded name raises AGENT_NOT_SCAFFOLDED with the actionable message pointing at 'mosaic fleet agent new <name>' (acceptance carried over from the T3 card after the roster-v2 reconciliation moved it onto the launch path). Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh	2026-08-13 11:39:44 -05:00
Jason Woltje	4e2f9888a0	Merge branch 'feat/wf-fleet-t2-launch' into feat/wf-fleet-mvp	2026-08-13 11:36:32 -05:00
Jason Woltje	9a92bb64ff	Merge branch 'feat/wf-fleet-t3-scaffold' into feat/wf-fleet-mvp	2026-08-13 11:36:32 -05:00
Jason Woltje	fe26b37e81	Merge branch 'feat/wf-fleet-t1-base' into feat/wf-fleet-mvp	2026-08-13 11:36:32 -05:00
Jason Woltje	378c227cbb	feat(fleet): compose and launch profile-backed seats	2026-08-13 11:30:53 -05:00
Jason Woltje	4522adaa5e	feat(fleet): scaffold user-owned agent homes	2026-08-13 11:25:25 -05:00
Jason Woltje	a42d5e2ee5	feat(mosaic): split Claude lease overlay from base	2026-08-13 11:21:51 -05:00
shaggyandmos-dt-0	216cd72226	refactor(chat): route browser chat through one runtime (P3 Slice-Zero Task 5) (#1172 ) ci/woodpecker/push/publish Pipeline failed Details Co-authored-by: shaggy <[email protected]>	2026-08-12 20:11:12 +00:00