docs: close installation and control-link gates

Co-authored-by: shaggy <[email protected]>

.env.example

@@ -149,6 +149,5 @@ OTEL_SERVICE_NAME=mosaic-gateway
 # KEYCLOAK_CLIENT_ID=mosaic
 # KEYCLOAK_CLIENT_SECRET=
 
-# Feature flags — set to true alongside provider credentials to show SSO buttons in the UI
-# NEXT_PUBLIC_WORKOS_ENABLED=true
-# NEXT_PUBLIC_KEYCLOAK_ENABLED=true
+# The web login page discovers configured providers dynamically from
+# GET /api/sso/providers. No NEXT_PUBLIC_* provider feature flag is required.

.gitignore

@@ -9,7 +9,7 @@ coverage
 *.tsbuildinfo
 .pnpm-store
 __pycache__/
-docs/reports/
+docs/.obsidian
 
 # Step-CA dev password — real file is gitignored; commit only the .example
 infra/step-ca/dev-password

.woodpecker/ci.yml

@@ -109,6 +109,16 @@ steps:
       # `apk add` guarantees openssl is present on PR pipelines too (and is a
       # fast no-op once the rebuilt image already ships it).
       - apk add --no-cache openssl
+      # Pi runtime (Invariant R): invariant_r_unittest.py hard-requires an
+      # installed `pi` binary at exactly this measured version — the test
+      # boots Pi's real tool registry to prove the read-only carve-out
+      # resolves to real, unshadowed builtins, and fails loud (by design)
+      # when the runtime is absent or drifts. The canonical Pi is
+      # @earendil-works/[email protected] exactly (@mariozechner/* is
+      # embedded-legacy). Step-level install because ci-base image publishes
+      # are currently blocked on registry auth; fold into Dockerfile.ci once
+      # that is fixed, keeping this as a fast no-op guard.
+      - npm install -g @earendil-works/[email protected]
       # postgresql-client (pg_isready) is baked into ci-base.
       # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
       - |

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

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

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

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

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

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

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

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

apps/gateway/src/app.module.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

apps/gateway/src/coord/interaction-coordination.di.test.ts

@@ -0,0 +1,19 @@
+import 'reflect-metadata';
+import { Test } from '@nestjs/testing';
+import { describe, expect, it } from 'vitest';
+import { CoordModule } from './coord.module.js';
+import { InteractionCoordinationService } from './interaction-coordination.service.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+
+describe('CoordModule DI (compiled-metadata boot)', () => {
+  it('resolves InteractionCoordinationService through Nest DI', async () => {
+    const moduleRef = await Test.createTestingModule({ imports: [CoordModule] })
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: (): boolean => true })
+      .compile();
+    expect(moduleRef.get(InteractionCoordinationService)).toBeInstanceOf(
+      InteractionCoordinationService,
+    );
+    await moduleRef.close();
+  });
+});

apps/gateway/src/coord/interaction-coordination.service.ts

@@ -1,4 +1,4 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { Inject, Injectable, Optional } from '@nestjs/common';
 import {
   InteractionCoordinationClient,
   type CoordinationObservation,
@@ -13,6 +13,7 @@ import type { CreateHandoffDto } from './interaction-coordination.dto.js';
 
 export const COORDINATION_PORT = Symbol('COORDINATION_PORT');
 export const COORDINATION_CONFIG = Symbol('COORDINATION_CONFIG');
+export const HANDOFF_ID_FACTORY = Symbol('HANDOFF_ID_FACTORY');
 
 const HANDOFF_TRACKING_TTL_MS = 60 * 60 * 1_000;
 const MAX_TRACKED_HANDOFFS = 1_000;
@@ -60,6 +61,8 @@ export class InteractionCoordinationService {
   constructor(
     @Inject(COORDINATION_PORT) private readonly port: InteractionCoordinationPort,
     @Inject(COORDINATION_CONFIG) private readonly config: InteractionCoordinationConfig,
+    @Optional()
+    @Inject(HANDOFF_ID_FACTORY)
     private readonly handoffIdFactory: () => string = (): string => crypto.randomUUID(),
   ) {}
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import {
+  HarnessAdapterUnavailableError,
+  HarnessRegistrationError,
+  HarnessRegistry,
+} from './harness.registry.js';
+import { FakeHarnessAdapter } from './testing/fake-harness.adapter.js';
+
+describe('HarnessRegistry', () => {
+  it('registers and looks up an adapter by harness id', () => {
+    const registry = new HarnessRegistry();
+    const adapter = new FakeHarnessAdapter({ id: 'fake' });
+
+    registry.register(adapter);
+
+    expect(registry.get('fake')).toBe(adapter);
+    expect(registry.has('fake')).toBe(true);
+    expect(registry.list().map((entry) => entry.id)).toEqual(['fake']);
+  });
+
+  it('rejects a blank adapter id', () => {
+    const registry = new HarnessRegistry();
+
+    let error: unknown;
+    try {
+      registry.register(new FakeHarnessAdapter({ id: '   ' }));
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessRegistrationError);
+    expect((error as HarnessRegistrationError).reason).toBe('blank_id');
+    expect(registry.list()).toEqual([]);
+  });
+
+  it('rejects a duplicate adapter id', () => {
+    const registry = new HarnessRegistry();
+    registry.register(new FakeHarnessAdapter({ id: 'fake' }));
+
+    let error: unknown;
+    try {
+      registry.register(new FakeHarnessAdapter({ id: 'fake' }));
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessRegistrationError);
+    expect((error as HarnessRegistrationError).reason).toBe('duplicate_id');
+    expect((error as HarnessRegistrationError).harnessId).toBe('fake');
+    // The original registration is untouched.
+    expect(registry.list()).toHaveLength(1);
+  });
+
+  it('returns adapter_unavailable for an unknown harness id', () => {
+    const registry = new HarnessRegistry();
+
+    let error: unknown;
+    try {
+      registry.get('missing');
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessAdapterUnavailableError);
+    expect((error as HarnessAdapterUnavailableError).code).toBe('adapter_unavailable');
+    expect((error as HarnessAdapterUnavailableError).harnessId).toBe('missing');
+    expect(registry.has('missing')).toBe(false);
+  });
+});

apps/gateway/src/harness/harness.registry.ts

@@ -0,0 +1,100 @@
+import { Injectable } from '@nestjs/common';
+import type {
+  HarnessAdapter,
+  HarnessErrorCode,
+  HarnessErrorDto,
+  HarnessSelection,
+} from '@mosaicstack/types';
+
+/**
+ * A typed harness operation failure that carries a fully-formed, browser-safe
+ * {@link HarnessErrorDto}. The DTO's `selection` is always the exact requested
+ * tuple — there is no field through which a substituted "effective" selection
+ * could ever be reported.
+ */
+export class HarnessOperationError extends Error {
+  readonly code: HarnessErrorCode;
+  readonly dto: HarnessErrorDto;
+
+  constructor(dto: HarnessErrorDto) {
+    super(dto.message);
+    this.name = 'HarnessOperationError';
+    this.code = dto.code;
+    this.dto = dto;
+  }
+}
+
+/** Build a {@link HarnessOperationError} that echoes the requested selection unchanged. */
+export function operationError(
+  code: HarnessErrorCode,
+  message: string,
+  selection: HarnessSelection,
+  correlationId: string,
+  retryable = false,
+): HarnessOperationError {
+  return new HarnessOperationError({ code, message, retryable, correlationId, selection });
+}
+
+/** Raised when an unknown harness id is looked up. Discriminated by `code`. */
+export class HarnessAdapterUnavailableError extends Error {
+  readonly code = 'adapter_unavailable' as const satisfies HarnessErrorCode;
+
+  constructor(readonly harnessId: string) {
+    super(`No harness adapter is registered for id "${harnessId}".`);
+    this.name = 'HarnessAdapterUnavailableError';
+  }
+}
+
+export type HarnessRegistrationFailure = 'blank_id' | 'duplicate_id';
+
+/** Raised when an adapter cannot be registered (blank or duplicate id). */
+export class HarnessRegistrationError extends Error {
+  constructor(
+    readonly reason: HarnessRegistrationFailure,
+    readonly harnessId: string,
+  ) {
+    super(
+      reason === 'blank_id'
+        ? 'A harness adapter id must be a non-empty string.'
+        : `A harness adapter is already registered for id "${harnessId}".`,
+    );
+    this.name = 'HarnessRegistrationError';
+  }
+}
+
+/**
+ * Harness-neutral adapter registry. Adapters are keyed by their harness id.
+ * Registration rejects blank and duplicate ids; lookup of an unknown id fails
+ * with {@link HarnessAdapterUnavailableError} (`adapter_unavailable`).
+ */
+@Injectable()
+export class HarnessRegistry {
+  private readonly adapters = new Map<string, HarnessAdapter>();
+
+  register(adapter: HarnessAdapter): void {
+    const id = adapter.id;
+    if (typeof id !== 'string' || id.trim().length === 0) {
+      throw new HarnessRegistrationError('blank_id', id ?? '');
+    }
+    if (this.adapters.has(id)) {
+      throw new HarnessRegistrationError('duplicate_id', id);
+    }
+    this.adapters.set(id, adapter);
+  }
+
+  get(harnessId: string): HarnessAdapter {
+    const adapter = this.adapters.get(harnessId);
+    if (!adapter) {
+      throw new HarnessAdapterUnavailableError(harnessId);
+    }
+    return adapter;
+  }
+
+  has(harnessId: string): boolean {
+    return this.adapters.has(harnessId);
+  }
+
+  list(): readonly HarnessAdapter[] {
+    return [...this.adapters.values()];
+  }
+}

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

@@ -0,0 +1,227 @@
+import { describe, expect, it } from 'vitest';
+import type { HarnessActorContext, HarnessCapability, HarnessSelection } from '@mosaicstack/types';
+import { HARNESS_CAPABILITIES } from '@mosaicstack/types';
+import { HarnessOperationError, HarnessRegistry } from './harness.registry.js';
+import {
+  HarnessScopeViolationError,
+  HarnessService,
+  type TrustedGatewayScope,
+} from './harness.service.js';
+import { FakeHarnessAdapter } from './testing/fake-harness.adapter.js';
+
+const SCOPE: TrustedGatewayScope = {
+  actorId: 'actor-trusted',
+  tenantId: 'tenant-trusted',
+  seatId: 'seat-trusted',
+  correlationId: 'correlation-trusted',
+};
+
+const READ_CONTEXT: HarnessActorContext = {
+  actorId: SCOPE.actorId,
+  tenantId: SCOPE.tenantId,
+  seatId: SCOPE.seatId,
+  correlationId: SCOPE.correlationId,
+};
+
+function setup(capabilities?: readonly HarnessCapability[]) {
+  const registry = new HarnessRegistry();
+  const adapter = new FakeHarnessAdapter({ id: 'fake', capabilities });
+  registry.register(adapter);
+  const service = new HarnessService(registry);
+  return { registry, adapter, service };
+}
+
+async function availableSelection(adapter: FakeHarnessAdapter): Promise<HarnessSelection> {
+  const catalog = await adapter.catalog(READ_CONTEXT);
+  const entry = catalog.models.find((model) => model.availability === 'available');
+  if (!entry) {
+    throw new Error('fixture requires an available model');
+  }
+  return { harnessId: entry.harnessId, providerId: entry.providerId, modelId: entry.modelId };
+}
+
+describe('HarnessService', () => {
+  it('derives the actor context from trusted scope on create', async () => {
+    const { service, adapter } = setup();
+    const selection = await availableSelection(adapter);
+
+    const snapshot = await service.createSession(SCOPE, {
+      conversationId: 'conversation-1',
+      selection,
+    });
+
+    expect(snapshot.seatId).toBe(SCOPE.seatId);
+    expect(snapshot.state).toBe('idle');
+    expect(snapshot.selection).toEqual(selection);
+    expect(snapshot.nativeSessionId).toBeTruthy();
+  });
+
+  it('rejects server-authority fields supplied by an external caller', async () => {
+    const { service, adapter } = setup();
+    const selection = await availableSelection(adapter);
+
+    const hostile = {
+      conversationId: 'conversation-1',
+      selection,
+      seatId: 'attacker-seat',
+      executablePath: '/usr/bin/evil',
+      home: '/home/attacker',
+      cwd: '/tmp/attacker',
+      nativeSessionPath: '/var/native/attacker.jsonl',
+    } as unknown as Parameters<HarnessService['createSession']>[1];
+
+    let error: unknown;
+    try {
+      await service.createSession(SCOPE, hostile);
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessScopeViolationError);
+    expect((error as HarnessScopeViolationError).field).toBe('seatId');
+  });
+
+  it('returns adapter_unavailable for an unknown harness id, echoing the requested tuple', async () => {
+    const { service } = setup();
+    const selection: HarnessSelection = {
+      harnessId: 'ghost-harness',
+      providerId: 'p',
+      modelId: 'm',
+    };
+
+    let error: unknown;
+    try {
+      await service.createSession(SCOPE, { conversationId: 'conversation-1', selection });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessOperationError);
+    const dto = (error as HarnessOperationError).dto;
+    expect(dto.code).toBe('adapter_unavailable');
+    expect(dto.selection).toEqual(selection);
+    expect(dto.correlationId).toBe(SCOPE.correlationId);
+  });
+
+  it('returns selection_invalid for an unknown provider/model tuple, unchanged', async () => {
+    const { service } = setup();
+    const selection: HarnessSelection = {
+      harnessId: 'fake',
+      providerId: 'ghost-provider',
+      modelId: 'ghost-model',
+    };
+
+    let error: unknown;
+    try {
+      await service.createSession(SCOPE, { conversationId: 'conversation-1', selection });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessOperationError);
+    const dto = (error as HarnessOperationError).dto;
+    expect(dto.code).toBe('selection_invalid');
+    expect(dto.selection).toEqual(selection);
+  });
+
+  it('returns model_unavailable without falling back for a known unavailable model', async () => {
+    const { service, adapter } = setup();
+    const catalog = await adapter.catalog(READ_CONTEXT);
+    const unavailable = catalog.models.find((entry) => entry.availability === 'unavailable');
+    expect(unavailable).toBeDefined();
+    const selection: HarnessSelection = {
+      harnessId: unavailable!.harnessId,
+      providerId: unavailable!.providerId,
+      modelId: unavailable!.modelId,
+    };
+
+    let error: unknown;
+    try {
+      await service.createSession(SCOPE, { conversationId: 'conversation-1', selection });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessOperationError);
+    const dto = (error as HarnessOperationError).dto;
+    expect(dto.code).toBe('model_unavailable');
+    // No substitution: the DTO tuple is exactly what was requested.
+    expect(dto.selection).toEqual(selection);
+  });
+
+  it('gives create, resume, detach, evict, and end distinct observable effects', async () => {
+    const { service, adapter } = setup();
+    const selection = await availableSelection(adapter);
+
+    const created = await service.createSession(SCOPE, {
+      conversationId: 'conversation-create',
+      selection,
+    });
+    expect(created.state).toBe('idle');
+    expect(created.processId).toBeTruthy();
+    expect(created.attachedClientIds).toEqual([]);
+
+    const resumed = await service.resumeSession(SCOPE, {
+      conversationId: 'conversation-resume',
+      nativeSessionId: 'native-preexisting-123',
+      selection,
+    });
+    // Resume binds the supplied native session; create mints a fresh one.
+    expect(resumed.nativeSessionId).toBe('native-preexisting-123');
+    expect(resumed.nativeSessionId).not.toBe(created.nativeSessionId);
+
+    await service.attach(SCOPE, {
+      conversationId: 'conversation-create',
+      clientId: 'browser-1',
+    });
+    const afterAttach = await service.snapshot(SCOPE, 'conversation-create');
+    expect(afterAttach.attachedClientIds).toEqual(['browser-1']);
+
+    const afterDetach = await service.detach(SCOPE, {
+      conversationId: 'conversation-create',
+      clientId: 'browser-1',
+    });
+    // Detach removes the browser attachment only; the process stays alive.
+    expect(afterDetach.attachedClientIds).toEqual([]);
+    expect(afterDetach.state).toBe('idle');
+    expect(afterDetach.processId).toBeTruthy();
+
+    const afterEvict = await service.evict(SCOPE, {
+      conversationId: 'conversation-create',
+      reason: 'idle_timeout',
+    });
+    // Evict stops the process but retains the resumable native session.
+    expect(afterEvict.state).toBe('evicted');
+    expect(afterEvict.processId).toBeUndefined();
+    expect(afterEvict.nativeSessionId).toBe(created.nativeSessionId);
+
+    const afterEnd = await service.end(SCOPE, {
+      conversationId: 'conversation-create',
+      reason: 'session_ended',
+    });
+    // End destructively terminates the native session.
+    expect(afterEnd.state).toBe('ended');
+  });
+
+  it('fails typed when an unsupported capability is exercised', async () => {
+    const withoutExtensionUi = HARNESS_CAPABILITIES.filter(
+      (capability) => capability !== 'extensionUi',
+    );
+    const { service, adapter } = setup(withoutExtensionUi);
+    const selection = await availableSelection(adapter);
+    await service.createSession(SCOPE, { conversationId: 'conversation-1', selection });
+
+    let error: unknown;
+    try {
+      await service.respondInteraction(SCOPE, {
+        conversationId: 'conversation-1',
+        response: { requestId: 'interaction-1', type: 'confirm', accepted: true },
+      });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessOperationError);
+    expect((error as HarnessOperationError).dto.code).toBe('interaction_unsupported');
+  });
+});

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

@@ -0,0 +1,285 @@
+import { Inject, Injectable } from '@nestjs/common';
+import type {
+  HarnessActorContext,
+  HarnessAdapter,
+  HarnessCatalog,
+  HarnessCloseReason,
+  HarnessInteractionResponse,
+  HarnessSelection,
+  HarnessSessionHandle,
+  HarnessSessionSnapshot,
+} from '@mosaicstack/types';
+import {
+  HarnessAdapterUnavailableError,
+  HarnessRegistry,
+  operationError,
+} from './harness.registry.js';
+import { HARNESS_REGISTRY } from './harness.tokens.js';
+
+/**
+ * Trusted, server-derived authority. In production this is produced by the
+ * Gateway from the authenticated session — never from a browser/caller DTO.
+ */
+export interface TrustedGatewayScope {
+  readonly actorId: string;
+  readonly tenantId: string;
+  readonly seatId: string;
+  readonly correlationId: string;
+}
+
+/** Server-authority fields that must never arrive from an external request DTO. */
+const FORBIDDEN_REQUEST_FIELDS = [
+  'actorId',
+  'tenantId',
+  'correlationId',
+  'seatId',
+  'seat',
+  'executable',
+  'executablePath',
+  'home',
+  'homeDir',
+  'cwd',
+  'workingDir',
+  'workingDirectory',
+  'nativeSessionPath',
+  'sessionPath',
+] as const;
+
+/** Raised when an external request DTO smuggles a server-authority field. */
+export class HarnessScopeViolationError extends Error {
+  constructor(readonly field: string) {
+    super(`External request supplied server-authority field "${field}".`);
+    this.name = 'HarnessScopeViolationError';
+  }
+}
+
+export interface CreateHarnessSessionRequest {
+  readonly conversationId: string;
+  readonly selection: HarnessSelection;
+}
+
+export interface ResumeHarnessSessionRequest {
+  readonly conversationId: string;
+  readonly nativeSessionId: string;
+  readonly selection: HarnessSelection;
+}
+
+export interface AttachClientRequest {
+  readonly conversationId: string;
+  readonly clientId: string;
+}
+
+export interface DetachClientRequest {
+  readonly conversationId: string;
+  readonly clientId: string;
+}
+
+export interface EvictSessionRequest {
+  readonly conversationId: string;
+  readonly reason: HarnessCloseReason;
+}
+
+export interface EndSessionRequest {
+  readonly conversationId: string;
+  readonly reason: HarnessCloseReason;
+}
+
+export interface RespondInteractionRequest {
+  readonly conversationId: string;
+  readonly response: HarnessInteractionResponse;
+}
+
+interface ActiveSession {
+  readonly harnessId: string;
+  readonly handle: HarnessSessionHandle;
+  readonly correlationId: string;
+}
+
+/**
+ * Harness-neutral service. It derives the {@link HarnessActorContext} strictly
+ * from trusted Gateway scope, validates the selected provider/model tuple with
+ * NO fallback substitution, and exposes distinct create/resume/detach/evict/end
+ * lifecycle operations.
+ */
+@Injectable()
+export class HarnessService {
+  private readonly sessions = new Map<string, ActiveSession>();
+
+  constructor(@Inject(HARNESS_REGISTRY) private readonly registry: HarnessRegistry) {}
+
+  async createSession(
+    scope: TrustedGatewayScope,
+    request: CreateHarnessSessionRequest,
+  ): Promise<HarnessSessionSnapshot> {
+    assertTrustedRequest(request);
+    const { conversationId, selection } = request;
+    const adapter = this.resolveAdapter(scope, selection);
+    const context = deriveActorContext(scope);
+    await this.assertSelectionAvailable(scope, adapter.catalog(context), selection);
+
+    const handle = await adapter.create({ context, conversationId, selection });
+    this.sessions.set(conversationId, {
+      harnessId: selection.harnessId,
+      handle,
+      correlationId: scope.correlationId,
+    });
+    return handle.snapshot();
+  }
+
+  async resumeSession(
+    scope: TrustedGatewayScope,
+    request: ResumeHarnessSessionRequest,
+  ): Promise<HarnessSessionSnapshot> {
+    assertTrustedRequest(request);
+    const { conversationId, nativeSessionId, selection } = request;
+    const adapter = this.resolveAdapter(scope, selection);
+    const context = deriveActorContext(scope);
+    await this.assertSelectionAvailable(scope, adapter.catalog(context), selection);
+
+    const handle = await adapter.resume({ context, conversationId, nativeSessionId, selection });
+    this.sessions.set(conversationId, {
+      harnessId: selection.harnessId,
+      handle,
+      correlationId: scope.correlationId,
+    });
+    return handle.snapshot();
+  }
+
+  async attach(
+    scope: TrustedGatewayScope,
+    request: AttachClientRequest,
+  ): Promise<HarnessSessionSnapshot> {
+    assertTrustedRequest(request);
+    const handle = this.requireHandle(scope, request.conversationId);
+    await handle.attach({ clientId: request.clientId });
+    return handle.snapshot();
+  }
+
+  async detach(
+    scope: TrustedGatewayScope,
+    request: DetachClientRequest,
+  ): Promise<HarnessSessionSnapshot> {
+    assertTrustedRequest(request);
+    const handle = this.requireHandle(scope, request.conversationId);
+    await handle.detach(request.clientId);
+    return handle.snapshot();
+  }
+
+  async evict(
+    scope: TrustedGatewayScope,
+    request: EvictSessionRequest,
+  ): Promise<HarnessSessionSnapshot> {
+    assertTrustedRequest(request);
+    const handle = this.requireHandle(scope, request.conversationId);
+    await handle.evictProcess(request.reason);
+    return handle.snapshot();
+  }
+
+  async end(
+    scope: TrustedGatewayScope,
+    request: EndSessionRequest,
+  ): Promise<HarnessSessionSnapshot> {
+    assertTrustedRequest(request);
+    const handle = this.requireHandle(scope, request.conversationId);
+    await handle.endSession(request.reason);
+    const snapshot = await handle.snapshot();
+    this.sessions.delete(request.conversationId);
+    return snapshot;
+  }
+
+  async respondInteraction(
+    scope: TrustedGatewayScope,
+    request: RespondInteractionRequest,
+  ): Promise<void> {
+    assertTrustedRequest(request);
+    const handle = this.requireHandle(scope, request.conversationId);
+    await handle.respondInteraction(request.response);
+  }
+
+  async snapshot(
+    scope: TrustedGatewayScope,
+    conversationId: string,
+  ): Promise<HarnessSessionSnapshot> {
+    const handle = this.requireHandle(scope, conversationId);
+    return handle.snapshot();
+  }
+
+  private resolveAdapter(scope: TrustedGatewayScope, selection: HarnessSelection): HarnessAdapter {
+    try {
+      return this.registry.get(selection.harnessId);
+    } catch (error) {
+      if (error instanceof HarnessAdapterUnavailableError) {
+        throw operationError('adapter_unavailable', error.message, selection, scope.correlationId);
+      }
+      throw error;
+    }
+  }
+
+  private async assertSelectionAvailable(
+    scope: TrustedGatewayScope,
+    catalogPromise: Promise<HarnessCatalog>,
+    selection: HarnessSelection,
+  ): Promise<void> {
+    const catalog = await catalogPromise;
+    const entry = catalog.models.find(
+      (candidate) =>
+        candidate.harnessId === selection.harnessId &&
+        candidate.providerId === selection.providerId &&
+        candidate.modelId === selection.modelId,
+    );
+    if (!entry) {
+      // No first-row fallback: reject the requested tuple unchanged.
+      throw operationError(
+        'selection_invalid',
+        'The requested harness/provider/model tuple is not in the catalog.',
+        selection,
+        scope.correlationId,
+      );
+    }
+    if (entry.availability === 'unavailable') {
+      throw operationError(
+        'model_unavailable',
+        'The requested model is currently unavailable.',
+        selection,
+        scope.correlationId,
+        true,
+      );
+    }
+  }
+
+  private requireHandle(scope: TrustedGatewayScope, conversationId: string): HarnessSessionHandle {
+    const active = this.sessions.get(conversationId);
+    if (!active) {
+      throw operationError(
+        'session_not_found',
+        `No active harness session for conversation "${conversationId}".`,
+        { harnessId: '', providerId: '', modelId: '' },
+        scope.correlationId,
+      );
+    }
+    return active.handle;
+  }
+}
+
+/** Build the actor context strictly from trusted scope. No caller data leaks in. */
+export function deriveActorContext(scope: TrustedGatewayScope): HarnessActorContext {
+  return {
+    actorId: scope.actorId,
+    tenantId: scope.tenantId,
+    seatId: scope.seatId,
+    correlationId: scope.correlationId,
+  };
+}
+
+/** Reject any request object that carries a server-authority field. */
+function assertTrustedRequest(request: object): void {
+  for (const field of FORBIDDEN_REQUEST_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(request, field)) {
+      throw new HarnessScopeViolationError(field);
+    }
+  }
+}
+
+// Re-export the typed operation error so callers importing from the service
+// have the discriminated failure type without reaching into the registry.
+export { HarnessOperationError } from './harness.registry.js';

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

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

apps/gateway/src/harness/testing/fake-harness.adapter.spec.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import type { HarnessActorContext, HarnessSelection } from '@mosaicstack/types';
+import { HarnessOperationError } from '../harness.registry.js';
+import { FakeHarnessAdapter } from './fake-harness.adapter.js';
+import { runHarnessAdapterContract } from './harness-adapter.contract.js';
+
+const CONTEXT: HarnessActorContext = {
+  actorId: 'actor-1',
+  tenantId: 'tenant-1',
+  seatId: 'seat-1',
+  correlationId: 'correlation-1',
+};
+
+// The reusable conformance suite. Task 13 re-runs it against the native Pi adapter.
+runHarnessAdapterContract('FakeHarnessAdapter', () => new FakeHarnessAdapter({ id: 'fake' }));
+
+describe('FakeHarnessAdapter no-substitution', () => {
+  it('never substitutes the first catalog row when a bogus selection is requested', async () => {
+    const adapter = new FakeHarnessAdapter({ id: 'fake' });
+    const catalog = await adapter.catalog(CONTEXT);
+    const firstRow = catalog.models[0];
+    if (!firstRow) {
+      throw new Error('fixture requires a catalog model');
+    }
+    const available = catalog.models.find(
+      (entry) => entry.availability === 'available' && entry.modelId !== firstRow.modelId,
+    );
+    expect(available).toBeDefined();
+    const selected: HarnessSelection = {
+      harnessId: available!.harnessId,
+      providerId: available!.providerId,
+      modelId: available!.modelId,
+    };
+
+    const handle = await adapter.create({
+      context: CONTEXT,
+      conversationId: 'conversation-1',
+      selection: selected,
+    });
+
+    const bogus: HarnessSelection = {
+      harnessId: 'fake',
+      providerId: 'ghost-provider',
+      modelId: 'ghost-model',
+    };
+
+    let error: unknown;
+    try {
+      await handle.setModel(bogus);
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessOperationError);
+    const dto = (error as HarnessOperationError).dto;
+    expect(dto.code).toBe('selection_invalid');
+    // The DTO echoes the exact requested tuple, unchanged.
+    expect(dto.selection).toEqual(bogus);
+    // No substitution to the first catalog row.
+    expect(dto.selection).not.toEqual({
+      harnessId: firstRow.harnessId,
+      providerId: firstRow.providerId,
+      modelId: firstRow.modelId,
+    });
+    // The active selection is untouched by the rejected request.
+    expect((await handle.snapshot()).selection).toEqual(selected);
+  });
+
+  it('reports model_unavailable with the unchanged tuple for a known but unavailable model', async () => {
+    const adapter = new FakeHarnessAdapter({ id: 'fake' });
+    const catalog = await adapter.catalog(CONTEXT);
+    const unavailable = catalog.models.find((entry) => entry.availability === 'unavailable');
+    const available = catalog.models.find((entry) => entry.availability === 'available');
+    expect(unavailable).toBeDefined();
+    expect(available).toBeDefined();
+
+    const startingSelection: HarnessSelection = {
+      harnessId: available!.harnessId,
+      providerId: available!.providerId,
+      modelId: available!.modelId,
+    };
+    const handle = await adapter.create({
+      context: CONTEXT,
+      conversationId: 'conversation-2',
+      selection: startingSelection,
+    });
+
+    const requested: HarnessSelection = {
+      harnessId: unavailable!.harnessId,
+      providerId: unavailable!.providerId,
+      modelId: unavailable!.modelId,
+    };
+
+    let error: unknown;
+    try {
+      await handle.setModel(requested);
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessOperationError);
+    const dto = (error as HarnessOperationError).dto;
+    expect(dto.code).toBe('model_unavailable');
+    expect(dto.selection).toEqual(requested);
+    expect((await handle.snapshot()).selection).toEqual(startingSelection);
+  });
+});

apps/gateway/src/harness/testing/fake-harness.adapter.ts

@@ -0,0 +1,248 @@
+import type {
+  AttachClient,
+  CreateHarnessSession,
+  HarnessAdapter,
+  HarnessActorContext,
+  HarnessCapability,
+  HarnessCatalog,
+  HarnessCatalogEntry,
+  HarnessCloseReason,
+  HarnessDescriptor,
+  HarnessEvent,
+  HarnessInteractionResponse,
+  HarnessPrompt,
+  HarnessPromptReceipt,
+  HarnessSelection,
+  HarnessSessionHandle,
+  HarnessSessionSnapshot,
+  HarnessSessionState,
+  ResumeHarnessSession,
+} from '@mosaicstack/types';
+import { HARNESS_CAPABILITIES } from '@mosaicstack/types';
+import { operationError } from '../harness.registry.js';
+
+export interface FakeHarnessAdapterOptions {
+  readonly id: string;
+  readonly capabilities?: readonly HarnessCapability[];
+  readonly catalog?: readonly HarnessCatalogEntry[];
+}
+
+const FAKE_PROVIDER = 'fake-openai';
+
+function defaultCatalog(harnessId: string): readonly HarnessCatalogEntry[] {
+  return [
+    {
+      harnessId,
+      providerId: FAKE_PROVIDER,
+      modelId: 'fake-mini',
+      displayName: 'Fake Mini',
+      reasoningCapability: false,
+      inputTypes: ['text'],
+      authState: 'ready',
+      availability: 'available',
+    },
+    {
+      harnessId,
+      providerId: FAKE_PROVIDER,
+      modelId: 'fake-pro',
+      displayName: 'Fake Pro',
+      reasoningCapability: true,
+      inputTypes: ['text', 'image'],
+      authState: 'ready',
+      availability: 'available',
+    },
+    {
+      harnessId,
+      providerId: FAKE_PROVIDER,
+      modelId: 'fake-legacy',
+      displayName: 'Fake Legacy',
+      reasoningCapability: false,
+      inputTypes: ['text'],
+      authState: 'unavailable',
+      availability: 'unavailable',
+    },
+  ];
+}
+
+function matches(entry: HarnessCatalogEntry, selection: HarnessSelection): boolean {
+  return (
+    entry.harnessId === selection.harnessId &&
+    entry.providerId === selection.providerId &&
+    entry.modelId === selection.modelId
+  );
+}
+
+/**
+ * In-memory harness session handle used by the fake adapter and by the shared
+ * conformance suite. It enforces the two invariants the real adapters must also
+ * honor: model selection is validated against the catalog and is NEVER
+ * substituted, and unsupported capabilities fail with a typed error.
+ */
+export class FakeHarnessSessionHandle implements HarnessSessionHandle {
+  private state: HarnessSessionState = 'idle';
+  private processId: string | undefined;
+  private readonly attachedClientIds = new Set<string>();
+  private readonly listeners = new Set<(event: HarnessEvent) => void>();
+
+  constructor(
+    private readonly conversationId: string,
+    private readonly nativeSessionId: string,
+    private readonly seatId: string,
+    private selection: HarnessSelection,
+    private readonly correlationId: string,
+    private readonly capabilities: readonly HarnessCapability[],
+    private readonly catalog: readonly HarnessCatalogEntry[],
+  ) {
+    this.processId = `process-${nativeSessionId}`;
+  }
+
+  async snapshot(): Promise<HarnessSessionSnapshot> {
+    return {
+      conversationId: this.conversationId,
+      nativeSessionId: this.nativeSessionId,
+      processId: this.processId,
+      seatId: this.seatId,
+      selection: this.selection,
+      state: this.state,
+      attachedClientIds: [...this.attachedClientIds],
+    };
+  }
+
+  async attach(input: AttachClient): Promise<void> {
+    this.attachedClientIds.add(input.clientId);
+  }
+
+  async detach(clientId: string): Promise<void> {
+    // Removes the browser attachment only; the process and native session persist.
+    this.attachedClientIds.delete(clientId);
+  }
+
+  async prompt(input: HarnessPrompt & { idempotencyKey: string }): Promise<HarnessPromptReceipt> {
+    return {
+      conversationId: this.conversationId,
+      turnId: input.turnId,
+      correlationId: input.correlationId,
+      state: 'accepted',
+      selection: this.selection,
+    };
+  }
+
+  async setModel(selection: HarnessSelection): Promise<HarnessSelection> {
+    const entry = this.catalog.find((candidate) => matches(candidate, selection));
+    if (!entry) {
+      // No fallback to the first catalog row: reject with the requested tuple, unchanged.
+      throw operationError(
+        'selection_invalid',
+        'The requested harness/provider/model tuple is not in the catalog.',
+        selection,
+        this.correlationId,
+      );
+    }
+    if (entry.availability === 'unavailable') {
+      throw operationError(
+        'model_unavailable',
+        'The requested model is currently unavailable.',
+        selection,
+        this.correlationId,
+        true,
+      );
+    }
+    this.selection = selection;
+    return this.selection;
+  }
+
+  async abort(_turnId: string): Promise<void> {
+    // No active turn machinery in the fake; abort is a no-op acknowledgement.
+  }
+
+  async respondInteraction(_input: HarnessInteractionResponse): Promise<void> {
+    if (!this.capabilities.includes('extensionUi')) {
+      throw operationError(
+        'interaction_unsupported',
+        'This harness does not support interactive responses.',
+        this.selection,
+        this.correlationId,
+      );
+    }
+  }
+
+  events(listener: (event: HarnessEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  async evictProcess(_reason: HarnessCloseReason): Promise<void> {
+    // Stop the process but keep the resumable native session.
+    this.processId = undefined;
+    this.state = 'evicted';
+  }
+
+  async endSession(_reason: HarnessCloseReason): Promise<void> {
+    // Destructively end the native session.
+    this.processId = undefined;
+    this.state = 'ended';
+  }
+}
+
+/**
+ * Minimal in-memory {@link HarnessAdapter} for Slice Zero. It mints a fresh
+ * native session id on `create` and binds the supplied one on `resume`, so the
+ * two paths are observably distinct.
+ */
+export class FakeHarnessAdapter implements HarnessAdapter {
+  readonly id: string;
+  private readonly capabilities: readonly HarnessCapability[];
+  private readonly catalogEntries: readonly HarnessCatalogEntry[];
+  private createdCount = 0;
+
+  constructor(options: FakeHarnessAdapterOptions) {
+    this.id = options.id;
+    this.capabilities = options.capabilities ?? [...HARNESS_CAPABILITIES];
+    this.catalogEntries = options.catalog ?? defaultCatalog(options.id);
+  }
+
+  async describe(_context: HarnessActorContext): Promise<HarnessDescriptor> {
+    return {
+      id: this.id,
+      displayName: `Fake harness (${this.id})`,
+      capabilities: this.capabilities,
+    };
+  }
+
+  async catalog(_context: HarnessActorContext): Promise<HarnessCatalog> {
+    return {
+      harnessId: this.id,
+      version: '1.0.0',
+      fingerprint: `fake-${this.id}-${this.catalogEntries.length}`,
+      models: this.catalogEntries,
+    };
+  }
+
+  async create(input: CreateHarnessSession): Promise<HarnessSessionHandle> {
+    this.createdCount += 1;
+    const nativeSessionId = `native-${input.conversationId}-${this.createdCount}`;
+    return new FakeHarnessSessionHandle(
+      input.conversationId,
+      nativeSessionId,
+      input.context.seatId,
+      input.selection,
+      input.context.correlationId,
+      this.capabilities,
+      this.catalogEntries,
+    );
+  }
+
+  async resume(input: ResumeHarnessSession): Promise<HarnessSessionHandle> {
+    return new FakeHarnessSessionHandle(
+      input.conversationId,
+      input.nativeSessionId,
+      input.context.seatId,
+      input.selection,
+      input.context.correlationId,
+      this.capabilities,
+      this.catalogEntries,
+    );
+  }
+}

apps/gateway/src/harness/testing/harness-adapter.contract.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  HarnessActorContext,
+  HarnessAdapter,
+  HarnessCatalogEntry,
+  HarnessSelection,
+} from '@mosaicstack/types';
+import { HarnessOperationError } from '../harness.registry.js';
+
+const CONTEXT: HarnessActorContext = {
+  actorId: 'contract-actor',
+  tenantId: 'contract-tenant',
+  seatId: 'contract-seat',
+  correlationId: 'contract-correlation',
+};
+
+function toSelection(entry: HarnessCatalogEntry): HarnessSelection {
+  return { harnessId: entry.harnessId, providerId: entry.providerId, modelId: entry.modelId };
+}
+
+function pickAvailable(models: readonly HarnessCatalogEntry[]): HarnessCatalogEntry {
+  const entry = models.find((candidate) => candidate.availability === 'available') ?? models[0];
+  if (!entry) {
+    throw new Error('contract fixture requires at least one catalog model');
+  }
+  return entry;
+}
+
+async function captureError(run: () => Promise<unknown>): Promise<unknown> {
+  try {
+    await run();
+    return undefined;
+  } catch (caught) {
+    return caught;
+  }
+}
+
+/**
+ * Shared conformance suite every {@link HarnessAdapter} must pass. Slice Zero
+ * runs it against the fake adapter; Task 13 re-runs the identical suite against
+ * the native Pi adapter so both share one behavioral contract.
+ */
+export function runHarnessAdapterContract(
+  label: string,
+  createAdapter: () => HarnessAdapter,
+): void {
+  describe(`harness adapter contract: ${label}`, () => {
+    it('mints a fresh native session on create and binds the supplied one on resume', async () => {
+      const adapter = createAdapter();
+      const catalog = await adapter.catalog(CONTEXT);
+      const selection = toSelection(pickAvailable(catalog.models));
+
+      const created = await (
+        await adapter.create({ context: CONTEXT, conversationId: 'conv-create', selection })
+      ).snapshot();
+      const resumed = await (
+        await adapter.resume({
+          context: CONTEXT,
+          conversationId: 'conv-resume',
+          nativeSessionId: 'native-supplied-1',
+          selection,
+        })
+      ).snapshot();
+
+      expect(created.nativeSessionId).toBeTruthy();
+      expect(resumed.nativeSessionId).toBe('native-supplied-1');
+      expect(created.nativeSessionId).not.toBe(resumed.nativeSessionId);
+      expect(created.seatId).toBe(CONTEXT.seatId);
+    });
+
+    it('gives detach, evict, and end distinct effects (not aliases)', async () => {
+      const adapter = createAdapter();
+      const catalog = await adapter.catalog(CONTEXT);
+      const selection = toSelection(pickAvailable(catalog.models));
+      const handle = await adapter.create({
+        context: CONTEXT,
+        conversationId: 'conv-lifecycle',
+        selection,
+      });
+
+      await handle.attach({ clientId: 'browser-1' });
+      await handle.detach('browser-1');
+      const afterDetach = await handle.snapshot();
+      expect(afterDetach.attachedClientIds).toEqual([]);
+      expect(afterDetach.state).not.toBe('evicted');
+      expect(afterDetach.state).not.toBe('ended');
+
+      await handle.evictProcess('idle_timeout');
+      const afterEvict = await handle.snapshot();
+      expect(afterEvict.state).toBe('evicted');
+      // The native session survives eviction (resumable); the process does not.
+      expect(afterEvict.nativeSessionId).toBe(afterDetach.nativeSessionId);
+      expect(afterEvict.processId).toBeUndefined();
+
+      await handle.endSession('session_ended');
+      const afterEnd = await handle.snapshot();
+      expect(afterEnd.state).toBe('ended');
+      // End is not an alias of evict.
+      expect(afterEnd.state).not.toBe(afterEvict.state);
+    });
+
+    it('never substitutes the first catalog row for an unknown selection', async () => {
+      const adapter = createAdapter();
+      const catalog = await adapter.catalog(CONTEXT);
+      const firstRow = catalog.models[0];
+      if (!firstRow) {
+        throw new Error('contract fixture requires a catalog model');
+      }
+      const start = toSelection(pickAvailable(catalog.models));
+      const handle = await adapter.create({
+        context: CONTEXT,
+        conversationId: 'conv-nosub',
+        selection: start,
+      });
+
+      const bogus: HarnessSelection = {
+        harnessId: adapter.id,
+        providerId: 'contract-ghost-provider',
+        modelId: 'contract-ghost-model',
+      };
+      const error = await captureError(() => handle.setModel(bogus));
+
+      expect(error).toBeInstanceOf(HarnessOperationError);
+      const dto = (error as HarnessOperationError).dto;
+      expect(dto.code).toBe('selection_invalid');
+      expect(dto.selection).toEqual(bogus);
+      expect(dto.selection).not.toEqual(toSelection(firstRow));
+      expect((await handle.snapshot()).selection).toEqual(start);
+    });
+
+    it('validates capability-gated interactions with a typed error, not a silent no-op', async () => {
+      const adapter = createAdapter();
+      const descriptor = await adapter.describe(CONTEXT);
+      const catalog = await adapter.catalog(CONTEXT);
+      const selection = toSelection(pickAvailable(catalog.models));
+      const handle = await adapter.create({
+        context: CONTEXT,
+        conversationId: 'conv-interaction',
+        selection,
+      });
+
+      const response = {
+        requestId: 'interaction-1',
+        type: 'confirm',
+        accepted: true,
+      } as const;
+
+      if (descriptor.capabilities.includes('extensionUi')) {
+        await expect(handle.respondInteraction(response)).resolves.toBeUndefined();
+      } else {
+        const error = await captureError(() => handle.respondInteraction(response));
+        expect(error).toBeInstanceOf(HarnessOperationError);
+        expect((error as HarnessOperationError).dto.code).toBe('interaction_unsupported');
+      }
+    });
+  });
+}

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

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

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

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

apps/web/src/lib/types.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/ADMIN-GUIDE/README.md

@@ -0,0 +1,50 @@
+# Administrator Guide
+
+> **Status:** Partially migrated. Current SSO and local upgrade/recovery procedures are available; held procedures are labeled non-operative.
+
+This book is the canonical home for installation, configuration, deployment, routine operations, security controls, incident response, and recovery. User workflows belong in [`USER-GUIDE/`](../USER-GUIDE/); implementation and contributor material belongs in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
+
+## Start here
+
+- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
+- [Documentation sitemap](../SITEMAP.md) — resolvable current navigation and authority-gated migration summary.
+- [Product requirements](../PRD.md) — normative requirements, currently marked draft.
+- [Operations index](operations/README.md) — current local procedures and explicitly held operational outlines.
+- [Security index](security/README.md) — current SSO provider configuration.
+
+## Chapter map
+
+| Chapter                               | Scope                                                               | Status                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `installation/`                       | Prerequisites, installation, and first deployment.                  | Scaffold only.                                                          |
+| `configuration/`                      | Environment, provider, tier, and runtime configuration.             | Scaffold only.                                                          |
+| `deployment/`                         | Topologies, rollout, migration, and upgrade procedures.             | Scaffold only.                                                          |
+| [`operations/`](operations/README.md) | Health, observability, routine operation, and maintenance.          | Local upgrade/recovery is current; connector lease operations are held. |
+| [`security/`](security/README.md)     | Authentication, authorization, SSO, secrets, and security controls. | SSO provider guide is current; other pages are planned.                 |
+| `recovery/`                           | Incident response, backup, rollback, and recovery.                  | Scaffold only.                                                          |
+
+Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
+
+## Evidence — not current operator guidance
+
+- [`P8-003 performance report`](../reports/qa/p8-003-performance-optimization.md) — historical performance evidence; implementation alignment is partial, and production metrics remain unverified. It is not an operational SLO or runbook.
+
+## Migration backlog — not current operator guidance
+
+These are source candidates, not verified runbooks:
+
+- `_old_structure/guides/admin-guide.md` — quarantined historical source; verify claims before promotion.
+- `_old_structure/guides/deployment.md` — quarantined historical source; deployment commands and assumptions remain held.
+- See the [documentation catalog](../reports/documentation/2026-08-10-docs-catalog-audit.md) for file-level dispositions.
+
+Do not treat a migration candidate as current until its commands, paths, permissions, and safety status are checked against source and tests.
+
+## Authoring boundary
+
+New administrator documentation belongs under one of the chapter directories above. Operationally sensitive pages must identify prerequisites, ownership, source-of-truth dependencies, and whether any procedure is current, illustrative, held, or non-operative.
+
+## Related
+
+- [[README|Documentation contract]]
+- [[PRD|Product requirements]]
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]

docs/ADMIN-GUIDE/operations/README.md

@@ -0,0 +1,19 @@
+# Administrator Operations
+
+> **Status:** Partially migrated. Procedures explicitly identify whether they are current or held.
+
+## Current procedures
+
+- [Upgrade safety and recovery](upgrade-safety-and-recovery.md) — installed-CLI and local-PGlite upgrade, rollback, and framework-configuration recovery.
+
+## Held procedures
+
+- [Mos connector lease operations](mos-connector-lease-operations.md) — non-operative M1 outline while the gateway policy remains deny-all and no connector is activated.
+
+A held page is architecture and readiness context, not command authority. PostgreSQL, federated, bare-metal, Compose, Gateway/Web activation, and migration-runner procedures remain outside the current local route unless a later page explicitly removes the hold with verified evidence.
+
+## Related
+
+- [[ADMIN-GUIDE/README|Administrator guide]]
+- [[ADMIN-GUIDE/security/README|Administrator security]]
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]

