feat(fleet): add roster v2 structural compiler

.prettierignore

@@ -5,3 +5,5 @@ pnpm-lock.yaml
 **/drizzle
 **/.next
 .claude/
+docs/tess/TASKS.md
+docs/scratchpads/

.woodpecker/ci.yml

@@ -7,7 +7,14 @@ variables:
   - &enable_pnpm 'corepack enable'
 
 when:
-  - event: [push, pull_request, manual]
+  # PR + manual CI run on any branch — the pull_request pipeline is the merge gate.
+  # push CI is restricted to protected branches (main) so a feature-branch push no
+  # longer fires a redundant SECOND pipeline alongside its PR pipeline. This ~halves
+  # CI load on the storage-constrained runner with zero loss of gating (branch
+  # protection requires no push/ci status context; main still gets full push CI).
+  - event: [pull_request, manual]
+  - event: push
+    branch: main
 
 # Turbo remote cache (turbo.mosaicstack.dev) is configured via Woodpecker
 # repository-level environment variables (TURBO_API, TURBO_TEAM, TURBO_TOKEN).

.woodpecker/publish.yml

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

README.md

@@ -30,16 +30,6 @@ This installs both components:
 | **Framework**           | Bash launcher, guides, runtime configs, tools, skills            | `~/.config/mosaic/`  |
 | **@mosaicstack/mosaic** | Unified `mosaic` CLI — TUI, gateway client, wizard, auto-updater | `~/.npm-global/bin/` |
 
-### Install lanes
-
-| Lane                     | Command                               | Use when                                              | Source                                                                  |
-| ------------------------ | ------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------- |
-| Stable                   | `bash tools/install.sh`               | You want the released Mosaic CLI/framework            | npm registry `@mosaicstack/mosaic@latest` + framework archive at `main` |
-| Prerelease integration   | `bash tools/install.sh --next`        | You want the current `next` integration branch        | Build-from-source at `next`                                             |
-| Contributor/source build | `bash tools/install.sh --dev --ref X` | You are testing a branch before release; `--ref` wins | Build-from-source at the requested ref                                  |
-
-`--next` is shorthand for the prerelease integration lane: it enables source-build mode and uses `next` unless an explicit `--ref` or `MOSAIC_REF` is provided.
-
 After install, the wizard runs automatically or you can invoke it manually:
 
 ```bash
@@ -346,9 +336,7 @@ The CLI also performs a background update check on every invocation (cached for
 bash tools/install.sh --check           # Version check only
 bash tools/install.sh --framework       # Framework only (skip npm CLI)
 bash tools/install.sh --cli             # npm CLI only (skip framework)
-bash tools/install.sh --next            # Prerelease lane: source build from next
-bash tools/install.sh --dev             # Contributor lane: source build at --ref/main
-bash tools/install.sh --ref v1.0        # Install from a specific git ref (--ref wins over --next)
+bash tools/install.sh --ref v1.0        # Install from a specific git ref
 bash tools/install.sh --yes             # Non-interactive, accept all defaults
 bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```

apps/gateway/package.json

@@ -31,6 +31,7 @@
     "@mariozechner/pi-ai": "^0.65.0",
     "@mariozechner/pi-coding-agent": "^0.65.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@mosaicstack/agent": "workspace:^",
     "@mosaicstack/auth": "workspace:^",
     "@mosaicstack/brain": "workspace:^",
     "@mosaicstack/config": "workspace:^",

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

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

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

@@ -0,0 +1,192 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { InMemoryDurableSessionStore } from '@mosaicstack/agent';
+import {
+  createDiscordIngressEnvelope,
+  DiscordPlugin,
+  type DiscordIngressPayload,
+} from '@mosaicstack/discord-plugin';
+import { InteractionController } from '../../agent/interaction.controller.js';
+import { RuntimeProviderService } from '../../agent/runtime-provider-registry.service.js';
+import { DurableSessionService } from '../../agent/durable-session.service.js';
+import { ChatGateway } from '../../chat/chat.gateway.js';
+import { CommandAuthorizationService } from '../../commands/command-authorization.service.js';
+
+const SERVICE_TOKEN = 'test-discord-service-token';
+const envKeys = [
+  'DISCORD_SERVICE_TOKEN',
+  'DISCORD_SERVICE_TENANT_ID',
+  'DISCORD_INTERACTION_BINDINGS',
+  'DISCORD_ALLOWED_GUILD_IDS',
+  'DISCORD_ALLOWED_CHANNEL_IDS',
+  'DISCORD_ALLOWED_USER_IDS',
+  'MOSAIC_AGENT_NAME',
+] as const;
+const priorEnv = new Map<string, string | undefined>();
+
+function payload(content: string, messageId: string, correlationId: string): DiscordIngressPayload {
+  return {
+    content,
+    messageId,
+    correlationId,
+    guildId: 'guild-1',
+    channelId: 'channel-1',
+    userId: 'discord-admin-1',
+    conversationId: 'Nova:discord:channel-1',
+  };
+}
+
+function authorization(): CommandAuthorizationService {
+  const entries = new Map<string, string>();
+  return new CommandAuthorizationService(
+    {
+      select: () => ({
+        from: () => ({ where: () => ({ limit: async () => [{ role: 'admin' }] }) }),
+      }),
+    } as never,
+    {
+      get: async (key: string) => entries.get(key) ?? null,
+      set: async (key: string, value: string) => entries.set(key, value),
+      del: async (key: string) => Number(entries.delete(key)),
+    },
+  );
+}
+
+describe('interaction Discord/CLI durable-session integration', () => {
+  afterEach(() => {
+    for (const key of envKeys) {
+      const value = priorEnv.get(key);
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+    priorEnv.clear();
+  });
+
+  it('enrolls through the CLI surface then resolves the same durable session from Discord', async () => {
+    for (const key of envKeys) priorEnv.set(key, process.env[key]);
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    process.env['DISCORD_SERVICE_TOKEN'] = SERVICE_TOKEN;
+    process.env['DISCORD_SERVICE_TENANT_ID'] = 'tenant-1';
+    process.env['DISCORD_ALLOWED_GUILD_IDS'] = 'guild-1';
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-1';
+    process.env['DISCORD_ALLOWED_USER_IDS'] = 'discord-admin-1';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        guildId: 'guild-1',
+        channelId: 'channel-1',
+        pairedUsers: {
+          'discord-admin-1': { role: 'admin', mosaicUserId: 'mosaic-admin-1' },
+        },
+      },
+    ]);
+
+    const durable = new DurableSessionService(
+      new InMemoryDurableSessionStore() as never,
+      {} as never,
+    );
+    const enrollmentRuntime = {
+      listSessions: vi.fn().mockResolvedValue([{ id: 'runtime-1' }]),
+    };
+    const controller = new InteractionController(enrollmentRuntime as never, durable);
+    await controller.enroll(
+      'Nova',
+      'Nova:discord:channel-1',
+      { providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+      { id: 'mosaic-admin-1', tenantId: 'tenant-1' },
+      'cli-enrollment-correlation',
+    );
+
+    const authz = authorization();
+    const terminated = vi.fn().mockResolvedValue(undefined);
+    const runtime = new RuntimeProviderService(
+      {
+        require: () => ({
+          capabilities: async () => ({ supported: ['session.terminate'] }),
+          terminate: terminated,
+        }),
+      } as never,
+      { record: async () => undefined } as never,
+      {
+        consume: (approvalId, action) =>
+          authz.consumeRuntimeTerminationApproval(approvalId, action),
+      },
+    );
+    const gateway = new ChatGateway(
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      authz,
+      runtime,
+      durable,
+    );
+    const client = { data: { discordService: true }, emit: vi.fn() };
+    const plugin = new DiscordPlugin({
+      token: 'unused',
+      gatewayUrl: 'http://unused',
+      serviceToken: SERVICE_TOKEN,
+      allowedGuildIds: ['guild-1'],
+      allowedChannelIds: ['channel-1'],
+      allowedUserIds: ['discord-admin-1'],
+      interactionBindings: [
+        {
+          instanceId: 'Nova',
+          guildId: 'guild-1',
+          channelId: 'channel-1',
+          pairedUsers: {
+            'discord-admin-1': { role: 'admin', mosaicUserId: 'mosaic-admin-1' },
+          },
+        },
+      ],
+    });
+    const pluginInternals = plugin as unknown as {
+      client: { user: { id: string } };
+      socket: { connected: boolean; emit: ReturnType<typeof vi.fn> };
+      handleDiscordMessage(message: unknown): void;
+    };
+    const pluginSocket = { connected: true, emit: vi.fn() };
+    pluginInternals.client = { user: { id: 'bot-1' } };
+    pluginInternals.socket = pluginSocket;
+    pluginInternals.handleDiscordMessage({
+      id: 'approve-1',
+      guildId: 'guild-1',
+      channelId: 'channel-1',
+      author: { id: 'discord-admin-1', bot: false },
+      mentions: { has: () => true },
+      content: '<@bot-1> /approve',
+      channel: { parentId: null },
+      attachments: new Map(),
+    });
+
+    expect(pluginSocket.emit).toHaveBeenCalledWith('discord:approve', expect.any(Object));
+    const approvalEnvelope = pluginSocket.emit.mock.calls[0]?.[1];
+    await gateway.handleDiscordApproval(client as never, approvalEnvelope);
+    const approval = client.emit.mock.calls.find(
+      ([event]) => event === 'discord:approval',
+    )?.[1] as {
+      approvalId: string;
+      success: boolean;
+    };
+    expect(approval.success).toBe(true);
+
+    await gateway.handleDiscordStop(
+      client as never,
+      createDiscordIngressEnvelope(
+        payload(`/stop ${approval.approvalId}`, 'stop-1', 'discord-stop-correlation'),
+        SERVICE_TOKEN,
+      ),
+    );
+
+    expect(terminated).toHaveBeenCalledWith(
+      'runtime-1',
+      approval.approvalId,
+      expect.objectContaining({ actorId: 'mosaic-admin-1' }),
+    );
+    expect(client.emit).toHaveBeenCalledWith('discord:stop', {
+      correlationId: 'discord-stop-correlation',
+      success: true,
+    });
+  });
+});

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

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

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

@@ -0,0 +1,179 @@
+import { ForbiddenException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+import { AgentService, type AgentSession } from '../agent.service.js';
+import type { ActorTenantScope } from '../../auth/session-scope.js';
+
+const CONVERSATION_ID = '22222222-2222-4222-8222-222222222222';
+const OWNER_SCOPE: ActorTenantScope = { userId: 'owner-user', tenantId: 'owner-tenant' };
+const FOREIGN_SCOPE: ActorTenantScope = { userId: 'foreign-user', tenantId: 'foreign-tenant' };
+
+type AgentServiceInternals = {
+  sessions: Map<string, AgentSession>;
+  creating: Map<string, Promise<AgentSession>>;
+};
+
+function makeService(operatorMemory: unknown = null): AgentService {
+  return new AgentService(
+    {
+      getDefaultModel: vi.fn(() => null),
+      getRegistry: vi.fn(() => ({})),
+      findModel: vi.fn(),
+      listAvailableModels: vi.fn(() => []),
+    } as never,
+    {} as never,
+    {} as never,
+    { available: false } as never,
+    {} as never,
+    { getToolDefinitions: vi.fn(() => []) } as never,
+    { loadForSession: vi.fn(async () => ({ metaTools: [], promptAdditions: [] })) } as never,
+    null,
+    null,
+    { collect: vi.fn().mockResolvedValue(undefined) } as never,
+    operatorMemory as never,
+  );
+}
+
+function internals(service: AgentService): AgentServiceInternals {
+  return service as unknown as AgentServiceInternals;
+}
+
+function makeSession(scope: ActorTenantScope = OWNER_SCOPE): AgentSession {
+  return {
+    id: CONVERSATION_ID,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    piSession: {
+      thinkingLevel: 'off',
+      getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
+      setThinkingLevel: vi.fn(),
+      abort: vi.fn().mockResolvedValue(undefined),
+      prompt: vi.fn().mockResolvedValue(undefined),
+      dispose: vi.fn(),
+      getSessionStats: vi.fn(),
+      getContextUsage: vi.fn(),
+    } as unknown as AgentSession['piSession'],
+    listeners: new Set(),
+    unsubscribe: vi.fn(),
+    createdAt: Date.now(),
+    promptCount: 0,
+    channels: new Set(),
+    skillPromptAdditions: [],
+    sandboxDir: '/tmp/tess-session-ownership-test',
+    allowedTools: null,
+    userId: scope.userId,
+    tenantId: scope.tenantId,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    },
+  };
+}
+
+describe('AgentService owner/tenant scope enforcement', () => {
+  it('allows owner-scoped operations and rejects foreign scopes for seeded sessions', async () => {
+    const service = makeService();
+    const session = makeSession();
+    internals(service).sessions.set(CONVERSATION_ID, session);
+
+    expect(service.getSession(CONVERSATION_ID, OWNER_SCOPE)).toBe(session);
+    expect(service.getSession(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
+    expect(service.getSessionInfo(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
+    expect(service.listSessions(OWNER_SCOPE)).toHaveLength(1);
+    expect(service.listSessions(FOREIGN_SCOPE)).toEqual([]);
+
+    service.addChannel(CONVERSATION_ID, 'websocket:owner', OWNER_SCOPE);
+    expect(session.channels.has('websocket:owner')).toBe(true);
+    expect(() => service.addChannel(CONVERSATION_ID, 'websocket:foreign', FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+    expect(() => service.removeChannel(CONVERSATION_ID, 'websocket:owner', FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+
+    expect(() =>
+      service.updateSessionModel(CONVERSATION_ID, 'foreign-model', FOREIGN_SCOPE),
+    ).toThrow(ForbiddenException);
+    service.updateSessionModel(CONVERSATION_ID, 'owner-model', OWNER_SCOPE);
+    expect(session.modelId).toBe('owner-model');
+
+    expect(() =>
+      service.applyAgentConfig(CONVERSATION_ID, 'agent-foreign', 'Foreign Agent', FOREIGN_SCOPE),
+    ).toThrow(ForbiddenException);
+    service.applyAgentConfig(CONVERSATION_ID, 'agent-owner', 'Owner Agent', OWNER_SCOPE);
+    expect(session.agentConfigId).toBe('agent-owner');
+
+    expect(() => service.onEvent(CONVERSATION_ID, vi.fn(), FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+    const cleanup = service.onEvent(CONVERSATION_ID, vi.fn(), OWNER_SCOPE);
+    cleanup();
+
+    await expect(
+      service.prompt(CONVERSATION_ID, 'foreign prompt', FOREIGN_SCOPE),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await service.prompt(CONVERSATION_ID, 'owner prompt', OWNER_SCOPE);
+    expect(session.piSession.prompt).toHaveBeenCalledWith('owner prompt');
+
+    await expect(service.destroySession(CONVERSATION_ID, FOREIGN_SCOPE)).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+    expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(true);
+
+    await service.destroySession(CONVERSATION_ID, OWNER_SCOPE);
+    expect(session.piSession.dispose).toHaveBeenCalled();
+    expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(false);
+  });
+
+  it('derives the operator-memory scope on the createSession production path', async () => {
+    const plugin = { capture: vi.fn(), search: vi.fn() };
+    const service = makeService(plugin);
+    const buildTools = vi.spyOn(service as never, 'buildToolsForSandbox').mockReturnValue([]);
+
+    // Session construction reaches the real scope derivation before the intentionally incomplete
+    // Pi test double rejects later in createAgentSession.
+    await service.createSession(CONVERSATION_ID, OWNER_SCOPE).catch(() => undefined);
+
+    expect(buildTools).toHaveBeenCalledWith(expect.any(String), OWNER_SCOPE.userId, {
+      tenantId: OWNER_SCOPE.tenantId,
+      ownerId: OWNER_SCOPE.userId,
+      sessionId: CONVERSATION_ID,
+    });
+  });
+
+  it('denies a foreign actor before it can obtain another session operator-memory scope', async () => {
+    const plugin = { capture: vi.fn(), search: vi.fn() };
+    const service = makeService(plugin);
+    internals(service).sessions.set(CONVERSATION_ID, makeSession());
+    const buildTools = vi.spyOn(service as never, 'buildToolsForSandbox');
+
+    await expect(service.createSession(CONVERSATION_ID, FOREIGN_SCOPE)).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+
+    expect(buildTools).not.toHaveBeenCalled();
+    expect(plugin.capture).not.toHaveBeenCalled();
+    expect(plugin.search).not.toHaveBeenCalled();
+  });
+
+  it('checks owner/tenant scope before returning an in-flight session creation', async () => {
+    const service = makeService();
+    const session = makeSession();
+    internals(service).creating.set(CONVERSATION_ID, Promise.resolve(session));
+
+    await expect(
+      service.createSession(CONVERSATION_ID, {
+        userId: FOREIGN_SCOPE.userId,
+        tenantId: FOREIGN_SCOPE.tenantId,
+      }),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+
+    await expect(
+      service.createSession(CONVERSATION_ID, {
+        userId: OWNER_SCOPE.userId,
+        tenantId: OWNER_SCOPE.tenantId,
+      }),
+    ).resolves.toBe(session);
+  });
+});

apps/gateway/src/agent/__tests__/runtime-provider-registry.service.test.ts

@@ -0,0 +1,370 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  AgentRuntimeProvider,
+  RuntimeAttachHandle,
+  RuntimeAttachMode,
+  RuntimeCapability,
+  RuntimeCapabilitySet,
+  RuntimeHealth,
+  RuntimeMessage,
+  RuntimeScope,
+  RuntimeSession,
+  RuntimeSessionTree,
+  RuntimeStreamEvent,
+} from '@mosaicstack/types';
+import { AgentRuntimeProviderRegistry } from '@mosaicstack/agent';
+import type { ActorTenantScope } from '../../auth/session-scope.js';
+import {
+  RuntimeProviderAuditService,
+  RuntimeProviderService,
+  type RuntimeAuditEvent,
+  type RuntimeAuditSink,
+  type RuntimeApprovalVerifier,
+} from '../runtime-provider-registry.service.js';
+
+process.env['MOSAIC_AGENT_NAME'] ??= 'test-runtime-agent';
+
+const OWNER_SCOPE: ActorTenantScope = { userId: 'owner-1', tenantId: 'tenant-1' };
+const CONTEXT = {
+  actorScope: OWNER_SCOPE,
+  channelId: 'cli',
+  correlationId: 'correlation-1',
+};
+
+class RecordingRuntimeProvider implements AgentRuntimeProvider {
+  readonly id = 'fleet';
+  readonly receivedScopes: RuntimeScope[] = [];
+  readonly sentMessages: RuntimeMessage[] = [];
+  terminateCalls = 0;
+  throwAfterSend = false;
+  throwAuthorization = false;
+
+  constructor(private readonly supported: RuntimeCapability[]) {}
+
+  async capabilities(scope: RuntimeScope): Promise<RuntimeCapabilitySet> {
+    this.receivedScopes.push(scope);
+    return { supported: this.supported };
+  }
+
+  async health(scope: RuntimeScope): Promise<RuntimeHealth> {
+    this.receivedScopes.push(scope);
+    return { status: 'healthy', checkedAt: '2026-07-12T00:00:00.000Z' };
+  }
+
+  async listSessions(scope: RuntimeScope): Promise<RuntimeSession[]> {
+    this.receivedScopes.push(scope);
+    return [];
+  }
+
+  async getSessionTree(scope: RuntimeScope): Promise<RuntimeSessionTree[]> {
+    this.receivedScopes.push(scope);
+    return [];
+  }
+
+  async *streamSession(
+    _sessionId: string,
+    _cursor: string | undefined,
+    scope: RuntimeScope,
+  ): AsyncIterable<RuntimeStreamEvent> {
+    this.receivedScopes.push(scope);
+    return;
+  }
+
+  async sendMessage(
+    _sessionId: string,
+    message: RuntimeMessage,
+    scope: RuntimeScope,
+  ): Promise<void> {
+    this.receivedScopes.push(scope);
+    this.sentMessages.push(message);
+    if (this.throwAuthorization) {
+      throw Object.assign(new Error('provider authorization denied'), { code: 'forbidden' });
+    }
+    if (this.throwAfterSend) {
+      throw new Error('provider acknowledgement failed');
+    }
+  }
+
+  async attach(
+    sessionId: string,
+    mode: RuntimeAttachMode,
+    scope: RuntimeScope,
+  ): Promise<RuntimeAttachHandle> {
+    this.receivedScopes.push(scope);
+    return {
+      attachmentId: 'attachment-1',
+      sessionId,
+      mode,
+      expiresAt: '2026-07-12T00:00:00.000Z',
+    };
+  }
+
+  async detach(_attachmentId: string, scope: RuntimeScope): Promise<void> {
+    this.receivedScopes.push(scope);
+  }
+
+  async terminate(_sessionId: string, _approvalRef: string, scope: RuntimeScope): Promise<void> {
+    this.receivedScopes.push(scope);
+    this.terminateCalls += 1;
+  }
+}
+
+class RecordingAuditSink implements RuntimeAuditSink {
+  readonly events: RuntimeAuditEvent[] = [];
+
+  async record(event: RuntimeAuditEvent): Promise<void> {
+    this.events.push(event);
+  }
+}
+
+class DenyingApprovalVerifier implements RuntimeApprovalVerifier {
+  async consume(): Promise<boolean> {
+    return false;
+  }
+}
+
+class AcceptingApprovalVerifier implements RuntimeApprovalVerifier {
+  consumedAction: Parameters<RuntimeApprovalVerifier['consume']>[1] | undefined;
+
+  async consume(
+    _approvalRef: string,
+    action: Parameters<RuntimeApprovalVerifier['consume']>[1],
+  ): Promise<boolean> {
+    this.consumedAction = action;
+    return true;
+  }
+}
+
+function makeService(
+  provider: RecordingRuntimeProvider,
+  audit: RuntimeAuditSink = new RecordingAuditSink(),
+  approval: RuntimeApprovalVerifier = new DenyingApprovalVerifier(),
+): RuntimeProviderService {
+  const registry = new AgentRuntimeProviderRegistry();
+  registry.register(provider);
+  return new RuntimeProviderService(registry, audit, approval);
+}
+
+describe('RuntimeProviderService security boundary', (): void => {
+  it('derives and freezes only the authenticated actor scope while preserving correlation metadata', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.send']);
+    const audit = new RecordingAuditSink();
+    const service = makeService(provider, audit);
+
+    await service.sendMessage(
+      'fleet',
+      'session-1',
+      { content: 'hello', idempotencyKey: 'key-1' },
+      CONTEXT,
+    );
+
+    const providerScope = provider.receivedScopes[0];
+    expect(providerScope).toEqual({
+      actorId: OWNER_SCOPE.userId,
+      tenantId: OWNER_SCOPE.tenantId,
+      channelId: CONTEXT.channelId,
+      correlationId: CONTEXT.correlationId,
+    });
+    expect(Object.isFrozen(providerScope)).toBe(true);
+    expect(audit.events).toContainEqual(
+      expect.objectContaining({
+        providerId: 'fleet',
+        operation: 'session.send',
+        outcome: 'succeeded',
+        actorId: OWNER_SCOPE.userId,
+        tenantId: OWNER_SCOPE.tenantId,
+        channelId: CONTEXT.channelId,
+        correlationId: CONTEXT.correlationId,
+        resourceId: 'session-1',
+        durationMs: expect.any(Number),
+      }),
+    );
+    expect(JSON.stringify(audit.events)).not.toContain('hello');
+    expect(JSON.stringify(audit.events)).not.toContain('key-1');
+  });
+
+  it('does not block a provider operation when an unsafe resource ID is redacted in durable audit', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.send']);
+    let persisted: unknown;
+    const durableAudit = new RuntimeProviderAuditService({
+      logs: {
+        ingest: async (entry: unknown): Promise<unknown> => {
+          persisted = entry;
+          return entry;
+        },
+      },
+    } as never);
+    const service = makeService(provider, durableAudit);
+
+    await service.sendMessage(
+      'fleet',
+      'session/credential-canary=secret-value',
+      { content: 'safe message', idempotencyKey: 'key-1' },
+      CONTEXT,
+    );
+
+    expect(provider.sentMessages).toHaveLength(1);
+    expect(JSON.stringify(persisted)).not.toContain('secret-value');
+  });
+
+  it('fails closed before a provider side effect when a capability is missing', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider([]);
+    const service = makeService(provider);
+
+    await expect(
+      service.sendMessage(
+        'fleet',
+        'session-1',
+        { content: 'hello', idempotencyKey: 'key-1' },
+        CONTEXT,
+      ),
+    ).rejects.toThrow(/capability denied/);
+    expect(provider.sentMessages).toEqual([]);
+  });
+
+  it('requires a consumed exact-action approval before termination', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.terminate']);
+    const approval = new DenyingApprovalVerifier();
+    const audit = new RecordingAuditSink();
+    const service = makeService(provider, audit, approval);
+
+    await expect(
+      service.terminate('fleet', 'session-1', 'forged-approval', CONTEXT),
+    ).rejects.toThrow(/approval denied/);
+    expect(provider.terminateCalls).toBe(0);
+    expect(audit.events.at(-1)).toMatchObject({ outcome: 'denied', errorCode: 'policy_denied' });
+  });
+
+  it('binds an accepted termination approval to provider, session, immutable scope, and correlation', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.terminate']);
+    const approval = new AcceptingApprovalVerifier();
+    const service = makeService(provider, new RecordingAuditSink(), approval);
+
+    await service.terminate('fleet', 'session-1', 'approval-1', CONTEXT);
+
+    expect(approval.consumedAction).toEqual({
+      providerId: 'fleet',
+      sessionId: 'session-1',
+      actorId: OWNER_SCOPE.userId,
+      tenantId: OWNER_SCOPE.tenantId,
+      channelId: CONTEXT.channelId,
+      correlationId: CONTEXT.correlationId,
+      agentName: process.env['MOSAIC_AGENT_NAME'],
+    });
+    expect(provider.terminateCalls).toBe(1);
+  });
+
+  it('fails closed before invoking a provider when audit persistence rejects the request', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.send']);
+    const unavailableAudit: RuntimeAuditSink = {
+      async record(): Promise<void> {
+        throw new Error('audit unavailable');
+      },
+    };
+    const service = makeService(provider, unavailableAudit);
+
+    await expect(
+      service.sendMessage(
+        'fleet',
+        'session-1',
+        { content: 'hello', idempotencyKey: 'key-1' },
+        CONTEXT,
+      ),
+    ).rejects.toThrow(/audit unavailable/);
+    expect(provider.sentMessages).toEqual([]);
+  });
+
+  it('records a provider error after invocation as failed rather than denied', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.send']);
+    provider.throwAfterSend = true;
+    const audit = new RecordingAuditSink();
+    const service = makeService(provider, audit);
+
+    await expect(
+      service.sendMessage(
+        'fleet',
+        'session-1',
+        { content: 'hello', idempotencyKey: 'key-1' },
+        CONTEXT,
+      ),
+    ).rejects.toThrow(/provider acknowledgement failed/);
+    expect(provider.sentMessages).toHaveLength(1);
+    expect(audit.events.map((event: RuntimeAuditEvent): string => event.outcome)).toEqual([
+      'requested',
+      'failed',
+    ]);
+    expect(audit.events.at(-1)).toMatchObject({
+      errorCode: 'provider_error',
+      durationMs: expect.any(Number),
+    });
+  });
+
+  it('records a provider authorization rejection as denied rather than provider failure', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.send']);
+    provider.throwAuthorization = true;
+    const audit = new RecordingAuditSink();
+    const service = makeService(provider, audit);
+
+    await expect(
+      service.sendMessage(
+        'fleet',
+        'session-1',
+        { content: 'hello', idempotencyKey: 'key-1' },
+        CONTEXT,
+      ),
+    ).rejects.toThrow(/provider authorization denied/);
+    expect(audit.events.at(-1)).toMatchObject({ outcome: 'denied', errorCode: 'policy_denied' });
+  });
+
+  it('persists only metadata-only runtime audit fields', async (): Promise<void> => {
+    let persisted: unknown;
+    const ingest = async (entry: unknown): Promise<unknown> => {
+      persisted = entry;
+      return entry;
+    };
+    const service = new RuntimeProviderAuditService({ logs: { ingest } } as never);
+
+    await service.record({
+      providerId: 'fleet',
+      operation: 'session.send',
+      outcome: 'succeeded',
+      actorId: 'owner-1',
+      tenantId: 'tenant-1',
+      channelId: 'cli',
+      correlationId: 'correlation-1',
+      resourceId: 'session-1',
+      durationMs: 12,
+    });
+
+    expect(persisted).toMatchObject({
+      content: 'runtime.provider.audit',
+      metadata: expect.objectContaining({ correlationId: 'correlation-1', durationMs: 12 }),
+    });
+    expect(JSON.stringify(persisted)).not.toContain('approval');
+  });
+
+  it('does not misreport a completed provider side effect when completion auditing fails', async (): Promise<void> => {
+    const provider = new RecordingRuntimeProvider(['session.send']);
+    let auditCalls = 0;
+    const audit: RuntimeAuditSink = {
+      async record(): Promise<void> {
+        auditCalls += 1;
+        if (auditCalls === 2) {
+          throw new Error('completion audit unavailable');
+        }
+      },
+    };
+    const service = makeService(provider, audit);
+
+    await expect(
+      service.sendMessage(
+        'fleet',
+        'session-1',
+        { content: 'hello', idempotencyKey: 'key-1' },
+        CONTEXT,
+      ),
+    ).resolves.toBeUndefined();
+    expect(provider.sentMessages).toHaveLength(1);
+    expect(auditCalls).toBe(2);
+  });
+});

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

@@ -0,0 +1,262 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../agent.service.js', () => ({ AgentService: class AgentService {} }));
+vi.mock('../../commands/command-executor.service.js', () => ({
+  CommandExecutorService: class CommandExecutorService {},
+}));
+vi.mock('../routing/routing-engine.service.js', () => ({
+  RoutingEngineService: class RoutingEngineService {},
+}));
+
+import { SessionsController } from '../sessions.controller.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';
+
+const USER_A = { id: 'user-a', tenantId: 'tenant-a' };
+const USER_B = { id: 'user-b', tenantId: 'tenant-b' };
+const CONVERSATION_ID = '11111111-1111-4111-8111-111111111111';
+
+function makeSessionInfo(overrides?: Partial<SessionInfoDto>): SessionInfoDto {
+  return {
+    id: CONVERSATION_ID,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    createdAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    promptCount: 0,
+    channels: [],
+    durationMs: 0,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    },
+    ...overrides,
+  };
+}
+
+function makeAgentSession(owner = USER_A): AgentSession {
+  return {
+    id: CONVERSATION_ID,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    piSession: {
+      thinkingLevel: 'off',
+      getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
+      setThinkingLevel: vi.fn(),
+      abort: vi.fn().mockResolvedValue(undefined),
+      prompt: vi.fn().mockResolvedValue(undefined),
+      dispose: vi.fn(),
+      getSessionStats: vi.fn(),
+      getContextUsage: vi.fn(),
+    } as unknown as AgentSession['piSession'],
+    listeners: new Set(),
+    unsubscribe: vi.fn(),
+    createdAt: Date.now(),
+    promptCount: 0,
+    channels: new Set(),
+    skillPromptAdditions: [],
+    sandboxDir: '/tmp',
+    allowedTools: null,
+    userId: owner.id,
+    tenantId: owner.tenantId,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    },
+  };
+}
+
+function makeScopedAgentService() {
+  const foreign = makeAgentSession(USER_A);
+  return {
+    listSessions: vi.fn((scope?: { userId: string; tenantId?: string }) =>
+      scope?.userId === USER_B.id ? [] : [makeSessionInfo({ id: foreign.id })],
+    ),
+    getSessionInfo: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
+      scope?.userId === USER_B.id ? undefined : makeSessionInfo({ id: foreign.id }),
+    ),
+    destroySession: vi.fn(),
+    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')),
+    onEvent: vi.fn(() => vi.fn()),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    recordMessage: vi.fn(),
+    prompt: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+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');
+
+    expect(source).toContain('getSession(sessionId: string, scope: ActorTenantScope)');
+    expect(source).toContain('listSessions(scope: ActorTenantScope)');
+    expect(source).toContain('getSessionInfo(sessionId: string, scope: ActorTenantScope)');
+    expect(source).toContain(
+      'addChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
+    );
+    expect(source).toContain(
+      'removeChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
+    );
+    expect(source).toContain(
+      'async prompt(sessionId: string, message: string, scope: ActorTenantScope)',
+    );
+    expect(source).toContain('scope: ActorTenantScope,');
+    expect(source).toContain('async destroySession(sessionId: string, scope: ActorTenantScope)');
+    expect(source).not.toContain('scope?: ActorTenantScope');
+  });
+});
+
+describe('TESS-M1-SEC-002 REST session ownership and tenant binding', () => {
+  it('lists only sessions owned by the authenticated owner+tenant scope', () => {
+    const agentService = makeScopedAgentService();
+    const controller = new SessionsController(agentService as never);
+
+    expect(controller.list(USER_B)).toEqual({ sessions: [], total: 0 });
+    expect(agentService.listSessions).toHaveBeenCalledWith({
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+  });
+
+  it('does not reveal another owner/tenant session by guessed id', () => {
+    const agentService = makeScopedAgentService();
+    const controller = new SessionsController(agentService as never);
+
+    expect(() => controller.findOne(CONVERSATION_ID, USER_B)).toThrow(NotFoundException);
+    expect(agentService.getSessionInfo).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+  });
+
+  it('does not terminate another owner/tenant session by guessed id', async () => {
+    const agentService = makeScopedAgentService();
+    const controller = new SessionsController(agentService as never);
+
+    await expect(controller.destroy(CONVERSATION_ID, USER_B)).rejects.toBeInstanceOf(
+      NotFoundException,
+    );
+    expect(agentService.destroySession).not.toHaveBeenCalled();
+  });
+});
+
+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);
+
+    await expect(
+      controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
+    ).rejects.toMatchObject({ status: 404 });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(agentService.prompt).not.toHaveBeenCalled();
+  });
+});
+
+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 };
+  }
+
+  function makeSocket() {
+    return {
+      id: 'socket-b',
+      connected: true,
+      data: { user: USER_B, session: { id: 'auth-session-b', userId: USER_B.id } },
+      emit: vi.fn(),
+      disconnect: vi.fn(),
+    };
+  }
+
+  it('does not attach or send to another owner/tenant session by guessed conversationId', async () => {
+    const { gateway, agentService } = makeGateway();
+    const socket = makeSocket();
+
+    await gateway.handleMessage(socket as never, {
+      conversationId: CONVERSATION_ID,
+      content: 'attach to foreign session',
+    });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(agentService.onEvent).not.toHaveBeenCalled();
+    expect(agentService.addChannel).not.toHaveBeenCalled();
+    expect(agentService.prompt).not.toHaveBeenCalled();
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    );
+  });
+
+  it('does not mutate thinking level on another owner/tenant session', () => {
+    const { gateway, agentService } = makeGateway();
+    const socket = makeSocket();
+
+    gateway.handleSetThinking(socket as never, { conversationId: CONVERSATION_ID, level: 'high' });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    );
+  });
+
+  it('does not terminate another owner/tenant session over WebSocket abort', async () => {
+    const { gateway, agentService } = makeGateway();
+    const socket = makeSocket();
+
+    await gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    );
+  });
+});

apps/gateway/src/agent/agent.module.ts

@@ -1,4 +1,5 @@
 import { Global, Module } from '@nestjs/common';
+import { AgentRuntimeProviderRegistry, HermesRuntimeProvider } from '@mosaicstack/agent';
 import { AgentService } from './agent.service.js';
 import { ProviderService } from './provider.service.js';
 import { ProviderCredentialsService } from './provider-credentials.service.js';
@@ -8,24 +9,66 @@ import { SkillLoaderService } from './skill-loader.service.js';
 import { ProvidersController } from './providers.controller.js';
 import { SessionsController } from './sessions.controller.js';
 import { AgentConfigsController } from './agent-configs.controller.js';
+import { InteractionController } from './interaction.controller.js';
 import { RoutingController } from './routing/routing.controller.js';
+import { DurableSessionRepository } from './durable-session.repository.js';
+import { DurableSessionService } from './durable-session.service.js';
 import { CoordModule } from '../coord/coord.module.js';
 import { McpClientModule } from '../mcp-client/mcp-client.module.js';
 import { SkillsModule } from '../skills/skills.module.js';
 import { GCModule } from '../gc/gc.module.js';
+import { LogModule } from '../log/log.module.js';
+import { CommandsModule } from '../commands/commands.module.js';
+import { CommandRuntimeApprovalVerifier } from '../commands/runtime-approval-verifier.js';
+import { GatewayHermesRuntimeTransport } from './hermes-runtime.transport.js';
+import {
+  AGENT_RUNTIME_PROVIDER_REGISTRY,
+  RUNTIME_APPROVAL_VERIFIER,
+  RUNTIME_PROVIDER_AUDIT_SINK,
+  RuntimeProviderAuditService,
+  RuntimeProviderService,
+} from './runtime-provider-registry.service.js';
+
+export function createGatewayRuntimeProviderRegistry(): AgentRuntimeProviderRegistry {
+  const registry = new AgentRuntimeProviderRegistry();
+  registry.register(new HermesRuntimeProvider(new GatewayHermesRuntimeTransport()));
+  return registry;
+}
 
 @Global()
 @Module({
-  imports: [CoordModule, McpClientModule, SkillsModule, GCModule],
+  imports: [CoordModule, McpClientModule, SkillsModule, GCModule, LogModule, CommandsModule],
   providers: [
     ProviderService,
     ProviderCredentialsService,
     RoutingService,
     RoutingEngineService,
     SkillLoaderService,
+    DurableSessionRepository,
+    DurableSessionService,
+    {
+      provide: AGENT_RUNTIME_PROVIDER_REGISTRY,
+      useFactory: createGatewayRuntimeProviderRegistry,
+    },
+    RuntimeProviderAuditService,
+    {
+      provide: RUNTIME_PROVIDER_AUDIT_SINK,
+      useExisting: RuntimeProviderAuditService,
+    },
+    {
+      provide: RUNTIME_APPROVAL_VERIFIER,
+      useExisting: CommandRuntimeApprovalVerifier,
+    },
+    RuntimeProviderService,
     AgentService,
   ],
-  controllers: [ProvidersController, SessionsController, AgentConfigsController, RoutingController],
+  controllers: [
+    ProvidersController,
+    SessionsController,
+    AgentConfigsController,
+    InteractionController,
+    RoutingController,
+  ],
   exports: [
     AgentService,
     ProviderService,
@@ -33,6 +76,9 @@ import { GCModule } from '../gc/gc.module.js';
     RoutingService,
     RoutingEngineService,
     SkillLoaderService,
+    DurableSessionService,
+    RuntimeProviderService,
+    AGENT_RUNTIME_PROVIDER_REGISTRY,
   ],
 })
 export class AgentModule {}

apps/gateway/src/agent/agent.service.ts

@@ -1,4 +1,11 @@
-import { Inject, Injectable, Logger, Optional, type OnModuleDestroy } from '@nestjs/common';
+import {
+  ForbiddenException,
+  Inject,
+  Injectable,
+  Logger,
+  Optional,
+  type OnModuleDestroy,
+} from '@nestjs/common';
 import {
   createAgentSession,
   DefaultResourceLoader,
@@ -8,9 +15,10 @@ import {
   type ToolDefinition,
 } from '@mariozechner/pi-coding-agent';
 import type { Brain } from '@mosaicstack/brain';
-import type { Memory } from '@mosaicstack/memory';
+import type { Memory, OperatorMemoryPlugin } from '@mosaicstack/memory';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { MEMORY } from '../memory/memory.tokens.js';
+import { OPERATOR_MEMORY_PLUGIN } from '../memory/memory.module.js';
 import { EmbeddingService } from '../memory/embedding.service.js';
 import { CoordService } from '../coord/coord.service.js';
 import { ProviderService } from './provider.service.js';
@@ -28,6 +36,7 @@ import type { SessionInfoDto, SessionMetrics } from './session.dto.js';
 import { SystemOverrideService } from '../preferences/system-override.service.js';
 import { PreferencesService } from '../preferences/preferences.service.js';
 import { SessionGCService } from '../gc/session-gc.service.js';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 
 /** A single message from DB conversation history, used for context injection. */
 export interface ConversationHistoryMessage {
@@ -68,6 +77,8 @@ export interface AgentSessionOptions {
   agentConfigId?: string;
   /** ID of the user who owns this session. Used for preferences and system override lookups. */
   userId?: string;
+  /** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
+  tenantId?: string;
   /**
    * Prior conversation messages to inject as context when resuming a session.
    * These messages are formatted and prepended to the system prompt so the
@@ -94,6 +105,8 @@ export interface AgentSession {
   allowedTools: string[] | null;
   /** User ID that owns this session, used for preference lookups. */
   userId?: string;
+  /** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
+  tenantId?: string;
   /** Agent config ID applied to this session, if any (M5-001). */
   agentConfigId?: string;
   /** Human-readable agent name applied to this session, if any (M5-001). */
@@ -123,6 +136,9 @@ export class AgentService implements OnModuleDestroy {
     @Inject(PreferencesService)
     private readonly preferencesService: PreferencesService | null,
     @Inject(SessionGCService) private readonly gc: SessionGCService,
+    @Optional()
+    @Inject(OPERATOR_MEMORY_PLUGIN)
+    private readonly operatorMemory: OperatorMemoryPlugin | null = null,
   ) {}
 
   /**
@@ -134,6 +150,7 @@ export class AgentService implements OnModuleDestroy {
   private buildToolsForSandbox(
     sandboxDir: string,
     sessionUserId: string | undefined,
+    sessionScope?: { tenantId: string; ownerId: string; sessionId: string },
   ): ToolDefinition[] {
     return [
       ...createBrainTools(this.brain),
@@ -142,6 +159,9 @@ export class AgentService implements OnModuleDestroy {
         this.memory,
         this.embeddingService.available ? this.embeddingService : null,
         sessionUserId,
+        this.operatorMemory && sessionScope
+          ? { plugin: this.operatorMemory, scope: sessionScope }
+          : undefined,
       ),
       ...createFileTools(sandboxDir),
       ...createGitTools(sandboxDir),
@@ -174,12 +194,20 @@ export class AgentService implements OnModuleDestroy {
       .filter((t) => t.length > 0);
   }
 
-  async createSession(sessionId: string, options?: AgentSessionOptions): Promise<AgentSession> {
+  async createSession(sessionId: string, options: AgentSessionOptions): Promise<AgentSession> {
+    const scope = this.scopeFromOptions(options);
     const existing = this.sessions.get(sessionId);
-    if (existing) return existing;
+    if (existing) {
+      this.assertSessionScope(existing, scope);
+      return existing;
+    }
 
     const inflight = this.creating.get(sessionId);
-    if (inflight) return inflight;
+    if (inflight) {
+      const session = await inflight;
+      this.assertSessionScope(session, scope);
+      return session;
+    }
 
     const promise = this.doCreateSession(sessionId, options).finally(() => {
       this.creating.delete(sessionId);
@@ -208,6 +236,7 @@ export class AgentService implements OnModuleDestroy {
           isAdmin: options.isAdmin,
           agentConfigId: options.agentConfigId,
           userId: options.userId,
+          tenantId: options.tenantId,
           conversationHistory: options.conversationHistory,
         };
         this.logger.log(
@@ -247,7 +276,15 @@ export class AgentService implements OnModuleDestroy {
     }
 
     // Build per-session tools scoped to the sandbox directory and authenticated user
-    const sandboxTools = this.buildToolsForSandbox(sandboxDir, mergedOptions?.userId);
+    const sessionUserId = mergedOptions?.userId;
+    const sessionTenantId = this.tenantIdFor(sessionUserId, mergedOptions?.tenantId);
+    const sandboxTools = this.buildToolsForSandbox(
+      sandboxDir,
+      sessionUserId,
+      sessionUserId && sessionTenantId
+        ? { tenantId: sessionTenantId, ownerId: sessionUserId, sessionId }
+        : undefined,
+    );
 
     // Combine static tools with dynamically discovered MCP client tools and skill tools
     const mcpTools = this.mcpClientService.getToolDefinitions();
@@ -342,6 +379,7 @@ export class AgentService implements OnModuleDestroy {
       sandboxDir,
       allowedTools,
       userId: mergedOptions?.userId,
+      tenantId: sessionTenantId,
       agentConfigId: mergedOptions?.agentConfigId,
       agentName: resolvedAgentName,
       metrics: {
@@ -473,38 +511,70 @@ export class AgentService implements OnModuleDestroy {
     return this.providerService.getDefaultModel() ?? null;
   }
 
-  getSession(sessionId: string): AgentSession | undefined {
-    return this.sessions.get(sessionId);
+  getSession(sessionId: string, scope: ActorTenantScope): AgentSession | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session || !this.sessionMatchesScope(session, scope)) return undefined;
+    return session;
   }
 
-  listSessions(): SessionInfoDto[] {
+  listSessions(scope: ActorTenantScope): SessionInfoDto[] {
     const now = Date.now();
-    return Array.from(this.sessions.values()).map((s) => ({
-      id: s.id,
-      provider: s.provider,
-      modelId: s.modelId,
-      ...(s.agentName ? { agentName: s.agentName } : {}),
-      createdAt: new Date(s.createdAt).toISOString(),
-      promptCount: s.promptCount,
-      channels: Array.from(s.channels),
-      durationMs: now - s.createdAt,
-      metrics: { ...s.metrics },
-    }));
+    return Array.from(this.sessions.values())
+      .filter((s) => this.sessionMatchesScope(s, scope))
+      .map((s) => this.toSessionInfo(s, now));
   }
 
-  getSessionInfo(sessionId: string): SessionInfoDto | undefined {
+  listAllSessionsForSystem(): SessionInfoDto[] {
+    const now = Date.now();
+    return Array.from(this.sessions.values()).map((s) => this.toSessionInfo(s, now));
+  }
+
+  getSessionInfo(sessionId: string, scope: ActorTenantScope): SessionInfoDto | undefined {
     const s = this.sessions.get(sessionId);
-    if (!s) return undefined;
+    if (!s || !this.sessionMatchesScope(s, scope)) return undefined;
+    return this.toSessionInfo(s);
+  }
+
+  private scopeFromOptions(options: AgentSessionOptions): ActorTenantScope {
+    if (!options.userId) {
+      throw new ForbiddenException('Session owner scope is required');
+    }
     return {
-      id: s.id,
-      provider: s.provider,
-      modelId: s.modelId,
-      ...(s.agentName ? { agentName: s.agentName } : {}),
-      createdAt: new Date(s.createdAt).toISOString(),
-      promptCount: s.promptCount,
-      channels: Array.from(s.channels),
-      durationMs: Date.now() - s.createdAt,
-      metrics: { ...s.metrics },
+      userId: options.userId,
+      tenantId: this.tenantIdFor(options.userId, options.tenantId) ?? options.userId,
+    };
+  }
+
+  private tenantIdFor(
+    userId: string | undefined,
+    tenantId: string | undefined,
+  ): string | undefined {
+    return tenantId ?? userId;
+  }
+
+  private sessionMatchesScope(session: AgentSession, scope: ActorTenantScope): boolean {
+    return (
+      session.userId === scope.userId && (session.tenantId ?? session.userId) === scope.tenantId
+    );
+  }
+
+  private assertSessionScope(session: AgentSession, scope: ActorTenantScope): void {
+    if (!this.sessionMatchesScope(session, scope)) {
+      throw new ForbiddenException('Session does not belong to the current owner/tenant scope');
+    }
+  }
+
+  private toSessionInfo(session: AgentSession, now = Date.now()): SessionInfoDto {
+    return {
+      id: session.id,
+      provider: session.provider,
+      modelId: session.modelId,
+      ...(session.agentName ? { agentName: session.agentName } : {}),
+      createdAt: new Date(session.createdAt).toISOString(),
+      promptCount: session.promptCount,
+      channels: Array.from(session.channels),
+      durationMs: now - session.createdAt,
+      metrics: { ...session.metrics },
     };
   }
 
@@ -553,9 +623,10 @@ export class AgentService implements OnModuleDestroy {
    * not reconstructed — the model is used on the next createSession call for
    * the same conversationId when the session is torn down or a new one is created.
    */
-  updateSessionModel(sessionId: string, modelId: string): void {
+  updateSessionModel(sessionId: string, modelId: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    this.assertSessionScope(session, scope);
     const prev = session.modelId;
     session.modelId = modelId;
     this.recordModelSwitch(sessionId);
@@ -572,48 +643,51 @@ export class AgentService implements OnModuleDestroy {
     sessionId: string,
     agentConfigId: string,
     agentName: string,
+    scope: ActorTenantScope,
     modelId?: string,
   ): void {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    this.assertSessionScope(session, scope);
     session.agentConfigId = agentConfigId;
     session.agentName = agentName;
     if (modelId) {
-      this.updateSessionModel(sessionId, modelId);
+      this.updateSessionModel(sessionId, modelId, scope);
     }
     this.logger.log(
       `Session ${sessionId}: agent switched to "${agentName}" (${agentConfigId}) (M5-003)`,
     );
   }
 
-  addChannel(sessionId: string, channel: string): void {
+  addChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
-    if (session) {
-      session.channels.add(channel);
-    }
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    session.channels.add(channel);
   }
 
-  removeChannel(sessionId: string, channel: string): void {
+  removeChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
-    if (session) {
-      session.channels.delete(channel);
-    }
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    session.channels.delete(channel);
   }
 
-  async prompt(sessionId: string, message: string): Promise<void> {
+  async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
     }
+    this.assertSessionScope(session, scope);
     session.promptCount += 1;
 
     // Prepend session-scoped system override if present (renew TTL on each turn)
     let effectiveMessage = message;
     if (this.systemOverride) {
-      const override = await this.systemOverride.get(sessionId);
+      const override = await this.systemOverride.get(sessionId, scope);
       if (override) {
         effectiveMessage = `[System Override]\n${override}\n\n${message}`;
-        await this.systemOverride.renew(sessionId);
+        await this.systemOverride.renew(sessionId, scope);
         this.logger.debug(`Applied system override for session ${sessionId}`);
       }
     }
@@ -629,16 +703,28 @@ export class AgentService implements OnModuleDestroy {
     }
   }
 
-  onEvent(sessionId: string, listener: (event: AgentSessionEvent) => void): () => void {
+  onEvent(
+    sessionId: string,
+    listener: (event: AgentSessionEvent) => void,
+    scope: ActorTenantScope,
+  ): () => void {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
     }
+    this.assertSessionScope(session, scope);
     session.listeners.add(listener);
     return () => session.listeners.delete(listener);
   }
 
-  async destroySession(sessionId: string): Promise<void> {
+  async destroySession(sessionId: string, scope: ActorTenantScope): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    await this.destroySessionForSystem(sessionId);
+  }
+
+  private async destroySessionForSystem(sessionId: string): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) return;
     this.logger.log(`Destroying agent session ${sessionId}`);
@@ -667,7 +753,7 @@ export class AgentService implements OnModuleDestroy {
 
   async onModuleDestroy(): Promise<void> {
     this.logger.log('Shutting down all agent sessions');
-    const stops = Array.from(this.sessions.keys()).map((id) => this.destroySession(id));
+    const stops = Array.from(this.sessions.keys()).map((id) => this.destroySessionForSystem(id));
     const results = await Promise.allSettled(stops);
     for (const result of results) {
       if (result.status === 'rejected') {

apps/gateway/src/agent/durable-session.dto.ts

@@ -0,0 +1,10 @@
+import type { RuntimeProviderRequestContext } from './runtime-provider-registry.service.js';
+
+/** Server-side request for a replay-safe provider message. */
+export interface ProviderOutboxDto {
+  sessionId: string;
+  idempotencyKey: string;
+  correlationId: string;
+  content: string;
+  context: RuntimeProviderRequestContext;
+}

apps/gateway/src/agent/durable-session.repository.test.ts

@@ -0,0 +1,416 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { eq, sql, interactionCheckpoints, interactionInbox } from '@mosaicstack/db';
+import { DurableSessionCoordinator, type DurableSessionIdentity } from '@mosaicstack/agent';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPgliteDb, runPgliteMigrations, type DbHandle } from '@mosaicstack/db';
+import { DurableSessionRepository } from './durable-session.repository.js';
+import { DurableSessionService } from './durable-session.service.js';
+
+const IDENTITY: DurableSessionIdentity = {
+  agentName: 'Nova',
+  sessionId: 'tess-pglite-session',
+  tenantId: 'tenant-pglite',
+  ownerId: 'tess-owner',
+  providerId: 'fleet',
+  runtimeSessionId: 'nova',
+};
+
+describe('DurableSessionRepository', () => {
+  let dataDir: string | undefined;
+  let handle: DbHandle;
+  let previousAuthSecret: string | undefined;
+
+  beforeAll(async (): Promise<void> => {
+    previousAuthSecret = process.env['BETTER_AUTH_SECRET'];
+    process.env['BETTER_AUTH_SECRET'] = 'tess-durable-state-test-sealing-key';
+    dataDir = mkdtempSync(join(tmpdir(), 'tess-durable-state-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    await seedOwner(handle);
+  }, 30_000);
+
+  beforeEach(async (): Promise<void> => {
+    await handle.db.execute(sql`DELETE FROM interaction_handoffs`);
+    await handle.db.execute(sql`DELETE FROM interaction_checkpoints`);
+    await handle.db.execute(sql`DELETE FROM interaction_inbox`);
+    await handle.db.execute(sql`DELETE FROM interaction_outbox`);
+    await handle.db.execute(sql`DELETE FROM interaction_sessions`);
+  });
+
+  afterAll(async (): Promise<void> => {
+    await handle.close();
+    if (dataDir) rmSync(dataDir, { recursive: true, force: true });
+    if (previousAuthSecret === undefined) delete process.env['BETTER_AUTH_SECRET'];
+    else process.env['BETTER_AUTH_SECRET'] = previousAuthSecret;
+  });
+
+  it('survives a full PGlite close/reopen mid-session without duplicate inbox or outbox side effects', async () => {
+    const beforeRestart = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
+    await beforeRestart.create(IDENTITY);
+    await beforeRestart.receive({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'inbox-before-kill',
+      correlationId: 'correlation-before-kill',
+      content: 'resume after a kill',
+    });
+    await beforeRestart.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-before-kill',
+      correlationId: 'correlation-before-kill',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'one response only',
+    });
+    await beforeRestart.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-before-kill',
+      cursor: 'cursor-before-kill',
+      summary: 'restart-safe state',
+      compactionEpoch: 1,
+    });
+    await beforeRestart.handoff({
+      sessionId: IDENTITY.sessionId,
+      handoffId: 'handoff-before-kill',
+      destination: 'mos',
+      correlationId: 'correlation-before-kill',
+      checkpointId: 'checkpoint-before-kill',
+      status: 'pending',
+    });
+    await beforeRestart.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-after-handoff',
+      cursor: 'cursor-after-handoff',
+      summary: 'newer state cannot strand the portable handoff',
+      compactionEpoch: 2,
+    });
+
+    await handle.close();
+    handle = createPgliteDb(dataDir!);
+
+    const afterRestart = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
+    const recovered = await afterRestart.recover(IDENTITY.sessionId);
+    const resumedHandoff = await afterRestart.resumeHandoff('handoff-before-kill');
+    const handled: string[] = [];
+    const effects: string[] = [];
+
+    await afterRestart.drainInbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      handled.push(entry.idempotencyKey);
+    });
+    await afterRestart.dispatchOutbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      effects.push(entry.idempotencyKey);
+    });
+    await afterRestart.drainInbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      handled.push(entry.idempotencyKey);
+    });
+    await afterRestart.dispatchOutbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      effects.push(entry.idempotencyKey);
+    });
+
+    expect(recovered.identity).toEqual(IDENTITY);
+    expect(recovered.checkpoint).toMatchObject({ checkpointId: 'checkpoint-after-handoff' });
+    expect(recovered.handoffs).toMatchObject([{ handoffId: 'handoff-before-kill' }]);
+    expect(resumedHandoff.checkpoint).toMatchObject({ checkpointId: 'checkpoint-before-kill' });
+    expect(handled).toEqual(['inbox-before-kill']);
+    expect(effects).toEqual(['outbox-before-kill']);
+  }, 30_000);
+
+  it('redacts sensitive durable payloads before persistence', async () => {
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    await coordinator.receive({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'redacted-inbox',
+      correlationId: 'correlation-redaction',
+      content: 'api_key=super-secret-canary',
+    });
+    await coordinator.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'redacted-outbox',
+      correlationId: 'correlation-redaction',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'email operator@example.test api_key=super-secret-canary',
+    });
+    await coordinator.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'redacted-checkpoint',
+      cursor: 'bearer super-secret-canary',
+      summary: 'email operator@example.test',
+      compactionEpoch: 0,
+    });
+
+    const snapshot = await coordinator.snapshot(IDENTITY.sessionId);
+    const [persisted] = await handle.db
+      .select({ content: interactionInbox.content })
+      .from(interactionInbox)
+      .where(eq(interactionInbox.idempotencyKey, 'redacted-inbox'));
+
+    expect(JSON.stringify(snapshot)).not.toContain('super-secret-canary');
+    expect(JSON.stringify(snapshot)).not.toContain('operator@example.test');
+    expect(persisted?.content).not.toContain('super-secret-canary');
+    expect(persisted?.content).not.toContain('[REDACTED]');
+  }, 30_000);
+
+  it('fails closed when the configured idempotency secret is unavailable', async () => {
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    const secret = process.env['BETTER_AUTH_SECRET'];
+    delete process.env['BETTER_AUTH_SECRET'];
+    try {
+      await expect(
+        coordinator.receive({
+          sessionId: IDENTITY.sessionId,
+          idempotencyKey: 'requires-idempotency-secret',
+          correlationId: 'correlation-secret',
+          content: 'sensitive payload',
+        }),
+      ).rejects.toThrow(/required for durable idempotency digests/);
+    } finally {
+      if (secret === undefined) delete process.env['BETTER_AUTH_SECRET'];
+      else process.env['BETTER_AUTH_SECRET'] = secret;
+    }
+  }, 30_000);
+
+  it('uses keyed pre-redaction digests to reject distinct sensitive checkpoint payloads', async () => {
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    const input = {
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-secret-conflict',
+      cursor: 'api_key=secret-one',
+      summary: 'bearer secret-one',
+      compactionEpoch: 1,
+    };
+    await coordinator.checkpoint(input);
+
+    await expect(
+      coordinator.checkpoint({
+        ...input,
+        cursor: 'api_key=secret-two',
+        summary: 'bearer secret-two',
+      }),
+    ).rejects.toThrow(/checkpoint identity conflict/);
+
+    const [persisted] = await handle.db
+      .select({
+        digest: interactionCheckpoints.contentDigest,
+        cursor: interactionCheckpoints.cursor,
+      })
+      .from(interactionCheckpoints)
+      .where(eq(interactionCheckpoints.checkpointId, input.checkpointId));
+    expect(persisted?.cursor).not.toContain('secret-one');
+    expect(persisted?.digest).not.toBe(
+      createHash('sha256')
+        .update(JSON.stringify([input.cursor, input.summary]))
+        .digest('hex'),
+    );
+
+    await coordinator.checkpoint({
+      ...input,
+      checkpointId: 'checkpoint-delimiter-conflict',
+      cursor: 'a\u0000b',
+      summary: 'c',
+    });
+    await expect(
+      coordinator.checkpoint({
+        ...input,
+        checkpointId: 'checkpoint-delimiter-conflict',
+        cursor: 'a',
+        summary: 'b\u0000c',
+      }),
+    ).rejects.toThrow(/checkpoint identity conflict/);
+  }, 30_000);
+
+  it('rejects distinct sensitive inbox and outbox payloads under reused idempotency keys', async () => {
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    const inbox = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'inbox-secret-conflict',
+      correlationId: 'correlation-inbox-secret',
+      content: 'api_key=secret-one',
+    };
+    const outbox = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-secret-conflict',
+      correlationId: 'correlation-outbox-secret',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'api_key=secret-one',
+    };
+    await coordinator.receive(inbox);
+    await coordinator.enqueueOutbox(outbox);
+
+    await expect(coordinator.receive({ ...inbox, content: 'api_key=secret-two' })).rejects.toThrow(
+      /idempotency conflict/,
+    );
+    await expect(
+      coordinator.enqueueOutbox({ ...outbox, content: 'api_key=secret-two' }),
+    ).rejects.toThrow(/idempotency conflict/);
+  }, 30_000);
+
+  it('rejects database inbox and outbox idempotency-key conflicts', async () => {
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    await coordinator.receive({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'inbox-conflict',
+      correlationId: 'correlation-inbox',
+      content: 'original inbox',
+    });
+    await coordinator.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-conflict',
+      correlationId: 'correlation-outbox',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'original outbox',
+    });
+
+    await expect(
+      coordinator.receive({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'inbox-conflict',
+        correlationId: 'forged-correlation',
+        content: 'original inbox',
+      }),
+    ).rejects.toThrow(/idempotency conflict/);
+    await expect(
+      coordinator.enqueueOutbox({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'outbox-conflict',
+        correlationId: 'correlation-outbox',
+        channelId: 'forged-channel',
+        kind: 'provider.send',
+        content: 'original outbox',
+      }),
+    ).rejects.toThrow(/idempotency conflict/);
+  }, 30_000);
+
+  it('does not requeue a live outbox claim during a normal scoped dispatch', async () => {
+    const repository = new DurableSessionRepository(handle.db);
+    const coordinator = new DurableSessionCoordinator(repository);
+    const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
+    const service = new DurableSessionService(repository, runtimeProviders as never);
+    const input = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'live-effect',
+      correlationId: 'correlation-live',
+      content: 'must not duplicate',
+      context: {
+        actorScope: { userId: IDENTITY.ownerId, tenantId: IDENTITY.tenantId },
+        channelId: 'cli',
+        correlationId: 'correlation-live',
+      },
+    };
+
+    await coordinator.create(IDENTITY);
+    await service.queueProviderSend(input);
+    expect(await repository.claimOutbox(IDENTITY.sessionId)).toMatchObject({
+      status: 'processing',
+    });
+
+    await service.dispatchProviderOutbox(IDENTITY.sessionId, input);
+    await expect(
+      service.recoverProviderSession(IDENTITY.sessionId, {
+        ...input,
+        context: {
+          ...input.context,
+          actorScope: { userId: 'intruder', tenantId: 'tenant-pglite' },
+        },
+      }),
+    ).rejects.toThrow(/scope or correlation mismatch/);
+
+    expect(runtimeProviders.sendMessage).not.toHaveBeenCalled();
+    expect(await coordinator.snapshot(IDENTITY.sessionId)).toMatchObject({
+      outbox: [{ idempotencyKey: 'live-effect', status: 'processing' }],
+    });
+  }, 30_000);
+
+  it('rejects an outbox correlation mismatch before claiming the pending effect', async () => {
+    const repository = new DurableSessionRepository(handle.db);
+    const coordinator = new DurableSessionCoordinator(repository);
+    const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
+    const service = new DurableSessionService(repository, runtimeProviders as never);
+    const input = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'mismatch-effect',
+      correlationId: 'correlation-expected',
+      content: 'must remain pending',
+      context: {
+        actorScope: { userId: IDENTITY.ownerId, tenantId: IDENTITY.tenantId },
+        channelId: 'cli',
+        correlationId: 'correlation-expected',
+      },
+    };
+
+    await coordinator.create(IDENTITY);
+    await service.queueProviderSend(input);
+    await expect(
+      service.dispatchProviderOutbox(IDENTITY.sessionId, {
+        ...input,
+        correlationId: 'correlation-forged',
+        context: { ...input.context, correlationId: 'correlation-forged' },
+      }),
+    ).rejects.toThrow(/scope or correlation mismatch/);
+
+    expect(runtimeProviders.sendMessage).not.toHaveBeenCalled();
+    expect(await coordinator.snapshot(IDENTITY.sessionId)).toMatchObject({
+      outbox: [{ idempotencyKey: 'mismatch-effect', status: 'pending' }],
+    });
+  }, 30_000);
+
+  it('dispatches only the outbox record bound to the supplied correlation and channel', async () => {
+    const repository = new DurableSessionRepository(handle.db);
+    const coordinator = new DurableSessionCoordinator(repository);
+    const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
+    const service = new DurableSessionService(repository, runtimeProviders as never);
+    const first = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'scoped-effect-one',
+      correlationId: 'correlation-one',
+      content: 'first result',
+      context: {
+        actorScope: { userId: IDENTITY.ownerId, tenantId: IDENTITY.tenantId },
+        channelId: 'cli',
+        correlationId: 'correlation-one',
+      },
+    };
+    const second = {
+      ...first,
+      idempotencyKey: 'scoped-effect-two',
+      correlationId: 'correlation-two',
+      content: 'second result',
+      context: { ...first.context, correlationId: 'correlation-two' },
+    };
+
+    await coordinator.create(IDENTITY);
+    await service.queueProviderSend(first);
+    await service.queueProviderSend(second);
+    await service.dispatchProviderOutbox(IDENTITY.sessionId, first);
+
+    expect(runtimeProviders.sendMessage).toHaveBeenCalledTimes(1);
+    expect(runtimeProviders.sendMessage).toHaveBeenCalledWith(
+      IDENTITY.providerId,
+      IDENTITY.runtimeSessionId,
+      { content: 'first result', idempotencyKey: 'scoped-effect-one' },
+      first.context,
+    );
+    expect(await coordinator.snapshot(IDENTITY.sessionId)).toMatchObject({
+      outbox: [
+        { idempotencyKey: 'scoped-effect-one', status: 'delivered' },
+        { idempotencyKey: 'scoped-effect-two', status: 'pending' },
+      ],
+    });
+  }, 30_000);
+});
+
+async function seedOwner(handle: DbHandle): Promise<void> {
+  await handle.db.execute(sql`
+    INSERT INTO users (id, name, email, email_verified, created_at, updated_at)
+    VALUES ('tess-owner', 'Tess Owner', 'tess-owner@example.test', false, now(), now())
+  `);
+}

apps/gateway/src/agent/durable-session.repository.ts

@@ -0,0 +1,529 @@
+import { createHash, createHmac } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  interactionCheckpoints,
+  interactionHandoffs,
+  interactionInbox,
+  interactionOutbox,
+  interactionSessions,
+  type Db,
+} from '@mosaicstack/db';
+import { seal, unseal } from '@mosaicstack/auth';
+import { redactSensitiveContent } from '@mosaicstack/log';
+import type {
+  DurableCheckpoint,
+  DurableCheckpointInput,
+  DurableEnqueueResult,
+  DurableHandoff,
+  DurableHandoffInput,
+  DurableInboxEntry,
+  DurableInboxInput,
+  DurableInboxStatus,
+  DurableOutboxEntry,
+  DurableOutboxInput,
+  DurableOutboxStatus,
+  DurableSessionIdentity,
+  DurableSessionSnapshot,
+  DurableSessionStore,
+} from '@mosaicstack/agent';
+import { DB } from '../database/database.module.js';
+
+@Injectable()
+export class DurableSessionRepository implements DurableSessionStore {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async create(identity: DurableSessionIdentity): Promise<void> {
+    await this.db
+      .insert(interactionSessions)
+      .values({
+        id: identity.sessionId,
+        agentName: identity.agentName,
+        tenantId: identity.tenantId,
+        ownerId: identity.ownerId,
+        providerId: identity.providerId,
+        runtimeSessionId: identity.runtimeSessionId,
+      })
+      .onConflictDoNothing();
+
+    const existing = await this.session(identity.sessionId);
+    if (!existing || !sameEnrollmentScope(existing, identity)) {
+      throw new Error(`Durable session identity conflict: ${identity.sessionId}`);
+    }
+    // A recovered/re-enrolled runtime can receive a new provider session ID;
+    // the conversation handle and owner scope remain immutable.
+    if (
+      existing.providerId !== identity.providerId ||
+      existing.runtimeSessionId !== identity.runtimeSessionId
+    ) {
+      await this.db
+        .update(interactionSessions)
+        .set({ providerId: identity.providerId, runtimeSessionId: identity.runtimeSessionId })
+        .where(eq(interactionSessions.id, identity.sessionId));
+    }
+  }
+
+  async snapshot(sessionId: string): Promise<DurableSessionSnapshot | null> {
+    const identity = await this.session(sessionId);
+    if (!identity) return null;
+
+    const [inbox, outbox, checkpoints, handoffs] = await Promise.all([
+      this.db
+        .select()
+        .from(interactionInbox)
+        .where(eq(interactionInbox.sessionId, sessionId))
+        .orderBy(asc(interactionInbox.createdAt)),
+      this.db
+        .select()
+        .from(interactionOutbox)
+        .where(eq(interactionOutbox.sessionId, sessionId))
+        .orderBy(asc(interactionOutbox.createdAt)),
+      this.db
+        .select()
+        .from(interactionCheckpoints)
+        .where(eq(interactionCheckpoints.sessionId, sessionId))
+        .orderBy(
+          desc(interactionCheckpoints.compactionEpoch),
+          desc(interactionCheckpoints.createdAt),
+        )
+        .limit(1),
+      this.db
+        .select()
+        .from(interactionHandoffs)
+        .where(eq(interactionHandoffs.sessionId, sessionId))
+        .orderBy(asc(interactionHandoffs.createdAt)),
+    ]);
+
+    const checkpoint = checkpoints[0];
+    return {
+      identity,
+      inbox: inbox.map(toInbox),
+      outbox: outbox.map(toOutbox),
+      ...(checkpoint ? { checkpoint: toCheckpoint(checkpoint) } : {}),
+      handoffs: handoffs.map(toHandoff),
+    };
+  }
+
+  async enqueueInbox(input: DurableInboxInput): Promise<DurableEnqueueResult<DurableInboxStatus>> {
+    const digest = contentDigest(input.content);
+    const record: DurableInboxInput = {
+      ...input,
+      content: redactSensitiveContent(input.content).content,
+    };
+    const inserted = await this.db
+      .insert(interactionInbox)
+      .values({
+        ...record,
+        content: seal(record.content),
+        contentDigest: digest,
+        status: 'pending',
+      })
+      .onConflictDoNothing()
+      .returning({ status: interactionInbox.status });
+    if (inserted[0]) return { accepted: true, status: inserted[0].status };
+
+    const existing = await this.db
+      .select()
+      .from(interactionInbox)
+      .where(
+        and(
+          eq(interactionInbox.sessionId, input.sessionId),
+          eq(interactionInbox.idempotencyKey, input.idempotencyKey),
+        ),
+      )
+      .limit(1);
+    if (!existing[0]) throw new Error(`Durable inbox enqueue failed: ${input.idempotencyKey}`);
+    const entry = toInbox(existing[0]);
+    if (
+      !sameInbox(entry, record) ||
+      !matchesContentDigest(existing[0].contentDigest, input.content)
+    ) {
+      throw new Error(`Durable inbox idempotency conflict: ${input.idempotencyKey}`);
+    }
+    return { accepted: false, status: entry.status };
+  }
+
+  async claimInbox(sessionId: string): Promise<DurableInboxEntry | null> {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const candidate = await this.db
+        .select()
+        .from(interactionInbox)
+        .where(
+          and(eq(interactionInbox.sessionId, sessionId), eq(interactionInbox.status, 'pending')),
+        )
+        .orderBy(asc(interactionInbox.createdAt))
+        .limit(1);
+      const entry = candidate[0];
+      if (!entry) return null;
+      const claimed = await this.db
+        .update(interactionInbox)
+        .set({ status: 'processing', updatedAt: new Date() })
+        .where(and(eq(interactionInbox.id, entry.id), eq(interactionInbox.status, 'pending')))
+        .returning();
+      if (claimed[0]) return toInbox(claimed[0]);
+    }
+    return null;
+  }
+
+  async completeInbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionInbox)
+      .set({ status: 'processed', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionInbox.sessionId, sessionId),
+          eq(interactionInbox.idempotencyKey, idempotencyKey),
+          eq(interactionInbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async releaseInbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionInbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionInbox.sessionId, sessionId),
+          eq(interactionInbox.idempotencyKey, idempotencyKey),
+          eq(interactionInbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async enqueueOutbox(
+    input: DurableOutboxInput,
+  ): Promise<DurableEnqueueResult<DurableOutboxStatus>> {
+    const digest = contentDigest(input.content);
+    const record: DurableOutboxInput = {
+      ...input,
+      content: redactSensitiveContent(input.content).content,
+    };
+    const inserted = await this.db
+      .insert(interactionOutbox)
+      .values({
+        ...record,
+        content: seal(record.content),
+        contentDigest: digest,
+        status: 'pending',
+      })
+      .onConflictDoNothing()
+      .returning({ status: interactionOutbox.status });
+    if (inserted[0]) return { accepted: true, status: inserted[0].status };
+
+    const existing = await this.db
+      .select()
+      .from(interactionOutbox)
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, input.sessionId),
+          eq(interactionOutbox.idempotencyKey, input.idempotencyKey),
+        ),
+      )
+      .limit(1);
+    if (!existing[0]) throw new Error(`Durable outbox enqueue failed: ${input.idempotencyKey}`);
+    const entry = toOutbox(existing[0]);
+    if (
+      !sameOutbox(entry, record) ||
+      !matchesContentDigest(existing[0].contentDigest, input.content)
+    ) {
+      throw new Error(`Durable outbox idempotency conflict: ${input.idempotencyKey}`);
+    }
+    return { accepted: false, status: entry.status };
+  }
+
+  async claimOutbox(sessionId: string): Promise<DurableOutboxEntry | null> {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const candidate = await this.db
+        .select()
+        .from(interactionOutbox)
+        .where(
+          and(eq(interactionOutbox.sessionId, sessionId), eq(interactionOutbox.status, 'pending')),
+        )
+        .orderBy(asc(interactionOutbox.createdAt))
+        .limit(1);
+      const entry = candidate[0];
+      if (!entry) return null;
+      const claimed = await this.db
+        .update(interactionOutbox)
+        .set({ status: 'processing', updatedAt: new Date() })
+        .where(and(eq(interactionOutbox.id, entry.id), eq(interactionOutbox.status, 'pending')))
+        .returning();
+      if (claimed[0]) return toOutbox(claimed[0]);
+    }
+    return null;
+  }
+
+  async claimOutboxByKey(
+    sessionId: string,
+    idempotencyKey: string,
+  ): Promise<DurableOutboxEntry | null> {
+    const claimed = await this.db
+      .update(interactionOutbox)
+      .set({ status: 'processing', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, sessionId),
+          eq(interactionOutbox.idempotencyKey, idempotencyKey),
+          eq(interactionOutbox.status, 'pending'),
+        ),
+      )
+      .returning();
+    return claimed[0] ? toOutbox(claimed[0]) : null;
+  }
+
+  async completeOutbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionOutbox)
+      .set({ status: 'delivered', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, sessionId),
+          eq(interactionOutbox.idempotencyKey, idempotencyKey),
+          eq(interactionOutbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async releaseOutbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionOutbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, sessionId),
+          eq(interactionOutbox.idempotencyKey, idempotencyKey),
+          eq(interactionOutbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async checkpoint(input: DurableCheckpointInput): Promise<void> {
+    // Compute identity before redaction.  The persisted digest is keyed so a database
+    // reader cannot use it as an offline oracle for sensitive cursor/summary values.
+    const digest = contentDigest(JSON.stringify([input.cursor, input.summary]));
+    const checkpoint: DurableCheckpointInput = {
+      ...input,
+      cursor: redactSensitiveContent(input.cursor).content,
+      summary: redactSensitiveContent(input.summary).content,
+    };
+    const inserted = await this.db
+      .insert(interactionCheckpoints)
+      .values({
+        ...checkpoint,
+        contentDigest: digest,
+        cursor: seal(checkpoint.cursor),
+        summary: seal(checkpoint.summary),
+      })
+      .onConflictDoNothing()
+      .returning({ checkpointId: interactionCheckpoints.checkpointId });
+    if (inserted[0]) return;
+
+    const existing = await this.db
+      .select()
+      .from(interactionCheckpoints)
+      .where(
+        and(
+          eq(interactionCheckpoints.sessionId, input.sessionId),
+          eq(interactionCheckpoints.checkpointId, input.checkpointId),
+        ),
+      )
+      .limit(1);
+    if (
+      !existing[0] ||
+      !sameCheckpoint(toCheckpoint(existing[0]), checkpoint) ||
+      !matchesCheckpointDigest(existing[0].contentDigest, digest)
+    ) {
+      throw new Error(`Durable checkpoint identity conflict: ${input.checkpointId}`);
+    }
+  }
+
+  async findCheckpoint(sessionId: string, checkpointId: string): Promise<DurableCheckpoint | null> {
+    const checkpoints = await this.db
+      .select()
+      .from(interactionCheckpoints)
+      .where(
+        and(
+          eq(interactionCheckpoints.sessionId, sessionId),
+          eq(interactionCheckpoints.checkpointId, checkpointId),
+        ),
+      )
+      .limit(1);
+    const checkpoint = checkpoints[0];
+    return checkpoint ? toCheckpoint(checkpoint) : null;
+  }
+
+  async handoff(input: DurableHandoffInput): Promise<void> {
+    const checkpoint = await this.findCheckpoint(input.sessionId, input.checkpointId);
+    if (!checkpoint) {
+      throw new Error(`Durable handoff checkpoint is unavailable: ${input.checkpointId}`);
+    }
+    const inserted = await this.db
+      .insert(interactionHandoffs)
+      .values({ ...input })
+      .onConflictDoNothing()
+      .returning({ handoffId: interactionHandoffs.handoffId });
+    if (inserted[0]) return;
+
+    const existing = await this.findHandoff(input.handoffId);
+    if (!existing || !sameHandoff(existing, input)) {
+      throw new Error(`Durable handoff identity conflict: ${input.handoffId}`);
+    }
+  }
+
+  async findHandoff(handoffId: string): Promise<DurableHandoff | null> {
+    const handoffs = await this.db
+      .select()
+      .from(interactionHandoffs)
+      .where(eq(interactionHandoffs.handoffId, handoffId))
+      .limit(1);
+    const handoff = handoffs[0];
+    return handoff ? toHandoff(handoff) : null;
+  }
+
+  async requeueInFlight(sessionId: string): Promise<void> {
+    // Inbox handlers are process-local work. A provider outbox claim may have
+    // reached an external target before a crash, so it is deliberately not
+    // replayed by generic recovery.
+    await this.db
+      .update(interactionInbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(
+        and(eq(interactionInbox.sessionId, sessionId), eq(interactionInbox.status, 'processing')),
+      );
+  }
+
+  private async session(sessionId: string): Promise<DurableSessionIdentity | null> {
+    const sessions = await this.db
+      .select()
+      .from(interactionSessions)
+      .where(eq(interactionSessions.id, sessionId))
+      .limit(1);
+    const session = sessions[0];
+    return session
+      ? {
+          agentName: session.agentName,
+          sessionId: session.id,
+          tenantId: session.tenantId,
+          ownerId: session.ownerId,
+          providerId: session.providerId,
+          runtimeSessionId: session.runtimeSessionId,
+        }
+      : null;
+  }
+}
+
+function contentDigest(content: string): string {
+  const secret = process.env['BETTER_AUTH_SECRET'];
+  if (!secret) {
+    throw new Error('BETTER_AUTH_SECRET is required for durable idempotency digests');
+  }
+  return `hmac:v1:${createHmac('sha256', secret).update(content).digest('hex')}`;
+}
+
+function matchesContentDigest(stored: string, content: string): boolean {
+  return (
+    stored === contentDigest(content) ||
+    stored === createHash('sha256').update(content).digest('hex')
+  );
+}
+
+function matchesCheckpointDigest(stored: string, digest: string): boolean {
+  // Legacy rows predate any pre-redaction identity and cannot safely prove equality.
+  // Reject rather than let redaction collapse distinct sensitive checkpoint payloads.
+  return stored === digest;
+}
+
+function sameEnrollmentScope(left: DurableSessionIdentity, right: DurableSessionIdentity): boolean {
+  return (
+    left.agentName === right.agentName &&
+    left.sessionId === right.sessionId &&
+    left.tenantId === right.tenantId &&
+    left.ownerId === right.ownerId
+  );
+}
+
+function sameInbox(left: DurableInboxEntry, right: DurableInboxInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.idempotencyKey === right.idempotencyKey &&
+    left.correlationId === right.correlationId &&
+    left.content === right.content
+  );
+}
+
+function sameOutbox(left: DurableOutboxEntry, right: DurableOutboxInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.idempotencyKey === right.idempotencyKey &&
+    left.correlationId === right.correlationId &&
+    left.channelId === right.channelId &&
+    left.kind === right.kind &&
+    left.content === right.content
+  );
+}
+
+function sameCheckpoint(left: DurableCheckpoint, right: DurableCheckpointInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.checkpointId === right.checkpointId &&
+    left.compactionEpoch === right.compactionEpoch
+  );
+}
+
+function sameHandoff(left: DurableHandoff, right: DurableHandoffInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.handoffId === right.handoffId &&
+    left.destination === right.destination &&
+    left.correlationId === right.correlationId &&
+    left.checkpointId === right.checkpointId &&
+    left.status === right.status
+  );
+}
+
+function toInbox(row: typeof interactionInbox.$inferSelect): DurableInboxEntry {
+  return {
+    sessionId: row.sessionId,
+    idempotencyKey: row.idempotencyKey,
+    correlationId: row.correlationId,
+    content: unseal(row.content),
+    status: row.status,
+  };
+}
+
+function toOutbox(row: typeof interactionOutbox.$inferSelect): DurableOutboxEntry {
+  return {
+    sessionId: row.sessionId,
+    idempotencyKey: row.idempotencyKey,
+    correlationId: row.correlationId,
+    channelId: row.channelId,
+    kind: row.kind,
+    content: unseal(row.content),
+    status: row.status,
+  };
+}
+
+function toCheckpoint(row: typeof interactionCheckpoints.$inferSelect): DurableCheckpoint {
+  return {
+    sessionId: row.sessionId,
+    checkpointId: row.checkpointId,
+    cursor: unseal(row.cursor),
+    summary: unseal(row.summary),
+    compactionEpoch: row.compactionEpoch,
+  };
+}
+
+function toHandoff(row: typeof interactionHandoffs.$inferSelect): DurableHandoff {
+  return {
+    sessionId: row.sessionId,
+    handoffId: row.handoffId,
+    destination: row.destination,
+    correlationId: row.correlationId,
+    checkpointId: row.checkpointId,
+    status: row.status,
+  };
+}

apps/gateway/src/agent/durable-session.service.ts

@@ -0,0 +1,123 @@
+import { ForbiddenException, Inject, Injectable } from '@nestjs/common';
+import { DurableSessionCoordinator, type DurableSessionIdentity } from '@mosaicstack/agent';
+import type { ProviderOutboxDto } from './durable-session.dto.js';
+import { DurableSessionRepository } from './durable-session.repository.js';
+import {
+  RuntimeProviderService,
+  type RuntimeProviderRequestContext,
+} from './runtime-provider-registry.service.js';
+
+/**
+ * Scoped gateway boundary for the canonical durable session state machine. It deliberately
+ * uses composition: raw state methods cannot be injected into channel, CLI, or
+ * MCP adapters without a server-derived actor/tenant/correlation context.
+ */
+@Injectable()
+export class DurableSessionService {
+  private readonly coordinator: DurableSessionCoordinator;
+
+  constructor(
+    @Inject(DurableSessionRepository) repository: DurableSessionRepository,
+    @Inject(RuntimeProviderService) private readonly runtimeProviders: RuntimeProviderService,
+  ) {
+    this.coordinator = new DurableSessionCoordinator(repository);
+  }
+
+  /** Enroll a verified runtime session under the stable cross-surface conversation handle. */
+  async enroll(
+    identity: DurableSessionIdentity,
+    context: RuntimeProviderRequestContext,
+  ): Promise<void> {
+    if (
+      identity.ownerId !== context.actorScope.userId ||
+      identity.tenantId !== context.actorScope.tenantId
+    ) {
+      throw new ForbiddenException('Durable session enrollment scope mismatch');
+    }
+    await this.coordinator.create(identity);
+  }
+
+  async queueProviderSend(input: ProviderOutboxDto): Promise<void> {
+    const snapshot = await this.coordinator.snapshot(input.sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    await this.coordinator.enqueueOutbox({
+      sessionId: input.sessionId,
+      idempotencyKey: input.idempotencyKey,
+      correlationId: input.correlationId,
+      channelId: input.context.channelId,
+      kind: 'provider.send',
+      content: input.content,
+    });
+  }
+
+  async dispatchProviderOutbox(sessionId: string, input: ProviderOutboxDto): Promise<void> {
+    if (sessionId !== input.sessionId) {
+      throw new ForbiddenException('Durable outbox session mismatch');
+    }
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    const pendingEntry = snapshot.outbox.find(
+      (entry): boolean => entry.idempotencyKey === input.idempotencyKey,
+    );
+    if (!pendingEntry) return;
+    // Validate immutable routing before claiming. A caller with a mismatched
+    // correlation/channel must not strand a pending external side effect.
+    this.assertOutboxScope(pendingEntry, input);
+    await this.coordinator.dispatchOutboxEntry(
+      sessionId,
+      input.idempotencyKey,
+      async (entry): Promise<void> => {
+        this.assertOutboxScope(entry, input);
+        await this.runtimeProviders.sendMessage(
+          snapshot.identity.providerId,
+          snapshot.identity.runtimeSessionId,
+          { content: entry.content, idempotencyKey: entry.idempotencyKey },
+          input.context,
+        );
+      },
+    );
+  }
+
+  /** Read durable identity/state only after deriving and checking the server-side actor scope. */
+  async getSnapshot(sessionId: string, context: RuntimeProviderRequestContext) {
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, {
+      sessionId,
+      content: '',
+      idempotencyKey: 'read-only',
+      correlationId: context.correlationId,
+      context,
+    });
+    return snapshot;
+  }
+
+  /** Startup/recovery-only path; normal queue/dispatch methods never requeue live work. */
+  async recoverProviderSession(sessionId: string, input: ProviderOutboxDto): Promise<void> {
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    await this.coordinator.recover(sessionId);
+  }
+
+  private assertOutboxScope(
+    entry: { kind: string; correlationId: string; channelId: string },
+    input: ProviderOutboxDto,
+  ): void {
+    if (
+      entry.kind !== 'provider.send' ||
+      entry.correlationId !== input.correlationId ||
+      entry.channelId !== input.context.channelId
+    ) {
+      throw new ForbiddenException('Durable outbox scope or correlation mismatch');
+    }
+  }
+
+  private assertScope(ownerId: string, tenantId: string, input: ProviderOutboxDto): void {
+    if (
+      input.context.actorScope.userId !== ownerId ||
+      input.context.actorScope.tenantId !== tenantId ||
+      input.context.correlationId !== input.correlationId
+    ) {
+      throw new ForbiddenException('Durable session scope or correlation mismatch');
+    }
+  }
+}

apps/gateway/src/agent/hermes-runtime-reachability.e2e.test.ts

@@ -0,0 +1,176 @@
+import 'reflect-metadata';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { Global, Module } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { HermesRuntimeProvider } from '@mosaicstack/agent';
+import { AgentModule } from './agent.module.js';
+import { AUTH } from '../auth/auth.tokens.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { BRAIN } from '../brain/brain.tokens.js';
+import { DB } from '../database/database.module.js';
+import { CoordModule } from '../coord/coord.module.js';
+import { McpClientModule } from '../mcp-client/mcp-client.module.js';
+import { SkillsModule } from '../skills/skills.module.js';
+import { GCModule } from '../gc/gc.module.js';
+import { LogModule } from '../log/log.module.js';
+import { CommandsModule } from '../commands/commands.module.js';
+import {
+  AGENT_RUNTIME_PROVIDER_REGISTRY,
+  RUNTIME_APPROVAL_VERIFIER,
+  RUNTIME_PROVIDER_AUDIT_SINK,
+  RuntimeProviderAuditService,
+} from './runtime-provider-registry.service.js';
+import { DurableSessionService } from './durable-session.service.js';
+import { DurableSessionRepository } from './durable-session.repository.js';
+import { AgentService } from './agent.service.js';
+import { ProviderService } from './provider.service.js';
+import { ProviderCredentialsService } from './provider-credentials.service.js';
+import { RoutingService } from './routing.service.js';
+import { RoutingEngineService } from './routing/routing-engine.service.js';
+import { SkillLoaderService } from './skill-loader.service.js';
+
+const authenticatedUser = { id: 'operator-1', tenantId: 'tenant-1' };
+
+@Module({})
+class EmptyAgentDependencyModule {}
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: AUTH,
+      useValue: {
+        api: {
+          getSession: vi.fn(async ({ headers }: { headers: Headers }) =>
+            headers.get('cookie') === 'session=trusted'
+              ? { user: authenticatedUser, session: { id: 'session-1' } }
+              : null,
+          ),
+        },
+      },
+    },
+    AuthGuard,
+    { provide: BRAIN, useValue: {} },
+    { provide: DB, useValue: {} },
+  ],
+  exports: [AUTH, AuthGuard, BRAIN, DB],
+})
+class AuthenticatedRequestModule {}
+
+/**
+ * This is deliberately an HTTP test rather than a controller unit test: it
+ * exercises AgentModule's actual provider factory, Nest DI, and AuthGuard.
+ */
+describe('Hermes runtime provider reachability', (): void => {
+  let app: NestFastifyApplication | undefined;
+
+  beforeAll(async (): Promise<void> => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const moduleRef = await Test.createTestingModule({
+      imports: [AuthenticatedRequestModule, AgentModule],
+    })
+      .overrideModule(CoordModule)
+      .useModule(EmptyAgentDependencyModule)
+      .overrideModule(McpClientModule)
+      .useModule(EmptyAgentDependencyModule)
+      .overrideModule(SkillsModule)
+      .useModule(EmptyAgentDependencyModule)
+      .overrideModule(GCModule)
+      .useModule(EmptyAgentDependencyModule)
+      .overrideModule(LogModule)
+      .useModule(EmptyAgentDependencyModule)
+      .overrideModule(CommandsModule)
+      .useModule(EmptyAgentDependencyModule)
+      .overrideProvider(RuntimeProviderAuditService)
+      .useValue({ record: vi.fn().mockResolvedValue(undefined) })
+      .overrideProvider(RUNTIME_PROVIDER_AUDIT_SINK)
+      .useValue({ record: vi.fn().mockResolvedValue(undefined) })
+      .overrideProvider(RUNTIME_APPROVAL_VERIFIER)
+      .useValue({ consume: vi.fn().mockResolvedValue(false) })
+      .overrideProvider(DurableSessionService)
+      .useValue({})
+      .overrideProvider(DurableSessionRepository)
+      .useValue({})
+      .overrideProvider(AgentService)
+      .useValue({})
+      .overrideProvider(ProviderService)
+      .useValue({})
+      .overrideProvider(ProviderCredentialsService)
+      .useValue({})
+      .overrideProvider(RoutingService)
+      .useValue({})
+      .overrideProvider(RoutingEngineService)
+      .useValue({})
+      .overrideProvider(SkillLoaderService)
+      .useValue({})
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  afterAll(async (): Promise<void> => {
+    await app?.close();
+  });
+
+  it('returns gateway denial responses from the actual guarded interaction routes', async (): Promise<void> => {
+    if (!app) throw new Error('Nest application did not initialize');
+
+    const attachDenied = await app.inject({
+      method: 'POST',
+      url: '/api/interaction/Nova/sessions/session-1/attach',
+      headers: { 'x-correlation-id': 'correlation-1' },
+      payload: { mode: 'read' },
+    });
+    expect(attachDenied.statusCode).toBe(401);
+
+    const sendDenied = await app.inject({
+      method: 'POST',
+      url: '/api/interaction/Nova/sessions/session-1/send',
+      headers: { cookie: 'session=trusted', 'x-correlation-id': 'correlation-1' },
+      payload: {},
+    });
+    expect(sendDenied.statusCode).toBe(403);
+    expect(sendDenied.json()).toMatchObject({
+      message: 'Content and idempotency key are required',
+    });
+
+    const stopDenied = await app.inject({
+      method: 'POST',
+      url: '/api/interaction/Nova/sessions/session-1/stop',
+      headers: { cookie: 'session=trusted', 'x-correlation-id': 'correlation-1' },
+      payload: {},
+    });
+    expect(stopDenied.statusCode).toBe(403);
+    expect(stopDenied.json()).toMatchObject({ message: 'Exact-action approval is required' });
+  });
+
+  it('requires authentication and reaches the Hermes provider registered by AgentModule', async (): Promise<void> => {
+    if (!app) throw new Error('Nest application did not initialize');
+    const registry = app.get(AGENT_RUNTIME_PROVIDER_REGISTRY);
+    expect(registry.get('runtime.hermes')).toBeInstanceOf(HermesRuntimeProvider);
+
+    const denied = await app.inject({
+      method: 'GET',
+      url: '/api/interaction/Nova/transitional-capabilities?provider=runtime.hermes',
+      headers: { 'x-correlation-id': 'correlation-1' },
+    });
+    expect(denied.statusCode).toBe(401);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/interaction/Nova/transitional-capabilities?provider=runtime.hermes',
+      headers: { cookie: 'session=trusted', 'x-correlation-id': 'correlation-1' },
+    });
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual([
+      { capability: 'kanban', status: 'unsupported' },
+      { capability: 'skills', status: 'unsupported' },
+      { capability: 'memory', status: 'unsupported' },
+      { capability: 'tools', status: 'unsupported' },
+      { capability: 'cron', status: 'unsupported' },
+    ]);
+  });
+});

apps/gateway/src/agent/hermes-runtime.transport.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest';
+import { GatewayHermesRuntimeTransport } from './hermes-runtime.transport.js';
+
+const scope = {
+  actorId: 'owner-1',
+  tenantId: 'tenant-1',
+  channelId: 'cli',
+  correlationId: 'correlation-1',
+};
+
+describe('GatewayHermesRuntimeTransport', () => {
+  it('preserves a configured path prefix and authenticates the concrete runtime request', async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue(new Response(JSON.stringify(['session.list']), { status: 200 }));
+    const transport = new GatewayHermesRuntimeTransport(
+      'https://runtime.example.test/hermes',
+      'test-service-token',
+      fetchFn,
+    );
+
+    await expect(transport.capabilities(scope)).resolves.toEqual(['session.list']);
+
+    expect(fetchFn).toHaveBeenCalledWith(
+      new URL('https://runtime.example.test/hermes/capabilities'),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          authorization: 'Bearer test-service-token',
+          'x-mosaic-channel-id': 'cli',
+        }),
+      }),
+    );
+  });
+
+  it('rejects non-loopback HTTP runtime endpoints before sending identity headers', async () => {
+    const fetchFn = vi.fn();
+    const transport = new GatewayHermesRuntimeTransport(
+      'http://runtime.example.test/hermes',
+      'test-service-token',
+      fetchFn,
+    );
+
+    await expect(transport.capabilities(scope)).rejects.toThrow('requires HTTPS');
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+});

apps/gateway/src/agent/hermes-runtime.transport.ts

@@ -0,0 +1,121 @@
+import type { HermesLegacySession, HermesRuntimeTransport } from '@mosaicstack/agent';
+import type {
+  RuntimeAttachHandle,
+  RuntimeAttachMode,
+  RuntimeMessage,
+  RuntimeScope,
+  RuntimeStreamEvent,
+} from '@mosaicstack/types';
+
+/** Concrete HTTP transport for a configured legacy Hermes runtime endpoint. */
+export class GatewayHermesRuntimeTransport implements HermesRuntimeTransport {
+  constructor(
+    private readonly baseUrl = process.env['MOSAIC_HERMES_RUNTIME_URL']?.trim(),
+    private readonly serviceToken = process.env['MOSAIC_HERMES_RUNTIME_TOKEN']?.trim(),
+    private readonly fetchFn: typeof fetch = fetch,
+  ) {}
+
+  async capabilities(scope: RuntimeScope): Promise<string[]> {
+    return this.request<string[]>('/capabilities', scope);
+  }
+
+  async health(scope: RuntimeScope): Promise<{ status: string; detail?: string }> {
+    return this.request<{ status: string; detail?: string }>('/health', scope);
+  }
+
+  async sessions(scope: RuntimeScope): Promise<HermesLegacySession[]> {
+    return this.request<HermesLegacySession[]>('/sessions', scope);
+  }
+
+  async *stream(
+    sessionId: string,
+    cursor: string | undefined,
+    scope: RuntimeScope,
+  ): AsyncIterable<RuntimeStreamEvent> {
+    const params = new URLSearchParams(cursor ? { cursor } : {});
+    const events = await this.request<RuntimeStreamEvent[]>(
+      `/sessions/${encodeURIComponent(sessionId)}/stream?${params.toString()}`,
+      scope,
+    );
+    yield* events;
+  }
+
+  async send(sessionId: string, message: RuntimeMessage, scope: RuntimeScope): Promise<void> {
+    await this.request(`/sessions/${encodeURIComponent(sessionId)}/messages`, scope, {
+      method: 'POST',
+      body: message,
+    });
+  }
+
+  async attach(
+    sessionId: string,
+    mode: RuntimeAttachMode,
+    scope: RuntimeScope,
+  ): Promise<RuntimeAttachHandle> {
+    return this.request<RuntimeAttachHandle>(
+      `/sessions/${encodeURIComponent(sessionId)}/attach`,
+      scope,
+      {
+        method: 'POST',
+        body: { mode },
+      },
+    );
+  }
+
+  async detach(attachmentId: string, scope: RuntimeScope): Promise<void> {
+    await this.request(`/attachments/${encodeURIComponent(attachmentId)}`, scope, {
+      method: 'DELETE',
+    });
+  }
+
+  async terminate(sessionId: string, approvalRef: string, scope: RuntimeScope): Promise<void> {
+    await this.request(`/sessions/${encodeURIComponent(sessionId)}/terminate`, scope, {
+      method: 'POST',
+      body: { approvalRef },
+    });
+  }
+
+  private async request<T>(
+    path: string,
+    scope: RuntimeScope,
+    init: { method?: string; body?: unknown } = {},
+  ): Promise<T> {
+    if (!this.baseUrl || !this.serviceToken) {
+      throw new Error(
+        'MOSAIC_HERMES_RUNTIME_URL and MOSAIC_HERMES_RUNTIME_TOKEN must configure Hermes transport',
+      );
+    }
+    const endpoint = new URL(this.baseUrl);
+    if (endpoint.protocol !== 'https:' && !isLoopbackHttp(endpoint)) {
+      throw new Error('Hermes runtime transport requires HTTPS outside loopback');
+    }
+    const response = await this.fetchFn(
+      new URL(path.replace(/^\//, ''), `${endpoint.toString().replace(/\/$/, '')}/`),
+      {
+        method: init.method ?? 'GET',
+        headers: {
+          accept: 'application/json',
+          authorization: `Bearer ${this.serviceToken}`,
+          'x-mosaic-actor-id': scope.actorId,
+          'x-mosaic-tenant-id': scope.tenantId,
+          'x-mosaic-channel-id': scope.channelId,
+          'x-correlation-id': scope.correlationId,
+          ...(init.body ? { 'content-type': 'application/json' } : {}),
+        },
+        ...(init.body ? { body: JSON.stringify(init.body) } : {}),
+      },
+    );
+    if (!response.ok) throw new Error(`Hermes runtime request failed: ${response.status}`);
+    if (response.status === 204) return undefined as T;
+    return (await response.json()) as T;
+  }
+}
+
+function isLoopbackHttp(endpoint: URL): boolean {
+  return (
+    endpoint.protocol === 'http:' &&
+    (endpoint.hostname === 'localhost' ||
+      endpoint.hostname === '127.0.0.1' ||
+      endpoint.hostname === '::1')
+  );
+}

apps/gateway/src/agent/interaction.controller.test.ts

@@ -0,0 +1,263 @@
+import { createGatewayRuntimeProviderRegistry } from './agent.module.js';
+import { firstValueFrom } from 'rxjs';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  RuntimeApprovalDeniedError,
+  RuntimeProviderService,
+} from './runtime-provider-registry.service.js';
+import { RuntimeApprovalDeniedFilter } from './runtime-approval-denied.filter.js';
+import { InteractionController } from './interaction.controller.js';
+
+describe('InteractionController', (): void => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('maps a denied runtime approval to Fastify HTTP 403', () => {
+    const send = vi.fn();
+    const status = vi.fn().mockReturnValue({ send });
+    const response = { status };
+    const host = { switchToHttp: () => ({ getResponse: () => response }) };
+
+    new RuntimeApprovalDeniedFilter().catch(new RuntimeApprovalDeniedError(), host as never);
+
+    expect(status).toHaveBeenCalledWith(403);
+    expect(send).toHaveBeenCalledWith({
+      statusCode: 403,
+      message: 'Runtime termination approval denied',
+    });
+  });
+
+  it('honors a differently named configured instance without a code change', async () => {
+    const prior = process.env['MOSAIC_AGENT_NAME'];
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const runtime = { listSessions: vi.fn().mockResolvedValue([]) };
+    const controller = new InteractionController(runtime as never, {} as never);
+
+    await expect(
+      controller.sessions('Nova', 'fleet', { id: 'owner', tenantId: 'team' }, 'corr-1'),
+    ).resolves.toEqual([]);
+    await expect(
+      controller.sessions('Other', 'fleet', { id: 'owner', tenantId: 'team' }, 'corr-1'),
+    ).rejects.toThrow('Interaction agent is not configured');
+
+    if (prior === undefined) delete process.env['MOSAIC_AGENT_NAME'];
+    else process.env['MOSAIC_AGENT_NAME'] = prior;
+  });
+
+  it('reaches the registered Hermes provider through the authenticated transitional matrix route', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const registry = createGatewayRuntimeProviderRegistry();
+    const runtime = new RuntimeProviderService(
+      registry,
+      { record: vi.fn().mockResolvedValue(undefined) },
+      { consume: vi.fn().mockResolvedValue(false) },
+    );
+    const controller = new InteractionController(runtime, {} as never);
+
+    await expect(
+      controller.transitionalCapabilities(
+        'Nova',
+        'runtime.hermes',
+        { id: 'owner', tenantId: 'team' },
+        'corr-1',
+      ),
+    ).resolves.toEqual([
+      { capability: 'kanban', status: 'unsupported' },
+      { capability: 'skills', status: 'unsupported' },
+      { capability: 'memory', status: 'unsupported' },
+      { capability: 'tools', status: 'unsupported' },
+      { capability: 'cron', status: 'unsupported' },
+    ]);
+  });
+
+  it('rejects a request without the non-simple correlation header', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const controller = new InteractionController({ listSessions: vi.fn() } as never, {} as never);
+
+    await expect(controller.sessions('Nova', 'fleet', { id: 'owner' })).rejects.toThrow(
+      'X-Correlation-Id is required',
+    );
+  });
+
+  it('enrolls a visible runtime session under the cross-surface conversation handle', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const runtime = {
+      listSessions: vi.fn().mockResolvedValue([{ id: 'runtime-1' }]),
+    };
+    const durable = { enroll: vi.fn().mockResolvedValue(undefined) };
+    const controller = new InteractionController(runtime as never, durable as never);
+
+    await expect(
+      controller.enroll(
+        'Nova',
+        'conversation-1',
+        { providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+        { id: 'owner', tenantId: 'team' },
+        'corr-1',
+      ),
+    ).resolves.toEqual({ status: 'enrolled', sessionId: 'conversation-1' });
+    expect(durable.enroll).toHaveBeenCalledWith(
+      {
+        agentName: 'Nova',
+        sessionId: 'conversation-1',
+        tenantId: 'team',
+        ownerId: 'owner',
+        providerId: 'fleet',
+        runtimeSessionId: 'runtime-1',
+      },
+      expect.objectContaining({ correlationId: 'corr-1' }),
+    );
+  });
+
+  it('rejects an invalid attach mode before invoking a provider', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const controller = new InteractionController({ attach: vi.fn() } as never, {} as never);
+
+    await expect(
+      controller.attach('Nova', 'durable-1', { mode: 'write' as never }, { id: 'owner' }, 'corr-1'),
+    ).rejects.toThrow('Interaction attach mode is invalid');
+  });
+
+  it('resumes a durable session by attaching and streaming its runtime events', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const runtimeEvent = {
+      type: 'message.delta' as const,
+      sessionId: 'runtime-1',
+      cursor: 'cursor-1',
+      occurredAt: '2026-07-13T00:00:00.000Z',
+      content: 'resumed',
+    };
+    const runtime = {
+      attach: vi.fn().mockResolvedValue({ attachmentId: 'attach-1', sessionId: 'runtime-1' }),
+      streamSession: vi.fn(async function* () {
+        yield runtimeEvent;
+      }),
+    };
+    const durable = {
+      getSnapshot: vi.fn().mockResolvedValue({
+        identity: { agentName: 'Nova', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+      }),
+    };
+    const controller = new InteractionController(runtime as never, durable as never);
+
+    await controller.attach('Nova', 'conversation-1', { mode: 'read' }, { id: 'owner' }, 'corr-1');
+    await expect(
+      firstValueFrom(
+        controller.stream('Nova', 'conversation-1', undefined, { id: 'owner' }, 'corr-1'),
+      ),
+    ).resolves.toEqual({ data: runtimeEvent });
+
+    expect(runtime.attach).toHaveBeenCalledWith(
+      'fleet',
+      'runtime-1',
+      'read',
+      expect.objectContaining({ correlationId: 'corr-1' }),
+    );
+    expect(runtime.streamSession).toHaveBeenCalledWith(
+      'fleet',
+      'runtime-1',
+      undefined,
+      expect.objectContaining({ correlationId: 'corr-1' }),
+    );
+  });
+
+  it('does not create a runtime stream after the SSE subscriber disconnects during snapshot lookup', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    let resolveSnapshot!: (value: { identity: Record<string, string> }) => void;
+    const snapshot = new Promise<{ identity: Record<string, string> }>((resolve) => {
+      resolveSnapshot = resolve;
+    });
+    const runtime = { streamSession: vi.fn() };
+    const durable = { getSnapshot: vi.fn().mockReturnValue(snapshot) };
+    const controller = new InteractionController(runtime as never, durable as never);
+
+    const subscription = controller
+      .stream('Nova', 'conversation-1', undefined, { id: 'owner' }, 'corr-1')
+      .subscribe();
+    subscription.unsubscribe();
+    resolveSnapshot({
+      identity: { agentName: 'Nova', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(runtime.streamSession).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['wrong actor', { getSnapshot: vi.fn().mockRejectedValue(new Error('scope mismatch')) }],
+    [
+      'session-agent mismatch',
+      {
+        getSnapshot: vi.fn().mockResolvedValue({
+          identity: { agentName: 'Other', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+        }),
+      },
+    ],
+  ])('denies a CLI stop for %s', async (_reason, durable) => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const runtime = { terminate: vi.fn().mockResolvedValue(undefined) };
+    const controller = new InteractionController(runtime as never, durable as never);
+
+    await expect(
+      controller.stop(
+        'Nova',
+        'durable-1',
+        { approvalRef: 'approval-1' },
+        { id: 'owner' },
+        'corr-1',
+      ),
+    ).rejects.toBeDefined();
+    expect(runtime.terminate).not.toHaveBeenCalled();
+  });
+
+  it('surfaces a denied runtime approval to the CLI interaction surface', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const runtime = {
+      terminate: vi.fn().mockRejectedValue(new Error('Runtime termination approval denied')),
+    };
+    const durable = {
+      getSnapshot: vi.fn().mockResolvedValue({
+        identity: { agentName: 'Nova', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+      }),
+    };
+    const controller = new InteractionController(runtime as never, durable as never);
+
+    await expect(
+      controller.stop(
+        'Nova',
+        'durable-1',
+        { approvalRef: 'approval-1' },
+        { id: 'owner' },
+        'corr-1',
+      ),
+    ).rejects.toThrow('Runtime termination approval denied');
+  });
+
+  it('uses the durable session identity and runtime registry for an approved stop', async () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+    const runtime = { terminate: vi.fn().mockResolvedValue(undefined) };
+    const durable = {
+      getSnapshot: vi.fn().mockResolvedValue({
+        identity: { agentName: 'Nova', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+      }),
+    };
+    const controller = new InteractionController(runtime as never, durable as never);
+
+    await controller.stop(
+      'Nova',
+      'durable-1',
+      { approvalRef: 'approval-1' },
+      { id: 'owner' },
+      'corr-1',
+    );
+
+    expect(runtime.terminate).toHaveBeenCalledWith(
+      'fleet',
+      'runtime-1',
+      'approval-1',
+      expect.objectContaining({
+        correlationId: 'corr-1',
+        actorScope: { userId: 'owner', tenantId: 'owner' },
+      }),
+    );
+  });
+});

apps/gateway/src/agent/interaction.controller.ts

@@ -0,0 +1,293 @@
+import {
+  Body,
+  Controller,
+  ForbiddenException,
+  Get,
+  Headers,
+  Sse,
+  Inject,
+  Param,
+  Post,
+  Query,
+  UseGuards,
+  UseFilters,
+} from '@nestjs/common';
+import type { RuntimeAttachMode, RuntimeStreamEvent } from '@mosaicstack/types';
+import { Observable } from 'rxjs';
+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 { DurableSessionService } from './durable-session.service.js';
+import { RuntimeApprovalDeniedFilter } from './runtime-approval-denied.filter.js';
+import {
+  RuntimeProviderService,
+  type RuntimeProviderRequestContext,
+} from './runtime-provider-registry.service.js';
+
+/**
+ * Authenticated HTTP boundary for operator interaction clients. Identity is
+ * selected from deployment configuration, never a client-side command name.
+ */
+@Controller('api/interaction/:agentName')
+@UseGuards(AuthGuard)
+@UseFilters(RuntimeApprovalDeniedFilter)
+export class InteractionController {
+  constructor(
+    @Inject(RuntimeProviderService) private readonly runtime: RuntimeProviderService,
+    @Inject(DurableSessionService) private readonly durable: DurableSessionService,
+  ) {}
+
+  @Get('sessions')
+  async sessions(
+    @Param('agentName') agentName: string,
+    @Query('provider') providerId: string,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    return this.runtime.listSessions(
+      this.requiredProvider(providerId),
+      this.context(user, correlationId),
+    );
+  }
+
+  @Get('transitional-capabilities')
+  async transitionalCapabilities(
+    @Param('agentName') agentName: string,
+    @Query('provider') providerId: string,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    return this.runtime.transitionalCapabilityMatrix(
+      this.requiredProvider(providerId),
+      this.context(user, correlationId),
+    );
+  }
+
+  @Get('tree')
+  async tree(
+    @Param('agentName') agentName: string,
+    @Query('provider') providerId: string,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    return this.runtime.getSessionTree(
+      this.requiredProvider(providerId),
+      this.context(user, correlationId),
+    );
+  }
+
+  /**
+   * Bind an existing, authorized runtime session to the stable conversation ID.
+   * This is the lifecycle boundary where both runtime identifiers are known.
+   */
+  @Post('sessions/:sessionId/enroll')
+  async enroll(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @Body() body: { providerId?: string; runtimeSessionId?: string } = {},
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    const providerId = this.requiredProvider(body.providerId ?? '');
+    const runtimeSessionId = body.runtimeSessionId?.trim();
+    if (!runtimeSessionId) throw new ForbiddenException('Runtime session identity is required');
+    const context = this.context(user, correlationId);
+    const sessions = await this.runtime.listSessions(providerId, context);
+    if (!sessions.some((session): boolean => session.id === runtimeSessionId)) {
+      throw new ForbiddenException('Runtime session is not visible to this actor');
+    }
+    await this.durable.enroll(
+      {
+        agentName,
+        sessionId,
+        tenantId: context.actorScope.tenantId,
+        ownerId: context.actorScope.userId,
+        providerId,
+        runtimeSessionId,
+      },
+      context,
+    );
+    return { status: 'enrolled', sessionId };
+  }
+
+  @Post('sessions/:sessionId/attach')
+  async attach(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @Body() body: { mode?: RuntimeAttachMode } = {},
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    const context = this.context(user, correlationId);
+    const mode = body.mode ?? 'read';
+    if (mode !== 'read' && mode !== 'control') {
+      throw new ForbiddenException('Interaction attach mode is invalid');
+    }
+    const snapshot = await this.durable.getSnapshot(sessionId, context);
+    this.assertSessionAgent(snapshot.identity.agentName, agentName);
+    return this.runtime.attach(
+      snapshot.identity.providerId,
+      snapshot.identity.runtimeSessionId,
+      mode,
+      context,
+    );
+  }
+
+  @Sse('sessions/:sessionId/stream')
+  stream(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @Query('cursor') cursor: string | undefined,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ): Observable<{ data: RuntimeStreamEvent }> {
+    this.assertConfiguredAgent(agentName);
+    const context = this.context(user, correlationId);
+    return new Observable((subscriber) => {
+      let iterator: AsyncIterator<RuntimeStreamEvent> | undefined;
+      let cancelled = false;
+      void (async (): Promise<void> => {
+        try {
+          const snapshot = await this.durable.getSnapshot(sessionId, context);
+          if (cancelled || subscriber.closed) return;
+          this.assertSessionAgent(snapshot.identity.agentName, agentName);
+          iterator = this.runtime
+            .streamSession(
+              snapshot.identity.providerId,
+              snapshot.identity.runtimeSessionId,
+              cursor?.trim() || undefined,
+              context,
+            )
+            [Symbol.asyncIterator]();
+          if (cancelled || subscriber.closed) {
+            await iterator.return?.();
+            return;
+          }
+          while (!cancelled && !subscriber.closed) {
+            const next = await iterator.next();
+            if (next.done || cancelled || subscriber.closed) break;
+            subscriber.next({ data: next.value });
+          }
+          if (!subscriber.closed) subscriber.complete();
+        } catch (error: unknown) {
+          if (!subscriber.closed) subscriber.error(error);
+        }
+      })();
+      return (): void => {
+        cancelled = true;
+        void iterator?.return?.();
+      };
+    });
+  }
+
+  @Post('sessions/:sessionId/send')
+  async send(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @Body() body: { content?: string; idempotencyKey?: string } = {},
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    if (!body.content?.trim() || !body.idempotencyKey?.trim()) {
+      throw new ForbiddenException('Content and idempotency key are required');
+    }
+    const context = this.context(user, correlationId);
+    const snapshot = await this.durable.getSnapshot(sessionId, context);
+    this.assertSessionAgent(snapshot.identity.agentName, agentName);
+    const input = {
+      sessionId,
+      content: body.content,
+      idempotencyKey: body.idempotencyKey,
+      correlationId: context.correlationId,
+      context,
+    };
+    await this.durable.queueProviderSend(input);
+    await this.durable.dispatchProviderOutbox(sessionId, input);
+    return { status: 'queued', sessionId };
+  }
+
+  @Post('sessions/:sessionId/stop')
+  async stop(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @Body() body: { approvalRef?: string } = {},
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    if (!body.approvalRef?.trim())
+      throw new ForbiddenException('Exact-action approval is required');
+    const context = this.context(user, correlationId);
+    const snapshot = await this.durable.getSnapshot(sessionId, context);
+    this.assertSessionAgent(snapshot.identity.agentName, agentName);
+    await this.runtime.terminate(
+      snapshot.identity.providerId,
+      snapshot.identity.runtimeSessionId,
+      body.approvalRef,
+      context,
+    );
+    return { status: 'stopped', sessionId };
+  }
+
+  @Post('sessions/:sessionId/recover')
+  async recover(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    const context = this.context(user, correlationId);
+    const snapshot = await this.durable.getSnapshot(sessionId, context);
+    this.assertSessionAgent(snapshot.identity.agentName, agentName);
+    await this.durable.recoverProviderSession(sessionId, {
+      sessionId,
+      content: '',
+      idempotencyKey: `recovery:${context.correlationId}`,
+      correlationId: context.correlationId,
+      context,
+    });
+    return { status: 'recovered', sessionId };
+  }
+
+  private context(
+    user: AuthenticatedUserLike,
+    correlationId?: string,
+  ): RuntimeProviderRequestContext {
+    const requestCorrelationId = correlationId?.trim();
+    // This non-simple request header is mandatory for mutations. Browser
+    // cross-origin requests cannot set it without a CORS preflight, and the
+    // gateway's allowlist rejects untrusted origins before the handler runs.
+    if (!requestCorrelationId) {
+      throw new ForbiddenException('X-Correlation-Id is required');
+    }
+    return {
+      actorScope: scopeFromUser(user),
+      channelId: 'cli',
+      correlationId: requestCorrelationId,
+    };
+  }
+
+  private assertConfiguredAgent(agentName: string): void {
+    const configured = process.env['MOSAIC_AGENT_NAME']?.trim();
+    if (!configured || configured !== agentName) {
+      throw new ForbiddenException('Interaction agent is not configured for this request');
+    }
+  }
+
+  private assertSessionAgent(sessionAgentName: string, agentName: string): void {
+    if (sessionAgentName !== agentName)
+      throw new ForbiddenException('Interaction session identity mismatch');
+  }
+
+  private requiredProvider(providerId: string): string {
+    if (!providerId?.trim()) throw new ForbiddenException('Runtime provider is required');
+    return providerId;
+  }
+}

apps/gateway/src/agent/provider.service.ts

@@ -107,8 +107,7 @@ export class ProviderService implements OnModuleInit, OnModuleDestroy {
    * Interval is configurable via PROVIDER_HEALTH_INTERVAL env (seconds, default 60).
    */
   private startHealthCheckScheduler(): void {
-    const intervalSecs =
-      parseInt(process.env['PROVIDER_HEALTH_INTERVAL'] ?? '', 10) || DEFAULT_HEALTH_INTERVAL_SECS;
+    const intervalSecs = this.effectiveHealthCheckIntervalSecs();
     const intervalMs = intervalSecs * 1000;
 
     // Run an initial check immediately (non-blocking)
@@ -176,6 +175,28 @@ export class ProviderService implements OnModuleInit, OnModuleDestroy {
     });
   }
 
+  /**
+   * Returns the effective provider operational policy without credentials,
+   * endpoints, request content, or provider error details.
+   */
+  getEffectivePolicyStatus(): {
+    healthCheckIntervalSecs: number;
+    configuredProviders: string[];
+    availableModelCount: number;
+  } {
+    return {
+      healthCheckIntervalSecs: this.effectiveHealthCheckIntervalSecs(),
+      configuredProviders: this.adapters.map((adapter) => adapter.name),
+      availableModelCount: this.registry?.getAvailable().length ?? 0,
+    };
+  }
+
+  private effectiveHealthCheckIntervalSecs(): number {
+    return (
+      parseInt(process.env['PROVIDER_HEALTH_INTERVAL'] ?? '', 10) || DEFAULT_HEALTH_INTERVAL_SECS
+    );
+  }
+
   // ---------------------------------------------------------------------------
   // Adapter-pattern API
   // ---------------------------------------------------------------------------

apps/gateway/src/agent/providers.controller.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ProvidersController } from './providers.controller.js';
+
+describe('ProvidersController operational status', (): void => {
+  it('reports provider latency and effective policy without exposing provider error details', (): void => {
+    const providerService = {
+      getProvidersHealth: vi.fn(() => [
+        {
+          name: 'fleet',
+          status: 'down',
+          latencyMs: 42,
+          lastChecked: '2026-07-12T00:00:00.000Z',
+          modelCount: 0,
+          error: 'credential-canary=secret-value',
+        },
+      ]),
+      getEffectivePolicyStatus: vi.fn(() => ({
+        healthCheckIntervalSecs: 60,
+        configuredProviders: ['fleet'],
+        availableModelCount: 0,
+      })),
+    };
+    const controller = new ProvidersController(providerService as never, {} as never, {} as never);
+
+    const status = controller.status();
+
+    expect(status).toEqual({
+      providers: [
+        {
+          name: 'fleet',
+          status: 'down',
+          latencyMs: 42,
+          lastChecked: '2026-07-12T00:00:00.000Z',
+          modelCount: 0,
+          errorCode: 'provider_unavailable',
+        },
+      ],
+      effectivePolicy: {
+        healthCheckIntervalSecs: 60,
+        configuredProviders: ['fleet'],
+        availableModelCount: 0,
+      },
+    });
+    expect(JSON.stringify(status)).not.toContain('secret-value');
+  });
+});

apps/gateway/src/agent/providers.controller.ts

@@ -33,7 +33,20 @@ export class ProvidersController {
 
   @Get('health')
   health() {
-    return { providers: this.providerService.getProvidersHealth() };
+    return { providers: this.safeProviderHealth() };
+  }
+
+  /**
+   * Safe operational status for troubleshooting and readiness checks. Provider
+   * errors are reduced to a stable code so credentials and remote responses
+   * cannot leak through this endpoint.
+   */
+  @Get('status')
+  status() {
+    return {
+      providers: this.safeProviderHealth(),
+      effectivePolicy: this.providerService.getEffectivePolicyStatus(),
+    };
   }
 
   @Post('test')
@@ -51,6 +64,13 @@ export class ProvidersController {
     return this.routingService.rank(criteria);
   }
 
+  private safeProviderHealth() {
+    return this.providerService.getProvidersHealth().map(({ error, ...provider }) => ({
+      ...provider,
+      ...(error ? { errorCode: 'provider_unavailable' } : {}),
+    }));
+  }
+
   // ── Credential CRUD ──────────────────────────────────────────────────────
 
   /**

apps/gateway/src/agent/runtime-approval-denied.filter.ts

@@ -0,0 +1,13 @@
+import { Catch, type ArgumentsHost, type ExceptionFilter } from '@nestjs/common';
+import { RuntimeApprovalDeniedError } from './runtime-provider-registry.service.js';
+
+/** Maps a consumed/missing runtime approval to a stable HTTP authorization response. */
+@Catch(RuntimeApprovalDeniedError)
+export class RuntimeApprovalDeniedFilter implements ExceptionFilter {
+  catch(_exception: RuntimeApprovalDeniedError, host: ArgumentsHost): void {
+    const response = host.switchToHttp().getResponse<{
+      status(code: number): { send(body: { statusCode: number; message: string }): void };
+    }>();
+    response.status(403).send({ statusCode: 403, message: 'Runtime termination approval denied' });
+  }
+}

apps/gateway/src/agent/runtime-provider-registry.service.ts

@@ -0,0 +1,500 @@
+import { ForbiddenException, Inject, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { AgentRuntimeProviderRegistry } from '@mosaicstack/agent';
+import {
+  createRuntimeAuditLogEntry,
+  type LogService,
+  type RuntimeAuditErrorCode,
+} from '@mosaicstack/log';
+import type {
+  AgentRuntimeProvider,
+  RuntimeAttachHandle,
+  RuntimeAttachMode,
+  RuntimeCapability,
+  RuntimeCapabilitySet,
+  RuntimeHealth,
+  RuntimeMessage,
+  RuntimeScope,
+  RuntimeSession,
+  RuntimeSessionTree,
+  RuntimeStreamEvent,
+  TransitionalCapabilityInventoryEntry,
+  TransitionalCapabilityInventoryProvider,
+} from '@mosaicstack/types';
+import type { ActorTenantScope } from '../auth/session-scope.js';
+import { LOG_SERVICE } from '../log/log.tokens.js';
+
+export const AGENT_RUNTIME_PROVIDER_REGISTRY = Symbol('AGENT_RUNTIME_PROVIDER_REGISTRY');
+export const RUNTIME_PROVIDER_AUDIT_SINK = Symbol('RUNTIME_PROVIDER_AUDIT_SINK');
+export const RUNTIME_APPROVAL_VERIFIER = Symbol('RUNTIME_APPROVAL_VERIFIER');
+
+export type RuntimeProviderOperation =
+  | RuntimeCapability
+  | 'runtime.capabilities'
+  | 'runtime.health'
+  | 'runtime.transitional-capabilities';
+export type RuntimeProviderAuditOutcome = 'requested' | 'succeeded' | 'denied' | 'failed';
+
+/** Trusted server-side context only; it intentionally excludes client-provided identity fields. */
+export interface RuntimeProviderRequestContext {
+  actorScope: ActorTenantScope;
+  channelId: string;
+  correlationId: string;
+}
+
+/** Metadata-only audit record. Message bodies, idempotency keys, and approval refs are excluded. */
+export interface RuntimeAuditEvent {
+  providerId: string;
+  operation: RuntimeProviderOperation;
+  outcome: RuntimeProviderAuditOutcome;
+  actorId: string;
+  tenantId: string;
+  channelId: string;
+  correlationId: string;
+  resourceId?: string;
+  durationMs?: number;
+  errorCode?: RuntimeAuditErrorCode;
+}
+
+export interface RuntimeAuditSink {
+  record(event: RuntimeAuditEvent): Promise<void>;
+}
+
+/** Exact action shape that a durable approval implementation must consume once. */
+export interface RuntimeTerminationAction {
+  providerId: string;
+  sessionId: string;
+  actorId: string;
+  tenantId: string;
+  channelId: string;
+  correlationId: string;
+  agentName: string;
+}
+
+export interface RuntimeApprovalVerifier {
+  consume(approvalRef: string, action: RuntimeTerminationAction): Promise<boolean>;
+}
+
+function isTransitionalInventoryProvider(
+  provider: AgentRuntimeProvider,
+): provider is AgentRuntimeProvider & TransitionalCapabilityInventoryProvider {
+  return (
+    typeof (provider as Partial<TransitionalCapabilityInventoryProvider>)
+      .transitionalCapabilityMatrix === 'function'
+  );
+}
+
+function configuredAgentName(): string {
+  const agentName = process.env['MOSAIC_AGENT_NAME']?.trim();
+  if (!agentName) throw new RuntimeApprovalDeniedError();
+  return agentName;
+}
+
+export class RuntimeApprovalDeniedError extends Error {
+  constructor() {
+    super('Runtime termination approval denied');
+  }
+}
+
+/**
+ * The default denies all runtime termination until a durable, exact-action
+ * approval implementation is configured. This is safer than a permissive stub.
+ */
+@Injectable()
+export class DenyRuntimeApprovalVerifier implements RuntimeApprovalVerifier {
+  async consume(_approvalRef: string, _action: RuntimeTerminationAction): Promise<boolean> {
+    return false;
+  }
+}
+
+/**
+ * Temporary metadata-only audit sink. M1 observability can replace this token
+ * with a durable audit writer without changing provider call sites.
+ */
+@Injectable()
+export class RuntimeProviderAuditService implements RuntimeAuditSink {
+  private readonly logger = new Logger(RuntimeProviderAuditService.name);
+
+  constructor(@Inject(LOG_SERVICE) private readonly logService: LogService) {}
+
+  async record(event: RuntimeAuditEvent): Promise<void> {
+    const entry = createRuntimeAuditLogEntry(event);
+    await this.logService.logs.ingest(entry);
+    this.logger.log(JSON.stringify({ event: entry.content, metadata: entry.metadata }));
+  }
+}
+
+@Injectable()
+export class RuntimeProviderService {
+  private readonly logger = new Logger(RuntimeProviderService.name);
+
+  constructor(
+    @Inject(AGENT_RUNTIME_PROVIDER_REGISTRY)
+    private readonly registry: AgentRuntimeProviderRegistry,
+    @Inject(RUNTIME_PROVIDER_AUDIT_SINK)
+    private readonly audit: RuntimeAuditSink,
+    @Inject(RUNTIME_APPROVAL_VERIFIER)
+    private readonly approvals: RuntimeApprovalVerifier,
+  ) {}
+
+  async capabilities(
+    providerId: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<RuntimeCapabilitySet> {
+    return this.execute(
+      providerId,
+      'runtime.capabilities',
+      undefined,
+      undefined,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeCapabilitySet> =>
+        provider.capabilities(scope),
+    );
+  }
+
+  async health(providerId: string, context: RuntimeProviderRequestContext): Promise<RuntimeHealth> {
+    return this.execute(
+      providerId,
+      'runtime.health',
+      undefined,
+      undefined,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeHealth> =>
+        provider.health(scope),
+    );
+  }
+
+  async transitionalCapabilityMatrix(
+    providerId: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<TransitionalCapabilityInventoryEntry[]> {
+    return this.execute(
+      providerId,
+      'runtime.transitional-capabilities',
+      undefined,
+      undefined,
+      context,
+      async (provider: AgentRuntimeProvider, scope: RuntimeScope) => {
+        if (!isTransitionalInventoryProvider(provider)) {
+          throw new NotFoundException('Runtime provider has no transitional capability inventory');
+        }
+        return provider.transitionalCapabilityMatrix(scope);
+      },
+    );
+  }
+
+  async listSessions(
+    providerId: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<RuntimeSession[]> {
+    return this.execute(
+      providerId,
+      'session.list',
+      'session.list',
+      undefined,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeSession[]> =>
+        provider.listSessions(scope),
+    );
+  }
+
+  async getSessionTree(
+    providerId: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<RuntimeSessionTree[]> {
+    return this.execute(
+      providerId,
+      'session.tree',
+      'session.tree',
+      undefined,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeSessionTree[]> =>
+        provider.getSessionTree(scope),
+    );
+  }
+
+  streamSession(
+    providerId: string,
+    sessionId: string,
+    cursor: string | undefined,
+    context: RuntimeProviderRequestContext,
+  ): AsyncIterable<RuntimeStreamEvent> {
+    return this.stream(
+      providerId,
+      'session.stream',
+      'session.stream',
+      sessionId,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): AsyncIterable<RuntimeStreamEvent> =>
+        provider.streamSession(sessionId, cursor, scope),
+    );
+  }
+
+  async sendMessage(
+    providerId: string,
+    sessionId: string,
+    message: RuntimeMessage,
+    context: RuntimeProviderRequestContext,
+  ): Promise<void> {
+    await this.execute(
+      providerId,
+      'session.send',
+      'session.send',
+      sessionId,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<void> =>
+        provider.sendMessage(sessionId, message, scope),
+    );
+  }
+
+  async attach(
+    providerId: string,
+    sessionId: string,
+    mode: RuntimeAttachMode,
+    context: RuntimeProviderRequestContext,
+  ): Promise<RuntimeAttachHandle> {
+    return this.execute(
+      providerId,
+      'session.attach',
+      'session.attach',
+      sessionId,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeAttachHandle> =>
+        provider.attach(sessionId, mode, scope),
+    );
+  }
+
+  async detach(
+    providerId: string,
+    attachmentId: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<void> {
+    await this.execute(
+      providerId,
+      'session.attach',
+      'session.attach',
+      attachmentId,
+      context,
+      (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<void> =>
+        provider.detach(attachmentId, scope),
+    );
+  }
+
+  async terminate(
+    providerId: string,
+    sessionId: string,
+    approvalRef: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<void> {
+    await this.execute(
+      providerId,
+      'session.terminate',
+      'session.terminate',
+      sessionId,
+      context,
+      async (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<void> => {
+        const approved = await this.approvals.consume(approvalRef, {
+          providerId,
+          sessionId,
+          actorId: scope.actorId,
+          tenantId: scope.tenantId,
+          channelId: scope.channelId,
+          correlationId: scope.correlationId,
+          agentName: configuredAgentName(),
+        });
+        if (!approved) {
+          throw new RuntimeApprovalDeniedError();
+        }
+        await provider.terminate(sessionId, approvalRef, scope);
+      },
+    );
+  }
+
+  private async execute<T>(
+    providerId: string,
+    operation: RuntimeProviderOperation,
+    requiredCapability: RuntimeCapability | undefined,
+    resourceId: string | undefined,
+    context: RuntimeProviderRequestContext,
+    invoke: (provider: AgentRuntimeProvider, scope: RuntimeScope) => Promise<T>,
+  ): Promise<T> {
+    const scope = this.deriveScope(context);
+    const startedAt = Date.now();
+    await this.record(providerId, operation, 'requested', scope, resourceId);
+    let invocationStarted = false;
+    try {
+      const provider = this.provider(providerId);
+      if (requiredCapability) {
+        await this.assertCapability(provider, requiredCapability, scope);
+      }
+      invocationStarted = true;
+      const result = await invoke(provider, scope);
+      await this.recordCompletion(providerId, operation, scope, resourceId, Date.now() - startedAt);
+      return result;
+    } catch (error: unknown) {
+      const durationMs = Date.now() - startedAt;
+      if (invocationStarted && !this.isAuthorizationDenied(error)) {
+        await this.recordFailure(providerId, operation, scope, resourceId, durationMs);
+      } else {
+        await this.record(
+          providerId,
+          operation,
+          'denied',
+          scope,
+          resourceId,
+          durationMs,
+          'policy_denied',
+        );
+      }
+      throw error;
+    }
+  }
+
+  private async *stream(
+    providerId: string,
+    operation: RuntimeProviderOperation,
+    requiredCapability: RuntimeCapability,
+    resourceId: string,
+    context: RuntimeProviderRequestContext,
+    invoke: (
+      provider: AgentRuntimeProvider,
+      scope: RuntimeScope,
+    ) => AsyncIterable<RuntimeStreamEvent>,
+  ): AsyncIterable<RuntimeStreamEvent> {
+    const scope = this.deriveScope(context);
+    const startedAt = Date.now();
+    await this.record(providerId, operation, 'requested', scope, resourceId);
+    let invocationStarted = false;
+    try {
+      const provider = this.provider(providerId);
+      await this.assertCapability(provider, requiredCapability, scope);
+      invocationStarted = true;
+      for await (const event of invoke(provider, scope)) {
+        yield event;
+      }
+      await this.recordCompletion(providerId, operation, scope, resourceId, Date.now() - startedAt);
+    } catch (error: unknown) {
+      const durationMs = Date.now() - startedAt;
+      if (invocationStarted) {
+        await this.recordFailure(providerId, operation, scope, resourceId, durationMs);
+      } else {
+        await this.record(
+          providerId,
+          operation,
+          'denied',
+          scope,
+          resourceId,
+          durationMs,
+          'policy_denied',
+        );
+      }
+      throw error;
+    }
+  }
+
+  private isAuthorizationDenied(error: unknown): boolean {
+    return (
+      error instanceof RuntimeApprovalDeniedError ||
+      error instanceof ForbiddenException ||
+      (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        (error as { code?: unknown }).code === 'forbidden')
+    );
+  }
+
+  private provider(providerId: string): AgentRuntimeProvider {
+    try {
+      return this.registry.require(providerId);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : 'Runtime provider is not registered';
+      throw new NotFoundException(message);
+    }
+  }
+
+  private async assertCapability(
+    provider: AgentRuntimeProvider,
+    requiredCapability: RuntimeCapability,
+    scope: RuntimeScope,
+  ): Promise<void> {
+    const capabilities = await provider.capabilities(scope);
+    if (!capabilities.supported.includes(requiredCapability)) {
+      throw new ForbiddenException(`Runtime provider capability denied: ${requiredCapability}`);
+    }
+  }
+
+  private deriveScope(context: RuntimeProviderRequestContext): RuntimeScope {
+    const actorId = context.actorScope.userId.trim();
+    const tenantId = context.actorScope.tenantId.trim();
+    const channelId = context.channelId.trim();
+    const correlationId = context.correlationId.trim();
+    if (!actorId || !tenantId || !channelId || !correlationId) {
+      throw new ForbiddenException(
+        'Authenticated runtime actor scope and correlation are required',
+      );
+    }
+    return Object.freeze({ actorId, tenantId, channelId, correlationId });
+  }
+
+  private async recordFailure(
+    providerId: string,
+    operation: RuntimeProviderOperation,
+    scope: RuntimeScope,
+    resourceId: string | undefined,
+    durationMs: number,
+  ): Promise<void> {
+    try {
+      await this.record(
+        providerId,
+        operation,
+        'failed',
+        scope,
+        resourceId,
+        durationMs,
+        'provider_error',
+      );
+    } catch {
+      this.logger.error(
+        `Runtime provider failure audit failed provider=${providerId} operation=${operation} correlation=${scope.correlationId}`,
+      );
+    }
+  }
+
+  private async recordCompletion(
+    providerId: string,
+    operation: RuntimeProviderOperation,
+    scope: RuntimeScope,
+    resourceId: string | undefined,
+    durationMs: number,
+  ): Promise<void> {
+    try {
+      await this.record(providerId, operation, 'succeeded', scope, resourceId, durationMs);
+    } catch {
+      this.logger.error(
+        `Runtime provider completion audit failed provider=${providerId} operation=${operation} correlation=${scope.correlationId}`,
+      );
+    }
+  }
+
+  private async record(
+    providerId: string,
+    operation: RuntimeProviderOperation,
+    outcome: RuntimeProviderAuditOutcome,
+    scope: RuntimeScope,
+    resourceId: string | undefined,
+    durationMs?: number,
+    errorCode?: RuntimeAuditErrorCode,
+  ): Promise<void> {
+    await this.audit.record({
+      providerId,
+      operation,
+      outcome,
+      actorId: scope.actorId,
+      tenantId: scope.tenantId,
+      channelId: scope.channelId,
+      correlationId: scope.correlationId,
+      ...(resourceId ? { resourceId } : {}),
+      ...(durationMs !== undefined ? { durationMs } : {}),
+      ...(errorCode ? { errorCode } : {}),
+    });
+  }
+}

apps/gateway/src/agent/sessions.controller.ts

@@ -10,6 +10,8 @@ import {
   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 { AgentService } from './agent.service.js';
 
 @Controller('api/sessions')
@@ -18,23 +20,24 @@ export class SessionsController {
   constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
 
   @Get()
-  list() {
-    const sessions = this.agentService.listSessions();
+  list(@CurrentUser() user: AuthenticatedUserLike) {
+    const sessions = this.agentService.listSessions(scopeFromUser(user));
     return { sessions, total: sessions.length };
   }
 
   @Get(':id')
-  findOne(@Param('id') id: string) {
-    const info = this.agentService.getSessionInfo(id);
+  findOne(@Param('id') id: string, @CurrentUser() user: AuthenticatedUserLike) {
+    const info = this.agentService.getSessionInfo(id, scopeFromUser(user));
     if (!info) throw new NotFoundException('Session not found');
     return info;
   }
 
   @Delete(':id')
   @HttpCode(HttpStatus.NO_CONTENT)
-  async destroy(@Param('id') id: string) {
-    const info = this.agentService.getSessionInfo(id);
+  async destroy(@Param('id') id: string, @CurrentUser() user: AuthenticatedUserLike) {
+    const scope = scopeFromUser(user);
+    const info = this.agentService.getSessionInfo(id, scope);
     if (!info) throw new NotFoundException('Session not found');
-    await this.agentService.destroySession(id);
+    await this.agentService.destroySession(id, scope);
   }
 }

apps/gateway/src/agent/tools/memory-tools.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMemoryTools } from './memory-tools.js';
+
+describe('createMemoryTools operator retrieval binding', () => {
+  const memory = {
+    insights: { searchByEmbedding: vi.fn(), create: vi.fn() },
+    preferences: { findByUserAndCategory: vi.fn(), findByUser: vi.fn(), upsert: vi.fn() },
+  };
+  const scope = { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 'session-a' };
+
+  it('uses the configured plugin with the server-derived scope for retrieval and capture', async () => {
+    const plugin = {
+      search: vi.fn(async () => []),
+      capture: vi.fn(async () => ({ id: 'insight-1' })),
+    };
+    const tools = createMemoryTools(memory as never, null, 'owner-a', {
+      plugin: plugin as never,
+      scope,
+    });
+
+    await tools
+      .find((tool) => tool.name === 'memory_search')!
+      .execute('call-1', { query: 'plans' }, undefined, undefined, {} as never);
+    await tools
+      .find((tool) => tool.name === 'memory_save_insight')!
+      .execute(
+        'call-2',
+        { content: 'secret', category: 'decision' },
+        undefined,
+        undefined,
+        {} as never,
+      );
+
+    expect(plugin.search).toHaveBeenCalledWith(scope, 'plans', 5);
+    expect(plugin.capture).toHaveBeenCalledWith(scope, {
+      content: 'secret',
+      source: 'agent',
+      category: 'decision',
+    });
+  });
+});

apps/gateway/src/agent/tools/memory-tools.ts

@@ -1,7 +1,11 @@
 import { Type } from '@sinclair/typebox';
 import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
-import type { Memory } from '@mosaicstack/memory';
-import type { EmbeddingProvider } from '@mosaicstack/memory';
+import type {
+  EmbeddingProvider,
+  Memory,
+  OperatorMemoryPlugin,
+  OperatorMemoryScope,
+} from '@mosaicstack/memory';
 
 /**
  * Create memory tools bound to the session's authenticated userId.
@@ -13,8 +17,10 @@ import type { EmbeddingProvider } from '@mosaicstack/memory';
 export function createMemoryTools(
   memory: Memory,
   embeddingProvider: EmbeddingProvider | null,
-  /** Authenticated user ID from the session. All memory operations are scoped to this user. */
+  /** Authenticated user ID from the session. All preference operations are scoped to this user. */
   sessionUserId: string | undefined,
+  /** Optional configured retrieval plugin, bound to a server-derived session scope. */
+  operatorMemory?: { plugin: OperatorMemoryPlugin; scope: OperatorMemoryScope },
 ): ToolDefinition[] {
   /** Return an error result when no session user is bound. */
   function noUserError() {
@@ -46,6 +52,14 @@ export function createMemoryTools(
         limit?: number;
       };
 
+      if (operatorMemory) {
+        const results = await operatorMemory.plugin.search(operatorMemory.scope, query, limit ?? 5);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }],
+          details: undefined,
+        };
+      }
+
       if (!embeddingProvider) {
         return {
           content: [
@@ -158,6 +172,18 @@ export function createMemoryTools(
       };
       type Cat = 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
 
+      if (operatorMemory) {
+        const insight = await operatorMemory.plugin.capture(operatorMemory.scope, {
+          content,
+          source: 'agent',
+          category: category ?? 'learning',
+        });
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(insight, null, 2) }],
+          details: undefined,
+        };
+      }
+
       let embedding: number[] | null = null;
       if (embeddingProvider) {
         embedding = await embeddingProvider.embed(content);

apps/gateway/src/auth/session-scope.ts

@@ -0,0 +1,24 @@
+export interface AuthenticatedUserLike {
+  id: string;
+  tenantId?: string | null;
+  teamId?: string | null;
+  organizationId?: string | null;
+  orgId?: string | null;
+}
+
+export interface ActorTenantScope {
+  userId: string;
+  tenantId: string;
+}
+
+/**
+ * Build the immutable server-derived scope used for Tess session operations.
+ * Current Mosaic auth is user-scoped; future org/team claims can populate one
+ * of the tenant fields without allowing clients to choose another tenant.
+ */
+export function scopeFromUser(user: AuthenticatedUserLike): ActorTenantScope {
+  return {
+    userId: user.id,
+    tenantId: user.tenantId ?? user.teamId ?? user.organizationId ?? user.orgId ?? user.id,
+  };
+}

apps/gateway/src/chat/__tests__/chat-security.test.ts

@@ -12,7 +12,8 @@ describe('Chat controller source hardening', () => {
     const source = readFileSync(resolve('src/chat/chat.controller.ts'), 'utf8');
 
     expect(source).toContain('@UseGuards(AuthGuard)');
-    expect(source).toContain('@CurrentUser() user: { id: string }');
+    expect(source).toContain('@CurrentUser() user: AuthenticatedUserLike');
+    expect(source).toContain('const scope = scopeFromUser(user);');
   });
 });
 

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

@@ -3,8 +3,10 @@ import {
   Post,
   Body,
   Logger,
+  ForbiddenException,
   HttpException,
   HttpStatus,
+  NotFoundException,
   Inject,
   UseGuards,
 } from '@nestjs/common';
@@ -13,6 +15,7 @@ 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';
 
@@ -32,16 +35,23 @@ export class ChatController {
   @Throttle({ default: { limit: 10, ttl: 60_000 } })
   async chat(
     @Body() body: ChatRequestDto,
-    @CurrentUser() user: { id: string },
+    @CurrentUser() user: AuthenticatedUserLike,
   ): Promise<ChatResponse> {
     const conversationId = body.conversationId ?? uuid();
+    const scope = scopeFromUser(user);
 
     try {
-      let agentSession = this.agentService.getSession(conversationId);
+      let agentSession = this.agentService.getSession(conversationId, scope);
       if (!agentSession) {
-        agentSession = await this.agentService.createSession(conversationId);
+        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),
@@ -60,20 +70,27 @@ export class ChatController {
         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();
-        }
-      });
+      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);
+      await this.agentService.prompt(conversationId, body.content, scope);
       await done;
     } catch (err) {
       if (err instanceof HttpException) throw err;

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

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from 'node:crypto';
 import type { IncomingHttpHeaders } from 'node:http';
 import { fromNodeHeaders } from 'better-auth/node';
 
@@ -12,6 +13,19 @@ export interface SessionAuth {
   };
 }
 
+export function validateDiscordServiceToken(
+  candidate: unknown,
+  expected: string | undefined,
+): boolean {
+  if (typeof candidate !== 'string' || !expected) return false;
+  const candidateBuffer = Buffer.from(candidate);
+  const expectedBuffer = Buffer.from(expected);
+  return (
+    candidateBuffer.length === expectedBuffer.length &&
+    timingSafeEqual(candidateBuffer, expectedBuffer)
+  );
+}
+
 export async function validateSocketSession(
   headers: IncomingHttpHeaders,
   auth: SessionAuth,

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

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { SlashCommandPayload } from '@mosaicstack/types';
+import { ChatGateway } from './chat.gateway.js';
+
+const payload: SlashCommandPayload = {
+  command: 'gc',
+  conversationId: 'conversation-1',
+  approvalId: 'approval-1',
+};
+
+function buildGateway(commandExecutor: {
+  execute: ReturnType<typeof vi.fn>;
+  createApproval: ReturnType<typeof vi.fn>;
+}): ChatGateway {
+  return new ChatGateway(
+    {} as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    commandExecutor as never,
+    {} as never,
+  );
+}
+
+describe('ChatGateway command approval ingress', () => {
+  it('passes the client approval ID through to command execution while deriving the actor server-side', async (): Promise<void> => {
+    const commandExecutor = {
+      execute: vi.fn().mockResolvedValue({ ...payload, success: true }),
+      createApproval: vi.fn(),
+    };
+    const gateway = buildGateway(commandExecutor);
+    const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
+
+    await gateway.handleCommandExecute(client as never, payload);
+
+    expect(commandExecutor.execute).toHaveBeenCalledWith(payload, {
+      userId: 'admin-1',
+      tenantId: 'admin-1',
+    });
+    expect(client.emit).toHaveBeenCalledWith(
+      'command:result',
+      expect.objectContaining({ success: true }),
+    );
+  });
+
+  it('issues a durable approval only for the authenticated actor', async (): Promise<void> => {
+    const commandExecutor = {
+      execute: vi.fn(),
+      createApproval: vi.fn().mockResolvedValue({
+        approvalId: 'approval-1',
+        expiresAt: '2026-07-12T00:05:00.000Z',
+      }),
+    };
+    const gateway = buildGateway(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', {
+      command: 'gc',
+      conversationId: 'conversation-1',
+      success: true,
+      approvalId: 'approval-1',
+      expiresAt: '2026-07-12T00:05:00.000Z',
+    });
+  });
+});

apps/gateway/src/chat/chat.gateway-redaction.spec.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChatGateway } from './chat.gateway.js';
+
+const CONVERSATION_ID = 'conversation-1';
+const CANARY = 'sk_canary12345678';
+
+type GatewayInternals = {
+  clientSessions: Map<string, unknown>;
+  relayEvent(client: unknown, conversationId: string, event: unknown): void;
+};
+
+function buildGateway() {
+  const brain = {
+    conversations: {
+      addMessage: vi.fn().mockResolvedValue(undefined),
+    },
+  };
+  const agentService = {
+    getSession: vi.fn().mockReturnValue(undefined),
+  };
+  const gateway = new ChatGateway(
+    agentService as never,
+    {} as never,
+    brain as never,
+    {} as never,
+    {} as never,
+    {} as never,
+  );
+
+  return { gateway: gateway as unknown as GatewayInternals, brain };
+}
+
+describe('ChatGateway redaction boundary', (): void => {
+  it('redacts a secret split across assistant deltas before egress and persistence', (): void => {
+    const { gateway } = buildGateway();
+    const client = {
+      connected: true,
+      id: 'client-1',
+      data: { user: { id: 'user-1' } },
+      emit: vi.fn(),
+    };
+    const session = {
+      conversationId: CONVERSATION_ID,
+      cleanup: vi.fn(),
+      assistantText: '',
+      toolCalls: [],
+      pendingToolCalls: new Map(),
+      scope: { userId: 'user-1', tenantId: 'tenant-1' },
+    };
+    gateway.clientSessions.set(client.id, session);
+
+    gateway.relayEvent(client, CONVERSATION_ID, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: 'sk_canary' },
+    });
+
+    expect(JSON.stringify(client.emit.mock.calls)).not.toContain('sk_canary');
+
+    gateway.relayEvent(client, CONVERSATION_ID, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: '12345678 ' },
+    });
+
+    expect(client.emit).toHaveBeenCalledWith('agent:text', {
+      conversationId: CONVERSATION_ID,
+      text: '[REDACTED_SECRET] ',
+    });
+    expect(session.assistantText).toBe(`${CANARY} `);
+    expect(JSON.stringify(client.emit.mock.calls)).not.toContain(CANARY);
+  });
+
+  it('retains a split secret label until its value can be redacted', (): void => {
+    const { gateway } = buildGateway();
+    const client = {
+      connected: true,
+      id: 'client-1',
+      data: { user: { id: 'user-1' } },
+      emit: vi.fn(),
+    };
+
+    gateway.relayEvent(client, CONVERSATION_ID, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: 'token ' },
+    });
+    gateway.relayEvent(client, CONVERSATION_ID, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: '=canaryvalue123 ' },
+    });
+
+    expect(client.emit).toHaveBeenCalledWith('agent:text', {
+      conversationId: CONVERSATION_ID,
+      text: '[REDACTED_SECRET] ',
+    });
+    expect(JSON.stringify(client.emit.mock.calls)).not.toContain('canaryvalue123');
+  });
+
+  it('holds a streamed private key until it can be redacted', (): void => {
+    const { gateway } = buildGateway();
+    const client = {
+      connected: true,
+      id: 'client-1',
+      data: { user: { id: 'user-1' } },
+      emit: vi.fn(),
+    };
+
+    gateway.relayEvent(client, CONVERSATION_ID, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: '-----BEGIN PRIVATE KEY-----\ncanary' },
+    });
+    gateway.relayEvent(client, CONVERSATION_ID, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: '\n-----END PRIVATE KEY-----' },
+    });
+
+    expect(client.emit).toHaveBeenCalledWith('agent:text', {
+      conversationId: CONVERSATION_ID,
+      text: '[REDACTED_SECRET]',
+    });
+    expect(JSON.stringify(client.emit.mock.calls)).not.toContain('canary');
+  });
+
+  it('drops an oversized unterminated stream fragment rather than retaining it', (): void => {
+    const { gateway } = buildGateway();
+    const client = {
+      connected: true,
+      id: 'client-1',
+      data: { user: { id: 'user-1' } },
+      emit: vi.fn(),
+    };
+
+    gateway.relayEvent(client, CONVERSATION_ID, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: 'x'.repeat(8_193) },
+    });
+
+    expect(client.emit).toHaveBeenCalledWith('agent:text', {
+      conversationId: CONVERSATION_ID,
+      text: '[REDACTED_STREAM_OVERFLOW]',
+    });
+  });
+
+  it('persists only redacted assistant content with classifications', (): void => {
+    const { gateway, brain } = buildGateway();
+    const client = {
+      connected: true,
+      id: 'client-1',
+      data: { user: { id: 'user-1' } },
+      emit: vi.fn(),
+    };
+    gateway.clientSessions.set(client.id, {
+      conversationId: CONVERSATION_ID,
+      cleanup: vi.fn(),
+      assistantText: CANARY,
+      toolCalls: [],
+      pendingToolCalls: new Map(),
+      scope: { userId: 'user-1', tenantId: 'tenant-1' },
+    });
+
+    gateway.relayEvent(client, CONVERSATION_ID, { type: 'agent_end' });
+
+    expect(brain.conversations.addMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        content: '[REDACTED_SECRET]',
+        metadata: expect.objectContaining({ classifications: ['secret'] }),
+      }),
+      'user-1',
+    );
+    expect(JSON.stringify(brain.conversations.addMessage.mock.calls)).not.toContain(CANARY);
+  });
+});

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

@@ -1,4 +1,5 @@
-import { Inject, Logger } from '@nestjs/common';
+import { createHash } from 'node:crypto';
+import { Inject, Logger, Optional } from '@nestjs/common';
 import {
   WebSocketGateway,
   WebSocketServer,
@@ -11,24 +12,47 @@ import {
 } from '@nestjs/websockets';
 import { Server, Socket } from 'socket.io';
 import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import {
+  verifyDiscordIngressEnvelope,
+  parseDiscordInteractionBindings,
+  resolveDiscordInteractionActorId,
+  resolveDiscordInteractionBinding,
+  type DiscordIngressEnvelope,
+  type DiscordIngressPayload,
+} from '@mosaicstack/discord-plugin';
 import type { Auth } from '@mosaicstack/auth';
 import type { Brain } from '@mosaicstack/brain';
+import { redactSensitiveContent } from '@mosaicstack/log';
 import type {
   SetThinkingPayload,
+  SlashCommandApprovalResultPayload,
   SlashCommandPayload,
   SystemReloadPayload,
   RoutingDecisionInfo,
   AbortPayload,
 } from '@mosaicstack/types';
 import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
+import {
+  RUNTIME_PROVIDER_AUDIT_SINK,
+  RuntimeProviderService,
+  type RuntimeAuditSink,
+} from '../agent/runtime-provider-registry.service.js';
+import { DurableSessionService } from '../agent/durable-session.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
+import {
+  scopeFromUser,
+  type ActorTenantScope,
+  type AuthenticatedUserLike,
+} from '../auth/session-scope.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 { CommandAuthorizationService } from '../commands/command-authorization.service.js';
 import { RoutingEngineService } from '../agent/routing/routing-engine.service.js';
 import { v4 as uuid } from 'uuid';
 import { ChatSocketMessageDto } from './chat.dto.js';
-import { validateSocketSession } from './chat.gateway-auth.js';
+import { validateDiscordServiceToken, validateSocketSession } from './chat.gateway-auth.js';
+import { DiscordReplayProtector } from '../plugin/discord-replay-protector.js';
 
 /** Per-client state tracking streaming accumulation for persistence. */
 interface ClientSession {
@@ -40,6 +64,8 @@ interface ClientSession {
   toolCalls: Array<{ toolCallId: string; toolName: string; args: unknown; isError: boolean }>;
   /** Tool calls in-flight (started but not ended yet). */
   pendingToolCalls: Map<string, { toolName: string; args: unknown }>;
+  /** Server-derived owner/tenant scope for this socket's conversation attachment. */
+  scope: ActorTenantScope;
   /** Last routing decision made for this session (M4-008) */
   lastRoutingDecision?: RoutingDecisionInfo;
 }
@@ -49,6 +75,38 @@ interface ClientSession {
  * Keyed by conversationId, value is the model name to use.
  */
 const modelOverrides = new Map<string, string>();
+const MAX_REDACTION_BUFFER_LENGTH = 8_192;
+
+function isDiscordIngressEnvelope(value: unknown): value is DiscordIngressEnvelope {
+  if (typeof value !== 'object' || value === null) return false;
+  const envelope = value as { payload?: unknown; signature?: unknown };
+  if (
+    typeof envelope.signature !== 'string' ||
+    typeof envelope.payload !== 'object' ||
+    envelope.payload === null
+  ) {
+    return false;
+  }
+  const payload = envelope.payload as Record<string, unknown>;
+  return [
+    payload['correlationId'],
+    payload['messageId'],
+    payload['guildId'],
+    payload['channelId'],
+    payload['userId'],
+    payload['conversationId'],
+    payload['content'],
+  ].every((field: unknown): boolean => typeof field === 'string');
+}
+
+function isChatSocketMessage(value: unknown): value is ChatSocketMessageDto {
+  if (typeof value !== 'object' || value === null) return false;
+  const payload = value as { content?: unknown; conversationId?: unknown };
+  return (
+    typeof payload.content === 'string' &&
+    (payload.conversationId === undefined || typeof payload.conversationId === 'string')
+  );
+}
 
 @WebSocketGateway({
   cors: {
@@ -62,6 +120,11 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
   private readonly logger = new Logger(ChatGateway.name);
   private readonly clientSessions = new Map<string, ClientSession>();
+  /** Raw stream fragments are kept in memory only until they are safe to redact and emit. */
+  private readonly textEgressBuffers = new Map<string, string>();
+  private readonly thinkingEgressBuffers = new Map<string, string>();
+  private readonly overflowedEgress = new Set<string>();
+  private readonly discordReplayProtector = new DiscordReplayProtector();
 
   constructor(
     @Inject(AgentService) private readonly agentService: AgentService,
@@ -70,6 +133,18 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     @Inject(CommandRegistryService) private readonly commandRegistry: CommandRegistryService,
     @Inject(CommandExecutorService) private readonly commandExecutor: CommandExecutorService,
     @Inject(RoutingEngineService) private readonly routingEngine: RoutingEngineService,
+    @Optional()
+    @Inject(CommandAuthorizationService)
+    private readonly commandAuthorization: CommandAuthorizationService | null = null,
+    @Optional()
+    @Inject(RuntimeProviderService)
+    private readonly runtimeRegistry: RuntimeProviderService | null = null,
+    @Optional()
+    @Inject(DurableSessionService)
+    private readonly durableSessions: DurableSessionService | null = null,
+    @Optional()
+    @Inject(RUNTIME_PROVIDER_AUDIT_SINK)
+    private readonly runtimeAudit: RuntimeAuditSink | null = null,
   ) {}
 
   afterInit(): void {
@@ -77,6 +152,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
   }
 
   async handleConnection(client: Socket): Promise<void> {
+    const serviceToken = client.handshake.auth['discordServiceToken'];
+    if (validateDiscordServiceToken(serviceToken, process.env['DISCORD_SERVICE_TOKEN'])) {
+      client.data.discordService = true;
+      this.logger.log(`Authenticated Discord service connected: ${client.id}`);
+      return;
+    }
+
     const session = await validateSocketSession(client.handshake.headers, this.auth);
     if (!session) {
       this.logger.warn(`Rejected unauthenticated WebSocket client: ${client.id}`);
@@ -87,8 +169,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     client.data.user = session.user;
     client.data.session = session.session;
     this.logger.log(`Client connected: ${client.id}`);
-
-    // Broadcast command manifest to the newly connected client
     client.emit('commands:manifest', { manifest: this.commandRegistry.getManifest() });
   }
 
@@ -97,25 +177,84 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     const session = this.clientSessions.get(client.id);
     if (session) {
       session.cleanup();
-      this.agentService.removeChannel(session.conversationId, `websocket:${client.id}`);
+      this.agentService.removeChannel(
+        session.conversationId,
+        `websocket:${client.id}`,
+        session.scope,
+      );
       this.clientSessions.delete(client.id);
     }
+    this.textEgressBuffers.delete(client.id);
+    this.thinkingEgressBuffers.delete(client.id);
+    this.overflowedEgress.delete(this.egressKey(client, 'agent:text'));
+    this.overflowedEgress.delete(this.egressKey(client, 'agent:thinking'));
+  }
+
+  private getClientScope(client: Socket): ActorTenantScope | null {
+    const user = client.data.user as AuthenticatedUserLike | undefined;
+    if (!user?.id) return null;
+    return scopeFromUser(user);
+  }
+
+  private modelOverrideKey(conversationId: string, scope: ActorTenantScope): string {
+    return `${scope.tenantId}:${scope.userId}:${conversationId}`;
+  }
+
+  private scopesEqual(a: ActorTenantScope, b: ActorTenantScope): boolean {
+    return a.userId === b.userId && a.tenantId === b.tenantId;
   }
 
   @SubscribeMessage('message')
   async handleMessage(
     @ConnectedSocket() client: Socket,
-    @MessageBody() data: ChatSocketMessageDto,
+    @MessageBody() rawData: unknown,
   ): Promise<void> {
+    let discordIngress: DiscordIngressPayload | null = null;
+    let data: ChatSocketMessageDto;
+    if (client.data.discordService) {
+      if (!isDiscordIngressEnvelope(rawData)) {
+        this.logger.warn(`Rejected malformed Discord ingress from ${client.id}`);
+        return;
+      }
+      discordIngress = this.resolveDiscordIngress(client, rawData);
+      if (!discordIngress) return;
+      data = { conversationId: discordIngress.conversationId, content: discordIngress.content };
+    } else {
+      if (!isChatSocketMessage(rawData)) {
+        this.logger.warn(`Rejected malformed chat message from ${client.id}`);
+        return;
+      }
+      data = rawData;
+    }
     const conversationId = data.conversationId ?? uuid();
-    const userId = (client.data.user as { id: string } | undefined)?.id;
+    const discordServiceUserId = process.env['DISCORD_SERVICE_USER_ID'];
+    if (discordIngress && !discordServiceUserId) {
+      this.logger.warn(
+        `Rejected Discord ingress without configured service owner from ${client.id}`,
+      );
+      return;
+    }
+    const scope = discordIngress
+      ? {
+          userId: discordServiceUserId!,
+          tenantId: process.env['DISCORD_SERVICE_TENANT_ID'] ?? discordServiceUserId!,
+        }
+      : this.getClientScope(client);
+    if (!scope) {
+      client.emit('error', { conversationId, error: 'Authenticated user scope is required.' });
+      return;
+    }
+    const userId = scope.userId;
+    const correlationId = discordIngress?.correlationId;
 
-    this.logger.log(`Message from ${client.id} in conversation ${conversationId}`);
+    this.logger.log(
+      `Message from ${client.id} in conversation ${conversationId}${correlationId ? ` correlation=${correlationId}` : ''}`,
+    );
 
     // Ensure agent session exists for this conversation
     let sessionRoutingDecision: RoutingDecisionInfo | undefined;
     try {
-      let agentSession = this.agentService.getSession(conversationId);
+      let agentSession = this.agentService.getSession(conversationId, scope);
       if (!agentSession) {
         // When resuming an existing conversation, load prior messages to inject as context (M1-004)
         const conversationHistory = await this.loadConversationHistory(conversationId, userId);
@@ -135,7 +274,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
         let resolvedProvider = data.provider;
         let resolvedModelId = data.modelId;
 
-        const modelOverride = modelOverrides.get(conversationId);
+        const modelOverride = modelOverrides.get(this.modelOverrideKey(conversationId, scope));
         if (modelOverride) {
           // /model override bypasses routing engine (M4-007)
           resolvedModelId = modelOverride;
@@ -172,6 +311,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
           modelId: resolvedModelId,
           agentConfigId: data.agentId,
           userId,
+          tenantId: scope.tenantId,
           conversationHistory: conversationHistory.length > 0 ? conversationHistory : undefined,
         });
 
@@ -210,9 +350,17 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
           {
             conversationId,
             role: 'user',
-            content: data.content,
+            content: redactSensitiveContent(data.content).content,
             metadata: {
               timestamp: new Date().toISOString(),
+              ...(correlationId
+                ? {
+                    correlationId,
+                    discordMessageId: discordIngress?.messageId,
+                    discordUserId: discordIngress?.userId,
+                  }
+                : {}),
+              classifications: redactSensitiveContent(data.content).classifications,
             },
           },
           userId,
@@ -232,9 +380,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     }
 
     // Subscribe to agent events and relay to client
-    const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
-      this.relayEvent(client, conversationId, event);
-    });
+    const cleanup = this.agentService.onEvent(
+      conversationId,
+      (event: AgentSessionEvent) => {
+        this.relayEvent(client, conversationId, event);
+      },
+      scope,
+    );
 
     // Preserve routing decision from the existing client session if we didn't get a new one
     const prevClientSession = this.clientSessions.get(client.id);
@@ -246,16 +398,17 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       assistantText: '',
       toolCalls: [],
       pendingToolCalls: new Map(),
+      scope,
       lastRoutingDecision: routingDecisionToStore,
     });
 
     // Track channel connection
-    this.agentService.addChannel(conversationId, `websocket:${client.id}`);
+    this.agentService.addChannel(conversationId, `websocket:${client.id}`, scope);
 
     // Send session info so the client knows the model/provider (M4-008: include routing decision)
     // Include agentName when a named agent config is active (M5-001)
     {
-      const agentSession = this.agentService.getSession(conversationId);
+      const agentSession = this.agentService.getSession(conversationId, scope);
       if (agentSession) {
         const piSession = agentSession.piSession;
         client.emit('session:info', {
@@ -271,11 +424,21 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     }
 
     // Send acknowledgment
-    client.emit('message:ack', { conversationId, messageId: uuid() });
+    client.emit('message:ack', {
+      conversationId,
+      messageId: uuid(),
+      ...(correlationId
+        ? {
+            correlationId,
+            discordMessageId: discordIngress?.messageId,
+            discordUserId: discordIngress?.userId,
+          }
+        : {}),
+    });
 
     // Dispatch to agent
     try {
-      await this.agentService.prompt(conversationId, data.content);
+      await this.agentService.prompt(conversationId, data.content, scope);
     } catch (err) {
       this.logger.error(
         `Agent prompt failed for client=${client.id}, conversation=${conversationId}`,
@@ -293,7 +456,16 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     @ConnectedSocket() client: Socket,
     @MessageBody() data: SetThinkingPayload,
   ): void {
-    const session = this.agentService.getSession(data.conversationId);
+    const scope = this.getClientScope(client);
+    if (!scope) {
+      client.emit('error', {
+        conversationId: data.conversationId,
+        error: 'Authenticated user scope is required.',
+      });
+      return;
+    }
+
+    const session = this.agentService.getSession(data.conversationId, scope);
     if (!session) {
       client.emit('error', {
         conversationId: data.conversationId,
@@ -334,7 +506,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     const conversationId = data.conversationId;
     this.logger.log(`Abort requested by ${client.id} for conversation ${conversationId}`);
 
-    const session = this.agentService.getSession(conversationId);
+    const scope = this.getClientScope(client);
+    if (!scope) {
+      client.emit('error', { conversationId, error: 'Authenticated user scope is required.' });
+      return;
+    }
+
+    const session = this.agentService.getSession(conversationId, scope);
     if (!session) {
       client.emit('error', {
         conversationId,
@@ -363,11 +541,45 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     @ConnectedSocket() client: Socket,
     @MessageBody() payload: SlashCommandPayload,
   ): Promise<void> {
-    const userId = (client.data.user as { id: string } | undefined)?.id ?? 'unknown';
-    const result = await this.commandExecutor.execute(payload, userId);
+    const scope = this.getClientScope(client);
+    if (!scope) {
+      client.emit('command:result', {
+        command: payload.command,
+        conversationId: payload.conversationId,
+        success: false,
+        message: 'Authenticated user scope is required.',
+      });
+      return;
+    }
+
+    const result = await this.commandExecutor.execute(payload, scope);
     client.emit('command:result', result);
   }
 
+  @SubscribeMessage('command:approve')
+  async handleCommandApproval(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() payload: SlashCommandPayload,
+  ): Promise<void> {
+    const scope = this.getClientScope(client);
+    const approval = scope ? await this.commandExecutor.createApproval(payload, scope) : null;
+    const result: SlashCommandApprovalResultPayload = approval
+      ? {
+          command: payload.command,
+          conversationId: payload.conversationId,
+          success: true,
+          approvalId: approval.approvalId,
+          expiresAt: approval.expiresAt,
+        }
+      : {
+          command: payload.command,
+          conversationId: payload.conversationId,
+          success: false,
+          message: 'Not authorized to approve this command.',
+        };
+    client.emit('command:approval', result);
+  }
+
   broadcastReload(payload: SystemReloadPayload): void {
     this.server.emit('system:reload', payload);
     this.logger.log('Broadcasted system:reload to all connected clients');
@@ -380,18 +592,23 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
    * M5-005: Emits session:info to clients subscribed to this conversation when a model is set.
    * M5-007: Records a model switch in session metrics.
    */
-  setModelOverride(conversationId: string, modelName: string | null): void {
+  setModelOverride(
+    conversationId: string,
+    modelName: string | null,
+    scope: ActorTenantScope,
+  ): void {
+    const key = this.modelOverrideKey(conversationId, scope);
     if (modelName) {
-      modelOverrides.set(conversationId, modelName);
+      modelOverrides.set(key, modelName);
       this.logger.log(`Model override set: conversation=${conversationId} model="${modelName}"`);
 
       // M5-002: Update the live session's modelId so session:info reflects the new model immediately
-      this.agentService.updateSessionModel(conversationId, modelName);
+      this.agentService.updateSessionModel(conversationId, modelName, scope);
 
       // M5-005: Broadcast session:info to all clients subscribed to this conversation
-      this.broadcastSessionInfo(conversationId);
+      this.broadcastSessionInfo(conversationId, scope);
     } else {
-      modelOverrides.delete(conversationId);
+      modelOverrides.delete(key);
       this.logger.log(`Model override cleared: conversation=${conversationId}`);
     }
   }
@@ -399,8 +616,8 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
   /**
    * Return the active model override for a conversation, or undefined if none.
    */
-  getModelOverride(conversationId: string): string | undefined {
-    return modelOverrides.get(conversationId);
+  getModelOverride(conversationId: string, scope: ActorTenantScope): string | undefined {
+    return modelOverrides.get(this.modelOverrideKey(conversationId, scope));
   }
 
   /**
@@ -409,9 +626,10 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
    */
   broadcastSessionInfo(
     conversationId: string,
+    scope: ActorTenantScope,
     extra?: { agentName?: string; routingDecision?: RoutingDecisionInfo },
   ): void {
-    const agentSession = this.agentService.getSession(conversationId);
+    const agentSession = this.agentService.getSession(conversationId, scope);
     if (!agentSession) return;
 
     const piSession = agentSession.piSession;
@@ -428,7 +646,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
     // Emit to all clients currently subscribed to this conversation
     for (const [clientId, session] of this.clientSessions) {
-      if (session.conversationId === conversationId) {
+      if (session.conversationId === conversationId && this.scopesEqual(session.scope, scope)) {
         const socket = this.server.sockets.sockets.get(clientId);
         if (socket?.connected) {
           socket.emit('session:info', payload);
@@ -442,6 +660,233 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
    * Creates it if absent — safe to call concurrently since a duplicate insert
    * would fail on the PK constraint and be caught here.
    */
+  @SubscribeMessage('discord:approve')
+  async handleDiscordApproval(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() envelope: DiscordIngressEnvelope,
+  ): Promise<void> {
+    if (!client.data.discordService) return;
+    const ingress = this.resolveDiscordIngress(client, envelope, 'approve');
+    const isApprovalCommand = /^\/approve\s*$/i.test(ingress?.content ?? '');
+    const tenantId = process.env['DISCORD_SERVICE_TENANT_ID']?.trim();
+    if (
+      !ingress ||
+      !isApprovalCommand ||
+      !tenantId ||
+      !this.commandAuthorization ||
+      !this.durableSessions
+    )
+      return;
+    const binding = resolveDiscordInteractionBinding(
+      parseDiscordInteractionBindings(process.env['DISCORD_INTERACTION_BINDINGS']),
+      ingress.guildId,
+      ingress.channelId,
+      ingress.userId,
+      'approve',
+    );
+    const actorId = binding && resolveDiscordInteractionActorId(binding, ingress.userId);
+    const agentName = process.env['MOSAIC_AGENT_NAME']?.trim();
+    if (!actorId || !agentName || binding.instanceId !== agentName) {
+      this.logger.warn(
+        `Rejected Discord approval without a matching runtime agent from ${client.id}`,
+      );
+      client.emit('discord:approval', {
+        correlationId: ingress.correlationId,
+        success: false,
+        approvalId: undefined,
+        expiresAt: undefined,
+      });
+      return;
+    }
+    let snapshot;
+    try {
+      snapshot = await this.durableSessions.getSnapshot(ingress.conversationId, {
+        actorScope: { userId: actorId, tenantId },
+        channelId: ingress.channelId,
+        correlationId: ingress.correlationId,
+      });
+    } catch {
+      client.emit('discord:approval', {
+        correlationId: ingress.correlationId,
+        success: false,
+        approvalId: undefined,
+        expiresAt: undefined,
+      });
+      return;
+    }
+    if (snapshot.identity.agentName !== agentName) {
+      client.emit('discord:approval', {
+        correlationId: ingress.correlationId,
+        success: false,
+        approvalId: undefined,
+        expiresAt: undefined,
+      });
+      return;
+    }
+    const approval = await this.commandAuthorization.createRuntimeTerminationApproval({
+      providerId: snapshot.identity.providerId,
+      sessionId: snapshot.identity.runtimeSessionId,
+      actorId,
+      tenantId,
+      channelId: ingress.channelId,
+      correlationId: this.discordRuntimeActionCorrelation(
+        binding.instanceId,
+        ingress,
+        snapshot.identity.providerId,
+        snapshot.identity.runtimeSessionId,
+      ),
+      agentName,
+    });
+    if (!approval) {
+      await this.runtimeAudit?.record({
+        providerId: snapshot.identity.providerId,
+        operation: 'session.terminate',
+        outcome: 'denied',
+        actorId,
+        tenantId,
+        channelId: ingress.channelId,
+        correlationId: this.discordRuntimeActionCorrelation(
+          binding.instanceId,
+          ingress,
+          snapshot.identity.providerId,
+          snapshot.identity.runtimeSessionId,
+        ),
+        resourceId: snapshot.identity.runtimeSessionId,
+        errorCode: 'policy_denied',
+      });
+    }
+    client.emit('discord:approval', {
+      correlationId: ingress.correlationId,
+      success: approval !== null,
+      approvalId: approval?.approvalId,
+      expiresAt: approval?.expiresAt,
+    });
+  }
+
+  @SubscribeMessage('discord:stop')
+  async handleDiscordStop(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() envelope: DiscordIngressEnvelope,
+  ): Promise<void> {
+    if (!client.data.discordService) return;
+    const ingress = this.resolveDiscordIngress(client, envelope, 'stop');
+    const approvalRef = /^\/stop\s+([^\s]+)$/i.exec(ingress?.content ?? '')?.[1];
+    const tenantId = process.env['DISCORD_SERVICE_TENANT_ID']?.trim();
+    if (!ingress || !approvalRef || !tenantId || !this.runtimeRegistry || !this.durableSessions)
+      return;
+    const binding = resolveDiscordInteractionBinding(
+      parseDiscordInteractionBindings(process.env['DISCORD_INTERACTION_BINDINGS']),
+      ingress.guildId,
+      ingress.channelId,
+      ingress.userId,
+      'stop',
+    );
+    const actorId = binding && resolveDiscordInteractionActorId(binding, ingress.userId);
+    if (!actorId) return;
+
+    try {
+      const context = {
+        actorScope: { userId: actorId, tenantId },
+        channelId: ingress.channelId,
+        correlationId: ingress.correlationId,
+      };
+      const snapshot = await this.durableSessions.getSnapshot(ingress.conversationId, context);
+      if (snapshot.identity.agentName !== binding.instanceId) throw new Error('agent mismatch');
+      // RuntimeProviderService consumes the durable approval exactly once using the
+      // provisioned approving-admin identity, never the Discord service account.
+      await this.runtimeRegistry.terminate(
+        snapshot.identity.providerId,
+        snapshot.identity.runtimeSessionId,
+        approvalRef,
+        {
+          ...context,
+          correlationId: this.discordRuntimeActionCorrelation(
+            binding.instanceId,
+            ingress,
+            snapshot.identity.providerId,
+            snapshot.identity.runtimeSessionId,
+          ),
+        },
+      );
+      client.emit('discord:stop', { correlationId: ingress.correlationId, success: true });
+    } catch {
+      client.emit('discord:stop', { correlationId: ingress.correlationId, success: false });
+    }
+  }
+
+  /**
+   * Correlates the immutable termination target rather than either Discord message.
+   * Approval and stop are distinct ingress events, but must consume the same seven-field action.
+   */
+  private discordRuntimeActionCorrelation(
+    instanceId: string,
+    ingress: DiscordIngressPayload,
+    providerId: string,
+    sessionId: string,
+  ): string {
+    const target = [
+      instanceId,
+      ingress.guildId,
+      ingress.channelId,
+      ingress.conversationId,
+      providerId,
+      sessionId,
+    ];
+    return `discord-action:v1:${createHash('sha256').update(JSON.stringify(target)).digest('hex')}`;
+  }
+
+  private resolveDiscordIngress(
+    client: Socket,
+    envelope: DiscordIngressEnvelope,
+    operation: 'send' | 'approve' | 'stop' = 'send',
+  ): DiscordIngressPayload | null {
+    const payload = verifyDiscordIngressEnvelope(
+      envelope,
+      process.env['DISCORD_SERVICE_TOKEN'] ?? '',
+      {
+        guildIds: this.readDiscordAllowlist('DISCORD_ALLOWED_GUILD_IDS'),
+        channelIds: this.readDiscordAllowlist('DISCORD_ALLOWED_CHANNEL_IDS'),
+        userIds: this.readDiscordAllowlist('DISCORD_ALLOWED_USER_IDS'),
+      },
+    );
+    if (!payload) {
+      this.logger.warn(`Rejected invalid Discord ingress envelope from ${client.id}`);
+      return null;
+    }
+    try {
+      const binding = resolveDiscordInteractionBinding(
+        parseDiscordInteractionBindings(process.env['DISCORD_INTERACTION_BINDINGS']),
+        payload.guildId,
+        payload.channelId,
+        payload.userId,
+        operation,
+      );
+      if (!binding) {
+        this.logger.warn(`Rejected unpaired Discord ingress from ${client.id}`);
+        return null;
+      }
+    } catch {
+      this.logger.warn(
+        `Rejected Discord ingress without valid binding configuration from ${client.id}`,
+      );
+      return null;
+    }
+    if (!this.discordReplayProtector.claim(payload.messageId)) {
+      this.logger.warn(
+        `Rejected replayed Discord message=${payload.messageId} correlation=${payload.correlationId}`,
+      );
+      return null;
+    }
+    return payload;
+  }
+
+  private readDiscordAllowlist(name: string): string[] {
+    return (process.env[name] ?? '')
+      .split(',')
+      .map((id: string): string => id.trim())
+      .filter((id: string): boolean => id.length > 0);
+  }
+
   private async ensureConversation(conversationId: string, userId: string): Promise<void> {
     try {
       const existing = await this.brain.conversations.findById(conversationId, userId);
@@ -527,6 +972,127 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     }
   }
 
+  private appendAndFlushRedactedEgress(
+    client: Socket,
+    conversationId: string,
+    eventName: 'agent:text' | 'agent:thinking',
+    buffers: Map<string, string>,
+    delta: string,
+  ): void {
+    const key = this.egressKey(client, eventName);
+    if (this.overflowedEgress.has(key)) return;
+
+    const buffered = `${buffers.get(client.id) ?? ''}${delta}`;
+    if (buffered.length > MAX_REDACTION_BUFFER_LENGTH) {
+      buffers.delete(client.id);
+      this.overflowedEgress.add(key);
+      client.emit(eventName, { conversationId, text: '[REDACTED_STREAM_OVERFLOW]' });
+      return;
+    }
+
+    buffers.set(client.id, buffered);
+    this.flushRedactedEgress(client, conversationId, eventName, buffers, false);
+  }
+
+  /**
+   * Holds any suffix that could become a secret, email, or phone number after a
+   * later stream chunk. This avoids relying on downstream redaction after data
+   * has already reached the socket.
+   */
+  private flushRedactedEgress(
+    client: Socket,
+    conversationId: string,
+    eventName: 'agent:text' | 'agent:thinking',
+    buffers: Map<string, string>,
+    final: boolean,
+  ): void {
+    const key = this.egressKey(client, eventName);
+    if (this.overflowedEgress.has(key)) {
+      if (final) this.overflowedEgress.delete(key);
+      return;
+    }
+
+    const buffered = buffers.get(client.id) ?? '';
+    const releaseLength = final ? buffered.length : this.safeRedactionPrefixLength(buffered);
+    const released = buffered.slice(0, releaseLength);
+    const pending = buffered.slice(releaseLength);
+
+    if (pending) {
+      buffers.set(client.id, pending);
+    } else {
+      buffers.delete(client.id);
+    }
+
+    if (released) {
+      client.emit(eventName, {
+        conversationId,
+        text: redactSensitiveContent(released).content,
+      });
+    }
+  }
+
+  private safeRedactionPrefixLength(content: string): number {
+    let retainedFrom = content.length;
+
+    // Retain the current token because it may become a split secret or email.
+    const token = /(?:^|\s)(\S*)$/.exec(content);
+    if (token) {
+      const matched = token[0] ?? '';
+      const trailingToken = token[1] ?? '';
+      retainedFrom = token.index + matched.length - trailingToken.length;
+    }
+
+    // The secret classifier accepts whitespace around ':' and '=', so preserve
+    // a pending label until its value and delimiter are both complete.
+    const pendingSecretLabel =
+      /(?:^|[^A-Za-z0-9_])((?:api[_-]?key|token|password|secret|bearer|authorization)\s*)$/i.exec(
+        content,
+      );
+    if (pendingSecretLabel) {
+      const label = pendingSecretLabel[1] ?? '';
+      retainedFrom = Math.min(
+        retainedFrom,
+        pendingSecretLabel.index + pendingSecretLabel[0].length - label.length,
+      );
+    }
+
+    const secretLabel = /(?:api[_-]?key|token|password|secret|authorization)\s*[:=]\s*$/i.exec(
+      content,
+    );
+    if (secretLabel) {
+      retainedFrom = Math.min(retainedFrom, secretLabel.index);
+    }
+
+    // Phone numbers can contain whitespace and punctuation; preserve the full
+    // trailing numeric candidate until a non-phone character establishes a boundary.
+    const phone = /(?:^|[^A-Za-z0-9_])(\+?\d[\d(). -]*)$/.exec(content);
+    if (phone) {
+      const matched = phone[0] ?? '';
+      const trailingPhoneCandidate = phone[1] ?? '';
+      retainedFrom = Math.min(
+        retainedFrom,
+        phone.index + matched.length - trailingPhoneCandidate.length,
+      );
+    }
+
+    const privateKeyStart = content.lastIndexOf('-----BEGIN');
+    if (privateKeyStart >= 0) {
+      const privateKey = content.slice(privateKeyStart);
+      if (/-----END(?: [A-Z]+)* KEY-----/.test(privateKey)) {
+        // Release the complete block in one pass so the full-block classifier can redact it.
+        retainedFrom = content.length;
+      } else {
+        retainedFrom = Math.min(retainedFrom, privateKeyStart);
+      }
+    }
+
+    return retainedFrom;
+  }
+
+  private egressKey(client: Socket, eventName: 'agent:text' | 'agent:thinking'): string {
+    return `${client.id}:${eventName}`;
+  }
+
   private relayEvent(client: Socket, conversationId: string, event: AgentSessionEvent): void {
     if (!client.connected) {
       this.logger.warn(
@@ -544,13 +1110,20 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
           cs.toolCalls = [];
           cs.pendingToolCalls.clear();
         }
+        this.textEgressBuffers.set(client.id, '');
+        this.thinkingEgressBuffers.set(client.id, '');
+        this.overflowedEgress.delete(this.egressKey(client, 'agent:text'));
+        this.overflowedEgress.delete(this.egressKey(client, 'agent:thinking'));
         client.emit('agent:start', { conversationId });
         break;
       }
 
       case 'agent_end': {
         // Gather usage stats from the Pi session
-        const agentSession = this.agentService.getSession(conversationId);
+        const activeClientSession = this.clientSessions.get(client.id);
+        const agentSession = activeClientSession
+          ? this.agentService.getSession(conversationId, activeClientSession.scope)
+          : undefined;
         const piSession = agentSession?.piSession;
         const stats = piSession?.getSessionStats();
         const contextUsage = piSession?.getContextUsage();
@@ -569,6 +1142,20 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
             }
           : undefined;
 
+        this.flushRedactedEgress(
+          client,
+          conversationId,
+          'agent:text',
+          this.textEgressBuffers,
+          true,
+        );
+        this.flushRedactedEgress(
+          client,
+          conversationId,
+          'agent:thinking',
+          this.thinkingEgressBuffers,
+          true,
+        );
         client.emit('agent:end', {
           conversationId,
           usage: usagePayload,
@@ -611,8 +1198,11 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
               {
                 conversationId,
                 role: 'assistant',
-                content: cs.assistantText,
-                metadata,
+                content: redactSensitiveContent(cs.assistantText).content,
+                metadata: {
+                  ...metadata,
+                  classifications: redactSensitiveContent(cs.assistantText).classifications,
+                },
               },
               userId,
             )
@@ -634,20 +1224,26 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       case 'message_update': {
         const assistantEvent = event.assistantMessageEvent;
         if (assistantEvent.type === 'text_delta') {
-          // Accumulate assistant text for persistence
+          // Keep raw stream material in memory only; persist and emit only redacted text.
           const cs = this.clientSessions.get(client.id);
           if (cs) {
             cs.assistantText += assistantEvent.delta;
           }
-          client.emit('agent:text', {
+          this.appendAndFlushRedactedEgress(
+            client,
             conversationId,
-            text: assistantEvent.delta,
-          });
+            'agent:text',
+            this.textEgressBuffers,
+            assistantEvent.delta,
+          );
         } else if (assistantEvent.type === 'thinking_delta') {
-          client.emit('agent:thinking', {
+          this.appendAndFlushRedactedEgress(
+            client,
             conversationId,
-            text: assistantEvent.delta,
-          });
+            'agent:thinking',
+            this.thinkingEgressBuffers,
+            assistantEvent.delta,
+          );
         }
         break;
       }

apps/gateway/src/commands/command-authorization.service.spec.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import type { CommandDef, SlashCommandPayload } from '@mosaicstack/types';
+import { CommandAuthorizationService } from './command-authorization.service.js';
+
+const adminCommand: CommandDef = {
+  name: 'gc',
+  description: 'GC',
+  aliases: [],
+  scope: 'admin',
+  execution: 'socket',
+  available: true,
+};
+const payload: SlashCommandPayload = { command: 'gc', conversationId: 'conversation-1' };
+
+function createService(
+  role: string,
+  entries: Map<string, string> = new Map<string, string>(),
+): CommandAuthorizationService {
+  const db = {
+    select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role }] }) }) }),
+  };
+  const redis = {
+    get: async (key: string) => entries.get(key) ?? null,
+    set: async (key: string, value: string) => {
+      entries.set(key, value);
+    },
+    del: async (key: string) => Number(entries.delete(key)),
+  };
+  return new CommandAuthorizationService(db as never, redis);
+}
+
+describe('CommandAuthorizationService', () => {
+  it('consumes one exact actor-bound approval once', async (): Promise<void> => {
+    const service = createService('admin');
+    const approval = await service.createApproval(adminCommand, payload, 'admin-1');
+    expect(approval).not.toBeNull();
+    expect(
+      (await service.authorize(adminCommand, payload, 'admin-1', approval!.approvalId)).allowed,
+    ).toBe(true);
+    expect(
+      (await service.authorize(adminCommand, payload, 'admin-1', approval!.approvalId)).allowed,
+    ).toBe(false);
+  });
+
+  it('rejects an approval when the structured action is mutated', async (): Promise<void> => {
+    const service = createService('admin');
+    const approval = await service.createApproval(adminCommand, payload, 'admin-1');
+    const mutated = { ...payload, conversationId: 'other-conversation' };
+    expect(approval).not.toBeNull();
+    expect(
+      (await service.authorize(adminCommand, mutated, 'admin-1', approval!.approvalId)).allowed,
+    ).toBe(false);
+  });
+
+  it('denies an admin command to a member before approval is considered', async (): Promise<void> => {
+    const service = createService('member');
+    const approval = await service.createApproval(adminCommand, payload, 'member-1');
+    expect(approval).toBeNull();
+    expect(
+      (await service.authorize(adminCommand, payload, 'member-1', 'forged-approval-id')).allowed,
+    ).toBe(false);
+  });
+
+  it('denies a malformed durable approval expiry instead of treating it as unexpired', async (): Promise<void> => {
+    const entries = new Map<string, string>();
+    const action = {
+      providerId: 'fleet',
+      sessionId: 'nova',
+      actorId: 'admin-1',
+      tenantId: 'tenant-1',
+      channelId: 'discord:operator',
+      correlationId: 'correlation-malformed-expiry',
+      agentName: 'Nova',
+    };
+    const service = createService('admin', entries);
+    const approval = await service.createRuntimeTerminationApproval(action);
+    expect(approval).not.toBeNull();
+    const key = `agent:Nova:command-approval:${approval!.approvalId}`;
+    const stored = entries.get(key);
+    expect(stored).toBeDefined();
+    entries.set(key, JSON.stringify({ ...JSON.parse(stored!), expiresAt: 'not-a-date' }));
+
+    expect(await service.consumeRuntimeTerminationApproval(approval!.approvalId, action)).toBe(
+      false,
+    );
+  });
+
+  it('persists and consumes one exact runtime termination approval across a service restart', async (): Promise<void> => {
+    const entries = new Map<string, string>();
+    const action = {
+      providerId: 'fleet',
+      sessionId: 'nova',
+      actorId: 'admin-1',
+      tenantId: 'tenant-1',
+      channelId: 'discord:operator',
+      correlationId: 'correlation-1',
+      agentName: 'Nova',
+    };
+    const beforeRestart = createService('admin', entries);
+    const approval = await beforeRestart.createRuntimeTerminationApproval(action);
+
+    const afterRestart = createService('admin', entries);
+    expect(
+      await afterRestart.consumeRuntimeTerminationApproval(approval!.approvalId, {
+        ...action,
+        sessionId: 'forged-session',
+      }),
+    ).toBe(false);
+    expect(await afterRestart.consumeRuntimeTerminationApproval(approval!.approvalId, action)).toBe(
+      true,
+    );
+    expect(await afterRestart.consumeRuntimeTerminationApproval(approval!.approvalId, action)).toBe(
+      false,
+    );
+  });
+});

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

@@ -0,0 +1,268 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import { eq, users as usersTable, type Db } from '@mosaicstack/db';
+import type { CommandDef, SlashCommandPayload } from '@mosaicstack/types';
+import { DB } from '../database/database.module.js';
+import { COMMANDS_REDIS } from './commands.tokens.js';
+
+export type CommandRole = 'admin' | 'member' | 'viewer';
+
+export interface CommandApproval {
+  approvalId: string;
+  actionDigest: string;
+  actorId: string;
+  command: string;
+  expiresAt: string;
+}
+
+/** Exact immutable binding for a privileged runtime termination. */
+export interface RuntimeTerminationApprovalAction {
+  providerId: string;
+  sessionId: string;
+  actorId: string;
+  tenantId: string;
+  channelId: string;
+  correlationId: string;
+  /** Provisioned roster identity; isolates approvals between interaction agents. */
+  agentName: string;
+}
+
+export interface RuntimeTerminationApproval extends RuntimeTerminationApprovalAction {
+  approvalId: string;
+  actionDigest: string;
+  expiresAt: string;
+}
+
+export interface CommandAuthorizationResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+@Injectable()
+export class CommandAuthorizationService {
+  constructor(
+    @Inject(DB) private readonly db: Db,
+    @Inject(COMMANDS_REDIS)
+    private readonly redis: {
+      get(key: string): Promise<string | null>;
+      set(key: string, value: string, ...args: string[]): Promise<unknown>;
+      del(key: string): Promise<number>;
+    },
+  ) {}
+
+  async authorize(
+    command: CommandDef,
+    payload: SlashCommandPayload,
+    actorId: string,
+    approvalId?: string,
+  ): Promise<CommandAuthorizationResult> {
+    const role = await this.resolveRole(actorId);
+    if (!role || !this.hasScope(role, command.scope)) {
+      return { allowed: false, reason: 'not authorized for this command scope' };
+    }
+    if (command.scope !== 'admin') return { allowed: true };
+    if (!approvalId) return { allowed: false, reason: 'durable approval is required' };
+    const actionDigest = this.actionDigest(command.name, payload);
+    const approved = await this.consumeApproval(approvalId, actorId, actionDigest);
+    return approved
+      ? { allowed: true }
+      : {
+          allowed: false,
+          reason: 'approval is invalid, expired, replayed, or does not match this action',
+        };
+  }
+
+  async createApproval(
+    command: CommandDef,
+    payload: SlashCommandPayload,
+    actorId: string,
+  ): Promise<CommandApproval | null> {
+    const role = await this.resolveRole(actorId);
+    if (!role || command.scope !== 'admin' || !this.hasScope(role, command.scope)) return null;
+
+    const approvalId = randomUUID();
+    const expiresAt = new Date(Date.now() + 5 * 60_000).toISOString();
+    const approval: CommandApproval = {
+      approvalId,
+      actionDigest: this.actionDigest(command.name, payload),
+      actorId,
+      command: command.name,
+      expiresAt,
+    };
+    await this.redis.set(this.key(approvalId), JSON.stringify(approval), 'EX', '300');
+    return approval;
+  }
+
+  /**
+   * Uses the same `interaction:command-approval:*` store and one-time deletion rule as
+   * command approvals. This deliberately avoids a parallel approval database.
+   */
+  async createRuntimeTerminationApproval(
+    action: RuntimeTerminationApprovalAction,
+  ): Promise<RuntimeTerminationApproval | null> {
+    if (!this.hasRuntimeTerminationAction(action)) return null;
+    const role = await this.resolveRole(action.actorId);
+    if (role !== 'admin') return null;
+
+    const approval: RuntimeTerminationApproval = {
+      approvalId: randomUUID(),
+      actionDigest: this.runtimeActionDigest(action),
+      ...action,
+      expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),
+    };
+    await this.redis.set(
+      this.runtimeKey(action.agentName, approval.approvalId),
+      JSON.stringify(approval),
+      'EX',
+      '300',
+    );
+    return approval;
+  }
+
+  async consumeRuntimeTerminationApproval(
+    approvalId: string,
+    action: RuntimeTerminationApprovalAction,
+  ): Promise<boolean> {
+    const encoded = await this.redis.get(this.runtimeKey(action.agentName, approvalId));
+    if (!encoded) return false;
+    let approval: unknown;
+    try {
+      approval = JSON.parse(encoded);
+    } catch {
+      return false;
+    }
+    if (
+      !this.isRuntimeTerminationApproval(approval) ||
+      approval.actionDigest !== this.runtimeActionDigest(action) ||
+      approval.actorId !== action.actorId ||
+      approval.tenantId !== action.tenantId ||
+      !this.isUnexpired(approval.expiresAt)
+    ) {
+      return false;
+    }
+    if ((await this.resolveRole(approval.actorId)) !== 'admin') return false;
+    return (await this.redis.del(this.runtimeKey(action.agentName, approvalId))) === 1;
+  }
+
+  private async resolveRole(actorId: string): Promise<CommandRole | null> {
+    const [user] = await this.db
+      .select({ role: usersTable.role })
+      .from(usersTable)
+      .where(eq(usersTable.id, actorId))
+      .limit(1);
+    const role = user?.role;
+    return role === 'admin' || role === 'member' || role === 'viewer' ? role : null;
+  }
+
+  private hasScope(role: CommandRole, scope: CommandDef['scope']): boolean {
+    if (role === 'admin') return true;
+    return role === 'member' && (scope === 'core' || scope === 'agent');
+  }
+
+  private async consumeApproval(
+    approvalId: string,
+    actorId: string,
+    actionDigest: string,
+  ): Promise<boolean> {
+    const key = this.key(approvalId);
+    const encoded = await this.redis.get(key);
+    if (!encoded) return false;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(encoded);
+    } catch {
+      return false;
+    }
+    if (
+      !this.isCommandApproval(parsed) ||
+      parsed.actorId !== actorId ||
+      parsed.actionDigest !== actionDigest ||
+      !this.isUnexpired(parsed.expiresAt)
+    )
+      return false;
+    return (await this.redis.del(key)) === 1;
+  }
+
+  private actionDigest(command: string, payload: SlashCommandPayload): string {
+    return createHash('sha256')
+      .update(
+        JSON.stringify({
+          command,
+          args: payload.args?.trim() ?? '',
+          conversationId: payload.conversationId,
+        }),
+      )
+      .digest('hex');
+  }
+
+  private hasRuntimeTerminationAction(action: RuntimeTerminationApprovalAction): boolean {
+    return [
+      action.providerId,
+      action.sessionId,
+      action.actorId,
+      action.tenantId,
+      action.channelId,
+      action.correlationId,
+      action.agentName,
+    ].every((value: string): boolean => value.trim().length > 0);
+  }
+
+  private runtimeActionDigest(action: RuntimeTerminationApprovalAction): string {
+    return createHash('sha256')
+      .update(
+        JSON.stringify({
+          providerId: action.providerId,
+          sessionId: action.sessionId,
+          actorId: action.actorId,
+          tenantId: action.tenantId,
+          channelId: action.channelId,
+          correlationId: action.correlationId,
+          agentName: action.agentName,
+        }),
+      )
+      .digest('hex');
+  }
+
+  private isUnexpired(expiresAt: unknown): expiresAt is string {
+    if (typeof expiresAt !== 'string') return false;
+    const expiresAtMs = Date.parse(expiresAt);
+    return Number.isFinite(expiresAtMs) && expiresAtMs > Date.now();
+  }
+
+  private isCommandApproval(value: unknown): value is CommandApproval {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      'approvalId' in value &&
+      'actionDigest' in value &&
+      'actorId' in value &&
+      'expiresAt' in value &&
+      'command' in value
+    );
+  }
+
+  private isRuntimeTerminationApproval(value: unknown): value is RuntimeTerminationApproval {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      'approvalId' in value &&
+      'actionDigest' in value &&
+      'actorId' in value &&
+      'tenantId' in value &&
+      'providerId' in value &&
+      'sessionId' in value &&
+      'channelId' in value &&
+      'correlationId' in value &&
+      'agentName' in value &&
+      'expiresAt' in value
+    );
+  }
+
+  private key(approvalId: string): string {
+    return `interaction:command-approval:${approvalId}`;
+  }
+
+  private runtimeKey(agentName: string, approvalId: string): string {
+    return `agent:${encodeURIComponent(agentName)}:command-approval:${approvalId}`;
+  }
+}

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

@@ -89,6 +89,7 @@ function buildService(): CommandExecutorService {
 describe('CommandExecutorService — P8-012 commands', () => {
   let service: CommandExecutorService;
   const userId = 'user-123';
+  const userScope = { userId, tenantId: userId };
   const conversationId = 'conv-456';
 
   beforeEach(() => {
@@ -99,31 +100,26 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider login — missing provider name
   it('/provider login with no provider name returns usage error', async () => {
     const payload: SlashCommandPayload = { command: 'provider', args: 'login', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('Usage: /provider login');
     expect(result.command).toBe('provider');
   });
 
-  // /provider login anthropic — success with URL containing poll token
-  it('/provider login <name> returns success with URL and poll token', async () => {
+  // /provider login anthropic — no bearer token or auth URL reaches chat output
+  it('/provider login <name> keeps its one-time token out of chat output', async () => {
     const payload: SlashCommandPayload = {
       command: 'provider',
       args: 'login anthropic',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('provider');
     expect(result.message).toContain('anthropic');
-    expect(result.message).toContain('http');
-    // data should contain loginUrl and pollToken
-    expect(result.data).toBeDefined();
-    const data = result.data as Record<string, unknown>;
-    expect(typeof data['loginUrl']).toBe('string');
-    expect(typeof data['pollToken']).toBe('string');
-    expect(data['loginUrl'] as string).toContain('anthropic');
-    expect(data['loginUrl'] as string).toContain(data['pollToken'] as string);
+    expect(result.message).not.toContain('http');
+    expect(result.message).not.toContain('token=');
+    expect(result.data).toEqual({ provider: 'anthropic' });
     // Verify Valkey was called
     expect(mockRedis.set).toHaveBeenCalledOnce();
     const [key, value, , ttl] = mockRedis.set.mock.calls[0] as [string, string, string, number];
@@ -138,7 +134,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider with no args — returns usage
   it('/provider with no args returns usage message', async () => {
     const payload: SlashCommandPayload = { command: 'provider', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Usage: /provider');
   });
@@ -146,7 +142,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider list
   it('/provider list returns success', async () => {
     const payload: SlashCommandPayload = { command: 'provider', args: 'list', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('provider');
   });
@@ -154,7 +150,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider logout with no name — usage error
   it('/provider logout with no name returns error', async () => {
     const payload: SlashCommandPayload = { command: 'provider', args: 'logout', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('Usage: /provider logout');
   });
@@ -166,7 +162,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
       args: 'unknown',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('Unknown subcommand');
   });
@@ -174,7 +170,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /mission status
   it('/mission status returns stub message', async () => {
     const payload: SlashCommandPayload = { command: 'mission', args: 'status', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('mission');
     expect(result.message).toContain('Mission status');
@@ -183,7 +179,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /mission with no args
   it('/mission with no args returns status stub', async () => {
     const payload: SlashCommandPayload = { command: 'mission', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Mission status');
   });
@@ -195,7 +191,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
       args: 'set my-mission-123',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('my-mission-123');
   });
@@ -203,7 +199,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /agent list
   it('/agent list returns stub message', async () => {
     const payload: SlashCommandPayload = { command: 'agent', args: 'list', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('agent');
     expect(result.message).toContain('agent');
@@ -212,7 +208,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /agent with no args
   it('/agent with no args returns usage', async () => {
     const payload: SlashCommandPayload = { command: 'agent', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Usage: /agent');
   });
@@ -224,7 +220,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
       args: 'my-agent-id',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('my-agent-id');
   });
@@ -232,7 +228,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /prdy
   it('/prdy returns PRD wizard message', async () => {
     const payload: SlashCommandPayload = { command: 'prdy', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('prdy');
     expect(result.message).toContain('mosaic prdy');
@@ -241,7 +237,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /tools
   it('/tools returns tools stub message', async () => {
     const payload: SlashCommandPayload = { command: 'tools', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('tools');
     expect(result.message).toContain('tools');

apps/gateway/src/commands/command-executor-tess-security.spec.ts

@@ -0,0 +1,112 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SlashCommandPayload } from '@mosaicstack/types';
+import { CommandAuthorizationService } from './command-authorization.service.js';
+import { CommandExecutorService } from './command-executor.service.js';
+
+const registry = {
+  getManifest: vi.fn(() => ({
+    version: 1,
+    commands: [
+      {
+        name: 'gc',
+        description: 'System-wide garbage collection',
+        aliases: [],
+        scope: 'admin' as const,
+        execution: 'socket' as const,
+        available: true,
+      },
+    ],
+    skills: [],
+  })),
+};
+
+const sessionGc = {
+  sweepOrphans: vi.fn().mockResolvedValue({ orphanedSessions: 1, totalCleaned: [], duration: 1 }),
+};
+
+const scope = (userId: string) => ({ userId, tenantId: 'tenant-1' });
+
+const authorization = {
+  authorize: vi.fn((_command: unknown, _payload: unknown, actorId: string) =>
+    Promise.resolve(
+      actorId === 'member-1'
+        ? { allowed: false, reason: 'durable approval is required' }
+        : { allowed: false, reason: 'not authorized for this command scope' },
+    ),
+  ),
+};
+
+function buildExecutor(authorizationService: unknown = authorization): CommandExecutorService {
+  return new CommandExecutorService(
+    registry as never,
+    { getSession: vi.fn() } as never,
+    { clear: vi.fn(), set: vi.fn() } as never,
+    sessionGc as never,
+    { set: vi.fn() } as never,
+    { agents: {} } as never,
+    null,
+    null,
+    null,
+    authorizationService as never,
+  );
+}
+
+function createDurableAuthorization(): CommandAuthorizationService {
+  const entries = new Map<string, string>();
+  const db = {
+    select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role: 'admin' }] }) }) }),
+  };
+  const redis = {
+    get: async (key: string) => entries.get(key) ?? null,
+    set: async (key: string, value: string) => {
+      entries.set(key, value);
+    },
+    del: async (key: string) => Number(entries.delete(key)),
+  };
+  return new CommandAuthorizationService(db as never, redis);
+}
+
+describe('TESS-M1-SEC-001 command authorization abuse cases', () => {
+  const payload: SlashCommandPayload = { command: 'gc', conversationId: 'conversation-1' };
+
+  beforeEach((): void => {
+    vi.clearAllMocks();
+  });
+
+  it('denies a forged admin identity and does not execute a system-wide command', async (): Promise<void> => {
+    const result = await buildExecutor().execute(payload, scope('admin-forged-by-client'));
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('not authorized');
+    expect(sessionGc.sweepOrphans).not.toHaveBeenCalled();
+  });
+
+  it('denies a privileged command without a server-bound durable approval', async (): Promise<void> => {
+    const result = await buildExecutor().execute(payload, scope('member-1'));
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('approval');
+    expect(sessionGc.sweepOrphans).not.toHaveBeenCalled();
+  });
+
+  it('executes an admin command only after a valid durable approval is issued and supplied', async (): Promise<void> => {
+    const executor = buildExecutor(createDurableAuthorization());
+
+    const adminScope = scope('admin-1');
+    const denied = await executor.execute(payload, adminScope);
+    const approval = await executor.createApproval(payload, adminScope);
+    const approved = await executor.execute(
+      { ...payload, approvalId: approval?.approvalId },
+      adminScope,
+    );
+
+    expect(denied.success).toBe(false);
+    expect(denied.message).toContain('approval');
+    expect(approval).not.toBeNull();
+    // A valid durable approval is consumed, but cannot authorize an unimplemented
+    // global retention operation. Session-scoped cleanup remains lifecycle-only.
+    expect(approved.success).toBe(false);
+    expect(approved.message).toContain('Global GC is disabled');
+    expect(sessionGc.sweepOrphans).not.toHaveBeenCalled();
+  });
+});

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

@@ -3,6 +3,7 @@ import type { QueueHandle } from '@mosaicstack/queue';
 import type { Brain } from '@mosaicstack/brain';
 import type { SlashCommandPayload, SlashCommandResultPayload } from '@mosaicstack/types';
 import { AgentService } from '../agent/agent.service.js';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 import { ChatGateway } from '../chat/chat.gateway.js';
 import { SessionGCService } from '../gc/session-gc.service.js';
 import { SystemOverrideService } from '../preferences/system-override.service.js';
@@ -10,6 +11,7 @@ import { ReloadService } from '../reload/reload.service.js';
 import { McpClientService } from '../mcp-client/mcp-client.service.js';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { COMMANDS_REDIS } from './commands.tokens.js';
+import { CommandAuthorizationService } from './command-authorization.service.js';
 import { CommandRegistryService } from './command-registry.service.js';
 
 @Injectable()
@@ -21,10 +23,7 @@ export class CommandExecutorService {
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(SystemOverrideService) private readonly systemOverride: SystemOverrideService,
     @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
-    // On Local tier COMMANDS_REDIS is null — provider login caching is skipped.
-    @Optional()
-    @Inject(COMMANDS_REDIS)
-    private readonly redis: QueueHandle['redis'] | null,
+    @Inject(COMMANDS_REDIS) private readonly redis: QueueHandle['redis'],
     @Inject(BRAIN) private readonly brain: Brain,
     @Optional()
     @Inject(forwardRef(() => ReloadService))
@@ -35,10 +34,17 @@ export class CommandExecutorService {
     @Optional()
     @Inject(McpClientService)
     private readonly mcpClient: McpClientService | null,
+    @Optional()
+    @Inject(CommandAuthorizationService)
+    private readonly authorization: CommandAuthorizationService | null = null,
   ) {}
 
-  async execute(payload: SlashCommandPayload, userId: string): Promise<SlashCommandResultPayload> {
+  async execute(
+    payload: SlashCommandPayload,
+    scope: ActorTenantScope,
+  ): Promise<SlashCommandResultPayload> {
     const { command, args, conversationId } = payload;
+    const userId = scope.userId;
 
     const def = this.registry.getManifest().commands.find((c) => c.name === command);
     if (!def) {
@@ -50,14 +56,24 @@ export class CommandExecutorService {
       };
     }
 
+    const authorization = await this.authorization?.authorize(
+      def,
+      payload,
+      userId,
+      payload.approvalId,
+    );
+    if (authorization && !authorization.allowed) {
+      return { command, conversationId, success: false, message: authorization.reason };
+    }
+
     try {
       switch (command) {
         case 'model':
-          return await this.handleModel(args ?? null, conversationId);
+          return await this.handleModel(args ?? null, conversationId, scope);
         case 'thinking':
           return await this.handleThinking(args ?? null, conversationId);
         case 'system':
-          return await this.handleSystem(args ?? null, conversationId);
+          return await this.handleSystem(args ?? null, conversationId, scope);
         case 'new':
           return {
             command,
@@ -86,18 +102,17 @@ export class CommandExecutorService {
             success: true,
             message: 'Retry last message requested.',
           };
-        case 'gc': {
-          // Admin-only: system-wide GC sweep across all sessions
-          const result = await this.sessionGC.sweepOrphans();
+        case 'gc':
+          // Global retention requires a separate, authorized and audited job.
+          // Session cleanup is performed only through the session lifecycle.
           return {
             command: 'gc',
-            success: true,
-            message: `GC sweep complete: ${result.orphanedSessions} orphaned sessions cleaned in ${result.duration}ms.`,
+            success: false,
+            message: 'Global GC is disabled pending an authorized retention job.',
             conversationId,
           };
-        }
         case 'agent':
-          return await this.handleAgent(args ?? null, conversationId, userId);
+          return await this.handleAgent(args ?? null, conversationId, scope);
         case 'provider':
           return await this.handleProvider(args ?? null, userId, conversationId);
         case 'mission':
@@ -146,13 +161,22 @@ export class CommandExecutorService {
     }
   }
 
+  async createApproval(payload: SlashCommandPayload, scope: ActorTenantScope) {
+    const def = this.registry
+      .getManifest()
+      .commands.find((command) => command.name === payload.command);
+    if (!def || !this.authorization) return null;
+    return this.authorization.createApproval(def, payload, scope.userId);
+  }
+
   private async handleModel(
     args: string | null,
     conversationId: string,
+    scope: ActorTenantScope,
   ): Promise<SlashCommandResultPayload> {
     if (!args || args.trim().length === 0) {
       // Show current override or usage hint
-      const currentOverride = this.chatGateway?.getModelOverride(conversationId);
+      const currentOverride = this.chatGateway?.getModelOverride(conversationId, scope);
       if (currentOverride) {
         return {
           command: 'model',
@@ -174,7 +198,7 @@ export class CommandExecutorService {
 
     // /model clear removes the override and re-enables automatic routing
     if (modelName === 'clear') {
-      this.chatGateway?.setModelOverride(conversationId, null);
+      this.chatGateway?.setModelOverride(conversationId, null, scope);
       return {
         command: 'model',
         conversationId,
@@ -184,9 +208,9 @@ export class CommandExecutorService {
     }
 
     // Set the sticky per-session override (M4-007)
-    this.chatGateway?.setModelOverride(conversationId, modelName);
+    this.chatGateway?.setModelOverride(conversationId, modelName, scope);
 
-    const session = this.agentService.getSession(conversationId);
+    const session = this.agentService.getSession(conversationId, scope);
     if (!session) {
       return {
         command: 'model',
@@ -227,10 +251,11 @@ export class CommandExecutorService {
   private async handleSystem(
     args: string | null,
     conversationId: string,
+    scope: ActorTenantScope,
   ): Promise<SlashCommandResultPayload> {
     if (!args || args.trim().length === 0) {
       // Clear the override when called with no args
-      await this.systemOverride.clear(conversationId);
+      await this.systemOverride.clear(conversationId, scope);
       return {
         command: 'system',
         conversationId,
@@ -239,7 +264,7 @@ export class CommandExecutorService {
       };
     }
 
-    await this.systemOverride.set(conversationId, args.trim());
+    await this.systemOverride.set(conversationId, args.trim(), scope);
     return {
       command: 'system',
       conversationId,
@@ -251,8 +276,9 @@ export class CommandExecutorService {
   private async handleAgent(
     args: string | null,
     conversationId: string,
-    userId: string,
+    scope: ActorTenantScope,
   ): Promise<SlashCommandResultPayload> {
+    const userId = scope.userId;
     if (!args) {
       return {
         command: 'agent',
@@ -341,11 +367,14 @@ export class CommandExecutorService {
         conversationId,
         agentConfig.id,
         agentConfig.name,
+        scope,
         agentConfig.model ?? undefined,
       );
 
       // Broadcast updated session:info so TUI TopBar reflects new agent/model
-      this.chatGateway?.broadcastSessionInfo(conversationId, { agentName: agentConfig.name });
+      this.chatGateway?.broadcastSessionInfo(conversationId, scope, {
+        agentName: agentConfig.name,
+      });
 
       this.logger.log(
         `Agent switched to "${agentConfig.name}" (${agentConfig.id}) for conversation ${conversationId} (M5-003)`,
@@ -406,24 +435,28 @@ export class CommandExecutorService {
           };
         }
         const pollToken = crypto.randomUUID();
-        const pollKey = `mosaic:auth:poll:${pollToken}`;
-        if (this.redis) {
-          // Store pending state in Valkey (TTL 5 minutes)
-          await this.redis.set(
-            pollKey,
-            JSON.stringify({ status: 'pending', provider: providerName, userId }),
-            'EX',
-            300,
-          );
-        }
-        // In production this would construct an OAuth URL
-        const loginUrl = `${process.env['MOSAIC_BASE_URL'] ?? 'http://localhost:3000'}/auth/provider/${providerName}?token=${pollToken}`;
+        const tokenDigest = await crypto.subtle.digest(
+          'SHA-256',
+          new TextEncoder().encode(pollToken),
+        );
+        const tokenHash = Array.from(new Uint8Array(tokenDigest), (byte: number): string =>
+          byte.toString(16).padStart(2, '0'),
+        ).join('');
+        const key = `mosaic:auth:poll:${tokenHash}`;
+        // Persist only a short-lived token digest. The raw token is delivered only by
+        // the authenticated dashboard flow, never in chat output or command metadata.
+        await this.redis.set(
+          key,
+          JSON.stringify({ status: 'pending', provider: providerName, userId }),
+          'EX',
+          300,
+        );
         return {
           command: 'provider',
           success: true,
-          message: `Open this URL to authenticate with ${providerName}:\n${loginUrl}`,
+          message: `Provider login for ${providerName} is ready. Continue in the authenticated dashboard.`,
           conversationId,
-          data: { loginUrl, pollToken, provider: providerName },
+          data: { provider: providerName },
         };
       }
 

apps/gateway/src/commands/commands.integration.spec.ts

@@ -159,6 +159,7 @@ describe('CommandExecutorService — integration', () => {
   let registry: CommandRegistryService;
   let executor: CommandExecutorService;
   const userId = 'user-integ-001';
+  const userScope = { userId, tenantId: userId };
   const conversationId = 'conv-integ-001';
 
   beforeEach(() => {
@@ -170,28 +171,26 @@ describe('CommandExecutorService — integration', () => {
   // Unknown command returns error
   it('unknown command returns success:false with descriptive message', async () => {
     const payload: SlashCommandPayload = { command: 'nonexistent', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('nonexistent');
     expect(result.command).toBe('nonexistent');
   });
 
-  // /gc handler calls SessionGCService.sweepOrphans (admin-only, no userId arg)
-  it('/gc calls SessionGCService.sweepOrphans without arguments', async () => {
+  it('/gc refuses an unaudited global sweep', async () => {
     const payload: SlashCommandPayload = { command: 'gc', conversationId };
-    const result = await executor.execute(payload, userId);
-    expect(mockSessionGC.sweepOrphans).toHaveBeenCalledWith();
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('GC sweep complete');
-    expect(result.message).toContain('3 orphaned sessions');
+    const result = await executor.execute(payload, userScope);
+    expect(mockSessionGC.sweepOrphans).not.toHaveBeenCalled();
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('disabled pending an authorized retention job');
   });
 
   // /system with args calls SystemOverrideService.set
   it('/system with text calls SystemOverrideService.set', async () => {
     const override = 'You are a helpful assistant.';
     const payload: SlashCommandPayload = { command: 'system', args: override, conversationId };
-    const result = await executor.execute(payload, userId);
-    expect(mockSystemOverride.set).toHaveBeenCalledWith(conversationId, override);
+    const result = await executor.execute(payload, userScope);
+    expect(mockSystemOverride.set).toHaveBeenCalledWith(conversationId, override, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('override set');
   });
@@ -199,8 +198,8 @@ describe('CommandExecutorService — integration', () => {
   // /system with no args clears the override
   it('/system with no args calls SystemOverrideService.clear', async () => {
     const payload: SlashCommandPayload = { command: 'system', conversationId };
-    const result = await executor.execute(payload, userId);
-    expect(mockSystemOverride.clear).toHaveBeenCalledWith(conversationId);
+    const result = await executor.execute(payload, userScope);
+    expect(mockSystemOverride.clear).toHaveBeenCalledWith(conversationId, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('cleared');
   });
@@ -212,7 +211,7 @@ describe('CommandExecutorService — integration', () => {
       args: 'claude-3-opus',
       conversationId,
     };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('model');
     expect(result.message).toContain('claude-3-opus');
@@ -221,7 +220,7 @@ describe('CommandExecutorService — integration', () => {
   // /thinking with valid level returns success
   it('/thinking with valid level returns success', async () => {
     const payload: SlashCommandPayload = { command: 'thinking', args: 'high', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('high');
   });
@@ -229,7 +228,7 @@ describe('CommandExecutorService — integration', () => {
   // /thinking with invalid level returns usage message
   it('/thinking with invalid level returns usage message', async () => {
     const payload: SlashCommandPayload = { command: 'thinking', args: 'invalid', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Usage:');
   });
@@ -237,7 +236,7 @@ describe('CommandExecutorService — integration', () => {
   // /new command returns success
   it('/new returns success', async () => {
     const payload: SlashCommandPayload = { command: 'new', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('new');
   });
@@ -245,7 +244,7 @@ describe('CommandExecutorService — integration', () => {
   // /reload without reloadService returns failure
   it('/reload without ReloadService returns failure', async () => {
     const payload: SlashCommandPayload = { command: 'reload', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('ReloadService');
   });
@@ -255,7 +254,7 @@ describe('CommandExecutorService — integration', () => {
   for (const cmd of stubCommands) {
     it(`/${cmd} returns success (stub)`, async () => {
       const payload: SlashCommandPayload = { command: cmd, conversationId };
-      const result = await executor.execute(payload, userId);
+      const result = await executor.execute(payload, userScope);
       expect(result.success).toBe(true);
       expect(result.command).toBe(cmd);
     });

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

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

apps/gateway/src/commands/runtime-approval-verifier.ts

@@ -0,0 +1,23 @@
+import { Inject, Injectable } from '@nestjs/common';
+import type {
+  RuntimeApprovalVerifier,
+  RuntimeTerminationAction,
+} from '../agent/runtime-provider-registry.service.js';
+import { CommandAuthorizationService } from './command-authorization.service.js';
+
+/**
+ * Adapter from the provider registry's exact termination action to the shared,
+ * Redis-backed `interaction:command-approval:*` store. It has no separate approval
+ * persistence or replay semantics.
+ */
+@Injectable()
+export class CommandRuntimeApprovalVerifier implements RuntimeApprovalVerifier {
+  constructor(
+    @Inject(CommandAuthorizationService)
+    private readonly authorization: CommandAuthorizationService,
+  ) {}
+
+  async consume(approvalRef: string, action: RuntimeTerminationAction): Promise<boolean> {
+    return this.authorization.consumeRuntimeTerminationApproval(approvalRef, action);
+  }
+}

apps/gateway/src/coord/coord.module.ts

@@ -1,10 +1,32 @@
 import { Module } from '@nestjs/common';
+import { InMemoryInteractionCoordinationPort } from '@mosaicstack/coord';
 import { CoordService } from './coord.service.js';
 import { CoordController } from './coord.controller.js';
+import { InteractionCoordinationController } from './interaction-coordination.controller.js';
+import {
+  COORDINATION_CONFIG,
+  COORDINATION_PORT,
+  InteractionCoordinationService,
+} from './interaction-coordination.service.js';
 
 @Module({
-  providers: [CoordService],
-  controllers: [CoordController],
-  exports: [CoordService],
+  providers: [
+    CoordService,
+    {
+      provide: COORDINATION_PORT,
+      useFactory: (): InMemoryInteractionCoordinationPort =>
+        new InMemoryInteractionCoordinationPort(),
+    },
+    {
+      provide: COORDINATION_CONFIG,
+      useFactory: () => ({
+        interactionAgentId: process.env['MOSAIC_AGENT_NAME'],
+        orchestrationAgentId: process.env['MOSAIC_ORCHESTRATOR_AGENT_NAME'],
+      }),
+    },
+    InteractionCoordinationService,
+  ],
+  controllers: [CoordController, InteractionCoordinationController],
+  exports: [CoordService, InteractionCoordinationService],
 })
 export class CoordModule {}

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

@@ -0,0 +1,47 @@
+const PATH_METADATA = 'path';
+import { describe, expect, it, vi } from 'vitest';
+import { InteractionCoordinationController } from './interaction-coordination.controller.js';
+
+const user = { id: 'operator-1', tenantId: 'tenant-a' };
+
+describe('InteractionCoordinationController', () => {
+  it('exposes the neutral canonical route and Mos compatibility alias over identical handlers', () => {
+    expect(Reflect.getMetadata(PATH_METADATA, InteractionCoordinationController)).toEqual([
+      'api/coord/interaction',
+      'api/coord/mos',
+    ]);
+    expect(InteractionCoordinationController.prototype.handoff).toBeTypeOf('function');
+    expect(InteractionCoordinationController.prototype.observe).toBeTypeOf('function');
+    expect(InteractionCoordinationController.prototype.result).toBeTypeOf('function');
+  });
+
+  it('derives actor and tenant from the authenticated user rather than handoff input', async () => {
+    const coordination = {
+      handoff: vi.fn(async () => ({ handoffId: 'handoff-1' })),
+      observe: vi.fn(),
+      result: vi.fn(),
+    };
+    const controller = new InteractionCoordinationController(coordination as never);
+
+    await controller.handoff({ idempotencyKey: 'request-1', summary: 'Implement' }, user, 'corr-1');
+
+    expect(coordination.handoff).toHaveBeenCalledWith(
+      { idempotencyKey: 'request-1', summary: 'Implement' },
+      expect.objectContaining({
+        actorScope: { userId: 'operator-1', tenantId: 'tenant-a' },
+        channelId: 'cli',
+        correlationId: 'corr-1',
+      }),
+    );
+  });
+
+  it('requires a correlation header before invoking the coordination service', async () => {
+    const coordination = { handoff: vi.fn(), observe: vi.fn(), result: vi.fn() };
+    const controller = new InteractionCoordinationController(coordination as never);
+
+    await expect(
+      controller.handoff({ idempotencyKey: 'request-1', summary: 'Implement' }, user, undefined),
+    ).rejects.toThrow('X-Correlation-Id is required');
+    expect(coordination.handoff).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,75 @@
+import {
+  Body,
+  Controller,
+  ForbiddenException,
+  Get,
+  Headers,
+  Inject,
+  Param,
+  Post,
+  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 type { RuntimeProviderRequestContext } from '../agent/runtime-provider-registry.service.js';
+import type {
+  InteractionCoordinationObservationDto,
+  InteractionCoordinationResponseDto,
+  InteractionCoordinationResultDto,
+  CreateHandoffDto,
+} from './interaction-coordination.dto.js';
+import { InteractionCoordinationService } from './interaction-coordination.service.js';
+
+/** Authenticated interaction-plane boundary for the handoff/observe/result-only interaction coordination contract. */
+/** `api/coord/interaction` is canonical; the Mos path remains a compatibility alias. */
+@Controller(['api/coord/interaction', 'api/coord/mos'])
+@UseGuards(AuthGuard)
+export class InteractionCoordinationController {
+  constructor(
+    @Inject(InteractionCoordinationService)
+    private readonly coordination: InteractionCoordinationService,
+  ) {}
+
+  @Post('handoff')
+  async handoff(
+    @Body() request: CreateHandoffDto,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ): Promise<InteractionCoordinationResponseDto> {
+    return { receipt: await this.coordination.handoff(request, this.context(user, correlationId)) };
+  }
+
+  @Get(':handoffId/observe')
+  async observe(
+    @Param('handoffId') handoffId: string,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ): Promise<InteractionCoordinationObservationDto> {
+    return {
+      observation: await this.coordination.observe(handoffId, this.context(user, correlationId)),
+    };
+  }
+
+  @Get(':handoffId/result')
+  async result(
+    @Param('handoffId') handoffId: string,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ): Promise<InteractionCoordinationResultDto> {
+    return { result: await this.coordination.result(handoffId, this.context(user, correlationId)) };
+  }
+
+  private context(
+    user: AuthenticatedUserLike,
+    correlationId?: string,
+  ): RuntimeProviderRequestContext {
+    const requestCorrelationId = correlationId?.trim();
+    if (!requestCorrelationId) throw new ForbiddenException('X-Correlation-Id is required');
+    return {
+      actorScope: scopeFromUser(user),
+      channelId: 'cli',
+      correlationId: requestCorrelationId,
+    };
+  }
+}

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

@@ -0,0 +1,25 @@
+import type {
+  CoordinationObservation,
+  CoordinationResult,
+  HandoffReceipt,
+} from '@mosaicstack/coord';
+
+/** Input accepted at the gateway coordination boundary. Agent identity is not caller-controlled. */
+export interface CreateHandoffDto {
+  idempotencyKey: string;
+  summary: string;
+  context?: string;
+  missionId?: string;
+}
+
+export interface InteractionCoordinationResponseDto {
+  receipt: HandoffReceipt;
+}
+
+export interface InteractionCoordinationObservationDto {
+  observation: CoordinationObservation;
+}
+
+export interface InteractionCoordinationResultDto {
+  result: CoordinationResult;
+}

apps/gateway/src/coord/interaction-coordination.routing.e2e.test.ts

@@ -0,0 +1,88 @@
+import 'reflect-metadata';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { Global, Module } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { AUTH } from '../auth/auth.tokens.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { InteractionCoordinationController } from './interaction-coordination.controller.js';
+import { InteractionCoordinationService } from './interaction-coordination.service.js';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: AUTH,
+      useValue: {
+        api: {
+          getSession: vi.fn(async ({ headers }: { headers: Headers }) =>
+            headers.get('cookie') === 'session=trusted'
+              ? { user: { id: 'operator-1', tenantId: 'tenant-1' }, session: { id: 'session-1' } }
+              : null,
+          ),
+        },
+      },
+    },
+    AuthGuard,
+  ],
+  exports: [AUTH, AuthGuard],
+})
+class AuthenticatedRequestModule {}
+
+describe('InteractionCoordinationController route aliases', (): void => {
+  let app: NestFastifyApplication | undefined;
+  const coordination = {
+    handoff: vi.fn(async () => ({ handoffId: 'handoff-1' })),
+    observe: vi.fn(async () => ({ status: 'running' })),
+    result: vi.fn(async () => ({ status: 'completed' })),
+  };
+
+  beforeAll(async (): Promise<void> => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [AuthenticatedRequestModule],
+      controllers: [InteractionCoordinationController],
+      providers: [{ provide: InteractionCoordinationService, useValue: coordination }],
+    }).compile();
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+  afterAll(async (): Promise<void> => app?.close());
+
+  it('routes handoff, observe, and result through the same AuthGuard-protected service for both prefixes', async (): Promise<void> => {
+    if (!app) throw new Error('test app was not initialized');
+    for (const prefix of ['/api/coord/interaction', '/api/coord/mos']) {
+      const headers = { cookie: 'session=trusted', 'x-correlation-id': `corr-${prefix}` };
+      expect(
+        (
+          await app.inject({
+            method: 'POST',
+            url: `${prefix}/handoff`,
+            headers,
+            payload: { idempotencyKey: `key-${prefix}`, summary: 'handoff' },
+          })
+        ).statusCode,
+      ).toBe(201);
+      expect(
+        (await app.inject({ method: 'GET', url: `${prefix}/handoff-1/observe`, headers }))
+          .statusCode,
+      ).toBe(200);
+      expect(
+        (await app.inject({ method: 'GET', url: `${prefix}/handoff-1/result`, headers }))
+          .statusCode,
+      ).toBe(200);
+    }
+    expect(coordination.handoff).toHaveBeenCalledTimes(2);
+    expect(coordination.observe).toHaveBeenCalledTimes(2);
+    expect(coordination.result).toHaveBeenCalledTimes(2);
+    expect(
+      (
+        await app.inject({
+          method: 'POST',
+          url: '/api/coord/interaction/handoff',
+          payload: { idempotencyKey: 'denied', summary: 'x' },
+        })
+      ).statusCode,
+    ).toBe(401);
+  });
+});

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

@@ -0,0 +1,217 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  InMemoryInteractionCoordinationPort,
+  type InteractionCoordinationPort,
+  type Handoff,
+} from '@mosaicstack/coord';
+import type { RuntimeProviderRequestContext } from '../agent/runtime-provider-registry.service.js';
+import {
+  InteractionCoordinationService,
+  type InteractionCoordinationConfig,
+  type InteractionCoordinationGatewayError,
+} from './interaction-coordination.service.js';
+
+const context: RuntimeProviderRequestContext = {
+  actorScope: { userId: 'operator-1', tenantId: 'tenant-a' },
+  channelId: 'cli',
+  correlationId: 'corr-1',
+};
+
+const config: InteractionCoordinationConfig = {
+  interactionAgentId: 'Nova',
+  orchestrationAgentId: 'Conductor',
+};
+
+function service(
+  port: InteractionCoordinationPort = new InMemoryInteractionCoordinationPort(),
+  options: {
+    config?: InteractionCoordinationConfig;
+    handoffIdFactory?: () => string;
+  } = {},
+): InteractionCoordinationService {
+  return new InteractionCoordinationService(
+    port,
+    options.config ?? config,
+    options.handoffIdFactory ?? (() => 'handoff-1'),
+  );
+}
+
+describe('InteractionCoordinationService authority boundary', (): void => {
+  it('derives identity and actor/tenant scope server-side, then round-trips the native adapter', async (): Promise<void> => {
+    const adapter = new InMemoryInteractionCoordinationPort();
+    const coordination = service(adapter);
+
+    await expect(
+      coordination.handoff(
+        { idempotencyKey: 'request-1', summary: 'Implement the requested feature' },
+        context,
+      ),
+    ).resolves.toEqual({
+      handoffId: 'handoff-1',
+      targetAgentId: 'Conductor',
+      status: 'queued',
+      correlationId: 'corr-1',
+    });
+
+    adapter.recordActivity('handoff-1', 'running', 'Orchestrator accepted the request');
+    adapter.recordResult('handoff-1', 'completed', 'Merged by orchestrator');
+
+    const followUpContext = { ...context, correlationId: 'corr-2' };
+    await expect(coordination.observe('handoff-1', followUpContext)).resolves.toMatchObject({
+      targetAgentId: 'Conductor',
+      status: 'completed',
+    });
+    await expect(coordination.result('handoff-1', followUpContext)).resolves.toMatchObject({
+      targetAgentId: 'Conductor',
+      status: 'completed',
+      summary: 'Merged by orchestrator',
+    });
+  });
+
+  it('fails closed without calling a port when the interaction requester is unconfigured', async (): Promise<void> => {
+    const adapter = new InMemoryInteractionCoordinationPort();
+    const handoff = vi.spyOn(adapter, 'handoff');
+    const coordination = service(adapter, {
+      config: { interactionAgentId: '', orchestrationAgentId: 'Conductor' },
+    });
+
+    await expect(
+      coordination.handoff(
+        { idempotencyKey: 'request-1', summary: 'Implement the requested feature' },
+        context,
+      ),
+    ).rejects.toMatchObject({
+      code: 'unconfigured_requester',
+    } satisfies Partial<InteractionCoordinationGatewayError>);
+    expect(handoff).not.toHaveBeenCalled();
+  });
+
+  it('rejects self-delegation configuration before delivering work', async (): Promise<void> => {
+    const adapter = new InMemoryInteractionCoordinationPort();
+    const handoff = vi.spyOn(adapter, 'handoff');
+    const coordination = service(adapter, {
+      config: { interactionAgentId: 'Nova', orchestrationAgentId: 'Nova' },
+    });
+
+    await expect(
+      coordination.handoff(
+        { idempotencyKey: 'request-1', summary: 'Implement the requested feature' },
+        context,
+      ),
+    ).rejects.toThrow('Interaction and orchestration identities must differ');
+    expect(handoff).not.toHaveBeenCalled();
+  });
+
+  it('denies cross-tenant observe and result before calling the adapter', async (): Promise<void> => {
+    const adapter = new InMemoryInteractionCoordinationPort();
+    const observe = vi.spyOn(adapter, 'observe');
+    const result = vi.spyOn(adapter, 'result');
+    const coordination = service(adapter);
+    await coordination.handoff(
+      { idempotencyKey: 'request-1', summary: 'Implement the requested feature' },
+      context,
+    );
+
+    const otherTenant = {
+      ...context,
+      actorScope: { ...context.actorScope, tenantId: 'tenant-b' },
+    };
+    await expect(coordination.observe('handoff-1', otherTenant)).rejects.toMatchObject({
+      code: 'cross_tenant_forbidden',
+    } satisfies Partial<InteractionCoordinationGatewayError>);
+    await expect(coordination.result('handoff-1', otherTenant)).rejects.toMatchObject({
+      code: 'cross_tenant_forbidden',
+    } satisfies Partial<InteractionCoordinationGatewayError>);
+    expect(observe).not.toHaveBeenCalled();
+    expect(result).not.toHaveBeenCalled();
+  });
+
+  it('scopes idempotency by actor and joins concurrent retries without duplicate delivery', async (): Promise<void> => {
+    let handoffSequence = 0;
+    let release: (() => void) | undefined;
+    const delivered = new Promise<void>((resolve: () => void): void => {
+      release = resolve;
+    });
+    const adapter: InteractionCoordinationPort = {
+      handoff: vi.fn(async (handoff: Handoff) => {
+        await delivered;
+        return {
+          handoffId: handoff.handoffId,
+          targetAgentId: handoff.targetAgentId,
+          status: 'queued' as const,
+          correlationId: handoff.scope.correlationId,
+        };
+      }),
+      observe: vi.fn(),
+      result: vi.fn(),
+    };
+    const coordination = service(adapter, {
+      handoffIdFactory: (): string => `handoff-${++handoffSequence}`,
+    });
+    const request = { idempotencyKey: 'request-1', summary: 'Implement the requested feature' };
+
+    const first = coordination.handoff(request, context);
+    const retry = coordination.handoff(request, context);
+    expect(adapter.handoff).toHaveBeenCalledTimes(1);
+    release?.();
+    await expect(Promise.all([first, retry])).resolves.toEqual([
+      expect.objectContaining({ handoffId: 'handoff-1' }),
+      expect.objectContaining({ handoffId: 'handoff-1' }),
+    ]);
+
+    await expect(
+      coordination.handoff(request, {
+        ...context,
+        actorScope: { ...context.actorScope, userId: 'operator-2' },
+      }),
+    ).resolves.toMatchObject({ handoffId: 'handoff-2' });
+    expect(adapter.handoff).toHaveBeenCalledTimes(2);
+  });
+
+  it('rejects idempotency-key payload drift and malformed handoff input before delivery', async (): Promise<void> => {
+    const adapter = new InMemoryInteractionCoordinationPort();
+    const handoff = vi.spyOn(adapter, 'handoff');
+    const coordination = service(adapter);
+    await coordination.handoff(
+      { idempotencyKey: 'request-1', summary: 'Implement the requested feature' },
+      context,
+    );
+
+    await expect(
+      coordination.handoff({ idempotencyKey: 'request-1', summary: 'Different work' }, context),
+    ).rejects.toMatchObject({
+      code: 'handoff_conflict',
+    } satisfies Partial<InteractionCoordinationGatewayError>);
+    await expect(
+      coordination.handoff({ idempotencyKey: 'request-2', summary: '' }, context),
+    ).rejects.toMatchObject({
+      code: 'invalid_request',
+    } satisfies Partial<InteractionCoordinationGatewayError>);
+    await expect(
+      coordination.handoff({ idempotencyKey: 'request-3', summary: 'x'.repeat(2_049) }, context),
+    ).rejects.toMatchObject({
+      code: 'invalid_request',
+    } satisfies Partial<InteractionCoordinationGatewayError>);
+    expect(handoff).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails closed when the port reports a target that drifts from configuration', async (): Promise<void> => {
+    const adapter: InteractionCoordinationPort = {
+      handoff: vi.fn(async (handoff: Handoff) => ({
+        handoffId: handoff.handoffId,
+        targetAgentId: 'Unexpected',
+        status: 'accepted' as const,
+        correlationId: handoff.scope.correlationId,
+      })),
+      observe: vi.fn(),
+      result: vi.fn(),
+    };
+
+    await expect(
+      service(adapter).handoff(
+        { idempotencyKey: 'request-1', summary: 'Implement the requested feature' },
+        context,
+      ),
+    ).rejects.toMatchObject({ code: 'target_drift' });
+  });
+});

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

@@ -0,0 +1,303 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  InteractionCoordinationClient,
+  type CoordinationObservation,
+  type CoordinationResult,
+  type CoordinationScope,
+  type InteractionCoordinationIdentity,
+  type InteractionCoordinationPort,
+  type HandoffReceipt,
+} from '@mosaicstack/coord';
+import type { RuntimeProviderRequestContext } from '../agent/runtime-provider-registry.service.js';
+import type { CreateHandoffDto } from './interaction-coordination.dto.js';
+
+export const COORDINATION_PORT = Symbol('COORDINATION_PORT');
+export const COORDINATION_CONFIG = Symbol('COORDINATION_CONFIG');
+
+const HANDOFF_TRACKING_TTL_MS = 60 * 60 * 1_000;
+const MAX_TRACKED_HANDOFFS = 1_000;
+const MAX_IDEMPOTENCY_KEY_LENGTH = 128;
+const MAX_SUMMARY_LENGTH = 2_048;
+const MAX_CONTEXT_LENGTH = 8_192;
+const MAX_MISSION_ID_LENGTH = 128;
+
+export interface InteractionCoordinationConfig {
+  interactionAgentId?: string;
+  orchestrationAgentId?: string;
+}
+
+interface HandoffOwner {
+  actorId: string;
+  tenantId: string;
+  requesterAgentId: string;
+  correlationId: string;
+  expiresAt: number;
+}
+
+interface NormalizedHandoffRequest {
+  idempotencyKey: string;
+  summary: string;
+  context?: string;
+  missionId?: string;
+}
+
+interface TrackedHandoff {
+  request: NormalizedHandoffRequest;
+  receipt: Promise<HandoffReceipt>;
+  expiresAt: number;
+}
+
+/**
+ * Gateway authority boundary for the interaction agent. It derives requester,
+ * actor, and tenant from trusted server configuration and authentication; no
+ * channel request can name a target or gain orchestrator-owned orchestration verbs.
+ */
+@Injectable()
+export class InteractionCoordinationService {
+  private readonly owners = new Map<string, HandoffOwner>();
+  private readonly handoffsByIdempotencyKey = new Map<string, TrackedHandoff>();
+
+  constructor(
+    @Inject(COORDINATION_PORT) private readonly port: InteractionCoordinationPort,
+    @Inject(COORDINATION_CONFIG) private readonly config: InteractionCoordinationConfig,
+    private readonly handoffIdFactory: () => string = (): string => crypto.randomUUID(),
+  ) {}
+
+  async handoff(
+    request: CreateHandoffDto,
+    context: RuntimeProviderRequestContext,
+  ): Promise<HandoffReceipt> {
+    this.pruneExpiredTracking();
+    const normalized = this.normalizeRequest(request);
+    const scope = this.scope(context);
+    const idempotencyKey = this.idempotencyKey(normalized.idempotencyKey, scope);
+    const existing = this.handoffsByIdempotencyKey.get(idempotencyKey);
+    if (existing !== undefined) {
+      if (!sameRequest(existing.request, normalized)) {
+        throw new InteractionCoordinationGatewayError(
+          'handoff_conflict',
+          'Handoff idempotency key is already bound to different immutable input',
+        );
+      }
+      return existing.receipt;
+    }
+
+    const pending = this.deliverHandoff(this.handoffIdFactory(), normalized, scope);
+    const tracked: TrackedHandoff = {
+      request: normalized,
+      receipt: pending,
+      expiresAt: this.expiresAt(),
+    };
+    this.handoffsByIdempotencyKey.set(idempotencyKey, tracked);
+    this.enforceTrackingLimit(this.handoffsByIdempotencyKey);
+    try {
+      return await pending;
+    } catch (error: unknown) {
+      if (this.handoffsByIdempotencyKey.get(idempotencyKey) === tracked) {
+        this.handoffsByIdempotencyKey.delete(idempotencyKey);
+      }
+      throw error;
+    }
+  }
+
+  async observe(
+    handoffId: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<CoordinationObservation> {
+    this.pruneExpiredTracking();
+    const scope = this.scope(context);
+    const owner = this.ownerFor(handoffId, scope);
+    return this.client().observe(handoffId, { ...scope, correlationId: owner.correlationId });
+  }
+
+  async result(
+    handoffId: string,
+    context: RuntimeProviderRequestContext,
+  ): Promise<CoordinationResult> {
+    this.pruneExpiredTracking();
+    const scope = this.scope(context);
+    const owner = this.ownerFor(handoffId, scope);
+    return this.client().result(handoffId, { ...scope, correlationId: owner.correlationId });
+  }
+
+  private async deliverHandoff(
+    handoffId: string,
+    request: NormalizedHandoffRequest,
+    scope: CoordinationScope,
+  ): Promise<HandoffReceipt> {
+    const receipt = await this.client((): string => handoffId).handoff(request, scope);
+    const owner: HandoffOwner = {
+      actorId: scope.actorId,
+      tenantId: scope.tenantId,
+      requesterAgentId: scope.requesterAgentId,
+      correlationId: scope.correlationId,
+      expiresAt: this.expiresAt(),
+    };
+    const existing = this.owners.get(receipt.handoffId);
+    if (existing !== undefined && !sameOwner(existing, owner)) {
+      throw new InteractionCoordinationGatewayError(
+        'handoff_conflict',
+        'Handoff ID is already bound to a different authenticated scope',
+      );
+    }
+    this.owners.set(receipt.handoffId, owner);
+    this.enforceTrackingLimit(this.owners);
+    return receipt;
+  }
+
+  private client(handoffIdFactory?: () => string): InteractionCoordinationClient {
+    return new InteractionCoordinationClient(this.identity(), this.port, handoffIdFactory);
+  }
+
+  private identity(): InteractionCoordinationIdentity {
+    const interactionAgentId = this.config.interactionAgentId?.trim();
+    const orchestrationAgentId = this.config.orchestrationAgentId?.trim();
+    if (!interactionAgentId) {
+      throw new InteractionCoordinationGatewayError(
+        'unconfigured_requester',
+        'Interaction agent identity is not configured',
+      );
+    }
+    if (!orchestrationAgentId) {
+      throw new InteractionCoordinationGatewayError(
+        'unconfigured_target',
+        'Orchestration agent identity is not configured',
+      );
+    }
+    return { interactionAgentId, orchestrationAgentId };
+  }
+
+  private scope(context: RuntimeProviderRequestContext): CoordinationScope {
+    const identity = this.identity();
+    return Object.freeze({
+      actorId: context.actorScope.userId,
+      tenantId: context.actorScope.tenantId,
+      correlationId: context.correlationId,
+      requesterAgentId: identity.interactionAgentId,
+    });
+  }
+
+  private normalizeRequest(request: CreateHandoffDto): NormalizedHandoffRequest {
+    if (typeof request !== 'object' || request === null) {
+      throw new InteractionCoordinationGatewayError(
+        'invalid_request',
+        'Handoff request is invalid',
+      );
+    }
+    const idempotencyKey = this.requiredString(
+      request.idempotencyKey,
+      'idempotency key',
+      MAX_IDEMPOTENCY_KEY_LENGTH,
+    );
+    const summary = this.requiredString(request.summary, 'summary', MAX_SUMMARY_LENGTH);
+    const context = this.optionalString(request.context, 'context', MAX_CONTEXT_LENGTH);
+    const missionId = this.optionalString(request.missionId, 'mission ID', MAX_MISSION_ID_LENGTH);
+    return Object.freeze({
+      idempotencyKey,
+      summary,
+      ...(context === undefined ? {} : { context }),
+      ...(missionId === undefined ? {} : { missionId }),
+    });
+  }
+
+  private idempotencyKey(requestKey: string, scope: CoordinationScope): string {
+    return `${scope.tenantId}\u0000${scope.actorId}\u0000${scope.requesterAgentId}\u0000${requestKey}`;
+  }
+
+  private requiredString(value: unknown, field: string, maximumLength: number): string {
+    if (typeof value !== 'string') {
+      throw new InteractionCoordinationGatewayError(
+        'invalid_request',
+        `Handoff ${field} must be a string`,
+      );
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > maximumLength) {
+      throw new InteractionCoordinationGatewayError(
+        'invalid_request',
+        `Handoff ${field} is invalid`,
+      );
+    }
+    return normalized;
+  }
+
+  private optionalString(value: unknown, field: string, maximumLength: number): string | undefined {
+    if (value === undefined) return undefined;
+    return this.requiredString(value, field, maximumLength);
+  }
+
+  private expiresAt(): number {
+    return Date.now() + HANDOFF_TRACKING_TTL_MS;
+  }
+
+  private pruneExpiredTracking(): void {
+    const now = Date.now();
+    for (const [key, tracked] of this.handoffsByIdempotencyKey) {
+      if (tracked.expiresAt <= now) this.handoffsByIdempotencyKey.delete(key);
+    }
+    for (const [key, owner] of this.owners) {
+      if (owner.expiresAt <= now) this.owners.delete(key);
+    }
+  }
+
+  private enforceTrackingLimit<T>(entries: Map<string, T>): void {
+    while (entries.size > MAX_TRACKED_HANDOFFS) {
+      const oldest = entries.keys().next().value;
+      if (typeof oldest !== 'string') return;
+      entries.delete(oldest);
+    }
+  }
+
+  private ownerFor(handoffId: string, scope: CoordinationScope): HandoffOwner {
+    const owner = this.owners.get(handoffId);
+    if (owner === undefined) {
+      throw new InteractionCoordinationGatewayError('not_found', 'Handoff was not found');
+    }
+    if (
+      owner.tenantId !== scope.tenantId ||
+      owner.actorId !== scope.actorId ||
+      owner.requesterAgentId !== scope.requesterAgentId
+    ) {
+      throw new InteractionCoordinationGatewayError(
+        'cross_tenant_forbidden',
+        'Handoff is outside the authenticated scope',
+      );
+    }
+    return owner;
+  }
+}
+
+export type InteractionCoordinationGatewayErrorCode =
+  | 'cross_tenant_forbidden'
+  | 'handoff_conflict'
+  | 'invalid_request'
+  | 'not_found'
+  | 'unconfigured_requester'
+  | 'unconfigured_target';
+
+function sameOwner(left: HandoffOwner, right: HandoffOwner): boolean {
+  return (
+    left.actorId === right.actorId &&
+    left.tenantId === right.tenantId &&
+    left.requesterAgentId === right.requesterAgentId
+  );
+}
+
+function sameRequest(left: NormalizedHandoffRequest, right: NormalizedHandoffRequest): boolean {
+  return (
+    left.idempotencyKey === right.idempotencyKey &&
+    left.summary === right.summary &&
+    left.context === right.context &&
+    left.missionId === right.missionId
+  );
+}
+
+export class InteractionCoordinationGatewayError extends Error {
+  constructor(
+    readonly code: InteractionCoordinationGatewayErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = InteractionCoordinationGatewayError.name;
+  }
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -3,6 +3,7 @@ import { Logger } from '@nestjs/common';
 import type { QueueHandle } from '@mosaicstack/queue';
 import type { LogService } from '@mosaicstack/log';
 import { SessionGCService } from './session-gc.service.js';
+import { CommandAuthorizationService } from '../commands/command-authorization.service.js';
 
 type MockRedis = {
   scan: ReturnType<typeof vi.fn>;
@@ -12,7 +13,12 @@ type MockRedis = {
 describe('SessionGCService', () => {
   let service: SessionGCService;
   let mockRedis: MockRedis;
-  let mockLogService: { logs: { promoteToWarm: ReturnType<typeof vi.fn> } };
+  let mockLogService: {
+    logs: {
+      promoteSessionToWarm: ReturnType<typeof vi.fn>;
+      promoteToWarm: ReturnType<typeof vi.fn>;
+    };
+  };
 
   /**
    * Helper: build a scan mock that returns all provided keys in a single
@@ -30,6 +36,7 @@ describe('SessionGCService', () => {
 
     mockLogService = {
       logs: {
+        promoteSessionToWarm: vi.fn().mockResolvedValue(0),
         promoteToWarm: vi.fn().mockResolvedValue(0),
       },
     };
@@ -59,54 +66,76 @@ describe('SessionGCService', () => {
     expect(result.cleaned.valkeyKeys).toBeUndefined();
   });
 
+  it('escapes glob metacharacters in a session identifier', async () => {
+    await service.collect('abc*?[tenant]\\escape');
+
+    expect(mockRedis.scan).toHaveBeenCalledWith(
+      '0',
+      'MATCH',
+      'mosaic:session:abc\\*\\?\\[tenant\\]\\\\escape:*',
+      'COUNT',
+      100,
+    );
+  });
+
+  it('preserves a valid durable approval after session GC', async () => {
+    const entries = new Map<string, string>();
+    const redis = {
+      scan: vi.fn().mockResolvedValue(['0', ['mosaic:session:owned:state']]),
+      get: vi.fn(async (key: string) => entries.get(key) ?? null),
+      set: vi.fn(async (key: string, value: string) => entries.set(key, value)),
+      del: vi.fn(async (...keys: string[]) => {
+        let deleted = 0;
+        for (const key of keys) deleted += Number(entries.delete(key));
+        return deleted;
+      }),
+    };
+    const authorization = new CommandAuthorizationService(
+      {
+        select: () => ({
+          from: () => ({ where: () => ({ limit: async () => [{ role: 'admin' }] }) }),
+        }),
+      } as never,
+      redis,
+    );
+    const command = {
+      name: 'gc',
+      description: 'System-wide garbage collection',
+      aliases: [],
+      scope: 'admin',
+      execution: 'socket',
+      available: true,
+    } as never;
+    const payload = { command: 'gc', conversationId: 'owned' };
+    const approval = await authorization.createApproval(command, payload, 'admin-1');
+    const approvalKey = `interaction:command-approval:${approval!.approvalId}`;
+    const gc = new SessionGCService(redis as never, mockLogService as unknown as LogService);
+
+    await gc.collect('owned');
+
+    expect(entries.has(approvalKey)).toBe(true);
+    await expect(
+      authorization.authorize(command, payload, 'admin-1', approval!.approvalId),
+    ).resolves.toEqual({ allowed: true });
+  });
+
   it('collect() returns sessionId in result', async () => {
     const result = await service.collect('test-session-id');
     expect(result.sessionId).toBe('test-session-id');
   });
 
-  it('fullCollect() deletes all session keys', async () => {
-    mockRedis.scan = makeScanMock(['mosaic:session:abc:system', 'mosaic:session:xyz:foo']);
-    const result = await service.fullCollect();
-    expect(mockRedis.del).toHaveBeenCalled();
-    expect(result.valkeyKeys).toBe(2);
+  it('collect() demotes logs only for the requested session', async () => {
+    await service.collect('owned-session');
+
+    expect(mockLogService.logs.promoteSessionToWarm).toHaveBeenCalledWith(
+      'owned-session',
+      expect.any(Date),
+    );
+    expect(mockLogService.logs.promoteToWarm).not.toHaveBeenCalled();
   });
 
-  it('fullCollect() with no keys returns 0 valkeyKeys', async () => {
-    mockRedis.scan = makeScanMock([]);
-    const result = await service.fullCollect();
-    expect(result.valkeyKeys).toBe(0);
-    expect(mockRedis.del).not.toHaveBeenCalled();
-  });
-
-  it('fullCollect() returns duration', async () => {
-    const result = await service.fullCollect();
-    expect(result.duration).toBeGreaterThanOrEqual(0);
-  });
-
-  it('sweepOrphans() extracts unique session IDs and collects them', async () => {
-    // First scan call returns the global session list; subsequent calls return
-    // per-session keys during collect().
-    mockRedis.scan = vi
-      .fn()
-      .mockResolvedValueOnce([
-        '0',
-        ['mosaic:session:abc:system', 'mosaic:session:abc:messages', 'mosaic:session:xyz:system'],
-      ])
-      // collect('abc') scan
-      .mockResolvedValueOnce(['0', ['mosaic:session:abc:system', 'mosaic:session:abc:messages']])
-      // collect('xyz') scan
-      .mockResolvedValueOnce(['0', ['mosaic:session:xyz:system']]);
-    mockRedis.del.mockResolvedValue(1);
-
-    const result = await service.sweepOrphans();
-    expect(result.orphanedSessions).toBeGreaterThanOrEqual(0);
-    expect(result.duration).toBeGreaterThanOrEqual(0);
-  });
-
-  it('sweepOrphans() returns empty when no session keys', async () => {
-    mockRedis.scan = makeScanMock([]);
-    const result = await service.sweepOrphans();
-    expect(result.orphanedSessions).toBe(0);
-    expect(result.totalCleaned).toHaveLength(0);
+  it('does not expose automatic global GC entry points', () => {
+    expect('fullCollect' in service).toBe(false);
+    expect('sweepOrphans' in service).toBe(false);
   });
 });

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

@@ -1,4 +1,4 @@
-import { Inject, Injectable, Logger, Optional, type OnModuleInit } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
 import type { QueueHandle } from '@mosaicstack/queue';
 import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
@@ -13,67 +13,24 @@ export interface GCResult {
   };
 }
 
-export interface GCSweepResult {
-  orphanedSessions: number;
-  totalCleaned: GCResult[];
-  duration: number;
-}
-
-export interface FullGCResult {
-  valkeyKeys: number;
-  logsDemoted: number;
-  jobsPurged: number;
-  tempFilesRemoved: number;
-  duration: number;
+/** Escape Redis glob metacharacters so a session identifier is always literal. */
+function escapeRedisGlobLiteral(value: string): string {
+  return value.replace(/[\\*?\[\]]/g, '\\$&');
 }
 
 @Injectable()
-export class SessionGCService implements OnModuleInit {
-  private readonly logger = new Logger(SessionGCService.name);
-
+export class SessionGCService {
   constructor(
-    // On Local tier there is no Redis — the GC module provides null for this token.
-    // NOTE: if a future feature stores Redis-backed state on Local tier, this guard
-    // would silently skip GC for those keys. Revisit when that happens.
-    @Optional()
-    @Inject(REDIS)
-    private readonly redis: QueueHandle['redis'] | null,
+    @Inject(REDIS) private readonly redis: QueueHandle['redis'],
     @Inject(LOG_SERVICE) private readonly logService: LogService,
   ) {}
 
-  onModuleInit(): void {
-    if (!this.redis) {
-      // Local tier: no Valkey — skip cold-start GC entirely (correct no-op).
-      this.logger.log('SessionGCService: Valkey GC skipped on local tier (no Redis configured)');
-      return;
-    }
-    // Fire-and-forget: run full GC asynchronously so it does not block the
-    // NestJS bootstrap chain.  Cold-start GC typically takes 100–500 ms
-    // depending on Valkey key count; deferring it removes that latency from
-    // the TTFB of the first HTTP request.
-    this.fullCollect()
-      .then((result) => {
-        this.logger.log(
-          `Full GC complete: ${result.valkeyKeys} Valkey keys, ` +
-            `${result.logsDemoted} logs demoted, ` +
-            `${result.jobsPurged} jobs purged, ` +
-            `${result.tempFilesRemoved} temp dirs removed ` +
-            `(${result.duration}ms)`,
-        );
-      })
-      .catch((err: unknown) => {
-        this.logger.error('Cold-start GC failed', err instanceof Error ? err.stack : String(err));
-      });
-  }
-
   /**
    * Scan Valkey for all keys matching a pattern using SCAN (non-blocking).
    * KEYS is avoided because it blocks the Valkey event loop for the full scan
    * duration, which can cause latency spikes under production key volumes.
-   * Returns empty array when Redis is not available (Local tier).
    */
   private async scanKeys(pattern: string): Promise<string[]> {
-    if (!this.redis) return [];
     const collected: string[] = [];
     let cursor = '0';
     do {
@@ -90,94 +47,21 @@ export class SessionGCService implements OnModuleInit {
   async collect(sessionId: string): Promise<GCResult> {
     const result: GCResult = { sessionId, cleaned: {} };
 
-    // 1. Valkey: delete all session-scoped keys (skipped on Local tier)
-    if (this.redis) {
-      const pattern = `mosaic:session:${sessionId}:*`;
-      const valkeyKeys = await this.scanKeys(pattern);
-      if (valkeyKeys.length > 0) {
-        await this.redis.del(...valkeyKeys);
-        result.cleaned.valkeyKeys = valkeyKeys.length;
-      }
+    // 1. Valkey: delete all session-scoped keys
+    const pattern = `mosaic:session:${escapeRedisGlobLiteral(sessionId)}:*`;
+    const valkeyKeys = await this.scanKeys(pattern);
+    if (valkeyKeys.length > 0) {
+      await this.redis.del(...valkeyKeys);
+      result.cleaned.valkeyKeys = valkeyKeys.length;
     }
 
-    // 2. PG: demote hot-tier agent_logs for this session to warm
-    const cutoff = new Date(); // demote all hot logs for this session
-    const logsDemoted = await this.logService.logs.promoteToWarm(cutoff);
+    // 2. PG: demote hot-tier agent logs for this session only.
+    const cutoff = new Date();
+    const logsDemoted = await this.logService.logs.promoteSessionToWarm(sessionId, cutoff);
     if (logsDemoted > 0) {
       result.cleaned.logsDemoted = logsDemoted;
     }
 
     return result;
   }
-
-  /**
-   * Sweep GC — find orphaned artifacts from dead sessions.
-   * System-wide operation: only call from admin-authorized paths or internal
-   * scheduled jobs.  Individual session cleanup is handled by collect().
-   */
-  async sweepOrphans(): Promise<GCSweepResult> {
-    const start = Date.now();
-    const cleaned: GCResult[] = [];
-
-    // 1. Find all session-scoped Valkey keys (non-blocking SCAN)
-    // Returns empty on Local tier — no Valkey session keys exist there.
-    const allSessionKeys = await this.scanKeys('mosaic:session:*');
-
-    // Extract unique session IDs from keys
-    const sessionIds = new Set<string>();
-    for (const key of allSessionKeys) {
-      const match = key.match(/^mosaic:session:([^:]+):/);
-      if (match) sessionIds.add(match[1]!);
-    }
-
-    // 2. For each session ID, collect stale keys
-    for (const sessionId of sessionIds) {
-      const gcResult = await this.collect(sessionId);
-      if (Object.keys(gcResult.cleaned).length > 0) {
-        cleaned.push(gcResult);
-      }
-    }
-
-    return {
-      orphanedSessions: cleaned.length,
-      totalCleaned: cleaned,
-      duration: Date.now() - start,
-    };
-  }
-
-  /**
-   * Full GC — aggressive collection for cold start.
-   * Assumes no sessions survived the restart.
-   */
-  async fullCollect(): Promise<FullGCResult> {
-    const start = Date.now();
-    let valkeyKeysCount = 0;
-
-    if (this.redis) {
-      // 1. Valkey: delete ALL session-scoped keys (non-blocking SCAN)
-      const sessionKeys = await this.scanKeys('mosaic:session:*');
-      if (sessionKeys.length > 0) {
-        await this.redis.del(...sessionKeys);
-      }
-      valkeyKeysCount = sessionKeys.length;
-    }
-
-    // 2. NOTE: channel keys are NOT collected on cold start
-    //    (discord/telegram plugins may reconnect and resume)
-
-    // 3. PG: demote stale hot-tier logs older than 24h to warm
-    const hotCutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
-    const logsDemoted = await this.logService.logs.promoteToWarm(hotCutoff);
-
-    // 4. No summarization job purge API available yet
-    const jobsPurged = 0;
-
-    return {
-      valkeyKeys: valkeyKeysCount,
-      logsDemoted,
-      jobsPurged,
-      tempFilesRemoved: 0,
-      duration: Date.now() - start,
-    };
-  }
 }

apps/gateway/src/health/health.controller.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { HealthController } from './health.controller.js';
+
+describe('HealthController', (): void => {
+  it('exposes liveness and readiness without configuration details', (): void => {
+    const controller = new HealthController();
+
+    expect(controller.check()).toEqual({ status: 'ok' });
+    expect(controller.ready()).toEqual({ status: 'ready' });
+    expect(JSON.stringify(controller.ready())).not.toContain('credential');
+  });
+});

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

@@ -6,4 +6,10 @@ export class HealthController {
   check(): { status: string } {
     return { status: 'ok' };
   }
+
+  /** Readiness intentionally exposes no configuration, provider, or credential details. */
+  @Get('ready')
+  ready(): { status: string } {
+    return { status: 'ready' };
+  }
 }

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

@@ -6,11 +6,10 @@ import {
   type OnModuleDestroy,
 } from '@nestjs/common';
 import { SummarizationService } from './summarization.service.js';
-import { SessionGCService } from '../gc/session-gc.service.js';
 import {
   QueueService,
-  QUEUE_SUMMARIZATION,
   QUEUE_GC,
+  QUEUE_SUMMARIZATION,
   QUEUE_TIER_MANAGEMENT,
 } from '../queue/queue.service.js';
 import type { Worker } from 'bullmq';
@@ -19,28 +18,16 @@ import type { MosaicJobData } from '../queue/queue.service.js';
 @Injectable()
 export class CronService implements OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(CronService.name);
-  private readonly registeredWorkers: Array<Worker<MosaicJobData>> = [];
+  private readonly registeredWorkers: Worker<MosaicJobData>[] = [];
 
   constructor(
     @Inject(SummarizationService) private readonly summarization: SummarizationService,
-    @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
     @Inject(QueueService) private readonly queueService: QueueService,
   ) {}
 
   async onModuleInit(): Promise<void> {
-    // On Local tier BullMQ is disabled — skip all job scheduling.
-    // NOTE: this means summarization, tier management, and Valkey GC jobs do not
-    // run on Local installs. For a single-user local install this is acceptable.
-    // If periodic background work is needed on Local in the future, add a
-    // setInterval-based scheduler here.
-    if (!this.queueService.isEnabled()) {
-      this.logger.log('CronService: BullMQ disabled on local tier — no jobs will be scheduled');
-      return;
-    }
-
     const summarizationSchedule = process.env['SUMMARIZATION_CRON'] ?? '0 */6 * * *'; // every 6 hours
     const tierManagementSchedule = process.env['TIER_MANAGEMENT_CRON'] ?? '0 3 * * *'; // daily at 3am
-    const gcSchedule = process.env['SESSION_GC_CRON'] ?? '0 4 * * *'; // daily at 4am
 
     // M6-003: Summarization repeatable job
     await this.queueService.addRepeatableJob(
@@ -52,7 +39,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const summarizationWorker = this.queueService.registerWorker(QUEUE_SUMMARIZATION, async () => {
       await this.summarization.runSummarization();
     });
-    if (summarizationWorker) this.registeredWorkers.push(summarizationWorker);
+    this.registeredWorkers.push(summarizationWorker);
 
     // M6-005: Tier management repeatable job
     await this.queueService.addRepeatableJob(
@@ -64,17 +51,14 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const tierWorker = this.queueService.registerWorker(QUEUE_TIER_MANAGEMENT, async () => {
       await this.summarization.runTierManagement();
     });
-    if (tierWorker) this.registeredWorkers.push(tierWorker);
+    this.registeredWorkers.push(tierWorker);
 
-    // M6-004: GC repeatable job
-    await this.queueService.addRepeatableJob(QUEUE_GC, 'session-gc', {}, gcSchedule);
-    const gcWorker = this.queueService.registerWorker(QUEUE_GC, async () => {
-      await this.sessionGC.sweepOrphans();
-    });
-    if (gcWorker) this.registeredWorkers.push(gcWorker);
+    // Retire any repeatable global GC schedule created by older deployments.
+    // Session cleanup is now triggered only by an authorized session lifecycle operation.
+    await this.queueService.removeRepeatableJobs(QUEUE_GC, 'session-gc');
 
     this.logger.log(
-      `BullMQ jobs scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}", gc="${gcSchedule}"`,
+      `BullMQ jobs scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}"`,
     );
   }
 

apps/gateway/src/mcp/mcp.controller.ts

@@ -3,7 +3,11 @@ import { Logger } from '@nestjs/common';
 import { fromNodeHeaders } from 'better-auth/node';
 import type { Auth } from '@mosaicstack/auth';
 import type { NestFastifyApplication } from '@nestjs/platform-fastify';
-import type { McpService } from './mcp.service.js';
+import {
+  createMcpActorContext,
+  deriveMcpToolScopesForUser,
+  type McpService,
+} from './mcp.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
 
 /**
@@ -67,14 +71,25 @@ async function handleMcpRequest(
     return;
   }
 
-  const userId = result.user.id;
+  const authUser = result.user as {
+    id: string;
+    role?: string | null;
+    tenantId?: string | null;
+    organizationId?: string | null;
+  };
+  const actor = createMcpActorContext({
+    userId: authUser.id,
+    role: authUser.role,
+    tenantId: authUser.tenantId ?? authUser.organizationId ?? undefined,
+    scopes: deriveMcpToolScopesForUser({ role: authUser.role }),
+  });
 
   // ─── Session routing ─────────────────────────────────────────────────────
   const sessionId = req.raw.headers['mcp-session-id'];
 
   if (typeof sessionId === 'string' && sessionId.length > 0) {
     // Existing session request
-    const transport = mcpService.getSession(sessionId);
+    const transport = mcpService.getSession(sessionId, actor);
     if (!transport) {
       logger.warn(`MCP session not found: ${sessionId}`);
       reply.raw.writeHead(404, { 'Content-Type': 'application/json' });
@@ -112,8 +127,10 @@ async function handleMcpRequest(
   }
 
   // Create new session and handle this initializing request
-  const { transport } = mcpService.createSession(userId);
-  logger.log(`New MCP session created for user ${userId}`);
+  const { transport } = mcpService.createSession(actor);
+  logger.log(
+    `New MCP session created for actor=${actor.userId} tenant=${actor.tenantId} correlation=${actor.correlationId}`,
+  );
 
   await transport.handleRequest(req.raw, reply.raw, body);
 }

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

@@ -0,0 +1,461 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Brain } from '@mosaicstack/brain';
+import type { Memory } from '@mosaicstack/memory';
+import type { EmbeddingService } from '../memory/embedding.service.js';
+import type { CoordService } from '../coord/coord.service.js';
+import {
+  assertMcpToolAuthorized,
+  createMcpActorContext,
+  deriveMcpToolScopesForUser,
+  MCP_TOOL_SCOPES,
+  McpService,
+  type McpToolName,
+} from './mcp.service.js';
+
+type ToolResult = { content: Array<{ type: 'text'; text: string }> };
+type ToolHandler = (params: Record<string, unknown>) => Promise<ToolResult>;
+
+interface CapturedTool {
+  inputSchema: z.ZodType;
+  handler: ToolHandler;
+}
+
+function makeCapturingServer(): { server: McpServer; tools: Map<string, CapturedTool> } {
+  const tools = new Map<string, CapturedTool>();
+  const server = {
+    registerTool(name: string, config: { inputSchema: z.ZodType }, handler: ToolHandler): void {
+      tools.set(name, { inputSchema: config.inputSchema, handler });
+    },
+  };
+  return { server: server as unknown as McpServer, tools };
+}
+
+function makeService(opts?: {
+  projects?: Array<Record<string, unknown> & { id: string; ownerId?: string | null }>;
+  missions?: Array<
+    Record<string, unknown> & { id: string; projectId?: string | null; userId?: string | null }
+  >;
+  tasks?: Array<
+    Record<string, unknown> & {
+      id: string;
+      projectId?: string | null;
+      missionId?: string | null;
+      status?: string;
+    }
+  >;
+}) {
+  const projects = opts?.projects ?? [];
+  const missions = opts?.missions ?? [];
+  const tasks = opts?.tasks ?? [];
+  const brain = {
+    projects: {
+      findAll: vi.fn(async () => projects),
+      findById: vi.fn(async (id: string) => projects.find((project) => project.id === id) ?? null),
+    },
+    tasks: {
+      findAll: vi.fn(async () => tasks),
+      findById: vi.fn(async (id: string) => tasks.find((task) => task.id === id) ?? null),
+      findByProject: vi.fn(async (projectId: string) =>
+        tasks.filter((task) => task.projectId === projectId),
+      ),
+      findByMission: vi.fn(async (missionId: string) =>
+        tasks.filter((task) => task.missionId === missionId),
+      ),
+      findByStatus: vi.fn(async (status: string) => tasks.filter((task) => task.status === status)),
+      create: vi.fn(async (task: Record<string, unknown>) => ({ id: 'task-1', ...task })),
+      update: vi.fn(async (id: string, updates: Record<string, unknown>) => ({ id, ...updates })),
+    },
+    missions: {
+      findAll: vi.fn(async () => missions),
+      findById: vi.fn(async (id: string) => missions.find((mission) => mission.id === id) ?? null),
+      findByProject: vi.fn(async (projectId: string) =>
+        missions.filter((mission) => mission.projectId === projectId),
+      ),
+    },
+    conversations: {
+      findAll: vi.fn(async (userId: string) => [{ id: 'conversation-1', userId }]),
+    },
+  } as unknown as Brain;
+
+  const memory = {
+    insights: {
+      searchByEmbedding: vi.fn(async (userId: string) => [{ id: 'insight-1', userId }]),
+      create: vi.fn(async (insight: Record<string, unknown>) => ({ id: 'insight-2', ...insight })),
+    },
+    preferences: {
+      findByUser: vi.fn(async (userId: string) => [{ key: 'theme', userId }]),
+      findByUserAndCategory: vi.fn(async (userId: string, category: string) => [
+        { key: 'theme', userId, category },
+      ]),
+      upsert: vi.fn(async (preference: Record<string, unknown>) => ({
+        id: 'pref-1',
+        ...preference,
+      })),
+    },
+  } as unknown as Memory;
+
+  const embeddings = {
+    available: true,
+    embed: vi.fn(async () => [0.1, 0.2, 0.3]),
+  } as unknown as EmbeddingService;
+
+  const coord = {
+    getMissionStatus: vi.fn(async () => null),
+    listTasks: vi.fn(async () => []),
+    getTaskStatus: vi.fn(async () => null),
+  } as unknown as CoordService;
+
+  return {
+    service: new McpService(brain, memory, embeddings, coord),
+    brain: brain as unknown as {
+      conversations: { findAll: ReturnType<typeof vi.fn> };
+      tasks: {
+        create: ReturnType<typeof vi.fn>;
+        update: ReturnType<typeof vi.fn>;
+      };
+    },
+    memory: memory as unknown as {
+      insights: { searchByEmbedding: ReturnType<typeof vi.fn> };
+    },
+    coord: coord as unknown as {
+      listTasks: ReturnType<typeof vi.fn>;
+    },
+  };
+}
+
+function getTool(tools: Map<string, CapturedTool>, name: McpToolName): CapturedTool {
+  const tool = tools.get(name);
+  if (!tool) throw new Error(`Missing captured tool ${name}`);
+  return tool;
+}
+
+function makeMemberActor(userId = 'authenticated-user') {
+  return createMcpActorContext({
+    userId,
+    role: 'member',
+    scopes: deriveMcpToolScopesForUser({ role: 'member' }),
+  });
+}
+
+function makeAdminActor(userId = 'admin-user', tenantId?: string) {
+  return createMcpActorContext({
+    userId,
+    tenantId,
+    role: 'admin',
+    scopes: deriveMcpToolScopesForUser({ role: 'admin' }),
+  });
+}
+
+function makePlatformAdminActor(userId = 'platform-admin-user') {
+  return createMcpActorContext({
+    userId,
+    role: 'platform-admin',
+    scopes: deriveMcpToolScopesForUser({ role: 'platform-admin' }),
+  });
+}
+
+describe('MCP actor identity and tool scope enforcement', () => {
+  it('derives immutable actor, tenant, channel, correlation, and explicit tool scopes server-side', () => {
+    const actor = createMcpActorContext({
+      userId: ' user-authenticated ',
+      role: 'member',
+      scopes: deriveMcpToolScopesForUser({ role: 'member' }),
+    });
+
+    expect(actor.userId).toBe('user-authenticated');
+    expect(actor.tenantId).toBe('user:user-authenticated');
+    expect(actor.role).toBe('member');
+    expect(actor.channel).toBe('mcp');
+    expect(actor.correlationId).toMatch(/[0-9a-f-]{36}/i);
+    expect(actor.scopes.has(MCP_TOOL_SCOPES.memory_search)).toBe(true);
+    expect(actor.scopes.has(MCP_TOOL_SCOPES.coord_list_tasks)).toBe(false);
+    expect(
+      deriveMcpToolScopesForUser({ role: 'admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
+    ).toBe(false);
+    expect(
+      deriveMcpToolScopesForUser({ role: 'platform-admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
+    ).toBe(true);
+  });
+
+  it('fails closed when scopes are not supplied by the authenticated context policy', () => {
+    const actor = createMcpActorContext({ userId: 'user-authenticated' });
+
+    expect(actor.scopes.size).toBe(0);
+    expect(() => assertMcpToolAuthorized(actor, 'memory_search', { query: 'notes' })).toThrow(
+      'MCP tool scope denied: memory:insight:read',
+    );
+  });
+
+  it('fails closed when a tool caller supplies actor or tenant identity fields', () => {
+    const actor = createMcpActorContext({ userId: 'user-authenticated' });
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'memory_search', {
+        userId: 'victim-user',
+        query: 'private data',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: userId');
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'coord_list_tasks', {
+        tenantId: 'victim-tenant',
+        projectPath: '/tmp/project',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: tenantId');
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'brain_create_task', {
+        title: 'forged org',
+        organizationId: 'victim-org',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: organizationId');
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'brain_update_task', {
+        title: 'forged team',
+        teamId: 'victim-team',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: teamId');
+  });
+
+  it('fails closed when the server-derived actor lacks the required per-tool scope', () => {
+    const actor = createMcpActorContext({ userId: 'user-authenticated', scopes: [] });
+
+    expect(() => assertMcpToolAuthorized(actor, 'memory_search', { query: 'notes' })).toThrow(
+      'MCP tool scope denied: memory:insight:read',
+    );
+  });
+
+  it('removes caller-controlled userId from memory schemas and never queries victim memory', async () => {
+    const { service, memory } = makeService();
+    const { server, tools } = makeCapturingServer();
+    const actor = makeMemberActor('authenticated-user');
+
+    service.registerTools(server, actor);
+    const tool = getTool(tools, 'memory_search');
+
+    expect(tool.inputSchema.safeParse({ userId: 'victim-user', query: 'anything' }).success).toBe(
+      false,
+    );
+    await expect(tool.handler({ userId: 'victim-user', query: 'anything' })).rejects.toThrow(
+      'MCP caller-controlled identity field is forbidden: userId',
+    );
+    expect(memory.insights.searchByEmbedding).not.toHaveBeenCalled();
+
+    await tool.handler({ query: 'only my notes' });
+    expect(memory.insights.searchByEmbedding).toHaveBeenCalledWith(
+      'authenticated-user',
+      [0.1, 0.2, 0.3],
+      5,
+    );
+  });
+
+  it('binds conversation listing to the authenticated actor instead of a caller-supplied userId', async () => {
+    const { service, brain } = makeService();
+    const { server, tools } = makeCapturingServer();
+    const actor = makeMemberActor('authenticated-user');
+
+    service.registerTools(server, actor);
+    const tool = getTool(tools, 'brain_list_conversations');
+
+    expect(tool.inputSchema.safeParse({ userId: 'victim-user' }).success).toBe(false);
+    await expect(tool.handler({ userId: 'victim-user' })).rejects.toThrow(
+      'MCP caller-controlled identity field is forbidden: userId',
+    );
+    expect(brain.conversations.findAll).not.toHaveBeenCalled();
+
+    await tool.handler({});
+    expect(brain.conversations.findAll).toHaveBeenCalledWith('authenticated-user');
+  });
+
+  it('scopes brain project, mission, and task reads to the authenticated actor', async () => {
+    const { service } = makeService({
+      projects: [
+        { id: 'project-owned', ownerId: 'authenticated-user', name: 'owned' },
+        { id: 'project-victim', ownerId: 'victim-user', name: 'victim' },
+      ],
+      missions: [
+        { id: 'mission-owned', projectId: 'project-owned' },
+        { id: 'mission-victim', userId: 'victim-user', projectId: 'project-victim' },
+      ],
+      tasks: [
+        { id: 'task-owned-project', projectId: 'project-owned', status: 'not-started' },
+        { id: 'task-owned-mission', missionId: 'mission-owned', status: 'not-started' },
+        { id: 'task-victim-project', projectId: 'project-victim', status: 'not-started' },
+        { id: 'task-unowned', status: 'not-started' },
+      ],
+    });
+    const { server, tools } = makeCapturingServer();
+    const actor = makeMemberActor('authenticated-user');
+
+    service.registerTools(server, actor);
+
+    const projects = JSON.parse(
+      (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
+    );
+    expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-owned']);
+
+    const missions = JSON.parse(
+      (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
+    );
+    expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-owned']);
+
+    const tasks = JSON.parse(
+      (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
+    );
+    expect(tasks.map((task: { id: string }) => task.id)).toEqual([
+      'task-owned-project',
+      'task-owned-mission',
+    ]);
+  });
+
+  it('enforces tenant boundaries for tenant-admin brain project, mission, and task reads', async () => {
+    const { service } = makeService({
+      projects: [
+        {
+          id: 'project-tenant-a',
+          ownerId: 'other-user-a',
+          teamId: 'tenant-a',
+          name: 'same tenant',
+        },
+        {
+          id: 'project-tenant-b',
+          ownerId: 'other-user-b',
+          teamId: 'tenant-b',
+          name: 'other tenant',
+        },
+      ],
+      missions: [
+        { id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
+        { id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
+      ],
+      tasks: [
+        { id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
+        { id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
+      ],
+    });
+    const { server, tools } = makeCapturingServer();
+    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
+
+    service.registerTools(server, actor);
+
+    const projects = JSON.parse(
+      (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
+    );
+    expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-tenant-a']);
+
+    const missions = JSON.parse(
+      (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
+    );
+    expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-tenant-a']);
+
+    const tasks = JSON.parse(
+      (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
+    );
+    expect(tasks.map((task: { id: string }) => task.id)).toEqual(['task-tenant-a']);
+  });
+
+  it('denies tenant-admin task writes outside the authenticated tenant', async () => {
+    const { service, brain } = makeService({
+      projects: [
+        { id: 'project-tenant-a', ownerId: 'other-user-a', teamId: 'tenant-a' },
+        { id: 'project-tenant-b', ownerId: 'other-user-b', teamId: 'tenant-b' },
+      ],
+      missions: [
+        { id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
+        { id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
+      ],
+      tasks: [
+        { id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
+        { id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
+      ],
+    });
+    const { server, tools } = makeCapturingServer();
+    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
+
+    service.registerTools(server, actor);
+
+    await expect(
+      getTool(tools, 'brain_create_task').handler({
+        title: 'unscoped tenant write',
+      }),
+    ).rejects.toThrow('MCP task scope denied');
+    expect(brain.tasks.create).not.toHaveBeenCalled();
+
+    await expect(
+      getTool(tools, 'brain_create_task').handler({
+        title: 'cross-tenant write',
+        projectId: 'project-tenant-b',
+      }),
+    ).rejects.toThrow('MCP task project scope denied');
+    expect(brain.tasks.create).not.toHaveBeenCalled();
+
+    await expect(
+      getTool(tools, 'brain_update_task').handler({
+        id: 'task-tenant-a',
+        projectId: 'project-tenant-b',
+      }),
+    ).rejects.toThrow('MCP task project scope denied');
+    expect(brain.tasks.update).not.toHaveBeenCalled();
+
+    const updateResult = await getTool(tools, 'brain_update_task').handler({
+      id: 'task-tenant-b',
+      title: 'cross-tenant update',
+    });
+    expect(updateResult.content[0]!.text).toBe('Task not found: task-tenant-b');
+    expect(brain.tasks.update).not.toHaveBeenCalled();
+
+    await getTool(tools, 'brain_create_task').handler({
+      title: 'same-tenant write',
+      projectId: 'project-tenant-a',
+    });
+    expect(brain.tasks.create).toHaveBeenCalledWith(
+      expect.objectContaining({ projectId: 'project-tenant-a', title: 'same-tenant write' }),
+    );
+  });
+
+  it('keeps admin-only coordination tools on server-derived paths', async () => {
+    const { service, coord } = makeService();
+    const { server, tools } = makeCapturingServer();
+    const member = makeMemberActor('authenticated-user');
+    const tenantAdmin = makeAdminActor('admin-user');
+    const platformAdmin = makePlatformAdminActor('platform-admin-user');
+
+    service.registerTools(server, member);
+    const memberTool = getTool(tools, 'coord_list_tasks');
+    expect(memberTool.inputSchema.safeParse({ projectPath: '/tmp/victim' }).success).toBe(false);
+    await expect(memberTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
+
+    tools.clear();
+    service.registerTools(server, tenantAdmin);
+    const tenantAdminTool = getTool(tools, 'coord_list_tasks');
+    await expect(tenantAdminTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
+
+    tools.clear();
+    service.registerTools(server, platformAdmin);
+    const platformAdminTool = getTool(tools, 'coord_list_tasks');
+    await platformAdminTool.handler({ projectPath: '/tmp/victim' });
+    expect(coord.listTasks).toHaveBeenCalledWith(process.cwd());
+  });
+
+  it('does not attach a guessed or stale-scope MCP session to another authenticated context', async () => {
+    const { service } = makeService();
+    const owner = makeMemberActor('owner-user');
+    const attacker = makeMemberActor('attacker-user');
+    const admin = makeAdminActor('admin-user');
+    const downgradedAdmin = makeMemberActor('admin-user');
+
+    const { sessionId, transport } = service.createSession(owner);
+    const staleSession = service.createSession(admin);
+
+    expect(service.getSession(sessionId, owner)).toBe(transport);
+    expect(service.getSession(sessionId, attacker)).toBeNull();
+    expect(service.getSession(sessionId, owner)).toBe(transport);
+    expect(service.getSession(staleSession.sessionId, downgradedAdmin)).toBeNull();
+    expect(service.getSession(staleSession.sessionId, admin)).toBe(staleSession.transport);
+
+    await service.onModuleDestroy();
+  });
+});

apps/gateway/src/mcp/mcp.service.ts

@@ -10,11 +10,216 @@ import { MEMORY } from '../memory/memory.tokens.js';
 import { EmbeddingService } from '../memory/embedding.service.js';
 import { CoordService } from '../coord/coord.service.js';
 
+export const MCP_CALLER_IDENTITY_FIELDS = [
+  'actorId',
+  'actor',
+  'authenticatedUserId',
+  'channel',
+  'organizationId',
+  'ownerId',
+  'sessionUserId',
+  'teamId',
+  'tenant',
+  'tenantId',
+  'user',
+  'userId',
+] as const;
+
+type McpCallerIdentityField = (typeof MCP_CALLER_IDENTITY_FIELDS)[number];
+
+export const MCP_TOOL_SCOPES = {
+  brain_list_projects: 'brain:project:read',
+  brain_get_project: 'brain:project:read',
+  brain_list_tasks: 'brain:task:read',
+  brain_create_task: 'brain:task:write',
+  brain_update_task: 'brain:task:write',
+  brain_list_missions: 'brain:mission:read',
+  brain_list_conversations: 'brain:conversation:read',
+  memory_search: 'memory:insight:read',
+  memory_get_preferences: 'memory:preference:read',
+  memory_save_preference: 'memory:preference:write',
+  memory_save_insight: 'memory:insight:write',
+  coord_mission_status: 'coord:read',
+  coord_list_tasks: 'coord:read',
+  coord_task_detail: 'coord:read',
+} as const;
+
+export type McpToolName = keyof typeof MCP_TOOL_SCOPES;
+export type McpToolScope = (typeof MCP_TOOL_SCOPES)[McpToolName];
+
+export interface McpActorContext {
+  userId: string;
+  tenantId: string;
+  role: string;
+  channel: 'mcp';
+  correlationId: string;
+  scopes: ReadonlySet<McpToolScope>;
+}
+
 interface SessionEntry {
   server: McpServer;
   transport: StreamableHTTPServerTransport;
   createdAt: Date;
+  actor: McpActorContext;
+}
+
+const GLOBAL_ADMIN_MCP_SCOPES = new Set<McpToolScope>(Object.values(MCP_TOOL_SCOPES));
+const TENANT_ADMIN_MCP_SCOPES = new Set<McpToolScope>([
+  MCP_TOOL_SCOPES.brain_list_projects,
+  MCP_TOOL_SCOPES.brain_get_project,
+  MCP_TOOL_SCOPES.brain_list_tasks,
+  MCP_TOOL_SCOPES.brain_create_task,
+  MCP_TOOL_SCOPES.brain_update_task,
+  MCP_TOOL_SCOPES.brain_list_missions,
+  MCP_TOOL_SCOPES.brain_list_conversations,
+  MCP_TOOL_SCOPES.memory_search,
+  MCP_TOOL_SCOPES.memory_get_preferences,
+  MCP_TOOL_SCOPES.memory_save_preference,
+  MCP_TOOL_SCOPES.memory_save_insight,
+]);
+const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
+  MCP_TOOL_SCOPES.brain_list_projects,
+  MCP_TOOL_SCOPES.brain_get_project,
+  MCP_TOOL_SCOPES.brain_list_tasks,
+  MCP_TOOL_SCOPES.brain_list_missions,
+  MCP_TOOL_SCOPES.brain_list_conversations,
+  MCP_TOOL_SCOPES.memory_search,
+  MCP_TOOL_SCOPES.memory_get_preferences,
+  MCP_TOOL_SCOPES.memory_save_preference,
+  MCP_TOOL_SCOPES.memory_save_insight,
+]);
+
+export function deriveMcpToolScopesForUser(input: {
+  role?: string | null;
+}): ReadonlySet<McpToolScope> {
+  if (input.role === 'platform-admin' || input.role === 'super-admin') {
+    return new Set(GLOBAL_ADMIN_MCP_SCOPES);
+  }
+  if (input.role === 'admin') {
+    return new Set(TENANT_ADMIN_MCP_SCOPES);
+  }
+  return new Set(MEMBER_MCP_SCOPES);
+}
+
+export function createMcpActorContext(input: {
   userId: string;
+  tenantId?: string;
+  role?: string | null;
+  scopes?: Iterable<McpToolScope>;
+  correlationId?: string;
+}): McpActorContext {
+  const userId = input.userId.trim();
+  if (userId.length === 0) {
+    throw new Error('MCP authenticated user is required');
+  }
+
+  return {
+    userId,
+    tenantId: input.tenantId?.trim() || `user:${userId}`,
+    role: input.role ?? 'member',
+    channel: 'mcp',
+    correlationId: input.correlationId ?? randomUUID(),
+    scopes: new Set(input.scopes ?? []),
+  };
+}
+
+export function assertNoCallerControlledIdentity(params: unknown): void {
+  if (params === null || typeof params !== 'object') return;
+
+  const keys = new Set(Object.keys(params));
+  const forbidden = MCP_CALLER_IDENTITY_FIELDS.find((field: McpCallerIdentityField) =>
+    keys.has(field),
+  );
+  if (forbidden) {
+    throw new Error(`MCP caller-controlled identity field is forbidden: ${forbidden}`);
+  }
+}
+
+export function assertMcpToolAuthorized(
+  actor: McpActorContext,
+  toolName: McpToolName,
+  params: unknown,
+): void {
+  assertNoCallerControlledIdentity(params);
+  const requiredScope = MCP_TOOL_SCOPES[toolName];
+  if (!actor.scopes.has(requiredScope)) {
+    throw new Error(`MCP tool scope denied: ${requiredScope}`);
+  }
+}
+
+function strictObject<T extends z.ZodRawShape>(shape: T): z.ZodObject<T> {
+  return z.object(shape).strict();
+}
+
+type TenantScopedLike = {
+  tenantId?: string | null;
+  organizationId?: string | null;
+  teamId?: string | null;
+};
+type ProjectLike = TenantScopedLike & { id: string; ownerId?: string | null };
+type MissionLike = TenantScopedLike & {
+  id: string;
+  projectId?: string | null;
+  userId?: string | null;
+};
+type TaskLike = TenantScopedLike & {
+  projectId?: string | null;
+  missionId?: string | null;
+  userId?: string | null;
+};
+
+function isGlobalAdminActor(actor: McpActorContext): boolean {
+  return actor.role === 'platform-admin' || actor.role === 'super-admin';
+}
+
+function isTenantAdminActor(actor: McpActorContext): boolean {
+  return actor.role === 'admin';
+}
+
+function matchesTenant(actor: McpActorContext, record: TenantScopedLike): boolean {
+  return (
+    record.tenantId === actor.tenantId ||
+    record.organizationId === actor.tenantId ||
+    record.teamId === actor.tenantId
+  );
+}
+
+function filterProjectsForActor<T extends ProjectLike>(actor: McpActorContext, projects: T[]): T[] {
+  if (isGlobalAdminActor(actor)) return projects;
+  return projects.filter(
+    (project) =>
+      project.ownerId === actor.userId ||
+      (isTenantAdminActor(actor) && matchesTenant(actor, project)),
+  );
+}
+
+function filterMissionsByDirectActorScope<T extends MissionLike>(
+  actor: McpActorContext,
+  missions: T[],
+): T[] {
+  if (isGlobalAdminActor(actor)) return missions;
+  return missions.filter(
+    (mission) =>
+      mission.userId === actor.userId ||
+      (isTenantAdminActor(actor) && matchesTenant(actor, mission)),
+  );
+}
+
+function scopesEqual(left: ReadonlySet<McpToolScope>, right: ReadonlySet<McpToolScope>): boolean {
+  if (left.size !== right.size) return false;
+  for (const scope of left) {
+    if (!right.has(scope)) return false;
+  }
+  return true;
+}
+
+function sameActorAuthorization(stored: McpActorContext, current: McpActorContext): boolean {
+  return (
+    stored.userId === current.userId &&
+    stored.tenantId === current.tenantId &&
+    stored.role === current.role &&
+    scopesEqual(stored.scopes, current.scopes)
+  );
 }
 
 @Injectable()
@@ -33,13 +238,18 @@ export class McpService implements OnModuleDestroy {
    * Creates a new MCP session with its own server + transport pair.
    * Returns the transport for use by the controller.
    */
-  createSession(userId: string): { sessionId: string; transport: StreamableHTTPServerTransport } {
+  createSession(actor: McpActorContext): {
+    sessionId: string;
+    transport: StreamableHTTPServerTransport;
+  } {
     const sessionId = randomUUID();
 
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => sessionId,
       onsessioninitialized: (id) => {
-        this.logger.log(`MCP session initialized: ${id} for user ${userId}`);
+        this.logger.log(
+          `MCP session initialized: ${id} for actor=${actor.userId} tenant=${actor.tenantId} correlation=${actor.correlationId}`,
+        );
       },
     });
 
@@ -48,7 +258,7 @@ export class McpService implements OnModuleDestroy {
       { capabilities: { tools: {} } },
     );
 
-    this.registerTools(server, userId);
+    this.registerTools(server, actor);
 
     transport.onclose = () => {
       this.logger.log(`MCP session closed: ${sessionId}`);
@@ -61,31 +271,126 @@ export class McpService implements OnModuleDestroy {
       );
     });
 
-    this.sessions.set(sessionId, { server, transport, createdAt: new Date(), userId });
+    this.sessions.set(sessionId, { server, transport, createdAt: new Date(), actor });
     return { sessionId, transport };
   }
 
   /**
-   * Returns the transport for an existing session, or null if not found.
+   * Returns the transport for an existing session only when it belongs to the
+   * currently authenticated MCP actor. Guessed or cross-tenant session IDs grant
+   * no authority.
    */
-  getSession(sessionId: string): StreamableHTTPServerTransport | null {
-    return this.sessions.get(sessionId)?.transport ?? null;
+  getSession(sessionId: string, actor: McpActorContext): StreamableHTTPServerTransport | null {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return null;
+    if (!sameActorAuthorization(entry.actor, actor)) {
+      this.logger.warn(
+        `MCP session actor or scope mismatch: session=${sessionId} actor=${actor.userId} tenant=${actor.tenantId} role=${actor.role}`,
+      );
+      return null;
+    }
+    return entry.transport;
+  }
+
+  private async isProjectAuthorized(actor: McpActorContext, projectId: string): Promise<boolean> {
+    if (isGlobalAdminActor(actor)) return true;
+    const project = (await this.brain.projects.findById(projectId)) as ProjectLike | undefined;
+    return project ? filterProjectsForActor(actor, [project]).length === 1 : false;
+  }
+
+  private async filterMissionsForActor<T extends MissionLike>(
+    actor: McpActorContext,
+    missions: T[],
+  ): Promise<T[]> {
+    if (isGlobalAdminActor(actor)) return missions;
+
+    const projects = (await this.brain.projects.findAll()) as ProjectLike[];
+    const projectIds = new Set(
+      filterProjectsForActor(actor, projects).map((project) => project.id),
+    );
+
+    return missions.filter(
+      (mission) =>
+        filterMissionsByDirectActorScope(actor, [mission]).length === 1 ||
+        (typeof mission.projectId === 'string' && projectIds.has(mission.projectId)),
+    );
+  }
+
+  private async isMissionAuthorized(actor: McpActorContext, missionId: string): Promise<boolean> {
+    if (isGlobalAdminActor(actor)) return true;
+    const mission = (await this.brain.missions.findById(missionId)) as MissionLike | undefined;
+    if (!mission) return false;
+    return (await this.filterMissionsForActor(actor, [mission])).length === 1;
+  }
+
+  private async assertTaskReferencesAuthorized(
+    actor: McpActorContext,
+    refs: { projectId?: string | null; missionId?: string | null },
+  ): Promise<void> {
+    if (refs.projectId && !(await this.isProjectAuthorized(actor, refs.projectId))) {
+      throw new Error('MCP task project scope denied');
+    }
+    if (refs.missionId && !(await this.isMissionAuthorized(actor, refs.missionId))) {
+      throw new Error('MCP task mission scope denied');
+    }
+  }
+
+  private async assertTaskCreateScopeAuthorized(
+    actor: McpActorContext,
+    refs: { projectId?: string | null; missionId?: string | null },
+  ): Promise<void> {
+    if (!isGlobalAdminActor(actor) && !refs.projectId && !refs.missionId) {
+      throw new Error('MCP task scope denied');
+    }
+    await this.assertTaskReferencesAuthorized(actor, refs);
+  }
+
+  private async filterTasksForActor<T extends TaskLike>(
+    actor: McpActorContext,
+    tasks: T[],
+  ): Promise<T[]> {
+    if (isGlobalAdminActor(actor)) return tasks;
+
+    const [projects, missions] = await Promise.all([
+      this.brain.projects.findAll(),
+      this.brain.missions.findAll(),
+    ]);
+    const projectIds = new Set(
+      filterProjectsForActor(actor, projects as ProjectLike[]).map((project) => project.id),
+    );
+    const missionIds = new Set(
+      (await this.filterMissionsForActor(actor, missions as MissionLike[])).map(
+        (mission) => mission.id,
+      ),
+    );
+
+    return tasks.filter(
+      (task) =>
+        task.userId === actor.userId ||
+        (isTenantAdminActor(actor) && matchesTenant(actor, task)) ||
+        (typeof task.projectId === 'string' && projectIds.has(task.projectId)) ||
+        (typeof task.missionId === 'string' && missionIds.has(task.missionId)),
+    );
   }
 
   /**
    * Registers all platform tools on the given McpServer instance.
    */
-  private registerTools(server: McpServer, _userId: string): void {
+  registerTools(server: McpServer, actor: McpActorContext): void {
     // ─── Brain: Project tools ────────────────────────────────────────────
 
     server.registerTool(
       'brain_list_projects',
       {
         description: 'List all projects in the brain.',
-        inputSchema: z.object({}),
+        inputSchema: strictObject({}),
       },
-      async () => {
-        const projects = await this.brain.projects.findAll();
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_projects', params);
+        const projects = filterProjectsForActor(
+          actor,
+          (await this.brain.projects.findAll()) as ProjectLike[],
+        );
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(projects, null, 2) }],
         };
@@ -96,17 +401,21 @@ export class McpService implements OnModuleDestroy {
       'brain_get_project',
       {
         description: 'Get a project by ID.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           id: z.string().describe('Project ID (UUID)'),
         }),
       },
-      async ({ id }) => {
-        const project = await this.brain.projects.findById(id);
+      async ({ id, ...params }) => {
+        assertMcpToolAuthorized(actor, 'brain_get_project', params);
+        const project = (await this.brain.projects.findById(id)) as ProjectLike | undefined;
+        const authorizedProject = project ? filterProjectsForActor(actor, [project])[0] : undefined;
         return {
           content: [
             {
               type: 'text' as const,
-              text: project ? JSON.stringify(project, null, 2) : `Project not found: ${id}`,
+              text: authorizedProject
+                ? JSON.stringify(authorizedProject, null, 2)
+                : `Project not found: ${id}`,
             },
           ],
         };
@@ -119,20 +428,23 @@ export class McpService implements OnModuleDestroy {
       'brain_list_tasks',
       {
         description: 'List tasks, optionally filtered by project, mission, or status.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           projectId: z.string().optional().describe('Filter by project ID'),
           missionId: z.string().optional().describe('Filter by mission ID'),
           status: z.string().optional().describe('Filter by status'),
         }),
       },
-      async ({ projectId, missionId, status }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_tasks', params);
+        const { projectId, missionId, status } = params;
         type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
         let tasks;
         if (projectId) tasks = await this.brain.tasks.findByProject(projectId);
         else if (missionId) tasks = await this.brain.tasks.findByMission(missionId);
         else if (status) tasks = await this.brain.tasks.findByStatus(status as TaskStatus);
         else tasks = await this.brain.tasks.findAll();
-        return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
+        const scopedTasks = await this.filterTasksForActor(actor, tasks as TaskLike[]);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(scopedTasks, null, 2) }] };
       },
     );
 
@@ -140,7 +452,7 @@ export class McpService implements OnModuleDestroy {
       'brain_create_task',
       {
         description: 'Create a new task in the brain.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           title: z.string().describe('Task title'),
           description: z.string().optional().describe('Task description'),
           projectId: z.string().optional().describe('Project ID'),
@@ -149,6 +461,8 @@ export class McpService implements OnModuleDestroy {
         }),
       },
       async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_create_task', params);
+        await this.assertTaskCreateScopeAuthorized(actor, params);
         type Priority = 'low' | 'medium' | 'high' | 'critical';
         const task = await this.brain.tasks.create({
           ...params,
@@ -162,7 +476,7 @@ export class McpService implements OnModuleDestroy {
       'brain_update_task',
       {
         description: 'Update an existing task.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           id: z.string().describe('Task ID'),
           title: z.string().optional(),
           description: z.string().optional(),
@@ -171,9 +485,17 @@ export class McpService implements OnModuleDestroy {
             .optional()
             .describe('not-started, in-progress, blocked, done, cancelled'),
           priority: z.string().optional(),
+          projectId: z.string().optional().describe('Project ID'),
+          missionId: z.string().optional().describe('Mission ID'),
         }),
       },
       async ({ id, ...updates }) => {
+        assertMcpToolAuthorized(actor, 'brain_update_task', updates);
+        const existing = (await this.brain.tasks.findById(id)) as TaskLike | undefined;
+        if (!existing || (await this.filterTasksForActor(actor, [existing])).length === 0) {
+          return { content: [{ type: 'text' as const, text: `Task not found: ${id}` }] };
+        }
+        await this.assertTaskReferencesAuthorized(actor, updates);
         type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
         type Priority = 'low' | 'medium' | 'high' | 'critical';
         const task = await this.brain.tasks.update(id, {
@@ -198,14 +520,19 @@ export class McpService implements OnModuleDestroy {
       'brain_list_missions',
       {
         description: 'List all missions, optionally filtered by project.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           projectId: z.string().optional().describe('Filter by project ID'),
         }),
       },
-      async ({ projectId }) => {
-        const missions = projectId
-          ? await this.brain.missions.findByProject(projectId)
-          : await this.brain.missions.findAll();
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_missions', params);
+        const { projectId } = params;
+        const missions = await this.filterMissionsForActor(
+          actor,
+          (projectId
+            ? await this.brain.missions.findByProject(projectId)
+            : await this.brain.missions.findAll()) as MissionLike[],
+        );
         return { content: [{ type: 'text' as const, text: JSON.stringify(missions, null, 2) }] };
       },
     );
@@ -213,13 +540,12 @@ export class McpService implements OnModuleDestroy {
     server.registerTool(
       'brain_list_conversations',
       {
-        description: 'List conversations for a user.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
-        }),
+        description: 'List conversations for the authenticated MCP actor.',
+        inputSchema: strictObject({}),
       },
-      async ({ userId }) => {
-        const conversations = await this.brain.conversations.findAll(userId);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_conversations', params);
+        const conversations = await this.brain.conversations.findAll(actor.userId);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(conversations, null, 2) }],
         };
@@ -232,14 +558,15 @@ export class McpService implements OnModuleDestroy {
       'memory_search',
       {
         description:
-          'Search across stored insights and knowledge using natural language. Returns semantically similar results.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID to search memory for'),
+          'Search stored insights and knowledge for the authenticated MCP actor using natural language.',
+        inputSchema: strictObject({
           query: z.string().describe('Natural language search query'),
           limit: z.number().optional().describe('Max results (default 5)'),
         }),
       },
-      async ({ userId, query, limit }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_search', params);
+        const { query, limit } = params;
         if (!this.embeddings.available) {
           return {
             content: [
@@ -251,7 +578,11 @@ export class McpService implements OnModuleDestroy {
           };
         }
         const embedding = await this.embeddings.embed(query);
-        const results = await this.memory.insights.searchByEmbedding(userId, embedding, limit ?? 5);
+        const results = await this.memory.insights.searchByEmbedding(
+          actor.userId,
+          embedding,
+          limit ?? 5,
+        );
         return { content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }] };
       },
     );
@@ -259,20 +590,21 @@ export class McpService implements OnModuleDestroy {
     server.registerTool(
       'memory_get_preferences',
       {
-        description: 'Retrieve stored preferences for a user.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
+        description: 'Retrieve stored preferences for the authenticated MCP actor.',
+        inputSchema: strictObject({
           category: z
             .string()
             .optional()
             .describe('Filter by category: communication, coding, workflow, appearance, general'),
         }),
       },
-      async ({ userId, category }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_get_preferences', params);
+        const { category } = params;
         type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
         const prefs = category
-          ? await this.memory.preferences.findByUserAndCategory(userId, category as Cat)
-          : await this.memory.preferences.findByUser(userId);
+          ? await this.memory.preferences.findByUserAndCategory(actor.userId, category as Cat)
+          : await this.memory.preferences.findByUser(actor.userId);
         return { content: [{ type: 'text' as const, text: JSON.stringify(prefs, null, 2) }] };
       },
     );
@@ -281,9 +613,8 @@ export class McpService implements OnModuleDestroy {
       'memory_save_preference',
       {
         description:
-          'Store a learned user preference (e.g., "prefers tables over paragraphs", "timezone: America/Chicago").',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
+          'Store a learned preference for the authenticated MCP actor (e.g., "prefers tables over paragraphs").',
+        inputSchema: strictObject({
           key: z.string().describe('Preference key'),
           value: z.string().describe('Preference value (JSON string)'),
           category: z
@@ -292,7 +623,9 @@ export class McpService implements OnModuleDestroy {
             .describe('Category: communication, coding, workflow, appearance, general'),
         }),
       },
-      async ({ userId, key, value, category }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_save_preference', params);
+        const { key, value, category } = params;
         type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
         let parsedValue: unknown;
         try {
@@ -301,7 +634,7 @@ export class McpService implements OnModuleDestroy {
           parsedValue = value;
         }
         const pref = await this.memory.preferences.upsert({
-          userId,
+          userId: actor.userId,
           key,
           value: parsedValue,
           category: (category as Cat) ?? 'general',
@@ -315,9 +648,8 @@ export class McpService implements OnModuleDestroy {
       'memory_save_insight',
       {
         description:
-          'Store a learned insight, decision, or knowledge extracted from the current interaction.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
+          'Store a learned insight, decision, or knowledge for the authenticated MCP actor.',
+        inputSchema: strictObject({
           content: z.string().describe('The insight or knowledge to store'),
           category: z
             .string()
@@ -325,11 +657,13 @@ export class McpService implements OnModuleDestroy {
             .describe('Category: decision, learning, preference, fact, pattern, general'),
         }),
       },
-      async ({ userId, content, category }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_save_insight', params);
+        const { content, category } = params;
         type Cat = 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
         const embedding = this.embeddings.available ? await this.embeddings.embed(content) : null;
         const insight = await this.memory.insights.create({
-          userId,
+          userId: actor.userId,
           content,
           embedding,
           source: 'agent',
@@ -346,16 +680,11 @@ export class McpService implements OnModuleDestroy {
       {
         description:
           'Get the current orchestration mission status including milestones, tasks, and active session.',
-        inputSchema: z.object({
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
-        }),
+        inputSchema: strictObject({}),
       },
-      async ({ projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const status = await this.coordService.getMissionStatus(resolvedPath);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'coord_mission_status', params);
+        const status = await this.coordService.getMissionStatus(process.cwd());
         return {
           content: [
             {
@@ -371,16 +700,11 @@ export class McpService implements OnModuleDestroy {
       'coord_list_tasks',
       {
         description: 'List all tasks from the orchestration TASKS.md file.',
-        inputSchema: z.object({
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
-        }),
+        inputSchema: strictObject({}),
       },
-      async ({ projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const tasks = await this.coordService.listTasks(resolvedPath);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'coord_list_tasks', params);
+        const tasks = await this.coordService.listTasks(process.cwd());
         return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
       },
     );
@@ -389,17 +713,14 @@ export class McpService implements OnModuleDestroy {
       'coord_task_detail',
       {
         description: 'Get detailed status for a specific orchestration task.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           taskId: z.string().describe('Task ID (e.g. P2-005)'),
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
         }),
       },
-      async ({ taskId, projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const detail = await this.coordService.getTaskStatus(resolvedPath, taskId);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'coord_task_detail', params);
+        const { taskId } = params;
+        const detail = await this.coordService.getTaskStatus(process.cwd(), taskId);
         return {
           content: [
             {

apps/gateway/src/memory/memory.module.ts

@@ -3,8 +3,10 @@ import {
   createMemory,
   type Memory,
   createMemoryAdapter,
+  createOperatorMemoryPlugin,
   type MemoryAdapter,
   type MemoryConfig,
+  type OperatorMemoryPlugin,
 } from '@mosaicstack/memory';
 import type { Db } from '@mosaicstack/db';
 import type { StorageAdapter } from '@mosaicstack/storage';
@@ -14,6 +16,9 @@ import { DB, STORAGE_ADAPTER } from '../database/database.module.js';
 import { MEMORY } from './memory.tokens.js';
 import { MemoryController } from './memory.controller.js';
 import { EmbeddingService } from './embedding.service.js';
+import { redactSensitiveContent } from '@mosaicstack/log';
+
+export const OPERATOR_MEMORY_PLUGIN = 'OPERATOR_MEMORY_PLUGIN';
 
 export const MEMORY_ADAPTER = 'MEMORY_ADAPTER';
 
@@ -38,9 +43,24 @@ function buildMemoryConfig(config: MosaicConfig, storageAdapter: StorageAdapter)
         createMemoryAdapter(buildMemoryConfig(config, storageAdapter)),
       inject: [MOSAIC_CONFIG, STORAGE_ADAPTER],
     },
+    {
+      provide: OPERATOR_MEMORY_PLUGIN,
+      useFactory: (adapter: MemoryAdapter): OperatorMemoryPlugin | null => {
+        const instanceId = process.env['MOSAIC_OPERATOR_MEMORY_INSTANCE_ID']?.trim();
+        const namespace = process.env['MOSAIC_OPERATOR_MEMORY_NAMESPACE']?.trim();
+        if (!instanceId || !namespace) return null;
+        return createOperatorMemoryPlugin({
+          adapter,
+          instanceId,
+          namespace,
+          redact: (content) => redactSensitiveContent(content).content,
+        });
+      },
+      inject: [MEMORY_ADAPTER],
+    },
     EmbeddingService,
   ],
   controllers: [MemoryController],
-  exports: [MEMORY, MEMORY_ADAPTER, EmbeddingService],
+  exports: [MEMORY, MEMORY_ADAPTER, OPERATOR_MEMORY_PLUGIN, EmbeddingService],
 })
 export class MemoryModule {}

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

@@ -0,0 +1,443 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  createDiscordIngressEnvelope,
+  verifyDiscordIngressEnvelope,
+  DiscordPlugin,
+  type DiscordIngressPayload,
+  parseDiscordInteractionBindings,
+  resolveDiscordInteractionActorId,
+  resolveDiscordInteractionBinding,
+} from '@mosaicstack/discord-plugin';
+import { RuntimeProviderService } from '../agent/runtime-provider-registry.service.js';
+import { ChatGateway } from '../chat/chat.gateway.js';
+import { CommandAuthorizationService } from '../commands/command-authorization.service.js';
+import { validateDiscordServiceToken } from '../chat/chat.gateway-auth.js';
+import { DiscordReplayProtector } from './discord-replay-protector.js';
+
+const SERVICE_TOKEN = 'test-service-token';
+const ENV_KEYS = [
+  'DISCORD_SERVICE_TOKEN',
+  'DISCORD_SERVICE_USER_ID',
+  'DISCORD_SERVICE_TENANT_ID',
+  'DISCORD_INTERACTION_BINDINGS',
+  'DISCORD_ALLOWED_GUILD_IDS',
+  'DISCORD_ALLOWED_CHANNEL_IDS',
+  'DISCORD_ALLOWED_USER_IDS',
+  'MOSAIC_AGENT_NAME',
+] as const;
+const savedEnv = new Map<string, string | undefined>();
+
+function configureDiscordEnv(role: 'admin' | 'member' = 'admin'): void {
+  for (const key of ENV_KEYS) savedEnv.set(key, process.env[key]);
+  process.env['DISCORD_SERVICE_TOKEN'] = SERVICE_TOKEN;
+  process.env['DISCORD_SERVICE_USER_ID'] = 'discord-service';
+  process.env['DISCORD_SERVICE_TENANT_ID'] = 'tenant-discord';
+  process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+  process.env['DISCORD_ALLOWED_GUILD_IDS'] = 'guild-001';
+  process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
+  process.env['DISCORD_ALLOWED_USER_IDS'] = 'user-001';
+  process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+    {
+      instanceId: 'Nova',
+      guildId: 'guild-001',
+      channelId: 'channel-001',
+      pairedUsers: {
+        'user-001': {
+          role: role === 'admin' ? 'admin' : 'operator',
+          mosaicUserId: 'mosaic-admin-001',
+        },
+      },
+    },
+  ]);
+}
+
+afterEach((): void => {
+  for (const key of ENV_KEYS) {
+    const value = savedEnv.get(key);
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  savedEnv.clear();
+});
+
+function commandAuthorization(role: 'admin' | 'member'): CommandAuthorizationService {
+  const entries = new Map<string, string>();
+  const db = {
+    select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role }] }) }) }),
+  };
+  const redis = {
+    get: async (key: string) => entries.get(key) ?? null,
+    set: async (key: string, value: string) => entries.set(key, value),
+    del: async (key: string) => Number(entries.delete(key)),
+  };
+  return new CommandAuthorizationService(db as never, redis);
+}
+
+function discordGateway(role: 'admin' | 'member'): {
+  gateway: ChatGateway;
+  client: { data: { discordService: boolean }; emit: ReturnType<typeof vi.fn> };
+  consumedActions: Array<{ actorId: string; correlationId: string }>;
+  durable: { getSnapshot: ReturnType<typeof vi.fn> };
+  audit: { record: ReturnType<typeof vi.fn> };
+} {
+  const authorization = commandAuthorization(role);
+  const consumedActions: Array<{ actorId: string; correlationId: string }> = [];
+  const durable = {
+    getSnapshot: vi.fn().mockResolvedValue({
+      identity: { agentName: 'Nova', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+    }),
+  };
+  const audit = { record: vi.fn().mockResolvedValue(undefined) };
+  const runtimeRegistry = new RuntimeProviderService(
+    {
+      require: () => ({
+        capabilities: async () => ({ supported: ['session.terminate'] }),
+        terminate: async () => undefined,
+      }),
+    } as never,
+    { record: async () => undefined } as never,
+    {
+      consume: async (approvalId, action) => {
+        consumedActions.push({ actorId: action.actorId, correlationId: action.correlationId });
+        return authorization.consumeRuntimeTerminationApproval(approvalId, action);
+      },
+    },
+  );
+  return {
+    gateway: new ChatGateway(
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      authorization,
+      runtimeRegistry,
+      durable as never,
+      audit as never,
+    ),
+    client: { data: { discordService: true }, emit: vi.fn() },
+    consumedActions,
+    durable,
+    audit,
+  };
+}
+
+function ingressEnvelope(
+  content: string,
+  messageId: string,
+  overrides: Partial<DiscordIngressPayload> = {},
+): ReturnType<typeof createDiscordIngressEnvelope> {
+  return createDiscordIngressEnvelope(
+    createPayload({ content, messageId, ...overrides }),
+    SERVICE_TOKEN,
+  );
+}
+
+function createPayload(overrides: Partial<DiscordIngressPayload> = {}): DiscordIngressPayload {
+  return {
+    correlationId: 'correlation-001',
+    messageId: 'discord-message-001',
+    guildId: 'guild-001',
+    channelId: 'channel-001',
+    userId: 'user-001',
+    conversationId: 'discord-channel-001',
+    content: 'hello Tess',
+    ...overrides,
+  };
+}
+
+describe('Discord ingress security', () => {
+  it('keeps legacy role-only bindings valid while withholding privileged actor identity', () => {
+    const [binding] = parseDiscordInteractionBindings(
+      JSON.stringify([
+        {
+          instanceId: 'Nova',
+          guildId: 'guild-001',
+          channelId: 'channel-001',
+          pairedUsers: { 'user-001': 'admin' },
+        },
+      ]),
+    );
+    expect(
+      resolveDiscordInteractionBinding([binding!], 'guild-001', 'channel-001', 'user-001', 'send'),
+    ).toEqual(binding);
+    expect(resolveDiscordInteractionActorId(binding!, 'user-001')).toBeNull();
+  });
+
+  it('binds a differently named configured interaction instance without code changes', () => {
+    const binding = resolveDiscordInteractionBinding(
+      [
+        {
+          instanceId: 'Nova',
+          guildId: 'guild-001',
+          channelId: 'channel-001',
+          pairedUsers: { 'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' } },
+        },
+      ],
+      'guild-001',
+      'channel-001',
+      'user-001',
+      'send',
+    );
+
+    expect(binding?.instanceId).toBe('Nova');
+  });
+
+  it('accepts only the configured Discord service identity', () => {
+    expect(validateDiscordServiceToken(SERVICE_TOKEN, SERVICE_TOKEN)).toBe(true);
+    expect(validateDiscordServiceToken('wrong-service-token', SERVICE_TOKEN)).toBe(false);
+    expect(validateDiscordServiceToken(undefined, SERVICE_TOKEN)).toBe(false);
+  });
+
+  it('rejects unauthenticated or tampered service envelopes', () => {
+    const envelope = createDiscordIngressEnvelope(createPayload(), SERVICE_TOKEN);
+
+    expect(verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN)).toEqual(createPayload());
+    expect(verifyDiscordIngressEnvelope(envelope, 'wrong-service-token')).toBeNull();
+    expect(
+      verifyDiscordIngressEnvelope(
+        { ...envelope, payload: { ...envelope.payload, content: 'forged command' } },
+        SERVICE_TOKEN,
+      ),
+    ).toBeNull();
+  });
+
+  it.each([
+    ['guild', { guildId: 'unlisted-guild' }],
+    ['channel', { channelId: 'unlisted-channel' }],
+    ['user', { userId: 'unlisted-user' }],
+  ])(
+    'rejects an unallowlisted Discord %s',
+    (_kind: string, overrides: Partial<DiscordIngressPayload>) => {
+      const envelope = createDiscordIngressEnvelope(createPayload(overrides), SERVICE_TOKEN);
+
+      expect(
+        verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
+          guildIds: ['guild-001'],
+          channelIds: ['channel-001'],
+          userIds: ['user-001'],
+        }),
+      ).toBeNull();
+    },
+  );
+
+  it('retains Discord message and correlation IDs after authenticated allowlisted validation', () => {
+    const payload = createPayload({
+      correlationId: 'correlation-trace-123',
+      messageId: 'discord-snowflake-987',
+    });
+    const envelope = createDiscordIngressEnvelope(payload, SERVICE_TOKEN);
+
+    expect(
+      verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
+        guildIds: ['guild-001'],
+        channelIds: ['channel-001'],
+        userIds: ['user-001'],
+      }),
+    ).toEqual(payload);
+  });
+
+  it('rejects a replayed Discord message ID while retaining bounded replay state', () => {
+    const replayProtector = new DiscordReplayProtector(60_000, 2);
+
+    expect(replayProtector.claim('discord-message-001')).toBe(true);
+    expect(replayProtector.claim('discord-message-001')).toBe(false);
+    expect(replayProtector.claim('discord-message-002')).toBe(true);
+    expect(replayProtector.claim('discord-message-003')).toBe(true);
+    expect(replayProtector.size).toBe(2);
+  });
+
+  it('consumes the exact target once when approval and stop are separate Discord messages', async () => {
+    configureDiscordEnv();
+    const { gateway, client, consumedActions } = discordGateway('admin');
+    await gateway.handleDiscordApproval(
+      client as never,
+      ingressEnvelope('/approve', 'approve-message', {
+        correlationId: 'approval-ingress-correlation',
+      }),
+    );
+    const approval = client.emit.mock.calls.find(
+      ([event]) => event === 'discord:approval',
+    )?.[1] as {
+      approvalId: string;
+      success: boolean;
+    };
+    expect(approval.success).toBe(true);
+
+    await gateway.handleDiscordStop(
+      client as never,
+      ingressEnvelope(`/stop ${approval.approvalId}`, 'stop-message', {
+        correlationId: 'stop-ingress-correlation',
+      }),
+    );
+    expect(client.emit).toHaveBeenCalledWith('discord:stop', {
+      correlationId: 'stop-ingress-correlation',
+      success: true,
+    });
+    expect(consumedActions).toEqual([
+      {
+        actorId: 'mosaic-admin-001',
+        correlationId: expect.stringMatching(/^discord-action:v1:/),
+      },
+    ]);
+  });
+
+  it('audits a Discord mint-side authorization denial', async () => {
+    configureDiscordEnv();
+    const { gateway, client, audit } = discordGateway('member');
+
+    await gateway.handleDiscordApproval(
+      client as never,
+      ingressEnvelope('/approve', 'denied-approve'),
+    );
+
+    expect(client.emit).toHaveBeenCalledWith('discord:approval', {
+      correlationId: 'correlation-001',
+      success: false,
+      approvalId: undefined,
+      expiresAt: undefined,
+    });
+    expect(audit.record).toHaveBeenCalledWith(
+      expect.objectContaining({
+        outcome: 'denied',
+        operation: 'session.terminate',
+        errorCode: 'policy_denied',
+      }),
+    );
+  });
+
+  it.each([
+    [
+      'binding',
+      () => {
+        process.env['MOSAIC_AGENT_NAME'] = 'Other';
+      },
+    ],
+    [
+      'durable session',
+      (durable: { getSnapshot: ReturnType<typeof vi.fn> }) => {
+        durable.getSnapshot.mockResolvedValueOnce({
+          identity: { agentName: 'Other', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+        });
+      },
+    ],
+  ])(
+    'rejects approval when the %s targets a different runtime agent',
+    async (_source, configure) => {
+      configureDiscordEnv();
+      const { gateway, client, durable } = discordGateway('admin');
+      configure(durable);
+
+      await gateway.handleDiscordApproval(
+        client as never,
+        ingressEnvelope('/approve', 'mismatched-agent-approve'),
+      );
+
+      expect(client.emit).toHaveBeenCalledWith('discord:approval', {
+        correlationId: 'correlation-001',
+        success: false,
+        approvalId: undefined,
+        expiresAt: undefined,
+      });
+    },
+  );
+
+  it('rejects unpaired and non-admin Discord users for approval and stop', async () => {
+    configureDiscordEnv();
+    const { gateway, client } = discordGateway('member');
+    await gateway.handleDiscordApproval(
+      client as never,
+      ingressEnvelope('/approve', 'member-approve'),
+    );
+    expect(client.emit).toHaveBeenCalledWith('discord:approval', {
+      correlationId: 'correlation-001',
+      success: false,
+      approvalId: undefined,
+      expiresAt: undefined,
+    });
+
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([]);
+    await gateway.handleDiscordStop(
+      client as never,
+      ingressEnvelope('/stop forged', 'unpaired-stop'),
+    );
+    expect(client.emit).not.toHaveBeenCalledWith('discord:stop', expect.anything());
+  });
+
+  it('rejects replaying a Discord-created termination approval', async () => {
+    configureDiscordEnv();
+    const { gateway, client } = discordGateway('admin');
+    await gateway.handleDiscordApproval(
+      client as never,
+      ingressEnvelope('/approve', 'replay-approve', {
+        correlationId: 'replay-approval-correlation',
+      }),
+    );
+    const approval = client.emit.mock.calls.find(
+      ([event]) => event === 'discord:approval',
+    )?.[1] as {
+      approvalId: string;
+    };
+    await gateway.handleDiscordStop(
+      client as never,
+      ingressEnvelope(`/stop ${approval.approvalId}`, 'replay-stop-one', {
+        correlationId: 'replay-stop-correlation-one',
+      }),
+    );
+    await gateway.handleDiscordStop(
+      client as never,
+      ingressEnvelope(`/stop ${approval.approvalId}`, 'replay-stop-two', {
+        correlationId: 'replay-stop-correlation-two',
+      }),
+    );
+    const stopResults = client.emit.mock.calls.filter(([event]) => event === 'discord:stop');
+    expect(stopResults.map(([, result]) => (result as { success: boolean }).success)).toEqual([
+      true,
+      false,
+    ]);
+  });
+
+  it('accepts a thread message through its allowed bound parent channel', () => {
+    const emitted = vi.fn();
+    const plugin = new DiscordPlugin({
+      token: 'unused',
+      gatewayUrl: 'http://unused',
+      serviceToken: SERVICE_TOKEN,
+      allowedGuildIds: ['guild-001'],
+      allowedChannelIds: ['channel-001'],
+      allowedUserIds: ['user-001'],
+      interactionBindings: [
+        {
+          instanceId: 'Nova',
+          guildId: 'guild-001',
+          channelId: 'channel-001',
+          pairedUsers: { 'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' } },
+        },
+      ],
+    });
+    const internals = plugin as unknown as {
+      client: { user: { id: string } };
+      socket: { connected: boolean; emit: ReturnType<typeof vi.fn> };
+      handleDiscordMessage(message: unknown): void;
+    };
+    internals.client = { user: { id: 'bot-001' } };
+    internals.socket = { connected: true, emit: emitted };
+    internals.handleDiscordMessage({
+      id: 'thread-message',
+      guildId: 'guild-001',
+      channelId: 'thread-001',
+      author: { id: 'user-001', bot: false },
+      mentions: { has: () => true },
+      content: '<@bot-001> hello from thread',
+      channel: { parentId: 'channel-001' },
+      attachments: new Map(),
+    });
+
+    const [, envelope] = emitted.mock.calls[0] as [
+      string,
+      ReturnType<typeof createDiscordIngressEnvelope>,
+    ];
+    expect(verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN)?.channelId).toBe('channel-001');
+  });
+});

apps/gateway/src/plugin/discord-replay-protector.ts

@@ -0,0 +1,40 @@
+/**
+ * Bounded replay cache for Discord's globally unique native message IDs.
+ * Durable ingress idempotency is added with Tess's canonical inbox/outbox work.
+ */
+export class DiscordReplayProtector {
+  private readonly claimedAt = new Map<string, number>();
+
+  constructor(
+    private readonly ttlMs = 15 * 60 * 1000,
+    private readonly maxEntries = 10_000,
+  ) {}
+
+  get size(): number {
+    return this.claimedAt.size;
+  }
+
+  /** Claims an ID exactly once within its bounded retention window. */
+  claim(messageId: string, now = Date.now()): boolean {
+    this.prune(now);
+    if (this.claimedAt.has(messageId)) return false;
+
+    this.claimedAt.set(messageId, now);
+    this.evictOverflow();
+    return true;
+  }
+
+  private prune(now: number): void {
+    for (const [messageId, claimedAt] of this.claimedAt) {
+      if (now - claimedAt >= this.ttlMs) this.claimedAt.delete(messageId);
+    }
+  }
+
+  private evictOverflow(): void {
+    while (this.claimedAt.size > this.maxEntries) {
+      const oldestMessageId = this.claimedAt.keys().next().value;
+      if (oldestMessageId === undefined) return;
+      this.claimedAt.delete(oldestMessageId);
+    }
+  }
+}

apps/gateway/src/plugin/plugin.module.ts

@@ -6,7 +6,7 @@ import {
   type OnModuleDestroy,
   type OnModuleInit,
 } from '@nestjs/common';
-import { DiscordPlugin } from '@mosaicstack/discord-plugin';
+import { DiscordPlugin, parseDiscordInteractionBindings } from '@mosaicstack/discord-plugin';
 import { TelegramPlugin } from '@mosaicstack/telegram-plugin';
 import { PluginService } from './plugin.service.js';
 import type { IChannelPlugin } from './plugin.interface.js';
@@ -50,19 +50,44 @@ class TelegramChannelPluginAdapter implements IChannelPlugin {
 
 const DEFAULT_GATEWAY_URL = 'http://localhost:14242';
 
+function requiredDiscordAllowlist(name: string): string[] {
+  const value = process.env[name]
+    ?.split(',')
+    .map((id: string): string => id.trim())
+    .filter((id: string): boolean => id.length > 0);
+  if (!value || value.length === 0) {
+    throw new Error(`${name} is required when DISCORD_BOT_TOKEN is configured`);
+  }
+  return value;
+}
+
 function createPluginRegistry(): IChannelPlugin[] {
   const plugins: IChannelPlugin[] = [];
   const discordToken = process.env['DISCORD_BOT_TOKEN'];
   const discordGuildId = process.env['DISCORD_GUILD_ID'];
   const discordGatewayUrl = process.env['DISCORD_GATEWAY_URL'] ?? DEFAULT_GATEWAY_URL;
+  const discordServiceToken = process.env['DISCORD_SERVICE_TOKEN'];
+  const discordServiceUserId = process.env['DISCORD_SERVICE_USER_ID'];
 
   if (discordToken) {
+    if (!discordServiceToken || !discordServiceUserId) {
+      throw new Error(
+        'DISCORD_SERVICE_TOKEN and DISCORD_SERVICE_USER_ID are required when DISCORD_BOT_TOKEN is configured',
+      );
+    }
     plugins.push(
       new DiscordChannelPluginAdapter(
         new DiscordPlugin({
           token: discordToken,
           guildId: discordGuildId,
           gatewayUrl: discordGatewayUrl,
+          serviceToken: discordServiceToken,
+          allowedGuildIds: requiredDiscordAllowlist('DISCORD_ALLOWED_GUILD_IDS'),
+          allowedChannelIds: requiredDiscordAllowlist('DISCORD_ALLOWED_CHANNEL_IDS'),
+          allowedUserIds: requiredDiscordAllowlist('DISCORD_ALLOWED_USER_IDS'),
+          interactionBindings: parseDiscordInteractionBindings(
+            process.env['DISCORD_INTERACTION_BINDINGS'],
+          ),
         }),
       ),
     );

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

@@ -1,11 +1,13 @@
-import { Inject, Injectable, Logger, Optional, type OnApplicationShutdown } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
-import type { MosaicConfig } from '@mosaicstack/config';
-import { MOSAIC_CONFIG } from '../config/config.module.js';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 
-const SESSION_SYSTEM_KEY = (sessionId: string) => `mosaic:session:${sessionId}:system`;
-const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string) =>
-  `mosaic:session:${sessionId}:system:fragments`;
+const scopedSessionId = (sessionId: string, scope: ActorTenantScope) =>
+  `${scope.tenantId}:${scope.userId}:${sessionId}`;
+const SESSION_SYSTEM_KEY = (sessionId: string, scope: ActorTenantScope) =>
+  `mosaic:session:${scopedSessionId(sessionId, scope)}:system`;
+const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string, scope: ActorTenantScope) =>
+  `mosaic:session:${scopedSessionId(sessionId, scope)}:system:fragments`;
 const SYSTEM_OVERRIDE_TTL_SECONDS = 604800; // 7 days
 
 interface OverrideFragment {
@@ -13,56 +15,18 @@ interface OverrideFragment {
   addedAt: number;
 }
 
-interface LocalOverrideEntry {
-  condensed: string;
-  fragments: OverrideFragment[];
-}
-
 @Injectable()
-export class SystemOverrideService implements OnApplicationShutdown {
+export class SystemOverrideService {
   private readonly logger = new Logger(SystemOverrideService.name);
-  private readonly handle: QueueHandle | null;
-  /**
-   * In-memory fallback used on Local tier (no Redis).
-   * NOTE: state is ephemeral — lost on restart. For Local single-user installs
-   * this is acceptable; system overrides are re-applied at the next session.
-   * This is a deliberate behavior change from the Redis-backed 7-day TTL.
-   */
-  private readonly localStore = new Map<string, LocalOverrideEntry>();
+  private readonly handle: QueueHandle;
 
-  constructor(
-    @Optional()
-    @Inject(MOSAIC_CONFIG)
-    private readonly mosaicConfig: MosaicConfig | null,
-  ) {
-    if (this.mosaicConfig?.queue?.type === 'local') {
-      this.handle = null;
-    } else {
-      this.handle = createQueue();
-    }
+  constructor() {
+    this.handle = createQueue();
   }
 
-  async onApplicationShutdown(): Promise<void> {
-    // On non-local tiers the constructor opens an ioredis connection; close it
-    // on graceful shutdown to avoid leaking the handle (local tier is null).
-    await this.handle?.close().catch(() => {});
-  }
-
-  async set(sessionId: string, override: string): Promise<void> {
-    if (!this.handle) {
-      // Local tier: in-memory path
-      const entry = this.localStore.get(sessionId) ?? { condensed: '', fragments: [] };
-      entry.fragments.push({ text: override, addedAt: Date.now() });
-      entry.condensed = await this.condenseOverrides(entry.fragments.map((f) => f.text));
-      this.localStore.set(sessionId, entry);
-      this.logger.debug(
-        `Set system override for session ${sessionId} (local, ${entry.fragments.length} fragment(s))`,
-      );
-      return;
-    }
-
+  async set(sessionId: string, override: string, scope: ActorTenantScope): Promise<void> {
     // Load existing fragments
-    const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId));
+    const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope));
     const fragments: OverrideFragment[] = existing
       ? (JSON.parse(existing) as OverrideFragment[])
       : [];
@@ -77,11 +41,11 @@ export class SystemOverrideService implements OnApplicationShutdown {
     // Store both: fragments array and condensed result
     const pipeline = this.handle.redis.pipeline();
     pipeline.setex(
-      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
+      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
       SYSTEM_OVERRIDE_TTL_SECONDS,
       JSON.stringify(fragments),
     );
-    pipeline.setex(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
+    pipeline.setex(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
     await pipeline.exec();
 
     this.logger.debug(
@@ -89,33 +53,21 @@ export class SystemOverrideService implements OnApplicationShutdown {
     );
   }
 
-  async get(sessionId: string): Promise<string | null> {
-    if (!this.handle) {
-      return this.localStore.get(sessionId)?.condensed ?? null;
-    }
-    return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId));
+  async get(sessionId: string, scope: ActorTenantScope): Promise<string | null> {
+    return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId, scope));
   }
 
-  async renew(sessionId: string): Promise<void> {
-    if (!this.handle) {
-      // Local tier: no TTL to renew; entry persists until restart
-      return;
-    }
+  async renew(sessionId: string, scope: ActorTenantScope): Promise<void> {
     const pipeline = this.handle.redis.pipeline();
-    pipeline.expire(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
-    pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
+    pipeline.expire(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
+    pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
     await pipeline.exec();
   }
 
-  async clear(sessionId: string): Promise<void> {
-    if (!this.handle) {
-      this.localStore.delete(sessionId);
-      this.logger.debug(`Cleared system override for session ${sessionId} (local)`);
-      return;
-    }
+  async clear(sessionId: string, scope: ActorTenantScope): Promise<void> {
     await this.handle.redis.del(
-      SESSION_SYSTEM_KEY(sessionId),
-      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
+      SESSION_SYSTEM_KEY(sessionId, scope),
+      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
     );
     this.logger.debug(`Cleared system override for session ${sessionId}`);
   }

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

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

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

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

docs/MISSION-MANIFEST.md

@@ -10,9 +10,9 @@
 **Statement:** Ship a self-hosted, multi-user AI agent platform that consolidates the user's disparate jarvis-brain usage across home and USC workstations into a single coherent system reachable via three first-class surfaces — webUI, TUI, and CLI — with federation as the data-layer mechanism that makes cross-host agent sessions work in real time without copying user data across the boundary.
 **Phase:** Execution (workstream W1 in planning-complete state)
 **Current Workstream:** W1 — Federation v1
-**Progress:** 0 / 1 declared workstreams complete (more workstreams will be declared as scope is refined)
+**Progress:** 0 / 3 declared workstreams complete (more workstreams will be declared as scope is refined)
 **Status:** active (continuous since 2026-03-13)
-**Last Updated:** 2026-04-19 (manifest authored at the rollup level; install-ux-v2 archived; W1 federation planning landed via PR #468)
+**Last Updated:** 2026-07-14 (W3 Native Kanban/SOT canon independently approved under issue #751)
 **Source PRD:** [docs/PRD.md](./PRD.md) — Mosaic Stack v0.1.0
 **Scratchpad:** [docs/scratchpads/mvp-20260312.md](./scratchpads/mvp-20260312.md) (active since 2026-03-13; 14 prior sessions of phase-based execution)
 
@@ -67,10 +67,12 @@ The MVP is complete when ALL declared workstreams are complete AND every cross-c
 
 ## Workstreams
 
-| #   | ID  | Name                                        | Status            | Manifest                                                                | Notes                                               |
-| --- | --- | ------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
-| W1  | FED | Federation v1                               | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) | 7 milestones, ~175K tokens, issues #460–#466 filed  |
-| W2+ | TBD | (additional workstreams declared as scoped) | —                 | —                                                                       | Scope creep is expected and explicitly accommodated |
+| #   | ID   | Name                                        | Status            | Manifest                                                                              | Notes                                                    |
+| --- | ---- | ------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| W1  | FED  | Federation v1                               | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md)               | 7 milestones, ~175K tokens, issues #460–#466 filed       |
+| W2  | TESS | Tess interaction agent                      | planning-complete | [docs/tess/MISSION-MANIFEST.md](./tess/MISSION-MANIFEST.md)                           | 5 milestones; issue #706; M1 issue #707 ready            |
+| W3  | KBN  | Native Kanban and canonical task SOT        | planning-complete | [docs/native-kanban-sot/MISSION-MANIFEST.md](./native-kanban-sot/MISSION-MANIFEST.md) | P0–P3; issue #751; implementation held until canon merge |
+| W4+ | TBD  | (additional workstreams declared as scoped) | —                 | —                                                                                     | Scope creep is expected and explicitly accommodated      |
 
 ### Likely Additional Workstreams (Not Yet Declared)
 

docs/PRD.md

@@ -79,6 +79,148 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 
 ---
 
+## Fleet Declarative Configuration Management Workstream (FCM, #758)
+
+### Problem and objective
+
+The local Mosaic fleet has a roster, generated agent environment files, user-systemd units, tmux
+sessions, heartbeat files, examples, profiles, and separate gateway-backed agent records. These
+planes have drifted and are not one safe operator lifecycle. The objective is one **local fleet
+roster** as the desired-state SSOT, with generated environment, systemd, tmux, and heartbeat
+artifacts as rebuildable projections; it does not merge the local fleet control plane with the
+gateway-backed agent catalog.
+
+### Normative requirements
+
+| ID           | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FCM-REQ-01` | The roster SHALL be the sole writable desired-state source for local fleet membership, launch policy, and persisted lifecycle target. Generated environment files, systemd enablement, tmux sessions, and heartbeat state SHALL be non-authoritative projections.                                                                                                                                                                                                         |
+| `FCM-REQ-02` | The implementation SHALL provide one executable structural contract for YAML/JSON input and one shared semantic validator. Roster load, profile validation, provision, migration, and apply SHALL reuse the existing baseline-plus-`roles.local` profile/persona resolver; a parallel role resolver is forbidden.                                                                                                                                                         |
+| `FCM-REQ-03` | The local fleet CLI SHALL expose documented programmatic validate, show, plan, apply/reconcile, create, inspect, update, delete, start, stop, restart, status, verify, and doctor operations with stable JSON and exit-code behavior. Existing `fleet add/remove` compatibility aliases may remain during the stated deprecation window.                                                                                                                                  |
+| `FCM-REQ-04` | A fresh create SHALL persist `enabled:true` and `desired_state:stopped` unless an explicit persisted start is requested. The model SHALL distinguish enabled state, persisted desired state, and observed state. Migration, apply, reboot, and rollback SHALL not start an agent that was observed stopped before cutover.                                                                                                                                                |
+| `FCM-REQ-05` | The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash.                     |
+| `FCM-REQ-06` | Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name.                                                                                                                                    |
+| `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities. |
+| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note.                                                |
+| `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model.                                                                                                                                                                                              |
+| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence.                                                                                                  |
+
+### Acceptance criteria
+
+1. `AC-FCM-01`: A valid local v2 roster can be parsed from YAML or JSON, validated structurally and semantically through the shared resolver, and rendered canonically; invalid fields, duplicate names, unresolved classes, unsupported runtime/model combinations, socket ambiguity, and incompatible options fail closed.
+2. `AC-FCM-02`: `plan` reports deterministic desired-versus-observed differences for roster, generated environment, systemd enablement, tmux/session, heartbeat, installed-asset revision, and provable orphans without mutation; `apply --check` reports drift without mutation.
+3. `AC-FCM-03`: Local create/update/delete is generation-guarded, atomic, idempotent, and safe by default; it permits supported runtime/model/harness/effort/workdir/role changes without direct editing of generated environment files and does not start a newly created agent unless explicitly persisted.
+4. `AC-FCM-04`: The generated-env/local-override launch chain rejects generated-key shadowing, arbitrary command override, unknown keys, shell evaluation, and sensitive-value diagnostics before any agent starts; known-safe legacy input is regenerated or strictly relocated, and forbidden input is quarantined.
+5. `AC-FCM-05`: Local lifecycle reconciliation implements the persisted/transient start-stop rules, exact default/named tmux socket targeting, systemd/tmux status, stale generated state, unmanaged-session reporting, and rollback without surprise restarts or fuzzy destructive targeting.
+6. `AC-FCM-06`: A v1 roster migration previews field-by-field disposition, preserves observed stopped/running state, inventories rather than reconciles remote/schema-only entries, supports a canary and rollback, and classifies every shipped example, profile, and service preset according to the M0 inventory.
+7. `AC-FCM-07`: Required role authority is validated: validator certificate is consumed but does not merge, merge-gate is the sole merge authority, team-leader leases do not change roster/credentials/authority, and interaction/Tess cannot claim orchestration or merge powers.
+8. `AC-FCM-08`: Documentation, examples, migration, troubleshooting, operational recovery, package/update asset drift, schema/example/profile validation, independent code/security review, validator certificate, and terminal-green CI are complete before #758 closes.
+
+### M0 implementation gate
+
+No source, schema, role, example, profile, systemd, or live-fleet change is authorized before M0
+lands. M0 consists only of these normative requirements, the complete task DAG, the scoped
+documentation IA checklist, and the legacy example/profile disposition inventory. Subsequent cards
+are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
+
+---
+
+## Tess Interaction Agent Workstream (TESS)
+
+### Problem and Objective
+
+Jason needs one durable, operator-facing Mosaic agent outside Hermes that is reachable through a dedicated Discord channel and CLI, can attach to and operate the Mosaic fleet and transitional Hermes agents, and preserves context across restarts and compaction. Mos remains the coding/general fleet orchestrator; Tess is the complementary human interaction, visibility, control, and migration agent.
+
+The objective is to ship **Tess** (from _tessera_, a piece of a mosaic) as a Pi-native, GPT-5.6 Sol agent with high reasoning. Tess must use Mosaic-owned contracts and plugins so Hermes can be replaced incrementally rather than becoming a permanent architectural dependency.
+
+### Scope
+
+#### In Scope
+
+1. `TESS-ARP-001`: A runtime-neutral `AgentRuntimeProvider` contract supporting `listSessions`, `streamSession`, `sendMessage`, `terminate`, `getSessionTree`, `attach`, health, capability discovery, and normalized events/errors.
+2. `TESS-PI-001`: A long-running Pi-native Tess agent profile/service pinned to GPT-5.6 Sol with high reasoning, explicit tool policy, lifecycle hooks, durable checkpoints, and restart recovery.
+3. `TESS-DSC-001`: Dedicated Discord channel binding to Tess through the Mosaic gateway, with allowlists/RBAC, thread/reply policy, streaming, attachments, approvals, and correlation IDs.
+4. `TESS-CLI-001`: `mosaic tess` CLI commands for chat, status, session listing, attach/detach, send/steer/stop, provider health, and recovery.
+5. `TESS-FLT-001`: Fleet plugin capabilities for roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, and controlled restart/recovery.
+6. `TESS-MOS-001`: Explicit Mos coordination boundary and tools: hand off orchestration requests, observe mission/task state, receive results, and never silently compete for orchestration authority.
+7. `TESS-HRM-001`: Transitional Hermes adapter for profiles/agents, sessions, streaming/messages, Kanban, skills, memory, tools, cron, and health, using capability negotiation and fail-closed unsupported operations.
+8. `TESS-MEM-001`: Unified memory/retrieval plugin with scoped search/recent/capture/stats, startup context injection, provenance, redaction, namespace isolation, and flat-file/project truth precedence.
+9. `TESS-STA-001`: Durable agent state, inbox, handoff, compaction-recovery, and resume reconstruction.
+10. `TESS-PLG-001`: Plugin/tool catalog covering runtime bootstrap, repository/PR workflow, fleet diagnostics, incident-safe read operations, Discord interaction, and extensible MCP/skill discovery.
+11. `TESS-TRN-001`: Replaceable transport providers: tmux/fleet now, Matrix/native Mosaic transport later, with no Discord/CLI business logic coupled to transport details.
+12. `TESS-SEC-001`: RBAC, per-operation authorization, explicit approval for destructive/privileged/customer-visible actions, audit events, secret/PII redaction, tenant isolation, and bounded command execution.
+13. `TESS-SEC-002`: Command execution SHALL enforce declared scope/role server-side; admin/system and destructive operations SHALL require policy-bound durable approval.
+14. `TESS-SEC-003`: Every session list/read/attach/send/terminate operation SHALL enforce server-derived owner and tenant scope; guessed or client-supplied IDs SHALL grant no authority.
+15. `TESS-SEC-004`: MCP tools SHALL derive actor/tenant from authenticated context and SHALL NOT accept caller-controlled identity fields.
+16. `TESS-SEC-005`: Discord plugin ingress SHALL authenticate service identity, enforce guild/channel/user allowlists, propagate correlation/message IDs, and reject replay.
+17. `TESS-SEC-006`: Secret/PII classification and redaction SHALL occur before persistence and before channel egress, including tool metadata and authentication flows.
+18. `TESS-SEC-007`: Approvals SHALL be one-time, expiring, actor/tenant-bound, and cryptographically bound to the exact structured action digest.
+19. `TESS-SEC-008`: Ingress, provider sends, tool side effects, and responses SHALL use durable inbox/outbox/checkpoints and idempotency records for restart-safe replay.
+20. `TESS-SEC-009`: Garbage collection and retention SHALL be session/tenant scoped unless executed as a separately authorized and audited system-wide job.
+21. `TESS-OBS-001`: Structured logs, traces, health/readiness, provider latency/errors, session lifecycle, tool audit, and actionable recovery diagnostics.
+22. `TESS-MIG-001`: Capability inventory and staged Hermes-to-Mosaic migration matrix with coexistence, cutover, rollback, and deprecation gates.
+
+#### Out of Scope
+
+1. Replacing Mos as coding/general fleet orchestrator.
+2. Making Hermes the Mosaic core or coupling Mosaic domain logic to Hermes schemas.
+3. Migrating every historical chat verbatim; only policy-compliant indexed summaries and user-selected sessions are migrated.
+4. Unrestricted shell execution from Discord.
+5. Full web UI parity in the first Tess operational milestone; gateway contracts must remain web-consumable.
+6. Replacing tmux before Matrix/native transport reaches operational parity.
+
+### Stakeholder and User Requirements
+
+- Jason must be able to converse with the same Tess session from Discord and CLI.
+- Jason must be able to see what is running, stale, blocked, or unhealthy without attaching manually to every session.
+- Jason must be able to attach to Tess and authorized fleet sessions through supported CLI controls.
+- Tess must collaborate with Mos and the fleet while preserving a single clear orchestration authority.
+- The system must migrate useful Hermes/OpenClaw capabilities intentionally, with evidence, instead of copying implementations wholesale.
+
+### Non-Functional Requirements
+
+1. **Security:** default-deny provider/tool capabilities, least privilege, no secrets in logs/prompts/commits, Discord user/channel authorization, and auditable approvals.
+2. **Reliability:** durable inbox/checkpoints; idempotent message handling; reconnect with bounded backoff; no message loss or duplicate execution across gateway restart.
+3. **Performance:** first acknowledgement within 2 seconds when connected; streamed agent output begins within 5 seconds excluding model/provider delay; status reads return within 2 seconds under nominal local conditions.
+4. **Observability:** every ingress message and resulting provider/tool operation carries a correlation ID across Discord, gateway, Tess, provider, and audit events.
+5. **Maintainability:** channel, runtime, transport, memory, and external-agent integrations remain adapter-based with contract tests.
+6. **Privacy:** only scoped context enters external runtimes; persisted messages/memories follow retention and redaction policy.
+7. **Portability:** Tess runs through Pi/Mosaic contracts and does not require Hermes to start or serve native Mosaic operations.
+
+### Acceptance Criteria
+
+1. `AC-TESS-01`: A dedicated Discord channel and `mosaic tess chat` connect to one durable Tess session and stream responses bidirectionally.
+2. `AC-TESS-02`: `mosaic tess status|sessions|tree|attach|send|stop` operate against authorized provider capabilities with stable typed outputs and actionable errors.
+3. `AC-TESS-03`: Tess runs GPT-5.6 Sol at high reasoning and its effective runtime/model/tool policy is visible through status without exposing credentials.
+4. `AC-TESS-04`: Tess can inspect and message the Mosaic fleet, hand orchestration work to Mos, and demonstrate that Tess does not independently claim Mos-owned orchestration work.
+5. `AC-TESS-05`: Hermes adapter demonstrates session listing, streaming/message delivery, hierarchy mapping, and at least one approved capability in each of Kanban, skills, memory, tools, and cron—or reports unsupported capabilities fail-closed.
+6. `AC-TESS-06`: Restart/compaction test preserves session identity, pending inbox, last durable checkpoint, and a resumable handoff without duplicate side effects.
+7. `AC-TESS-07`: Unauthorized Discord users/channels, cross-tenant access, unsafe tool calls, forged approvals, and sensitive-output cases are denied and audited.
+8. `AC-TESS-08`: tmux/fleet and Matrix/native transport implementations pass the same provider contract suite; Matrix may remain non-default until readiness gates pass.
+9. `AC-TESS-09`: Baseline quality gates, unit/integration/contract tests, Discord+CLI E2E, restart/recovery tests, independent code review, and security review are green.
+10. `AC-TESS-10`: Migration matrix documents every audited Hermes/OpenClaw capability as native, adapted, deferred, or rejected, with cutover and rollback evidence.
+11. `AC-TESS-11`: User, admin, developer, API/OpenAPI, operations/recovery, and plugin-authoring documentation is current and linked from the sitemap.
+
+### Constraints, Dependencies, Risks, and Assumptions
+
+- Dependency: Mosaic gateway remains the single API surface; Pi is the native runtime; Valkey/PostgreSQL provide canonical durable state where required.
+- Dependency: Discord bot credentials and dedicated channel ID are deployment secrets provisioned outside source control.
+- Risk: Tess could drift into a second orchestrator. Mitigation: explicit role policy, Mos handoff contract, authority checks, and E2E boundary tests.
+- Risk: broad Hermes compatibility can freeze legacy semantics into Mosaic. Mitigation: Mosaic-owned normalized contracts and capability negotiation.
+- Risk: Discord creates a privileged remote-control surface. Mitigation: pairing/allowlists, RBAC, approvals, rate limits, audit, and safe tool classes.
+- Risk: transcript ingestion can violate privacy or overload memory. Mitigation: scoped opt-in import, redacted summaries, provenance, retention, and deduplication.
+- Risk: current root filesystem has limited headroom. Mitigation: isolated worktrees, no duplicated dependency installation unless required, and cleanup only after active-lane verification.
+- `ASSUMPTION:` The public name is **Tess**, because the user requested a name and the tessera/Mosaic relationship is distinctive; config must permit later display-name changes without renaming APIs or storage keys.
+- `ASSUMPTION:` The dedicated Discord channel ID and final guild policy will be supplied/provisioned during deployment, so implementation uses explicit configuration and fail-fast startup validation.
+- `ASSUMPTION:` tmux/fleet is the production transport for the first operational milestone; Matrix/native transport is implemented behind the same contract and promoted only after parity/reliability verification.
+- `ASSUMPTION:` Project/task truth remains in canonical Mosaic/project stores; semantic memory systems are retrieval/mirror layers, not hidden authorities.
+
+### Testing and Delivery Intent
+
+Delivery uses five gated milestones: runtime contracts/security; Pi service/state; Discord/CLI; fleet/Hermes/plugin suite; migration/Matrix/recovery/qualification. Every source-code task requires tests, independent review, a PR to `main`, terminal-green CI, and issue/task closure. Production activation additionally requires a clean-host Pi launch, dedicated Discord channel smoke test, CLI attach test, restart/recovery drill, and rollback procedure.
+
+---
+
 ## Architecture
 
 ### High-Level System Diagram

docs/SITEMAP.md

@@ -0,0 +1,50 @@
+# Documentation Sitemap
+
+## Native Kanban and canonical task SOT
+
+- [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.
+- [Frozen shared contract](native-kanban-sot/SHARED-CONTRACT.md) — schema, API, Coordinator, health, recovery, and migration contracts.
+- [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.
+
+## Tess interaction agent
+
+### Operator guides
+
+- [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.
+
+### Architecture and security
+
+- [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 contract
+
+- [Tess OpenAPI contract](openapi-tess.yaml)
+
+### Migration and qualification
+
+- [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)
+
+## Runtime-neutral Mos portability
+
+- [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)

docs/TASKS.md

@@ -14,9 +14,12 @@
 
 ## Workstream Rollup
 
-| id  | status            | workstream          | progress         | tasks file                                        | notes                                                           |
-| --- | ----------------- | ------------------- | ---------------- | ------------------------------------------------- | --------------------------------------------------------------- |
-| W1  | planning-complete | Federation v1 (FED) | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md) | M1 task breakdown populated; M2–M7 deferred to mission planning |
+| id  | status            | workstream                     | progress         | tasks file                                                      | notes                                                                             |
+| --- | ----------------- | ------------------------------ | ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| W1  | planning-complete | Federation v1 (FED)            | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md)               | M1 task breakdown populated; M2–M7 deferred to mission planning                   |
+| W2  | planning-complete | Tess interaction agent         | 0 / 5 milestones | [docs/tess/TASKS.md](./tess/TASKS.md)                           | Issue #706; independent planning gate PASS; M1 issue #707 ready                   |
+| W3  | planning-complete | Native Kanban/SOT              | 0 / 4 phases     | [docs/native-kanban-sot/TASKS.md](./native-kanban-sot/TASKS.md) | Issue #751; canon independently approved; implementation held until canon merges  |
+| W4  | planning-complete | Fleet configuration management | 0 / 12 cards     | This file (§ Fleet configuration management #758)               | Issue #758; M0 docs gate defines the implementation DAG before any fleet mutation |
 
 ## Cross-Cutting Tracking
 
@@ -40,6 +43,30 @@ Active workstream is **W1 — Federation v1**. Workers should:
 2. Read [docs/federation/TASKS.md](./federation/TASKS.md) for the next pending task
 3. Follow per-task agent + tier guidance from the workstream manifest
 
+## Fleet configuration management (#758) — M0–M5 implementation DAG
+
+> **PRD:** [Fleet declarative configuration management](./PRD.md#fleet-declarative-configuration-management-workstream-fcm-758) · **M0 acceptance:** [docs IA checklist](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) · **baseline dispositions:** [legacy example/profile inventory](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md)
+>
+> Every row below is one independently reviewable card and **one PR**. `depends_on` is a
+> hard DAG edge; no card may silently absorb another card's scope. All source cards require
+> the repository quality gates, independent code and security review, terminal-green CI, and
+> the applicable acceptance evidence before merge. Issue #758 remains open until M5 closes.
+
+| id         | status      | description                                                                                                                                                            | issue | agent  | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                            |
+| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
+| FCM-M0-001 | in-progress | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | M0 exit: approved docs; every shipped example/profile/service preset classified; docs-only PR                    |
+| FCM-M1-001 | not-started | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | codex  | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | No lifecycle, remote, connector, secret, channel, or gateway work                                                |
+| FCM-M1-002 | not-started | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | codex  | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | Validator is certificate-only; merge-gate remains sole merge authority                                           |
+| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex  | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | Every shipped artifact must validate, be versioned v1, or be retired with replacement                            |
+| FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex  | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | No arbitrary command compatibility path; diagnostics expose key names/hashes only                                |
+| FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex  | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | Fresh create persists stopped unless explicit persisted start                                                    |
+| FCM-M3-001 | not-started | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex  | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | Exact systemd/tmux ownership; remote/schema-only entries are inventory only                                      |
+| FCM-M3-002 | not-started | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Proves stopped-state preservation and zero fuzzy destructive targeting                                           |
+| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex  | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | Preview first; no unreviewed lifecycle inference                                                                 |
+| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | Never starts a previously stopped agent or kills an unproven unmanaged session                                   |
+| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku  | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Must close every checklist item or record an approved deferral                                                   |
+| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI |
+
 ## Thin-core prompt diet (#528) — feat/contract-thin-core
 
 - Status: PR open, awaiting maintainer merge ratification (fleet-governing change).

docs/architecture/ADR-MOS-EGRESS-GATEWAYS.md

@@ -0,0 +1,151 @@
+# ADR: Optional AI egress gateways for runtime-neutral Mos
+
+**Status:** Proposed for controlled prototypes; not approved as Mosaic core
+
+**Date:** 2026-07-14
+
+**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, and inference transport are separate concerns.
+2. A generic AI gateway can improve provider routing, budgets, and observability, but must not become Mosaic's identity, authorization, tenant, or orchestration boundary.
+
+The Tess qualification report also found that current provider rebinding is not identity-continuous failover. Mosaic still needs a logical agent identity, durable connector lease/fencing, canonical handoff/checkpoint, exactly-once receipts, concrete harness adapters, and cross-harness rollback E2E.
+
+## Decision
+
+Mosaic MAY support LiteLLM, Bifrost, the purpose-built Claude/Codex proxy, or future gateways as optional egress implementations behind `IProviderAdapter` / `AgentRuntimeProvider`.
+
+Mosaic Gateway remains authoritative for:
+
+- authenticated actor and tenant identity;
+- logical agent identity and connector binding;
+- authorization, approval, and policy;
+- lease epoch and stale-holder fencing;
+- audit correlation and redaction;
+- canonical handoff/checkpoint state;
+- idempotency and side-effect receipts.
+
+An egress gateway MUST NOT:
+
+- receive channel ingress directly;
+- authorize tools or connector ownership;
+- define Mosaic tenant or agent identity;
+- persist raw Mosaic handoffs or channel credentials;
+- bypass adapter capability negotiation;
+- silently fail over when policy, lease, or provider health is uncertain.
+
+Allowed topology:
+
+```text
+Discord / Matrix / CLI / web
+        ↓
+Mosaic Gateway: identity, authz, lease/fence, approvals, audit
+        ↓
+IProviderAdapter / AgentRuntimeProvider
+        ↓
+optional egress gateway
+        ↓
+upstream provider or subscription-backed OAuth session
+```
+
+## Candidate assessment
+
+### Purpose-built `raine/claude-code-proxy`
+
+**Disposition:** Approved only for the verified emergency localhost bridge.
+
+Strengths:
+
+- explicit Codex device OAuth flow;
+- small operational surface;
+- Anthropic Messages translation suitable for Claude Code;
+- model and reasoning-effort enforcement;
+- straightforward loopback systemd supervision and rollback.
+
+Constraints:
+
+- not a Mosaic multi-tenant control plane;
+- Claude built-in channels still depend on Claude subscription entitlement and feature lookup;
+- model aliases can obscure the upstream model unless proxy policy/logs are treated as evidence;
+- no replacement for connector leasing, canonical handoff, or exactly-once effects.
+
+### LiteLLM
+
+**Disposition:** Candidate for a formal adapter-only prototype and terms/security review.
+
+Current documentation states that ChatGPT subscription access is available through an OAuth device-code flow. LiteLLM also provides broad provider routing, virtual keys, budgets, observability, and OpenAI/Anthropic-compatible surfaces.
+
+Required prototype gates:
+
+- verify the exact ChatGPT subscription OAuth flow and supported models against current provider terms;
+- document token location, encryption, revocation, refresh, scope, and incident response;
+- prove tenant isolation and prevent virtual keys from becoming Mosaic principals;
+- verify streaming, tool calls, reasoning controls, cancellation, and idempotency metadata;
+- fail closed instead of selecting an unhealthy provider merely to return a result;
+- demonstrate that Mosaic audit correlation survives gateway retries/failover;
+- keep channel ingress and connector credentials 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:** Candidate for governance/routing research; subscription OAuth compatibility unverified.
+
+Useful concepts include virtual keys, budgets, rate limits, weighted load balancing, and automatic provider failover. Those features may inform Mosaic egress policy, but Bifrost virtual keys are downstream credentials—not Mosaic actors or tenants.
+
+Required prototype gates:
+
+- verify Codex/ChatGPT subscription OAuth rather than assuming API-key compatibility;
+- map budgets and virtual keys to server-derived Mosaic tenants without duplicating authority;
+- prove failover does not violate connector lease, approval, or exactly-once semantics;
+- ensure request/response logs are redacted before persistence;
+- disable or constrain automatic failover when policy or side-effect state is ambiguous.
+
+Source references:
+
+- [Bifrost overview](https://docs.getbifrost.ai/overview)
+- [Bifrost repository](https://github.com/maximhq/bifrost)
+
+### `teremterem/claude-code-gpt-5-codex`
+
+**Disposition:** Not selected as the emergency implementation; useful as a historical LiteLLM recipe.
+
+The reviewed repository uses `OPENAI_API_KEY`, tells previously authenticated Claude users to log out, and documents a Claude Web Search schema incompatibility. Logging Claude out conflicts with the channel-entitlement requirement observed in the live Mos cutover. The repository therefore does not, as provided, satisfy subscription-OAuth plus built-in-channel continuity.
+
+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)
+
+## 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, or agent authority.
+- Automatic retry/failover can duplicate tool or external side effects unless Mosaic owns operation IDs and receipts.
+- Gateway telemetry can contain prompts, tool schemas, and model output; redaction and retention policy must apply before persistence.
+- A localhost unauthenticated translation endpoint must remain loopback-only and process-isolated.
+
+## Acceptance before production use
+
+1. Threat model and provider-terms review approved.
+2. Credential lifecycle and revocation drill documented and exercised.
+3. Adapter contract tests pass for streaming, tools, cancellation, reasoning policy, errors, and audit correlation.
+4. Tenant-bound authorization remains entirely in Mosaic Gateway.
+5. Failure injection proves no duplicate side effects across retries or provider failover.
+6. Rollback to the prior provider path is exercised.
+7. Independent code and security reviews approve the exact deployed revision.
+
+## Follow-up
+
+- #754 owns cross-harness logical identity, checkpoint, receipt, adapter, and failover work.
+- #755 / PR #757 implements the first logical identity and connector lease/fencing boundary.
+- A later issue should prototype LiteLLM and Bifrost behind the provider adapter after #755 is merged and independently qualified.

docs/architecture/channel-protocol.md

@@ -232,6 +232,10 @@ The following sections document how each supported channel maps its native messa
 
 **Outbound:** Adapter calls Discord REST `POST /channels/{id}/messages`. Markdown content is sent as-is (Discord renders it). For `contentType = "code"` the adapter wraps in triple-backtick fences with the `metadata.language` tag.
 
+### Discord service ingress security
+
+The Discord adapter is an authenticated gateway service, not an anonymous Socket.IO client. It presents `DISCORD_SERVICE_TOKEN` during its `/chat` connection and signs each inbound envelope using HMAC-SHA-256. The envelope contains the Discord native message ID and a generated correlation ID. Gateway verifies the service credential, signature, and configured guild/channel/user allowlists before agent dispatch, then rejects duplicate native message IDs inside its bounded replay window. All three allowlists are default-deny and required when the Discord plugin is enabled. The service credential is injected at runtime and is never logged or included in protocol payloads.
+
 ---
 
 ### Telegram

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

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

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

@@ -0,0 +1,86 @@
+# Fleet Configuration Management — Documentation IA Acceptance Checklist
+
+**Issue:** #758 · **Scope:** M0 documentation gate for the local fleet declarative-configuration program.
+
+This checklist is an acceptance contract for documentation and examples. It does not authorize
+schema, runtime, systemd, role, profile, or live-fleet changes. An item is complete only when its
+named artifact exists, is linked from the fleet documentation entry point, and its evidence is
+recorded in the M0 task/PR.
+
+## M0 baseline acceptance
+
+- [ ] `docs/PRD.md` states the roster as desired-state SSOT; generated environment, systemd,
+      tmux, and heartbeat artifacts as non-authoritative projections; and fail-closed handling of
+      unsupported or quarantined legacy input.
+- [ ] `docs/PRD.md` defines the required classes and authority boundary: `validator` certifies but
+      does not merge; `merge-gate` remains sole approve-to-land/merge authority; `team-leader`
+      capacity is lease-bounded; `interaction` is request/status only; instance names such as Tess
+      and Ultron remain configurable.
+- [ ] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and
+      observed state, including stopped-state preservation through migration, apply, and reboot.
+- [ ] `docs/PRD.md` defines the generated-env/local-override boundary, explicitly denies arbitrary
+      command overrides in M1–M5, and requires key-name/hash-only quarantine diagnostics.
+- [ ] `docs/PRD.md` identifies the M1–M5 local-tmux scope and excludes remote reconciliation,
+      connector mutation, secret references, arbitrary commands/channels, gateway convergence, and
+      UI configuration storage.
+- [ ] `docs/TASKS.md` contains the complete M0–M5 one-card/one-PR dependency DAG for #758 with
+      agent tier, branch, dependency, estimate, and evidence expectations.
+- [ ] `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` classifies every current shipped
+      fleet example, profile, and service preset before M1 implementation starts.
+
+## Required documentation IA for M1–M5
+
+| Path                                                    | Minimum content                                                              | Delivery gate |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------- |
+| `docs/fleet/README.md`                                  | Fleet configuration entry point, desired-vs-observed decision tree, link map | M5            |
+| `docs/fleet/concepts/desired-vs-observed-state.md`      | SSOT/projection model, drift, generation and ownership                       | M5            |
+| `docs/fleet/concepts/identity-class-runtime.md`         | Stable name, display alias, class, runtime/provider/model separation         | M5            |
+| `docs/fleet/concepts/role-authority-and-leases.md`      | Required roles, validator/merge-gate separation, lease limits                | M5            |
+| `docs/fleet/concepts/generated-env-launch-chain.md`     | Generated/local files, precedence, quarantine and non-shell parsing          | M5            |
+| `docs/fleet/reference/roster-v2.schema.json`            | Executable v2 structural contract                                            | M1            |
+| `docs/fleet/reference/roster-v2-fields.md`              | Every field, default, constraint, compatibility behavior and examples        | M1            |
+| `docs/fleet/reference/cli.md`                           | `config`, `agent`, lifecycle, plan/apply, JSON and exit-code contracts       | M2–M3         |
+| `docs/fleet/reference/role-classes.md`                  | Canonical classes, aliases, authority matrix and instance-name rule          | M1            |
+| `docs/fleet/reference/lifecycle-transitions.md`         | Create/start/stop/restart/apply/reboot/rollback transition table             | M3            |
+| `docs/fleet/reference/status-and-drift.md`              | Desired/observed/managed state, orphans, revision mismatch, doctor output    | M3            |
+| `docs/fleet/how-to/create-update-delete-agent.md`       | Safe CRUD, expected generation, dry-run and rollback                         | M2            |
+| `docs/fleet/how-to/start-stop-restart.md`               | Persisted versus one-shot lifecycle actions                                  | M3            |
+| `docs/fleet/how-to/configure-tess-interaction.md`       | Configurable interaction instance; no hardcoded identity                     | M5            |
+| `docs/fleet/how-to/configure-ultron-validator.md`       | Configurable validator instance; no merge authority                          | M5            |
+| `docs/fleet/how-to/customize-roles.md`                  | Existing baseline + `roles.local` resolution and validation                  | M1            |
+| `docs/fleet/operations/reconcile-and-recover.md`        | Plan/apply failure recovery, generation lock and canary rollout              | M3            |
+| `docs/fleet/operations/env-quarantine.md`               | Legacy-key inventory, private quarantine and redaction behavior              | M2            |
+| `docs/fleet/operations/systemd-tmux-troubleshooting.md` | Socket ambiguity, ownership proof, systemd/tmux drift                        | M3            |
+| `docs/fleet/operations/backup-restore.md`               | Roster/projection backup and rollback boundaries                             | M4            |
+| `docs/fleet/operations/upgrade-assets.md`               | Source-vs-installed asset revision detection and safe refresh                | M5            |
+| `docs/fleet/migration/v1-to-v2.md`                      | Normative field map, observed-state preservation and rollback                | M4            |
+| `docs/fleet/migration/example-profile-disposition.md`   | Final disposition of every shipped example/profile                           | M1–M4         |
+| `docs/fleet/migration/legacy-class-aliases.md`          | Alias, unresolved-class, and retirement rules                                | M1            |
+
+## PRD acceptance-criteria mapping
+
+| PRD acceptance criterion                                     | Owning card(s)                     | Required evidence                                                                       |
+| ------------------------------------------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------- |
+| `AC-FCM-01` schema, semantic validation, canonical rendering | FCM-M1-001, FCM-M1-002             | YAML/JSON positive/negative and schema/parser/resolver parity tests                     |
+| `AC-FCM-02` deterministic plan and no-mutation check         | FCM-M3-001                         | Stable JSON/exit-code and desired-versus-observed fixture tests                         |
+| `AC-FCM-03` safe generation-guarded CRUD                     | FCM-M2-002                         | Create/update/delete idempotency, expected-generation, dry-run, and recovery tests      |
+| `AC-FCM-04` generated/local boundary and quarantine          | FCM-M2-001                         | Launch-chain, shadow, injection, redaction, and forbidden-key tests                     |
+| `AC-FCM-05` lifecycle/reconcile/socket/drift safety          | FCM-M3-001, FCM-M3-002             | Isolated systemd/tmux, stopped-state, orphan, socket, and rollback evidence             |
+| `AC-FCM-06` v1 migration and example/profile disposition     | FCM-M4-001, FCM-M4-002, FCM-M1-003 | Preview/canary/rollback fixture plus executable disposition inventory                   |
+| `AC-FCM-07` authority and lease boundaries                   | FCM-M1-002                         | Role/authority/lease denial tests and resolved role contracts                           |
+| `AC-FCM-08` documentation and final release gate             | FCM-M5-001, FCM-M5-002             | Checklist closure, link/example validation, reviews, certificate, and terminal-green CI |
+
+## Cross-cutting evidence gates
+
+- [ ] Every retained or migrated YAML/JSON example, profile, and service preset validates through the
+      same executable schema and shared baseline-plus-`roles.local` resolver used by the CLI.
+- [ ] Every retired example/profile/service preset has a replacement link and deprecation note; no
+      unresolved legacy class or tool-policy alias remains silently shipped.
+- [ ] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded
+      Tess/Ultron identity.
+- [ ] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed
+      `mosaic agent` catalog.
+- [ ] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of
+      legacy sensitive keys are never printed.
+- [ ] M5 release review verifies links, schema/example validation, and that all checklist rows have
+      owner/evidence or an explicit approved deferral.

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

@@ -0,0 +1,56 @@
+# Fleet Configuration Management — Legacy Example, Profile, and Service Disposition Inventory
+
+**Issue:** #758 · **Baseline:** `origin/main` `49e8a541` · **Status:** M0 inventory; no source
+examples or profiles are changed by this document.
+
+The v2 compiler may not silently accept an unresolved class. Before M1 exits, every shipped file
+below must be either migrated and executable, retained as an explicitly versioned v1 fixture, or
+retired with a replacement/deprecation note. Class resolution must use the existing
+profile/persona/provision baseline-plus-`roles.local` resolver; this inventory does not create a
+parallel resolver.
+
+## Examples
+
+| Shipped file                                         | Current class evidence                                              | M0 disposition decision                                                                              | Required M1/M4 evidence                                              |
+| ---------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `framework/fleet/examples/coding.yaml`               | `orchestrator`, `enhancer`, `implementer`, `reviewer`               | Migrate: `implementer → code`, `reviewer → review`; retain orchestration/enhancer intent             | v2 fixture validates; role aliases and authority matrix tested       |
+| `framework/fleet/examples/general.yaml`              | `orchestrator`, `enhancer`, `worker`                                | Migrate only after operator chooses a concrete canonical role for `worker`; no implicit conversion   | Explicit replacement class, or versioned v1 fixture/retirement note  |
+| `framework/fleet/examples/hybrid.yaml`               | `orchestrator`, `enhancer`, `implementer`, `researcher`, `reviewer` | Migrate aliases; resolve `researcher` through existing role resolver or retain/version               | Shared resolver validation; no ad-hoc class scanner                  |
+| `framework/fleet/examples/local-canary.yaml`         | `orchestrator`, `implementer`, `reviewer`                           | Migrate aliases; preserve its local-tmux canary purpose                                              | v2 fixture validates and preserves safe stopped/running behavior     |
+| `framework/fleet/examples/minimal.yaml`              | `canary`                                                            | Retire or version as v1 unless an existing canonical role contract is selected deliberately          | Replacement link/deprecation note or CI-valid v1 fixture             |
+| `framework/fleet/examples/operator-interaction.yaml` | `operator-interaction`                                              | Migrate alias to `interaction`; preserve instance/display name as configuration, not schema identity | v2 interaction fixture validates; no Tess literal is required        |
+| `framework/fleet/examples/research.yaml`             | `orchestrator`, `enhancer`, `researcher`, `analyst`                 | Resolve `researcher`/`analyst` through baseline + `roles.local`, or version/retire                   | Resolver evidence and explicit disposition for each unresolved class |
+
+## Profiles
+
+| Shipped file                                       | Current class evidence                                                                                                                                                                     | M0 disposition decision                                                                                                                                | Required M1/M4 evidence                                                               |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `framework/fleet/profiles/business.yaml`           | `ceo`, `coo`, `cfo`, `product-manager`, `marketing-lead`, `sales-lead`, `operations-manager`, `customer-success-manager`, `code`, `review`                                                 | Retain only if every class resolves through the existing role library/`roles.local`; otherwise version/retire rather than weakening validation         | Shared resolver CI result for every class; documented role source or replacement      |
+| `framework/fleet/profiles/marketing.yaml`          | `marketing-lead`, `content-strategist`, `copywriter`, `seo-specialist`, `social-media-manager`, `brand-strategist`, `growth-marketer`, `ux-designer`                                       | Same resolver-or-version/retire rule                                                                                                                   | Per-class resolver CI result and replacement/deprecation record if unresolved         |
+| `framework/fleet/profiles/personal-assistant.yaml` | `personal-assistant`, `executive-assistant`, `scheduler`, `inbox-manager`, `researcher`                                                                                                    | Same resolver-or-version/retire rule                                                                                                                   | Per-class resolver CI result; do not infer `interaction` equivalence                  |
+| `framework/fleet/profiles/research.yaml`           | `lead-researcher`, `researcher`, `data-analyst`, `data-scientist`, `market-analyst`, `documentation`, `review`                                                                             | Same resolver-or-version/retire rule                                                                                                                   | Per-class resolver CI result and explicit compatibility posture                       |
+| `framework/fleet/profiles/software-delivery.yaml`  | `orchestrator`, `board`, `planner`, `decomposition`, `code`, `review`, `security-review`, `site-tester`, `documentation`, `merge-gate`, `rebase`, `operator`, `session-review`, `enhancer` | Retain as the governance reference; add `validator`, `team-leader`, and `interaction` only through approved role/profile work, not silent substitution | CI validates all current classes; separate fixture proves required M1 authority seats |
+
+## Service presets
+
+| Shipped file                                         | Current policy evidence                                                                                                                                               | M0 disposition decision                                                                                                                                                                                                              | Required M1/M4 evidence                                                                                                                                                               |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `framework/fleet/services/operator-interaction.yaml` | Generic policy only: `runtime: pi`, `model: openai/gpt-5.6-sol`, `reasoning: high`, `tool_policy: operator-interaction`; provisioning supplies the agent name as data | Retain as a generic service policy, not a Tess identity. Migrate `tool_policy: operator-interaction` only through the approved interaction tool-policy alias/semantic resolver; do not infer a class or machine name from this file. | Service-policy fixture validates runtime/model/reasoning and alias behavior; generic provisioning proves a configured interaction instance is supplied without a hardcoded Tess name. |
+
+## Required disposition controls
+
+1. **No silent aliasing:** only `implementer → code`, `reviewer → review`, and
+   `operator-interaction → interaction` are approved deterministic aliases in this M0 baseline.
+   `worker`, `analyst`, `canary`, and domain-specific classes require resolver evidence or an
+   explicit version/retirement decision.
+2. **No identity hardcoding:** Tess and Ultron are optional instance/display names. An example/profile
+   may demonstrate the capability but must not make a product name a required class or machine ID.
+3. **No lifecycle inference from an example:** examples describe desired configuration only; migration
+   of an installed v1 roster separately preserves observed stopped/running state.
+4. **No secret or command migration:** examples/profiles must not introduce credential values or
+   `MOSAIC_AGENT_COMMAND`; those legacy keys are M2 quarantine inputs, never v2 authoring fields.
+5. **Service presets are included:** service policies are inventoried alongside examples/profiles.
+   They may express launch/tool policy, but do not create a class, a canonical agent identity, or a
+   second validation path.
+6. **Evidence is executable:** M1/M4 CI must enumerate these exact files, validate retained/migrated
+   inputs through the shared resolver, and fail if a file lacks its documented disposition.

docs/fleet/reference/roster-v2-fields.md

@@ -0,0 +1,95 @@
+# Fleet Roster v2 Structural Contract
+
+**Status:** FCM-M1-001 local-tmux structural compiler contract. This document describes parsing,
+strict structural validation, normalized in-memory representation, and deterministic rendering only.
+It does not authorize role resolution, lifecycle reconciliation, mutation, migration, remote
+placement, connector configuration, secret references, arbitrary commands, channels, gateway
+mapping, or any live-fleet change.
+
+The executable schema is [`roster-v2.schema.json`](./roster-v2.schema.json). The compiler exports
+the same schema and its test parses this file and compares it structurally with the executable contract.
+
+## Format and canonical shape
+
+The compiler accepts YAML or JSON. It reads only snake_case source fields and renders canonical,
+snake_case YAML. Rendering sorts runtime keys and agents by stable name. Agent names, class names,
+and tool-policy names are structural identifiers; whether a class or policy resolves is a later
+shared-resolver concern.
+
+```yaml
+version: 2
+generation: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~/src
+  runtime: pi
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: coder0
+    alias: Coder 0
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: high
+    tool_policy: code
+    working_directory: ~/src
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+```
+
+## Root fields
+
+| Field        | Required | Constraint            | Meaning                                                                                                                               |
+| ------------ | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`    | yes      | integer constant `2`  | Identifies this contract. Version `1` is explicitly rejected by this compiler and remains on the existing v1 path until M4 migration. |
+| `generation` | yes      | positive safe integer | Desired-state generation. M2 uses it for mutation guards; M1 does not mutate it.                                                      |
+| `transport`  | yes      | constant `tmux`       | M1–M5 support local tmux only.                                                                                                        |
+| `tmux`       | yes      | strict object         | Explicit local socket and holder-session configuration.                                                                               |
+| `defaults`   | yes      | strict object         | Default work directory and one supported local runtime.                                                                               |
+| `runtimes`   | yes      | non-empty object      | Declared local runtime reset policy map.                                                                                              |
+| `agents`     | yes      | non-empty array       | Local fleet entries. Duplicate stable names are rejected.                                                                             |
+
+## Nested fields
+
+| Path                                                 | Required | Constraint                                                                                           |
+| ---------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `tmux.socket_name`                                   | yes      | non-empty `[A-Za-z0-9_.-]+`; an explicit named socket prevents default-versus-named socket ambiguity |
+| `tmux.holder_session`                                | yes      | non-empty `[A-Za-z0-9_.-]+`                                                                          |
+| `defaults.working_directory`                         | yes      | non-empty string                                                                                     |
+| `defaults.runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                            |
+| `runtimes.<runtime>.reset_command`                   | yes      | non-empty string; runtime key must be a supported local runtime                                      |
+| `agents[].name`                                      | yes      | unique `[A-Za-z0-9][A-Za-z0-9_.-]*` stable machine identity                                          |
+| `agents[].alias`                                     | yes      | non-empty display string                                                                             |
+| `agents[].class`                                     | yes      | `[a-z][a-z0-9-]*`; structural only in M1, semantic role resolution is FCM-M1-002                     |
+| `agents[].runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                            |
+| `agents[].provider`, `model`, `working_directory`    | yes      | non-empty strings; provider/model capability resolution is a later card                              |
+| `agents[].reasoning`                                 | yes      | `low`, `medium`, or `high`                                                                           |
+| `agents[].tool_policy`                               | yes      | `[a-z][a-z0-9-]*`; structural only in M1                                                             |
+| `agents[].persistent_persona`, `reset_between_tasks` | yes      | booleans                                                                                             |
+| `agents[].lifecycle.enabled`                         | yes      | boolean; stored now, reconciled in FCM-M3-001                                                        |
+| `agents[].lifecycle.desired_state`                   | yes      | `running` or `stopped`                                                                               |
+| `agents[].launch.yolo`                               | yes      | boolean; structured data only, not an arbitrary command escape hatch                                 |
+
+## Fail-closed boundary
+
+Every object is `additionalProperties: false`. The compiler rejects unknown, missing, malformed,
+and wrong-type fields before producing a model. It specifically rejects remote/SSH/host/socket
+per-agent fields, connector blocks, secret references, channel fields, arbitrary command fields,
+and gateway fields because they are unsupported in the local-tmux M1 contract. It does not silently
+ignore v1 camelCase input, version `1`, or a source that does not parse to an object.
+
+The v2 compiler is intentionally isolated from the existing v1 loader. Existing v1 rosters and
+current examples/profiles continue on their current path; FCM-M4 owns explicit inventory, preview,
+migration, and rollback. FCM-M2 owns generated-file/local-override quarantine, and FCM-M3 owns
+runtime lifecycle and reconciliation.

docs/fleet/reference/roster-v2.schema.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mosaicstack.dev/schemas/fleet/roster-v2.schema.json",
+  "title": "Mosaic local tmux fleet roster v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generation", "transport", "tmux", "defaults", "runtimes", "agents"],
+  "properties": {
+    "version": {
+      "const": 2
+    },
+    "generation": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "transport": {
+      "const": "tmux"
+    },
+    "tmux": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["socket_name", "holder_session"],
+      "properties": {
+        "socket_name": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.-]+$"
+        },
+        "holder_session": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.-]+$"
+        }
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["working_directory", "runtime"],
+      "properties": {
+        "working_directory": {
+          "type": "string",
+          "minLength": 1
+        },
+        "runtime": {
+          "enum": ["claude", "codex", "opencode", "pi"]
+        }
+      }
+    },
+    "runtimes": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "enum": ["claude", "codex", "opencode", "pi"]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reset_command"],
+        "properties": {
+          "reset_command": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "agents": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "alias",
+          "class",
+          "runtime",
+          "provider",
+          "model",
+          "reasoning",
+          "tool_policy",
+          "working_directory",
+          "persistent_persona",
+          "reset_between_tasks",
+          "lifecycle",
+          "launch"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$"
+          },
+          "alias": {
+            "type": "string",
+            "minLength": 1
+          },
+          "class": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "runtime": {
+            "enum": ["claude", "codex", "opencode", "pi"]
+          },
+          "provider": {
+            "type": "string",
+            "minLength": 1
+          },
+          "model": {
+            "type": "string",
+            "minLength": 1
+          },
+          "reasoning": {
+            "enum": ["low", "medium", "high"]
+          },
+          "tool_policy": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "working_directory": {
+            "type": "string",
+            "minLength": 1
+          },
+          "persistent_persona": {
+            "type": "boolean"
+          },
+          "reset_between_tasks": {
+            "type": "boolean"
+          },
+          "lifecycle": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["enabled", "desired_state"],
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "desired_state": {
+                "enum": ["running", "stopped"]
+              }
+            }
+          },
+          "launch": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["yolo"],
+            "properties": {
+              "yolo": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

docs/guides/admin-guide.md

@@ -293,13 +293,28 @@ Each OIDC provider requires its client ID, client secret, and issuer URL togethe
 
 ### Plugins
 
-| Variable               | Description                                                                |
-| ---------------------- | -------------------------------------------------------------------------- |
-| `DISCORD_BOT_TOKEN`    | Discord bot token (enables Discord plugin)                                 |
-| `DISCORD_GUILD_ID`     | Discord guild/server ID                                                    |
-| `DISCORD_GATEWAY_URL`  | Gateway URL for Discord plugin to call (default: `http://localhost:14242`) |
-| `TELEGRAM_BOT_TOKEN`   | Telegram bot token (enables Telegram plugin)                               |
-| `TELEGRAM_GATEWAY_URL` | Gateway URL for Telegram plugin to call                                    |
+| Variable                      | Description                                                                                                                               |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `DISCORD_BOT_TOKEN`           | Discord bot token (enables Discord plugin)                                                                                                |
+| `DISCORD_SERVICE_TOKEN`       | Required high-entropy service credential used to authenticate and sign Discord ingress; inject through the approved secret mechanism only |
+| `DISCORD_SERVICE_USER_ID`     | Required Mosaic service-principal user ID that owns persisted Discord conversations; the original Discord user ID remains audit metadata  |
+| `DISCORD_GUILD_ID`            | Discord guild/server ID                                                                                                                   |
+| `DISCORD_GATEWAY_URL`         | Gateway URL for Discord plugin to call (default: `http://localhost:14242`)                                                                |
+| `DISCORD_ALLOWED_GUILD_IDS`   | Required comma-separated Discord guild snowflake allowlist; default-deny                                                                  |
+| `DISCORD_ALLOWED_CHANNEL_IDS` | Required comma-separated Discord channel snowflake allowlist; default-deny                                                                |
+| `DISCORD_ALLOWED_USER_IDS`    | Required comma-separated Discord user snowflake allowlist; default-deny                                                                   |
+| `TELEGRAM_BOT_TOKEN`          | Telegram bot token (enables Telegram plugin)                                                                                              |
+| `TELEGRAM_GATEWAY_URL`        | Gateway URL for Telegram plugin to call                                                                                                   |
+
+### Discord ingress security
+
+When `DISCORD_BOT_TOKEN` is configured, `DISCORD_SERVICE_TOKEN`, `DISCORD_SERVICE_USER_ID`, and all three Discord allowlists are required. Gateway startup fails rather than enabling a broad or unauthenticated remote-control surface. The service user ID identifies a provisioned Mosaic service principal for persistence; the original Discord user ID is retained in ingress audit metadata. The service token is a secret supplied by the approved runtime secret mechanism and is never committed or logged.
+
+Inbound Discord messages must originate from an allowed guild, channel, and user, mention the bot, and carry a signed envelope containing the native Discord message ID and a generated correlation ID. The gateway validates the service identity, envelope signature, and allowlists again before dispatching. Replayed Discord message IDs are rejected during the bounded ingress replay window. Durable inbox/idempotency retention is introduced with Tess durable state.
+
+### Session retention and garbage collection
+
+Session cleanup is scoped to one session identifier and only removes that session's Valkey keys and demotes that session's hot logs. Gateway startup and scheduled jobs do not perform global session cleanup; startup removes legacy repeatable `session-gc` schedules created by older deployments. The `/gc` command is intentionally disabled until a distinct global-retention job supplies explicit authorization and audit evidence. This prevents one tenant or session's cleanup from changing another's retained data.
 
 ### Observability
 

docs/guides/dev-guide.md

@@ -211,17 +211,6 @@ pnpm format:check && pnpm typecheck && pnpm lint
 
 A pre-push hook enforces this mechanically.
 
-### CI Publish Channels
-
-Woodpecker `.woodpecker/publish.yml` keeps stable and integration-line artifacts separate:
-
-| Source                            | npm packages                                                                                                  | Gateway image                                                                            |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `main` push/manual or release tag | committed package versions published to Gitea npm without changing the dist-tag workflow                      | `gateway:sha-<short>` plus `gateway:latest` on `main`, and the release tag on tag events |
-| `next` push/manual                | CI-computed prereleases, `<target-stable>-next.<CI_PIPELINE_NUMBER>`, published with `npm publish --tag next` | `gateway:sha-<short>` only                                                               |
-
-`next` never publishes npm `latest` or Docker `latest`. The next npm publish step verifies that `@mosaicstack/mosaic@next` resolves to the computed prerelease before the pipeline can pass.
-
 ---
 
 ## Adding New Agent Tools

docs/guides/user-guide.md

@@ -175,18 +175,8 @@ Or use the direct URL:
 bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
 ```
 
-The installer places the `mosaic` binary at `~/.npm-global/bin/mosaic`.
-
-Install lanes:
-
-| Lane                     | Command                               | Source                                                                                       |
-| ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Stable                   | `bash tools/install.sh`               | npm `@mosaicstack/mosaic@latest` + `main`                                                    |
-| Prerelease integration   | `bash tools/install.sh --next`        | Fast npm `@mosaicstack/mosaic@next` + `@mosaicstack/gateway@next`; source fallback at `next` |
-| Contributor/source build | `bash tools/install.sh --dev --ref X` | Build-from-source at the requested ref                                                       |
-
-`--next` is fast-by-default from the Gitea npm `next` dist-tag and falls back to a source build at the permanent `next` branch if the dist-tag is missing or unreachable. Explicit `--ref` or `MOSAIC_REF` still wins and uses the source path.
-Flags for non-interactive use:
+The installer places the `mosaic` binary at `~/.npm-global/bin/mosaic`. Flags for
+non-interactive use:
 
 ```bash
 --yes               # Accept all defaults

docs/native-kanban-sot/DOCUMENTATION-CHECKLIST.md

@@ -0,0 +1,36 @@
+# Documentation Completion Checklist — Native Kanban/SOT Canon
+
+**Tracking:** Mosaic Stack issue #751
+**Scope:** Requirements and contract publication only; runtime implementation follows in separate slices.
+
+## Required artifacts
+
+- [x] Project `docs/PRD.md` exists; the workstream requirements refine its task/project-management scope.
+- [x] Canonical workstream requirements published at `docs/requirements/native-kanban-sot.md`.
+- [x] Mission manifest, task decomposition, frozen shared contract, and typed contract declarations included.
+- [x] `docs/SITEMAP.md` updated.
+- [x] Independent initial review and final GO report stored under `docs/reports/native-kanban-sot/`.
+- [x] Task scratchpad stored under `docs/scratchpads/`.
+- [ ] User/Admin/Developer guides — N/A for canon-only publication; required in implementation slices that change behavior or operations.
+- [ ] OpenAPI and endpoint index — N/A until KBN-105 freezes implementation-ready endpoint contracts.
+
+## Structural and root hygiene
+
+- [x] Canonical requirements are under `docs/requirements/`.
+- [x] Workstream artifacts are under `docs/native-kanban-sot/`.
+- [x] Review reports are under `docs/reports/native-kanban-sot/`.
+- [x] No new unscoped document was added to the `docs/` root.
+- [x] Root mission/task rollups link to the workstream.
+
+## Review gate
+
+- [x] Author and independent reviewer are different agents.
+- [x] KCR-001–016 closure was independently verified.
+- [x] Ultron final gate returned GO with zero BLOCKER/HIGH findings.
+- [x] Formatter, lint, typecheck, strict contract TypeScript, link, scope, and invariant publication validation passed in the current Stack toolchain.
+- [ ] PR review, CI, squash merge, and issue closure remain required before publication completion.
+
+## Publishing
+
+- [x] Canonical source remains in-repository.
+- [x] No external publishing platform is required for this internal architecture contract.

docs/native-kanban-sot/INDEX.md

@@ -0,0 +1,64 @@
+# Native Kanban/SOT Canon
+
+**Status:** KCR-001–016 independently cleared; canonical publication is in progress under issue [#751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
+**Date:** 2026-07-14
+**Implementation hold:** no feature implementation starts until this canon is squash-merged to `main` with terminal-green CI; after merge, every slice remains held until its KBN prerequisite graph is satisfied.
+
+## Artifacts
+
+| Artifact                                                                                 | Purpose                                                                                                                                                                                               |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Canonical requirements](../requirements/native-kanban-sot.md)                           | Canonical P0–P3 requirements, all seven ratified decisions, fixed invariants, thin MVP, recovery tiers, non-goals, and per-requirement acceptance criteria                                            |
+| [`MISSION-MANIFEST.md`](./MISSION-MANIFEST.md)                                           | Mission/authority boundaries, exact role chain, gate model, mandatory SecReview triggers, Certifier final/no-merge rule, and collision-free slice ownership                                           |
+| [`TASKS.md`](./TASKS.md)                                                                 | Dependency-ordered, bounded P0–P3 slices with IN/OUT scope, dependencies, shared contracts, file ownership, evidence, and USC coder2/3/4/5 parallelization                                            |
+| [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)                                             | Remediated v1 integration contract: proof authority, exact failures/routes/DTOs/MCP ownership, concrete current-main field migration map, relational invariants, Coordinator split, recovery delivery |
+| [`contracts/kanban-schema.v1.ts`](./contracts/kanban-schema.v1.ts)                       | Drizzle target declarations including exact owner/principal membership, project congruence, tags/archive, proposals, persisted assignments, monotonic fences, durable retry, immutable evidence/audit |
+| [`contracts/mechanical-coordinator.v1.ts`](./contracts/mechanical-coordinator.v1.ts)     | Pure snapshot decision engine separated from persistence/service adapter; ID-bound approvals, bigint-safe fences, durable retry/quarantine, artifact-backed checkpoints, exact failures               |
+| [`contracts/health-state.v1.ts`](./contracts/health-state.v1.ts)                         | Discriminated public health, separate branded transaction-local write proof, and non-overlapping denial/transport/version-conflict mappings                                                           |
+| [`contracts/recovery-posture.v1.ts`](./contracts/recovery-posture.v1.ts)                 | Provider-neutral shape schema plus normative runtime refinement, cross-field constraints, and Lite/Standard/High-assurance defaults                                                                   |
+| [`tsconfig.json`](./tsconfig.json)                                                       | Strict no-emit project scope for linting and compiling the four frozen TypeScript contracts against the current Stack Drizzle declarations                                                            |
+| [`DOCUMENTATION-CHECKLIST.md`](./DOCUMENTATION-CHECKLIST.md)                             | Publication documentation gate and implementation-slice deferrals                                                                                                                                     |
+| [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 matrix, reproducible validation evidence, and GO verdict                                                                                                                                      |
+| [Ultron final gate](../reports/native-kanban-sot/ultron-final-go.md)                     | Final requirements, authority, schema, migration, recovery, decomposition, and evidence review GO                                                                                                     |
+
+## Recommended USC lane partition
+
+| Lane       | Natural seam                         | Exclusive ownership                                                                                                                                     |
+| ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **coder2** | Schema + migrations + recovery slice | Unified Drizzle schema, migration SQL/meta/journal/tests, then recovery parser/mechanism/runbook files                                                  |
+| **coder3** | Domain + Gateway + MCP server        | Workspace-safe repositories, DTOs/controllers/services, exact `apps/gateway/src/mcp/**` files, health proof, proposals, Coordinator persistence adapter |
+| **coder4** | Pure Coordinator + tooling           | `packages/coord` mechanical engine, CLI/MCP consumers, generated projection, one-way importer and cutover tooling; lane-serialized internally           |
+| **coder5** | Web                                  | Tasks/Projects Kanban/List/detail and later Coordinator/migration-review UI                                                                             |
+| **Mos**    | Serialized integration               | Canon publication, frozen-contract changes, shared-root/exports, integration gates, merge authority                                                     |
+
+The safe order is KBN-010 → KBN-100 → KBN-105, then coder3 Gateway/MCP server, coder4 CLI/projection, coder5 web, and coder2 recovery can proceed on disjoint files. coder4 then runs pure Coordinator → importer → cutover tooling serially. No two active slices edit the same files.
+
+## Recovery defaults
+
+| Tier           | RPO / RTO    | WAL / PITR          | Base backup | Restore / break-glass   | Off-cluster                                     |
+| -------------- | ------------ | ------------------- | ----------- | ----------------------- | ----------------------------------------------- |
+| Lite           | 24h / 24h    | disabled / disabled | daily       | quarterly / annual      | encrypted separate target                       |
+| Standard       | 1h / 8h      | q15m / 14d          | daily       | quarterly / semiannual  | encrypted separate object storage               |
+| High-assurance | **15m / 4h** | **q5m / 35d**       | **daily**   | **monthly / quarterly** | **encrypted base+WAL, separate failure domain** |
+
+These knobs affect recovery posture only. PostgreSQL remains the sole writable SOT in every tier. Fail-closed writes, generated-file non-authority, attributable post-recovery proposals, non-LLM Coordinator limits, and Certifier final-gate/no-merge authority are fixed for every tier.
+
+## Non-blocking implementation sub-decisions for Mos
+
+The source plan and ratified seven decisions resolve all build-blocking product choices. The following implementation-local selections remain for the owning slices/Mos and must not weaken v1:
+
+1. Exact PostgreSQL write-health probe SQL and bounded proof lifetime; authority and failures are frozen.
+2. Dependency-cycle serialization mechanism (recursive CTE plus transaction/advisory lock or equivalent); required behavior is frozen.
+3. Whether RLS lands in the first migration or immediately after the tested session-context pattern; workspace constraints/repository authorization are required from migration one.
+4. Concrete off-cluster backup provider/bucket and selected production recovery tier; High-assurance minima are frozen if selected.
+5. Cutover reconciliation thresholds and stabilization duration, to be owner-approved before P3 execution.
+
+None authorizes a second writer, dual sync, LLM scheduling, Coordinator gate waiver/merge, or Certifier merge authority.
+
+## Publication validation evidence
+
+- Concrete TypeScript contracts are formatted with repository Prettier.
+- All four contracts pass strict TypeScript no-emit checking against the current Stack Drizzle toolchain.
+- Contract remediation and KCR-001–016 traceability are recorded in the issue scratchpad and linked review reports.
+- Independent re-review returned GO with KCR-001–016 closed; implementation remains held until canon merge and the dependency-ordered KBN prerequisites complete.

docs/native-kanban-sot/MISSION-MANIFEST.md

@@ -0,0 +1,195 @@
+# Mission Manifest — Mosaic Native Kanban and Canonical Task SOT P0–P3
+
+**Mission status:** CANON INDEPENDENTLY APPROVED; publication in progress under issue [#751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
+**Date:** 2026-07-14
+**Human decision owner:** Jason
+**Orchestrator/publication owner:** web1 control plane (`mos-claude`; `mosaic-100` acting during Claude quota outage)
+**Execution topology:** USC web1, partitioned across collision-free GPT coder2/3/4/5 lanes
+**Canonical requirements:** [`../requirements/native-kanban-sot.md`](../requirements/native-kanban-sot.md)
+**Frozen integration contract:** `SHARED-CONTRACT.md` and `contracts/*.v1.ts`
+
+## 1. Mission statement
+
+Extend current `mosaicstack/stack` main into the sole native control plane for workspace-scoped project, mission, milestone, task, dependency, assignment, lease, approval, evidence, and audit state. First deliver a thin writable Kanban/List vertical slice; then add deterministic mechanical coordination and execute a one-way migration/cutover from jarvis-brain/Vikunja project/task stores.
+
+Success means every user, agent, orchestrator, specialist, and UI sees and mutates the same PostgreSQL aggregate revisions through typed Gateway commands, with no writable fallback and no hidden second authority.
+
+## 2. Scope boundaries
+
+### In scope
+
+- Current Drizzle/PostgreSQL schema extension and migrations.
+- Workspace tenancy and authorization from the first migration.
+- Projects, missions, milestones, tasks, normalized tags, dependencies, assignments, durable execution/quarantine state, links, immutable artifacts/evidence joins, outage change proposals, events, approvals, leases, checkpoints, and transactional outbox.
+- NestJS Gateway queries and explicit lifecycle commands.
+- MCP/CLI agent surfaces and generated read-only projections.
+- Thin writable Next.js Tasks Kanban/List, task detail, minimal Projects CRUD, filters, dependency readiness, ownership/lease separation, and audit timeline.
+- Non-LLM Mechanical Coordinator eligibility, proposal, approval-policy, lease/fence, heartbeat, retry, expiry, quarantine, and restart recovery.
+- Planning, Enhance, Coder, Review, SecReview, PR-Monitor, and Certifier role/gate representation.
+- One-way shadow importer, reconciliation, write freeze, final delta, cutover, rollback package, and legacy read-only stabilization.
+- Recovery-posture configuration and health-state/fail-closed contract.
+
+### Out of scope
+
+- Greenfield services, Prisma runtime revival, or jarvis-brain flat files as runtime storage.
+- Writable Markdown/JSON/Valkey/browser/provider fallback.
+- Gitea issue/PR replacement or generic bidirectional provider sync.
+- Calendar, email, GLPI cache, CRM, billing, time tracking, personal-brain migration.
+- LLM scheduling or scope interpretation by the Coordinator.
+- Autonomous gate waiver, certification, merge, release, deployment, or issue closure by Coordinator.
+- Merge authority for Certifier.
+- P4 full portfolio/mission designer and P5 fleet-scale policy unless separately released.
+
+## 3. Fixed invariants
+
+Every deployment MUST preserve all of the following:
+
+1. PostgreSQL is the sole writable SOT.
+2. Drizzle on current stack main is the only persistence foundation.
+3. Mutations fail closed when DB write-health cannot be proven `healthy`.
+4. No file, Valkey, browser, queue, provider, or human note becomes a fallback writer.
+5. `TASKS.md`, `mission.json`, and every file export are generated, read-only, non-authoritative, and never import sources.
+6. Human outage notes become attributable post-recovery proposals only.
+7. Workspace is the hard tenant; Team is intra-workspace authorization.
+8. Valkey is expendable; PostgreSQL owns state, leases, fencing, audit, and outbox.
+9. Mechanical Coordinator is deterministic/non-LLM and cannot invent scope, waive gates, certify, or merge.
+10. Certifier is the final independent quality gate and has no merge authority.
+11. Mutations use idempotency and optimistic aggregate versions; worker commands also require a current fencing token.
+12. Recovery tier changes only backup/recovery posture, never authority or gate semantics.
+
+## 4. Configurable recovery posture
+
+Deployments select Lite, Standard, or High-assurance defaults from [`../requirements/native-kanban-sot.md`](../requirements/native-kanban-sot.md) and `contracts/recovery-posture.v1.ts`. Configurable fields are limited to:
+
+- backup/base-backup cadence;
+- RPO and RTO targets;
+- PITR retention;
+- WAL archive cadence;
+- restore-test frequency;
+- break-glass drill frequency;
+- encrypted off-cluster storage.
+
+High-assurance defaults are fixed reference values: RPO 15 minutes, RTO 4 hours, encrypted off-cluster WAL every 5 minutes with 35-day PITR, daily base backup, monthly restore test, and quarterly break-glass drill.
+
+## 5. Canonical role map
+
+```text
+User
+  ↓ objectives, constraints, ratified decisions
+Interaction Layer
+  ↓ workspace/project context; no scheduling authority
+Portfolio Orchestrator
+  ↓ approved mission, cross-project priority/capacity
+Project Sub-Orchestrator
+  ↓ decomposition, DAG, acceptance, release, routing policy, overrides
+Gateway
+  ↓ authenticated/authorized typed commands
+Project/Task Domain Services
+  ↓ transactional state + semantic event + outbox
+Mechanical Coordinator
+  ↓ deterministic eligibility/proposal/lease/fence/retry/quarantine
+Specialists
+  Planning → Enhance → Coder → Review → conditional SecReview → remediation
+  ↓ complete evidence bundle
+Certifier
+  ↓ final pass/reject/escalate; NO merge authority
+Project Sub-Orchestrator / control plane
+  ↓ merge authority after all gates
+Post-merge validation
+```
+
+### Authority table
+
+| Role/layer               | Owns                                                                                                        | Explicitly cannot do                               |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| User                     | Objectives, constraints, Jason-owned decisions                                                              | Direct DB/file authority bypass                    |
+| Interaction              | Conversation and context resolution                                                                         | Schedule, approve, lease, certify                  |
+| Portfolio Orchestrator   | Mission approval, cross-project priority/capacity/global holds                                              | Implement or self-certify specialist work          |
+| Project Sub-Orchestrator | Task decomposition/DAG/acceptance, release to ready, routing policy, overrides, remediation, merge go-ahead | Bypass required independent gates                  |
+| Gateway                  | Identity, tenancy, DTO validation, commands, state-machine enforcement                                      | Accept file edits or client SQL as mutations       |
+| Domain services          | Transactional business invariants, semantic events/outbox                                                   | Depend on Valkey/files for committed truth         |
+| Mechanical Coordinator   | Eligibility, dependencies, proposal, approved routing, lease/fence, heartbeat, retry/quarantine             | Invent/alter scope, waive gates, certify, merge    |
+| Specialists              | Bounded planning/implementation/review artifacts under a task lease                                         | Modify another lane's owned files or self-approve  |
+| Certifier                | Final independent evidence/traceability/gate decision                                                       | Merge, close provider issue, release, waive policy |
+
+## 6. Gate model
+
+### Mandatory gates
+
+1. Requirements/contract freeze before parallel implementation.
+2. P0 schema/authority threat model and tenant isolation review.
+3. Author and reviewer MUST be different principals/sessions.
+4. Functional review validates requirements, endpoint registry, concurrency, and negative paths.
+5. **Mandatory SecReview (`secrev`)** for any auth, authorization, tenant, service-token, secret, database schema/migration, data-integrity, import/cutover, audit, lease/fencing, recovery, or destructive-retirement surface.
+6. Review findings enter bounded remediation owned by the implementation lane.
+7. Raising reviewer re-verifies remediation.
+8. Certifier performs the final independent evidence and traceability gate.
+9. Merge authority remains with `mos-claude`/Project Sub-Orchestrator control plane after gates pass.
+10. Post-merge CI and situational validation must be terminal green before closure.
+
+### Gate outcomes
+
+- **PASS:** evidence complete; next authority may proceed.
+- **REJECT:** findings are explicit and route to remediation.
+- **ESCALATE:** policy/owner decision required; no implicit waiver.
+
+No role can transform a missing gate into a warning by changing status, editing a projection, or writing Valkey.
+
+## 7. Slice ownership rules
+
+1. USC web1 is the sole execution environment; coder2/3/4/5 are independent bounded lanes under Mos.
+2. Every slice has one named file-tree owner and an explicit IN/OUT boundary in `TASKS.md`.
+3. Two active slices MUST NOT edit the same source file, migration file, generated snapshot, lockfile, or API contract.
+4. coder2 exclusively owns `packages/db/src/schema.ts`, `packages/db/drizzle/**`, migration journal/meta/tests, then its disjoint recovery-parser/runbook slice. All schema requests serialize through coder2.
+5. Frozen `contracts/*.v1.ts` are read-only inputs during implementation. Contract changes require Mos approval, a version bump/amendment, and coordinated rebase before work resumes.
+6. coder3 exclusively owns Gateway DTO/controllers/services and the enumerated `apps/gateway/src/mcp/**` server files. coder4 owns CLI/projection clients and never edits MCP server files. Web consumers use the exact KBN-105 endpoint/DTO freeze.
+7. coder4 executes one lane order: CLI/projection → pure Coordinator → importer → cutover. The pure Coordinator under `packages/coord` does not load IDs or access DB, Gateway, Valkey, recovery I/O, or web files; coder3 owns the persistence/service adapter.
+8. Migration/import tooling calls Gateway/migration-only approved ports and does not add a second database model.
+9. Each lane commits only its owned files and reports any needed cross-slice change as a contract-change request instead of editing another lane's tree.
+10. Cross-review is mandatory: no lane reviews its own changes. Recommended ring is coder2 ← coder5, coder3 ← coder2, coder4 ← coder3, coder5 ← coder4, followed by independent SecReview where triggered and Certifier final.
+11. Integration-only edits are a separate serialized slice after component lanes are green; no opportunistic merge-conflict resolution may alter semantics.
+
+## 8. Delivery phases and exit gates
+
+### P0 — Canon and authority foundation
+
+- Publish this canon, frozen schema/ports/health/recovery contracts, threat model, authorization matrix, exact endpoint/DTO registry, concrete current-main field-by-field migration map, and standards amendment.
+- Build hold remains active until independent author≠reviewer re-review returns GO on health proof/failures, approval binding, fencing, tenant relationships, proposals, migration map, slice ordering/API freeze, recovery validation, and vocabulary alignment.
+- Exit: no unresolved second writer or contract blocker, tenant boundary frozen, all seven decisions traceable, and independent re-review GO recorded.
+
+### P1 — Thin native MVP
+
+- Schema/migration, tenant-safe Gateway, CLI/MCP/projection, writable Kanban/List/Projects, dependencies/readiness/audit.
+- Exit: same revision across web/CLI/MCP/projection; cross-workspace tests fail closed; generated files cannot mutate state.
+
+### P2 — Mechanical coordination
+
+- Agent/session registry, deterministic engine, approval queue, PostgreSQL leases/fencing/checkpoints/outbox, retry/quarantine, operations UI.
+- Exit: one lease winner, stale tokens rejected, dependencies/approvals enforced, DB/Valkey fault semantics proven, Certifier gate has no merge authority.
+
+### P3 — Shadow migration and cutover
+
+- Importer, lineage, reconciliation, reviewer UI, write freeze, final delta, Gateway switch, legacy read-only, stabilization and rollback package.
+- Exit: signed reconciliation, zero active legacy writers, scoped Gateway identities, imported backlog cannot dispatch accidentally.
+
+## 9. Evidence required for mission closure
+
+- Requirement-to-test/evidence matrix.
+- Schema/migration and N-1 rolling-deploy proof.
+- Cross-workspace API/repository/import/Coordinator negative tests.
+- Health-state and fail-closed fault injection.
+- Valkey-loss/outbox replay and Coordinator restart tests.
+- Concurrent lease and stale fencing tests.
+- Endpoint-registry alignment across web/CLI/MCP/Gateway.
+- Accessible real-Gateway Kanban journeys.
+- Generated projection tamper/no-import proof.
+- One-way migration dry-run/apply/verify and field reconciliation.
+- Author-independent functional review and required SecReview.
+- Certifier final decision and evidence bundle.
+- Merged main SHA, terminal green CI, closed linked task/issue, and post-merge situational validation under orchestrator ownership.
+
+## 10. Change control
+
+This manifest is derived from the ratified source plan. Any change to SOT authority, workspace tenancy, fixed statuses, Coordinator/Certifier authority, health-state semantics, schema v1, migration direction, or recovery-tier field set is a contract change. Contract changes require Jason/Mos authorization and cannot be inferred by an implementation lane.
+
+No coder lane may start while the build hold is active. KBN-010 must complete before KBN-100; KBN-105 exact endpoint/DTO freeze must complete before any API consumer implementation.

docs/native-kanban-sot/SHARED-CONTRACT.md

@@ -0,0 +1,219 @@
+# Native Kanban/SOT — Remediated Shared Contract v1
+
+**Status:** INDEPENDENT REVIEW GO; freezes as v1 when issue #751 canon merges to `main`
+**Version:** 1.0.0-rc.3
+**Date:** 2026-07-14
+**Change authority:** Mosaic control plane/Jason only
+
+## 1. Authority
+
+Concrete contracts are the four `contracts/*.v1.ts` files. PostgreSQL/current-main Drizzle is the sole writable SOT. Public health, Valkey, files, exports, providers, browser state, and outage notes cannot authorize/reconstruct writes. Mechanical Coordinator is non-LLM with no scope/gate/certification/merge authority. Certifier is final independent gate with no merge authority. No feature lane starts until this canon merges and the KBN-010/KBN-105 prerequisites are satisfied.
+
+## 2. Health proof and exact failures
+
+`KanbanHealthResponseV1` is a discriminated union:
+
+| State                |  read | write | Capability                                          |
+| -------------------- | ----: | ----: | --------------------------------------------------- |
+| `healthy`            |  true |  true | reads; public state still cannot authorize mutation |
+| `read-only-degraded` |  true | false | reads only                                          |
+| `write-unavailable`  | false | false | diagnostics only                                    |
+
+Every response has `checkedAt`, `validUntil`, `policyRevision`; contradictory booleans fail validation.
+
+For a mutation, Gateway opens the PostgreSQL transaction, executes the live write probe on that transaction/connection, mints the internal branded `PostgresWriteHealthProofV1`, and revalidates time/policy/transaction identity immediately before mutation. Public REST/MCP/CLI DTOs never accept health/proof fields. Valkey/caller assertions cannot mint proof. Pure Coordinator takes `KanbanEvaluationContextV1`; persistence takes `InternalKanbanMutationContextV1` or probes internally.
+
+| Case                         |                        HTTP | Frozen result                                                       | Retry                |
+| ---------------------------- | --------------------------: | ------------------------------------------------------------------- | -------------------- |
+| degraded write               |                         503 | `KANBAN_WRITE_HEALTH_UNPROVEN`, `read-only-degraded`, `not_applied` | false                |
+| write unavailable            |                         503 | `KANBAN_WRITE_UNAVAILABLE`, `write-unavailable`, `not_applied`      | false                |
+| version conflict             |                         409 | `AGGREGATE_VERSION_CONFLICT`, actual version, `not_applied`         | false                |
+| timeout/unreachable          |             timeout/502/504 | `retryable_transport_error`, `unknown`                              | same idempotency key |
+| stale fence/session/approval | coordinator rejection union | `not_applied`                                                       | false                |
+
+Required negatives: contradictory state, expired/policy-mismatched/wrong-transaction proof, Valkey-only health, forged healthy, and exhaustive non-cross-mapping of 503 vs 502/504/timeout vs 409.
+
+## 3. Canonical schema invariants
+
+Complete declaration: `contracts/kanban-schema.v1.ts`.
+
+- Tables: tenant/identity (`workspaces`, members, teams/members, agents/sessions); planning (`projects`, `milestones`, current-milestone join, `missions`, mission-milestones, `tasks`, normalized tags, dependencies); orchestration (`task_assignments`, durable execution state, leases, checkpoints/evidence); governance (`change_proposals`, immutable artifacts/evidence, events, approvals, outbox, external links).
+- Task statuses: `backlog | ready | in_progress | blocked | in_review | done | cancelled`.
+- Assignment states everywhere: `awaiting_approval | policy_pre_authorized | approved | rejected | leased | released | expired | superseded`.
+- Specialist roles everywhere: `planning | enhance | coder | review | security-review | pr-monitor | certifier`.
+- Owner uses exactly-one user/team; assignment principal exactly-one user/team/agent; users require active membership; agent/session and all evidence are workspace-bound.
+- Task→mission/milestone/parent, mission→milestone, and project→current-milestone are project-congruent composite relations.
+- Dependency identity is workspace+predecessor+successor independent of type.
+- Approval evidence and checkpoint evidence are workspace-scoped joins to immutable artifacts, never JSON ID arrays.
+- Proposal audit links are composite relations: `(workspace_id, submitted_audit_event_id)` and `(workspace_id, accepted_command_audit_event_id)` reference `task_events(workspace_id, id)` with RESTRICT deletion.
+- Assignment is persisted with task/version, exact target/session, expiry/state/policy/proposer/reason. Approval relates to assignment. Lease acquisition accepts IDs, then reloads/locks and validates every relation.
+- `tasks.fencing_counter` is bigint; locked atomic increment/RETURNING creates a decimal-string lease token. Lease/checkpoint composites bind exact workspace+task+assignment/session+fence.
+- `task_execution_states` durably records retry/quarantine/exhaustion.
+- Tags are normalized; legacy `tasks.tags` remains through N-1. Archive is explicit actor/reason/time and does not change lifecycle.
+- Canonical parents use RESTRICT. Events/checkpoints/artifacts/evidence are INSERT/SELECT-only for application roles. Normal flow archives/cancels; purge is audited break-glass retention work.
+
+## 4. Outage proposal contract
+
+`change_proposals` stores workspace, active-member proposer, source-note digest, target/version, typed command/payload, idempotency, lifecycle, decision actor/reason/time, proposal version, and submit/accepted event IDs. Both event IDs are workspace-aware composite foreign keys to `task_events(workspace_id, id)`; a bare UUID is never sufficient.
+
+Submission preallocates the proposal ID. One transaction inserts `change_proposal.submitted` with the proposal workspace, `aggregate_type='change_proposal'`, `aggregate_id=<new proposal ID>`, `previous_version=NULL`, and `new_version=1`, then inserts the proposal referencing that event. Missing, foreign-workspace, wrong-type, or unrelated-proposal events abort the transaction.
+
+Submit/list/get/accept/reject are explicit Gateway commands. Pending/rejected proposals are inert: no scheduling, dependency/gate satisfaction, or direct target mutation. Acceptance locks proposal+target, obtains fresh transaction-local proof, verifies pending/expected version, invokes the normal command handler, and atomically stores the emitted normal-command event ID. That event must share the proposal workspace, match `target_aggregate_type` and `target_aggregate_id`, use `causation_id=submitted_audit_event_id`, and carry `payload.changeProposalId=<locked proposal ID>`. Missing, foreign-workspace, unrelated-target, unrelated-proposal, or unrelated-command events abort acceptance.
+
+## 5. Concrete current-main N-1 migration delta
+
+**Inspected:** `origin/main:packages/db/src/schema.ts` at `e72388b2cbfe400842fe940fa6cabf984ed43711` (2026-07-13). It has global teams/no workspace keys, legacy project/mission/task statuses, nullable task project/mission, `tasks.assignee/tags/due_date`, mission JSON/config, duplicated `mission_tasks.status`, legacy agent fields, and separate fleet `backlog` claims.
+
+Legacy columns remain declared in unified `schema.ts` for expand + full N-1/rollback window. Generation must not infer early drops.
+
+### 5.1 Ordered phases
+
+1. **Pre-expand:** N-1 patch stops `mission_tasks.status` as write source; inventory writers; backup/checksum.
+2. **Expand:** add enums/tables and nullable-first columns; retain legacy declarations/uniques; emit no v1-only status.
+3. **Backfill:** bootstrap workspace; bounded idempotent cursor/checksum batches; quarantine ambiguous rows.
+4. **Validate:** no null tenant, cross-project link, ambiguous owner; status/tag/date/config retention; then constraints/NOT NULL.
+5. **Compatibility:** N-1 reads legacy; same-DB transaction mirrors only unavoidable fields; never file/Valkey dual write.
+6. **Switch:** stop N-1 writers; Gateway sole command boundary; enable canonical statuses.
+7. **Contract release:** later release after rollback/N-1; remove compatibility/global uniques/legacy fields.
+
+### 5.2 New audit/proposal DDL order
+
+KBN-100 migration DDL must execute in this order:
+
+1. create `task_events` and its unique `(workspace_id, id)` key;
+2. create `change_proposals` with nullable acceptance-event ID and required submission-event ID;
+3. add `change_proposals_workspace_submitted_event_fk` from `(workspace_id, submitted_audit_event_id)` to `task_events(workspace_id, id)` with `ON DELETE RESTRICT`;
+4. add `change_proposals_workspace_accepted_command_event_fk` from `(workspace_id, accepted_command_audit_event_id)` to the same composite key with `ON DELETE RESTRICT`;
+5. install application-role immutability privileges and same-transaction semantic validation before enabling proposal commands.
+
+The submission transaction inserts the event first using a preallocated proposal UUID, then the proposal. Acceptance inserts the normal command event before updating the locked proposal. Neither FK is omitted or replaced by a bare UUID/index check.
+
+### 5.3 Field map
+
+| Current                                        | Expand/backfill                                                                        | N-1 compatibility                               | Switch/contract                                               |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- |
+| global `teams`, `team_members`                 | add workspace nullable; bootstrap; validate active owners                              | retain global slug/FKs                          | workspace composites; global unique contracts later           |
+| `projects.status`                              | add `canonical_status`; map active/paused/completed/archived                           | mirror representable values; no `planning`      | canonical authority; legacy contracts later                   |
+| project `owner_id/team_id/owner_type`          | add exact accountable user/team; deterministic map or quarantine                       | preserve old reads and compare drift            | canonical exact-one; remove legacy after parity               |
+| current milestone                              | create milestones then join table (no circular DDL)                                    | absent to N-1                                   | join is authority                                             |
+| nullable `missions.project_id`                 | derive workspace/project; null/orphan exception, never guess                           | keep nullable legacy read                       | canonical required; validate/set NOT NULL later               |
+| mission `description`                          | add objective; preserve description; reviewed nonblank mapping                         | N-1 description                                 | objective authority; retain until signed review               |
+| `missions.status`                              | add canonical; planning→draft, active/paused/completed/failed same                     | no new-only statuses emitted                    | canonical authority                                           |
+| mission `milestones` JSON                      | normalize with source digest; preserve malformed/original                              | N-1 reads JSON; no reverse sync                 | normalized authority; JSON removed after checksum sign-off    |
+| mission config/metadata/phase/user             | retain all; map known typed policy only                                                | all remain declared                             | remove only by signed consumer inventory                      |
+| nullable `tasks.project_id`                    | derive explicit/mission project; orphan quarantine                                     | retain nullable read/write during compatibility | canonical required; NOT NULL later                            |
+| `tasks.mission_id`                             | add project-congruent composite                                                        | old relation readable                           | composite authority                                           |
+| `tasks.status`                                 | canonical: not-started→backlog, in-progress→in_progress, others same                   | no ready/in_review emission                     | canonical authority                                           |
+| `tasks.assignee`                               | deterministic active user/team/agent assignment; raw value preserved if ambiguous      | mirror text only if unambiguous                 | canonical owner/assignment; remove after no-loss sign-off     |
+| `tasks.tags` JSON                              | normalize trim/case/dedupe with original digest                                        | transactionally mirror normalized rows          | normalized authority; JSON later removed                      |
+| `tasks.due_date`                               | copy exactly to `due_at`                                                               | mirror                                          | due_at authority; legacy later                                |
+| task common fields                             | preserve metadata byte-for-byte; add criteria/rank/retry/archive/version/fence         | old reads valid                                 | new fields canonical                                          |
+| `mission_tasks.status`                         | keep; prohibit as write source; linked status ignored; unlinked becomes task or reject | read-only compatibility value                   | membership uses task mission; status dropped after no readers |
+| mission-task notes/PR/user                     | map to metadata/artifact/event/link/attribution; preserve                              | read-only                                       | remove after parity                                           |
+| `agents.status`                                | add workspace/lifecycle/runtime/roles; status remains presence                         | retain all legacy fields                        | lifecycle/roles authority; status may remain telemetry        |
+| agent project/owner/prompt/tools/skills/config | preserve; validate tenant; derive typed capabilities without loss                      | N-1 reads                                       | removal only by separate inventory                            |
+| fleet `backlog`                                | map to designated-project tasks; edges; claimed rows quarantine                        | freeze claims before switch; read-only compare  | task/lease authority; retire after stabilization              |
+
+### 5.4 Required migration tests
+
+Empty DB; exact production-shape snapshot; crash/resume; rollback before switch; N-1 startup/read/write; workspace/member negatives; status-shadow/no premature new status; `mission_tasks.status` write prohibition; tags/assignee/date/mission JSON/config/description/agent checksum; project congruence/current-milestone order; backlog freeze/no dispatch; and proof legacy declarations persist until contract release.
+
+Proposal-specific negatives must attempt: missing submission event, foreign-workspace submission event, foreign-workspace acceptance event, same-workspace event for another proposal, event for another target aggregate, and unrelated normal-command event. Every attempt must fail atomically with no accepted proposal and no target mutation.
+
+## 6. Ownership and Coordinator split
+
+coder2 solely owns `packages/db/src/schema.ts`, `packages/db/drizzle/**`, journal/metadata, and migration tests. No other lane generates migrations. Expand is additive; no drop/rename/narrow; constraints validate before NOT NULL; compatibility is same-DB only; contract is later.
+
+KBN-200/coder4 owns pure `MechanicalCoordinatorDecisionEngineV1`: complete immutable snapshots in, deterministic eligibility/proposal/retry decisions out; no ID loading, SQL, Gateway, Valkey, proof, persistence, restart I/O, or LLM.
+
+KBN-210/coder3 owns `MechanicalCoordinatorServicePortV1`: ID loading, locks, fresh proof, assignment/approval persistence, atomic fencing, lease/checkpoint/outbox, Valkey wakes, durable retry/quarantine, and `recoverFromPostgres`. Cycle: load snapshots → pure decision → persist assignment → authoritative approval/policy → acquire by IDs/locks → increment fence → lease → ack/heartbeat/checkpoint → submit to review or durable retry/quarantine. No completion/certification/merge method exists.
+
+## 7. Exact Gateway/DTO freeze for KBN-105
+
+### 7.1 Common wire rules
+
+Base is `/api/v1/workspaces/:workspaceId`. Mutations require header `Idempotency-Key` (1–128 chars). Existing-aggregate mutations also require `If-Match-Version` (positive integer); create and privileged assignment-cycle requests are the only exceptions, while proposal submission carries `expectedTargetVersion` in its body. Body workspace fields are forbidden. Tenant denial follows one 404/403 policy without foreign existence detail.
+
+```ts
+interface SuccessEnvelopeV1<T> {
+  contractVersion: '1.0.0';
+  data: T;
+  aggregateRevision: string;
+  correlationId: string;
+}
+interface ListEnvelopeV1<T> extends SuccessEnvelopeV1<T[]> {
+  page: { cursor: string | null; nextCursor: string | null; limit: number };
+}
+```
+
+Errors are the exact health/transport/version unions in §2 plus validation/auth/not-found. Public DTOs never expose/accept internal write proof.
+
+### 7.2 Exact route registry
+
+| Method/path                                             | Request body/query                                                                                                                                                                                                             | Success data                                                         |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `GET /kanban-health`                                    | none                                                                                                                                                                                                                           | `KanbanHealthResponseV1`                                             |
+| `GET /projects`                                         | `status,ownerUserId,ownerTeamId,cursor,limit`                                                                                                                                                                                  | project list                                                         |
+| `POST /projects`                                        | `name,key,description,status,priority,ownerUserId XOR ownerTeamId,metadata`                                                                                                                                                    | project                                                              |
+| `GET /projects/:projectId`                              | none                                                                                                                                                                                                                           | project                                                              |
+| `PATCH /projects/:projectId`                            | editable create fields + expected header                                                                                                                                                                                       | project                                                              |
+| `POST /projects/:projectId/archive`                     | `reason`                                                                                                                                                                                                                       | project                                                              |
+| `GET /tasks`                                            | `projectId,missionId,milestoneId,status,priority,ownerUserId,ownerTeamId,specialistRole,tag,dueState,archived,cursor,limit`                                                                                                    | task summary list                                                    |
+| `POST /tasks`                                           | `projectId,missionId?,milestoneId?,parentTaskId?,title,description?,acceptanceCriteria[],status,priority,rank,ownerUserId XOR ownerTeamId,specialistRole?,dueAt?,notBeforeAt?,estimateMinutes?,retryPolicy?,tagIds[],metadata` | task detail                                                          |
+| `GET /tasks/:taskId`                                    | none                                                                                                                                                                                                                           | task detail including readiness/dependencies/assignment/lease/events |
+| `PATCH /tasks/:taskId`                                  | editable non-transition fields                                                                                                                                                                                                 | task detail                                                          |
+| `POST /tasks/:taskId/transition`                        | `toStatus,reason?`                                                                                                                                                                                                             | task detail                                                          |
+| `POST /tasks/:taskId/move`                              | `toStatus?,beforeTaskId?,afterTaskId?`                                                                                                                                                                                         | task detail with persisted rank                                      |
+| `POST /tasks/:taskId/archive`                           | `reason`                                                                                                                                                                                                                       | task detail                                                          |
+| `PUT /tasks/:taskId/tags`                               | `tagIds[]`                                                                                                                                                                                                                     | task detail                                                          |
+| `POST /tasks/:taskId/dependencies`                      | `predecessorTaskId,type`                                                                                                                                                                                                       | dependency                                                           |
+| `DELETE /tasks/:taskId/dependencies/:predecessorTaskId` | no body                                                                                                                                                                                                                        | deleted dependency ID                                                |
+| `GET /tasks/:taskId/events`                             | `cursor,limit`                                                                                                                                                                                                                 | event list                                                           |
+| `GET /tags`                                             | `query,cursor,limit`                                                                                                                                                                                                           | tag list                                                             |
+| `POST /tags`                                            | `name,color?`                                                                                                                                                                                                                  | tag                                                                  |
+| `GET /change-proposals`                                 | `state,targetType,targetId,cursor,limit`                                                                                                                                                                                       | proposal list                                                        |
+| `POST /change-proposals`                                | `sourceNoteDigest,targetType,targetId,expectedTargetVersion,commandType,commandPayload`                                                                                                                                        | inert proposal                                                       |
+| `GET /change-proposals/:proposalId`                     | none                                                                                                                                                                                                                           | proposal                                                             |
+| `POST /change-proposals/:proposalId/accept`             | `reason`                                                                                                                                                                                                                       | proposal + normal command result                                     |
+| `POST /change-proposals/:proposalId/reject`             | `reason`                                                                                                                                                                                                                       | proposal                                                             |
+| `GET /coordinator/eligibility`                          | `projectId?,missionId?,cursor,limit`                                                                                                                                                                                           | `EligibilityDecisionV1[]`                                            |
+| `POST /coordinator/assignment-cycles`                   | `limit`                                                                                                                                                                                                                        | assignment proposals; privileged internal                            |
+| `POST /coordinator/assignments/:assignmentId/approve`   | `decision,reason,policyRevision,artifactIds[]`                                                                                                                                                                                 | approval decision                                                    |
+| `POST /coordinator/leases/acquire`                      | `taskId,assignmentId,approvalDecisionId,targetSessionId,leaseTtlSeconds`                                                                                                                                                       | lease with decimal-string fence                                      |
+| `POST /coordinator/leases/:leaseId/ack`                 | `taskId,sessionId,fencingToken`                                                                                                                                                                                                | lease                                                                |
+| `POST /coordinator/leases/:leaseId/heartbeat`           | `taskId,sessionId,fencingToken,extendSeconds`                                                                                                                                                                                  | lease                                                                |
+| `POST /coordinator/leases/:leaseId/checkpoints`         | `taskId,sessionId,fencingToken,sequence,resumableSummary,artifactIds[],contextUsagePercent`                                                                                                                                    | checkpoint                                                           |
+| `POST /coordinator/leases/:leaseId/submit-review`       | `taskId,sessionId,fencingToken,artifactIds[],summary`                                                                                                                                                                          | task in `in_review`                                                  |
+
+All Coordinator mutations except human approval are service-identity-only. Generic task PATCH cannot perform claim/heartbeat/checkpoint/review/certification/completion shortcuts. Completion after certification uses a separately gated lifecycle command owned by the Portfolio/Sub-Orchestrator flow, not the Coordinator.
+
+### 7.3 DTO invariants
+
+Task summary/detail use exact schema vocabularies, owner union, `version: number`, `fencingCounter: string`, explicit `archivedAt/by/reason`, normalized tags, computed readiness, and separate assignment/lease. Assignment DTO includes one persisted ID, task/version, exact principal/agent/session, role, state, expiry, policy, proposer/reason. Lease/checkpoint DTOs serialize every fence as decimal string. Proposal DTO exposes no hidden write authority.
+
+### 7.4 MCP ownership and mapping
+
+coder3 exclusively owns:
+
+- `apps/gateway/src/mcp/mcp.dto.ts`
+- `mcp.controller.ts`
+- `mcp.service.ts`
+- `mcp.module.ts`
+- `mcp.tokens.ts`
+- `mcp.service.spec.ts`
+
+MCP tools are thin maps: `mosaic_projects_{list,get,create,update,archive}`, `mosaic_tasks_{list,get,create,update,transition,move,archive,set_tags,add_dependency,remove_dependency}`, and `mosaic_change_proposals_{list,get,submit,accept,reject}` to the exact routes above. coder4 owns CLI/projection clients only and must not edit Gateway MCP files.
+
+KBN-105 publishes route+DTO fixture digest before KBN-110/120/130. Every web/CLI/MCP call must match this registry and the generated client.
+
+## 8. Recovery contract and bounded delivery slice
+
+Runtime must invoke normative `validateRecoveryPostureV1`; JSON Schema alone is insufficient. It rejects unknown fields, PITR/WAL mismatch, RPO better than mechanism, unsafe storage, and weakened High-assurance. High-assurance is RPO 15m/RTO 4h, WAL ≤5m, PITR ≥35d, base ≤24h, restore test ≤30d, break-glass ≤90d, encrypted separate-failure-domain storage.
+
+KBN-115/coder2 owns `packages/config/src/recovery-posture.ts`, tests, and recovery runbook. It wires parser/refinement, override audit, mechanism assertions, restore test, and break-glass evidence. Any deployment manifest is separately enumerated and Mos-serialized. Recovery config has no SOT/gate/Coordinator authority fields.
+
+## 9. Integration, security, and hold
+
+Required release evidence includes empty/prod/partial/rollback/N-1 migration tests; cross-workspace and same-workspace wrong-project negatives; active-membership owners/principals; proposal inertness/normal acceptance; exact failure mapping; concurrent monotonic bigint fences; relational lease/checkpoint/evidence mismatch; immutability privileges/RESTRICT; recovery validation/mechanism evidence; endpoint registry alignment; accessible web journeys; author≠reviewer; mandatory SecReview; final Certifier pass/no merge authority.
+
+The build hold remains active until independent re-review reports GO for KCR-001–016. Mos alone releases waves and serializes integration roots.

docs/native-kanban-sot/TASKS.md

@@ -0,0 +1,261 @@
+# Native Kanban/SOT P0–P3 — Dependency-Ordered Build Slices
+
+**Status:** CANON INDEPENDENTLY APPROVED; PUBLICATION IN PROGRESS
+**Tracking:** [Mosaic Stack issue #751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
+**Execution:** USC web1 only; collision-free GPT coder2/3/4/5 lanes
+**Contract:** `SHARED-CONTRACT.md` + four `contracts/*.v1.ts` files
+**Implementation hold:** no feature slice starts until the canon PR is merged to `main` with terminal-green CI; after merge, each slice remains held until every declared KBN prerequisite is complete.
+
+> This publication file is not a runtime task authority. After cutover, repository `TASKS.md` is generated read-only and never imported.
+
+## Execution invariants
+
+- PostgreSQL is the sole writable SOT; current-main Drizzle is the persistence foundation.
+- Mutations require fresh internal PostgreSQL transaction-local write proof and fail closed otherwise.
+- Public health DTOs, Valkey, files, browser state, providers, and outage notes cannot authorize writes.
+- Outage notes return only through attributable `change_proposals`; proposal acceptance executes the normal command.
+- Mechanical Coordinator is non-LLM and cannot invent scope, waive gates, certify, or merge.
+- Certifier is final independent gate with no merge authority.
+- Workspace is the hard tenant. Project hierarchy is project-congruent. Assignment, approval, lease, fence, checkpoint, and evidence are relationally bound.
+- Recovery tiers change recovery posture only.
+
+## 1. Collision-free ownership
+
+| USC lane                                                | Exclusive ownership                                                                                                                                                                                                                                                                                              | Must not edit                                               |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| **coder2 — schema/recovery**                            | `packages/db/src/schema.ts`; `packages/db/drizzle/**`; DB tests; `packages/config/src/recovery-posture.ts`; `packages/config/src/recovery-posture.spec.ts`; `docs/runbooks/kanban-postgres-recovery.md`                                                                                                          | Gateway, Brain repositories, Coordinator, web, CLI/importer |
+| **coder3 — domain/Gateway/MCP server**                  | Kanban repositories under `packages/brain/src/`; Gateway workspace/project/mission/milestone/task/kanban/health/coord modules; **exact MCP files:** `apps/gateway/src/mcp/mcp.dto.ts`, `mcp.controller.ts`, `mcp.service.ts`, `mcp.module.ts`, `mcp.tokens.ts`, `mcp.service.spec.ts`; Gateway root wiring/tests | DB schema/migrations, `packages/coord`, web, CLI/importer   |
+| **coder4 — CLI → pure Coordinator → migration tooling** | In this one fixed lane order: KBN-120 (`packages/mosaic` CLI/projection) → KBN-200 (`packages/coord/src/mechanical/**`) → KBN-300/320 (`scripts/kanban-migration/**`)                                                                                                                                            | DB, Gateway/MCP server, web                                 |
+| **coder5 — web**                                        | `apps/web/src/app/(dashboard)/{tasks,projects}/**`; `apps/web/src/components/{tasks,projects}/**`; Kanban web API/types; later Coordinator/migration-review routes                                                                                                                                               | DB, Gateway, Coordinator, CLI/importer                      |
+| **Mos — publication/integration**                       | Contract amendments, exact endpoint registry publication, serialized root exports/manifests/lockfiles, integration gates                                                                                                                                                                                         | Active lane feature files                                   |
+
+Shared roots, package exports/manifests, lockfiles, and generated artifacts are integration-serialized. Contract changes stop affected lanes and require Mos approval.
+
+## 2. Parallelization legend
+
+- **SERIAL:** prerequisite must be complete and reviewed.
+- **PARALLEL-GROUP:** disjoint files and exact frozen contract permit concurrent work.
+- **LANE-SERIAL:** one lane's stated order cannot change.
+- **INTEGRATION-SERIAL:** component heads green first; semantic findings return to owner.
+
+## 3. Corrected dependency graph
+
+```text
+KBN-000 canon remediation
+  -> KBN-010 threat/auth/constraint-impact gate (MUST COMPLETE)
+      -> KBN-100 schema + concrete N-1 migration implementation
+          ├─ KBN-105 exact endpoint/DTO/error/registry freeze (SERIAL)
+          │    ├─ KBN-110 domain + Gateway + MCP server implementation
+          │    ├─ KBN-120 CLI/projection implementation [coder4 first]
+          │    └─ KBN-130 web MVP implementation
+          └─ KBN-115 recovery parser/mechanism slice [coder2 lane-serial]
+KBN-110 + KBN-120 + KBN-130 + KBN-115
+  -> KBN-140 P1 integration/SIT
+      -> KBN-200 pure decision engine [coder4 after KBN-120]
+          -> KBN-210 persistence/service adapter + approval/lease binding
+              -> KBN-220 Coordinator operations UI
+                  -> KBN-230 P2 concurrency/fault/gate integration
+KBN-230
+  -> KBN-300 importer dry-run/apply/verify [coder4 after KBN-200]
+      ├─ KBN-310 migration reviewer UI
+      └─ KBN-320 cutover/rollback tooling [coder4 after KBN-300]
+KBN-310 + KBN-320
+  -> KBN-330 rehearsal/reconciliation
+      -> KBN-340 owner-gated cutover/stabilization
+```
+
+No consumer implementation begins before KBN-105. No schema work begins before KBN-010 completes. The coder4 order is always KBN-120 → KBN-200 → KBN-300 → KBN-320.
+
+## 4. P0 — Canon, threat gate, schema, and exact API freeze
+
+### KBN-000 — Remediate and publish canon
+
+- **Owner:** Mos / publication control plane.
+- **Mode:** SERIAL; publication gate in progress.
+- **IN:** Resolve KCR-001–016 in requirements, schema, health, Coordinator, recovery, migration map, and slices; independent re-review.
+- **OUT:** Feature implementation.
+- **Depends on:** none.
+- **Contract surfaces:** all canon.
+- **Evidence:** strict TS; Prettier; per-finding traceability; independent author≠reviewer GO.
+
+### KBN-010 — Threat, authorization, and constraint-impact gate
+
+- **Owner:** coder3; independent `secrev`.
+- **Mode:** SERIAL prerequisite of KBN-100.
+- **Exclusive files:** Mos-selected threat/auth docs only.
+- **IN:** Cross-workspace owners/principals/evidence; active membership; stale/forged health; approval forgery; fence monotonicity; audit retention; proposal target/audit-event forgery; service tokens; DB/Valkey outage.
+- **OUT:** Runtime/schema edits.
+- **Depends on:** KBN-000 independent re-review GO.
+- **Contract surfaces:** schema constraints, health proof, exact errors, command-family authorization.
+- **Evidence:** signed constraint-impact matrix; no unresolved schema-impact finding; SecReview pass.
+
+### KBN-100 — Unified Drizzle schema and concrete N-1 migration
+
+- **Owner:** **coder2**.
+- **Mode:** SERIAL.
+- **Exclusive files:** `packages/db/src/schema.ts`, `packages/db/drizzle/**`, DB tests.
+- **IN:** All frozen tables/joins/enums; workspace/project-congruent constraints; owners/principals; tags/archive; change proposals with both workspace-aware task-event composite FKs and frozen event-before-proposal DDL order; assignment approvals; durable execution/quarantine; monotonic bigint fence; exact checkpoint/evidence joins; RESTRICT/immutability; concrete current-main expand/backfill/switch/contract map.
+- **OUT:** Repositories, Gateway, Coordinator behavior, UI, importer.
+- **Depends on:** **KBN-010 completed**.
+- **Contract surfaces:** `kanban-schema.v1.ts`; SHARED-CONTRACT current-main delta map.
+- **Evidence:** reviewed SQL; empty/prod-shape/partial-resume/rollback tests; N-1 app safety; legacy columns remain declared; workspace/project mismatch negatives; proposal event-FK missing/foreign-workspace tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; SecReview.
+
+### KBN-105 — Exact Gateway/MCP endpoint, DTO, and error freeze
+
+- **Owner:** Mos + coder3 contract author; independent endpoint-alignment reviewer.
+- **Mode:** SERIAL after KBN-100; prerequisite for KBN-110/120/130.
+- **Exclusive files:** canonical endpoint-registry/DTO contract docs; no implementation.
+- **IN:** Exact routes and methods from SHARED-CONTRACT §8; request/success/error fields; status codes; pagination/filter/revision envelopes; idempotency/expected-version headers/fields; proposal commands; health proof exclusion from public DTOs; MCP tool-to-route map.
+- **OUT:** Controller/service/client implementation.
+- **Depends on:** KBN-100.
+- **Contract surfaces:** health/error unions; schema IDs/statuses; Gateway DTO freeze.
+- **Evidence:** every FE/CLI/MCP call maps 1:1 to a route; 503/502-504/409 non-cross-map fixtures; contract digest published.
+
+### KBN-115 — Recovery posture parser, mechanisms, and evidence
+
+- **Owner:** **coder2**, lane-serial after KBN-100.
+- **Mode:** PARALLEL with KBN-110/120/130 after KBN-105.
+- **Exclusive files:** `packages/config/src/recovery-posture.ts`, `.spec.ts`, `docs/runbooks/kanban-postgres-recovery.md`; deployment-specific backup manifest changes are a separately enumerated Mos integration patch.
+- **IN:** Wire normative `validateRecoveryPostureV1`; override audit; backup/WAL/PITR mechanism assertions; off-cluster encryption/failure-domain checks; restore and break-glass evidence procedure.
+- **OUT:** SOT/gate/Coordinator policy knobs; DB business schema.
+- **Depends on:** KBN-100, KBN-105.
+- **Contract surfaces:** `recovery-posture.v1.ts` only.
+- **Evidence:** impossible-combination tests; High-assurance weakening tests; selected-tier mechanism verification; restore and break-glass evidence; SecReview.
+
+## 5. P1 — Thin native MVP
+
+### KBN-110 — Workspace-safe domain, Gateway, MCP server, and proposal commands
+
+- **Owner:** **coder3**.
+- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
+- **Exclusive files:** ownership map, including all exact MCP server files listed there.
+- **IN:** Workspace-safe repositories; project/task/dependency/tag/archive CRUD; transitions; exact owners; assignment/approval/link/artifact queries; submit/query/accept/reject change proposals; health endpoint; internal write-proof mint/revalidation; event/outbox atomicity; frozen DTOs/routes.
+- **OUT:** Scheduling algorithm, web, CLI, DB schema.
+- **Depends on:** KBN-100, KBN-105.
+- **Contract surfaces:** all four TypeScript contracts and exact registry.
+- **Evidence:** DTO/service/controller/integration tests; active-membership and no-oracle negatives; proposal cannot mutate directly; submission event is the new proposal's exact `change_proposal.submitted` event; acceptance links the executed normal command for the locked proposal and same workspace/target; missing, foreign-workspace, unrelated-proposal/target/command event negatives; exact failure mapping; endpoint registry; SecReview.
+
+### KBN-120 — CLI, MCP client mapping, and generated projection
+
+- **Owner:** **coder4**; first coder4 slice.
+- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
+- **Exclusive files:** `packages/mosaic/src/commands/{kanban,tasks,projects}.ts`; `packages/mosaic/src/projections/**`; tests. **No `apps/gateway/src/mcp/**` edits.\*\*
+- **IN:** Frozen query/mutation routes; proposal commands; compact context; generated `TASKS.md`; deliberate denial/transport/conflict handling.
+- **OUT:** Gateway/MCP server, file importer, raw SQL/Valkey, Coordinator.
+- **Depends on:** KBN-105; runtime integration later requires KBN-110.
+- **Evidence:** contract fixtures; same revision; no import parser; same idempotency key on transport retry; 503 never auto-retried.
+
+### KBN-130 — Writable Kanban/List and minimal Projects UI
+
+- **Owner:** **coder5**.
+- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
+- **Exclusive files:** web ownership map.
+- **IN:** Workspace context; projects; tasks; tags; explicit archive; detail; accessible move/reorder; filters; dependency/readiness; owner/assignment/lease; audit; proposal visibility; conflict/loading/error/reconnect.
+- **OUT:** Gateway/schema, Coordinator operations UI, migration UI.
+- **Depends on:** KBN-105; runtime integration later requires KBN-110.
+- **Evidence:** frozen contract mocks; real-Gateway journeys; keyboard/non-drag; tags/archive semantics; no-oracle tenant negatives; 503/transport/409 distinct UI.
+
+### KBN-140 — P1 integration and situational gate
+
+- **Owner:** Mos integration; independent reviewer/SecReview/Certifier.
+- **Mode:** INTEGRATION-SERIAL.
+- **IN:** KBN-110/120/130/115; unavoidable root exports only.
+- **OUT:** P2 behavior.
+- **Depends on:** KBN-110, KBN-120, KBN-130, KBN-115.
+- **Evidence:** clean migration; web/CLI/MCP/projection revision parity; forged/expired health negatives; change-proposal event-chain success plus missing/foreign/unrelated-event negatives; tag/archive; tenant negatives; endpoint registry; author-independent review; Certifier pass.
+
+## 6. P2 — Mechanical Coordinator
+
+### KBN-200 — Pure deterministic decision engine
+
+- **Owner:** **coder4**; second coder4 slice, strictly after KBN-120.
+- **Mode:** SERIAL in coder4 lane.
+- **Exclusive files:** `packages/coord/src/mechanical/**` and pure tests.
+- **IN:** `MechanicalCoordinatorDecisionEngineV1`; complete immutable snapshots; eligibility/explanation; fairness/order; capability matching; expiry/retry/quarantine decisions.
+- **OUT:** ID loading, PostgreSQL, Drizzle, Gateway, Valkey, health-proof minting, persistence, `recoverFromPostgres`, LLM calls.
+- **Depends on:** KBN-140 (or Mos may release after KBN-120 + frozen types if no P1 semantic risk remains).
+- **Evidence:** deterministic/property tests; snapshot completeness; no I/O/model imports; no authority methods.
+
+### KBN-210 — Coordinator persistence/service adapter and approval-bound leases
+
+- **Owner:** **coder3**.
+- **Mode:** SERIAL after KBN-200.
+- **Exclusive files:** Gateway `coord` and repositories.
+- **IN:** `MechanicalCoordinatorServicePortV1`; snapshot loading; proposal persistence; manual/versioned policy approval; acquire by IDs; reload+lock task/assignment/approval/session; fresh txn-local write proof; atomic task fence increment; lease/ack/heartbeat/checkpoint/submit; durable retry/quarantine; outbox/Valkey wake; restart recovery.
+- **OUT:** Pure algorithm, UI, DB schema.
+- **Depends on:** KBN-110, KBN-200.
+- **Evidence:** forged/stale approval rejection; target/session/version/expiry/policy checks; concurrent monotonic fences; same-workspace mismatch negatives; bigint precision; stale worker rejection; DB/Valkey faults; SecReview.
+
+### KBN-220 — Coordinator operations UI
+
+- **Owner:** **coder5**.
+- **Mode:** after KBN-210 exact DTO freeze.
+- **IN:** Roster; eligibility; persisted assignment state; approvals/overrides; exact lease/fence; durable retry/quarantine; role/gate/Certifier visibility.
+- **OUT:** Scheduling decisions, schema, merge control for Certifier.
+- **Depends on:** KBN-210.
+- **Evidence:** authorized journeys; reason required; stale refresh; no Certifier merge; endpoint alignment/accessibility.
+
+### KBN-230 — P2 concurrency/fault/gate integration
+
+- **Owner:** Mos integration; independent reviewer/SecReview/Certifier.
+- **Mode:** INTEGRATION-SERIAL.
+- **Depends on:** KBN-200, KBN-210, KBN-220.
+- **Evidence:** one lease; monotonic fences; exact relational mismatches rejected; expired proof; forged healthy; approval binding; restart; durable quarantine; outbox recovery; author≠reviewer; Certifier final/no merge.
+
+## 7. P3 — Shadow migration and cutover
+
+### KBN-300 — One-way importer dry-run/apply/verify
+
+- **Owner:** **coder4**; third coder4 slice.
+- **Mode:** after KBN-230.
+- **Exclusive files:** `scripts/kanban-migration/import/**`.
+- **IN:** Immutable jarvis-brain/Vikunja snapshots; deterministic mapping; source digest/lineage; Gateway writes; rejects; no dispatch.
+- **OUT:** Bidirectional sync, direct DB/file canonical writes, unrelated brain data.
+- **Depends on:** KBN-230.
+- **Evidence:** idempotency; counts/fields; malformed/foreign rejects; no dispatch; SecReview.
+
+### KBN-310 — Shadow reviewer UI
+
+- **Owner:** **coder5**.
+- **Mode:** PARALLEL-GROUP P3-A after KBN-300 report freeze.
+- **IN:** Read-only counts/diffs/rejects/lineage/sign-off.
+- **OUT:** Apply/cutover mutations.
+- **Depends on:** KBN-300.
+- **Evidence:** read-only and tenant tests; pagination/accessibility.
+
+### KBN-320 — Cutover/rollback tooling
+
+- **Owner:** **coder4**; fourth coder4 slice, after KBN-300.
+- **Mode:** PARALLEL-GROUP P3-A with KBN-310.
+- **Exclusive files:** `scripts/kanban-migration/cutover/**`.
+- **IN:** Freeze assertion; backup/checksum; final delta; client switch; legacy writer/credential shutdown; rollback delta; stabilization.
+- **OUT:** Destructive deletion, reverse sync, ungated production execution.
+- **Depends on:** KBN-300.
+- **Evidence:** fail-safe rehearsal; no dual writer; rollback authority; SecReview.
+
+### KBN-330 — Migration rehearsal/reconciliation
+
+- **Owner:** Mos + coder4 support + independent data reviewer.
+- **Mode:** INTEGRATION-SERIAL.
+- **Depends on:** KBN-310, KBN-320.
+- **Evidence:** signed exceptions; selected-tier restore; backlog hold; no legacy changes; Certifier readiness.
+
+### KBN-340 — Final cutover/stabilization
+
+- **Owner:** Mos/control plane; owner-gated operation.
+- **Mode:** SERIAL.
+- **Depends on:** KBN-330 PASS and Jason authorization.
+- **Evidence:** no legacy writer; scoped Gateway identities; no accidental dispatch; terminal green health/CI; Certifier evidence; owner retirement approval.
+
+## 8. Consistent USC wave schedule
+
+| Wave | coder2                    | coder3                                 | coder4                         | coder5                         |
+| ---- | ------------------------- | -------------------------------------- | ------------------------------ | ------------------------------ |
+| 0    | Wait                      | **KBN-010**                            | Wait                           | Wait                           |
+| 1    | **KBN-100**               | Review constraint implementation       | Wait                           | Wait                           |
+| 2    | **KBN-115** after KBN-100 | **KBN-105** exact freeze, then KBN-110 | **KBN-120** only after KBN-105 | **KBN-130** only after KBN-105 |
+| 3    | Review support            | Finish KBN-110                         | **KBN-200 after KBN-120**      | Finish KBN-130                 |
+| 4    | —                         | **KBN-210 after KBN-200**              | Review/support                 | **KBN-220 after KBN-210 DTOs** |
+| 5    | —                         | P2 remediation                         | **KBN-300 then KBN-320**       | **KBN-310**                    |
+
+Mos alone releases slices and lifts the build hold after independent re-review GO.

docs/native-kanban-sot/contracts/health-state.v1.ts

@@ -0,0 +1,206 @@
+/**
+ * Mosaic Native Kanban — frozen health/error contract v1.
+ * Publication contract only; no runtime implementation is included here.
+ *
+ * PostgreSQL is the sole writable SOT. Public health DTOs are observations,
+ * never write authority. Only an internal transaction-local proof produced by
+ * the PostgreSQL adapter may authorize a mutation.
+ */
+
+export const KANBAN_CONTRACT_VERSION = '1.0.0' as const;
+
+export const kanbanHealthStates = ['healthy', 'read-only-degraded', 'write-unavailable'] as const;
+export type KanbanHealthState = (typeof kanbanHealthStates)[number];
+
+interface KanbanHealthBaseV1 {
+  contractVersion: typeof KANBAN_CONTRACT_VERSION;
+  checkedAt: string;
+  /** Observation expires at this RFC 3339 instant; it still never authorizes writes. */
+  validUntil: string;
+  policyRevision: string;
+  reasons: string[];
+}
+
+export interface HealthyKanbanHealthResponseV1 extends KanbanHealthBaseV1 {
+  state: 'healthy';
+  readHealthProven: true;
+  writeHealthProven: true;
+}
+
+export interface ReadOnlyDegradedKanbanHealthResponseV1 extends KanbanHealthBaseV1 {
+  state: 'read-only-degraded';
+  readHealthProven: true;
+  writeHealthProven: false;
+}
+
+export interface WriteUnavailableKanbanHealthResponseV1 extends KanbanHealthBaseV1 {
+  state: 'write-unavailable';
+  readHealthProven: false;
+  writeHealthProven: false;
+}
+
+/** Public, discriminated observation. Contradictory combinations are unrepresentable. */
+export type KanbanHealthResponseV1 =
+  | HealthyKanbanHealthResponseV1
+  | ReadOnlyDegradedKanbanHealthResponseV1
+  | WriteUnavailableKanbanHealthResponseV1;
+
+/** Pure evaluation context. It cannot authorize a mutation. */
+export interface KanbanEvaluationContextV1 {
+  contractVersion: typeof KANBAN_CONTRACT_VERSION;
+  workspaceId: string;
+  correlationId: string;
+  now: string;
+  policyRevision: string;
+  observedHealth: KanbanHealthResponseV1;
+}
+
+/**
+ * Non-exported brand: public DTO deserialization cannot construct this type.
+ * The PostgreSQL adapter mints it only after a fresh write probe inside the same
+ * transaction and validates checkedAt <= now < validUntil and policy revision.
+ */
+declare const postgresWriteHealthProofBrand: unique symbol;
+export interface PostgresWriteHealthProofV1 {
+  readonly [postgresWriteHealthProofBrand]: true;
+  readonly source: 'postgres-transaction-local-write-probe';
+  readonly transactionId: string;
+  readonly checkedAt: string;
+  readonly validUntil: string;
+  readonly policyRevision: string;
+}
+
+/** Internal mutation context; MUST NOT appear in REST/MCP/CLI request DTOs. */
+export interface InternalKanbanMutationContextV1 {
+  contractVersion: typeof KANBAN_CONTRACT_VERSION;
+  workspaceId: string;
+  correlationId: string;
+  causationId?: string;
+  idempotencyKey: string;
+  now: string;
+  expectedPolicyRevision: string;
+  writeProof: PostgresWriteHealthProofV1;
+}
+
+interface MutationFailureBaseV1 {
+  contractVersion: typeof KANBAN_CONTRACT_VERSION;
+  retryable: false;
+  requestOutcome: 'not_applied';
+  idempotencyKey: string;
+  correlationId: string;
+  message: string;
+}
+
+/** KCR-016: code/state pairing is exact and cannot cross-map. */
+export interface ReadOnlyWriteHealthDenialV1 extends MutationFailureBaseV1 {
+  kind: 'deliberate_fail_closed_denial';
+  code: 'KANBAN_WRITE_HEALTH_UNPROVEN';
+  healthState: 'read-only-degraded';
+  checkedAt: string;
+}
+
+export interface WriteUnavailableDenialV1 extends MutationFailureBaseV1 {
+  kind: 'deliberate_fail_closed_denial';
+  code: 'KANBAN_WRITE_UNAVAILABLE';
+  healthState: 'write-unavailable';
+  checkedAt: string;
+}
+
+export type DeliberateWriteDenialV1 = ReadOnlyWriteHealthDenialV1 | WriteUnavailableDenialV1;
+
+export const transportErrorCodes = [
+  'GATEWAY_UNREACHABLE',
+  'GATEWAY_TIMEOUT',
+  'UPSTREAM_BAD_GATEWAY',
+] as const;
+export type TransportErrorCode = (typeof transportErrorCodes)[number];
+
+/** Client-normalized transport uncertainty; never an authoritative 503 body. */
+export interface RetryableTransportErrorV1 {
+  contractVersion: typeof KANBAN_CONTRACT_VERSION;
+  kind: 'retryable_transport_error';
+  code: TransportErrorCode;
+  retryable: true;
+  requestOutcome: 'unknown';
+  /** Retry MUST reuse this exact key. */
+  idempotencyKey: string;
+  correlationId: string;
+  message: string;
+}
+
+export interface VersionConflictV1 {
+  contractVersion: typeof KANBAN_CONTRACT_VERSION;
+  kind: 'version_conflict';
+  code: 'AGGREGATE_VERSION_CONFLICT';
+  retryable: false;
+  requestOutcome: 'not_applied';
+  aggregateType: 'project' | 'mission' | 'milestone' | 'task' | 'change_proposal';
+  aggregateId: string;
+  expectedVersion: number;
+  actualVersion: number;
+  idempotencyKey: string;
+  correlationId: string;
+  message: string;
+}
+
+export type KanbanMutationFailureV1 =
+  | DeliberateWriteDenialV1
+  | RetryableTransportErrorV1
+  | VersionConflictV1;
+
+export const kanbanHealthCapabilities: Readonly<
+  Record<KanbanHealthState, { canonicalReads: boolean; mutations: boolean }>
+> = {
+  healthy: { canonicalReads: true, mutations: true },
+  'read-only-degraded': { canonicalReads: true, mutations: false },
+  'write-unavailable': { canonicalReads: false, mutations: false },
+};
+
+/** Exact HTTP/error normalization freeze; 503, transport, and 409 cannot cross-map. */
+export const kanbanFailureHttpMapV1 = {
+  KANBAN_WRITE_HEALTH_UNPROVEN: {
+    httpStatus: 503,
+    kind: 'deliberate_fail_closed_denial',
+    requestOutcome: 'not_applied',
+    retryable: false,
+  },
+  KANBAN_WRITE_UNAVAILABLE: {
+    httpStatus: 503,
+    kind: 'deliberate_fail_closed_denial',
+    requestOutcome: 'not_applied',
+    retryable: false,
+  },
+  AGGREGATE_VERSION_CONFLICT: {
+    httpStatus: 409,
+    kind: 'version_conflict',
+    requestOutcome: 'not_applied',
+    retryable: false,
+  },
+  GATEWAY_UNREACHABLE: {
+    httpStatus: 502,
+    kind: 'retryable_transport_error',
+    requestOutcome: 'unknown',
+    retryable: true,
+  },
+  GATEWAY_TIMEOUT: {
+    httpStatus: 504,
+    kind: 'retryable_transport_error',
+    requestOutcome: 'unknown',
+    retryable: true,
+  },
+  UPSTREAM_BAD_GATEWAY: {
+    httpStatus: 502,
+    kind: 'retryable_transport_error',
+    requestOutcome: 'unknown',
+    retryable: true,
+  },
+} as const;
+
+/**
+ * Required negative contract tests:
+ * - contradictory state/proof booleans fail type/schema validation;
+ * - expired internal proof and policy mismatch deny before mutation;
+ * - Valkey-only liveness cannot mint PostgresWriteHealthProofV1;
+ * - public/caller-forged `healthy` cannot enter InternalKanbanMutationContextV1;
+ * - authoritative 503, transport 502/504/timeout, and 409 mappings are exhaustive.
+ */

docs/native-kanban-sot/contracts/mechanical-coordinator.v1.ts

@@ -0,0 +1,419 @@
+/**
+ * Mosaic Native Kanban — frozen Mechanical Coordinator contracts v1.
+ *
+ * The pure decision engine and persistence/orchestration service are separate.
+ * Neither surface can create scope, edit acceptance, waive gates, certify,
+ * merge, release a deployment, or close a provider issue.
+ */
+
+import type {
+  DeliberateWriteDenialV1,
+  InternalKanbanMutationContextV1,
+  KanbanEvaluationContextV1,
+  KanbanMutationFailureV1,
+  RetryableTransportErrorV1,
+  VersionConflictV1,
+} from './health-state.v1.js';
+
+export const COORDINATOR_CONTRACT_VERSION = '1.0.0' as const;
+export type Uuid = string;
+export type IsoTimestamp = string;
+/** PostgreSQL bigint-safe decimal string; never a JavaScript number. */
+export type FencingTokenV1 = string;
+
+export const specialistRoles = [
+  'planning',
+  'enhance',
+  'coder',
+  'review',
+  'security-review',
+  'pr-monitor',
+  'certifier',
+] as const;
+export type SpecialistRole = (typeof specialistRoles)[number];
+
+/** One vocabulary shared with task_assignment_state_v1 in the Drizzle schema. */
+export const assignmentStates = [
+  'awaiting_approval',
+  'policy_pre_authorized',
+  'approved',
+  'rejected',
+  'leased',
+  'released',
+  'expired',
+  'superseded',
+] as const;
+export type AssignmentStateV1 = (typeof assignmentStates)[number];
+
+export const readinessStates = [
+  'dependency-gated',
+  'schedule-gated',
+  'policy-gated',
+  'lease-available',
+  'leased',
+  'retry-delayed',
+  'exhausted',
+  'quarantined',
+] as const;
+export type ReadinessState = (typeof readinessStates)[number];
+
+export interface RetryStateSnapshotV1 {
+  disposition: 'available' | 'retry_delayed' | 'quarantined' | 'exhausted';
+  attemptCount: number;
+  maxAttempts: number;
+  nextEligibleAt: IsoTimestamp | null;
+  idempotent: boolean;
+  terminalReason: string | null;
+  version: number;
+}
+
+export interface TaskEligibilitySnapshotV1 {
+  workspaceId: Uuid;
+  taskId: Uuid;
+  taskVersion: number;
+  projectId: Uuid;
+  projectActive: boolean;
+  missionId: Uuid | null;
+  missionActive: boolean;
+  status: 'ready';
+  priority: 'critical' | 'high' | 'medium' | 'low';
+  boardRank: string;
+  dueAt: IsoTimestamp | null;
+  notBeforeAt: IsoTimestamp | null;
+  createdAt: IsoTimestamp;
+  requiredRole: SpecialistRole;
+  requiredCapabilities: readonly string[];
+  blockingDependencies: readonly {
+    taskId: Uuid;
+    done: boolean;
+    completionConditionSatisfied: boolean;
+  }[];
+  releaseApproval: {
+    decisionId: Uuid;
+    approved: boolean;
+    policyRevision: string;
+  } | null;
+  activeLeaseId: Uuid | null;
+  retry: RetryStateSnapshotV1;
+}
+
+export interface AgentSessionSnapshotV1 {
+  workspaceId: Uuid;
+  agentId: Uuid;
+  sessionId: Uuid;
+  state: 'available' | 'busy';
+  roles: readonly SpecialistRole[];
+  capabilities: readonly string[];
+  capacity: number;
+  activeLeaseCount: number;
+  heartbeatAt: IsoTimestamp;
+}
+
+export interface EligibilityExplanationV1 {
+  taskId: Uuid;
+  eligible: boolean;
+  readiness: ReadinessState;
+  reasons: readonly {
+    gate:
+      | 'status'
+      | 'project'
+      | 'mission'
+      | 'dependency'
+      | 'schedule'
+      | 'retry'
+      | 'approval'
+      | 'lease'
+      | 'capability'
+      | 'capacity'
+      | 'health';
+    satisfied: boolean;
+    code: string;
+    detail: string;
+  }[];
+  policyRevision: string;
+  evaluatedAt: IsoTimestamp;
+}
+
+export interface AssignmentProposalDecisionV1 {
+  workspaceId: Uuid;
+  taskId: Uuid;
+  taskVersion: number;
+  targetAgentId: Uuid;
+  targetSessionId: Uuid;
+  specialistRole: SpecialistRole;
+  initialState: 'awaiting_approval' | 'policy_pre_authorized';
+  policyRevision: string;
+  explanation: EligibilityExplanationV1;
+  expiresAt: IsoTimestamp;
+}
+
+export interface AssignmentCycleSnapshotV1 {
+  context: KanbanEvaluationContextV1;
+  tasks: readonly TaskEligibilitySnapshotV1[];
+  sessions: readonly AgentSessionSnapshotV1[];
+  workspaceFairness: Readonly<Record<Uuid, number>>;
+  limit: number;
+}
+
+export interface AssignmentCycleDecisionV1 {
+  evaluatedTaskCount: number;
+  proposals: readonly AssignmentProposalDecisionV1[];
+  explanations: readonly EligibilityExplanationV1[];
+}
+
+export interface LeaseExpirySnapshotV1 {
+  workspaceId: Uuid;
+  taskId: Uuid;
+  taskVersion: number;
+  leaseId: Uuid;
+  assignmentId: Uuid;
+  sessionId: Uuid;
+  fencingToken: FencingTokenV1;
+  state: 'pending_ack' | 'active';
+  acknowledgeBy: IsoTimestamp;
+  expiresAt: IsoTimestamp;
+  lastHeartbeatAt: IsoTimestamp | null;
+  retry: RetryStateSnapshotV1;
+}
+
+export interface LeaseExpiryDecisionV1 {
+  leaseId: Uuid;
+  action: 'retain' | 'release' | 'retry' | 'quarantine' | 'exhaust';
+  reason: string;
+  nextEligibleAt: IsoTimestamp | null;
+}
+
+/** Pure package owned by KBN-200. It receives complete immutable snapshots. */
+export interface MechanicalCoordinatorDecisionEngineV1 {
+  evaluateAssignmentCycle(snapshot: AssignmentCycleSnapshotV1): AssignmentCycleDecisionV1;
+  explainEligibility(
+    context: KanbanEvaluationContextV1,
+    task: TaskEligibilitySnapshotV1,
+    sessions: readonly AgentSessionSnapshotV1[],
+  ): EligibilityExplanationV1;
+  decideLeaseExpiry(
+    context: KanbanEvaluationContextV1,
+    lease: LeaseExpirySnapshotV1,
+  ): LeaseExpiryDecisionV1;
+}
+
+export interface PersistedAssignmentV1 {
+  assignmentId: Uuid;
+  workspaceId: Uuid;
+  taskId: Uuid;
+  taskVersion: number;
+  targetAgentId: Uuid;
+  targetSessionId: Uuid;
+  specialistRole: SpecialistRole;
+  state: AssignmentStateV1;
+  policyRevision: string;
+  proposedBy: { kind: 'user' | 'agent'; id: Uuid };
+  reason: string;
+  createdAt: IsoTimestamp;
+  expiresAt: IsoTimestamp;
+}
+
+export interface TaskLeaseV1 {
+  leaseId: Uuid;
+  workspaceId: Uuid;
+  taskId: Uuid;
+  taskVersion: number;
+  assignmentId: Uuid;
+  agentId: Uuid;
+  sessionId: Uuid;
+  state: 'pending_ack' | 'active';
+  fencingToken: FencingTokenV1;
+  attempt: number;
+  acquiredAt: IsoTimestamp;
+  acknowledgeBy: IsoTimestamp;
+  lastHeartbeatAt: IsoTimestamp | null;
+  expiresAt: IsoTimestamp;
+}
+
+interface ServiceCommandBaseV1 {
+  context: InternalKanbanMutationContextV1;
+  taskId: Uuid;
+  expectedTaskVersion: number;
+}
+
+export interface AcquireApprovedLeaseCommandV1 extends ServiceCommandBaseV1 {
+  assignmentId: Uuid;
+  approvalDecisionId: Uuid;
+  targetSessionId: Uuid;
+  leaseTtlSeconds: number;
+}
+
+export interface LeaseCommandV1 extends ServiceCommandBaseV1 {
+  leaseId: Uuid;
+  sessionId: Uuid;
+  fencingToken: FencingTokenV1;
+}
+
+export interface HeartbeatLeaseCommandV1 extends LeaseCommandV1 {
+  extendSeconds: number;
+}
+
+export interface CheckpointCommandV1 extends LeaseCommandV1 {
+  sequence: number;
+  resumableSummary: string;
+  artifactIds: readonly Uuid[];
+  contextUsagePercent: number;
+}
+
+export interface SubmitForReviewCommandV1 extends LeaseCommandV1 {
+  artifactIds: readonly Uuid[];
+  summary: string;
+}
+
+export interface ReleaseLeaseCommandV1 extends LeaseCommandV1 {
+  reason:
+    | 'worker_requested'
+    | 'ack_timeout'
+    | 'heartbeat_timeout'
+    | 'task_submitted'
+    | 'policy_revoked'
+    | 'shutdown';
+}
+
+export interface AssignmentCycleCommandV1 {
+  context: InternalKanbanMutationContextV1;
+  limit: number;
+}
+
+export interface ExpirySweepCommandV1 {
+  context: InternalKanbanMutationContextV1;
+  limit: number;
+}
+
+export interface RecoverCoordinatorCommandV1 {
+  context: InternalKanbanMutationContextV1;
+}
+
+interface CoordinatorRejectionBaseV1 {
+  kind: 'coordinator_rejection';
+  retryable: false;
+  requestOutcome: 'not_applied';
+  correlationId: Uuid;
+  idempotencyKey: string;
+  message: string;
+}
+
+export type CoordinatorPolicyRejectionV1 =
+  | (CoordinatorRejectionBaseV1 & { code: 'WORKSPACE_MISMATCH' })
+  | (CoordinatorRejectionBaseV1 & {
+      code: 'TASK_NOT_ELIGIBLE';
+      explanation: EligibilityExplanationV1;
+    })
+  | (CoordinatorRejectionBaseV1 & { code: 'APPROVAL_REQUIRED' })
+  | (CoordinatorRejectionBaseV1 & { code: 'APPROVAL_STALE' })
+  | (CoordinatorRejectionBaseV1 & { code: 'ASSIGNMENT_STALE' })
+  | (CoordinatorRejectionBaseV1 & { code: 'ASSIGNMENT_TARGET_MISMATCH' })
+  | (CoordinatorRejectionBaseV1 & { code: 'POLICY_REVISION_MISMATCH' })
+  | (CoordinatorRejectionBaseV1 & { code: 'ARTIFACT_WORKSPACE_MISMATCH' })
+  | (CoordinatorRejectionBaseV1 & { code: 'LEASE_ALREADY_ACTIVE' })
+  | (CoordinatorRejectionBaseV1 & { code: 'LEASE_NOT_FOUND' })
+  | (CoordinatorRejectionBaseV1 & { code: 'LEASE_NOT_ACTIVE' })
+  | (CoordinatorRejectionBaseV1 & {
+      code: 'ACK_DEADLINE_EXPIRED';
+      expiredAt: IsoTimestamp;
+    })
+  | (CoordinatorRejectionBaseV1 & {
+      code: 'FENCING_TOKEN_STALE';
+      currentFencingToken: FencingTokenV1;
+    })
+  | (CoordinatorRejectionBaseV1 & { code: 'SESSION_MISMATCH' })
+  | (CoordinatorRejectionBaseV1 & {
+      code: 'HEARTBEAT_EXPIRED';
+      expiredAt: IsoTimestamp;
+    })
+  | (CoordinatorRejectionBaseV1 & {
+      code: 'CHECKPOINT_SEQUENCE_CONFLICT';
+      currentSequence: number;
+    })
+  | (CoordinatorRejectionBaseV1 & { code: 'RETRY_EXHAUSTED' })
+  | (CoordinatorRejectionBaseV1 & {
+      code: 'NON_IDEMPOTENT_RETRY_REQUIRES_ORCHESTRATOR';
+    });
+
+/** Explicit mapping to the Gateway mutation failure union; no arbitrary booleans. */
+export type CoordinatorFailureV1 =
+  | DeliberateWriteDenialV1
+  | VersionConflictV1
+  | RetryableTransportErrorV1
+  | CoordinatorPolicyRejectionV1;
+
+export interface CoordinatorSuccessV1<T> {
+  ok: true;
+  value: T;
+  correlationId: Uuid;
+}
+export interface CoordinatorFailureResultV1 {
+  ok: false;
+  failure: CoordinatorFailureV1;
+}
+export type CoordinatorResultV1<T> = CoordinatorSuccessV1<T> | CoordinatorFailureResultV1;
+
+export interface ExpirySweepResultV1 {
+  examined: number;
+  released: readonly Uuid[];
+  retryScheduled: readonly Uuid[];
+  quarantined: readonly Uuid[];
+  exhausted: readonly Uuid[];
+}
+
+export interface RestartRecoveryResultV1 {
+  activeLeaseIds: readonly Uuid[];
+  expiredLeaseIds: readonly Uuid[];
+  pendingAssignmentIds: readonly Uuid[];
+  pendingOutboxEventIds: readonly Uuid[];
+}
+
+/** Persistence/Gateway adapter owned by KBN-210. */
+export interface MechanicalCoordinatorServicePortV1 {
+  /** Loads immutable snapshots, invokes pure engine, and persists proposals atomically. */
+  runAssignmentCycle(
+    command: AssignmentCycleCommandV1,
+  ): Promise<CoordinatorResultV1<{ assignments: readonly PersistedAssignmentV1[] }>>;
+
+  /** Query path loads by ID; public health observation cannot authorize mutation. */
+  getEligibilityExplanation(
+    context: KanbanEvaluationContextV1,
+    taskId: Uuid,
+  ): Promise<CoordinatorResultV1<EligibilityExplanationV1>>;
+
+  /**
+   * Accepts IDs only. Implementation reloads and locks assignment + approval +
+   * task + target session in PostgreSQL, then verifies workspace, task version,
+   * target agent/session, state, expiry, policy revision, and current approval.
+   */
+  acquireApprovedLease(
+    command: AcquireApprovedLeaseCommandV1,
+  ): Promise<CoordinatorResultV1<TaskLeaseV1>>;
+
+  acknowledgeLease(command: LeaseCommandV1): Promise<CoordinatorResultV1<TaskLeaseV1>>;
+  heartbeatLease(command: HeartbeatLeaseCommandV1): Promise<CoordinatorResultV1<TaskLeaseV1>>;
+  appendCheckpoint(
+    command: CheckpointCommandV1,
+  ): Promise<CoordinatorResultV1<{ checkpointId: Uuid }>>;
+  submitForReview(
+    command: SubmitForReviewCommandV1,
+  ): Promise<CoordinatorResultV1<{ taskVersion: number; status: 'in_review' }>>;
+  releaseLease(command: ReleaseLeaseCommandV1): Promise<CoordinatorResultV1<{ released: true }>>;
+  expireAndRecover(
+    command: ExpirySweepCommandV1,
+  ): Promise<CoordinatorResultV1<ExpirySweepResultV1>>;
+  recoverFromPostgres(
+    command: RecoverCoordinatorCommandV1,
+  ): Promise<CoordinatorResultV1<RestartRecoveryResultV1>>;
+}
+
+/** Compile-time mapping guarantee: Coordinator Gateway failures are Kanban failures or exact policy rejections. */
+export function isKanbanMutationFailureV1(
+  failure: CoordinatorFailureV1,
+): failure is KanbanMutationFailureV1 {
+  return (
+    failure.kind === 'deliberate_fail_closed_denial' ||
+    failure.kind === 'retryable_transport_error' ||
+    failure.kind === 'version_conflict'
+  );
+}

docs/native-kanban-sot/contracts/recovery-posture.v1.ts

@@ -0,0 +1,369 @@
+/**
+ * Mosaic Native Kanban — frozen recovery-posture contract v1.
+ * Recovery posture is configurable; SOT, write-health, Coordinator authority,
+ * and gate semantics are not fields and cannot be overridden.
+ */
+
+export const RECOVERY_POSTURE_CONTRACT_VERSION = '1.0.0' as const;
+export const recoveryTiers = ['lite', 'standard', 'high-assurance'] as const;
+export type RecoveryTier = (typeof recoveryTiers)[number];
+
+export interface OffClusterStorageV1 {
+  required: true;
+  encrypted: true;
+  separateFailureDomain: true;
+  minimumCopies: number;
+  storageClass: 'encrypted-object-storage' | 'encrypted-backup-target';
+}
+
+export interface RecoveryPostureV1 {
+  contractVersion: typeof RECOVERY_POSTURE_CONTRACT_VERSION;
+  tier: RecoveryTier;
+  targetRpoMinutes: number;
+  targetRtoMinutes: number;
+  baseBackupIntervalHours: number;
+  /** null means WAL archival/PITR is disabled. */
+  walArchiveIntervalMinutes: number | null;
+  /** 0 means PITR is disabled. */
+  pitrRetentionDays: number;
+  restoreTestIntervalDays: number;
+  breakGlassDrillIntervalDays: number;
+  offClusterStorage: OffClusterStorageV1;
+}
+
+export const recoveryPostureDefaults: Readonly<Record<RecoveryTier, RecoveryPostureV1>> = {
+  lite: {
+    contractVersion: RECOVERY_POSTURE_CONTRACT_VERSION,
+    tier: 'lite',
+    targetRpoMinutes: 24 * 60,
+    targetRtoMinutes: 24 * 60,
+    baseBackupIntervalHours: 24,
+    walArchiveIntervalMinutes: null,
+    pitrRetentionDays: 0,
+    restoreTestIntervalDays: 90,
+    breakGlassDrillIntervalDays: 365,
+    offClusterStorage: {
+      required: true,
+      encrypted: true,
+      separateFailureDomain: true,
+      minimumCopies: 1,
+      storageClass: 'encrypted-backup-target',
+    },
+  },
+  standard: {
+    contractVersion: RECOVERY_POSTURE_CONTRACT_VERSION,
+    tier: 'standard',
+    targetRpoMinutes: 60,
+    targetRtoMinutes: 8 * 60,
+    baseBackupIntervalHours: 24,
+    walArchiveIntervalMinutes: 15,
+    pitrRetentionDays: 14,
+    restoreTestIntervalDays: 90,
+    breakGlassDrillIntervalDays: 180,
+    offClusterStorage: {
+      required: true,
+      encrypted: true,
+      separateFailureDomain: true,
+      minimumCopies: 1,
+      storageClass: 'encrypted-object-storage',
+    },
+  },
+  'high-assurance': {
+    contractVersion: RECOVERY_POSTURE_CONTRACT_VERSION,
+    tier: 'high-assurance',
+    targetRpoMinutes: 15,
+    targetRtoMinutes: 4 * 60,
+    baseBackupIntervalHours: 24,
+    walArchiveIntervalMinutes: 5,
+    pitrRetentionDays: 35,
+    restoreTestIntervalDays: 30,
+    breakGlassDrillIntervalDays: 90,
+    offClusterStorage: {
+      required: true,
+      encrypted: true,
+      separateFailureDomain: true,
+      minimumCopies: 1,
+      storageClass: 'encrypted-object-storage',
+    },
+  },
+};
+
+/** Shape schema. Normative cross-field semantics are enforced by validateRecoveryPostureV1. */
+export const recoveryPostureJsonSchemaV1 = {
+  $id: 'https://mosaicstack.dev/contracts/recovery-posture.v1.schema.json',
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'contractVersion',
+    'tier',
+    'targetRpoMinutes',
+    'targetRtoMinutes',
+    'baseBackupIntervalHours',
+    'walArchiveIntervalMinutes',
+    'pitrRetentionDays',
+    'restoreTestIntervalDays',
+    'breakGlassDrillIntervalDays',
+    'offClusterStorage',
+  ],
+  properties: {
+    contractVersion: { const: RECOVERY_POSTURE_CONTRACT_VERSION },
+    tier: { enum: recoveryTiers },
+    targetRpoMinutes: { type: 'integer', minimum: 1 },
+    targetRtoMinutes: { type: 'integer', minimum: 1 },
+    baseBackupIntervalHours: { type: 'integer', minimum: 1 },
+    walArchiveIntervalMinutes: {
+      anyOf: [{ type: 'integer', minimum: 1 }, { type: 'null' }],
+    },
+    pitrRetentionDays: { type: 'integer', minimum: 0 },
+    restoreTestIntervalDays: { type: 'integer', minimum: 1 },
+    breakGlassDrillIntervalDays: { type: 'integer', minimum: 1 },
+    offClusterStorage: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['required', 'encrypted', 'separateFailureDomain', 'minimumCopies', 'storageClass'],
+      properties: {
+        required: { const: true },
+        encrypted: { const: true },
+        separateFailureDomain: { const: true },
+        minimumCopies: { type: 'integer', minimum: 1 },
+        storageClass: {
+          enum: ['encrypted-object-storage', 'encrypted-backup-target'],
+        },
+      },
+    },
+  },
+} as const;
+
+export const recoveryValidationCodes = [
+  'INVALID_SHAPE',
+  'UNKNOWN_FIELD',
+  'PITR_REQUIRES_WAL',
+  'WAL_REQUIRES_PITR',
+  'RPO_BETTER_THAN_MECHANISM',
+  'OFF_CLUSTER_REQUIRED',
+  'HIGH_ASSURANCE_WEAKENED',
+] as const;
+export type RecoveryValidationCode = (typeof recoveryValidationCodes)[number];
+
+export interface RecoveryValidationIssueV1 {
+  code: RecoveryValidationCode;
+  path: string;
+  message: string;
+}
+export type RecoveryValidationResultV1 =
+  | { ok: true; value: RecoveryPostureV1 }
+  | { ok: false; issues: RecoveryValidationIssueV1[] };
+
+const topLevelFields = new Set([
+  'contractVersion',
+  'tier',
+  'targetRpoMinutes',
+  'targetRtoMinutes',
+  'baseBackupIntervalHours',
+  'walArchiveIntervalMinutes',
+  'pitrRetentionDays',
+  'restoreTestIntervalDays',
+  'breakGlassDrillIntervalDays',
+  'offClusterStorage',
+]);
+const storageFields = new Set([
+  'required',
+  'encrypted',
+  'separateFailureDomain',
+  'minimumCopies',
+  'storageClass',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPositiveInteger(value: unknown): value is number {
+  return Number.isInteger(value) && Number(value) > 0;
+}
+function isNonnegativeInteger(value: unknown): value is number {
+  return Number.isInteger(value) && Number(value) >= 0;
+}
+
+/**
+ * Normative parser/refinement. Deployment code MUST call this function (or a
+ * byte-for-byte behaviorally equivalent generated validator), not JSON Schema
+ * shape validation alone.
+ */
+export function validateRecoveryPostureV1(input: unknown): RecoveryValidationResultV1 {
+  const issues: RecoveryValidationIssueV1[] = [];
+  if (!isRecord(input)) {
+    return {
+      ok: false,
+      issues: [{ code: 'INVALID_SHAPE', path: '$', message: 'posture must be an object' }],
+    };
+  }
+
+  for (const key of Object.keys(input)) {
+    if (!topLevelFields.has(key)) {
+      issues.push({ code: 'UNKNOWN_FIELD', path: `$.${key}`, message: 'unknown field' });
+    }
+  }
+
+  const tier = input['tier'];
+  const storage = input['offClusterStorage'];
+  const integerFields = [
+    'targetRpoMinutes',
+    'targetRtoMinutes',
+    'baseBackupIntervalHours',
+    'restoreTestIntervalDays',
+    'breakGlassDrillIntervalDays',
+  ] as const;
+
+  if (input['contractVersion'] !== RECOVERY_POSTURE_CONTRACT_VERSION) {
+    issues.push({
+      code: 'INVALID_SHAPE',
+      path: '$.contractVersion',
+      message: `must equal ${RECOVERY_POSTURE_CONTRACT_VERSION}`,
+    });
+  }
+  if (!recoveryTiers.includes(tier as RecoveryTier)) {
+    issues.push({ code: 'INVALID_SHAPE', path: '$.tier', message: 'unknown recovery tier' });
+  }
+  for (const field of integerFields) {
+    if (!isPositiveInteger(input[field])) {
+      issues.push({
+        code: 'INVALID_SHAPE',
+        path: `$.${field}`,
+        message: 'must be a positive integer',
+      });
+    }
+  }
+  if (!isNonnegativeInteger(input['pitrRetentionDays'])) {
+    issues.push({
+      code: 'INVALID_SHAPE',
+      path: '$.pitrRetentionDays',
+      message: 'must be a nonnegative integer',
+    });
+  }
+  if (
+    input['walArchiveIntervalMinutes'] !== null &&
+    !isPositiveInteger(input['walArchiveIntervalMinutes'])
+  ) {
+    issues.push({
+      code: 'INVALID_SHAPE',
+      path: '$.walArchiveIntervalMinutes',
+      message: 'must be null or a positive integer',
+    });
+  }
+
+  if (!isRecord(storage)) {
+    issues.push({
+      code: 'INVALID_SHAPE',
+      path: '$.offClusterStorage',
+      message: 'must be an object',
+    });
+  } else {
+    for (const key of Object.keys(storage)) {
+      if (!storageFields.has(key)) {
+        issues.push({
+          code: 'UNKNOWN_FIELD',
+          path: `$.offClusterStorage.${key}`,
+          message: 'unknown field',
+        });
+      }
+    }
+    if (
+      storage['required'] !== true ||
+      storage['encrypted'] !== true ||
+      storage['separateFailureDomain'] !== true
+    ) {
+      issues.push({
+        code: 'OFF_CLUSTER_REQUIRED',
+        path: '$.offClusterStorage',
+        message: 'storage must be required, encrypted, and in a separate failure domain',
+      });
+    }
+    if (!isPositiveInteger(storage['minimumCopies'])) {
+      issues.push({
+        code: 'INVALID_SHAPE',
+        path: '$.offClusterStorage.minimumCopies',
+        message: 'must be a positive integer',
+      });
+    }
+    if (
+      storage['storageClass'] !== 'encrypted-object-storage' &&
+      storage['storageClass'] !== 'encrypted-backup-target'
+    ) {
+      issues.push({
+        code: 'INVALID_SHAPE',
+        path: '$.offClusterStorage.storageClass',
+        message: 'unsupported storage class',
+      });
+    }
+  }
+
+  const wal = input['walArchiveIntervalMinutes'];
+  const pitr = input['pitrRetentionDays'];
+  if (pitr !== 0 && wal === null) {
+    issues.push({
+      code: 'PITR_REQUIRES_WAL',
+      path: '$.pitrRetentionDays',
+      message: 'PITR retention requires WAL archival',
+    });
+  }
+  if (wal !== null && pitr === 0) {
+    issues.push({
+      code: 'WAL_REQUIRES_PITR',
+      path: '$.walArchiveIntervalMinutes',
+      message: 'WAL archival requires positive PITR retention',
+    });
+  }
+
+  if (
+    isPositiveInteger(input['targetRpoMinutes']) &&
+    isPositiveInteger(input['baseBackupIntervalHours']) &&
+    (wal === null || isPositiveInteger(wal))
+  ) {
+    const mechanismMinutes = wal === null ? input['baseBackupIntervalHours'] * 60 : wal;
+    if (mechanismMinutes > input['targetRpoMinutes']) {
+      issues.push({
+        code: 'RPO_BETTER_THAN_MECHANISM',
+        path: '$.targetRpoMinutes',
+        message: `configured mechanism can only support ${mechanismMinutes} minutes`,
+      });
+    }
+  }
+
+  if (tier === 'high-assurance') {
+    const weakened =
+      !isPositiveInteger(input['targetRpoMinutes']) ||
+      input['targetRpoMinutes'] > 15 ||
+      !isPositiveInteger(input['targetRtoMinutes']) ||
+      input['targetRtoMinutes'] > 4 * 60 ||
+      !isPositiveInteger(input['baseBackupIntervalHours']) ||
+      input['baseBackupIntervalHours'] > 24 ||
+      !isPositiveInteger(wal) ||
+      wal > 5 ||
+      !isNonnegativeInteger(pitr) ||
+      pitr < 35 ||
+      !isPositiveInteger(input['restoreTestIntervalDays']) ||
+      input['restoreTestIntervalDays'] > 30 ||
+      !isPositiveInteger(input['breakGlassDrillIntervalDays']) ||
+      input['breakGlassDrillIntervalDays'] > 90;
+    if (weakened) {
+      issues.push({
+        code: 'HIGH_ASSURANCE_WEAKENED',
+        path: '$',
+        message: 'high-assurance posture may be strengthened but not weakened',
+      });
+    }
+  }
+
+  if (issues.length > 0) return { ok: false, issues };
+  return { ok: true, value: input as unknown as RecoveryPostureV1 };
+}
+
+export interface RecoveryPostureOverrideAuditV1 {
+  actorId: string;
+  reason: string;
+  effectiveAt: string;
+  policyRevision: string;
+  previous: RecoveryPostureV1;
+  next: RecoveryPostureV1;
+}

docs/native-kanban-sot/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "incremental": false,
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "baseUrl": ".",
+    "paths": {
+      "drizzle-orm": ["../../packages/db/node_modules/drizzle-orm/index.d.ts"],
+      "drizzle-orm/pg-core": ["../../packages/db/node_modules/drizzle-orm/pg-core/index.d.ts"]
+    }
+  },
+  "include": ["contracts/*.ts"]
+}

docs/openapi-tess.yaml

@@ -0,0 +1,389 @@
+openapi: 3.1.0
+info: { title: Mosaic Tess Gateway, version: 1.0.0 }
+security: [{ sessionAuth: [] }]
+paths:
+  /api/interaction/{agentName}/sessions:
+    {
+      get:
+        {
+          summary: List authorized runtime sessions,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/provider' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          responses: { '200': { description: Sessions } },
+        },
+    }
+  /api/interaction/{agentName}/transitional-capabilities:
+    {
+      get:
+        {
+          summary: Get transitional capability matrix,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/provider' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          responses: { '200': { description: Matrix } },
+        },
+    }
+  /api/interaction/{agentName}/tree:
+    {
+      get:
+        {
+          summary: Get authorized session tree,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/provider' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          responses: { '200': { description: Tree } },
+        },
+    }
+  /api/interaction/{agentName}/sessions/{sessionId}/enroll:
+    {
+      post:
+        {
+          summary: Enroll a durable session,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/sessionId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          requestBody: { $ref: '#/components/requestBodies/Enroll' },
+          responses: { '200': { description: Enrolled } },
+        },
+    }
+  /api/interaction/{agentName}/sessions/{sessionId}/attach:
+    {
+      post:
+        {
+          summary: Attach to a runtime session,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/sessionId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          requestBody: { $ref: '#/components/requestBodies/Attach' },
+          responses: { '200': { description: Attachment } },
+        },
+    }
+  /api/interaction/{agentName}/sessions/{sessionId}/send:
+    {
+      post:
+        {
+          summary: Queue a durable provider send,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/sessionId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          requestBody: { $ref: '#/components/requestBodies/Send' },
+          responses: { '200': { description: Queued } },
+        },
+    }
+  /api/interaction/{agentName}/sessions/{sessionId}/stop:
+    {
+      post:
+        {
+          summary: Stop a session with approval,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/sessionId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          requestBody: { $ref: '#/components/requestBodies/Stop' },
+          responses: { '200': { description: Stopped }, '403': { description: Approval denied } },
+        },
+    }
+  /api/interaction/{agentName}/sessions/{sessionId}/recover:
+    {
+      post:
+        {
+          summary: Recover interrupted durable work,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/sessionId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          responses: { '200': { description: Recovered } },
+        },
+    }
+  /api/coord/mos/handoff:
+    {
+      post:
+        {
+          summary: Submit Mos handoff,
+          parameters: [{ $ref: '#/components/parameters/correlation' }],
+          requestBody: { $ref: '#/components/requestBodies/Handoff' },
+          responses: { '200': { description: Receipt } },
+        },
+    }
+  /api/coord/mos/{handoffId}/observe:
+    {
+      get:
+        {
+          summary: Observe Mos handoff,
+          parameters:
+            [
+              { $ref: '#/components/parameters/handoffId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          responses: { '200': { description: Observation } },
+        },
+    }
+  /api/coord/mos/{handoffId}/result:
+    {
+      get:
+        {
+          summary: Get Mos handoff result,
+          parameters:
+            [
+              { $ref: '#/components/parameters/handoffId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          responses: { '200': { description: Result } },
+        },
+    }
+  /api/interaction/{agentName}/sessions/{sessionId}/stream:
+    {
+      get:
+        {
+          summary: Stream runtime events,
+          parameters:
+            [
+              { $ref: '#/components/parameters/agentName' },
+              { $ref: '#/components/parameters/sessionId' },
+              { $ref: '#/components/parameters/correlation' },
+            ],
+          responses:
+            {
+              '200':
+                {
+                  description: Event stream,
+                  content: { text/event-stream: { schema: { type: string } } },
+                },
+            },
+        },
+    }
+  /api/memory/preferences:
+    {
+      get: { summary: List preferences, responses: { '200': { description: Preferences } } },
+      post:
+        {
+          summary: Upsert preference,
+          requestBody: { $ref: '#/components/requestBodies/Preference' },
+          responses: { '200': { description: Preference } },
+        },
+    }
+  /api/memory/preferences/{key}:
+    {
+      get:
+        {
+          summary: Get preference,
+          parameters: [{ $ref: '#/components/parameters/key' }],
+          responses: { '200': { description: Preference } },
+        },
+      delete:
+        {
+          summary: Delete preference,
+          parameters: [{ $ref: '#/components/parameters/key' }],
+          responses: { '204': { description: Deleted } },
+        },
+    }
+  /api/memory/insights:
+    {
+      get: { summary: List insights, responses: { '200': { description: Insights } } },
+      post:
+        {
+          summary: Create insight,
+          requestBody: { $ref: '#/components/requestBodies/Insight' },
+          responses: { '200': { description: Insight } },
+        },
+    }
+  /api/memory/insights/{id}:
+    {
+      get:
+        {
+          summary: Get insight,
+          parameters: [{ $ref: '#/components/parameters/id' }],
+          responses: { '200': { description: Insight } },
+        },
+      delete:
+        {
+          summary: Delete insight,
+          parameters: [{ $ref: '#/components/parameters/id' }],
+          responses: { '204': { description: Deleted } },
+        },
+    }
+  /api/memory/search:
+    {
+      post:
+        {
+          summary: Search memory,
+          requestBody: { $ref: '#/components/requestBodies/Search' },
+          responses: { '200': { description: Search results } },
+        },
+    }
+components:
+  securitySchemes: { sessionAuth: { type: http, scheme: bearer } }
+  parameters:
+    agentName: { name: agentName, in: path, required: true, schema: { type: string } }
+    sessionId: { name: sessionId, in: path, required: true, schema: { type: string } }
+    provider: { name: provider, in: query, required: true, schema: { type: string } }
+    correlation: { name: X-Correlation-Id, in: header, required: true, schema: { type: string } }
+    key: { name: key, in: path, required: true, schema: { type: string } }
+    id: { name: id, in: path, required: true, schema: { type: string } }
+  requestBodies:
+    Enroll:
+      {
+        required: true,
+        content:
+          {
+            application/json:
+              {
+                schema:
+                  {
+                    type: object,
+                    required: [providerId, runtimeSessionId],
+                    properties:
+                      { providerId: { type: string }, runtimeSessionId: { type: string } },
+                  },
+              },
+          },
+      }
+    Handoff:
+      {
+        required: true,
+        content:
+          {
+            application/json:
+              {
+                schema:
+                  {
+                    type: object,
+                    required: [idempotencyKey, summary],
+                    properties:
+                      {
+                        idempotencyKey: { type: string },
+                        summary: { type: string },
+                        context: { type: string },
+                        missionId: { type: string },
+                      },
+                  },
+              },
+          },
+      }
+    Attach:
+      {
+        content:
+          {
+            application/json: { schema: { type: object, properties: { mode: { enum: [read] } } } },
+          },
+      }
+    Send:
+      {
+        required: true,
+        content:
+          {
+            application/json:
+              {
+                schema:
+                  {
+                    type: object,
+                    required: [content, idempotencyKey],
+                    properties: { content: { type: string }, idempotencyKey: { type: string } },
+                  },
+              },
+          },
+      }
+    Stop:
+      {
+        required: true,
+        content:
+          {
+            application/json:
+              {
+                schema:
+                  {
+                    type: object,
+                    required: [approvalRef],
+                    properties: { approvalRef: { type: string } },
+                  },
+              },
+          },
+      }
+    Preference:
+      {
+        required: true,
+        content:
+          {
+            application/json:
+              {
+                schema:
+                  {
+                    type: object,
+                    required: [key, value],
+                    properties:
+                      {
+                        key: { type: string },
+                        value: {},
+                        category: { type: string },
+                        source: { type: string },
+                      },
+                  },
+              },
+          },
+      }
+    Insight:
+      {
+        required: true,
+        content:
+          {
+            application/json:
+              {
+                schema:
+                  {
+                    type: object,
+                    required: [content],
+                    properties:
+                      {
+                        content: { type: string },
+                        source: { type: string },
+                        category: { type: string },
+                        metadata: { type: object },
+                      },
+                  },
+              },
+          },
+      }
+    Search:
+      {
+        required: true,
+        content:
+          {
+            application/json:
+              {
+                schema:
+                  {
+                    type: object,
+                    required: [query],
+                    properties:
+                      {
+                        query: { type: string },
+                        limit: { type: integer },
+                        maxDistance: { type: number },
+                      },
+                  },
+              },
+          },
+      }

docs/reports/native-kanban-sot/canon-final-rereview-go.md

@@ -0,0 +1,59 @@
+VERDICT: GO
+
+# Native Kanban/SOT canon independent re-review 2
+
+Independent read-only re-review of the complete updated staged canon. Prior proposal-audit blocker is closed; no KCR-001–016 regression or new blocker found.
+
+## Prior blocker closure
+
+- `contracts/kanban-schema.v1.ts:836-837` declares the required unique `task_events(workspace_id,id)` key before proposal declaration.
+- `contracts/kanban-schema.v1.ts:885-894` adds both composite proposal audit FKs—submission and accepted-command event—to that exact workspace-aware key with `RESTRICT`.
+- Declaration/migration order is executable and explicit in `SHARED-CONTRACT.md:79-91`: events/key first, proposal table second, both FKs third/fourth, then command enablement. This avoids forward-reference/circular-DDL ambiguity.
+- Submission/acceptance semantics are frozen in `SHARED-CONTRACT.md:87-91`: preallocate proposal ID; create exact `change_proposal.submitted` event and proposal in one transaction; on acceptance lock proposal/target, execute the normal command, and bind only a same-workspace/target event with submission causation and `payload.changeProposalId` equal to the locked proposal.
+- Required missing, foreign-workspace, unrelated-proposal, unrelated-target, and unrelated-command negatives are explicit in `REQUIREMENTS.md` REQ-SOT-004 and `SHARED-CONTRACT.md:121`; KBN-100/110/140 own migration, service, and integration evidence.
+
+## KCR closure matrix
+
+| KCR                                                    | Status |
+| ------------------------------------------------------ | ------ |
+| 001 health/proof                                       | CLOSED |
+| 002 error discrimination                               | CLOSED |
+| 003 approval/assignment binding                        | CLOSED |
+| 004 monotonic fencing/composites                       | CLOSED |
+| 005 tenant-safe relations                              | CLOSED |
+| 006 outage proposal persistence/commands/audit binding | CLOSED |
+| 007 dependency/API freeze sequencing                   | CLOSED |
+| 008 concrete N-1 map                                   | CLOSED |
+| 009 dependency uniqueness                              | CLOSED |
+| 010 project congruence                                 | CLOSED |
+| 011 immutable audit retention                          | CLOSED |
+| 012 retry/quarantine/vocabulary                        | CLOSED |
+| 013 archive/tags target semantics                      | CLOSED |
+| 014 recovery validator/owner slice                     | CLOSED |
+| 015 pure Coordinator split                             | CLOSED |
+| 016 health code/state pairing                          | CLOSED |
+
+Fixed invariants remain consistent: PostgreSQL is sole writable SOT; writes require transaction-local proof and fail closed; exports never import sources; notes are attributable proposals only; Coordinator has no scope/gate/certify/merge authority; Certifier has no merge authority.
+
+## Reproducible validation evidence
+
+Executed read-only with current-stack config/toolchain `/src/mosaic-mono-v1`:
+
+```text
+./node_modules/.bin/prettier --config /src/mosaic-mono-v1/.prettierrc --check <all 9 publication artifacts>
+PASS: All matched files use Prettier code style.
+
+strict TypeScript --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext <four contract copies with current Drizzle node_modules resolution>
+PASS
+
+cascade/TODO/TBD/stale-hold grep plus composite-FK/semantic-marker invariant checks
+PASS
+```
+
+The TypeScript check used a disposable copy under `/home/hermes/agent-work` solely to provide external-file NodeNext dependency resolution; the reviewed staging artifacts were not modified.
+
+## Residual findings
+
+None blocking. Implementation must execute the frozen KBN-100/KBN-110/KBN-140 proposal-event-chain tests and SecReview evidence before feature release, as already required by the canon.
+
+No artifact source repository, branch, PR, or provider state was modified.

docs/reports/native-kanban-sot/canon-initial-review-no-go.md

@@ -0,0 +1,357 @@
+# Independent Review — Native Kanban/SOT Canon
+
+**Reviewer:** `enhance-sol` (independent of author `planner-sol`)
+**Date:** 2026-07-13
+**Review mode:** design/contract only; read-only against the staged canon
+**Source plan:** `/home/hermes/agent-work/planning/mosaic-native-kanban-sot-plan.md` (`sha256:96ea4fb91436ec9a53f371d27276e27f62ecf817662599ff9152df0db55296e5`)
+**Canon reviewed:** every listed artifact under `/home/hermes/agent-work/planning/kanban-canon/`, including the four TypeScript contracts; the author scratchpad was also read as validation context.
+
+## Executive verdict
+
+# NO-GO
+
+The canon is not freeze-ready. I found **8 BLOCKERs**, **7 MAJORs**, and **1 MINOR**. The prose preserves the ratified authority model well, but the frozen types/schema leave concrete fail-closed, approval, fencing, tenant, outage-proposal, migration, and parallelization gaps. Those gaps would force implementation lanes either to invent contract semantics or to ship paths that violate fixed invariants.
+
+### Blocking findings
+
+1. Health/write authorization can be represented as contradictory, stale, or caller-asserted state.
+2. Coordinator failures collapse authoritative denial, unknown transport outcome, and version conflict into one permissive shape.
+3. Assignment proposals and approval proofs have no authoritative relational binding; lease acquisition accepts a forgeable proof DTO.
+4. Fencing uniqueness is present, but monotonic fencing and same-task lease/checkpoint binding are not.
+5. Workspace-safe accountable-owner, assignment-principal, and evidence/artifact relationships are not frozen.
+6. Attributable post-recovery proposals have neither a canonical table nor command contract.
+7. The slice graph starts schema/UI work before prerequisite threat and exact API/DTO freezes and contradicts coder4 lane order.
+8. P0 claims a migration map while publishing only generic rules; the concrete N-1 transition from current `origin/main` is absent.
+
+---
+
+## Findings
+
+### KCR-001 — BLOCKER — “Healthy” is not a proof and can be contradictory or stale
+
+**Location**
+
+- `contracts/health-state.v1.ts:21-31` — `KanbanHealthResponseV1` permits every combination of `state`, `readHealthProven`, and `writeHealthProven`.
+- `contracts/mechanical-coordinator.v1.ts:40-49` — `CoordinatorContextV1` accepts a caller-supplied `healthState` enum only.
+- `contracts/mechanical-coordinator.v1.ts:255-293` — every Coordinator operation, including mutating operations, accepts that context.
+- `SHARED-CONTRACT.md:171-184` — mutations are allowed only after live PostgreSQL read/write probes.
+
+**Violation**
+
+Fixed invariant 2 / `REQ-SOT-002`: mutations must fail closed unless write health is positively proven. The current type permits `{ state: 'healthy', writeHealthProven: false }`, and the Coordinator mutation boundary can be invoked with a stale or fabricated `{ healthState: 'healthy' }`. A Valkey/client-derived enum could therefore be mistaken for write authorization.
+
+**Minimal fix**
+
+1. Make `KanbanHealthResponseV1` a discriminated union with only these legal combinations: `healthy => read=true/write=true`, `read-only-degraded => read=true/write=false`, and `write-unavailable => read=false/write=false`.
+2. Do not accept write authority from a public DTO. Require Gateway/domain code to obtain and revalidate a fresh internal PostgreSQL write-health proof at mutation time (including `checkedAt`, bounded validity/policy revision, and transaction-local enforcement).
+3. Split pure evaluation context from mutation context; mutation methods must accept only an unforgeable/internal healthy context or perform the probe themselves.
+4. Add negative contract tests for contradictory state, expired proof, Valkey-only liveness, and caller-forged `healthy`.
+
+### KCR-002 — BLOCKER — Coordinator error shape can conflate denial, unknown outcome, and conflict
+
+**Location**
+
+- `contracts/mechanical-coordinator.v1.ts:184-216` — one `CoordinatorFailureV1` allows every code to pair with arbitrary `retryable` and either `requestOutcome` value.
+- `contracts/health-state.v1.ts:51-106` — the Gateway health contract correctly distinguishes deliberate denial, transport uncertainty, and version conflict.
+- `SHARED-CONTRACT.md:177-216` — frozen client semantics require those cases not to be conflated.
+
+**Violation**
+
+Charter E and `REQ-SOT-002`. The current Coordinator result can legally encode `WRITE_HEALTH_UNPROVEN` as `retryable: true, requestOutcome: 'unknown'`, or `VERSION_CONFLICT` as retryable. That permits blind retry or a false “unknown” outcome after an authoritative fail-closed denial.
+
+**Minimal fix**
+
+Replace `CoordinatorFailureV1` with a discriminated union keyed by code/kind:
+
+- deliberate health denial: `not_applied`, `retryable:false`;
+- version conflict: `not_applied`, `retryable:false`, current version;
+- stale fence/session/eligibility/approval failures: exact non-retry semantics;
+- transport failure: a separate `retryable_transport_error`, `unknown`, same idempotency key.
+
+Reuse or map explicitly to `KanbanMutationFailureV1`, and add exhaustive client tests proving 503 authoritative bodies, 502/504/timeouts, and 409 cannot cross-map.
+
+### KCR-003 — BLOCKER — Approval proof is forgeable and is not linked to the persisted proposal
+
+**Location**
+
+- `contracts/mechanical-coordinator.v1.ts:107-137` — proposal and approval DTOs.
+- `contracts/mechanical-coordinator.v1.ts:265-270` — `acquireApprovedLease` accepts the entire `ApprovalProofV1` by value.
+- `contracts/kanban-schema.v1.ts:650-688` — `task_assignments` has no proposal expiry, task version, session binding, or proposal/approval FK.
+- `contracts/kanban-schema.v1.ts:823-863` — `approval_decisions` can target only a task or mission and has no proposal/assignment relation.
+- `SHARED-CONTRACT.md:128-137` — lease acquisition requires authoritative approval under the exact policy revision.
+
+**Violation**
+
+Fixed invariant 5 and `REQ-COORD-002/003`. A caller can construct an `ApprovalProofV1`; the schema cannot prove that it belongs to the proposal, workspace, task version, agent/session, unexpired policy revision, or still-current approval. The DTO state vocabulary (`awaiting_approval | policy_pre_authorized`) also does not map directly to the persisted assignment states (`proposed | approved | ...`).
+
+**Minimal fix**
+
+Persist one authoritative proposal/assignment identity with task version, target agent/session, expiry, state, and policy revision. Add a workspace-aware approval relation to that identity. Change lease acquisition to accept IDs, then reload and lock proposal + approval + task inside PostgreSQL and verify workspace, current version, target session, state, expiry, and policy revision before creating the lease. Freeze one state vocabulary across schema and DTOs.
+
+### KCR-004 — BLOCKER — Fencing is unique but not monotonically increasing; relational binding is incomplete
+
+**Location**
+
+- `contracts/kanban-schema.v1.ts:694-743` — `task_leases` has positive/unique fencing tokens but no monotonic per-task counter.
+- `contracts/kanban-schema.v1.ts:748-784` — checkpoints independently carry task, lease, and fencing token.
+- `contracts/kanban-schema.v1.ts:905-910` — token equality is deferred to prose; same-task lease binding is not stated.
+- `contracts/mechanical-coordinator.v1.ts:140-175` — worker commands depend on fencing safety.
+
+**Violation**
+
+Fixed invariant 12 / `REQ-COORD-003`. Uniqueness permits token 10 followed by token 9. A lease can reference assignment A while naming task B in the same workspace, and a checkpoint can reference lease A while naming task B. `bigint(..., { mode: 'number' })` also eventually loses integer precision in JavaScript.
+
+**Minimal fix**
+
+Add a durable per-task fencing counter (or equivalent PostgreSQL sequence row) incremented atomically under task lock and use the returned value for every new lease. Add workspace-aware composite constraints tying lease to its exact task+assignment and checkpoint to exact task+lease+fence. Use bigint-safe representation (`bigint`/serialized decimal), and test monotonicity, concurrent claims, stale lower tokens, and mismatched same-workspace IDs.
+
+### KCR-005 — BLOCKER — Hard tenant boundary is not frozen for several polymorphic relationships
+
+**Location**
+
+- `contracts/kanban-schema.v1.ts:315-318` and `475-478` — project/task accountable owners are unvalidated `(kind, text id)` pairs.
+- `contracts/kanban-schema.v1.ts:659-663` — assignment principals are unvalidated `(kind, text id)` pairs.
+- `contracts/kanban-schema.v1.ts:758` and `841` — checkpoint/evidence artifact relationships are JSON arrays without workspace-aware FKs.
+- `SHARED-CONTRACT.md:89-96` — only selected polymorphic checks are delegated to domain transactions; owner/principal/evidence checks are not included.
+- `REQUIREMENTS.md:101-108` — every relationship must reject cross-workspace IDs.
+
+**Violation**
+
+Fixed invariant 7 / `REQ-TEN-001` and `REQ-ID-001`. The frozen schema can name a team or agent from another workspace as owner/assignee, and can embed foreign-workspace artifact IDs in checkpoint or approval evidence arrays. A global user ID is also insufficient without active workspace membership validation.
+
+**Minimal fix**
+
+Use workspace-aware owner/assignment join tables or separate nullable user/team/agent columns with exactly-one checks and composite FKs where possible. Model checkpoint/evidence artifact links as workspace-scoped join rows, or freeze explicit transaction checks for every ID. Require active workspace membership for user principals and workspace-agent/session consistency for agent principals. Add DB/repository/API/Coordinator cross-workspace negative tests without existence oracles.
+
+### KCR-006 — BLOCKER — Post-recovery outage proposals have no canonical persistence or command surface
+
+**Location**
+
+- `REQUIREMENTS.md:93-99` — proposal submission and authorized accept/reject are required.
+- `SHARED-CONTRACT.md:26-29` — outage notes may return only as authenticated proposals.
+- `SHARED-CONTRACT.md:243-267` — the thin command/query contract contains no proposal submit/get/accept/reject operations.
+- `contracts/kanban-schema.v1.ts:1-916` — no proposal table captures proposed command, target/version, attribution, lifecycle, or decision.
+- `TASKS.md:99-108` — KBN-110 does not own an outage-proposal command path.
+
+**Violation**
+
+Fixed invariant 4 / `REQ-SOT-004`. An implementation lane would have to invent storage or misuse artifacts/approval gates. Either path risks silently applying an outage note or creating shadow state.
+
+**Minimal fix**
+
+Add a workspace-scoped `change_proposals`/`outage_proposals` contract with authenticated proposer, source note digest, target aggregate, expected version, proposed typed command/payload, pending/accepted/rejected state, decision actor/reason/time, idempotency key, and audit linkage. Add explicit submit/query/accept/reject Gateway commands. Acceptance must execute the normal command in a healthy transaction; a proposal itself can never claim, order, satisfy a gate, or mutate the target.
+
+### KCR-007 — BLOCKER — Parallel slice ordering is not freeze-safe and contains a direct lane-order contradiction
+
+**Location**
+
+- `TASKS.md:43-60` — dependency graph makes KBN-010 and KBN-100 siblings.
+- `TASKS.md:88-97` — KBN-100 nevertheless depends on KBN-010 threat findings that alter constraints.
+- `SHARED-CONTRACT.md:243` and `INDEX.md:44-50` — exact route names/DTO placement remain unresolved.
+- `TASKS.md:110-130` — KBN-120/130 depend on a frozen endpoint/DTO contract, while mocks may begin before KBN-110 lands.
+- `TASKS.md:145-153` — KBN-200 says lane-serial after KBN-120.
+- `TASKS.md:248-254` — wave table runs KBN-200 before KBN-120.
+
+**Violation**
+
+Charter C and the mandatory freeze-before-parallelize gate. Schema can begin before tenant/threat findings are complete; web/CLI consumers have only semantic operations, not exact DTO/endpoint contracts; coder4 has two opposite legal orders. This does not create same-file edits immediately, but it guarantees contract invention or rework across active lanes.
+
+**Minimal fix**
+
+1. Make KBN-010 (or an explicit constraint-impact gate from it) a completed prerequisite of KBN-100.
+2. Add a small serialized KBN-105 endpoint/DTO/endpoint-registry freeze, with exact request/response/error DTOs, before KBN-120 and KBN-130 implementation.
+3. Choose one coder4 lane order and use it consistently in slice text, graph, and wave table.
+4. Name the exact MCP-owned files or assign their Gateway changes to coder3 before coder4 starts.
+
+### KCR-008 — BLOCKER — Claimed P0 migration map is absent; concrete N-1 hazards remain unresolved
+
+**Location**
+
+- `MISSION-MANIFEST.md:153-157` — P0 says to publish a migration map and states the build hold is lifted at line 3.
+- `SHARED-CONTRACT.md:101-121` — only generic expand/backfill/contract rules are supplied.
+- `contracts/kanban-schema.v1.ts:1-916` — target-state declarations reuse live table names and make target fields required.
+- Current foundation evidence: `origin/main:packages/db/src/schema.ts:120-301` has no workspace keys, nullable project/mission links, legacy text status vocabularies, `tasks.tags`, `tasks.assignee`, `tasks.due_date`, mission JSON milestones/config, `mission_tasks.status`, and legacy agent fields.
+
+**Violation**
+
+Charter D / `REQ-MIG-001` and the P0 exit claim. The generic rule is correct, but coder2 lacks the required field-by-field transition map. A direct Drizzle reconciliation could attempt type narrowing/status conversion, add required workspace/project/owner columns too early, or drop legacy columns before N-1 readers and writers are retired.
+
+**Minimal fix**
+
+Publish a concrete current-main delta map before lifting the hold. For each existing table/column, specify expand, backfill, compatibility read/write, switch, and contract release. At minimum cover:
+
+- nullable-first `workspace_id`, required project/owner fields, and workspace backfill;
+- legacy task/project/mission status aliases or shadow columns before v1 emission;
+- `mission_tasks.status` read retirement and write-source prohibition;
+- mapping/retention for tags, assignee, due date, mission description/config/milestones, and agent fields;
+- current milestone circular FK ordering;
+- empty, production-shape, partial-resume, and rollback/downgrade tests already named in §4.
+
+Explicitly require legacy columns to remain in the unified Drizzle declaration during the expand/N-1 window.
+
+### KCR-009 — MAJOR — Dependency uniqueness permits parallel duplicate edges
+
+**Location**
+
+- `contracts/kanban-schema.v1.ts:561-567` — unique key includes `dependencyType`.
+- `SHARED-CONTRACT.md:47-49` — calls for a unique directed edge.
+- `REQUIREMENTS.md:142-149` — duplicate edge attempts must fail.
+
+**Violation**
+
+`REQ-DEP-001`. The same predecessor/successor pair can be inserted three times, once per dependency type. That is not a unique directed edge and complicates readiness semantics.
+
+**Minimal fix**
+
+Make `(workspace_id, predecessor_task_id, successor_task_id)` unique independent of type, or explicitly redefine the requirement as one edge per type and freeze deterministic multi-edge completion semantics. The source plan says unique directed edge, so the former is the minimal faithful fix.
+
+### KCR-010 — MAJOR — Same-workspace planning relationships can contradict the project hierarchy
+
+**Location**
+
+- `contracts/kanban-schema.v1.ts:325` — `projects.currentMilestoneId` has no FK in the declaration.
+- `contracts/kanban-schema.v1.ts:427-448` — mission/milestone association checks workspace but not common project.
+- `contracts/kanban-schema.v1.ts:490-516` — a task’s project, mission, milestone, and parent only need share a workspace, not a project.
+- `contracts/kanban-schema.v1.ts:905-908` — only current milestone is mentioned as a deferred invariant.
+
+**Violation**
+
+`REQ-PLAN-001` and schema correctness. A task in project A can point to a mission/milestone/parent task from project B in the same workspace. A mission can associate a milestone from another project despite having one required project.
+
+**Minimal fix**
+
+Add project-congruent composite keys/FKs (or freeze mandatory transaction checks) for task→mission, task→milestone, task→parent, mission→milestone, and project→current milestone. Add same-workspace/same-project negative tests.
+
+### KCR-011 — MAJOR — Immutable/append-only records can be erased by parent cascades
+
+**Location**
+
+- `contracts/kanban-schema.v1.ts:798-818` — `task_events` is described as append-only but remains under a workspace cascade.
+- `contracts/kanban-schema.v1.ts:911` — only application-role UPDATE/DELETE privilege removal is stated.
+- Numerous canonical relationships use `onDelete('cascade')`, including workspace roots and artifact/checkpoint/event owners.
+- `REQUIREMENTS.md:41-43` and `154-170` — audit must be append-only, attributable, and reconstructable.
+
+**Violation**
+
+`REQ-AUD-001`. Revoking direct DELETE on `task_events` does not prevent a parent delete from cascading into the audit log. Checkpoints and immutable artifacts also lack explicit append-only privilege/retention semantics.
+
+**Minimal fix**
+
+Use lifecycle/archive states and `RESTRICT` for canonical parent deletion during normal operation. Freeze a separate, audited retention/break-glass purge procedure. Apply INSERT/SELECT-only or equivalent immutability controls to task events, checkpoints, and immutable artifacts, and test that parent deletion cannot silently erase them.
+
+### KCR-012 — MAJOR — Coordinator persistence lacks durable quarantine/retry state and DTO/schema alignment
+
+**Location**
+
+- `contracts/mechanical-coordinator.v1.ts:239-244` — expiry returns `quarantined` IDs.
+- `contracts/kanban-schema.v1.ts:457-490` — task has only untyped `retryPolicy` metadata and no quarantine/execution disposition.
+- `contracts/mechanical-coordinator.v1.ts:173` — `evidenceIds` has no corresponding evidence table/type; schema has artifacts.
+- `contracts/kanban-schema.v1.ts:479`, `663`, and agent role JSON — specialist roles are free text despite the frozen role vocabulary in `mechanical-coordinator.v1.ts:19-29`.
+
+**Violation**
+
+`REQ-COORD-004` and internal consistency. PostgreSQL cannot deterministically reconstruct why/when a task was quarantined, its bounded retry state, or which typed evidence was submitted. Free-text roles allow the schema and engine to disagree.
+
+**Minimal fix**
+
+Freeze a durable execution/retry/quarantine record (attempt count, next eligibility, terminal reason, actor/policy, timestamps, version) or typed task columns with events. Align `evidenceIds` to artifact IDs or add a real evidence entity. Use one specialist-role enum/check across tasks, assignments, agents/sessions, DTOs, and Coordinator.
+
+### KCR-013 — MAJOR — Thin MVP promises task archive and tag filtering without target-state semantics
+
+**Location**
+
+- `REQUIREMENTS.md:182-193` — users must archive tasks and filter by tags.
+- `SHARED-CONTRACT.md:252-267` — mutations include cancel but not archive task.
+- `contracts/kanban-schema.v1.ts:457-490` — no task archive field and no typed tags field/table.
+- Current `origin/main` already has `tasks.tags`, making omission from the target declaration a migration-loss hazard.
+
+**Violation**
+
+`REQ-UI-001/002` and internal acceptance consistency. “Archive” cannot be implemented without inventing whether it means cancelled, hidden, or soft-deleted; tag filtering has no frozen storage/query contract.
+
+**Minimal fix**
+
+Either remove task archive/tag acceptance from P1, or add explicit non-lifecycle archival semantics (`archived_at/by/reason`) and a workspace-safe tags model/query contract. Preserve/migrate the current tags column until the selected model is live.
+
+### KCR-014 — MAJOR — Recovery contract states critical rules only in comments and has no owning implementation slice
+
+**Location**
+
+- `contracts/recovery-posture.v1.ts:97-147` — exported JSON Schema validates only local field shapes.
+- `contracts/recovery-posture.v1.ts:150-156` — PITR/WAL, effective RPO, off-cluster, high-assurance minima, and audit rules are comments only.
+- `REQUIREMENTS.md:270-277` — parser rejection of impossible combinations is acceptance-critical.
+- `TASKS.md:75-244` — no bounded slice owns recovery config parsing, override audit, backup/WAL setup, or restore/break-glass evidence.
+
+**Violation**
+
+`REQ-REC-001`. A consumer using the advertised JSON Schema can accept weakened high-assurance values, PITR without WAL, or an impossible RPO. The task plan has no lane accountable for closing that acceptance criterion.
+
+**Minimal fix**
+
+Export a normative `validateRecoveryPostureV1`/schema refinement with machine-testable cross-field checks and add a bounded Infra/recovery slice (serialized if it touches shared config) owning config parsing, override audit, mechanism verification, restore test, and break-glass evidence. Recovery config must continue to expose no authority/gate knobs.
+
+### KCR-015 — MAJOR — Pure Coordinator slice cannot implement two frozen methods without persistence access
+
+**Location**
+
+- `contracts/mechanical-coordinator.v1.ts:259-263` — `explainEligibility` receives only `taskId`, not a structured snapshot.
+- `contracts/mechanical-coordinator.v1.ts:289-293` — `recoverFromPostgres` explicitly reads PostgreSQL.
+- `TASKS.md:145-153` — KBN-200 is a pure engine with no SQL, Drizzle, Gateway, or Valkey.
+- `TASKS.md:157-164` — persistence belongs to coder3/KBN-210.
+
+**Violation**
+
+Charter C and internal consistency. coder4 cannot implement the frozen port in a pure package without crossing coder3’s persistence boundary. If coder3 implements the port instead, KBN-200’s acceptance and ownership are misassigned.
+
+**Minimal fix**
+
+Split the contract into a pure decision engine that receives complete immutable snapshots and a persistence/orchestration service port implemented by KBN-210. Move `recoverFromPostgres` and ID-based loading to the adapter/service; make pure explanation accept a snapshot.
+
+### KCR-016 — MINOR — Health denial code/state pairs are not correlated by type
+
+**Location**
+
+- `contracts/health-state.v1.ts:35-61` — either denial code can pair with either degraded state.
+- `SHARED-CONTRACT.md:188-190` — prose defines `KANBAN_WRITE_UNAVAILABLE` specifically for `write-unavailable`.
+
+**Violation**
+
+Health contract precision. A client can receive a semantically inconsistent authoritative body even after KCR-001’s broader state fix.
+
+**Minimal fix**
+
+Make deliberate denial a two-variant union with exact code/state pairing.
+
+---
+
+## Clean checks / invariants that do hold
+
+The review did **not** find a gap in these areas:
+
+- The canon consistently selects current `mosaicstack/stack` + Drizzle/PostgreSQL and rejects greenfield/Prisma revival.
+- Every artifact states PostgreSQL is the sole writable SOT and Valkey/files are non-authoritative.
+- Generated `TASKS.md`, `mission.json`, and exports are consistently declared read-only and never import sources. KBN-300’s importer is scoped to immutable legacy JSON/Vikunja snapshots, not generated projections.
+- Recovery config exposes recovery fields only; it contains no direct fail-open, SOT, Coordinator-authority, or gate-waiver knob.
+- The Coordinator interface contains no `createTask`, acceptance-edit, gate-waive, certify, merge, release, or provider-close method. `submitForReview` is type-limited to `in_review`, not `done` or `certified`.
+- Certifier is consistently final independent gate with no merge authority.
+- The seven canonical task status values match across requirements, shared prose, schema, and Coordinator’s ready/in-review surfaces.
+- One-active-lease partial uniqueness, no-self-edge, outbox aggregate-revision/event-type uniqueness, optimistic task/project/mission/milestone versions, and N-1 test categories are explicitly present.
+- The file-tree partition is mostly well separated once the ordering/freeze defects in KCR-007 are corrected.
+
+## Required re-review scope
+
+After remediation, re-review at minimum:
+
+1. health/coordinator discriminated unions and mutation-time health proof;
+2. proposal/approval/assignment/lease relational model;
+3. monotonic fencing and composite bindings;
+4. tenant-safe polymorphic relationships;
+5. outage-proposal persistence and commands;
+6. concrete current-main migration map;
+7. corrected dependency graph and exact API/DTO freeze;
+8. recovery validator/owner slice;
+9. all schema and DTO vocabulary alignment.
+
+## Overall verdict
+
+**NO-GO — 8 BLOCKERs must be resolved before the v1 contract is frozen or parallel implementation begins.**