docs/ADMIN-GUIDE/operations/mos-connector-lease-operations.md

@@ -0,0 +1,79 @@
+# Mos Connector Lease Operations — M1
+
+> **Status:** Held / non-operative.
+> **Operational authority:** None. This page is a future runbook outline, not a current command, endpoint, migration, or activation procedure.
+> **Hold condition:** The gateway's `DenyConnectorLeasePolicy` remains the default policy and rejects every lease and grant operation. No connector is activated by this page.
+
+## Current state
+
+M1 provides an implemented lease, fencing, audit, and gateway policy boundary. It does not currently provide an operator-facing lease endpoint, activate a connector, cut over a channel, or connect an existing runtime provider to `ConnectorExecutionContext`. The default gateway module is deny-all, so operators must not treat the schema or internal service as an available lease-control surface.
+
+There is no current operator command sequence to acquire, renew, take over, release, or grant connector authority. Do not attempt to operate the held procedure through direct database writes or by bypassing the gateway policy. Any future activation requires a separately approved server-side policy, concrete adapter, downstream fencing design, and an updated operational runbook.
+
+## Held future procedure — not current command authority
+
+The following records the intended shape of a later runbook. It is deliberately non-operative while deny-all remains:
+
+### Events and evidence to monitor later
+
+If an authorized policy and adapter are activated in a future work package, correlation IDs may be used to inspect `connector_lease_audit_log` events:
+
+| Event      | Meaning                                                                            |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `acquire`  | First holder inserted for an unused binding                                        |
+| `renew`    | Current holder heartbeat extended the TTL                                          |
+| `takeover` | Authorized compare-and-swap replaced the holder and incremented epoch              |
+| `release`  | Current holder explicitly relinquished authority                                   |
+| `expiry`   | An expired current lease was observed                                              |
+| `reject`   | Policy, compare-and-swap, expiry, scope, or fencing validation denied an operation |
+
+Audit records are metadata-only. Raw grant objects, connector payloads, scopes, tokens, approval references, and credentials must never be added to audit output. The current schema does not independently enforce append-only storage; database-level protection remains a future hardening requirement.
+
+### Held incident-review outline
+
+For a future suspected duplicate or stale connector effect, an approved operator procedure would:
+
+1. correlate the attempted operation with its `reject`, `takeover`, or `expiry` event;
+2. compare the durable row's connector ID, lease UUID, epoch, expiry, and release time with the adapter's normalized execution context;
+3. treat an old epoch, old lease UUID, expired lease, or released lease as non-authoritative rather than retrying it as the old holder;
+4. use only the authorized takeover path with the observed expected epoch, never ordinary acquire, for an expired or released row; and
+5. preserve evidence without assuming lease fencing provides exactly-once replay safety if an external effect may already have occurred.
+
+These are held review requirements, not instructions to bypass the current deny-all policy.
+
+### Held migration and rollback notes
+
+The checked-in `0016_salty_morlocks.sql` artifact is additive: it creates the lease and audit tables and indexes without changing existing authorization/session tables. A future database rollout would still require the repository's approved migration, backup, verification, and rollback controls. Application rollback would leave additive lease/audit tables in place; dropping them would destroy evidence and is not an automatic rollback step.
+
+This page does not authorize running migrations, connecting to PostgreSQL, initializing PGlite, or starting a connector. Those activities remain outside this held procedure and subject to repository/runtime gates.
+
+### Held security prerequisites
+
+Before this page could become operative, the activation work would need to demonstrate at least:
+
+- tenant authority derived from authenticated gateway context, not connector request fields;
+- authorized policy decisions over normalized identity and scopes, with policy TTL handling based on the requested input and coordinator hard caps still applied;
+- explicit takeover authorization and expected-epoch compare-and-swap;
+- application-boundary normalization plus any separately approved database constraints or protections;
+- validation and rejection audit before adapter side effects;
+- a concrete adapter that consumes and propagates the normalized epoch/context; and
+- existing authorization and exact-action approval controls remaining in force.
+
+M1 currently satisfies the boundary contract and default-deny posture, not these activation prerequisites.
+
+## Explicit non-goals while held
+
+This page does not authorize or claim:
+
+1. lease administration from the dashboard, CLI, HTTP, SQL console, or a connector;
+2. production connector or channel activation;
+3. exactly-once delivery, side-effect journaling, checkpoint/handoff recovery, or replay safety;
+4. automatic failover, rollback, or stale-effect recovery across Claude, Pi, Codex, Matrix, tmux, or provider sessions; or
+5. database-enforced audit immutability or database-enforced application normalization.
+
+The page may be promoted to an operative runbook only after deny-all is intentionally replaced, concrete adapters are reviewed, activation evidence exists, and this hold is explicitly removed by the owning work package.
+
+## Related contract
+
+- [M1 logical identity and fencing decision](../../DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md)
+- [MOS-PORT requirements](../../PRD.md#mos-runtime-portability-workstream-mos-port)

docs/ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md

@@ -0,0 +1,248 @@
+# Upgrade safety and recovery
+
+> **Supported route:** an already installed `mosaic` CLI using the local PGlite
+> configuration. This is a filesystem and CLI runbook; it does not activate a
+> service or connect to a database.
+
+This page covers the supported upgrade, rollback, health, and recovery checks for
+Mosaic framework configuration under `MOSAIC_HOME`. It deliberately does not
+turn the repository's deployment or PostgreSQL material into an operative
+procedure.
+
+## Support boundary
+
+Use this runbook only when all of the following are true:
+
+- `mosaic` resolves to the installed Mosaic CLI (`command -v mosaic`).
+- The active application configuration is the local tier: `tier: "local"`,
+  `storage.type: "pglite"`, and `queue.type: "local"`.
+- `DATABASE_URL` is unset. An inherited PostgreSQL DSN is outside this route and
+  must be removed before continuing.
+- `MOSAIC_STORAGE_TIER` is unset or `local`; standalone and federated overrides
+  are outside this route.
+- No Gateway, Web, Compose, or other service activation is required.
+
+The following routes are **held/non-operative** in this guide:
+
+| Route or operation                           | Status                                                                                                                                         |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| PostgreSQL-backed `standalone` storage       | Held; do not activate or probe it here.                                                                                                        |
+| Federated storage and peers                  | Held; do not activate or probe it here.                                                                                                        |
+| Bare-metal deployment                        | Held; no service installation or lifecycle action is authorized.                                                                               |
+| Gateway/Web activation or HTTP health checks | Held; `/health`, `/health/ready`, and `mosaic gateway ...` are not evidence for this route.                                                    |
+| Compose startup                              | Held; do not start a Compose profile or the full stack.                                                                                        |
+| Migration runners and tier migration         | Held; do not run `mosaic-db-migrator`, `pnpm --filter @mosaicstack/db db:migrate`, `mosaic storage migrate`, or `mosaic storage migrate-tier`. |
+
+A command being present in the CLI does not make a held route operative.
+
+## Storage and path terminology
+
+Keep these locations separate:
+
+- **`MOSAIC_HOME`** — the framework/operator configuration directory. It
+  defaults to `~/.config/mosaic` and can be overridden with `MOSAIC_HOME`.
+- **PGlite data** — the local, in-process database. The checked-in local config
+  uses `.mosaic/storage-pglite` as its storage `dataDir`; `.mosaic/queue` is the
+  local queue directory. These are project data, not framework configuration.
+- **Durable upgrade snapshots** — operator-file snapshots stored under
+  `${XDG_STATE_HOME:-$HOME/.local/state}/mosaic/backups/`. They are outside
+  `MOSAIC_HOME` and do not contain a PostgreSQL dump.
+
+The configuration tier is named `local`; the storage CLI reports the backend as
+`pglite`. PGlite is not PostgreSQL and does not require a PostgreSQL server.
+Local PGlite schema setup is adapter-owned; this page does not authorize a
+separate migration runner.
+
+## Pre-upgrade health gate
+
+Run these checks from a shell that has no inherited database DSN:
+
+```bash
+command -v mosaic
+mosaic --version
+mosaic config path
+test -d "$(mosaic config path)"
+
+env -u DATABASE_URL -u MOSAIC_STORAGE_TIER mosaic storage tier show
+env -u DATABASE_URL -u MOSAIC_STORAGE_TIER mosaic storage status
+mosaic restore --list
+```
+
+For the supported route, the storage checks should report the `pglite` backend
+and say that no network check is needed. `mosaic storage status` reports
+`PGLITE_DATA_DIR` when that variable is set; otherwise it reports the CLI's
+`:memory:` fallback. That output is an inspection of the CLI environment, not a
+claim that PGlite contents are healthy or durable.
+
+If `DATABASE_URL` is set, stop. Do not point it at a local PostgreSQL instance
+to make the check pass. If the active configuration is not local/PGlite, stop;
+no operative route is documented here.
+
+The supported health gate is intentionally limited to CLI resolution, framework
+configuration path, local storage selection, and available upgrade snapshots.
+It does not prove Gateway/Web readiness, provider connectivity, queue health, or
+PGlite data integrity.
+
+## Safe upgrade procedure
+
+1. **Record the baseline.** Save the output of `mosaic --version`,
+   `mosaic config path`, and `mosaic restore --list`. Do not copy secrets into a
+   ticket or report.
+2. **Check for updates without installing them:**
+
+   ```bash
+   mosaic update --check
+   ```
+
+   Exit status `0` means no update was reported; status `2` means an update is
+   available. Other failures are not a successful health result. The check is a
+   package-registry check and does not start Mosaic services or access storage.
+
+3. **Run the installed-CLI upgrade when approved:**
+
+   ```bash
+   mosaic update
+   ```
+
+   The command updates the installed `@mosaicstack/*` packages through npm and,
+   when the framework package changed or framework drift is detected, re-seeds
+   framework files in keep mode. Leave the default re-seed enabled. Do not use
+   `--relaunch` in this runbook: that option can restart durable fleet agents
+   and is outside the supported no-activation route. `--no-reseed` is also not a
+   normal upgrade path because it intentionally leaves framework files stale.
+
+4. **Repeat the health gate.** Confirm the CLI version, the same
+   `MOSAIC_HOME`, the local/PGlite storage selection, and the snapshot listing.
+   A successful framework upgrade must not be used as evidence that a held
+   Gateway, Web, PostgreSQL, or federated route is ready.
+
+Do not replace this procedure with a direct edit of `~/.config/mosaic`, a
+repository `tools/install.sh` invocation, a Compose startup, or a migration
+command. The supported operator entry point for this page is the installed
+`mosaic update` command.
+
+## What an upgrade protects
+
+For an existing keep-mode installation, the framework installer takes two
+separate snapshots before the file sync:
+
+1. An ephemeral whole-directory snapshot under `${TMPDIR:-/tmp}/` is used to
+   restore the previous framework directory if the sync is interrupted or
+   fails. If that restore cannot complete, the installer prints the retained
+   temporary snapshot path for manual recovery.
+2. A durable snapshot captures the existing operator-owned files before the
+   upgrade at:
+
+   ```text
+   ${XDG_STATE_HOME:-$HOME/.local/state}/mosaic/backups/pre-update-<UTC timestamp>/
+   ```
+
+   Snapshot directories are mode `0700`; captured files are mode `0600`.
+   Retention is five snapshots by default and can be changed with
+   `MOSAIC_BACKUP_RETENTION`. A durable snapshot failure is a warning and does
+   not replace the manifest and crash-rollback protections.
+
+After the keep-mode sync, the installer compares each captured operator file
+with its target. If a file was changed or removed unexpectedly, it restores the
+snapshot copy and emits a warning. A symlinked parent is not followed; that
+case is left for manual recovery from the snapshot path.
+
+Keep mode is manifest-driven and fail-safe for operator paths, but it does not
+mean every file under `MOSAIC_HOME` is user-owned. The framework contract files
+`CONSTITUTION.md`, `AGENTS.md`, and `STANDARDS.md` are refreshed by upgrades;
+keep local policy in the supported local overlays rather than editing those
+contract files as rollback data. A durable snapshot is for operator-owned
+configuration, not for the installed npm package, framework-owned contracts, or
+PGlite data.
+
+## Rollback and recovery
+
+### If the upgrade fails or is interrupted
+
+The framework sync attempts an automatic rollback from its ephemeral snapshot.
+Do not delete `MOSAIC_HOME`, the PGlite data directory, or the temporary snapshot
+named in the error. Preserve the command output, then run the health gate.
+
+If the installed framework reports that the automatic restore did not complete,
+use the durable snapshot procedure below. The durable snapshot is the recovery
+pointer that survives a successful upgrade and the removal of the temporary
+snapshot.
+
+### Restore operator configuration from a durable snapshot
+
+`mosaic restore` is confirmation-gated and reports counts and relative paths,
+not file contents. First list snapshots, then preview the selected timestamp:
+
+```bash
+mosaic restore --list
+mosaic restore --from <UTC-timestamp> --dry-run
+```
+
+If the preview is correct, run the interactive restore:
+
+```bash
+mosaic restore --from <UTC-timestamp>
+```
+
+Use `--yes` only when the overwrite has been explicitly approved:
+
+```bash
+mosaic restore --from <UTC-timestamp> --yes
+```
+
+The timestamp is the value printed by `mosaic restore --list`; the command also
+accepts the full `pre-update-<timestamp>` name. For a non-default configuration
+home, pass the same target explicitly:
+
+```bash
+mosaic restore --mosaic-home "$MOSAIC_HOME" --from <UTC-timestamp>
+```
+
+After restoring, repeat the health gate. Restore writes only the operator
+surface represented by that snapshot. It does not downgrade the installed CLI,
+restore framework-owned contract files, restore `.mosaic/storage-pglite`, or
+run any migration.
+
+### If local PGlite data is missing or corrupt
+
+Do not use a framework snapshot as a database backup. Do not run a migration
+runner, start PostgreSQL, start Compose, or activate Gateway/Web to investigate.
+The current CLI does not provide a wired PGlite export/import operation;
+`mosaic storage export` and `mosaic storage import` only print direct-copy
+guidance. Preserve the configured PGlite data directory and route data
+restoration through the held data-layer procedure rather than improvising a
+recursive delete or copy.
+
+### Recovery decision tree
+
+- **CLI or framework path is wrong:** stop, verify `command -v mosaic`,
+  `mosaic --version`, `MOSAIC_HOME`, and `mosaic config path`; do not activate a
+  held service route.
+- **Upgrade failed during framework sync:** use the installer's automatic
+  rollback first; if it reports incomplete recovery, list and preview the
+  durable snapshot, then restore it interactively.
+- **An operator file changed after a reported-successful upgrade:** select the
+  pre-upgrade snapshot with `mosaic restore --list`, preview it with `--dry-run`,
+  and restore only after reviewing the relative-path plan.
+- **PGlite data is affected:** preserve the data directory and stop at the
+  boundary described above. Framework rollback cannot recover database rows.
+- **Output requests PostgreSQL, federated, bare-metal, Compose, Gateway/Web, or
+  a migration runner:** stop; that is a held/non-operative route, not a next
+  command for this runbook.
+
+## Post-recovery verification
+
+Run the non-mutating checks again:
+
+```bash
+mosaic --version
+mosaic config path
+env -u DATABASE_URL -u MOSAIC_STORAGE_TIER mosaic storage tier show
+env -u DATABASE_URL -u MOSAIC_STORAGE_TIER mosaic storage status
+mosaic restore --list
+```
+
+A green result here means the installed CLI resolves, the framework path is
+present, the CLI selects local PGlite without a network probe, and snapshots can
+be enumerated. It does not certify database contents or any held deployment
+route.

docs/ADMIN-GUIDE/security/README.md

@@ -0,0 +1,20 @@
+# Security
+
+> **Status:** Partially migrated. The SSO provider and Discord ingress security pages are current.
+
+This chapter will contain authentication, authorization, SSO, secrets, RBAC, and security-control guidance for administrators.
+
+## Planned pages
+
+- [`sso-providers.md`](sso-providers.md) — current provider configuration, discovery, callbacks, and failure modes.
+- [`discord-ingress.md`](discord-ingress.md) — current Discord service authentication, allowlists, bindings, roles, replay, and failure controls.
+- `secrets.md` — document general secret handling after source/configuration verification.
+- `rbac.md` — document roles and permissions from the canonical implementation.
+
+The current SSO page reflects dynamic provider discovery. The Discord page documents only the verified Discord compatibility boundary; it does not claim Telegram or Matrix parity. Do not revive retired root documents or add frontend feature flags that the web flow does not consume.
+
+## Related
+
+- [`Administrator guide`](../README.md)
+- [`API documentation`](../../API/README.md)
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]

docs/ADMIN-GUIDE/security/discord-ingress.md

@@ -0,0 +1,137 @@
+# Discord ingress security
+
+> **Status:** Current Discord behavior only. Telegram shared-contract parity, Matrix channel ingress, and a gateway-wide shared adapter registry are not implemented or are not proven by the current source/tests.
+>
+> **Last verified:** 2026-08-10 against the Discord plugin, gateway ingress/authentication code, and focused tests linked in [Evidence](#evidence).
+>
+> **Audience:** Administrators provisioning the Discord remote-control boundary.
+
+This page documents the security boundary that exists today. It is not a deployment recipe for Telegram or Matrix, and it does not turn the gateway's lifecycle plugin list into a universal channel registry.
+
+## Security model
+
+Discord ingress has two current layers:
+
+1. **Native Discord admission** in `@mosaicstack/discord-plugin` applies guild/channel/user allowlists, pairing, role, rate, and thread rules before a thread is created or a message is dispatched.
+2. **Gateway compatibility admission** authenticates the Discord Socket.IO service, verifies the signed envelope again, re-checks the allowlists and binding, validates the conversation route, rejects replayed native message IDs, and then dispatches the message to the trusted agent configuration.
+
+The current gateway namespace is `/chat`. The Discord plugin connects with a Socket.IO handshake value named `discordServiceToken`; this is distinct from the environment variable name `DISCORD_SERVICE_TOKEN` that supplies the value to the plugin and gateway.
+
+### Admission and authorization order
+
+For an inbound guild message, the current implementation:
+
+1. Ignores bot-authored messages and messages without a guild. Discord DMs are therefore not handled by this ingress path, even though the client requests a direct-message intent.
+2. Uses the configured thread parent as the authorization channel for a thread. A normal Discord category parent is never substituted for a text channel.
+3. Requires the guild, authorization channel, and user to appear in their respective allowlists.
+4. Resolves a configuration-owned binding and paired user. `viewer` cannot send a turn. Ordinary `send` requires `operator` or `admin`; `approve` and `stop` require `admin`.
+5. Applies the message and mention-thread rate limits before any thread creation or gateway dispatch.
+6. Derives the route from the binding's logical-agent instance and the response channel/thread. The route does not accept a provider, model, harness, process, or runtime-session selector from Discord.
+7. Creates or reuses a thread only after the checks above pass.
+
+The gateway then verifies the HMAC-SHA-256 envelope with `DISCORD_SERVICE_TOKEN`, re-applies the allowlists and binding/role check, requires the conversation ID to match the bound logical agent and channel/thread, and claims the native Discord message ID in a bounded replay cache. The default replay cache is in-process, retains IDs for 15 minutes, and is bounded at 10,000 entries; it is not a durable inbox.
+
+For ordinary chat, the gateway attempts persistence and dispatch using `DISCORD_SERVICE_USER_ID`; `DISCORD_SERVICE_TENANT_ID` is used when configured and otherwise ordinary chat falls back to the service user ID as its tenant. The Discord external route is not a UUID, while persisted conversation IDs are UUIDs; no current route-to-UUID mapping proves that ordinary Discord persistence succeeds. The gateway may continue dispatch after a persistence/binding failure, so successful live delivery is not durable-history evidence.
+
+Privileged approval and stop additionally require a configured tenant, a paired `mosaicUserId`, and a previously enrolled durable session. The durable session's logical agent must match the binding before approval or stop is accepted. The approval is consumed once against the exact runtime target; the Discord service account is not substituted for the approving paired user.
+
+The trusted `agentConfigId` in each binding is resolved by the gateway. Its provisioned agent name must exactly equal `instanceId`. Discord cannot choose an arbitrary agent, provider, or model in the message payload, and Discord ingress does not use the general routing engine for a new session.
+
+## Required configuration
+
+The gateway's current plugin factory is in [`plugin.module.ts`](../../../apps/gateway/src/plugin/plugin.module.ts). When `DISCORD_BOT_TOKEN` is present, the following Discord values are required or validated as shown:
+
+| Name                                    | Required/current behavior                                                                                                                                               |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DISCORD_BOT_TOKEN`                     | Enables the Discord plugin and supplies the Discord bot credential.                                                                                                     |
+| `DISCORD_SERVICE_TOKEN`                 | Required when the bot is enabled. Authenticates the Socket.IO service handshake and signs/verifies ingress envelopes. Treat as a high-entropy secret.                   |
+| `DISCORD_SERVICE_USER_ID`               | Required when the bot is enabled. Provisioned Mosaic service principal used for ordinary Discord dispatch and attempted persistence; durable history is not guaranteed. |
+| `DISCORD_SERVICE_TENANT_ID`             | Not required to start ordinary Discord chat, but required for the `/approve` and `/stop <approval>` control path. Use the provisioned tenant for the service boundary.  |
+| `DISCORD_GATEWAY_URL`                   | Base gateway URL. The plugin connects to `${DISCORD_GATEWAY_URL}/chat`; the gateway factory default is `http://localhost:14242`.                                        |
+| `DISCORD_GUILD_ID`                      | Optional guild ID used only by the current project-channel provisioning helper. It is not the message authorization allowlist.                                          |
+| `DISCORD_ALLOWED_GUILD_IDS`             | Required, comma-separated guild IDs. Empty or missing values fail closed during plugin creation.                                                                        |
+| `DISCORD_ALLOWED_CHANNEL_IDS`           | Required, comma-separated parent text-channel IDs. Thread messages are checked against their configured parent.                                                         |
+| `DISCORD_ALLOWED_USER_IDS`              | Required, comma-separated Discord user IDs. This allowlist is checked in addition to `pairedUsers`.                                                                     |
+| `DISCORD_INTERACTION_BINDINGS`          | Required, non-empty JSON array of configuration-owned bindings. Malformed or empty data fails plugin creation.                                                          |
+| `DISCORD_MESSAGE_RATE_LIMIT_PER_MINUTE` | Optional positive integer; default is `30` authorized turns per guild/channel/user window. Zero, negative, and non-integer values are rejected.                         |
+| `DISCORD_THREAD_RATE_LIMIT_PER_MINUTE`  | Optional positive integer; default is `5` mention-triggered thread routes per guild/channel/user window. Invalid values are rejected.                                   |
+
+`MOSAIC_AGENT_NAME` and `MOSAIC_AGENT_CONFIG_ID` are not substitutes for a Discord binding. The current Discord binding uses `instanceId` and `agentConfigId` inside `DISCORD_INTERACTION_BINDINGS`; do not invent a different environment-based routing contract.
+
+### Binding shape
+
+Use placeholders for identifiers and keep credentials out of the JSON:
+
+```json
+[
+  {
+    "instanceId": "interaction-agent",
+    "agentConfigId": "provisioned-agent-config-id",
+    "guildId": "guild-id",
+    "channelId": "parent-channel-id",
+    "pairedUsers": {
+      "discord-user-id": {
+        "role": "operator",
+        "mosaicUserId": "provisioned-mosaic-user-id"
+      }
+    }
+  }
+]
+```
+
+Each binding requires `instanceId`, `agentConfigId`, `guildId`, `channelId`, and a non-empty `pairedUsers` object. Pairing roles are `viewer`, `operator`, and `admin`. A role-only pairing remains accepted for ordinary non-privileged compatibility, but it has no `mosaicUserId` and cannot authorize the privileged approval/stop path. The guild and parent channel must also be present in their allowlists.
+
+The bot needs permission to view and send messages in the configured channels and to create and send public threads. A category parent is not an authorization boundary. A thread inherits authorization only from its configured parent text channel.
+
+### Secret handling
+
+Supply `DISCORD_BOT_TOKEN` and `DISCORD_SERVICE_TOKEN` through the approved runtime secret mechanism. Do not commit them, put them in binding JSON, or pass them on a command line.
+
+The current `mosaic gateway config --set KEY=VALUE` implementation writes the gateway `.env` file and prints the value in its confirmation; its mask list does not include `DISCORD_SERVICE_TOKEN`. Do **not** use that command for the service token. `mosaic gateway config --edit` exists for local configuration, but production secret provisioning must remain outside the repository and follow the approved secret path.
+
+## Applying configuration safely
+
+These are the current CLI commands exposed by `@mosaicstack/mosaic`; they manage the gateway daemon and do not constitute a Discord protocol:
+
+```bash
+mosaic gateway install
+mosaic gateway config --edit
+mosaic gateway status
+mosaic gateway verify
+mosaic gateway restart
+mosaic gateway logs --lines 50
+```
+
+The daemon reads its environment from `~/.config/mosaic/gateway/.env` by default; `MOSAIC_GATEWAY_HOME` can change that home. `mosaic gateway config --set KEY=VALUE` and `--unset KEY` are also implemented for non-secret values. After changing Discord configuration, restart the gateway so the plugin factory is rebuilt. `mosaic gateway status` and `mosaic gateway verify` check the gateway daemon/health surfaces; the current lifecycle host does not expose a channel-specific `healthAll` command, so a green gateway check alone is not proof that Discord is connected.
+
+## Failure and abuse behavior
+
+| Condition                                                                                      | Current result                                                                                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Missing service token/user, allowlist, or interaction bindings when Discord is enabled         | Gateway plugin creation fails rather than enabling an unconfigured remote-control surface.                                                                                                                         |
+| Invalid optional rate limit                                                                    | Plugin creation fails; values must be positive integers.                                                                                                                                                           |
+| Unallowlisted guild/channel/user, unpaired user, or insufficient role                          | Message is ignored before thread creation and gateway dispatch.                                                                                                                                                    |
+| Mentioned message cannot create or fetch its requested thread                                  | The message is not dispatched because its response target cannot be honored.                                                                                                                                       |
+| Invalid HMAC, malformed envelope, route mismatch, wrong binding, or replayed native message ID | Gateway rejects the ingress without dispatch.                                                                                                                                                                      |
+| Unsafe attachment metadata or URL                                                              | Gateway rejects the message before acknowledgement/dispatch. Current bounds include at most 10 attachments, HTTPS URLs without credentials, query strings, or fragments, and bounded ID/name/URL/metadata lengths. |
+| Missing `DISCORD_SERVICE_TENANT_ID` for approval/stop                                          | The privileged control handler returns without creating or consuming an approval.                                                                                                                                  |
+| Agent configuration ID does not resolve or its name differs from `instanceId`                  | Gateway refuses to create the Discord-bound session.                                                                                                                                                               |
+| External route cannot be persisted as a UUID conversation                                      | Gateway may still dispatch live output; durable history and restart/resume continuity are not guaranteed and must not be inferred from delivery.                                                                   |
+
+## Explicitly not current
+
+- **Telegram:** `TELEGRAM_BOT_TOKEN` and `TELEGRAM_GATEWAY_URL` can instantiate the raw legacy Telegram plugin, but that plugin does not use the shared channel DTOs, Discord-style service authentication, allowlists, pairing, route validation, or a tested gateway security boundary. Do not treat these variables as a secured Telegram equivalent of the Discord configuration above.
+- **Matrix:** No current gateway channel adapter, binding, authentication path, or focused channel test establishes Matrix ingress. Matrix-related fleet/runtime code is not evidence of a Matrix channel deployment procedure.
+- **Shared registry parity:** The current gateway `PLUGIN_REGISTRY` hosts lifecycle wrappers (`name`, `start`, `stop`, and optional project provisioning). It does not expose a universal channel health/ingress/egress registry. That is follow-up work, not an administrator capability today.
+
+## Evidence
+
+- [`plugins/discord/src/index.ts`](../../../plugins/discord/src/index.ts) — Discord allowlists, bindings, roles, thread routing, signed envelope, typed ingress/egress, limits, retry, and health.
+- [`plugins/discord/src/index.test.ts`](../../../plugins/discord/src/index.test.ts) — authorization ordering, thread behavior, attachments, stable routes, egress, rate limits, and health.
+- [`apps/gateway/src/chat/chat.gateway.ts`](../../../apps/gateway/src/chat/chat.gateway.ts) — `/chat` authentication, envelope validation, replay, trusted agent selection, ordinary dispatch, approval, and stop.
+- [`apps/gateway/src/chat/chat.gateway-auth.ts`](../../../apps/gateway/src/chat/chat.gateway-auth.ts) — timing-safe service-token and BetterAuth session validation.
+- [`apps/gateway/src/plugin/discord-ingress.security.spec.ts`](../../../apps/gateway/src/plugin/discord-ingress.security.spec.ts) — signature, allowlist, replay, attachment, binding, approval, stop, and logical-agent checks.
+- [`apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts`](../../../apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts) — control-flow evidence with explicit durable-session pre-enrollment, not proof of ordinary Discord persistence.
+- [`packages/mosaic/src/commands/gateway.ts`](../../../packages/mosaic/src/commands/gateway.ts) and [`gateway/config.ts`](../../../packages/mosaic/src/commands/gateway/config.ts) — verified gateway CLI command names and configuration behavior.
+- [Channel protocol architecture](../../DEVELOPER-GUIDE/architecture/channel-protocol.md) — canonical shared-contract and parity boundary.
+- [Discord conversation workflow](../../USER-GUIDE/workflows/discord-conversations.md) — end-user behavior.

docs/ADMIN-GUIDE/security/sso-providers.md

@@ -0,0 +1,192 @@
+---
+title: SSO Providers
+type: runbook
+audience: admin
+status: current
+source_of_truth: false
+---
+
+# SSO Providers
+
+Configure optional enterprise single sign-on for Mosaic Stack through Better Auth's generic OAuth integration. The gateway owns provider configuration and discovery; the web application renders only providers reported by the gateway.
+
+> **Current behavior:** Authentik, WorkOS, and Keycloak are supported in the checked-in implementation. Authentik and WorkOS use OIDC. Keycloak supports OIDC and an optional direct SAML login URL. The web application does **not** read `NEXT_PUBLIC_WORKOS_ENABLED` or `NEXT_PUBLIC_KEYCLOAK_ENABLED`; provider buttons are discovered dynamically from the gateway.
+
+## Prerequisites
+
+Before configuring a provider, establish these gateway settings:
+
+- `BETTER_AUTH_URL` — the public base URL used to construct OAuth callback URLs.
+- `BETTER_AUTH_SECRET` — a strong secret for Better Auth sessions and tokens.
+- `GATEWAY_CORS_ORIGIN` — the web origin or comma-separated origins allowed by the gateway.
+
+Keep client secrets and Better Auth secrets in the deployment secret store. Do not commit them to `.env` files or expose them to the web bundle.
+
+## Provider configuration
+
+### Authentik OIDC
+
+Set all three variables to enable Authentik:
+
+```bash
+AUTHENTIK_ISSUER=https://auth.example.com/application/o/mosaic
+AUTHENTIK_CLIENT_ID=...
+AUTHENTIK_CLIENT_SECRET=...
+```
+
+The implementation derives OIDC discovery and endpoint URLs from `AUTHENTIK_ISSUER`. An optional team-claim label can be exposed in provider discovery:
+
+```bash
+AUTHENTIK_TEAM_SYNC_CLAIM=groups
+```
+
+The default reported claim is `groups`. The discovery payload reports this claim; verify any downstream membership-sync behavior separately before treating it as an authorization guarantee.
+
+Register this redirect URI with the Authentik application:
+
+```text
+{BETTER_AUTH_URL}/api/auth/oauth2/callback/authentik
+```
+
+### WorkOS OIDC
+
+Set all three variables to enable WorkOS:
+
+```bash
+WORKOS_ISSUER=https://your-company.authkit.app
+WORKOS_CLIENT_ID=client_...
+WORKOS_CLIENT_SECRET=...
+```
+
+Use the WorkOS AuthKit issuer or custom authentication domain, not a raw WorkOS REST API hostname. Mosaic derives the OIDC discovery URL by appending `/.well-known/openid-configuration` to the issuer. WorkOS uses PKCE and issuer validation in the current auth configuration.
+
+An optional team-claim label can be exposed in provider discovery:
+
+```bash
+WORKOS_TEAM_SYNC_CLAIM=organization_id
+```
+
+The default reported claim is `organization_id`. The discovery payload reports this claim; verify any downstream membership-sync behavior separately before treating it as an authorization guarantee.
+
+Register this redirect URI with the WorkOS application:
+
+```text
+{BETTER_AUTH_URL}/api/auth/oauth2/callback/workos
+```
+
+### Keycloak OIDC
+
+Use either an explicit issuer or the URL-plus-realm form. The client ID and secret are required in both forms.
+
+Explicit issuer:
+
+```bash
+KEYCLOAK_ISSUER=https://auth.example.com/realms/mosaic
+KEYCLOAK_CLIENT_ID=mosaic
+KEYCLOAK_CLIENT_SECRET=...
+```
+
+Derived issuer:
+
+```bash
+KEYCLOAK_URL=https://auth.example.com
+KEYCLOAK_REALM=mosaic
+KEYCLOAK_CLIENT_ID=mosaic
+KEYCLOAK_CLIENT_SECRET=...
+```
+
+`KEYCLOAK_ISSUER` takes precedence when both forms are present. Keycloak uses PKCE and issuer validation in the current auth configuration.
+
+An optional team-claim label can be exposed in provider discovery:
+
+```bash
+KEYCLOAK_TEAM_SYNC_CLAIM=groups
+```
+
+The default reported claim is `groups`. The discovery payload reports this claim; verify any downstream membership-sync behavior separately before treating it as an authorization guarantee.
+
+Register this redirect URI with the Keycloak client:
+
+```text
+{BETTER_AUTH_URL}/api/auth/oauth2/callback/keycloak
+```
+
+### Keycloak direct SAML fallback
+
+The current web flow supports a direct SAML link for Keycloak when `KEYCLOAK_SAML_LOGIN_URL` is configured:
+
+```bash
+KEYCLOAK_SAML_LOGIN_URL=https://auth.example.com/realms/mosaic/protocol/saml
+```
+
+This creates a configured Keycloak provider with `loginMode: saml`. The web login button links directly to the supplied URL as `Continue with Keycloak (SAML)`; there is no Better Auth OIDC callback for this mode. The URL must be the provider's valid SAML launch URL for the deployment.
+
+A SAML-only Keycloak configuration does not require the Keycloak OIDC client variables. Do not combine an incomplete OIDC variable set with SAML-only configuration: partial OIDC configuration is rejected during auth setup.
+
+## Callback and discovery contract
+
+Better Auth is mounted at `/api/auth`. OIDC callbacks use:
+
+```text
+{BETTER_AUTH_URL}/api/auth/oauth2/callback/{providerId}
+```
+
+The gateway exposes provider discovery at:
+
+```text
+GET /api/sso/providers
+```
+
+The response includes `authentik`, `workos`, and `keycloak` records with:
+
+- `configured` — whether a usable OIDC or Keycloak SAML configuration is present.
+- `protocols` — supported protocols for the provider record.
+- `loginMode` — `oidc`, `saml`, or `null`.
+- `callbackPath` — the OIDC callback path, or `null` for SAML-only mode.
+- `teamSync` — the configured/default claim label exposed to the UI.
+- `samlFallback` — whether a direct Keycloak SAML URL is configured.
+- `warnings` — partial OIDC configuration warnings when reported.
+
+The web login page filters this response to configured providers. OIDC buttons use Better Auth's `signIn.oauth2` flow. A configured Keycloak SAML fallback is rendered as a direct link. No provider-specific `NEXT_PUBLIC_*_ENABLED` flag is required or consumed.
+
+## Configuration procedure
+
+1. Set `BETTER_AUTH_URL` to the public gateway URL that the identity provider can reach.
+2. Set `BETTER_AUTH_SECRET` and the correct `GATEWAY_CORS_ORIGIN` values.
+3. Choose one provider configuration above and set its complete required variable group.
+4. Register the exact OIDC callback URI with the identity provider, when using OIDC.
+5. Restart or redeploy the gateway so it loads the changed environment.
+6. Inspect discovery without exposing secrets:
+
+   ```bash
+   curl "$BETTER_AUTH_URL/api/sso/providers"
+   ```
+
+7. Open the web login page and confirm that only configured providers are shown.
+8. Complete a sign-in and verify the callback returns to the configured application.
+
+## Partial configuration and failure modes
+
+Provider configuration is optional. If no provider variables are set, the gateway can run without SSO providers and the web login page renders no SSO section.
+
+For Authentik and WorkOS, setting only part of the issuer/client ID/client secret group raises a configuration error. For Keycloak OIDC, the client ID, client secret, and either an explicit issuer or a complete URL-plus-realm pair are required. Empty or whitespace-only values are treated as unset.
+
+Common failures:
+
+| Symptom                                               | Check                                                                                                                |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Provider does not appear on the login page            | Query `/api/sso/providers`; verify the complete provider variable group is present in the gateway environment.       |
+| OAuth callback is rejected                            | Compare the registered redirect URI character-for-character with `BETTER_AUTH_URL` and the provider callback path.   |
+| Provider is shown but sign-in cannot start            | Check `loginMode`, issuer discovery, client credentials, and gateway logs.                                           |
+| Keycloak SAML button is absent                        | Set `KEYCLOAK_SAML_LOGIN_URL` to the provider's direct launch URL and reload the gateway.                            |
+| Startup/auth initialization reports missing variables | Remove the partial provider configuration or provide the complete required group.                                    |
+| SSO succeeds but team membership is unexpected        | Treat `teamSync.claim` as discovery metadata and verify the actual claim mapping and membership-sync implementation. |
+
+Do not enable a provider by adding the obsolete `NEXT_PUBLIC_WORKOS_ENABLED` or `NEXT_PUBLIC_KEYCLOAK_ENABLED` variables. They are not read by the current web application.
+
+## Related
+
+- [Administrator guide](../README.md)
+- [Security chapter](README.md)
+- [API documentation index](../../API/README.md)
+- [Documentation atlas](../../README.md)

docs/API/README.md

@@ -0,0 +1,31 @@
+# API Documentation
+
+> **Status:** Scaffold only. The canonical gateway contract has not yet been migrated into this directory.
+
+This directory is the single API documentation boundary. `OPENAPI.yaml` will be the machine-readable contract, and `ENDPOINTS.md` will provide the human-readable endpoint, authentication, permission, and error index. Neither file exists here yet; do not describe this scaffold as a complete API reference.
+
+## Start here
+
+- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
+- [Documentation sitemap](../SITEMAP.md) — current API transition status and authority-gated backlog.
+- [Documentation catalog audit](../reports/documentation/2026-08-10-docs-catalog-audit.md) — current API artifact inventory and migration evidence.
+
+## Contract map
+
+| Artifact                                       | Purpose                                                           | Status                                                  |
+| ---------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
+| `OPENAPI.yaml`                                 | Canonical machine-readable HTTP/WebSocket API contract.           | Planned; not present yet.                               |
+| `ENDPOINTS.md`                                 | Human index for endpoint behavior, auth, permissions, and errors. | Planned; not present yet.                               |
+| [`../openapi-tess.yaml`](../openapi-tess.yaml) | Legacy Tess-scoped OpenAPI artifact with 17 paths.                | Migration candidate; not the complete gateway contract. |
+
+A contract migration must verify paths, schemas, authentication, permissions, error behavior, and generated/client references before the legacy artifact is retired. Keep scoped contracts explicitly labeled if they remain alongside the consolidated contract.
+
+## Authoring boundary
+
+New API contracts belong here. Use `OPENAPI.yaml` for machine-readable authority and `ENDPOINTS.md` for human-readable constraints that OpenAPI cannot fully express. Guide books may explain usage workflows, but must link back to this directory rather than copying endpoint definitions.
+
+## Related
+
+- [[README|Documentation contract]]
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
+- [[ADMIN-GUIDE/security/README|SSO provider chapter]]

docs/DEVELOPER-GUIDE/README.md

@@ -0,0 +1,50 @@
+# Developer Guide
+
+> **Status:** Partially migrated. Architecture, lease-broker verification, and channel-adapter authoring pages are current; other contributor chapters remain unmigrated.
+
+This book is the canonical home for architecture, package and application guides, local development, testing, contribution workflow, and integration authoring. User-facing procedures belong in [`USER-GUIDE/`](../USER-GUIDE/); operator procedures belong in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); API contracts belong in [`API/`](../API/).
+
+## Start here
+
+- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
+- [Architecture index](architecture/README.md) — current architecture chapter scaffold.
+- [Documentation audit](../reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence-based migration inventory.
+- [Product requirements](../PRD.md) — normative requirements, currently marked draft.
+
+## Chapter map
+
+| Chapter                                   | Scope                                                                | Status                                         |
+| ----------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------- |
+| [`architecture/`](architecture/README.md) | System model, components, data flow, security model, ADRs, and RFCs. | Partially migrated.                            |
+| `packages/`                               | Package- and application-level contracts and guides.                 | Scaffold only.                                 |
+| `local-development/`                      | Safe local setup and development routes.                             | Scaffold only.                                 |
+| `testing/`                                | Test strategy, verification, and quality gates.                      | Lease-broker verification boundary is current. |
+| `contributing/`                           | Contribution, review, and delivery workflow.                         | Scaffold only.                                 |
+| `integrations/`                           | Plugin, provider, and adapter authoring.                             | Channel-adapter authoring boundary is current. |
+
+### Current contributor pages
+
+- [Lease-broker operations and verification](testing/lease-broker-operations.md) — safe static/test commands plus explicitly held live operations.
+- [Channel adapters](integrations/channel-adapters.md) — current shared contracts and Discord reference boundary; future adapter parity is draft.
+
+Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
+
+## Migration backlog — not current developer guidance
+
+These are source candidates or stale records, not verified current instructions:
+
+- [`archived TUI PRD`](../archive/tui/PRD-TUI_Improvements.md) — contradicted/stale; it references a missing `packages/cli`, while current TUI code is under `packages/mosaic`.
+- [`archived TUI task ledger`](../archive/tui/TASKS-TUI_Improvements.md) — historical task ledger; its status and worktree claims require revalidation.
+- `_old_structure/guides/dev-guide.md` — quarantined historical source; verify paths and commands before promotion. See the [documentation catalog](../reports/documentation/2026-08-10-docs-catalog-audit.md) for its disposition.
+
+Do not make a legacy or archived page current by linking it from a chapter as if it were already promoted.
+
+## Authoring boundary
+
+New developer documentation belongs under one of the chapter directories above. Architecture decisions and RFCs must identify their status and authority; executable behavior must be checked against current code and tests.
+
+## Related
+
+- [[README|Documentation contract]]
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
+- [[API/README|API index]]

docs/DEVELOPER-GUIDE/architecture/README.md

@@ -0,0 +1,50 @@
+# Architecture
+
+> **Status:** Partially migrated. The lease-broker security-contract pages below are current references; the remaining architecture pages are still being classified.
+
+This chapter is the canonical home for Mosaic Stack's system model, component boundaries, data and control flow, security model, architecture decisions, and RFCs. It explains why the system has its shape; it does not replace [`PRD.md`](../../PRD.md), [`TASKS.md`](../../TASKS.md), or the API contract.
+
+## Promoted pages
+
+- [`lease-broker-protocol.md`](lease-broker-protocol.md) — authenticated Unix-socket protocol, identity binding, framing, persistence, and lease transitions.
+- [`lease-broker-security.md`](lease-broker-security.md) — identity, ancestry, filesystem, whole-class, observer, and named residual security boundaries.
+- [`mutator-class-gate.md`](mutator-class-gate.md) — default-deny tool authorization, runtime adapters, launch choke point, and parser assurance boundary.
+- [`compaction-revocation.md`](compaction-revocation.md) — Claude/Pi observer lifecycle, runtime generations, revocation, and the bounded residual stale window.
+- [`channel-protocol.md`](channel-protocol.md) — current shared channel DTOs and Discord compatibility baseline, with unimplemented adapter work explicitly marked draft.
+- [`decisions/mos-runtime-portability-m1.md`](decisions/mos-runtime-portability-m1.md) — current logical identity, connector lease, grant, audit, and fencing decision; connector activation remains held.
+
+These pages are current security-contract references and are consumed by the lease-broker acceptance suites. Their live deployment gaps remain explicitly labeled in the pages; this migration does not change runtime behavior.
+
+## Planned pages
+
+| Path                                | Purpose                                                               | Status                    |
+| ----------------------------------- | --------------------------------------------------------------------- | ------------------------- |
+| `system-overview.md`                | Platform boundary and major request, event, and agent-runtime flows.  | Planned.                  |
+| `component-map.md`                  | Apps, packages, plugins, and dependency ownership.                    | Planned.                  |
+| `data-flow.md`                      | Data, event, and control-plane movement.                              | Planned.                  |
+| `security-model.md`                 | Trust boundaries, authority, authentication, and authorization model. | Planned.                  |
+| [`decisions/`](decisions/README.md) | Approved architecture decision records.                               | Partially migrated.       |
+| [`rfcs/`](rfcs/README.md)           | Proposals and protocol RFCs.                                          | Draft egress RFC indexed. |
+
+### Draft RFCs
+
+- [`rfcs/optional-ai-egress-gateways.md`](rfcs/optional-ai-egress-gateways.md) — proposed model-egress boundary; not approved or integrated.
+
+Promoted pages must be linked here, from [`DEVELOPER-GUIDE/README.md`](../README.md), and from [`SITEMAP.md`](../../SITEMAP.md). Do not create duplicate architecture pages in `docs/mosaic-stack/` or the docs root.
+
+## Migration backlog — not current architecture
+
+- [`docs/README.md`](../../README.md) — current documentation contract and placement rules.
+- [`Documentation information architecture design`](../../plans/2026-08-10-docs-information-architecture-design.md) — approved documentation structure decision, not product architecture.
+- [`Documentation catalog audit`](../../reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations, not normative architecture.
+
+## Source-of-truth boundary
+
+Architecture pages explain approved design and current system boundaries. Requirements remain in [`PRD.md`](../../PRD.md); active work remains in [`TASKS.md`](../../TASKS.md); executable behavior remains authoritative in source and tests. Draft proposals belong in `rfcs/` or [`docs/plans/`](../../plans/), with status clearly labeled.
+
+## Related
+
+- [[README|Documentation contract]]
+- [[DEVELOPER-GUIDE/README|Developer guide]]
+- [[PRD|Product requirements]]
+- [[API/README|API index]]

docs/DEVELOPER-GUIDE/architecture/channel-protocol.md

@@ -0,0 +1,285 @@
+# Channel protocol architecture
+
+> **Status:** Current shared type contract and Discord compatibility baseline. The shared gateway registry, Telegram parity, Matrix integration, identity-linking, and multi-surface multiplexing described below are draft or unimplemented.
+>
+> **Audience:** Developers maintaining `@mosaicstack/types`, channel plugins, the gateway chat/plugin boundaries, or future official adapters.
+>
+> **Last verified:** 2026-08-10 against the source and focused tests listed in [Evidence](#evidence).
+>
+> **Authority:** Executable source and tests are authoritative for current behavior. This page explains the boundary; it is not a runtime registry, an API contract, a requirements document, or proof that every channel uses the shared DTOs.
+
+## Reading this page
+
+This page intentionally separates three states:
+
+- **Current** — implemented in the repository and supported by the cited tests.
+- **Compatibility** — an existing wire path that preserves current behavior but does not yet mean that the shared channel ports are wired through the gateway.
+- **Draft** — a design direction or follow-up work item. Draft sections have no implementation authority and must not be used as instructions for operating Telegram, Matrix, identity linking, or cross-surface fanout.
+
+The migration from `docs/_old_structure/architecture/channel-protocol.md` is a documentation correction. It does not add adapters, change gateway behavior, change authentication, or create database objects.
+
+## Authority and evidence boundaries
+
+| Boundary                                   | Current authority                                                                                                                                                                                                                     | What this page may claim                                                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Shared channel types and ports             | [`channel.dto.ts`](../../../packages/types/src/channel/channel.dto.ts), [`channel-adapter.ts`](../../../packages/types/src/channel/channel-adapter.ts), and their exports                                                             | The TypeScript shapes and method signatures that are currently published from `@mosaicstack/types`.                               |
+| Discord native behavior                    | [`plugins/discord/src/index.ts`](../../../plugins/discord/src/index.ts) and [`index.test.ts`](../../../plugins/discord/src/index.test.ts)                                                                                             | The Discord allowlist, pairing, role, thread, ingress, egress, retry, and health behavior covered by source and tests.            |
+| Discord gateway compatibility              | [`chat.gateway.ts`](../../../apps/gateway/src/chat/chat.gateway.ts), [`chat.gateway-auth.ts`](../../../apps/gateway/src/chat/chat.gateway-auth.ts), and the focused gateway tests                                                     | The signed Socket.IO service path, gateway validation, raw chat events, and current session dispatch behavior.                    |
+| Plugin hosting                             | [`plugin.interface.ts`](../../../apps/gateway/src/plugin/plugin.interface.ts), [`plugin.module.ts`](../../../apps/gateway/src/plugin/plugin.module.ts), and [`plugin.service.ts`](../../../apps/gateway/src/plugin/plugin.service.ts) | The lifecycle registry that exists today. It is not evidence of a shared `OfficialChannelAdapter` registry.                       |
+| Telegram                                   | [`plugins/telegram/src/index.ts`](../../../plugins/telegram/src/index.ts) and [`package.json`](../../../plugins/telegram/package.json)                                                                                                | The raw legacy behavior that exists. It is not evidence of shared-contract parity or a working authenticated gateway integration. |
+| Matrix, identity linking, and multiplexing | No matching current implementation and test boundary was found for the old page's designs                                                                                                                                             | These topics remain explicitly draft/unimplemented here.                                                                          |
+
+The current source boundaries also distinguish two identities:
+
+1. A channel route carries a configuration-owned logical agent and response destination.
+2. The gateway chooses provider, model, and runtime session internally. Durable-session enrollment is separate and is not proven by the external channel route alone.
+
+A route is therefore not a claim that a channel adapter owns or exposes a harness, provider, model, process, or native runtime-session identity.
+
+## Current shared contract
+
+The channel types are exported through `packages/types/src/channel/index.ts` and `packages/types/src/index.ts`. They define a transport-neutral vocabulary, but TypeScript interfaces alone do not prove that every producer or consumer uses that vocabulary.
+
+### DTOs
+
+The current DTO surface is:
+
+| Type                            | Current shape and boundary                                                                                                                                                  |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ChannelMetadataValue`          | JSON-safe strings, numbers, booleans, `null`, arrays, and nested objects.                                                                                                   |
+| `ChannelAttachmentDto`          | `id`, `name`, `mimeType`, `url`, and optional `sizeBytes`.                                                                                                                  |
+| `ChannelMessageDto`             | `id`, `channelName`, `channelId`, `senderId`, `senderKind`, `content`, `contentKind`, `timestamp`, and `metadata`; `threadId`, `replyToId`, and `attachments` are optional. |
+| `ChannelAuthorizedPrincipalDto` | Native `channelUserId`, a `viewer`/`operator`/`admin` role, and an optional `mosaicUserId` for privileged gateway policy.                                                   |
+| `ChannelBindingDto`             | Configuration-owned `bindingId`, `channelName`, `workspaceId`, `channelId`, `logicalAgentId`, and paired `principals`. Credentials are intentionally absent.                |
+| `ChannelResponseTargetDto`      | `channelId` and an optional `threadId`.                                                                                                                                     |
+| `ChannelConversationRouteDto`   | `bindingId`, `logicalAgentId`, `conversationId`, `channelName`, `authorizationChannelId`, and `responseTarget`.                                                             |
+| `ChannelIngressDto`             | `correlationId`, `nativeMessageId`, an operation, an authorized principal, a normalized message, and a stable route.                                                        |
+| `ChannelEgressDto`              | `correlationId`, a normalized message, and the stable route.                                                                                                                |
+| `ChannelAdapterHealthDto`       | `status` of `connected`, `degraded`, or `disconnected`, with optional `detail`.                                                                                             |
+
+The available operations are `message.send`, `approval.create`, and `session.stop`. The available sender kinds are `user`, `agent`, and `system`; content kinds are `text`, `markdown`, `code`, `image`, and `file`.
+
+### Lifecycle and ports
+
+The shared adapter file currently defines these seams:
+
+```typescript
+interface OfficialChannelAdapter {
+  readonly name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  health(): Promise<ChannelAdapterHealthDto>;
+}
+
+interface ChannelIngressPort {
+  receive(ingress: ChannelIngressDto): Promise<void>;
+}
+
+interface ChannelEgressPort {
+  send(egress: ChannelEgressDto): Promise<void>;
+}
+```
+
+`ChannelDeliveryError` currently has only these codes: `invalid_route`, `destination_unavailable`, and `delivery_failed`. The type surface does not define a revoked-auth error code or an executable protocol version `1.0.0`.
+
+### Stable route rule
+
+`ChannelConversationRouteDto` deliberately omits provider, harness, model, process, and native runtime-session fields. The Discord implementation derives its current conversation address as:
+
+```text
+<logical-agent-id>:discord:<response-channel-id>
+```
+
+and derives its binding address from the configured guild, parent channel, and logical-agent instance. The gateway validates the expected Discord conversation address before dispatch. This is a route-integrity rule, not a claim that the shared DTO is already the gateway's universal session API.
+
+### What is and is not wired today
+
+The Discord class implements both `OfficialChannelAdapter` and `ChannelEgressPort`, and accepts an optional `ChannelIngressPort` dependency. The direct ingress seam is exercised by the Discord tests. However, the gateway host currently registers `IChannelPlugin` objects with only `name`, `start`, `stop`, and optional project provisioning. Its `PLUGIN_REGISTRY` is an array of those lifecycle wrappers; it does not expose `health()`, `ChannelRegistry.healthAll()`, or shared port wiring.
+
+The gateway's current output path is also still Socket.IO event streaming (`agent:start`, `agent:text`, and `agent:end`). No gateway service in the cited implementation produces a `ChannelEgressDto` for a registered adapter. The shared ports are therefore current contracts and a tested Discord seam, not a completed gateway-wide adapter architecture.
+
+## Current Discord compatibility path
+
+Discord is the current reference implementation for the shared contract and the compatibility path. Its behavior is split between native Discord translation in the plugin and gateway-side validation/dispatch.
+
+### Native ingress and authorization
+
+For an inbound Discord message, the plugin currently:
+
+1. Ignores bot-authored messages and messages without a guild.
+2. Uses the configured parent text channel as the authorization channel only when the message is in a thread. A normal channel's category parent is not substituted for the channel itself.
+3. Applies default-deny guild, channel, and user allowlists.
+4. Resolves a configuration-owned binding and paired user role before creating a thread or dispatching to the gateway. `viewer` cannot send turns; approval and stop are admin operations.
+5. Applies per-user/channel message and mention-thread rate limits before Discord thread creation or gateway dispatch.
+6. Builds a stable route from the configured logical-agent instance and the response channel/thread.
+7. Normalizes the authorized turn to `ChannelIngressDto` when a direct `ingressPort` dependency is supplied.
+
+The normalized `ChannelMessageDto` currently includes:
+
+- `channelName: "discord"`;
+- the response channel as `channelId`;
+- the Discord author as `senderId` and `senderKind: "user"`;
+- `markdown` for non-empty text, or `image`/`file` for attachment-only input;
+- attachments mapped to `ChannelAttachmentDto`; and
+- `metadata` containing `channelMessageId` and `guildId`.
+
+The implementation does **not** currently populate `channelType`, mentions, embeds, or `replyToId` in that normalized metadata. The old page's broader Discord metadata table must not be treated as current behavior.
+
+### Direct shared ingress versus compatibility envelope
+
+When a direct port is present, the plugin calls `ChannelIngressPort.receive()` with the complete normalized ingress DTO. In the current gateway-hosted path, the plugin instead signs a compatibility envelope and emits one of these Socket.IO events:
+
+| Shared operation  | Compatibility event | Current envelope boundary                                                                                                         |
+| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `message.send`    | `message`           | Correlation ID, native Discord message ID, guild/channel/user IDs, conversation ID, content, optional thread ID, and attachments. |
+| `approval.create` | `discord:approve`   | The same signed Discord identity and route fields, carrying the approval command.                                                 |
+| `session.stop`    | `discord:stop`      | The same signed Discord identity and route fields, carrying the stop command.                                                     |
+
+The signature is HMAC-SHA-256 over the ordered envelope payload using the injected Discord service token. The token is used for service authentication and is not part of the protocol payload.
+
+### Gateway validation and dispatch
+
+The gateway exposes the `/chat` Socket.IO namespace. A Discord connection authenticates with `discordServiceToken`; ordinary clients use a BetterAuth session. For Discord service messages, the gateway:
+
+1. Verifies the signed envelope with `DISCORD_SERVICE_TOKEN`.
+2. Re-applies the configured guild, channel, and user allowlists.
+3. Resolves the configured binding and operation role.
+4. Checks that the conversation ID matches the bound logical-agent instance and channel/thread.
+5. Rejects a repeated native Discord message ID through the bounded replay protector.
+6. Reconstructs a gateway `ChatSocketMessageDto` containing the conversation ID, content, and validated attachments.
+7. Uses the configured Discord service principal/tenant for ordinary chat dispatch and the paired `mosaicUserId` for privileged approval/stop policy where required.
+8. Selects the trusted `agentConfigId` from the binding and verifies that the provisioned agent name matches the binding's logical-agent instance.
+
+This path is intentionally described as compatibility: the gateway receives a signed Discord envelope and reconstructs chat input; it does not currently receive a complete `ChannelIngressDto` from the host registry.
+
+### Persistence and durability boundary
+
+The Discord `conversationId` is an external route string such as `<logical-agent-id>:discord:<channel-or-thread-id>`. Persisted conversations and messages use UUID conversation IDs. No current route-mapping layer was found that resolves the external route to a generated UUID before ordinary Discord writes. The gateway catches persistence/binding failures and may continue dispatch, so live output does not prove durable history or restart/resume continuity.
+
+The focused cross-surface integration test explicitly pre-enrolls a durable session before exercising control flow. It does not prove that a fresh ordinary Discord message creates durable conversation/message rows. Current architecture claims are therefore limited to authenticated routing and live delivery. Durable Discord continuity requires a route-to-UUID mapping, observable persistence failures, ordinary-ingress enrollment where required, and a fresh-database restart test.
+
+### Thread and conversation behavior
+
+| Inbound case                                    | Current route and side effect                                                                                                   |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Authorized untagged message in a parent channel | Uses the parent channel as the response target; no thread is created.                                                           |
+| Authorized bot mention in a parent channel      | Creates a public thread, or reuses the thread already attached to that message, and routes the response to that thread.         |
+| Authorized follow-up in an existing thread      | Authorizes against the configured parent channel and keeps the existing thread; it does not create a nested thread.             |
+| `/approve` or `/stop <approval>`                | Uses the current parent/thread route and requires an already enrolled durable session; ordinary chat does not prove enrollment. |
+| Requested thread creation fails                 | Does not dispatch the message, because the requested response target cannot be honored.                                         |
+
+### Discord egress and health
+
+`DiscordPlugin.send()` is a typed egress implementation, even though the current gateway does not wire it as a universal `ChannelEgressPort`. It:
+
+- rejects a forged or route-misaligned conversation before looking up a Discord destination;
+- rejects a missing destination with `destination_unavailable`;
+- chunks text at a Discord-safe 1,900-character boundary;
+- retries transient rate-limit, server, and network failures up to three attempts;
+- derives one stable nonce per correlation/chunk and sends with Discord's enforced nonce option; and
+- does not retry permanent delivery failures.
+
+The plugin reports `connected`, `degraded`, or `disconnected` from Discord client readiness and gateway socket connectivity. The health method is tested without exposing provider or runtime state. Outbound delivery uses Discord's native send operation; code-content wrapping from the former page is not implemented.
+
+Agent output reaches the plugin through the current `agent:start`/`agent:text`/`agent:end` Socket.IO events. The plugin buffers the text by conversation ID and calls its typed Discord egress method when the stream ends.
+
+## Draft: shared adapter registry and gateway wiring
+
+**Status: Draft / unimplemented.**
+
+The gateway does have a startup `IChannelPlugin[]` registry, but that registry is a lifecycle host for the current Discord and Telegram wrappers. It does not register `OfficialChannelAdapter` instances, inject `ChannelIngressPort` and `ChannelEgressPort` through a common gateway service, expose adapter health, or implement a dynamic `ChannelRegistry` with `getAdapter`, `listAdapters`, and `healthAll` semantics.
+
+The former page's claim that adapters are already registered uniformly, or that new adapters can be added without channel-specific gateway branches, is not current. The gateway still has Discord-specific authentication, envelope, approval, stop, replay, and binding branches.
+
+A future implementation may define a registry and host lifecycle, but that work must first specify:
+
+- ownership and injection of ingress and egress ports;
+- health and failure semantics;
+- binding and credential loading boundaries;
+- compatibility behavior for existing Socket.IO clients; and
+- tests proving that an adapter cannot bypass gateway authorization or route validation.
+
+Until then, this section is design context only.
+
+## Draft: Telegram shared-contract parity
+
+**Status: Raw legacy adapter exists; shared protocol parity and authenticated gateway participation are unimplemented/unproven.**
+
+The current Telegram plugin is not an `OfficialChannelAdapter` implementation. Its source currently:
+
+- launches a Telegraf bot and a Socket.IO client;
+- accepts only messages with a text field and ignores attachment-only messages;
+- maps each Telegram chat ID to `telegram-<chatId>`;
+- emits a raw `{ conversationId, content, role: "user" }` object rather than `ChannelIngressDto`;
+- has no shared DTO import, channel binding, principal/role policy, native message ID, attachment mapping, route validation, or health method; and
+- sends plain `sendMessage` responses in chunks, without the former page's claimed MarkdownV2, photo, or document handling.
+
+The Telegram Socket.IO client does not provide the Discord service token or a BetterAuth session in its connection options. The source therefore does not establish participation in the gateway's current authenticated connection path. The package's test script uses `--passWithNoTests`, and no package test file is present in this checkout.
+
+Future Telegram parity is draft work. It would need an explicit identity/authentication boundary, shared ingress normalization, binding and operation policy, route-safe egress, health reporting, and focused tests before this page could describe Telegram as an official shared-contract adapter.
+
+## Draft: Matrix integration
+
+**Status: Draft / unimplemented in the channel protocol.**
+
+No current gateway adapter, shared-port wiring, channel binding, identity resolver, room/conversation persistence boundary, or focused channel tests were found for the Matrix design described by the former page. The old Conduit choice, appservice registration, room and Space mappings, ghost users, encryption defaults, retention jobs, and agent-room behavior are therefore proposals, not current system behavior.
+
+Those details must not be copied into implementation instructions or treated as deployment requirements. A future Matrix effort must independently decide and implement its homeserver/appservice boundary, authentication, route mapping, persistence, authorization, delivery, and tests.
+
+## Draft: channel identity linking
+
+**Status: Draft / unimplemented.**
+
+The shared contract carries an already-authorized `ChannelAuthorizedPrincipalDto`; it does not implement a generic channel-identity database or linking flow. Discord currently uses configuration-owned allowlists and pairings. A pairing may include a `mosaicUserId` for privileged operations, while ordinary Discord chat dispatch uses the configured service principal and tenant in the gateway.
+
+No current evidence establishes the former page's proposed `channel_identities` table, OAuth/deep-link flow, anonymous-principal behavior, persistent Matrix session, or revocation endpoint. Those are not implied by the optional `mosaicUserId` field and must remain planned work until schema, auth, gateway, and adapter implementations exist together.
+
+## Draft: multi-surface conversation multiplexing
+
+**Status: Partial raw chat-session support exists; the proposed channel-protocol fanout architecture is unimplemented.**
+
+The gateway currently tracks client/conversation sessions and emits raw typed Socket.IO chat events. Focused gateway tests verify isolation of concurrent conversation streams sharing one socket. The chat event contract is `ChatMessagePayload` plus `agent:*` events, not `ChannelMessageDto` fanout.
+
+There is no evidence in the cited current path for the former page's complete `ConversationService` plus Valkey pub/sub topology, canonical cross-surface `ChannelMessageDto` persistence, or Matrix fanout. Concurrent stream isolation must not be presented as multi-surface channel multiplexing.
+
+A future multiplexing design must define canonical message ownership, subscription and fanout boundaries, replay/ordering behavior, conflict semantics, and per-surface authorization before it can become architecture guidance.
+
+## Current limitations and version boundary
+
+The following are intentionally not claimed as current protocol policy:
+
+- A semantic protocol version of `1.0.0`. `packages/types/package.json` currently reports package version `0.0.2`, while `packages/types/src/index.ts` exports `VERSION = "0.0.0"`; no migration machinery is present in the cited channel code.
+- A generic revoked-auth `ChannelDeliveryError` code. The current union contains only `invalid_route`, `destination_unavailable`, and `delivery_failed`.
+- Structured log records with a universal `{ channel, event, ... }` schema. Current plugin logs are string-prefixed.
+- Universal adapter health monitoring by the gateway host. Discord exposes health; the `IChannelPlugin` host does not.
+- Complete `ChannelEgressDto` delivery from the gateway to every channel. Discord's current gateway egress remains Socket.IO stream events followed by plugin-side delivery.
+
+These limitations are evidence boundaries, not requests to change implementation in this documentation migration.
+
+## Evidence
+
+Current-contract evidence:
+
+- [`packages/types/src/channel/channel.dto.ts`](../../../packages/types/src/channel/channel.dto.ts) — DTOs, enums, route fields, and metadata shape.
+- [`packages/types/src/channel/channel-adapter.ts`](../../../packages/types/src/channel/channel-adapter.ts) — adapter lifecycle, ingress/egress ports, and delivery errors.
+- [`packages/types/src/channel/index.ts`](../../../packages/types/src/channel/index.ts) and [`packages/types/src/index.ts`](../../../packages/types/src/index.ts) — export surface and current package `VERSION`.
+
+Discord evidence:
+
+- [`plugins/discord/src/index.ts`](../../../plugins/discord/src/index.ts) — native translation, authorization, thread routing, signed compatibility envelope, typed ingress/egress seam, retry, and health.
+- [`plugins/discord/src/index.test.ts`](../../../plugins/discord/src/index.test.ts) — direct ingress, routing/thread behavior, authorization ordering, attachments, route-safe egress, retries, chunking, and health.
+- [`apps/gateway/src/chat/chat.gateway.ts`](../../../apps/gateway/src/chat/chat.gateway.ts) — `/chat` namespace, service/session authentication, signed-envelope reconstruction, trusted binding selection, and raw stream egress.
+- [`apps/gateway/src/chat/chat.gateway-auth.ts`](../../../apps/gateway/src/chat/chat.gateway-auth.ts) — Discord service-token and BetterAuth session validation.
+- [`apps/gateway/src/plugin/discord-ingress.security.spec.ts`](../../../apps/gateway/src/plugin/discord-ingress.security.spec.ts) — signature, allowlist, replay, binding, attachment, approval, stop, and logical-agent checks.
+- [`apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts`](../../../apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts) — focused control-flow test with explicit durable-session pre-enrollment; not ordinary persistence evidence.
+
+Hosting and compatibility evidence:
+
+- [`apps/gateway/src/plugin/plugin.interface.ts`](../../../apps/gateway/src/plugin/plugin.interface.ts), [`plugin.module.ts`](../../../apps/gateway/src/plugin/plugin.module.ts), and [`plugin.service.ts`](../../../apps/gateway/src/plugin/plugin.service.ts) — current lifecycle-only plugin host.
+- [`packages/types/src/chat/events.ts`](../../../packages/types/src/chat/events.ts) — raw Socket.IO chat event contracts.
+- [`apps/gateway/src/chat/chat.gateway-redaction.spec.ts`](../../../apps/gateway/src/chat/chat.gateway-redaction.spec.ts) — current per-client/per-conversation stream isolation evidence.
+
+Telegram evidence:
+
+- [`plugins/telegram/src/index.ts`](../../../plugins/telegram/src/index.ts) — current raw Telegraf and Socket.IO behavior.
+- [`plugins/telegram/package.json`](../../../plugins/telegram/package.json) — package scripts, including `--passWithNoTests`.

docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md

@@ -1,5 +1,9 @@
 # Compaction observer revocation and runtime generations
 
+> **Status:** Current contract reference.
+> **Audience:** Developer and security reviewer.
+> **Evidence:** Mutator-gate and framework portability acceptance suites consume this page; live deployment gaps remain explicitly labeled below.
+
 WI-3 connects Claude and Pi compaction/session lifecycle events to the existing authenticated lease-broker state machine. It does not add a second lease store or let runtime hooks assert identity. Each observer inherits the broker-minted session, resolves the current private runtime generation, and sends the existing `revoke_lease` action over the authenticated Unix socket.
 
 ## Observer matrix

docs/DEVELOPER-GUIDE/architecture/decisions/README.md

@@ -0,0 +1,15 @@
+# Architecture Decisions
+
+> **Status:** Current decision index. A decision describes an implemented and accepted boundary; draft proposals belong under `rfcs/` or `docs/plans/`.
+
+## Current decisions
+
+- [Mos runtime portability M1 — logical identity and fencing](mos-runtime-portability-m1.md) — implemented lease, grant, audit, policy, and fencing boundary; connector activation remains held.
+
+Decision pages do not override product requirements, API contracts, or executable behavior. Each page must identify implementation evidence, operational status, and explicit non-goals.
+
+## Related
+
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
+- [[PRD|Product requirements]]
+- [[ADMIN-GUIDE/operations/mos-connector-lease-operations|Held connector lease operations]]

docs/DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md

@@ -0,0 +1,96 @@
+# Mos Runtime Portability M1 — Logical Identity and Fencing
+
+> **Decision status:** Current implemented decision (M1).
+> **Operational status:** The lease/fencing boundary is implemented and test-covered; connector activation remains held.
+> **Audience:** Mosaic developers, gateway/runtime adapter authors, and security reviewers.
+> **Authority:** This page records the current M1 boundary. The executable source and tests are authoritative for behavior; [`PRD.md`](../../../PRD.md) remains authoritative for requirements.
+
+## Decision
+
+M1 separates the logical Mosaic agent from any Claude, Pi, Codex, tmux, Matrix, or provider-native session. The core identity is:
+
+```text
+(tenant_id, logical_agent_id, binding_id)
+```
+
+`logical_agent_id` is a Mosaic logical identifier, not a runtime session identifier. The gateway derives the tenant from authenticated actor scope. The current internal service boundary normalizes the supplied logical-agent identifier and binding; a future public boundary must resolve and authorize those values server-side. Runtime-native session IDs are not part of the lease or execution-grant contract.
+
+A connector is a replaceable holder of authority for one logical binding. It is not the logical agent identity.
+
+## Durable lease model
+
+The additive migration creates `logical_agent_connector_leases` with one unique row per tenant/logical-agent/binding tuple. The current row contains:
+
+- an opaque lease UUID;
+- connector ID and normalized allowed scopes;
+- a positive decimal fencing epoch exposed by the application and stored as PostgreSQL `bigint`;
+- acquisition, heartbeat, expiry, release, and update timestamps.
+
+Initial acquisition is insert-only. An existing active row yields `lease_held`. An expired or released row yields `takeover_required`; ordinary acquisition does not recover it. An authorized takeover compares and swaps the expected epoch, rotates the lease UUID, and increments the epoch atomically. Heartbeat and release match the full identity, binding, connector, lease UUID, and epoch.
+
+### Audit and enforcement precision
+
+`connector_lease_audit_log` is an **application-level append-only contract**: the repository has an insert-only audit path and writes credential-safe lifecycle/rejection metadata. The checked-in schema and migration add a table and indexes, but do not add database triggers, permissions, or other database-level protection against `UPDATE` or `DELETE`. M1 therefore does not claim database-enforced immutability; an append-only guarantee at the database security boundary is a later hardening requirement.
+
+Likewise, identifier, scope, and epoch normalization is performed at the application boundary by the shared types/coordinator and gateway service. The database enforces column types, non-null fields, the lease primary key, and the unique tenant/logical-agent/binding index, but it does not independently enforce all application formats or semantics such as positive epochs, canonical scope ordering/deduplication, or constrained identifier patterns. Database shape must not be mistaken for a second normalization layer.
+
+## Execution grants and TTL boundaries
+
+`ConnectorLeaseCoordinator` issues a short-lived internal grant only after rereading the durable current lease. It enforces hard defense-in-depth maxima of five minutes for leases and thirty seconds for grants; constructor options may only tighten those limits. A grant is bound to tenant, logical agent, binding, connector, lease UUID, scope subset, expiry, correlation ID, and epoch.
+
+The gateway policy and coordinator have deliberately separate TTL responsibilities:
+
+- `ConnectorLeaseService` passes the request's numeric `ttlMs` to policy as `requestedTtlMs` for acquire, takeover, heartbeat, and grant issuance. Identity and scopes are normalized before policy evaluation, but this TTL is a request input, not a coordinator-normalized or effective TTL.
+- Release and read policy checks use `null` because they do not request a TTL.
+- After policy authorization, the coordinator validates the TTL as a positive safe integer and rejects values above the applicable hard cap (`300000ms` for leases or `30000ms` for grants). It does not silently clamp an over-cap value.
+- A policy may impose a stricter duration limit, but it cannot expand the coordinator cap. A policy implementation must validate the requested value itself if its decision depends on a bounded or canonical TTL.
+
+Grant validation occurs immediately before adapter invocation and rereads the durable current row. Validation denies:
+
+- grants not minted by the current gateway process, including cloned or forged objects;
+- expired grants or leases;
+- released leases;
+- stale epochs or replaced connectors/lease UUIDs;
+- missing, cross-tenant, cross-agent, or cross-binding leases; and
+- scopes not authorized by both the grant and the current lease.
+
+A gateway restart intentionally invalidates process-local grant provenance. The durable lease and epoch survive, but a fresh grant is required after current-lease and policy validation.
+
+## Adapter boundary and activation state
+
+The normalized `ConnectorExecutionContext` and `FencedConnectorAdapter` contract define the future adapter boundary. When a concrete adapter is activated, it must receive the context only after the coordinator's final validation and must propagate the epoch/context to downstream effect boundaries that need to fence races after gateway validation.
+
+That contract is **not evidence of an activated adapter**. The current production module registers the lease repository, service, and deny-all policy. The coordinator and gateway integration tests use test adapters, but current production runtime providers and channel paths do not consume `ConnectorExecutionContext` or call `executeGrant`. No concrete Claude, Pi, Codex, Matrix, tmux, provider, or channel connector is activated by M1.
+
+`ConnectorLeaseService` is the gateway-owned policy surface. It derives tenant scope from authenticated context, records policy denials, and is internal: no M1 connector-lease HTTP controller or administration endpoint is registered. The default `DenyConnectorLeasePolicy` rejects every lease and grant operation until a separately authorized server-side policy is supplied.
+
+## Current implementation evidence
+
+The current boundary is represented by the following checked-in surfaces:
+
+- Contract and application normalizers: `packages/types/src/agent/connector-lease.dto.ts` and its unit specification.
+- Coordinator, TTL caps, grant provenance, reread, and fencing checks: `packages/agent/src/connector-lease.ts` and its unit tests.
+- Gateway policy, tenant derivation, and default deny wiring: `apps/gateway/src/agent/connector-lease.service.ts` and `agent.module.ts`.
+- Durable repository and compare-and-swap mutations: `apps/gateway/src/agent/connector-lease.repository.ts`.
+- Schema and additive migration artifacts: `packages/db/src/schema.ts` and `packages/db/drizzle/0016_salty_morlocks.sql`.
+- Gateway integration and repository specifications: `apps/gateway/src/agent/connector-lease.integration.test.ts` and `connector-lease.repository.test.ts`.
+
+These references establish the implemented boundary; they do not imply that a production database, connector policy, or concrete connector is currently active.
+
+## Explicit non-goals
+
+M1 does **not** provide or authorize:
+
+1. Production connector activation, channel cutover, or cross-harness failover/rollback E2E.
+2. Concrete Claude, Pi, Codex, Matrix, tmux, provider, or channel adapters, or integration of existing runtime providers with this lease context.
+3. A connector-lease HTTP API or caller-controlled tenant authority.
+4. Exactly-once connector receipts, a side-effect journal, checkpoint/handoff payloads, replay deduplication, or recovery semantics for an external effect that may already have happened.
+5. Database-enforced append-only audit rows or database-enforced copies of application identifier/scope/epoch normalization.
+6. A claim that gateway validation alone fences an effect after an adapter has crossed the boundary; downstream adapters and effect journals remain later work.
+
+A valid lease or grant is therefore not a claim of exactly-once delivery, production connector readiness, or completed runtime cutover.
+
+## Related contract
+
+- [M1 connector lease operations — held/non-operative](../../../ADMIN-GUIDE/operations/mos-connector-lease-operations.md)
+- [MOS-PORT requirements](../../../PRD.md#mos-runtime-portability-workstream-mos-port)

docs/DEVELOPER-GUIDE/architecture/lease-broker-protocol.md

@@ -1,5 +1,9 @@
 # Authenticated external lease broker protocol
 
+> **Status:** Current contract reference.
+> **Audience:** Developer and security reviewer.
+> **Evidence:** Lease-broker acceptance suites consume this page; executable behavior remains authoritative in source and tests.
+
 The compaction-refresh lease broker is a Linux-only, newline-framed JSON protocol over a Unix stream socket. It is runtime-neutral; M1 consumers are limited to Claude and Pi. This is an internal process boundary, not an HTTP API, so it is intentionally absent from OpenAPI.
 
 The broker, never the caller, obtains `(pid, uid, gid)` from kernel `SO_PEERCRED`. It correlates the PID with `/proc/<pid>/stat` field 22 (`starttime`) and mints `session_id` on `register_anchor`. Presence of `session_id` in that request is refused even when its value is `null` or empty. Later requests must originate from the anchor or a descendant. The broker walks parent PIDs to the `(pid,starttime)` anchor and then rereads every walked PID's starttime before accepting the chain.

docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md

@@ -1,5 +1,9 @@
 # WI-1 lease broker security notes
 
+> **Status:** Current contract reference.
+> **Audience:** Developer and security reviewer.
+> **Evidence:** The lease-broker implementation and acceptance material cross-check this boundary; deployment-review requirements remain explicitly labeled below.
+
 - Trusted identity comes only from Linux `SO_PEERCRED` plus `/proc` starttime, never request identity fields.
 - Descendant authorization is anchored to `(pid,starttime)` and uses a complete second starttime pass to fail closed on disappearance or PID-reuse races.
 - Runtime generations are monotonic per anchor; a bump revokes prior-incarnation tokens before persistence commits. WI-3 stores the live generation in an owner-only locked file so same-PID Pi reload/new/resume/fork and Claude resume/clear transitions cannot inherit a VERIFIED lease.

docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md

@@ -1,5 +1,9 @@
 # Whole mutator-class lease gate
 
+> **Status:** Current contract reference.
+> **Audience:** Developer and security reviewer.
+> **Evidence:** Runtime launch-guard and mutator-gate tests cross-check this boundary; parser residuals and deployment gaps remain explicitly labeled below.
+
 WI-2 adds the framework-native authorization boundary for Claude (including the supported Claudex overlay) and Pi. Every runtime-reported tool name reaches the lease broker before execution. The gate classifies capabilities by the whole tool class; it never parses a Bash command to decide whether that particular string looks read-only.
 
 ## Default-deny policy

docs/DEVELOPER-GUIDE/architecture/rfcs/README.md

@@ -0,0 +1,15 @@
+# Architecture RFCs
+
+> **Status:** Current proposal index. RFCs are draft design material and have no operational or implementation authority until an approved decision and implementation evidence supersede them.
+
+## Draft proposals
+
+- [Optional AI egress gateways](optional-ai-egress-gateways.md) — proposed model-egress boundary; LiteLLM and Bifrost are not integrated, and Claudex remains experimental harness tooling.
+
+A draft RFC must not be cited as a supported feature, deployment path, or approved architecture decision. Approved implemented boundaries belong under [`../decisions/`](../decisions/README.md).
+
+## Related
+
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
+- [[DEVELOPER-GUIDE/architecture/decisions/README|Architecture decisions]]
+- [[PRD|Product requirements]]

docs/DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md

@@ -0,0 +1,371 @@
+# RFC: Optional AI Egress Gateways
+
+> **Status:** Draft / proposed — not approved, not current, and not integrated.
+>
+> **Authority:** Non-operative design proposal. This document does not authorize an
+> integration, deployment, provider selection, credential flow, or production use.
+> It is intentionally an RFC rather than an approved architecture decision.
+>
+> **Scope:** Optional model/inference egress only. `IProviderAdapter` and
+> `AgentRuntimeProvider` are separate boundaries; this RFC does not merge them.
+
+- **Date:** 2026-07-14
+- **Related issues:** #754, #755
+- **Decision owner:** Mosaic Gateway / provider-adapter architecture
+
+## Context
+
+The emergency Mos continuity path kept Claude Code as the harness and translated
+Anthropic Messages traffic to Codex OAuth through a small localhost proxy. That
+preserved the existing Claude Discord plugin and transcript, but exposed two
+architectural facts:
+
+1. Harness identity, channel entitlement, provider credentials, inference
+   transport, and runtime sessions are separate concerns.
+2. A generic AI gateway could eventually improve model routing, budgets, and
+   observability, but it must not become Mosaic's identity, authorization,
+   tenant, connector, or orchestration boundary.
+
+The Tess qualification work also found that provider rebinding is not, by
+itself, identity-continuous failover. Any future design still needs a logical
+agent identity, durable connector lease/fencing, canonical handoff/checkpoint,
+exactly-once receipts, concrete runtime adapters, and cross-runtime rollback
+validation.
+
+This page is a reclassified migration of the historical egress-gateway
+proposal. The move to `docs/DEVELOPER-GUIDE/architecture/rfcs/` does not promote
+it to a decision and does not change runtime behavior.
+
+## Current status and non-goals
+
+This RFC describes a possible future integration boundary. It does **not** say
+that any of the candidates below is supported by Mosaic Gateway today:
+
+- **LiteLLM is not integrated.** It is only a candidate for a future model-egress
+  adapter and remains subject to the prerequisites in this RFC.
+- **Bifrost is not integrated.** Its routing, virtual-key, and failover features
+  are research inputs only, not Mosaic authority.
+- **Claudex and `claude-code-proxy` are experimental harness tooling, not
+  gateway egress.** The `mosaic claudex` path runs a Claude Code harness against
+  a local translation proxy for evaluation. It is not a Mosaic Gateway egress
+  integration, does not define the `IProviderAdapter` model contract, and does
+  not define the `AgentRuntimeProvider` runtime/session contract.
+
+In particular, this RFC does not propose that a generic gateway receive channel
+traffic directly, own Mosaic sessions, replace the runtime-provider registry,
+or become a second authorization or tenant system. No database, service, or
+runtime change is implied by this document.
+
+## Corrected contract boundary
+
+The historical proposal conflated two different adapter families. They must
+remain separate.
+
+### `IProviderAdapter`: model and inference egress
+
+`IProviderAdapter` is the model-provider abstraction. Its current contract
+covers provider registration, model discovery, provider health, and a future
+direct completion stream. `ProviderService` aggregates these adapters and
+connects model availability to the Pi `ModelRegistry`.
+
+It does **not** represent an agent process or session. It does not own channel
+identity, Mosaic actor or tenant identity, logical-agent ownership, runtime
+session IDs, runtime attachments, handoff state, or tool authorization. An
+optional LiteLLM, Bifrost, or similar model gateway would therefore be a
+candidate for this model-egress path only, after approval and qualification.
+
+### `AgentRuntimeProvider`: runtime and session boundary
+
+`AgentRuntimeProvider` is the runtime-neutral session contract. It covers
+runtime capabilities and health plus operations such as listing sessions,
+reading session trees, streaming a session, sending a message, attaching or
+detaching, and terminating a session. Its `RuntimeScope` is derived from
+trusted actor, tenant, channel, and correlation context.
+
+The runtime-provider service performs the gateway-side capability, authorization,
+approval, and metadata-only audit boundary before invoking a runtime provider.
+It is not a model-egress gateway and must not be substituted for
+`IProviderAdapter`. A runtime implementation may use model selection or a model
+service internally, but that dependency is an explicit composition between two
+contracts; it does not make the runtime provider a model provider or make a
+model gateway a session provider.
+
+The checked-in contract and implementation references are:
+
+- [`IProviderAdapter` and provider types](../../../../packages/types/src/provider/index.ts)
+- [`ProviderService`](../../../../apps/gateway/src/agent/provider.service.ts)
+- [`AgentRuntimeProvider`](../../../../packages/types/src/agent/agent-runtime-provider.ts)
+- [`RuntimeProviderService`](../../../../apps/gateway/src/agent/runtime-provider-registry.service.ts)
+- [`AgentRuntimeProviderRegistry`](../../../../packages/agent/src/runtime-provider-registry.ts)
+
+### Proposed relationship
+
+If a future implementation is approved, the model and runtime paths remain
+parallel and explicitly composed at the Mosaic boundary:
+
+```text
+Discord / Matrix / CLI / web
+             |
+             v
+Mosaic Gateway: authenticated actor + tenant, policy, approvals,
+               logical agent, connector lease/fence, audit, checkpoints,
+               idempotency, and side-effect receipts
+             |
+       +-----+-----------------------+
+       |                             |
+       v                             v
+model request path              runtime/session path
+ProviderService / routing      RuntimeProviderService
+       |                             |
+       v                             v
+IProviderAdapter                AgentRuntimeProvider
+       |                             |
+       v                             v
+optional model-egress           native or external runtime/session
+gateway (future only)           transport
+       |
+       v
+upstream model/provider
+```
+
+The optional egress gateway may receive only a validated model request from the
+Mosaic model path. It is not a channel ingress, runtime-session transport,
+connector owner, or source of Mosaic identity.
+
+## Draft proposal
+
+This RFC proposes, for review only, that Mosaic could support an optional
+model-egress gateway through a dedicated `IProviderAdapter` implementation or
+adapter-owned model transport. Any such integration would remain subordinate
+to Mosaic Gateway policy and would not add a second runtime/session boundary.
+
+Mosaic Gateway would remain authoritative for:
+
+- authenticated actor and tenant identity;
+- logical-agent identity, connector binding, lease epoch, and stale-holder
+  fencing;
+- authorization, approval, and model/tool policy;
+- runtime/session access through the separate `AgentRuntimeProvider` boundary;
+- audit correlation, redaction, retention, and operational evidence;
+- canonical handoff, checkpoint, and recovery state; and
+- idempotency keys, operation identity, and durable side-effect receipts.
+
+An optional model-egress gateway must not:
+
+- receive channel ingress directly;
+- authorize tools, connector ownership, runtime sessions, or approvals;
+- define Mosaic actors, tenants, logical agents, or session identity;
+- treat downstream virtual keys as Mosaic principals;
+- persist raw Mosaic handoffs, channel credentials, or unredacted telemetry;
+- bypass adapter capability negotiation or gateway policy;
+- retry or fail over an operation whose side-effect state is ambiguous; or
+- silently select an unhealthy or unauthorized provider merely to return a
+  result.
+
+## Candidate assessment
+
+These dispositions are deliberately non-integrated and do not constitute
+approval.
+
+### LiteLLM
+
+**Disposition:** Not integrated; future candidate for a formal
+`IProviderAdapter` model-egress prototype only.
+
+Potentially useful features include broad provider routing, virtual keys,
+budgets, observability, and OpenAI/Anthropic-compatible surfaces. A future
+review must verify, rather than assume, the exact ChatGPT subscription OAuth
+flow, supported models, provider terms, token storage, encryption, revocation,
+refresh, scope, and incident response.
+
+A prototype would also have to prove streaming, tool calls, reasoning controls,
+cancellation, tenant isolation, audit-correlation preservation, retry behavior,
+and idempotency. Virtual keys must remain downstream credentials and must not
+become Mosaic actors or tenants. Channel ingress and connector credentials
+would remain outside LiteLLM.
+
+Source references:
+
+- [LiteLLM ChatGPT subscription provider](https://docs.litellm.ai/docs/providers/chatgpt)
+- [LiteLLM providers](https://docs.litellm.ai/docs/providers)
+
+### Bifrost
+
+**Disposition:** Not integrated; future candidate for governance and routing
+research, with subscription OAuth compatibility unverified.
+
+Virtual keys, budgets, rate limits, weighted load balancing, and provider
+failover may inform a future Mosaic egress design, but they are not Mosaic
+authority. A future review must verify Codex/ChatGPT subscription OAuth rather
+than assume API-key compatibility, map all policy to server-derived Mosaic
+tenants, prove that failover preserves connector leases and approvals, and
+redact request/response telemetry before persistence.
+
+Automatic failover must be disabled or constrained whenever policy, approval,
+or side-effect state is ambiguous.
+
+Source references:
+
+- [Bifrost overview](https://docs.getbifrost.ai/overview)
+- [Bifrost repository](https://github.com/maximhq/bifrost)
+
+### Claudex / `claude-code-proxy`
+
+**Disposition:** Experimental harness overlay and local translation proxy; not
+Mosaic Gateway egress and not an approved provider integration.
+
+The reviewed path runs GPT models inside the Claude Code harness through a
+local `claude-code-proxy` that translates Anthropic Messages traffic to a
+ChatGPT-subscription (Codex OAuth) backend. It is intended for evaluation and
+must not be described as a current Mosaic model gateway, an `IProviderAdapter`
+implementation, or an `AgentRuntimeProvider` implementation.
+
+Its constraints remain important: it is not a multi-tenant control plane, it
+must not own connector leasing or canonical handoff, and local proxy
+credentials and listener exposure require isolation. The current Mosaic
+launcher documents its experimental status and isolated Claude configuration:
+
+- [`mosaic` claudex documentation](../../../../packages/mosaic/README.md)
+- [`claudex` launch composition](../../../../packages/mosaic/src/commands/claudex.ts)
+- [`claude-code-proxy`](https://github.com/raine/claude-code-proxy)
+
+### `teremterem/claude-code-gpt-5-codex`
+
+**Disposition:** Historical recipe; not selected and not integrated.
+
+The reviewed repository uses `OPENAI_API_KEY`, tells previously authenticated
+Claude users to log out, and documents a Claude Web Search schema
+incompatibility. That does not satisfy the subscription-OAuth plus built-in-
+channel continuity requirement observed in the Mos cutover.
+
+Source references:
+
+- [Repository](https://github.com/teremterem/claude-code-gpt-5-codex)
+- [Environment template](https://github.com/teremterem/claude-code-gpt-5-codex/blob/main/.env.template)
+
+## Prerequisites before approval or integration
+
+No candidate may be integrated, enabled as a Mosaic feature, or treated as a
+current supported path until all of the following are complete for the exact
+provider, adapter, configuration, and deployed revision.
+
+### 1. Recorded approval and governance
+
+- An architecture decision explicitly approves the model-egress scope and
+  records that `IProviderAdapter` remains separate from `AgentRuntimeProvider`.
+- Product/operations ownership, provider terms review, and independent security
+  review are recorded against the exact change and provider revision.
+- The approval identifies allowed providers, models, regions, data handling,
+  rollback owner, support status, and a time-bounded experimental or production
+  phase. This RFC itself is not that approval.
+- No candidate is advertised as integrated, current, or production-ready while
+  the approval record is absent or expired.
+
+### 2. Security and credential controls
+
+- A threat model covers prompt/tool data, model output, streaming, cancellation,
+  retries, failover, SSRF, endpoint authentication, TLS, egress allowlists,
+  supply-chain risk, provider terms, and denial-of-service behavior.
+- OAuth tokens, API keys, virtual keys, refresh tokens, and proxy credentials
+  have documented ownership, storage, encryption, rotation, revocation,
+  expiry, least-privilege scope, and incident-response procedures. Secrets do
+  not enter prompts, logs, traces, audit payloads, or commits.
+- Request, response, tool-schema, and error telemetry is classified and
+  redacted before persistence or external channel delivery. Retention and
+  deletion are tenant-scoped.
+- The adapter fails closed on missing, expired, revoked, malformed, or
+  unauthorized credentials and on uncertain provider health. Loopback-only
+  experimental proxies remain process-isolated and cannot become a gateway
+  bypass.
+
+### 3. Actor and tenant isolation
+
+- Actor and tenant identity are derived from authenticated Mosaic context at
+  the Gateway; callers cannot select a tenant, logical agent, credential, or
+  provider principal by supplying an ID.
+- Downstream virtual keys and provider account identifiers are mapped to
+  server-owned tenant policy. They never grant Mosaic authorization and never
+  replace RBAC, approvals, connector leases, or runtime scope.
+- Model configuration, budgets, rate limits, data residency, credential use,
+  logs, caches, and failure handling are isolated per tenant. Cross-tenant
+  reads, writes, cache hits, telemetry, and failover are denied and tested.
+- The egress adapter receives only the minimum scoped request needed for the
+  authorized model operation; channel ingress and runtime/session control stay
+  in Mosaic-owned boundaries.
+
+### 4. Idempotency and side-effect safety
+
+- Mosaic assigns a durable operation ID and idempotency key before an egress
+  request can cause a tool or external side effect. The provider gateway must
+  preserve the correlation and idempotency metadata or be wrapped by an
+  adapter that does so.
+- Durable receipts record request, attempt, provider, outcome, and replay state
+  without storing unredacted content. Retries and failover are allowed only
+  when the operation contract proves they cannot duplicate a side effect.
+- Ambiguous timeout, disconnect, stream-resume, cancellation, and provider
+  failover outcomes fail closed until the receipt is reconciled. The egress
+  gateway must not claim exactly-once behavior that Mosaic has not proven.
+- Failure injection demonstrates no duplicate tool, connector, channel, or
+  external side effect across gateway, adapter, proxy, and provider retries.
+
+### 5. Contract and rollback qualification
+
+- Separate contract tests pass for `IProviderAdapter` model registration,
+  health, streaming, tools, reasoning controls, cancellation, errors, and
+  audit correlation.
+- Separate `AgentRuntimeProvider` contract tests continue to pass for runtime
+  capability negotiation, session ownership, approval, attach/detach,
+  termination, and normalized events. A model-egress candidate must not be
+  used as evidence for runtime/session compatibility.
+- A verified rollback to the prior model path is exercised, including revoked
+  credentials, unhealthy providers, partial streams, and an adapter version
+  mismatch.
+- The exact deployed revision receives independent code and security review,
+  with terminal-green CI and operator recovery evidence before any activation.
+
+## Security consequences
+
+- Subscription OAuth grants are high-value credentials and require the same
+  lifecycle controls as service credentials.
+- Downstream virtual keys reduce provider-key exposure but do not establish
+  user, tenant, agent, or runtime authority.
+- Automatic retry or failover can duplicate tool and external side effects
+  unless Mosaic owns operation IDs, durable receipts, and reconciliation.
+- Gateway telemetry can contain prompts, tool schemas, and model output;
+  redaction and retention policy must apply before persistence.
+- A localhost translation endpoint must remain loopback-only, process-isolated,
+  authenticated where applicable, and outside the Mosaic Gateway ingress path.
+- A model-egress gateway outage must not weaken Mosaic authorization, lease
+  fencing, tenant isolation, approval, or runtime-session boundaries.
+
+## Acceptance before any production use
+
+The following are minimum exit criteria for a future, separately approved
+implementation; they are not satisfied by this RFC:
+
+1. The recorded approval and provider-terms review cover the exact integration.
+2. Credential lifecycle, revocation, rotation, redaction, and incident drills
+   are documented and exercised.
+3. Tenant-bound authorization remains entirely in Mosaic Gateway and passes
+   cross-tenant negative tests.
+4. `IProviderAdapter` contract tests pass without treating
+   `AgentRuntimeProvider` tests as substitutes.
+5. Failure injection proves no duplicate side effects across retries or
+   provider failover, with durable idempotency receipts.
+6. Streaming, tools, cancellation, reasoning policy, errors, and audit
+   correlation are qualified for the exact model path.
+7. Rollback to the prior provider path is exercised and operator-verifiable.
+8. Independent code and security reviews approve the exact deployed revision.
+
+## Follow-up
+
+- #754 owns cross-runtime logical identity, checkpoint, receipt, adapter, and
+  failover work.
+- #755 / PR #757 implements the first logical identity and connector
+  lease/fencing boundary.
+- A later issue may prototype LiteLLM or Bifrost behind the model-provider
+  boundary only after the recorded approval, security, tenant, idempotency,
+  contract, and rollback prerequisites are met.
+- The page remains **Draft / proposed** until an explicit decision changes its
+  status. Until then, it must not be cited as an approved architecture,
+  current integration, or operational runbook.

docs/DEVELOPER-GUIDE/integrations/channel-adapters.md

@@ -0,0 +1,181 @@
+# Channel adapters
+
+> **Status:** Current shared channel types plus the Discord reference/compatibility implementation. A shared gateway adapter registry, Telegram parity, and Matrix channel integration remain unimplemented or unproven.
+>
+> **Last verified:** 2026-08-10 against the source and focused tests listed in [Evidence](#evidence).
+>
+> **Audience:** Developers implementing or reviewing channel integrations.
+
+The gateway remains the policy and runtime boundary. Channel code translates native events, applies its native admission checks, and delivers normalized ingress/egress; it must not choose a provider, harness, process, or native runtime session on behalf of the gateway.
+
+## Current source boundaries
+
+| Boundary              | Current authority                                                                                                                                                                                                                                         | Current claim                                                                                                                                              |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Shared contract       | [`packages/types/src/channel/channel.dto.ts`](../../../packages/types/src/channel/channel.dto.ts), [`channel-adapter.ts`](../../../packages/types/src/channel/channel-adapter.ts)                                                                         | DTOs, ports, lifecycle health, and delivery error codes exported by `@mosaicstack/types`.                                                                  |
+| Discord translation   | [`plugins/discord/src/index.ts`](../../../plugins/discord/src/index.ts)                                                                                                                                                                                   | First adapter implementing the shared lifecycle/egress seam, with an optional direct ingress port and a tested Socket.IO compatibility path.               |
+| Discord behavior      | [`plugins/discord/src/index.test.ts`](../../../plugins/discord/src/index.test.ts)                                                                                                                                                                         | Current allowlist, pairing, role, thread, route, attachment, replay-envelope, egress, retry, and health behavior.                                          |
+| Gateway compatibility | [`apps/gateway/src/chat/chat.gateway.ts`](../../../apps/gateway/src/chat/chat.gateway.ts), [`chat.gateway-auth.ts`](../../../apps/gateway/src/chat/chat.gateway-auth.ts)                                                                                  | `/chat` Socket.IO service/session authentication, signed Discord envelope validation, trusted binding selection, raw chat dispatch, and raw stream egress. |
+| Host registry         | [`apps/gateway/src/plugin/plugin.interface.ts`](../../../apps/gateway/src/plugin/plugin.interface.ts), [`plugin.module.ts`](../../../apps/gateway/src/plugin/plugin.module.ts), [`plugin.service.ts`](../../../apps/gateway/src/plugin/plugin.service.ts) | Lifecycle-only `IChannelPlugin[]` hosting. This is not a universal `OfficialChannelAdapter` registry.                                                      |
+| Telegram              | [`plugins/telegram/src/index.ts`](../../../plugins/telegram/src/index.ts), [`package.json`](../../../plugins/telegram/package.json)                                                                                                                       | Raw legacy Telegraf/Socket.IO behavior only; no shared-contract or authenticated gateway parity.                                                           |
+| Matrix                | No current channel adapter boundary in the cited implementation                                                                                                                                                                                           | Matrix-related fleet/runtime code is not evidence of a gateway channel adapter.                                                                            |
+
+Executable source and tests outrank older architecture or quarantine pages. The canonical architecture summary is [`architecture/channel-protocol.md`](../architecture/channel-protocol.md).
+
+## Shared contract
+
+`@mosaicstack/types` currently exports the channel types through [`packages/types/src/channel/index.ts`](../../../packages/types/src/channel/index.ts) and [`packages/types/src/index.ts`](../../../packages/types/src/index.ts).
+
+The lifecycle and port seams are:
+
+```typescript
+interface OfficialChannelAdapter {
+  readonly name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  health(): Promise<ChannelAdapterHealthDto>;
+}
+
+interface ChannelIngressPort {
+  receive(ingress: ChannelIngressDto): Promise<void>;
+}
+
+interface ChannelEgressPort {
+  send(egress: ChannelEgressDto): Promise<void>;
+}
+```
+
+The current DTO boundary includes:
+
+- `ChannelMessageDto` for normalized native messages and JSON-safe metadata;
+- `ChannelAttachmentDto` for bounded external attachment references;
+- `ChannelAuthorizedPrincipalDto` for the already-authorized channel actor and `viewer`/`operator`/`admin` role;
+- `ChannelBindingDto` for configuration-owned workspace/channel/logical-agent binding;
+- `ChannelResponseTargetDto` for a channel and optional thread;
+- `ChannelConversationRouteDto` for binding, logical agent, stable conversation ID, authorization channel, and response target;
+- `ChannelIngressDto` for correlation, native message ID, operation, principal, message, and route; and
+- `ChannelEgressDto` for correlation, normalized output, and route.
+
+Current operations are `message.send`, `approval.create`, and `session.stop`. Current delivery errors are `invalid_route`, `destination_unavailable`, and `delivery_failed`; there is no shared revoked-auth error code or executable protocol-version contract in this surface.
+
+### Stable route rule
+
+The Discord adapter derives:
+
+```text
+<logical-agent-id>:discord:<response-channel-id>
+```
+
+The binding address is derived from the configured guild, parent channel, and logical-agent instance. The route intentionally omits runtime provider, harness, model, process, and native runtime-session identifiers. Gateway provider/runtime layers own those identities; durable-session ownership applies only after explicit enrollment and is not implied by the external route.
+
+This is a route-integrity rule, not proof that the gateway has a universal channel session API. A future adapter must derive its route from trusted configuration and native channel/thread identity; it must not accept a caller-selected logical agent or runtime target.
+
+## Current Discord implementation
+
+### Native ingress
+
+`DiscordPlugin` currently:
+
+1. ignores bot-authored and non-guild messages;
+2. resolves a thread's actual parent text channel, while leaving normal category parents out of authorization;
+3. applies default-deny guild, parent-channel, and user allowlists;
+4. resolves configuration-owned `instanceId`/`agentConfigId` bindings and paired-user roles before thread creation or dispatch;
+5. applies message and mention-thread limits before side effects;
+6. creates/reuses a mention thread or preserves an existing thread target; and
+7. maps the event to a `ChannelIngressDto` when an `ingressPort` dependency is supplied.
+
+The normalized message uses `channelName: "discord"`, the response target as `channelId`, `senderKind: "user"`, `markdown` for non-empty text, `image`/`file` for attachment-only input, mapped attachments, and metadata containing the native channel message ID and guild ID. It does not currently claim a universal metadata shape for mentions, embeds, channel type, or replies.
+
+### Socket.IO compatibility path
+
+The gateway-hosted plugin is currently constructed without a direct `ChannelIngressPort` in [`plugin.module.ts`](../../../apps/gateway/src/plugin/plugin.module.ts), so it uses the established compatibility path:
+
+1. `start()` connects to `${DISCORD_GATEWAY_URL}/chat` with `auth.discordServiceToken`.
+2. Normal sends emit a signed `message` envelope; approval and stop emit `discord:approve` and `discord:stop` envelopes.
+3. The HMAC-SHA-256 signature covers the ordered Discord payload using `DISCORD_SERVICE_TOKEN`.
+4. The gateway verifies the service token/signature, allowlists, binding/operation role, stable conversation ID, attachment bounds, and replay key before dispatch.
+5. The gateway selects the binding's trusted `agentConfigId` and verifies its name equals the logical-agent instance. It attempts normal conversation binding/persistence before dispatch, but the external route is not a UUID and no route-to-UUID mapping currently proves durable ordinary-chat history.
+6. Agent output currently returns as raw Socket.IO `agent:start`, `agent:text`, and `agent:end` events. The plugin buffers the text and calls its typed Discord egress at stream end.
+
+This compatibility path carries enough normalized identity to preserve current security and routing behavior, but it is not a gateway-produced `ChannelIngressDto`/`ChannelEgressDto` flow through a shared host registry. The gateway can continue live dispatch after persistence failure; adapter authors must not claim durable continuity until external routes map to UUID conversations and fresh-message restart tests pass.
+
+### Egress and health
+
+`DiscordPlugin.send()` is a typed `ChannelEgressPort` implementation. It validates the route and message alignment before destination lookup, sends at a 1,900-character boundary, retries transient 429/5xx/network failures up to three times, uses one deterministic enforced nonce per correlation/chunk, and does not retry permanent failures. It reports `connected`, `degraded`, or `disconnected` from Discord client readiness and gateway socket connectivity.
+
+The host wrapper currently exposes only `name`, `start`, `stop`, and optional project provisioning. It does not expose `health()`, inject the direct ingress port, produce `ChannelEgressDto` values from the gateway, or provide `healthAll`/`getAdapter` semantics.
+
+## Adapter authoring boundary
+
+For a future official adapter, preserve these current architectural boundaries:
+
+1. Normalize native messages to the shared DTOs and preserve native message ID, correlation ID, channel/thread identity, attachments, and response target.
+2. Enforce native guild/room/channel/user/pairing/role policy before thread/room creation or gateway dispatch.
+3. Select the logical agent from trusted configuration; never from a caller-controlled provider, model, harness, or route field.
+4. Keep the route stable when the gateway changes runtime provider or harness.
+5. Validate egress route and destination before sending; bound chunks, retries, and attachment metadata.
+6. Return sanitized errors and expose non-throwing lifecycle health for ordinary disconnected state.
+7. Add happy-path and failure-path tests for authorization ordering, replay/idempotency, route integrity, native side effects, egress, reconnect, and health.
+
+These are implementation constraints for future work, not evidence that the missing shared registry already exists.
+
+## Parity status
+
+### Telegram: raw legacy adapter, not shared parity
+
+The current Telegram source:
+
+- launches Telegraf and a Socket.IO client;
+- reads `TELEGRAM_BOT_TOKEN` and `TELEGRAM_GATEWAY_URL` through the gateway plugin factory, whose URL default is `http://localhost:14242`;
+- accepts text messages only and ignores attachment-only messages;
+- maps each Telegram `chat.id` to `telegram-<chatId>`;
+- emits a raw `{ conversationId, content, role: "user" }` object rather than `ChannelIngressDto`;
+- has no shared DTO import, channel binding, principal/role policy, native message ID, attachment mapping, route-safe egress, or health method; and
+- has no package test file in this checkout; its script is `vitest run --passWithNoTests`.
+
+Its Socket.IO connection does not send the Discord service token or a BetterAuth session. A configured `TELEGRAM_BOT_TOKEN` therefore must not be described as an authenticated official channel. Shared Telegram parity requires a separate implementation and focused security/contract tests.
+
+### Matrix: no current channel adapter
+
+No current gateway adapter, shared-port wiring, channel binding, identity resolver, persistence boundary, authentication path, or focused channel test establishes Matrix as a Mosaic channel. Matrix code elsewhere in the repository belongs to other transport/runtime work and must not be promoted into channel-adapter instructions without a separate contract and evidence.
+
+### Shared registry: draft/unimplemented
+
+The current `PLUGIN_REGISTRY` is an array of `IChannelPlugin` lifecycle wrappers. It is not a registry of `OfficialChannelAdapter` instances and does not inject `ChannelIngressPort`/`ChannelEgressPort`, aggregate adapter health, or remove the gateway's Discord-specific auth/envelope/approval/stop/replay branches.
+
+A future registry must specify binding and credential ownership, ingress/egress injection, health/error semantics, compatibility with the existing Socket.IO clients, and tests proving that adapters cannot bypass gateway authorization or route validation before it can be documented as current architecture.
+
+## Safe verification commands
+
+The focused package commands used by the current Discord evidence are:
+
+```bash
+pnpm --filter @mosaicstack/types build
+pnpm --filter @mosaicstack/types typecheck
+pnpm --filter @mosaicstack/discord-plugin typecheck
+pnpm --filter @mosaicstack/discord-plugin lint
+pnpm --filter @mosaicstack/discord-plugin test
+cd apps/gateway && pnpm exec vitest run \
+  src/plugin/discord-ingress.security.spec.ts \
+  src/chat/chat.gateway-redaction.spec.ts \
+  src/__tests__/integration/tess-cross-surface.integration.test.ts
+```
+
+These commands do not require starting Gateway, Discord, Telegram, Matrix, a queue, or a database. The Discord package test includes its configured coverage thresholds; the gateway command is a focused Vitest run rather than a claim of full repository integration coverage.
+
+## Evidence
+
+- [`packages/types/src/channel/channel.dto.ts`](../../../packages/types/src/channel/channel.dto.ts) — shared DTOs, operations, route fields, and metadata types.
+- [`packages/types/src/channel/channel-adapter.ts`](../../../packages/types/src/channel/channel-adapter.ts) — adapter lifecycle, ingress/egress ports, and delivery errors.
+- [`plugins/discord/src/index.ts`](../../../plugins/discord/src/index.ts) — native translation, auth ordering, compatibility envelope, route-safe egress, retry, and health.
+- [`plugins/discord/src/index.test.ts`](../../../plugins/discord/src/index.test.ts) — focused Discord contract and behavior tests.
+- [`apps/gateway/src/chat/chat.gateway.ts`](../../../apps/gateway/src/chat/chat.gateway.ts) — service/session auth, signed envelope validation, replay, trusted agent selection, and raw stream events.
+- [`apps/gateway/src/chat/chat.gateway-auth.ts`](../../../apps/gateway/src/chat/chat.gateway-auth.ts) — timing-safe Discord service-token and BetterAuth session checks.
+- [`apps/gateway/src/plugin/discord-ingress.security.spec.ts`](../../../apps/gateway/src/plugin/discord-ingress.security.spec.ts) — gateway security and privileged-operation tests.
+- [`apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts`](../../../apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts) — control-flow test with explicit durable-session pre-enrollment; not ordinary Discord persistence evidence.
+- [`apps/gateway/src/plugin/plugin.interface.ts`](../../../apps/gateway/src/plugin/plugin.interface.ts), [`plugin.module.ts`](../../../apps/gateway/src/plugin/plugin.module.ts), and [`plugin.service.ts`](../../../apps/gateway/src/plugin/plugin.service.ts) — lifecycle-only host registry.
+- [`plugins/telegram/src/index.ts`](../../../plugins/telegram/src/index.ts) and [`plugins/telegram/package.json`](../../../plugins/telegram/package.json) — raw Telegram behavior and no-test script.
+- [Canonical channel protocol architecture](../architecture/channel-protocol.md) — shared contract and explicit current/draft boundary.
+- [Discord ingress security](../../ADMIN-GUIDE/security/discord-ingress.md) — administrator-facing config and auth claims.
+- [Discord conversations](../../USER-GUIDE/workflows/discord-conversations.md) — user-facing routing behavior.
+- [Developer Guide](../README.md)

docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md

@@ -0,0 +1,292 @@
+---
+title: Lease-broker operations
+type: runbook
+audience: developer
+status: current
+source_of_truth: false
+---
+
+# Lease-broker operations
+
+> **Status:** Current for repository inspection and test verification. Live broker
+> startup, recovery, lease mutation, service management, and cleanup remain
+> **held/non-operative**.
+>
+> **Operational authority:** This page authorizes only the non-mutating
+> inspection and test commands in [Safe static inspection](#safe-static-inspection).
+> It does not authorize starting a daemon or systemd unit, connecting to a live
+> socket, invoking recovery, promoting or revoking a lease, executing a
+> consequential runtime tool, or changing a database.
+
+The lease broker is a Linux-only internal process boundary. Its executable
+behavior is authoritative in the [shipped broker daemon](../../../packages/mosaic/framework/tools/lease-broker/daemon.py)
+and tests, not in this page. The current architecture references are:
+
+- [Broker protocol](../architecture/lease-broker-protocol.md) — framing,
+  kernel identity, ancestry, generations, persistence, and state transitions.
+- [Lease-broker security](../architecture/lease-broker-security.md) — trust
+  boundaries, filesystem hardening, observer behavior, and residuals.
+- [Whole mutator-class gate](../architecture/mutator-class-gate.md) — default
+  deny, launch choke points, and broker-owned promotion order.
+- [Compaction revocation](../architecture/compaction-revocation.md) — Claude
+  and Pi lifecycle observers, generation fencing, and the bounded residual.
+
+## Safe static inspection
+
+These are the only operative commands documented here. They inspect checked-in
+files or run isolated tests; they do not start a user service, activate a
+runtime, connect to PostgreSQL, or mutate repository/product state.
+
+### Source and launch inventory
+
+From the repository root, inspect the current implementation and its permanent
+runtime-launch inventory:
+
+```bash
+find packages/mosaic/framework/tools/lease-broker packages/mosaic/src/lease-broker packages/mosaic/src/mutator-gate -maxdepth 1 -type f -print | sort
+python3 packages/mosaic/framework/tools/lease-broker/check-runtime-launches.py --root . --json
+```
+
+The launch inventory is a static completeness guard. A clean result means the
+checked-in production launch sites are classified by the guard; it does not
+prove that a broker, runtime, or service is running.
+
+### Safe unit and static contract tests
+
+The focused standard-library tests can be run directly:
+
+```bash
+python3 packages/mosaic/src/lease-broker/daemon_deadline_unittest.py
+python3 packages/mosaic/src/lease-broker/normative_fragments_unittest.py
+python3 packages/mosaic/src/lease-broker/receipt_challenge_unittest.py
+python3 packages/mosaic/src/lease-broker/context_recovery_unittest.py
+python3 packages/mosaic/src/lease-broker/state_store_unittest.py
+python3 packages/mosaic/src/lease-broker/framework_skill_portability_unittest.py
+python3 packages/mosaic/src/mutator-gate/runtime_tools_unittest.py
+python3 packages/mosaic/src/mutator-gate/runtime_launch_guard_unittest.py
+python3 packages/mosaic/src/mutator-gate/version_coupling_unittest.py
+```
+
+`recovery_runtime_unittest.py` and `recovery_b1_adversarial_unittest.py` are
+also safe when run as tests: they use private temporary daemons, sockets, and
+fixtures, never the installed user service or a model stream. They are not
+operator recovery instructions:
+
+```bash
+python3 packages/mosaic/src/lease-broker/recovery_runtime_unittest.py
+python3 packages/mosaic/src/lease-broker/recovery_b1_adversarial_unittest.py
+```
+
+The [lease-broker Vitest acceptance suite](../../../packages/mosaic/src/lease-broker/lease-broker.acceptance.spec.ts)
+and [mutator-gate Vitest acceptance suite](../../../packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts)
+provide additional private-fixture coverage. Test-created child processes and
+Unix sockets are disposable test fixtures, not live-service authority.
+
+## Current implementation facts
+
+### Protected paths and persistence
+
+The broker and supervisor source establish these invariants:
+
+| Object             | Current contract                                                                                                                                                                                                                  |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Parent directory   | The parent containing the socket and state must already exist and have exactly mode `0700`.                                                                                                                                       |
+| Broker socket      | The daemon refuses an existing path or symlink, binds a new Unix socket, sets it to `0600`, and removes only the inode it created during normal shutdown.                                                                         |
+| State file         | A present state file must be a regular, non-symlink file protected as mode `0600`, no larger than 4 MiB, and valid state-version-1 JSON. Corrupt, incompatible, oversized, or unsafe state refuses startup.                       |
+| State writes       | Changes are serialized through a mode-`0600` temporary file, complete-write loop, `fsync`, atomic replace, and parent-directory `fsync`. Post-replace durability uncertainty poisons the store and terminates service processing. |
+| Volatile authority | `VERIFIED` leases are not restored as live authority after broker restart. Persisted session identity and valid pending-token state are separate from volatile lease state.                                                       |
+| Runtime generation | `launch-runtime.py` creates `generation-<broker-session>.state` beside the socket. It is an owner-only, locked, monotonic generation file; unsafe, non-regular, oversized, or non-private state fails closed.                     |
+
+The resolved socket path is, in order: explicit
+`MOSAIC_LEASE_BROKER_SOCKET`, `$XDG_RUNTIME_DIR/mosaic-lease/broker.sock`, or
+`/run/user/<uid>/mosaic-lease/broker.sock`. The state file is `state.json` next
+to that resolved socket. The production observer transport is a separate
+`receipt-observer.sock` by default; `--test-observer-file` is a private test
+fixture option, not a production deployment path.
+
+The supervisor implementation can materialize a user unit, wrapper, and
+co-located daemon sources under caller-supplied paths, but
+[`applyBrokerSupervisor`](../../../packages/mosaic/src/lease-broker/broker-supervisor.ts)
+never runs `systemctl`, starts `daemon.py`, or enables the unit. The checked-in
+unit and [`start-lease-broker.sh`](../../../packages/mosaic/framework/tools/lease-broker/start-lease-broker.sh)
+are therefore implementation inputs, not live activation authority for this
+page.
+
+### Protocol and identity boundary
+
+The protocol accepts one UTF-8 JSON object followed by one newline, capped at
+64 KiB. The client must half-close its write side after the newline and before
+waiting for the response (`shutdown(SHUT_WR)` for POSIX clients or
+`socket.end()` for Node). Unterminated, multiple, delayed-second, malformed,
+oversized, or deadline-exceeded requests fail closed. This is an internal Unix
+socket protocol, not an HTTP/OpenAPI endpoint.
+
+The broker obtains `(pid, uid, gid)` from kernel `SO_PEERCRED`, binds the
+session to the anchor's `/proc/<pid>/stat` starttime, and revalidates every
+walked ancestor's starttime. A caller cannot choose `session_id`; a sibling or
+unrelated process cannot authenticate with another process's session. A higher
+runtime generation replaces the prior incarnation and revokes its tokens and
+lease authority; a lower generation is stale.
+
+### Lease and tool authorization
+
+The broker is the sole lease writer. The effective default-deny policy is:
+
+- Claude read-only classes: `Read`, `Grep`, `Glob`, `Ls`, and `Find`.
+- Pi read-only classes: `read`, `grep`, `find`, and `ls`.
+- Both runtimes expose the fixed `mosaic_context_recover` identity as the
+  constrained recovery exception.
+- Every other built-in, unknown, custom, MCP, shell, edit, write, deployment,
+  provider, or filesystem mutator is consequential and is denied while the
+  session is not `VERIFIED`.
+
+The normal broker transition is revoke-first and promote-last:
+
+1. `begin_verification` authenticates the broker-minted session and current
+   generation, revokes existing authority and pending tokens, validates the
+   exact source construction and binding, and enters a pending state.
+2. The receipt challenge and binding are broker-generated. A trusted observer
+   must provide the exact current-cycle assistant entry; caller-supplied
+   `latest_assistant_message` is rejected on the public broker socket.
+3. Promotion consumes the evidence-backed one-time token before volatile
+   `VERIFIED` becomes visible. A token or receipt cannot be replayed against a
+   later cycle.
+4. `revoke_lease`, generation replacement, broker restart, or monotonic TTL
+   expiry removes consequential-tool authority. TTL is positive and capped at
+   300 seconds.
+
+`launch-runtime.py` is the register-before-`exec` choke point for Claude and
+Pi. It performs the activation-capability version check, registers the anchor,
+creates the private generation file, exports the broker identity to descendants,
+and only then executes the requested runtime. Registration, capability,
+generation-file, broker-reply, or `exec` failure denies launch. Claude's raw
+`--dangerously-skip-permissions` flag is owned by this wrapper; callers request
+only its semantic dangerous mode.
+
+Claude's all-tools `PreToolUse` hook and Pi's `tool_call` handler submit the
+runtime-reported tool name to the gate. The gate does not inspect a shell string
+to decide that one command is safe. Missing identity, malformed input or reply,
+timeout, broker unavailability, unsafe generation state, and denial all fail
+closed.
+
+### Lifecycle and recovery boundaries
+
+Claude and Pi lifecycle observers use the same authenticated session and
+broker state machine. Compaction revocation and same-PID replacement behavior
+are summarized below:
+
+| Runtime event                                                  | Current source-backed behavior                                                                             |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Claude `PreCompact`                                            | Revoke before compaction; a failed hook blocks the lifecycle transition.                                   |
+| Claude `SessionStart` matcher `compact`                        | Revoke again after compacted context starts.                                                               |
+| Claude `SessionStart` matcher `resume\|clear`                  | Bump the private generation, then revoke the replacement incarnation.                                      |
+| Pi `session_before_compact`                                    | Revoke before compaction; failure cancels the transition.                                                  |
+| Pi `session_compact` then first `context`                      | Run one independent post-compaction revoke; a failed post-observer locally blocks later tools until retry. |
+| Pi `session_start` reason `reload`, `new`, `resume`, or `fork` | Bump the private generation before revoking and reusing the replacement session.                           |
+| Fired observer with unavailable broker                         | Advance the private generation as a local fence and return failure; do not continue consequential work.    |
+
+The [source-resident context-refresh skill](../../../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md)
+is a thin adapter over `recover-context.py`. Recovery begins with a validated
+normative-fragment construction, broker-side revoke-first transition, and a
+fresh `PENDING_DELIVERY` challenge. The trusted observer records only finalized
+Claude Stop-hook or Pi `message_end` content. Completion supplies no receipt or
+challenge argument; the broker obtains its current challenge, checks the exact
+observed entry, consumes evidence, and promotes last. Recovery does not accept
+normal-path receipt text as replayable authority.
+
+A receipt is only a delivery/liveness prerequisite. It is not a safety,
+obedience, comprehension, or residency proof. Absent, malformed,
+prefix-truncated, and observably mutated terminal receipts do not promote. A
+tail-preserving middle drop is explicitly not receipt-detectable and remains a
+server-side/T-C residual.
+
+### Named residual
+
+If both compaction observers are missed while a lease remains unexpired,
+consequential tools are **ALLOWED** inside the bounded residual stale window.
+The mutator gate makes no within-window action-count or timing claim. After the
+monotonic TTL expires, the next consequential tool is **DENIED**. This is
+separate from a fired observer that cannot reach the broker, which fails closed
+through lifecycle cancellation, a generation fence, and/or the Pi local latch.
+Protected-branch controls and required review/CI remain the irreducible
+server-side backstop for the T-C total-hook-miss boundary.
+
+## Held future procedure — non-operative
+
+There is no current command authority for the following live procedures. The
+sequence below records source-backed intent for a separately approved
+activation/recovery work package; it must not be copied into an operator shell.
+
+### Startup and restart outline (held)
+
+1. An activation owner would first materialize the exact framework unit,
+   wrapper, and co-located source copies, then verify the resolved parent,
+   socket, state, observer, and generation paths and their no-symlink/private
+   posture.
+2. The approved supervisor would start the daemon only after confirming that
+   the exact socket path is not owned by another process. `READY` from the
+   daemon and a live Unix socket would be health evidence; a unit file alone
+   would not be healthy.
+3. A broker crash would require preserving the state file, identifying the
+   socket owner, and making an explicit restart decision. Restart intentionally
+   clears volatile `VERIFIED` leases; it is not a way to restore authority.
+4. A leftover socket would be handled only after the owning service is
+   confirmed stopped and the exact path is deliberately reviewed. This page
+   supplies no deletion, `systemctl`, enablement, or start command.
+
+The source's `daemon.py` argument parser and the user unit show how a future
+activation is wired, but neither source file grants this page authority to
+invoke that wiring. `applyBrokerSupervisor` is materialization only; the
+supervisor source explicitly leaves enable/start as a separate held step.
+
+### Recovery outline (held)
+
+The future adapter flow is: runtime supplies validated construction and current
+non-negative epochs; broker performs `begin_recovery` revoke-first and returns
+one fresh receipt; the adapter delivers that exact receipt; the authenticated
+observer records the finalized assistant entry; and the adapter requests
+completion without presenting receipt text or a challenge. Any absent,
+malformed, stale, duplicated, or mismatched observation leaves the session
+`UNVERIFIED`; retry starts a new recovery cycle.
+
+Claude's adapter is restricted to the exact literal recovery argv shape checked
+by the gate. Pi uses only the registered `mosaic_context_recover` tool; Pi
+`bash` and all other tools remain gated. Do not manually invoke the revoker to
+restore authority, send assistant text through the public broker request, or
+reuse a normal-path receipt. The [context-refresh skill](../../../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md)
+and its [runtime boundary tests](../../../packages/mosaic/src/lease-broker/recovery_runtime_unittest.py)
+are references for future adapter qualification, not an active operator route.
+
+### Lease, mutator, and incident handling outline (held)
+
+- There is no supported operator CLI or HTTP endpoint for sending raw
+  `begin_verification`, `promote_lease`, `revoke_lease`, or `authorize_tool`
+  requests. Do not hand-craft JSON frames, mint tokens, replay receipts, or
+  treat a successful read-only authorization as a promotion.
+- After a runtime exits, its generation file may be removed only after an
+  approved check establishes that no process for that broker-minted session
+  remains. Retain stale files during incident analysis; they carry no lease
+  authority by themselves.
+- Corrupt, oversized, symlinked, or non-regular state must be preserved for
+  review and not overwritten in place. Establishing new state is an explicit
+  operational decision that invalidates prior sessions and tokens; no recovery
+  command is supplied here.
+- Directory `0700` and socket/state `0600` are same-principal hardening only.
+  They do not prevent the same UID from unlinking and replacing a socket. A
+  stronger deployment needs an external protected proxy, ACL, or service
+  boundary that preserves the peer identity required by `SO_PEERCRED` and
+  ancestry checks. No such deployment procedure is current here.
+
+## Related source and tests
+
+- [Broker daemon](../../../packages/mosaic/framework/tools/lease-broker/daemon.py)
+- [Register-and-exec launcher](../../../packages/mosaic/framework/tools/lease-broker/launch-runtime.py)
+- [Mutator gate](../../../packages/mosaic/framework/tools/lease-broker/mutator-gate.py)
+- [Recovery command](../../../packages/mosaic/framework/tools/lease-broker/recover-context.py)
+- [Lease broker acceptance tests](../../../packages/mosaic/src/lease-broker/lease-broker.acceptance.spec.ts)
+- [Mutator gate acceptance tests](../../../packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts)
+- [Pi lifecycle tests](../../../packages/mosaic/src/mutator-gate/pi-compaction-lifecycle.spec.ts)
+
+This migration changes documentation placement and verified wording only. It does
+not start or change the broker, a runtime, systemd, PostgreSQL, or any other
+service.

docs/README.md

@@ -0,0 +1,222 @@
+# Mosaic Stack Documentation
+
+This directory is the canonical home for Mosaic Stack product, architecture, API, operations, and delivery documentation.
+
+This file is the **documentation contract**. It defines where information belongs, which files are authoritative, how pages connect, and how agents must maintain the documentation set. The structure below is the target structure for the documentation migration; existing content is not considered migrated until it has been classified and moved deliberately.
+
+## Start here
+
+Choose the path that matches your purpose:
+
+- **Understand the product:** start with [`PRD.md`](PRD.md), then use the user guide and the architecture overview.
+- **Use Mosaic Stack:** use `USER-GUIDE/`.
+- **Install, configure, deploy, or recover Mosaic Stack:** use `ADMIN-GUIDE/`.
+- **Change or extend the codebase:** use `DEVELOPER-GUIDE/`.
+- **Integrate with the gateway:** use `API/`.
+- **Find a page or follow the documentation graph:** use [`SITEMAP.md`](SITEMAP.md).
+- **Understand active delivery state:** read [`TASKS.md`](TASKS.md), subject to its single-writer policy.
+
+The root README is an atlas and authoring guide, not a replacement for the user, administrator, developer, or API books.
+
+## Canonical directory structure
+
+The following is the complete target structure. Directories and pages may be created incrementally, but new documentation must use these locations.
+
+```text
+docs/
+├── README.md                         # this documentation contract and atlas
+├── PRD.md                            # canonical requirements source
+├── TASKS.md                          # active orchestrator task rollup
+├── SITEMAP.md                        # complete navigation index
+├── .obsidian/                        # optional Obsidian vault metadata only
+│
+├── USER-GUIDE/                       # end-user documentation
+│   ├── README.md                     # user-book index
+│   ├── getting-started/              # first install/use and quickstarts
+│   ├── concepts/                     # user-facing concepts and terminology
+│   ├── workflows/                    # task-oriented user procedures
+│   └── troubleshooting/              # user-visible failures and fixes
+│
+├── ADMIN-GUIDE/                      # operator and administrator documentation
+│   ├── README.md                     # admin-book index
+│   ├── installation/                 # installation and prerequisites
+│   ├── configuration/                # configuration and environment
+│   ├── deployment/                   # deployment topologies and rollout
+│   ├── operations/                   # routine operation and observability
+│   ├── security/                     # auth, RBAC, secrets, and security controls
+│   └── recovery/                     # incident response, backup, and recovery
+│
+├── DEVELOPER-GUIDE/                  # contributor and maintainer documentation
+│   ├── README.md                     # developer-book index
+│   ├── architecture/                # system model and technical design
+│   │   ├── README.md                 # architecture index
+│   │   ├── system-overview.md        # platform boundary and major flows
+│   │   ├── component-map.md          # apps, packages, plugins, and dependencies
+│   │   ├── data-flow.md              # data, event, and control-plane movement
+│   │   ├── security-model.md         # trust boundaries and authority model
+│   │   ├── decisions/                # ADRs and approved design decisions
+│   │   └── rfcs/                     # proposals and protocol RFCs
+│   ├── packages/                     # package- and application-level guides
+│   ├── local-development/            # local setup and safe development routes
+│   ├── testing/                      # test strategy and verification workflow
+│   ├── contributing/                 # contribution and review workflow
+│   └── integrations/                 # plugin, provider, and adapter authoring
+│
+├── API/                              # machine- and human-readable API contract
+│   ├── README.md                     # API documentation index
+│   ├── OPENAPI.yaml                  # canonical OpenAPI contract
+│   └── ENDPOINTS.md                  # endpoint, auth, permission, and error index
+│
+├── assets/                           # diagrams and documentation media
+├── reports/                          # evidence and findings; never normative by itself
+│   ├── code-review/                  # review reports
+│   ├── documentation/                # documentation audits and checklists
+│   ├── qa/                           # QA and verification reports
+│   ├── security/                     # security reviews and threat evidence
+│   └── deferred/                     # unresolved or explicitly deferred findings
+├── tasks/                            # archived task snapshots and learnings
+├── plans/                            # approved design and implementation plans
+├── scratchpads/                      # active task-specific working notes
+├── releases/                         # release notes and compatibility notes
+├── archive/                          # superseded but intentionally retained docs
+└── _old_structure/                   # temporary read-only migration quarantine
+```
+
+### Directory rules
+
+- `.obsidian/` is optional tool metadata. It is not a content directory. Do not put Markdown pages, reports, plans, task notes, or source-of-truth files there.
+- `USER-GUIDE/`, `ADMIN-GUIDE/`, and `DEVELOPER-GUIDE/` are books. Each book must have a `README.md` that links to every chapter and page in that book.
+- Each chapter is a directory for one topic area. Each page should cover one concern or workflow.
+- `API/OPENAPI.yaml` is the API contract. `API/ENDPOINTS.md` explains details that OpenAPI cannot fully express.
+- `reports/`, `tasks/`, `plans/`, `scratchpads/`, `releases/`, and `archive/` are artifact boundaries, not alternative guide books.
+- `_old_structure/` is temporary migration quarantine. It is read-only, is not current documentation, and is never a destination for new work.
+- `docs/mosaic-stack/` is retired as a content boundary. Do not create new files there. Cross-cutting architecture belongs in `DEVELOPER-GUIDE/architecture/` and navigation belongs here and in `SITEMAP.md`.
+- Do not add miscellaneous Markdown files directly under `docs/`. The permitted root files are `README.md`, `PRD.md`, `TASKS.md`, and `SITEMAP.md`; all other content belongs in a scoped directory.
+
+## Where agents must place documents
+
+Classify a document by its primary reader and purpose before creating it. Use this matrix instead of guessing from an existing filename.
+
+| Content                                                                    | Required location                                                      | Examples                                                  |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
+| Documentation contract and top-level map                                   | `docs/README.md`                                                       | Folder rules, source-of-truth policy, authoring workflow  |
+| Product requirements and acceptance criteria                               | `docs/PRD.md` or an explicitly scoped workstream PRD                   | Objectives, scope, requirements, acceptance criteria      |
+| Active orchestrator task state                                             | `docs/TASKS.md`                                                        | Milestone/task rollup; single writer is the orchestrator  |
+| Documentation navigation                                                   | `docs/SITEMAP.md` and the relevant book `README.md`                    | Page indexes and reader paths                             |
+| User-visible workflow or troubleshooting                                   | `docs/USER-GUIDE/<chapter>/`                                           | Chat, projects, task workflows, user setup                |
+| Installation, configuration, deployment, operations, security, or recovery | `docs/ADMIN-GUIDE/<chapter>/`                                          | SSO, tiers, secrets, health checks, incident runbooks     |
+| Architecture, component map, data flow, package design, ADR, or RFC        | `docs/DEVELOPER-GUIDE/architecture/` or its relevant developer chapter | System design, protocol decisions, package contracts      |
+| Local development, testing, contribution, or integration authoring         | `docs/DEVELOPER-GUIDE/<chapter>/`                                      | Setup, test commands, plugin development                  |
+| HTTP/WebSocket API contract                                                | `docs/API/OPENAPI.yaml` and `docs/API/ENDPOINTS.md`                    | Paths, schemas, auth, permissions, errors                 |
+| Diagram, screenshot, or other documentation media                          | `docs/assets/` or an owning chapter's asset directory                  | Architecture diagrams, workflow images                    |
+| Approved design or implementation plan                                     | `docs/plans/`                                                          | Design docs and task-by-task execution plans              |
+| Active task working notes and verification log                             | `docs/scratchpads/<task-id>-<slug>.md`                                 | Assumptions, progress, commands, evidence, blockers       |
+| Code review, QA, audit, security, or deferral evidence                     | `docs/reports/<category>/`                                             | Review findings, test reports, security evidence          |
+| Archived task snapshot or orchestrator learning                            | `docs/tasks/`                                                          | Closed task breakdowns and retained learnings             |
+| Release notes or version-specific compatibility information                | `docs/releases/`                                                       | Release summaries, upgrade notes, deprecations            |
+| Superseded documentation that must remain discoverable                     | `docs/archive/`                                                        | Historical guides, retired proposals, old mission records |
+
+If content seems to fit multiple locations, choose one canonical home and link to it from the other relevant indexes. Do not create copies merely to satisfy multiple audiences.
+
+## Source-of-truth and precedence
+
+Use these rules when documents disagree:
+
+1. **Requirements:** `PRD.md` is the project requirements source. A scoped PRD may add detail, but must link to and remain consistent with the root PRD.
+2. **Active work state:** `TASKS.md` is the active orchestrator rollup. Workers read it; they do not rewrite its status or schema unless the orchestrator authorizes that change.
+3. **API:** `API/OPENAPI.yaml` is the machine-readable API contract. `ENDPOINTS.md` is the human index and may explain constraints not represented by OpenAPI.
+4. **Current behavior:** guide pages describe verified current behavior. If implementation changes, update the affected guide in the same logical change set.
+5. **Architecture and decisions:** approved decisions under `DEVELOPER-GUIDE/architecture/decisions/` and RFCs explain why the system has its current shape. They do not silently override the PRD or API contract.
+6. **Evidence:** reports record what was reviewed, tested, or deferred. They are evidence, not a substitute for current requirements or operational instructions.
+7. **Plans:** plans describe intended work. After delivery, update the canonical guide, contract, or decision page rather than treating the plan as the current behavior.
+8. **Scratchpads:** scratchpads are working memory and verification records. They are not product documentation and must not become hidden requirements.
+9. **Archive:** archived pages are historical. Every retained page should identify its status and replacement, if one exists.
+10. **Code is authoritative for executable behavior:** documentation must not claim commands, paths, APIs, or safety properties that the current code and tests do not support. When the desired behavior differs from current behavior, record the desired behavior in the PRD or an approved design and label operational procedures as held/non-operative when necessary.
+
+## Page conventions
+
+Every canonical page should:
+
+1. Use a descriptive lowercase kebab-case filename, except for established root control files and required API filenames.
+2. Cover one concern, concept, decision, or workflow.
+3. Start with a clear title and a short purpose statement.
+4. Identify its audience and lifecycle status when it is more than a simple index.
+5. State prerequisites, dependencies, and source-of-truth references.
+6. Mark examples and commands as current, illustrative, held, or non-operative when that distinction matters.
+7. Include an owner or maintenance responsibility for operationally sensitive content.
+8. Link to the relevant book index and related canonical pages.
+
+Recommended front matter for canonical pages:
+
+```yaml
+---
+title: Human-readable page title
+type: guide
+audience: developer
+status: current
+source_of_truth: false
+---
+```
+
+Allowed `type` values include `guide`, `concept`, `reference`, `decision`, `rfc`, and `runbook`. Allowed `audience` values are `user`, `admin`, `developer`, and `all`. Allowed `status` values are `current`, `draft`, `deprecated`, and `historical`.
+
+Indexes may omit front matter when their purpose is self-evident. A page with normative authority must explicitly identify the authority it owns and the boundaries of that authority.
+
+## Obsidian and link conventions
+
+Mosaic Stack documentation is compatible with Obsidian without making Git-hosted navigation unusable.
+
+- Use Obsidian wikilinks for graph-oriented internal relationships, for example `[[DEVELOPER-GUIDE/architecture/component-map|Component map]]`.
+- Use normal relative Markdown links in `SITEMAP.md` and book `README.md` indexes so links render on Gitea/GitHub and other Markdown hosts. Obsidian resolves these links too.
+- Use `Related`, `Depends on`, and `Referenced by` sections when a page has meaningful relationships to other pages.
+- Use wikilink heading targets when a specific section matters, for example `[[DEVELOPER-GUIDE/architecture/system-overview#Gateway boundary|Gateway boundary]]`.
+- Omit `.md` in wikilinks. Use an alias when the path is not a readable label.
+- Use standard Markdown links for external URLs, source files, commands, and API paths.
+- Link to stable repository-relative paths, not temporary branches, line numbers, or machine-local paths.
+- Every current canonical page must be reachable from a book index or `SITEMAP.md`; do not create orphan pages.
+- Do not use `_old_structure/` links as current navigation. Historical references must explain why the page is retained and point to its replacement.
+
+## Authoring workflow for agents
+
+For every documentation change:
+
+1. **Search first.** Look for an existing page, requirement, report, task, or scratchpad before creating a new file.
+2. **Classify.** Choose the primary audience, content type, lifecycle status, and source-of-truth role.
+3. **Choose the canonical home.** Apply the placement matrix; do not place content in the docs root or `docs/mosaic-stack/`.
+4. **Write one concern.** Keep the page focused and link to existing pages instead of copying them.
+5. **Connect the page.** Add it to the owning book index and `SITEMAP.md`; add `Related`, `Depends on`, or `Referenced by` links where useful.
+6. **Record non-trivial work.** Create or update `docs/scratchpads/<task-id>-<slug>.md` with objective, assumptions, progress, commands, risks, and evidence. Active `docs/TASKS.md` changes remain under its single-writer policy.
+7. **Verify claims.** Check commands, paths, API schemas, permissions, and status against source and tests. Label held or non-operative procedures explicitly.
+8. **Format and review.** Run the repository's Markdown formatting check, inspect links and headings, and review the diff for stale paths or duplicated authority.
+9. **Commit a coherent change.** Keep documentation changes with the related code/API/operation change when applicable, and do not include unrelated staged files.
+
+## Migration policy
+
+The initial structure pass defined the target structure without moving or rewriting the existing documentation set. Subsequent migration slices may move or rewrite classified pages deliberately, with repository references and indexes updated together.
+
+- Treat `_old_structure/` as read-only migration quarantine. Do not add new content there.
+- Treat the current root-level legacy pages (`openapi-tess.yaml` and the task/mission documents) as migration backlog, not permission to create more root files. The former empty `QUICKSTART.md` placeholder now lives as `USER-GUIDE/getting-started/quickstart.md`; the verified SSO runbook lives under `ADMIN-GUIDE/security/`; historical evidence such as the P8-003 performance report belongs under `reports/qa/`.
+- Candidate destinations include `USER-GUIDE/getting-started/`, `ADMIN-GUIDE/security/`, `DEVELOPER-GUIDE/architecture/`, `API/`, `tasks/`, `plans/`, and `archive/`; classify each page before moving it.
+- `docs/fleet/` is an executable documentation contract consumed by current source and tests; keep that complete book at its canonical path. Federation and other authority surfaces may also have live consumers. Update any such path only through an explicitly coordinated source/test and authority migration.
+- When a page is moved, update all repository links, source comments, tests, book indexes, and `SITEMAP.md` in the same logical change.
+- Preserve historical evidence in `reports/`, `tasks/`, `releases/`, or `archive/` instead of mixing it into current guides.
+- Remove the empty `docs/mosaic-stack/` boundary only after confirming no source, test, or documentation reference requires it.
+- Remove `_old_structure/` only after migration verification proves that current navigation and required historical retention are intact.
+
+## Current transition state
+
+Classified migration is active and the audience books now contain verified current pages. During this transition:
+
+- The target directories listed above remain the placement contract; some planned chapters are not populated yet.
+- `docs/_old_structure/` remains available for migration evidence but is not current documentation or command authority.
+- `docs/fleet/`, `docs/native-kanban-sot/`, `docs/requirements/native-kanban-sot.md`, and the KBN-101 hold-site documents remain at their canonical paths because they are active executable or authority surfaces. Their placement cannot change through documentation-only cleanup.
+- Root control and API artifacts remain until their authority and destination decisions are approved.
+- `docs/SITEMAP.md` contains only resolvable current navigation plus a non-linked summary of authority-gated migration groups.
+- No external publishing platform is assumed. The canonical source remains this repository under `docs/`.
+
+## Current migration boundaries
+
+- Do not bulk-promote or bulk-rewrite quarantined documentation; classify and verify each coherent slice.
+- Do not rewrite product requirements, orchestrator-owned task state, mission status, or the API contract without the required authority decision.
+- Do not create a documentation website or publishing pipeline as part of content migration.
+- Do not treat Obsidian metadata as product or project source of truth.

docs/SITEMAP.md

@@ -1,103 +1,97 @@
 # Documentation Sitemap
 
-## Compaction refresh lease broker
+> **Status:** Current navigation index. Quarantined and authority-gated material is summarized without being presented as current guidance.
 
-- [Internal broker protocol](architecture/lease-broker-protocol.md) — kernel identity, ancestry and generation invariants, framed requests, responses, and persisted cycle bindings.
-- [Broker operations](guides/lease-broker-operations.md) — protected paths, startup, constrained recovery, fail-closed posture, distinct-principal deployment, and residual risk.
-- [Constrained recovery skill](../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md) — source-resident thin wrapper, receipt scope, C4 replay boundary, and T-C middle-drop disclosure.
-- [Lease-broker security notes](architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements.
-- [Whole mutator-class gate](architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary.
-- [Compaction revocation lifecycle](architecture/compaction-revocation.md) — Claude/Pi observer matrix, same-PID generation rollover, failure fencing, and the named bounded residual stale window.
+## Start here
 
-## CLI and skill management
+- [Documentation atlas](README.md) — placement, source-of-truth, linking, and migration rules.
+- [User guide](USER-GUIDE/README.md) — end-user workflows and product behavior.
+- [Administrator guide](ADMIN-GUIDE/README.md) — installation, configuration, operations, security, and recovery.
+- [Developer guide](DEVELOPER-GUIDE/README.md) — architecture, testing, integrations, and contributor material.
+- [API documentation](API/README.md) — API contract migration status.
+- [Reports index](reports/README.md) — review, audit, QA, security, and retained evidence.
+- [Archive index](archive/README.md) — superseded historical pages.
 
-- [Skill registration user guide](guides/user-guide.md#claude-code-skill-registration) — register, unregister, list statuses, automatic install/update reconciliation, and Claude reload behavior.
-- [Skill bridge developer guide](guides/dev-guide.md#claude-code-skill-bridge) — path-validation, ownership, clobber-protection, install/update wiring, tests, and Pi/Codex scope notes.
+## Product and delivery control
 
-## Fleet configuration management
+- [Product requirements](PRD.md) — normative requirements; currently marked draft and retaining authority-gated legacy references.
+- [Active task rollup](TASKS.md) — orchestrator-owned work state; workers do not modify it.
+- [MVP mission manifest](MISSION-MANIFEST.md) — control-plane mission rollup; activity and status remain under its authorized owner.
+- [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — complete baseline inventory, evidence labels, broken-link clusters, and migration recommendations.
 
-- [Fleet configuration entry point](fleet/README.md) — desired-versus-observed decision tree and complete operator link map.
-- [Desired, derived, and observed state](fleet/concepts/desired-vs-observed-state.md) — roster authority, generation, ownership, and drift.
-- [Identity, class, and runtime](fleet/concepts/identity-class-runtime.md) — stable name, display alias, class, runtime, provider, and model separation.
-- [Role authority and leases](fleet/concepts/role-authority-and-leases.md) — validator/merge-gate separation and bounded lease authority.
-- [Generated launch chain](fleet/concepts/generated-env-launch-chain.md) — strict data parsing, precedence, and quarantine.
-- [Roster v2 structural contract](fleet/reference/roster-v2-fields.md) — schema, supported values, required fields, defaults, and constraints.
-- [Fleet CLI reference](fleet/reference/cli.md) — local desired-state commands, JSON/exit behavior, and gateway-catalog separation.
-- [Lifecycle transitions](fleet/reference/lifecycle-transitions.md) — create/apply/reboot/migration/rollback boundaries.
-- [Status and drift](fleet/reference/status-and-drift.md) — desired/managed/observed state and current/future classifications.
-- [Safe agent CRUD](fleet/how-to/create-update-delete-agent.md) — expected generation, dry-run, and partial-failure recovery.
-- [Local lifecycle operations](fleet/how-to/start-stop-restart.md) — persisted versus one-shot actions.
-- [Configurable interaction instance](fleet/how-to/configure-tess-interaction.md) and [validator instance](fleet/how-to/configure-ultron-validator.md) — generic identities and protected limits.
-- [Reconcile and recover](fleet/operations/reconcile-and-recover.md) — plan/apply lock and recovery behavior.
-- [Environment quarantine](fleet/operations/env-quarantine.md) — private evidence and value-free diagnostics.
-- [Systemd/tmux troubleshooting](fleet/operations/systemd-tmux-troubleshooting.md) — socket, holder, unmanaged-session, and lock decisions.
-- [Backup/restore boundary](fleet/operations/backup-restore.md) and [upgrade-assets hold](fleet/operations/upgrade-assets.md).
-- [v1-to-v2 migration preview](fleet/migration/v1-to-v2.md) and [executable artifact dispositions](fleet/migration/example-profile-disposition.md).
-- [FCM M5 closure evidence](reports/documentation/758-fleet-config-ia-closure.md) and [approved deferrals](reports/deferred/758-fleet-config-deferrals.md).
+## Protected current authority and executable books
 
-## Official channel plugins
+These paths remain canonical because current source/tests consume them or because the KBN authority process protects them. Relocation requires an explicitly coordinated authority and consumer migration, not documentation-only cleanup.
 
-- [Channel protocol architecture](architecture/channel-protocol.md) — shared lifecycle, message, stable-route, authorization, and response-target contracts.
-- [Discord administrator configuration](guides/admin-guide.md#discord-ingress-security) — secrets, allowlists, bindings, role policy, and thread permissions.
-- [Discord user workflow](tess/USER-GUIDE.md#discord-conversations) — in-channel messages, mention-created threads, and runtime-transparent continuity.
-- [Channel plugin authoring](tess/PLUGIN-GUIDE.md#official-channel-adapter-contract) — requirements for future Matrix, Slack, and other official adapters.
-- [Discord package guide](../plugins/discord/README.md) — package behavior, configuration shape, and development commands.
+- [Fleet configuration management](fleet/README.md) — executable roster-v2 operator book, schema, examples, and north-star projections.
+- [Fleet local canary](guides/fleet-local-canary.md) — protected Fleet validation procedure referenced by the current developer hold-site guide.
+- [Native Kanban/SOT index](native-kanban-sot/INDEX.md) — active canonical KBN contract and workstream index.
+- [Native Kanban/SOT requirements](requirements/native-kanban-sot.md) — active ratified requirements surface.
+- [KBN-101 database role split](native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md) — active held database authority contract.
+- [Developer hold-site guide](guides/dev-guide.md) — protected current KBN-101 development boundary.
+- [Deployment hold-site guide](guides/deployment.md) — protected, non-operative PostgreSQL/deployment boundary.
+- [Tier-migration hold-site guide](guides/migrate-tier.md) — protected secure migration route and hold boundary.
+- [Federation setup hold site](federation/SETUP.md) — protected KBN-101 setup boundary; follow its explicit holds.
 
-## Native Kanban and canonical task SOT
+## User documentation
 
-- [Canonical requirements](requirements/native-kanban-sot.md) — ratified P0–P3 requirements and acceptance criteria.
-- [Workstream index](native-kanban-sot/INDEX.md) — artifact map, lane partition, and delivery order.
-- [Mission manifest](native-kanban-sot/MISSION-MANIFEST.md) — scope, authority, invariants, and gate model.
-- [Task decomposition](native-kanban-sot/TASKS.md) — dependency-ordered implementation slices and ownership boundaries.
-- [KBN-101 database role split](native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md) — rc.16 direct-Drizzle storage-wrapper hold: legacy N-1/uncertified/non-operative pending -02/-03/-06/-08; exact README/user-guide wrapper forms fail before masking and source-consistency rejects runner-delegation copy; held bootstrap → TLS/roles → run → verify → readiness; plus prior attestation, pgvector owner, classifier, TLS, activation, and certification prerequisite.
-- [Federated tier data migration](guides/migrate-tier.md) — active KBN-101-07 operator route: runner-produced target attestation, dedicated non-DDL importer, and paired credential-/attestation-file references only.
-- [Frozen shared contract](native-kanban-sot/SHARED-CONTRACT.md) — schema, API, Coordinator, health, recovery, and migration contracts.
-- [KBN-101 exact-head security review](reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) — retained prior REQUEST CHANGES evidence for `da742ca`; rc.16 awaits independent exact-head re-review after closing the current generic storage-wrapper authority HIGH finding.
-- [Initial independent review](reports/native-kanban-sot/canon-initial-review-no-go.md) — KCR-001–016 findings that blocked the first draft.
-- [Final independent re-review](reports/native-kanban-sot/canon-final-rereview-go.md) — closure evidence and GO verdict.
-- [Ultron final gate](reports/native-kanban-sot/ultron-final-go.md) — final requirements, authority, schema, migration, recovery, and evidence review.
+- [Quickstart](USER-GUIDE/getting-started/quickstart.md) — installed-CLI first-use route with local PGlite safety boundaries.
+- [Web dashboard](USER-GUIDE/product/web-dashboard.md) — current routes, views, chat persistence, settings, and admin behavior.
+- [Discord conversations](USER-GUIDE/workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow.
 
-## Tess interaction agent
+## Administrator documentation
 
-### Operator guides
+- [Administrator operations](ADMIN-GUIDE/operations/README.md) — current local procedures and explicitly held outlines.
+- [Upgrade safety and recovery](ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md) — installed-CLI/local-PGlite upgrade and framework recovery.
+- [Mos connector lease operations](ADMIN-GUIDE/operations/mos-connector-lease-operations.md) — held/non-operative M1 outline while policy remains deny-all.
+- [Administrator security](ADMIN-GUIDE/security/README.md) — current security chapter index.
+- [SSO providers](ADMIN-GUIDE/security/sso-providers.md) — Authentik, WorkOS, and Keycloak configuration and discovery.
+- [Discord ingress security](ADMIN-GUIDE/security/discord-ingress.md) — service authentication, allowlists, bindings, roles, replay, and failure controls.
 
-- [User guide](tess/USER-GUIDE.md) — authorized session, attach, send, stop, and handoff workflows.
-- [Admin guide](tess/ADMIN-GUIDE.md) — deployment configuration, policy, and approval controls.
-- [Developer guide](tess/DEVELOPER-GUIDE.md) — provider contracts, scope boundaries, and test workflow.
-- [Plugin guide](tess/PLUGIN-GUIDE.md) — adapter, redaction, and identity-as-data requirements.
-- [Operations guide](tess/OPERATIONS-GUIDE.md) — readiness, recovery, and incident-safe procedures.
+## Developer documentation
 
-### Architecture and security
+- [Architecture index](DEVELOPER-GUIDE/architecture/README.md) — current architecture contracts, decisions, and draft RFCs.
+- [Channel protocol](DEVELOPER-GUIDE/architecture/channel-protocol.md) — shared DTOs and current Discord compatibility boundary; future adapters are draft.
+- [Lease-broker protocol](DEVELOPER-GUIDE/architecture/lease-broker-protocol.md) — authenticated Unix-socket protocol and persistence boundary.
+- [Lease-broker security](DEVELOPER-GUIDE/architecture/lease-broker-security.md) — identity, ancestry, filesystem, observer, and residual boundaries.
+- [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny tool authorization and launch choke point.
+- [Compaction revocation](DEVELOPER-GUIDE/architecture/compaction-revocation.md) — lifecycle observers, generation fencing, and residual stale window.
+- [Architecture decisions](DEVELOPER-GUIDE/architecture/decisions/README.md) — implemented and accepted boundaries.
+- [Mos runtime portability M1](DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md) — logical identity, connector lease, grants, audit, and fencing.
+- [Architecture RFCs](DEVELOPER-GUIDE/architecture/rfcs/README.md) — draft proposals without operational authority.
+- [Optional AI egress gateways](DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md) — draft proposal; LiteLLM and Bifrost are not integrated.
+- [Lease-broker operations and verification](DEVELOPER-GUIDE/testing/lease-broker-operations.md) — safe static/test workflow; live procedures remain held.
+- [Channel adapter authoring](DEVELOPER-GUIDE/integrations/channel-adapters.md) — current shared contract and Discord reference boundary.
 
-- [Architecture](tess/ARCHITECTURE.md)
-- [Threat model](tess/THREAT-MODEL.md)
-- [Mos coordination boundary](tess/MOS-COORDINATION.md)
-- [Hermes runtime adapter design](tess/hermes-runtime-adapter-design.md)
-- [Operator plugin sketch](tess/M4-003-OPERATOR-PLUGIN-SKETCH.md)
+## API transition
 
-### API contract
+- [API index](API/README.md) — consolidated gateway contract remains planned.
+- [Legacy Tess-scoped OpenAPI contract](openapi-tess.yaml) — valid OpenAPI 3.1 artifact with incomplete gateway coverage; canonical scope requires maintainer approval.
 
-- [Tess OpenAPI contract](openapi-tess.yaml)
+## Evidence and planning
 
-### Migration and qualification
+- [Reports index](reports/README.md) — all tracked report categories and evidence boundaries.
+- [Archived missions](archive/missions/README.md) — historical CLI, harness, install UX, and storage-abstraction delivery records.
+- [Archived planning](archive/planning/README.md) — historical briefs, board reviews, and work-package specifications.
+- [Archived work records](archive/work-records/README.md) — historical task scratchpads without live consumers.
+- [P8-003 performance report](reports/qa/p8-003-performance-optimization.md) — historical implementation evidence, not a current SLO.
+- [Plans index](plans/README.md) — approved intent and implementation/audit plans.
+- [Documentation information-architecture design](plans/2026-08-10-docs-information-architecture-design.md) — approved documentation structure decision.
+- [Documentation catalog-audit plan](plans/2026-08-10-docs-catalog-audit.md) — evidence method and migration acceptance criteria.
+- [Scratchpads index](scratchpads/README.md) — working memory and verification records.
+- [Documentation migration scratchpad](scratchpads/DOCS-IA-002-catalog-audit.md) — coordinator progress, verification, and resumability record.
 
-- [Migration inventory](tess/M5-MIGRATION-INVENTORY.md)
-- [Cutover procedure](tess/M5-MIGRATION-CUTOVER.md)
-- [Rollback procedure](tess/M5-MIGRATION-ROLLBACK.md)
-- [Retention and deprecation evidence](tess/M5-MIGRATION-RETENTION-DEPRECATION.md)
-- [Verification matrix](tess/VERIFICATION-MATRIX.md)
-- [Documentation checklist](tess/M5-003-DOCUMENTATION-CHECKLIST.md)
-- [Independent Option 2 runtime-portability qualification (2026-07-14)](tess/qualification/2026-07-14-option2-runtime-portability.md)
+## Authority-gated migration backlog
 
-## Runtime-neutral Mos portability
+The complete file-level backlog remains in the [documentation catalog](reports/documentation/2026-08-10-docs-catalog-audit.md). The groups below are intentionally not linked as current pages:
 
-- [Optional AI egress gateway ADR](architecture/ADR-MOS-EGRESS-GATEWAYS.md) — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies.
-- [Runtime-neutral Mos identity and failover mission](https://git.mosaicstack.dev/mosaicstack/stack/issues/754)
-- [Logical identity and connector lease/fencing implementation](https://git.mosaicstack.dev/mosaicstack/stack/issues/755)
-- [M1 logical identity and fencing architecture](architecture/mos-runtime-portability-m1.md)
-- [M1 connector lease operations](guides/mos-connector-lease-operations.md)
+- **Fleet configuration:** the executable book is restored at `docs/fleet/`; any future audience-book relocation requires coordinated source/test and authority migration.
+- **Federation:** the protected KBN-101 setup hold site remains canonical; disposition of the rest of the workstream requires maintainer/orchestrator confirmation.
+- **Native Kanban/KBN-101:** active SSOT, requirements, and hold-site documents remain canonical; task state and future placement require product-owner, Task-18, and orchestrator decisions.
+- **Tess:** mixed user, administrator, developer, migration, qualification, and API material requires audience splitting and a decision on active versus historical status.
+- **Gateway API:** the Tess-scoped OpenAPI artifact must not be renamed into the canonical full-gateway contract until scope, authentication, errors, schemas, and transport coverage are approved.
+- **Deployment and tier migration:** PostgreSQL, federated, bare-metal, Compose, Gateway/Web activation, and migration-runner procedures remain held under the repository safety policy.
+- **Mixed legacy guides and scratchpads:** remaining records are coupled to control documents, tests/fixtures, mission evidence, or held procedures; migrate them with their owners.
+- **Compaction-refresh probes:** scripts are Mos-gated and path-coupled; do not move or execute them as documentation cleanup.
 
-## Comms evolution — Matrix-native MACP (design, draft)
-
-- [RFC-001 — MACP: a Mosaic-native, Matrix-native comms layer](rfcs/RFC-001-MACP-MATRIX-NATIVE.md) — Synapse + Mosaic appservice backbone, MACP v1 protocol, presence/escalation, federation, strangler migration off the Hermes MCP bridge.
-- [RFC-002 — Install, configuration & topology for the Matrix/MACP comms system](rfcs/RFC-002-INSTALL-CONFIG-TOPOLOGY.md) — open-source install topology modes, ACME cert provisioning, pluggable secret backend, and config precedence.
+`docs/_old_structure/` remains read-only migration quarantine. It is not current navigation and must not be used as command authority.

docs/SSO-PROVIDERS.md

@@ -1,111 +0,0 @@
-# SSO Providers
-
-Mosaic Stack supports optional enterprise single sign-on through Better Auth's generic OAuth flow. The gateway mounts Better Auth under `/api/auth`, so every provider callback terminates at:
-
-```text
-{BETTER_AUTH_URL}/api/auth/oauth2/callback/{providerId}
-```
-
-For the providers in this document:
-
-- Authentik: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/authentik`
-- WorkOS: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/workos`
-- Keycloak: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/keycloak`
-
-## Required environment variables
-
-### Authentik
-
-```bash
-AUTHENTIK_ISSUER=https://auth.example.com/application/o/mosaic
-AUTHENTIK_CLIENT_ID=...
-AUTHENTIK_CLIENT_SECRET=...
-```
-
-### WorkOS
-
-```bash
-WORKOS_ISSUER=https://your-company.authkit.app
-WORKOS_CLIENT_ID=client_...
-WORKOS_CLIENT_SECRET=...
-NEXT_PUBLIC_WORKOS_ENABLED=true
-```
-
-`WORKOS_ISSUER` should be the WorkOS AuthKit issuer or custom auth domain, not the raw REST API hostname. Mosaic derives the OIDC discovery URL from that issuer.
-
-### Keycloak
-
-```bash
-KEYCLOAK_ISSUER=https://auth.example.com/realms/master
-KEYCLOAK_CLIENT_ID=mosaic
-KEYCLOAK_CLIENT_SECRET=...
-NEXT_PUBLIC_KEYCLOAK_ENABLED=true
-```
-
-If you prefer, you can keep the issuer split as:
-
-```bash
-KEYCLOAK_URL=https://auth.example.com
-KEYCLOAK_REALM=master
-```
-
-The auth package will derive `KEYCLOAK_ISSUER` from those two values.
-
-## WorkOS setup
-
-1. In WorkOS, create or select the application that will back Mosaic login.
-2. Configure an AuthKit domain or custom authentication domain for the application.
-3. Add the redirect URI:
-
-```text
-{BETTER_AUTH_URL}/api/auth/oauth2/callback/workos
-```
-
-4. Copy the application's `client_id` and `client_secret` into `WORKOS_CLIENT_ID` and `WORKOS_CLIENT_SECRET`.
-5. Set `WORKOS_ISSUER` to the AuthKit domain from step 2.
-6. Create the WorkOS organization and attach the enterprise SSO connection you want Mosaic to use.
-7. Set `NEXT_PUBLIC_WORKOS_ENABLED=true` in the web deployment so the login button is rendered.
-
-## Keycloak setup
-
-1. Start from an existing Keycloak realm or create a dedicated realm for Mosaic.
-2. Create a confidential OIDC client named `mosaic` or your preferred client ID.
-3. Set the valid redirect URI to:
-
-```text
-{BETTER_AUTH_URL}/api/auth/oauth2/callback/keycloak
-```
-
-4. Set the web origin to the public Mosaic web URL.
-5. Copy the client secret into `KEYCLOAK_CLIENT_SECRET`.
-6. Set either `KEYCLOAK_ISSUER` directly or `KEYCLOAK_URL` + `KEYCLOAK_REALM`.
-7. Set `NEXT_PUBLIC_KEYCLOAK_ENABLED=true` in the web deployment so the login button is rendered.
-
-### Local Keycloak smoke test
-
-If you want to test locally with Docker:
-
-```bash
-docker run --rm --name mosaic-keycloak \
-  -p 8080:8080 \
-  -e KEYCLOAK_ADMIN=admin \
-  -e KEYCLOAK_ADMIN_PASSWORD=admin \
-  quay.io/keycloak/keycloak:26.1 start-dev
-```
-
-Then configure:
-
-```bash
-KEYCLOAK_ISSUER=http://localhost:8080/realms/master
-KEYCLOAK_CLIENT_ID=mosaic
-KEYCLOAK_CLIENT_SECRET=...
-NEXT_PUBLIC_KEYCLOAK_ENABLED=true
-```
-
-## Web flow
-
-The web login page renders provider buttons from `NEXT_PUBLIC_*_ENABLED` flags. Each button links to `/auth/provider/{providerId}`, and that page initiates Better Auth's `signIn.oauth2` flow before handing off to the provider.
-
-## Failure mode
-
-Provider config is optional, but partial config is rejected at startup. If any provider-specific env var is present without the full required set, `@mosaicstack/auth` throws a bootstrap error with the missing keys instead of silently registering a broken provider.

docs/USER-GUIDE/README.md

@@ -0,0 +1,49 @@
+# User Guide
+
+> **Status:** Partially migrated. The quickstart, web-dashboard reference, and Discord conversation workflow are current.
+
+This book is the canonical home for end-user workflows, user-visible behavior, product concepts, and user troubleshooting. Keep installation, deployment, security controls, and recovery procedures in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); keep implementation detail in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
+
+## Start here
+
+- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
+- [Documentation sitemap](../SITEMAP.md) — resolvable current navigation and authority-gated migration summary.
+- [Quickstart](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session.
+- [Web dashboard](product/web-dashboard.md) — current routes, navigation, chat persistence, projects/tasks views, settings, and admin behavior.
+- [Discord conversations](workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow.
+
+## Chapter map
+
+| Chapter            | Scope                                                         | Status                                               |
+| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `getting-started/` | First-use setup, orientation, and quickstarts.                | Quickstart is current; additional pages are planned. |
+| `concepts/`        | User-facing terminology, product concepts, and mental models. | Scaffold only.                                       |
+| `workflows/`       | Task-oriented procedures for using Mosaic Stack.              | Discord conversation workflow is current.            |
+| `product/`         | Current product surfaces and visible behavior.                | Web dashboard reference is current.                  |
+| `troubleshooting/` | User-visible failures, diagnostics, and fixes.                | Scaffold only.                                       |
+
+### Current pages
+
+- [Quickstart](getting-started/quickstart.md) — the verified installed-CLI first-use path.
+- [Web dashboard](product/web-dashboard.md) — verified current Next.js dashboard behavior and limitations.
+- [Discord conversations](workflows/discord-conversations.md) — verified current Discord user workflow.
+
+Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
+
+## Migration backlog — not current navigation
+
+These are source candidates, not current user guidance:
+
+- `_old_structure/guides/user-guide.md` — quarantined historical source; verify every claim before promotion. See the [documentation catalog](../reports/documentation/2026-08-10-docs-catalog-audit.md) for its disposition.
+- The former root `QUICKSTART.md` was an empty placeholder and has been replaced by the current page above.
+
+Do not link to the quarantine as a current user path. Create a new page only after classifying its audience, status, and evidence in the migration report.
+
+## Authoring boundary
+
+New user-facing documentation belongs under one of the chapter directories above. Use a lowercase kebab-case page name, state whether commands are current or held, and link back to this index plus related canonical sources.
+
+## Related
+
+- [[README|Documentation contract]]
+- [[PRD|Product requirements]]

docs/USER-GUIDE/getting-started/quickstart.md

@@ -0,0 +1,129 @@
+---
+title: Mosaic Stack Quickstart
+type: guide
+audience: user
+status: current
+source_of_truth: false
+---
+
+# Mosaic Stack Quickstart
+
+Verify and install the versioned Mosaic CLI package, complete first-run setup, connect to a gateway, and launch an agent session. This page covers the installed-CLI path with the default local storage tier.
+
+> **Scope:** This is an end-user installation route. It does not authorize PostgreSQL setup, production deployment, or starting Gateway/Web directly from a source checkout. Use the [administrator guide](../../ADMIN-GUIDE/README.md) for deployment and the [developer guide](../../DEVELOPER-GUIDE/README.md) for contributor setup.
+
+## Requirements
+
+- Node.js 20 or newer.
+- npm, for the global Mosaic CLI installation.
+- At least one supported agent runtime:
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  - [Codex](https://github.com/openai/codex)
+  - [OpenCode](https://opencode.ai)
+  - [Pi](https://pi.dev)
+- Credentials for the runtime or model provider you plan to use.
+
+## 1. Install Mosaic
+
+> **Installation hold:** Do not execute the website installer or a script fetched from a mutable repository branch. The current release tooling does not publish an independently verified immutable dependency closure or a signed installer. If your policy requires either property, stop until a release provides it.
+
+The currently published CLI/framework package is `@mosaicstack/[email protected]`. Pin the exact package version and verify its published artifact integrity before installation:
+
+```bash
+registry='https://git.mosaicstack.dev/api/packages/mosaicstack/npm/'
+package='@mosaicstack/mosaic@0.0.49'
+expected_integrity='sha512-/Zsjdf8Ln2QchQTG9lirpqSxhDbNyBjOvGkWrDWRugxCuqUWP5V0rUNVDivmPvro+Vyq3hxDyA9i4hDfkEFmMg=='
+actual_integrity="$(npm view --registry="$registry" "$package" dist.integrity)"
+test "$actual_integrity" = "$expected_integrity"
+npm install --global --registry="$registry" "$package"
+```
+
+The explicit comparison pins the reviewed top-level package artifact; npm also checks the downloaded tarball against registry integrity metadata. It does **not** make the package's transitive dependency graph independently immutable. Review the [package release](https://git.mosaicstack.dev/mosaicstack/-/packages/npm/%40mosaicstack%2Fmosaic/0.0.49) before proceeding, and stop if the integrity comparison fails.
+
+The versioned package includes the Mosaic framework and CLI. npm installs it under your configured global prefix. Ensure that prefix's `bin` directory is on `PATH` if your shell cannot find `mosaic`.
+
+## 2. Complete first-run setup
+
+The versioned package install does not launch the wizard. Run it manually:
+
+```bash
+mosaic wizard
+```
+
+The wizard guides framework setup and gateway installation. It can collect your agent identity, preferences, provider configuration, and gateway administrator details interactively.
+
+For a separately installed or existing gateway, skip local gateway installation and use its URL in the login step below.
+
+## 3. Verify and sign in
+
+For a gateway installed on this machine, check its health and setup state:
+
+```bash
+mosaic gateway status
+mosaic gateway verify
+```
+
+Sign in without putting your password in shell history or process listings:
+
+```bash
+mosaic gateway login
+```
+
+The command prompts for the gateway URL, email, and password as needed. Do not pass passwords with `--password`.
+
+For a remote gateway, provide its URL explicitly:
+
+```bash
+mosaic gateway login --gateway https://gateway.example.com
+```
+
+## 4. Launch Mosaic
+
+Open the interactive terminal interface:
+
+```bash
+mosaic tui
+```
+
+The TUI defaults to `http://localhost:14242` and can prompt for login if no valid session is saved. To connect it to another gateway:
+
+```bash
+mosaic tui --gateway https://gateway.example.com
+```
+
+You can also launch a supported runtime through Mosaic:
+
+```bash
+mosaic pi
+mosaic claude
+mosaic codex
+mosaic opencode
+```
+
+Use the launcher matching the runtime you installed and authenticated.
+
+## 5. Inspect configuration and health
+
+These commands are safe diagnostics and do not change the product requirements or active task ledger:
+
+```bash
+mosaic config show
+mosaic doctor
+mosaic gateway logs
+```
+
+If the gateway is unhealthy, run `mosaic gateway status` and `mosaic gateway logs` before attempting a reinstall. If your session expires, run `mosaic gateway login` again.
+
+## Storage and deployment boundary
+
+The default local gateway tier uses embedded PGlite and does not require an external PostgreSQL or Valkey service. This quickstart intentionally does not configure `DATABASE_URL`, PostgreSQL, pgvector, or a federated deployment.
+
+For standalone or federated storage, deployment topology, secrets, SSO, backups, or recovery, stop here and use the [administrator guide](../../ADMIN-GUIDE/README.md). For work from a repository checkout, keep `DATABASE_URL` unset and follow the [developer guide](../../DEVELOPER-GUIDE/README.md); do not use root `pnpm dev` as a local PGlite route while the current dotenv safety hold remains active.
+
+## Related
+
+- [User Guide](../README.md)
+- [Documentation atlas](../../README.md)
+- [Administrator Guide](../../ADMIN-GUIDE/README.md)
+- [Developer Guide](../../DEVELOPER-GUIDE/README.md)
+- [Repository README](../../../README.md)

docs/USER-GUIDE/product/web-dashboard.md

@@ -0,0 +1,276 @@
+---
+title: Mosaic web dashboard
+type: guide
+audience: user
+status: current
+source_of_truth: false
+---
+
+# Mosaic Web Dashboard
+
+This page documents the current Next.js dashboard: its routes, navigation, visible
+views, and the chat persistence behavior supported by the checked-in web and gateway
+implementation.
+
+> **Current UI boundary:** Projects and tasks can be displayed in the dashboard, but
+> the current dashboard does not provide **New Project** or **New Task** controls.
+> Those entities can be created through authenticated gateway API clients; that API
+> surface is separate from the views described here.
+
+## Access and routes
+
+The dashboard uses the gateway session. Dashboard routes are protected by the web
+`AuthGuard`; the admin route also requires the `admin` role.
+
+| Path                        | Access          | Current behavior                                                                                                                                                                                    |
+| --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/`                         | Any             | Redirects to `/chat`. A signed-out visitor is then redirected to `/login`.                                                                                                                          |
+| `/login`                    | Signed out      | Email/password sign-in, plus buttons for configured SSO providers. Successful sign-in returns to `/chat`.                                                                                           |
+| `/register`                 | Signed out      | Creates an account with name, email, and password, then returns to `/chat`.                                                                                                                         |
+| `/auth/provider/[provider]` | SSO handoff     | Looks up the requested provider and starts an OIDC sign-in when that provider is configured and supports OIDC. Unknown, disabled, or incompatible providers show an error and a link back to login. |
+| `/chat`                     | Signed in       | Conversation list and streamed assistant chat.                                                                                                                                                      |
+| `/projects`                 | Signed in       | Project cards and the Active Mission status section.                                                                                                                                                |
+| `/projects/[id]`            | Signed in       | Project detail view with overview, tasks, missions, and an optional read-only PRD tab.                                                                                                              |
+| `/tasks`                    | Signed in       | Task data in Kanban or list view.                                                                                                                                                                   |
+| `/settings`                 | Signed in       | Profile, appearance, notifications, and provider tabs.                                                                                                                                              |
+| `/admin`                    | Signed-in admin | User Management and System Health tabs. Non-admin users are redirected away from the admin page.                                                                                                    |
+
+Settings and admin tabs are client-side tabs; changing a tab does not change the URL.
+
+## Dashboard navigation
+
+The **Workspace** sidebar contains these links, in order:
+
+1. **Chat** — `/chat`
+2. **Tasks** — `/tasks`
+3. **Projects** — `/projects`
+4. **Settings** — `/settings`
+5. **Admin** — `/admin`
+
+The active link is highlighted, including the parent link when viewing a project
+such as `/projects/<id>`. The Admin link is rendered in the shared sidebar, but the
+page itself is still restricted to administrators.
+
+The top bar provides:
+
+- a sidebar toggle (collapse/expand on desktop; open/close an overlay on mobile),
+- the light/dark theme toggle,
+- the signed-in user's name, and
+- **Sign out**, which returns to `/login`.
+
+The applied global theme is stored in browser local storage under `mosaic-theme`.
+
+## Chat
+
+### Starting and managing conversations
+
+Open `/chat` and either select a conversation or choose **Start new conversation**
+in the empty state. The conversation sidebar also has **New conversation**. Creating
+one calls the gateway and gives the conversation a server-side ID before the first
+message is sent.
+
+The sidebar currently supports:
+
+- searching conversation titles,
+- selecting a conversation,
+- renaming a conversation inline (Enter or leaving the field commits the new title),
+- deleting a conversation after confirmation, and
+- grouping conversations by project when project data is available.
+
+Archived conversations are filtered out of the sidebar. The current dashboard does
+not expose archive/restore controls.
+
+If no conversation is selected when a message is sent, the dashboard creates one
+automatically. A new conversation is titled from the first 60 characters of the
+first message; an empty placeholder conversation is similarly retitled after its
+first message. The active conversation is held in page state, not in the URL: the
+route remains `/chat` rather than changing to `/chat/<id>`. After a refresh, select
+the stored conversation again from the sidebar.
+
+### Sending and streaming
+
+The chat composer provides:
+
+- a model selector populated from available gateway providers and models,
+- a multiline message field,
+- character and approximate token counts, and
+- a **Send** button.
+
+Use **Cmd/Ctrl+Enter** to send. The composer is disabled while a response is
+streaming. The interface displays a **Stop** control during streaming, but the
+current `ChatPage` does not pass a stop handler, so cancellation is not a reliable
+current dashboard action.
+
+Assistant and user messages render Markdown. Assistant messages can show model and
+token metadata when it is present in the returned message, and rendered user/assistant
+messages have a copy control.
+
+### What is persisted
+
+Assistant replies are not page-only or memory-only. The current flow is:
+
+1. The browser creates or selects a conversation and optimistically displays the
+   user's message.
+2. The browser submits the user message to the gateway conversation-message API and
+   sends the turn over the authenticated `/chat` WebSocket namespace.
+3. The gateway streams the assistant response to the page. At `agent_end`, it saves
+   non-empty assistant text to the conversation with model, provider, tool-call, and
+   token-usage metadata when available.
+4. Selecting the conversation later loads `/api/conversations/<id>/messages`, so
+   stored user and assistant messages are shown again. When the gateway has to create
+   or resume the agent session for that conversation, it also loads stored conversation
+   history as context.
+
+The live page appends the completed response as soon as the stream ends; the gateway
+persistence write is asynchronous. Therefore a persistence error can leave a reply
+visible in the current page while it is unavailable after a later reload. The gateway
+redacts sensitive content before emitting and storing assistant text.
+
+## Projects and missions
+
+### Project list: `/projects`
+
+The project page loads the signed-in user's projects and shows either:
+
+- project cards with name, status, description, and creation date, or
+- **No projects yet** with the message that projects appear when created through the
+  gateway API.
+
+The page also shows **Active Mission**. It reports the mission ID, phase, task
+completion count, and status when coordination data is available; otherwise it
+shows **No active mission detected**.
+
+There is no New Project button or project form on this page. The gateway has
+project CRUD endpoints, but this dashboard page currently reads project data only.
+
+### Project detail: `/projects/<id>`
+
+A project detail page shows its name, status, description, created/updated dates,
+and task summary counts for total, done, in progress, and blocked tasks. Its tabs
+are:
+
+- **Overview** — up to five recently updated tasks, a mission summary, and non-empty
+  project metadata.
+- **Tasks (`n`)** — task status filters and clickable task rows.
+- **Missions (`n`)** — a status-ordered mission timeline.
+- **PRD** — present only when project metadata contains non-empty `prd` or
+  `prdContent` text; the content is displayed read-only.
+
+Selecting a task from the project detail Tasks tab opens a detail dialog with its
+status, priority, description, assignee, due date, timestamps, tags, pull-request
+links, and notes when those fields exist. The dialog can be closed with its close
+button, the backdrop, or Escape. The dashboard does not provide project or task
+edit controls in this view.
+
+## Tasks
+
+Open `/tasks` to load the tasks visible to the signed-in user. The default view is
+**Kanban**; a toggle switches to **List**.
+
+- Kanban columns are **Not Started**, **In Progress**, **Blocked**, and **Done**.
+- Kanban cards show title, priority, optional description, status, and due date.
+- List view shows title, status, priority, and due date.
+- The supported task status set also includes `cancelled`; it is not a Kanban
+  column, but a returned cancelled task can appear in List view.
+
+The top-level Tasks page has no New Task button, form, or working task edit dialog.
+Clicking a task in that page does not open the project-detail dialog. The gateway
+supports authenticated task CRUD separately, while this dashboard page currently
+reads and presents task data.
+
+## Settings
+
+Open `/settings`. The page has four tabs and opens on **Profile**.
+
+### Profile
+
+- **Display Name** can be edited.
+- **Email** is displayed but disabled; the page says it cannot be changed there.
+- **Avatar URL** can be edited.
+- **Save changes** sends the profile update through BetterAuth and reports saving,
+  saved, or an error state.
+
+### Appearance
+
+The tab presents **System**, **Light**, and **Dark** theme choices, a **Collapse
+sidebar by default** switch, and a **Default Model** text field. **Save changes**
+saves these as user preferences.
+
+Current implementation limits are worth noting: the shared sidebar provider starts
+expanded and does not read `ui.sidebar_collapsed` on page load; the global applied
+theme is controlled by the top-bar theme toggle; and the chat page initially selects
+the first available provider model rather than reading `ui.default_model` itself.
+Do not treat these preference fields as proof that those defaults are applied across
+all dashboard sessions.
+
+### Notifications
+
+The tab presents and saves three email preferences:
+
+- **Agent task completed** — initially off,
+- **Mentions** — initially on, and
+- **Weekly digest** — initially off.
+
+### Providers
+
+The Providers tab contains SSO discovery and LLM provider discovery/testing areas:
+
+- **SSO Providers** shows configured providers and their protocols, callback path,
+  team-sync claim, SAML fallback, and warnings when supplied by the gateway. It does
+  not configure SSO from the dashboard.
+- **LLM Providers** shows configured providers as Active or Inactive. A provider can
+  be tested for reachability; the result may include latency, an error, and the
+  number of discovered models. Expanding a provider shows model capabilities,
+  context size, cost, and the default-model marker.
+
+When no LLM providers are configured, the page displays setup guidance mentioning
+`OLLAMA_BASE_URL` and `MOSAIC_CUSTOM_PROVIDERS`. Provider credentials and provider
+configuration are not editable in this dashboard tab.
+
+## Admin panel
+
+The `/admin` page is wrapped in an admin-role guard. It opens on **User Management**
+and provides **System Health** as the second tab.
+
+### User Management
+
+The page loads the user list and provides:
+
+- a user count,
+- **+ New User**, with name, email, password, and `member`/`admin` role fields,
+- role promotion/demotion,
+- ban/unban,
+- deletion after confirmation, and
+- a retry action when loading fails.
+
+The table shows name/email, role, active or banned status, creation date, and
+available actions.
+
+### System Health
+
+The health tab loads the gateway's overall `ok` or `degraded` status and provides a
+**Refresh** action. Its cards cover:
+
+- PostgreSQL database status and latency/error,
+- Valkey cache status and latency/error,
+- active agent-session count, and
+- configured LLM providers and model counts.
+
+## Evidence used for this page
+
+The behavior above was checked against the current implementation and focused tests,
+not copied forward as-is from the historical mixed guide. The main evidence files
+are:
+
+- `apps/web/src/app/(dashboard)/` route pages and `apps/web/src/app/page.tsx`,
+- `apps/web/src/components/layout/`, `apps/web/src/components/chat/`,
+  `apps/web/src/components/projects/`, and `apps/web/src/components/tasks/`,
+- `apps/web/e2e/navigation.spec.ts`, `chat.spec.ts`, `projects.spec.ts`,
+  `settings.spec.ts`, and `admin.spec.ts`,
+- `apps/gateway/src/chat/chat.gateway.ts` and
+  `apps/gateway/src/__tests__/conversation-persistence.test.ts`,
+- `apps/gateway/src/chat/chat.gateway-redaction.spec.ts`, and
+- the authenticated gateway controllers under `apps/gateway/src/conversations/`,
+  `projects/`, `tasks/`, and `admin/`.
+
+Related: [User Guide index](../README.md) and [SSO provider runbook](../../ADMIN-GUIDE/security/sso-providers.md).

docs/USER-GUIDE/workflows/discord-conversations.md

@@ -0,0 +1,128 @@
+# Discord conversations
+
+> **Status:** Current Discord workflow for an administrator-provisioned, authorized guild channel.
+>
+> Telegram shared-contract parity, Matrix channel conversations, and a gateway-wide shared adapter registry are not current features. See [Current versus planned](#current-versus-planned) before using any older channel instructions.
+>
+> **Audience:** People conversing with an agent through Discord.
+
+This workflow assumes an administrator has configured the Discord bot, gateway connection, allowlists, and a logical-agent binding. Users cannot create a binding or authorize themselves from Discord.
+
+## Current versus planned
+
+| Surface                 | Status                                    | What you can rely on                                                                                                                         |
+| ----------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Discord guild messages  | **Current live routing**                  | Authorized messages route to the configured logical agent; parent/thread delivery is tested, but ordinary durable history is not guaranteed. |
+| Telegram                | **Not shared-contract parity**            | A raw legacy plugin exists, but its current source has no equivalent documented authorization, pairing, route, or focused package tests.     |
+| Matrix                  | **Not implemented as a channel workflow** | No current gateway channel adapter and test boundary establishes a Matrix conversation workflow.                                             |
+| Shared channel registry | **Not implemented**                       | The gateway's current registry hosts lifecycle wrappers; it does not provide universal channel routing or health.                            |
+
+## Start in a configured parent channel
+
+Send a normal message in the administrator-configured parent text channel. You do **not** need to mention the bot for an ordinary turn.
+
+For an authorized user, Mosaic:
+
+1. checks the guild, parent channel, user allowlist, pairing, role, and rate limit;
+2. keeps the response target in the parent channel; and
+3. routes the turn to the binding's logical agent using a stable conversation address.
+
+No Discord thread is created for this untagged parent-channel case. The response is sent back to that same channel.
+
+Messages from an unconfigured guild/channel, an unallowlisted user, an unpaired user, or a user without a role that can send are ignored without creating a thread or dispatching to the gateway. Bot-authored messages are ignored. Direct messages are not handled by the current guild ingress path.
+
+## Start a threaded topic with a mention
+
+Mention the bot in a parent channel when you want a separate topic:
+
+```text
+@Mosaic investigate the deployment failure
+```
+
+The current Discord adapter creates a public thread for the message, removes the bot mention from the content sent to the agent, and targets the response to that thread. If the message already has a Discord thread attached, the adapter reuses it instead of creating another one.
+
+Authorization happens before thread creation. If the user, guild, parent channel, pairing, role, or rate check fails, no thread is created. If Discord cannot create or fetch the requested thread, the message is not dispatched because Mosaic cannot guarantee the requested response destination.
+
+## Continue inside a thread
+
+Reply in the existing authorized thread without mentioning the bot again. The adapter:
+
+- authorizes the message against the configured parent text channel;
+- keeps the thread as the response target; and
+- never attempts to create a nested thread.
+
+A category above the text channel is not used as the authorization parent. Only the actual configured text-channel parent grants thread inheritance.
+
+The stable conversation address is formed from the configured logical agent, channel name, and response channel/thread, for example:
+
+```text
+<logical-agent-id>:discord:<response-channel-id>
+```
+
+It does not contain Claude, Codex, Pi, OpenCode, a model, a provider, a process, or a native runtime-session ID. The gateway owns runtime selection behind that route, so changing the runtime/provider does not require a new Discord address.
+
+### Durability limitation
+
+Treat the current Discord path as **live routing and delivery**, not guaranteed durable conversation history. The Discord conversation address above is an external route string, while persisted conversation/message rows use UUID conversation IDs. No current external-route-to-UUID mapping was found. The gateway can continue dispatching after a persistence/binding failure, so a reply may appear in Discord without durable history or restart/resume continuity.
+
+Do not rely on Discord as the sole record of a conversation. Durable history requires an implementation that maps the external route to a UUID, surfaces persistence failure, and proves fresh-message persistence and restart recovery in an integration test.
+
+## Attachments
+
+An authorized message may contain text, attachments, or an attachment without text. The current adapter maps attachments into the shared message shape and preserves the native attachment ID, name, URL, content type, and optional size.
+
+The gateway accepts only bounded attachment metadata: at most 10 attachments, HTTPS URLs without credentials, query strings, or fragments, and bounded ID, name, URL, MIME-type, size, and total metadata values. An unsafe or malformed attachment is rejected before the message is acknowledged or dispatched. Binary content is not embedded in the gateway message; the attachment remains a validated external reference.
+
+## Runtime controls
+
+The current Discord text controls are:
+
+```text
+/approve
+/stop <approval>
+```
+
+They remain on the current parent/thread route and do not create a new topic. Approval and stop require an already enrolled durable session; ordinary Discord chat does not prove that enrollment occurred. These are privileged operations: the paired user must have the `admin` role and a provisioned `mosaicUserId`, the gateway must have a tenant configured for the control path, and the enrolled durable session must still belong to the bound logical agent. A stop must present the exact approval reference created for that target; approval consumption is one-time.
+
+If these checks fail, the control operation is denied or produces no successful control result. Do not assume that being able to read a channel grants control authority.
+
+## Response and delivery behavior
+
+The gateway emits raw stream events to the current Discord compatibility path. The plugin buffers `agent:start`/`agent:text` output and sends the completed response on `agent:end`; this is not a claim of token-by-token Discord rendering.
+
+Outbound Discord text is split at a 1,900-character boundary. Transient rate-limit, server, and network failures are retried up to three attempts with one deterministic nonce per correlation/chunk; permanent delivery failures are not retried. A response route is checked against the configured logical-agent/channel binding before Discord is contacted.
+
+## If a message gets no response
+
+Check these possibilities with the administrator:
+
+1. You are in a direct message, an unconfigured guild/channel, or a thread whose parent is not configured.
+2. Your Discord user ID is missing from the user allowlist or `pairedUsers`.
+3. Your pairing is `viewer`, which cannot send ordinary agent turns.
+4. The per-user/channel message or mention-thread limit was reached.
+5. The bot is not connected to Discord or the gateway Socket.IO `/chat` namespace.
+6. A mentioned topic could not create/fetch its thread.
+7. The gateway rejected the signed envelope, route, attachment, or replayed native message ID.
+8. `/approve` or `/stop <approval>` was attempted without the required admin pairing, tenant, pre-enrolled durable session, or exact approval.
+
+These failures are intentionally fail-closed; an unauthorized or unverifiable message should not create a thread or agent side effect.
+
+## Not current: Telegram and Matrix
+
+Do not substitute Telegram or Matrix instructions for this workflow:
+
+- The current Telegram plugin uses raw Telegraf and Socket.IO messages, maps a chat to `telegram-<chatId>`, accepts text only, and does not establish the Discord-style service-token, allowlist, pairing, shared-route, or attachment boundary.
+- No current Matrix gateway channel adapter, channel binding, user authorization flow, or focused channel tests establish a Matrix conversation workflow.
+- The current gateway plugin list is lifecycle-only; it is not proof that every channel shares this Discord behavior.
+
+Those are parity/design gaps, not alternate user workflows.
+
+## Evidence and related pages
+
+- [Channel protocol architecture](../../DEVELOPER-GUIDE/architecture/channel-protocol.md) — current shared types, Discord compatibility path, and explicit parity boundary.
+- [Discord ingress security](../../ADMIN-GUIDE/security/discord-ingress.md) — administrator configuration, authentication, authorization, and failure controls.
+- [`plugins/discord/src/index.ts`](../../../plugins/discord/src/index.ts) — native Discord routing and delivery implementation.
+- [`plugins/discord/src/index.test.ts`](../../../plugins/discord/src/index.test.ts) — parent, mention, existing-thread, authorization, attachment, rate, egress, and health tests.
+- [`apps/gateway/src/plugin/discord-ingress.security.spec.ts`](../../../apps/gateway/src/plugin/discord-ingress.security.spec.ts) — gateway signature, replay, binding, attachment, approval, and stop tests.
+- [`apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts`](../../../apps/gateway/src/__tests__/integration/tess-cross-surface.integration.test.ts) — Discord control-flow test with explicit durable-session pre-enrollment; it is not fresh-message persistence evidence.
+- [User Guide](../README.md)