fix(gateway): sanitize raw exceptions in /mcp status + /reload sources (P3 re-review#5 blocker)

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

.gitignore

@@ -8,6 +8,7 @@ coverage
 .env.local
 *.tsbuildinfo
 .pnpm-store
+__pycache__/
 docs/reports/
 
 # Step-CA dev password — real file is gitignored; commit only the .example

.husky/pre-push

@@ -1 +1 @@
-pnpm typecheck && pnpm lint && pnpm format:check
+pnpm preflight && pnpm typecheck && pnpm lint && pnpm format:check

.npmrc

@@ -1,5 +1,5 @@
 @mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
-# Pin the pnpm store to the same path the ci-base image warms (Dockerfile.ci),
-# so the pipeline `pnpm install --prefer-offline` consumes the baked store
-# instead of repopulating a fresh one.
-store-dir=/root/.local/share/pnpm/store
+# HOME resolves to /root in the ci-base image, preserving its warmed-store path.
+# Non-root checkouts use their own HOME. Override without editing this file via
+# NPM_CONFIG_STORE_DIR (pnpm's environment form of the store-dir setting).
+store-dir=${HOME}/.local/share/pnpm/store

.prettierignore

@@ -4,6 +4,15 @@ pnpm-lock.yaml
 **/node_modules
 **/drizzle
 **/.next
+# Python build/test artifacts — same category as node_modules/dist/.next above.
+# Prettier must never scan generated trees; without these a local venv poisons
+# `pnpm format:check` with thousands of third-party files.
+**/venv
+**/__pycache__
+**/.mypy_cache
+**/.pytest_cache
+**/htmlcov
 .claude/
 docs/tess/TASKS.md
 docs/scratchpads/
+packages/mosaic/src/fleet/testdata/documentation-publication-v1/inline-migration-v1.json

.woodpecker/ci.yml

@@ -41,6 +41,32 @@ steps:
       # (Constitution + dispatcher + each RUNTIME.md slice). See DESIGN §7 / R9.
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
+      # Test-membership guard (#1017): also first link of test:framework-shell.
+      # Invoked from BOTH surfaces it audits (F2, PR #1018) — the guard is link
+      # [0] of the pnpm chain, so severing that chain would silence it together
+      # with everything it guards; this direct line keeps one instrument running.
+      - bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh
+
+  # Blocking gate (#791): a framework upgrade must never write or delete an
+  # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
+  # survives a keep-mode reseed byte-identical (with rsync present AND absent —
+  # keep mode is a single cp-based path that must not depend on rsync), and that a
+  # corrupt/empty/missing manifest aborts fail-closed leaving operator files
+  # untouched (B2/B3). The rollback gate proves a mid-sync failure is rolled back
+  # from the pre-update snapshot (B1). The durable-snapshot gate (#791 PR2) proves
+  # the retained, operator-scoped pre-update backup is taken before any mutation
+  # (0700/0600, secret never logged, retention-pruned) and that the post-sync
+  # verify net restores any operator file a manifest bug lets the sync touch. The
+  # migration matrix pins the v2→v3 contract-file semantics. Pure bash, no
+  # node_modules — runs early alongside sanitization.
+  upgrade-guard:
+    image: *node_image
+    commands:
+      - apk add --no-cache bash rsync
+      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh
+      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh
+      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh
+      - bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
 
   typecheck:
     image: *node_image
@@ -50,6 +76,7 @@ steps:
     depends_on:
       - install
       - sanitization
+      - upgrade-guard
 
   # lint, format, and test are independent — run in parallel after typecheck
   lint:
@@ -76,6 +103,12 @@ steps:
       DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
     commands:
       - *enable_pnpm
+      # openssl (#912) is the wake HMAC signer: the digest H1/H2, beacon B12,
+      # and install I8 legs hard-require it in CI. It is baked into ci-base via
+      # Dockerfile.ci, but ci-base only rebuilds on push-to-main/tag — this
+      # `apk add` guarantees openssl is present on PR pipelines too (and is a
+      # fast no-op once the rebuilt image already ships it).
+      - apk add --no-cache openssl
       # postgresql-client (pg_isready) is baked into ci-base.
       # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
       - |

.woodpecker/publish.yml

@@ -1,5 +1,5 @@
 # Build, publish npm packages, and push Docker images
-# Runs only on main branch push/tag
+# Runs on main for stable publishes and on next for integration-line prereleases/images
 
 variables:
   # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
@@ -23,9 +23,21 @@ 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]
+  - branch: [main, next]
     event: [push, manual, tag]
 
 steps:
@@ -103,6 +115,84 @@ 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
@@ -134,8 +224,17 @@ 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" = "main" ]; then
+        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
           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"
@@ -146,7 +245,7 @@ steps:
 
   build-appservice:
     image: gcr.io/kaniko-project/executor:debug
-    when: *image_build_when
+    when: *main_image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username
@@ -172,7 +271,7 @@ steps:
 
   build-web:
     image: gcr.io/kaniko-project/executor:debug
-    when: *image_build_when
+    when: *main_image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username

CLAUDE.md

@@ -26,13 +26,14 @@ pnpm test             # Vitest (all packages)
 pnpm build            # Build all packages
 
 # Database
-pnpm --filter @mosaicstack/db db:push      # Push schema to PG (dev)
-pnpm --filter @mosaicstack/db db:generate  # Generate migrations
-pnpm --filter @mosaicstack/db db:migrate   # Run migrations
+pnpm --filter @mosaicstack/db db:generate  # Offline migration artifact generation only
+# PostgreSQL execution is held until KBN-101-00/-03/-05 land. Do not invoke a runner,
+# init SQL, or Compose PostgreSQL service from this checkout.
 
-# Dev
-docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger
-pnpm --filter @mosaicstack/gateway exec tsx src/main.ts  # Start gateway
+# Dev: local PGlite data-layer work needs no PostgreSQL. Optional local queue service only:
+docker compose up -d valkey
+# Do not start Gateway/Web or root pnpm dev as a local PGlite route: the current unguarded dotenv
+# loader can inherit a daemon PostgreSQL DSN. KBN-101-02 must make that state fail closed first.
 ```
 
 ## Conventions

Dockerfile.ci

@@ -22,10 +22,13 @@
 FROM node:24-alpine
 
 # Native toolchain required to compile node-gyp deps on musl, plus the
-# postgresql-client used by the test step's pg_isready readiness probe. `bash`
-# is baked here too — the sanitization step in ci.yml otherwise does a per-run
-# `apk add bash`.
-RUN apk add --no-cache python3 make g++ postgresql-client bash
+# postgresql-client used by the test step's pg_isready readiness probe. `bash`,
+# `git`, and `jq` are baked here too — framework shell tests and the shipped
+# Codex review wrappers require them without per-run installation in ci.yml.
+# `openssl` (#912) is the non-circular HMAC signer for the wake trust layer:
+# the digest H1/H2, beacon B12, and install I8 legs hard-require it in CI so the
+# §4 G6 evidence comes from an actually-run HMAC leg, not a skipped one.
+RUN apk add --no-cache python3 make g++ postgresql-client bash git jq openssl
 
 # Pin pnpm to the repo's packageManager version via corepack.
 RUN corepack enable && corepack prepare [email protected] --activate

README.md

@@ -30,6 +30,16 @@ 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
@@ -97,7 +107,10 @@ mosaic config path           # Print config file path
 ```bash
 mosaic doctor                # Health audit — detect drift and missing files
 mosaic sync                  # Sync skills from canonical source
-mosaic update                # Check for and install CLI updates
+mosaic skill list            # Audit Claude skill registrations and conflicts
+mosaic skill register <name> # Register one canonical skill with Claude Code
+mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
+mosaic update                # Update CLI/framework and auto-register canonical skills
 mosaic wizard                # Full guided setup wizard
 mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
 mosaic coord init            # Initialize a new orchestration mission
@@ -157,7 +170,12 @@ mosaic storage status
 mosaic storage tier
 mosaic storage export
 mosaic storage import
-mosaic storage migrate
+# Schema migration is unavailable in this release. The current storage wrapper shells
+# directly to `pnpm --filter @mosaicstack/db db:migrate`; it is legacy N-1,
+# uncertified, and MUST NOT be invoked pending KBN-101-02/-03/-06/-08 activation.
+# Future schema migration is non-operative: external bootstrap → TLS/roles → runner
+# --run → runner --verify → readiness. Tier copy uses only the separately held secure
+# migrate-tier route.
 ```
 
 ### Telemetry
@@ -192,33 +210,50 @@ Consent state is persisted in config. Remote upload is a no-op until you run `mo
 git clone [email protected]:mosaicstack/stack.git
 cd stack
 
-# Start infrastructure (Postgres, Valkey, Jaeger)
-docker compose up -d
-
-# Install dependencies
+# Install dependencies. The local tier uses in-process PGlite; leave DATABASE_URL unset.
+# The pnpm store defaults to $HOME/.local/share/pnpm/store. Override it without
+# editing the checkout with NPM_CONFIG_STORE_DIR=$HOME/another-store if needed.
 pnpm install
 
-# Run migrations
-pnpm --filter @mosaicstack/db run db:migrate
+# Verify dependencies and generated state before running source-quality gates.
+# Missing dependencies exit 42; stale/foreign apps/web/.next state exits 43.
+# The web build certifies its exact standalone symlink manifest; added, removed,
+# retargeted, or manifest-only-tampered generated links also exit 43. This detects
+# accidental, independent, stale, and foreign-residue mutation—the class exposed by
+# a five-month-stale .next that produced 19 phantom TS2307 errors.
+# It does NOT defend against a same-UID actor that can rewrite both manifest and
+# marker consistently (CWE-345). RM-59 tracks the required executor/spine-side
+# trust anchor outside worktree authority.
+pnpm preflight
 
-# Start all services in dev mode
-pnpm dev
+# Optional local queue service only. This does not start PostgreSQL.
+docker compose up -d valkey
+
+# The current Gateway/Web local process is held; see docs/guides/dev-guide.md.
+# Do not start it until KBN-101-02 makes inherited dotenv/DSN state fail closed.
 ```
 
-### Infrastructure
+### Held future procedure
 
-Docker Compose provides:
+The checked-in Compose PostgreSQL service mounts legacy initialization SQL and is **not** a
+current PostgreSQL, standalone, or federated developer route. Do not start it with Compose,
+invoke initialization SQL, or treat the planned migrator as currently executable.
 
-| Service               | Port      | Purpose                |
-| --------------------- | --------- | ---------------------- |
-| PostgreSQL (pgvector) | 5433      | Primary database       |
-| Valkey                | 6380      | Task queue + caching   |
-| Jaeger                | 16686     | Distributed tracing UI |
-| OTEL Collector        | 4317/4318 | Telemetry ingestion    |
+**Held future activation procedure — non-operative and no current command authority until KBN-101-00, KBN-101-03, and KBN-101-05
+land:** external bootstrap → TLS/roles → `mosaic-db-migrator --run` →
+`mosaic-db-migrator --verify` → Gateway/Compose readiness. The future deployment artifacts—not
+this README—will provide the reviewed commands and secret-consumer interface.
+
+For local data-layer work, PGlite needs no PostgreSQL service. The optional Compose command above
+starts only Valkey; OTEL Collector and Jaeger may likewise be started individually if needed,
+without starting PostgreSQL. A Gateway/Web local process is not currently a safe PGlite route:
+its unguarded dotenv loader may inherit a daemon PostgreSQL DSN. Do not use root `pnpm dev` or a
+Gateway start command until KBN-101-02 makes that state fail closed.
 
 ### Quality Gates
 
 ```bash
+pnpm preflight               # Checkout/dependency/generated-state validation
 pnpm typecheck               # TypeScript type checking (all packages)
 pnpm lint                    # ESLint (all packages)
 pnpm test                    # Vitest (all packages)
@@ -231,7 +266,7 @@ pnpm format                  # Prettier auto-fix
 Woodpecker CI runs on every push:
 
 - `pnpm install --frozen-lockfile`
-- Database migration against a fresh Postgres
+- **Legacy N-1 CI status only — active, uncertified, and non-authorizing as an operator route:** the checked-in job currently invokes `pnpm --filter @mosaicstack/db run db:migrate` with `DATABASE_URL` against an isolated disposable PostgreSQL CI database. It performs direct DDL in that CI database, is not approved ordinary behavior or an operator route, and remains a known exception pending KBN-101-06 removal/replacement by the certified runner-backed CI path.
 - `pnpm test` (Turbo-orchestrated across all packages)
 
 npm packages are published to the Gitea package registry on main merges.
@@ -336,11 +371,15 @@ 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 --ref v1.0        # Install from a specific git ref
+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 --yes             # Non-interactive, accept all defaults
 bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```
 
+The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
+
 ## Contributing
 
 ```bash

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

@@ -0,0 +1,519 @@
+/**
+ * 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,194 @@
+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',
+        agentConfigId: 'agent-config-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',
+          agentConfigId: 'agent-config-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,9 +1,11 @@
-import { Controller, Get, Inject, UseGuards } from '@nestjs/common';
+import { Controller, Get, Inject, Optional, 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';
 
@@ -14,6 +16,9 @@ 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()
@@ -55,6 +60,14 @@ 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

@@ -12,18 +12,24 @@ type AgentServiceInternals = {
   creating: Map<string, Promise<AgentSession>>;
 };
 
-function makeService(): AgentService {
+function makeService(operatorMemory: unknown = null): AgentService {
   return new AgentService(
-    {} as never,
+    {
+      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,
-    {} 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,
   );
 }
 
@@ -109,6 +115,18 @@ describe('AgentService owner/tenant scope enforcement', () => {
     ).rejects.toBeInstanceOf(ForbiddenException);
     await service.prompt(CONVERSATION_ID, 'owner prompt', OWNER_SCOPE);
     expect(session.piSession.prompt).toHaveBeenCalledWith('owner prompt');
+    await service.prompt(CONVERSATION_ID, '', OWNER_SCOPE, [
+      {
+        id: 'attachment-001',
+        name: 'diagram.png',
+        url: 'https://cdn.example.test/diagram.png',
+        mimeType: 'image/png',
+      },
+    ]);
+    expect(session.piSession.prompt).toHaveBeenLastCalledWith(
+      '\n\n[Untrusted channel attachments]\n' +
+        '{"id":"attachment-001","name":"diagram.png","mimeType":"image/png","url":"https://cdn.example.test/diagram.png"}',
+    );
 
     await expect(service.destroySession(CONVERSATION_ID, FOREIGN_SCOPE)).rejects.toBeInstanceOf(
       ForbiddenException,
@@ -120,6 +138,37 @@ describe('AgentService owner/tenant scope enforcement', () => {
     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();

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

@@ -37,6 +37,7 @@ class RecordingRuntimeProvider implements AgentRuntimeProvider {
   readonly sentMessages: RuntimeMessage[] = [];
   terminateCalls = 0;
   throwAfterSend = false;
+  throwAuthorization = false;
 
   constructor(private readonly supported: RuntimeCapability[]) {}
 
@@ -76,6 +77,9 @@ class RecordingRuntimeProvider implements AgentRuntimeProvider {
   ): 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');
     }
@@ -295,6 +299,23 @@ describe('RuntimeProviderService security boundary', (): void => {
     });
   });
 
+  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> => {

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

@@ -1,5 +1,5 @@
 import { Global, Module } from '@nestjs/common';
-import { AgentRuntimeProviderRegistry } from '@mosaicstack/agent';
+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';
@@ -11,8 +11,8 @@ 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 { TessDurableSessionRepository } from './tess-durable-session.repository.js';
-import { TessDurableSessionService } from './tess-durable-session.service.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';
@@ -20,6 +20,13 @@ 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 { ConnectorLeaseRepository } from './connector-lease.repository.js';
+import {
+  CONNECTOR_LEASE_POLICY,
+  ConnectorLeaseService,
+  DenyConnectorLeasePolicy,
+} from './connector-lease.service.js';
 import {
   AGENT_RUNTIME_PROVIDER_REGISTRY,
   RUNTIME_APPROVAL_VERIFIER,
@@ -28,6 +35,12 @@ import {
   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, LogModule, CommandsModule],
@@ -37,11 +50,18 @@ import {
     RoutingService,
     RoutingEngineService,
     SkillLoaderService,
-    TessDurableSessionRepository,
-    TessDurableSessionService,
+    DurableSessionRepository,
+    DurableSessionService,
+    ConnectorLeaseRepository,
+    DenyConnectorLeasePolicy,
+    {
+      provide: CONNECTOR_LEASE_POLICY,
+      useExisting: DenyConnectorLeasePolicy,
+    },
+    ConnectorLeaseService,
     {
       provide: AGENT_RUNTIME_PROVIDER_REGISTRY,
-      useFactory: (): AgentRuntimeProviderRegistry => new AgentRuntimeProviderRegistry(),
+      useFactory: createGatewayRuntimeProviderRegistry,
     },
     RuntimeProviderAuditService,
     {
@@ -69,8 +89,9 @@ import {
     RoutingService,
     RoutingEngineService,
     SkillLoaderService,
-    TessDurableSessionService,
+    DurableSessionService,
     RuntimeProviderService,
+    ConnectorLeaseService,
     AGENT_RUNTIME_PROVIDER_REGISTRY,
   ],
 })

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

@@ -15,9 +15,11 @@ import {
   type ToolDefinition,
 } from '@mariozechner/pi-coding-agent';
 import type { Brain } from '@mosaicstack/brain';
-import type { Memory } from '@mosaicstack/memory';
+import type { ChannelAttachmentDto } from '@mosaicstack/types';
+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';
@@ -42,6 +44,8 @@ export interface ConversationHistoryMessage {
   role: 'user' | 'assistant' | 'system';
   content: string;
   createdAt: Date;
+  /** Validated, URI-referenced channel attachments preserved on session resume. */
+  attachments?: readonly ChannelAttachmentDto[];
 }
 
 export interface AgentSessionOptions {
@@ -135,6 +139,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,
   ) {}
 
   /**
@@ -146,6 +153,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),
@@ -154,6 +162,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),
@@ -228,6 +239,7 @@ export class AgentService implements OnModuleDestroy {
           isAdmin: options.isAdmin,
           agentConfigId: options.agentConfigId,
           userId: options.userId,
+          tenantId: options.tenantId,
           conversationHistory: options.conversationHistory,
         };
         this.logger.log(
@@ -267,7 +279,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();
@@ -362,7 +382,7 @@ export class AgentService implements OnModuleDestroy {
       sandboxDir,
       allowedTools,
       userId: mergedOptions?.userId,
-      tenantId: this.tenantIdFor(mergedOptions?.userId, mergedOptions?.tenantId),
+      tenantId: sessionTenantId,
       agentConfigId: mergedOptions?.agentConfigId,
       agentName: resolvedAgentName,
       metrics: {
@@ -411,7 +431,7 @@ export class AgentService implements OnModuleDestroy {
     const formatMessage = (msg: ConversationHistoryMessage): string => {
       const roleLabel =
         msg.role === 'user' ? 'User' : msg.role === 'assistant' ? 'Assistant' : 'System';
-      return `**${roleLabel}:** ${msg.content}`;
+      return `**${roleLabel}:** ${msg.content}${this.attachmentContext(msg.attachments ?? [])}`;
     };
 
     const formatted = history.map((msg) => formatMessage(msg));
@@ -470,6 +490,21 @@ export class AgentService implements OnModuleDestroy {
     return result;
   }
 
+  private attachmentContext(attachments: readonly ChannelAttachmentDto[]): string {
+    if (attachments.length === 0) return '';
+    return `\n\n[Untrusted channel attachments]\n${attachments
+      .map((attachment: ChannelAttachmentDto): string =>
+        JSON.stringify({
+          id: attachment.id,
+          name: attachment.name,
+          mimeType: attachment.mimeType,
+          url: attachment.url,
+          ...(attachment.sizeBytes !== undefined ? { sizeBytes: attachment.sizeBytes } : {}),
+        }),
+      )
+      .join('\n')}`;
+  }
+
   private resolveModel(options?: AgentSessionOptions) {
     if (!options?.provider && !options?.modelId) {
       return this.providerService.getDefaultModel() ?? null;
@@ -656,7 +691,19 @@ export class AgentService implements OnModuleDestroy {
     session.channels.delete(channel);
   }
 
-  async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void> {
+  async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void>;
+  async prompt(
+    sessionId: string,
+    message: string,
+    scope: ActorTenantScope,
+    attachments: readonly ChannelAttachmentDto[] | undefined,
+  ): Promise<void>;
+  async prompt(
+    sessionId: string,
+    message: string,
+    scope: ActorTenantScope,
+    attachments: readonly ChannelAttachmentDto[] = [],
+  ): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
@@ -664,12 +711,16 @@ export class AgentService implements OnModuleDestroy {
     this.assertSessionScope(session, scope);
     session.promptCount += 1;
 
+    // Channel attachments are untrusted URI references. Preserve exact,
+    // authenticated metadata for the agent without treating it as authority.
+    const attachmentContext = this.attachmentContext(attachments);
+
     // Prepend session-scoped system override if present (renew TTL on each turn)
-    let effectiveMessage = message;
+    let effectiveMessage = `${message}${attachmentContext}`;
     if (this.systemOverride) {
       const override = await this.systemOverride.get(sessionId, scope);
       if (override) {
-        effectiveMessage = `[System Override]\n${override}\n\n${message}`;
+        effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
         await this.systemOverride.renew(sessionId, scope);
         this.logger.debug(`Applied system override for session ${sessionId}`);
       }

apps/gateway/src/agent/connector-lease.integration.test.ts

@@ -0,0 +1,341 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { Test, type TestingModule } from '@nestjs/testing';
+import {
+  connectorLeaseAuditLog,
+  createPgliteDb,
+  eq,
+  runPgliteMigrations,
+  type DbHandle,
+} from '@mosaicstack/db';
+import type { ConnectorExecutionContext, FencedConnectorAdapter } from '@mosaicstack/types';
+import { DB } from '../database/database.module.js';
+import { ConnectorLeaseRepository } from './connector-lease.repository.js';
+import {
+  CONNECTOR_LEASE_POLICY,
+  ConnectorLeaseService,
+  type ConnectorLeasePolicy,
+  type ConnectorLeasePolicySubject,
+} from './connector-lease.service.js';
+
+const authorize = vi.fn().mockResolvedValue(true);
+const policy: ConnectorLeasePolicy = { authorize };
+const context = {
+  actorScope: { userId: 'operator-a', tenantId: 'tenant-a' },
+  correlationId: 'correlation-acquire',
+};
+
+describe('gateway connector lease fencing integration', (): void => {
+  let dataDir: string;
+  let handle: DbHandle;
+  let moduleRef: TestingModule;
+  let service: ConnectorLeaseService;
+  let repository: ConnectorLeaseRepository;
+
+  beforeAll(async (): Promise<void> => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-07-14T17:00:00.000Z'));
+    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-connector-lease-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    moduleRef = await Test.createTestingModule({
+      providers: [
+        ConnectorLeaseRepository,
+        ConnectorLeaseService,
+        { provide: DB, useValue: handle.db },
+        { provide: CONNECTOR_LEASE_POLICY, useValue: policy },
+      ],
+    }).compile();
+    service = moduleRef.get(ConnectorLeaseService);
+    repository = moduleRef.get(ConnectorLeaseRepository);
+  });
+
+  afterAll(async (): Promise<void> => {
+    vi.useRealTimers();
+    await moduleRef.close();
+    await handle.close();
+    await rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('derives tenant authority at the gateway and validates a grant before side effects', async (): Promise<void> => {
+    const lease = await service.acquire(
+      {
+        logicalAgentId: 'Mos',
+        bindingId: 'operator-chat',
+        connectorId: 'pi-worker-a',
+        scopes: ['runtime.send'],
+        ttlMs: 60_000,
+      },
+      context,
+    );
+    const grant = await service.issueGrant(
+      { lease, scopes: ['runtime.send'], ttlMs: 30_000 },
+      { ...context, correlationId: 'correlation-grant' },
+    );
+    const execute = vi.fn(async (_message: string, leaseContext: ConnectorExecutionContext) => {
+      return leaseContext.leaseEpoch;
+    });
+    const adapter: FencedConnectorAdapter<string, string> = { execute };
+
+    await expect(service.executeGrant(grant, 'runtime.send', 'hello', adapter)).resolves.toBe('1');
+    expect(execute).toHaveBeenCalledOnce();
+    expect(authorize).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: 'grant.issue',
+        requestedScopes: ['runtime.send'],
+        requestedTtlMs: 30_000,
+      }),
+    );
+    expect(execute.mock.calls[0]?.[1]).toMatchObject({
+      identity: { tenantId: 'tenant-a', logicalAgentId: 'mos' },
+      bindingId: 'operator-chat',
+      connectorId: 'pi-worker-a',
+    });
+  });
+
+  it('normalizes lease-derived policy subjects before authorization', async (): Promise<void> => {
+    const lease = await service.acquire(
+      {
+        logicalAgentId: 'mos',
+        bindingId: 'operator-chat-policy',
+        connectorId: 'pi-worker-a',
+        scopes: ['runtime.send'],
+        ttlMs: 60_000,
+      },
+      { ...context, correlationId: 'correlation-policy-setup' },
+    );
+    const aliasedLease = {
+      ...lease,
+      identity: { ...lease.identity, logicalAgentId: ' MOS ' },
+      bindingId: ' Operator-Chat-Policy ',
+      connectorId: ' PI-Worker-A ',
+      scopes: [' Runtime.Send '],
+      leaseEpoch: `00${lease.leaseEpoch}`,
+    };
+
+    await service.heartbeat(aliasedLease, 30_000, {
+      ...context,
+      correlationId: 'correlation-policy-heartbeat',
+    });
+    expect(authorize).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        action: 'lease.heartbeat',
+        logicalAgentId: 'mos',
+        bindingId: 'operator-chat-policy',
+        connectorId: 'pi-worker-a',
+        requestedScopes: ['runtime.send'],
+      }),
+    );
+
+    await service.issueGrant(
+      { lease: aliasedLease, scopes: [' Runtime.Send '], ttlMs: 1_000 },
+      { ...context, correlationId: 'correlation-policy-grant' },
+    );
+    expect(authorize).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        action: 'grant.issue',
+        logicalAgentId: 'mos',
+        bindingId: 'operator-chat-policy',
+        connectorId: 'pi-worker-a',
+        requestedScopes: ['runtime.send'],
+      }),
+    );
+
+    await service.release(aliasedLease, {
+      ...context,
+      correlationId: 'correlation-policy-release',
+    });
+    expect(authorize).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        action: 'lease.release',
+        logicalAgentId: 'mos',
+        bindingId: 'operator-chat-policy',
+        connectorId: 'pi-worker-a',
+        requestedScopes: ['runtime.send'],
+      }),
+    );
+  });
+
+  it('denies stale, forged, expired, cross-tenant, and cross-binding grants before effects', async (): Promise<void> => {
+    const bindingId = 'operator-chat-denials';
+    const current = await service.acquire(
+      {
+        logicalAgentId: 'mos',
+        bindingId,
+        connectorId: 'pi-worker-a',
+        scopes: ['runtime.send'],
+        ttlMs: 60_000,
+      },
+      { ...context, correlationId: 'correlation-denial-setup' },
+    );
+    const stale = await service.issueGrant(
+      { lease: current, scopes: ['runtime.send'], ttlMs: 30_000 },
+      { ...context, correlationId: 'correlation-stale' },
+    );
+    await service.takeover(
+      {
+        logicalAgentId: 'mos',
+        bindingId,
+        connectorId: 'pi-worker-b',
+        scopes: ['runtime.send'],
+        ttlMs: 60_000,
+        expectedEpoch: current.leaseEpoch,
+      },
+      { ...context, correlationId: 'correlation-takeover' },
+    );
+    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
+
+    await expect(service.executeGrant(stale, 'runtime.send', undefined, adapter)).rejects.toThrow();
+
+    const active = await service.current('mos', bindingId, context);
+    if (!active) throw new Error('active lease fixture is unavailable');
+    const grant = await service.issueGrant(
+      { lease: active, scopes: ['runtime.send'], ttlMs: 1_000 },
+      { ...context, correlationId: 'correlation-active' },
+    );
+    await expect(
+      service.executeGrant({ ...grant }, 'runtime.send', undefined, adapter),
+    ).rejects.toThrow();
+    await expect(
+      service.executeGrant(
+        { ...grant, bindingId: 'other-binding' },
+        'runtime.send',
+        undefined,
+        adapter,
+      ),
+    ).rejects.toThrow();
+    await expect(
+      service.issueGrant(
+        { lease: active, scopes: ['runtime.send'], ttlMs: 30_000 },
+        {
+          actorScope: { userId: 'operator-b', tenantId: 'tenant-b' },
+          correlationId: 'correlation-cross-tenant',
+        },
+      ),
+    ).rejects.toThrow();
+    const crossTenantAudit = await handle.db
+      .select()
+      .from(connectorLeaseAuditLog)
+      .where(eq(connectorLeaseAuditLog.correlationId, 'correlation-cross-tenant'));
+    expect(crossTenantAudit).toHaveLength(1);
+    expect(crossTenantAudit[0]).toMatchObject({
+      tenantId: 'tenant-b',
+      logicalAgentId: 'untrusted',
+      bindingId: 'untrusted',
+      connectorId: 'untrusted',
+      reason: 'policy_denied',
+    });
+
+    vi.setSystemTime(new Date('2026-07-14T17:00:02.000Z'));
+    await expect(service.executeGrant(grant, 'runtime.send', undefined, adapter)).rejects.toThrow();
+    expect(adapter.execute).not.toHaveBeenCalled();
+  });
+
+  it('rejects submitted lifecycle scopes that differ from durable authority before policy or mutation', async (): Promise<void> => {
+    authorize.mockResolvedValue(true);
+    const heartbeatLease = await service.acquire(
+      {
+        logicalAgentId: 'mos',
+        bindingId: 'operator-chat-heartbeat-scope',
+        connectorId: 'pi-worker-a',
+        scopes: ['runtime.send'],
+        ttlMs: 60_000,
+      },
+      { ...context, correlationId: 'correlation-heartbeat-scope-setup' },
+    );
+    const releaseLease = await service.acquire(
+      {
+        logicalAgentId: 'mos',
+        bindingId: 'operator-chat-release-scope',
+        connectorId: 'pi-worker-a',
+        scopes: ['runtime.send'],
+        ttlMs: 60_000,
+      },
+      { ...context, correlationId: 'correlation-release-scope-setup' },
+    );
+    const forgedHeartbeat = { ...heartbeatLease, scopes: ['tool.execute'] };
+    const forgedRelease = { ...releaseLease, scopes: ['tool.execute'] };
+
+    authorize.mockImplementation(async (subject: ConnectorLeasePolicySubject) => {
+      return subject.requestedScopes.length === 1 && subject.requestedScopes[0] === 'tool.execute';
+    });
+    authorize.mockClear();
+
+    await expect(
+      service.heartbeat(forgedHeartbeat, 30_000, {
+        ...context,
+        correlationId: 'correlation-heartbeat-scope-forgery',
+      }),
+    ).rejects.toThrow('Connector authority policy denied');
+    await expect(
+      service.release(forgedRelease, {
+        ...context,
+        correlationId: 'correlation-release-scope-forgery',
+      }),
+    ).rejects.toThrow('Connector authority policy denied');
+    expect(authorize).not.toHaveBeenCalled();
+
+    const currentHeartbeat = await repository.findCurrent({
+      identity: heartbeatLease.identity,
+      bindingId: heartbeatLease.bindingId,
+    });
+    const currentRelease = await repository.findCurrent({
+      identity: releaseLease.identity,
+      bindingId: releaseLease.bindingId,
+    });
+    expect(currentHeartbeat).toMatchObject({
+      leaseId: heartbeatLease.leaseId,
+      scopes: ['runtime.send'],
+      heartbeatAt: heartbeatLease.heartbeatAt,
+      expiresAt: heartbeatLease.expiresAt,
+    });
+    expect(currentRelease).toMatchObject({
+      leaseId: releaseLease.leaseId,
+      scopes: ['runtime.send'],
+    });
+    expect(currentRelease?.releasedAt).toBeUndefined();
+
+    const forgedAudits = await handle.db
+      .select()
+      .from(connectorLeaseAuditLog)
+      .where(eq(connectorLeaseAuditLog.correlationId, 'correlation-heartbeat-scope-forgery'));
+    expect(forgedAudits).toHaveLength(1);
+    expect(forgedAudits[0]).toMatchObject({
+      bindingId: heartbeatLease.bindingId,
+      connectorId: heartbeatLease.connectorId,
+      event: 'reject',
+      outcome: 'denied',
+      reason: 'policy_denied',
+    });
+    const forgedReleaseAudits = await handle.db
+      .select()
+      .from(connectorLeaseAuditLog)
+      .where(eq(connectorLeaseAuditLog.correlationId, 'correlation-release-scope-forgery'));
+    expect(forgedReleaseAudits).toHaveLength(1);
+    expect(forgedReleaseAudits[0]).toMatchObject({
+      bindingId: releaseLease.bindingId,
+      connectorId: releaseLease.connectorId,
+      event: 'reject',
+      outcome: 'denied',
+      reason: 'policy_denied',
+    });
+
+    authorize.mockImplementation(async (subject: ConnectorLeasePolicySubject) => {
+      return subject.requestedScopes.length === 1 && subject.requestedScopes[0] === 'runtime.send';
+    });
+    await expect(
+      service.heartbeat(heartbeatLease, 30_000, {
+        ...context,
+        correlationId: 'correlation-heartbeat-scope-canonical',
+      }),
+    ).resolves.toMatchObject({ scopes: ['runtime.send'] });
+    await expect(
+      service.release(releaseLease, {
+        ...context,
+        correlationId: 'correlation-release-scope-canonical',
+      }),
+    ).resolves.toBeUndefined();
+  });
+});

apps/gateway/src/agent/connector-lease.postgres.integration.test.ts

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import {
+  connectorLeaseAuditLog,
+  createDb,
+  eq,
+  logicalAgentConnectorLeases,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { ConnectorLeaseCoordinator } from '@mosaicstack/agent';
+import { ConnectorLeaseRepository } from './connector-lease.repository.js';
+
+const hasPostgres = Boolean(process.env['DATABASE_URL']);
+const tenantId = `lease-test-${randomUUID()}`;
+const identity = { tenantId, logicalAgentId: 'mos' } as const;
+
+describe.skipIf(!hasPostgres)('ConnectorLeaseRepository real PostgreSQL integration', (): void => {
+  let handle: DbHandle;
+
+  beforeAll((): void => {
+    handle = createDb(process.env['DATABASE_URL']);
+  });
+
+  afterAll(async (): Promise<void> => {
+    if (!handle) return;
+    await handle.db
+      .delete(connectorLeaseAuditLog)
+      .where(eq(connectorLeaseAuditLog.tenantId, tenantId));
+    await handle.db
+      .delete(logicalAgentConnectorLeases)
+      .where(eq(logicalAgentConnectorLeases.tenantId, tenantId));
+    await handle.close();
+  });
+
+  it('preserves the exclusive CAS fence across a real pool close/reopen', async (): Promise<void> => {
+    const command = {
+      identity,
+      bindingId: 'operator-chat',
+      scopes: ['runtime.send'],
+      ttlMs: 60_000,
+    } as const;
+    const firstCoordinator = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db));
+    const contenders = await Promise.allSettled([
+      firstCoordinator.acquire({
+        ...command,
+        connectorId: 'connector-a',
+        correlationId: 'postgres-acquire-a',
+      }),
+      firstCoordinator.acquire({
+        ...command,
+        connectorId: 'connector-b',
+        correlationId: 'postgres-acquire-b',
+      }),
+    ]);
+    const acquired = contenders.find((result) => result.status === 'fulfilled');
+    if (!acquired || acquired.status !== 'fulfilled') throw new Error('no lease contender won');
+    expect(contenders.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
+
+    await handle.close();
+    handle = createDb(process.env['DATABASE_URL']);
+    const reopened = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db));
+    const persisted = await reopened.current({ identity, bindingId: 'operator-chat' });
+    expect(persisted).toMatchObject({
+      leaseId: acquired.value.leaseId,
+      leaseEpoch: '1',
+    });
+
+    const takeover = await reopened.takeover({
+      ...command,
+      connectorId: 'connector-c',
+      correlationId: 'postgres-takeover',
+      expectedEpoch: acquired.value.leaseEpoch,
+    });
+    expect(takeover).toMatchObject({ connectorId: 'connector-c', leaseEpoch: '2' });
+  });
+});

apps/gateway/src/agent/connector-lease.repository.test.ts

@@ -0,0 +1,149 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  connectorLeaseAuditLog,
+  createPgliteDb,
+  eq,
+  runPgliteMigrations,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { ConnectorLeaseCoordinator, ConnectorLeaseError } from '@mosaicstack/agent';
+import { ConnectorLeaseRepository } from './connector-lease.repository.js';
+
+const identity = { tenantId: 'tenant-a', logicalAgentId: 'mos' } as const;
+
+function acquireCommand(connectorId: string, correlationId: string) {
+  return {
+    identity,
+    bindingId: 'operator-chat',
+    connectorId,
+    scopes: ['runtime.send', 'tool.execute'],
+    ttlMs: 60_000,
+    correlationId,
+  };
+}
+
+describe('ConnectorLeaseRepository PostgreSQL semantics', (): void => {
+  let dataDir: string;
+  let handle: DbHandle;
+  let now: Date;
+  let coordinator: ConnectorLeaseCoordinator;
+
+  beforeEach(async (): Promise<void> => {
+    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-connector-lease-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    now = new Date('2026-07-14T17:00:00.000Z');
+    coordinator = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db), {
+      now: (): Date => now,
+    });
+  });
+
+  afterEach(async (): Promise<void> => {
+    await handle.close();
+    await rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('allows only one concurrent contender to acquire a binding', async (): Promise<void> => {
+    const outcomes = await Promise.allSettled([
+      coordinator.acquire(acquireCommand('connector-a', 'correlation-a')),
+      coordinator.acquire(acquireCommand('connector-b', 'correlation-b')),
+    ]);
+
+    expect(outcomes.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
+    const rejected = outcomes.find((result) => result.status === 'rejected');
+    expect(rejected).toMatchObject({
+      reason: { code: 'lease_held' } satisfies Partial<ConnectorLeaseError>,
+    });
+  });
+
+  it('uses compare-and-swap takeover and increments the fencing epoch monotonically', async (): Promise<void> => {
+    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
+    const results = await Promise.allSettled([
+      coordinator.takeover({
+        ...acquireCommand('connector-b', 'correlation-b'),
+        expectedEpoch: acquired.leaseEpoch,
+      }),
+      coordinator.takeover({
+        ...acquireCommand('connector-c', 'correlation-c'),
+        expectedEpoch: acquired.leaseEpoch,
+      }),
+    ]);
+    const winner = results.find((result) => result.status === 'fulfilled');
+
+    expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
+    expect(winner?.status === 'fulfilled' ? winner.value.leaseEpoch : null).toBe('2');
+    expect(results.find((result) => result.status === 'rejected')).toMatchObject({
+      reason: { code: 'cas_mismatch' } satisfies Partial<ConnectorLeaseError>,
+    });
+  });
+
+  it('heartbeats and releases only the current connector epoch', async (): Promise<void> => {
+    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
+    now = new Date('2026-07-14T17:00:30.000Z');
+    const renewed = await coordinator.heartbeat({
+      lease: acquired,
+      ttlMs: 120_000,
+      correlationId: 'correlation-renew',
+    });
+    expect(renewed.expiresAt).toBe('2026-07-14T17:02:30.000Z');
+
+    await coordinator.release({ lease: renewed, correlationId: 'correlation-release' });
+    await expect(
+      coordinator.heartbeat({
+        lease: renewed,
+        ttlMs: 120_000,
+        correlationId: 'correlation-stale',
+      }),
+    ).rejects.toMatchObject({ code: 'lease_released' } satisfies Partial<ConnectorLeaseError>);
+  });
+
+  it('survives close/reopen and requires CAS takeover to recover an expired lease', async (): Promise<void> => {
+    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
+    await handle.close();
+
+    now = new Date('2026-07-14T17:02:00.000Z');
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    coordinator = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db), {
+      now: (): Date => now,
+    });
+
+    await expect(
+      coordinator.acquire(acquireCommand('connector-b', 'correlation-plain-acquire')),
+    ).rejects.toMatchObject({ code: 'takeover_required' } satisfies Partial<ConnectorLeaseError>);
+    const recovered = await coordinator.takeover({
+      ...acquireCommand('connector-b', 'correlation-takeover'),
+      expectedEpoch: acquired.leaseEpoch,
+    });
+    expect(recovered).toMatchObject({ connectorId: 'connector-b', leaseEpoch: '2' });
+  });
+
+  it('writes credential-safe lifecycle and rejection audit records', async (): Promise<void> => {
+    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
+    await coordinator.heartbeat({
+      lease: acquired,
+      ttlMs: 60_000,
+      correlationId: 'correlation-renew',
+    });
+    await expect(
+      coordinator.acquire(acquireCommand('connector-b', 'correlation-reject')),
+    ).rejects.toBeInstanceOf(ConnectorLeaseError);
+
+    const rows = await handle.db
+      .select()
+      .from(connectorLeaseAuditLog)
+      .where(eq(connectorLeaseAuditLog.tenantId, identity.tenantId));
+    expect(rows.map((row) => row.event)).toEqual(
+      expect.arrayContaining(['acquire', 'renew', 'reject']),
+    );
+    const serialized = JSON.stringify(rows, (_key: string, value: unknown): unknown =>
+      typeof value === 'bigint' ? value.toString(10) : value,
+    );
+    expect(serialized).not.toContain('tool.execute');
+    expect(serialized).not.toContain('runtime.send');
+    expect(serialized).not.toMatch(/token|secret|credential/i);
+  });
+});

apps/gateway/src/agent/connector-lease.repository.ts

@@ -0,0 +1,354 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  connectorLeaseAuditLog,
+  eq,
+  gt,
+  isNull,
+  logicalAgentConnectorLeases,
+  sql,
+  type Db,
+} from '@mosaicstack/db';
+import { ConnectorLeaseError } from '@mosaicstack/agent';
+import type {
+  ConnectorLease,
+  ConnectorLeaseAcquireMutation,
+  ConnectorLeaseAuditEvent,
+  ConnectorLeaseHeartbeatMutation,
+  ConnectorLeaseRejectReason,
+  ConnectorLeaseReleaseMutation,
+  ConnectorLeaseStore,
+  ConnectorLeaseTakeoverMutation,
+  LogicalAgentBinding,
+} from '@mosaicstack/types';
+import { DB } from '../database/database.module.js';
+
+interface SuccessfulMutation {
+  readonly ok: true;
+  readonly lease: ConnectorLease;
+}
+
+interface FailedMutation {
+  readonly ok: false;
+  readonly reason: ConnectorLeaseRejectReason;
+}
+
+type MutationResult = SuccessfulMutation | FailedMutation;
+
+@Injectable()
+export class ConnectorLeaseRepository implements ConnectorLeaseStore {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async acquire(input: ConnectorLeaseAcquireMutation): Promise<ConnectorLease> {
+    const result: MutationResult = await this.db.transaction(
+      async (tx): Promise<MutationResult> => {
+        const inserted = await tx
+          .insert(logicalAgentConnectorLeases)
+          .values({
+            leaseId: input.leaseId,
+            tenantId: input.identity.tenantId,
+            logicalAgentId: input.identity.logicalAgentId,
+            bindingId: input.bindingId,
+            connectorId: input.connectorId,
+            scopes: [...input.scopes],
+            leaseEpoch: 1n,
+            acquiredAt: new Date(input.now),
+            heartbeatAt: new Date(input.now),
+            expiresAt: new Date(input.expiresAt),
+            updatedAt: new Date(input.now),
+          })
+          .onConflictDoNothing()
+          .returning();
+        const row = inserted[0];
+        if (row) {
+          const lease = toLease(row);
+          await insertAudit(tx, lifecycleAudit(input, lease, 'acquire'));
+          return { ok: true, lease };
+        }
+
+        const current = await findRow(tx, input);
+        if (current && current.expiresAt <= new Date(input.now) && !current.releasedAt) {
+          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
+        }
+        const reason: ConnectorLeaseRejectReason =
+          current && (current.releasedAt || current.expiresAt <= new Date(input.now))
+            ? 'takeover_required'
+            : 'lease_held';
+        await insertAudit(tx, rejectionAudit(input, current ? toLease(current) : null, reason));
+        return { ok: false, reason };
+      },
+    );
+    return unwrap(result);
+  }
+
+  async takeover(input: ConnectorLeaseTakeoverMutation): Promise<ConnectorLease> {
+    const result: MutationResult = await this.db.transaction(
+      async (tx): Promise<MutationResult> => {
+        const current = await findRow(tx, input);
+        if (!current || current.leaseEpoch.toString(10) !== input.expectedEpoch) {
+          await insertAudit(
+            tx,
+            rejectionAudit(input, current ? toLease(current) : null, 'cas_mismatch'),
+          );
+          return { ok: false, reason: 'cas_mismatch' };
+        }
+        if (current.expiresAt <= new Date(input.now) && !current.releasedAt) {
+          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
+        }
+        const updated = await tx
+          .update(logicalAgentConnectorLeases)
+          .set({
+            leaseId: input.leaseId,
+            connectorId: input.connectorId,
+            scopes: [...input.scopes],
+            leaseEpoch: sql`${logicalAgentConnectorLeases.leaseEpoch} + 1`,
+            acquiredAt: new Date(input.now),
+            heartbeatAt: new Date(input.now),
+            expiresAt: new Date(input.expiresAt),
+            releasedAt: null,
+            updatedAt: new Date(input.now),
+          })
+          .where(
+            and(
+              bindingPredicate(input),
+              eq(logicalAgentConnectorLeases.leaseId, current.leaseId),
+              eq(logicalAgentConnectorLeases.leaseEpoch, BigInt(input.expectedEpoch)),
+            ),
+          )
+          .returning();
+        const row = updated[0];
+        if (!row) {
+          await insertAudit(tx, rejectionAudit(input, toLease(current), 'cas_mismatch'));
+          return { ok: false, reason: 'cas_mismatch' };
+        }
+        const lease = toLease(row);
+        await insertAudit(tx, lifecycleAudit(input, lease, 'takeover'));
+        return { ok: true, lease };
+      },
+    );
+    return unwrap(result);
+  }
+
+  async heartbeat(input: ConnectorLeaseHeartbeatMutation): Promise<ConnectorLease> {
+    const result: MutationResult = await this.db.transaction(
+      async (tx): Promise<MutationResult> => {
+        const updated = await tx
+          .update(logicalAgentConnectorLeases)
+          .set({
+            heartbeatAt: new Date(input.now),
+            expiresAt: new Date(input.expiresAt),
+            updatedAt: new Date(input.now),
+          })
+          .where(
+            and(
+              bindingPredicate(input.lease),
+              eq(logicalAgentConnectorLeases.leaseId, input.lease.leaseId),
+              eq(logicalAgentConnectorLeases.connectorId, input.lease.connectorId),
+              eq(logicalAgentConnectorLeases.leaseEpoch, BigInt(input.lease.leaseEpoch)),
+              isNull(logicalAgentConnectorLeases.releasedAt),
+              gt(logicalAgentConnectorLeases.expiresAt, new Date(input.now)),
+            ),
+          )
+          .returning();
+        const row = updated[0];
+        if (row) {
+          const lease = toLease(row);
+          await insertAudit(tx, lifecycleAudit(input, lease, 'renew'));
+          return { ok: true, lease };
+        }
+        const current = await findRow(tx, input.lease);
+        const reason = classifyAuthorityFailure(
+          current ? toLease(current) : null,
+          input.lease,
+          input.now,
+        );
+        if (reason === 'lease_expired' && current) {
+          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
+        }
+        await insertAudit(
+          tx,
+          rejectionAudit(
+            { ...input.lease, correlationId: input.correlationId, now: input.now },
+            current ? toLease(current) : null,
+            reason,
+          ),
+        );
+        return { ok: false, reason };
+      },
+    );
+    return unwrap(result);
+  }
+
+  async release(input: ConnectorLeaseReleaseMutation): Promise<void> {
+    const result: MutationResult = await this.db.transaction(
+      async (tx): Promise<MutationResult> => {
+        const updated = await tx
+          .update(logicalAgentConnectorLeases)
+          .set({
+            releasedAt: new Date(input.now),
+            expiresAt: new Date(input.now),
+            updatedAt: new Date(input.now),
+          })
+          .where(
+            and(
+              bindingPredicate(input.lease),
+              eq(logicalAgentConnectorLeases.leaseId, input.lease.leaseId),
+              eq(logicalAgentConnectorLeases.connectorId, input.lease.connectorId),
+              eq(logicalAgentConnectorLeases.leaseEpoch, BigInt(input.lease.leaseEpoch)),
+              isNull(logicalAgentConnectorLeases.releasedAt),
+              gt(logicalAgentConnectorLeases.expiresAt, new Date(input.now)),
+            ),
+          )
+          .returning();
+        const row = updated[0];
+        if (row) {
+          const lease = toLease(row);
+          await insertAudit(tx, lifecycleAudit(input, lease, 'release'));
+          return { ok: true, lease };
+        }
+        const current = await findRow(tx, input.lease);
+        const reason = classifyAuthorityFailure(
+          current ? toLease(current) : null,
+          input.lease,
+          input.now,
+        );
+        if (reason === 'lease_expired' && current) {
+          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
+        }
+        await insertAudit(
+          tx,
+          rejectionAudit(
+            { ...input.lease, correlationId: input.correlationId, now: input.now },
+            current ? toLease(current) : null,
+            reason,
+          ),
+        );
+        return { ok: false, reason };
+      },
+    );
+    unwrap(result);
+  }
+
+  async findCurrent(binding: LogicalAgentBinding): Promise<ConnectorLease | null> {
+    const row = await findRow(this.db, binding);
+    return row ? toLease(row) : null;
+  }
+
+  async recordAudit(event: ConnectorLeaseAuditEvent): Promise<void> {
+    await insertAudit(this.db, event);
+  }
+}
+
+function unwrap(result: MutationResult): ConnectorLease {
+  if (!result.ok) throw new ConnectorLeaseError(result.reason, safeErrorMessage(result.reason));
+  return result.lease;
+}
+
+function safeErrorMessage(reason: ConnectorLeaseRejectReason): string {
+  return `Connector lease mutation denied: ${reason}`;
+}
+
+function bindingPredicate(binding: LogicalAgentBinding) {
+  return and(
+    eq(logicalAgentConnectorLeases.tenantId, binding.identity.tenantId),
+    eq(logicalAgentConnectorLeases.logicalAgentId, binding.identity.logicalAgentId),
+    eq(logicalAgentConnectorLeases.bindingId, binding.bindingId),
+  );
+}
+
+async function findRow(
+  db: Pick<Db, 'select'>,
+  binding: LogicalAgentBinding,
+): Promise<typeof logicalAgentConnectorLeases.$inferSelect | null> {
+  const rows = await db
+    .select()
+    .from(logicalAgentConnectorLeases)
+    .where(bindingPredicate(binding))
+    .limit(1);
+  return rows[0] ?? null;
+}
+
+function toLease(row: typeof logicalAgentConnectorLeases.$inferSelect): ConnectorLease {
+  return Object.freeze({
+    identity: Object.freeze({ tenantId: row.tenantId, logicalAgentId: row.logicalAgentId }),
+    bindingId: row.bindingId,
+    leaseId: row.leaseId,
+    connectorId: row.connectorId,
+    scopes: Object.freeze([...row.scopes]),
+    leaseEpoch: row.leaseEpoch.toString(10),
+    acquiredAt: row.acquiredAt.toISOString(),
+    heartbeatAt: row.heartbeatAt.toISOString(),
+    expiresAt: row.expiresAt.toISOString(),
+    ...(row.releasedAt ? { releasedAt: row.releasedAt.toISOString() } : {}),
+  });
+}
+
+function classifyAuthorityFailure(
+  current: ConnectorLease | null,
+  claimed: ConnectorLease,
+  now: string,
+): ConnectorLeaseRejectReason {
+  if (!current) return 'lease_missing';
+  if (current.releasedAt) return 'lease_released';
+  if (new Date(current.expiresAt) <= new Date(now)) return 'lease_expired';
+  if (current.leaseEpoch !== claimed.leaseEpoch) return 'stale_epoch';
+  return 'connector_mismatch';
+}
+
+function lifecycleAudit(
+  input: { readonly correlationId: string; readonly now: string },
+  lease: ConnectorLease,
+  event: Exclude<ConnectorLeaseAuditEvent['event'], 'reject'>,
+): ConnectorLeaseAuditEvent {
+  return {
+    identity: lease.identity,
+    bindingId: lease.bindingId,
+    connectorId: lease.connectorId,
+    leaseId: lease.leaseId,
+    leaseEpoch: lease.leaseEpoch,
+    event,
+    outcome: 'succeeded',
+    correlationId: input.correlationId,
+    occurredAt: input.now,
+  };
+}
+
+function rejectionAudit(
+  input: {
+    readonly identity: ConnectorLease['identity'];
+    readonly bindingId: string;
+    readonly connectorId: string;
+    readonly correlationId: string;
+    readonly now: string;
+  },
+  current: ConnectorLease | null,
+  reason: ConnectorLeaseRejectReason,
+): ConnectorLeaseAuditEvent {
+  return {
+    identity: input.identity,
+    bindingId: input.bindingId,
+    connectorId: input.connectorId,
+    event: 'reject',
+    outcome: 'denied',
+    correlationId: input.correlationId,
+    occurredAt: input.now,
+    ...(current ? { leaseId: current.leaseId, leaseEpoch: current.leaseEpoch } : {}),
+    reason,
+  };
+}
+
+async function insertAudit(db: Pick<Db, 'insert'>, event: ConnectorLeaseAuditEvent): Promise<void> {
+  await db.insert(connectorLeaseAuditLog).values({
+    tenantId: event.identity.tenantId,
+    logicalAgentId: event.identity.logicalAgentId,
+    bindingId: event.bindingId,
+    connectorId: event.connectorId,
+    ...(event.leaseId ? { leaseId: event.leaseId } : {}),
+    ...(event.leaseEpoch ? { leaseEpoch: BigInt(event.leaseEpoch) } : {}),
+    event: event.event,
+    outcome: event.outcome,
+    ...(event.reason ? { reason: event.reason } : {}),
+    correlationId: event.correlationId,
+    occurredAt: new Date(event.occurredAt),
+  });
+}

apps/gateway/src/agent/connector-lease.service.ts

@@ -0,0 +1,285 @@
+import { ForbiddenException, Inject, Injectable } from '@nestjs/common';
+import { ConnectorLeaseCoordinator, normalizeConnectorLease } from '@mosaicstack/agent';
+import {
+  normalizeConnectorId,
+  normalizeConnectorScopes,
+  normalizeCorrelationId,
+  normalizeLogicalAgentIdentity,
+  normalizeLogicalBindingId,
+  type AcquireConnectorLeaseInput,
+  type ConnectorExecutionGrant,
+  type ConnectorLease,
+  type ConnectorLeaseAuditEvent,
+  type FencedConnectorAdapter,
+} from '@mosaicstack/types';
+import type { ActorTenantScope } from '../auth/session-scope.js';
+import { ConnectorLeaseRepository } from './connector-lease.repository.js';
+
+export const CONNECTOR_LEASE_POLICY = Symbol('CONNECTOR_LEASE_POLICY');
+
+export type ConnectorLeasePolicyAction =
+  | 'lease.acquire'
+  | 'lease.takeover'
+  | 'lease.heartbeat'
+  | 'lease.release'
+  | 'lease.read'
+  | 'grant.issue';
+
+export interface ConnectorLeaseRequestContext {
+  readonly actorScope: ActorTenantScope;
+  readonly correlationId: string;
+}
+
+export interface GatewayConnectorLeaseRequest {
+  readonly logicalAgentId: string;
+  readonly bindingId: string;
+  readonly connectorId: string;
+  readonly scopes: readonly string[];
+  readonly ttlMs: number;
+}
+
+export interface GatewayConnectorLeaseTakeoverRequest extends GatewayConnectorLeaseRequest {
+  readonly expectedEpoch: string;
+}
+
+export interface GatewayConnectorGrantRequest {
+  readonly lease: ConnectorLease;
+  readonly scopes: readonly string[];
+  readonly ttlMs: number;
+}
+
+export interface ConnectorLeasePolicySubject {
+  readonly action: ConnectorLeasePolicyAction;
+  readonly actorId: string;
+  readonly tenantId: string;
+  readonly logicalAgentId: string;
+  readonly bindingId: string;
+  readonly connectorId: string;
+  readonly requestedScopes: readonly string[];
+  readonly requestedTtlMs: number | null;
+}
+
+export interface ConnectorLeasePolicy {
+  authorize(subject: ConnectorLeasePolicySubject): Promise<boolean>;
+}
+
+/** M1 has no concrete cutover policy: unconfigured production use fails closed. */
+@Injectable()
+export class DenyConnectorLeasePolicy implements ConnectorLeasePolicy {
+  async authorize(_subject: ConnectorLeasePolicySubject): Promise<boolean> {
+    return false;
+  }
+}
+
+/** Gateway-owned policy surface for durable connector authority and fenced effects. */
+@Injectable()
+export class ConnectorLeaseService {
+  private readonly coordinator: ConnectorLeaseCoordinator;
+
+  constructor(
+    @Inject(ConnectorLeaseRepository) private readonly repository: ConnectorLeaseRepository,
+    @Inject(CONNECTOR_LEASE_POLICY) private readonly policy: ConnectorLeasePolicy,
+  ) {
+    this.coordinator = new ConnectorLeaseCoordinator(repository);
+  }
+
+  async acquire(
+    request: GatewayConnectorLeaseRequest,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<ConnectorLease> {
+    const command = this.command(request, context);
+    await this.assertPolicy('lease.acquire', command, context, command.scopes, command.ttlMs);
+    return this.coordinator.acquire({ ...command, correlationId: this.correlation(context) });
+  }
+
+  async takeover(
+    request: GatewayConnectorLeaseTakeoverRequest,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<ConnectorLease> {
+    const command = this.command(request, context);
+    await this.assertPolicy('lease.takeover', command, context, command.scopes, command.ttlMs);
+    return this.coordinator.takeover({
+      ...command,
+      expectedEpoch: request.expectedEpoch,
+      correlationId: this.correlation(context),
+    });
+  }
+
+  async heartbeat(
+    lease: ConnectorLease,
+    ttlMs: number,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<ConnectorLease> {
+    const normalizedLease = normalizeConnectorLease(lease);
+    const durableLease = await this.durableLifecycleLease(normalizedLease, context);
+    await this.assertPolicy('lease.heartbeat', durableLease, context, durableLease.scopes, ttlMs);
+    return this.coordinator.heartbeat({
+      lease: durableLease,
+      ttlMs,
+      correlationId: this.correlation(context),
+    });
+  }
+
+  async release(lease: ConnectorLease, context: ConnectorLeaseRequestContext): Promise<void> {
+    const normalizedLease = normalizeConnectorLease(lease);
+    const durableLease = await this.durableLifecycleLease(normalizedLease, context);
+    await this.assertPolicy('lease.release', durableLease, context, durableLease.scopes, null);
+    await this.coordinator.release({
+      lease: durableLease,
+      correlationId: this.correlation(context),
+    });
+  }
+
+  async current(
+    logicalAgentId: string,
+    bindingId: string,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<ConnectorLease | null> {
+    const binding = {
+      identity: normalizeLogicalAgentIdentity({
+        tenantId: context.actorScope.tenantId,
+        logicalAgentId,
+      }),
+      bindingId: normalizeLogicalBindingId(bindingId),
+      connectorId: 'gateway',
+    };
+    await this.assertPolicy('lease.read', binding, context, [], null);
+    return this.coordinator.current(binding);
+  }
+
+  async issueGrant(
+    request: GatewayConnectorGrantRequest,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<ConnectorExecutionGrant> {
+    const lease = normalizeConnectorLease(request.lease);
+    await this.assertTenant(lease, context);
+    const scopes = normalizeConnectorScopes(request.scopes);
+    await this.assertPolicy('grant.issue', lease, context, scopes, request.ttlMs);
+    return this.coordinator.issueGrant({
+      lease,
+      scopes,
+      ttlMs: request.ttlMs,
+      correlationId: this.correlation(context),
+    });
+  }
+
+  async executeGrant<TInput, TOutput>(
+    grant: ConnectorExecutionGrant,
+    requiredScope: string,
+    input: TInput,
+    adapter: FencedConnectorAdapter<TInput, TOutput>,
+  ): Promise<TOutput> {
+    return this.coordinator.executeGrant(grant, requiredScope, input, adapter);
+  }
+
+  private command(
+    request: GatewayConnectorLeaseRequest,
+    context: ConnectorLeaseRequestContext,
+  ): Omit<AcquireConnectorLeaseInput, 'correlationId'> {
+    return {
+      identity: normalizeLogicalAgentIdentity({
+        tenantId: context.actorScope.tenantId,
+        logicalAgentId: request.logicalAgentId,
+      }),
+      bindingId: normalizeLogicalBindingId(request.bindingId),
+      connectorId: normalizeConnectorId(request.connectorId),
+      scopes: normalizeConnectorScopes(request.scopes),
+      ttlMs: request.ttlMs,
+    };
+  }
+
+  private async assertTenant(
+    lease: Pick<ConnectorLease, 'identity' | 'bindingId' | 'connectorId'>,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<void> {
+    if (lease.identity.tenantId !== context.actorScope.tenantId) {
+      await this.recordPolicyDenial(
+        {
+          identity: {
+            tenantId: context.actorScope.tenantId,
+            logicalAgentId: 'untrusted',
+          },
+          bindingId: 'untrusted',
+          connectorId: 'untrusted',
+        },
+        context,
+      );
+      throw new ForbiddenException('Connector authority tenant scope denied');
+    }
+  }
+
+  private async durableLifecycleLease(
+    submittedLease: ConnectorLease,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<ConnectorLease> {
+    await this.assertTenant(submittedLease, context);
+    const durableLease = await this.coordinator.current(submittedLease);
+    if (!durableLease || !hasSameLifecycleAuthority(submittedLease, durableLease)) {
+      await this.recordPolicyDenial(durableLease ?? submittedLease, context);
+      throw new ForbiddenException('Connector authority policy denied');
+    }
+    return durableLease;
+  }
+
+  private async assertPolicy(
+    action: ConnectorLeasePolicyAction,
+    subject: Pick<ConnectorLease, 'identity' | 'bindingId' | 'connectorId'>,
+    context: ConnectorLeaseRequestContext,
+    requestedScopes: readonly string[],
+    requestedTtlMs: number | null,
+  ): Promise<void> {
+    const allowed = await this.policy.authorize({
+      action,
+      actorId: context.actorScope.userId,
+      tenantId: subject.identity.tenantId,
+      logicalAgentId: subject.identity.logicalAgentId,
+      bindingId: subject.bindingId,
+      connectorId: subject.connectorId,
+      requestedScopes: Object.freeze([...requestedScopes]),
+      requestedTtlMs,
+    });
+    if (!allowed) {
+      await this.recordPolicyDenial(subject, context);
+      throw new ForbiddenException('Connector authority policy denied');
+    }
+  }
+
+  private async recordPolicyDenial(
+    subject: Pick<ConnectorLease, 'identity' | 'bindingId' | 'connectorId'>,
+    context: ConnectorLeaseRequestContext,
+  ): Promise<void> {
+    const event: ConnectorLeaseAuditEvent = {
+      identity: subject.identity,
+      bindingId: subject.bindingId,
+      connectorId: subject.connectorId,
+      event: 'reject',
+      outcome: 'denied',
+      reason: 'policy_denied',
+      correlationId: this.correlation(context),
+      occurredAt: new Date().toISOString(),
+    };
+    await this.repository.recordAudit(event);
+  }
+
+  private correlation(context: ConnectorLeaseRequestContext): string {
+    return normalizeCorrelationId(context.correlationId);
+  }
+}
+
+function hasSameLifecycleAuthority(
+  submittedLease: ConnectorLease,
+  durableLease: ConnectorLease,
+): boolean {
+  return (
+    submittedLease.identity.tenantId === durableLease.identity.tenantId &&
+    submittedLease.identity.logicalAgentId === durableLease.identity.logicalAgentId &&
+    submittedLease.bindingId === durableLease.bindingId &&
+    submittedLease.leaseId === durableLease.leaseId &&
+    submittedLease.connectorId === durableLease.connectorId &&
+    submittedLease.leaseEpoch === durableLease.leaseEpoch &&
+    submittedLease.scopes.length === durableLease.scopes.length &&
+    submittedLease.scopes.every((scope: string, index: number): boolean => {
+      return scope === durableLease.scopes[index];
+    })
+  );
+}

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

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

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

@@ -6,8 +6,8 @@ import { eq, sql, interactionCheckpoints, interactionInbox } from '@mosaicstack/
 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 { TessDurableSessionRepository } from './tess-durable-session.repository.js';
-import { TessDurableSessionService } from './tess-durable-session.service.js';
+import { DurableSessionRepository } from './durable-session.repository.js';
+import { DurableSessionService } from './durable-session.service.js';
 
 const IDENTITY: DurableSessionIdentity = {
   agentName: 'Nova',
@@ -18,7 +18,7 @@ const IDENTITY: DurableSessionIdentity = {
   runtimeSessionId: 'nova',
 };
 
-describe('TessDurableSessionRepository', () => {
+describe('DurableSessionRepository', () => {
   let dataDir: string | undefined;
   let handle: DbHandle;
   let previousAuthSecret: string | undefined;
@@ -48,9 +48,7 @@ describe('TessDurableSessionRepository', () => {
   });
 
   it('survives a full PGlite close/reopen mid-session without duplicate inbox or outbox side effects', async () => {
-    const beforeRestart = new DurableSessionCoordinator(
-      new TessDurableSessionRepository(handle.db),
-    );
+    const beforeRestart = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
     await beforeRestart.create(IDENTITY);
     await beforeRestart.receive({
       sessionId: IDENTITY.sessionId,
@@ -92,7 +90,7 @@ describe('TessDurableSessionRepository', () => {
     await handle.close();
     handle = createPgliteDb(dataDir!);
 
-    const afterRestart = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    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[] = [];
@@ -120,7 +118,7 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('redacts sensitive durable payloads before persistence', async () => {
-    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
     await coordinator.create(IDENTITY);
     await coordinator.receive({
       sessionId: IDENTITY.sessionId,
@@ -157,7 +155,7 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('fails closed when the configured idempotency secret is unavailable', async () => {
-    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    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'];
@@ -177,7 +175,7 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('uses keyed pre-redaction digests to reject distinct sensitive checkpoint payloads', async () => {
-    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
     await coordinator.create(IDENTITY);
     const input = {
       sessionId: IDENTITY.sessionId,
@@ -227,7 +225,7 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('rejects distinct sensitive inbox and outbox payloads under reused idempotency keys', async () => {
-    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
     await coordinator.create(IDENTITY);
     const inbox = {
       sessionId: IDENTITY.sessionId,
@@ -255,7 +253,7 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('rejects database inbox and outbox idempotency-key conflicts', async () => {
-    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    const coordinator = new DurableSessionCoordinator(new DurableSessionRepository(handle.db));
     await coordinator.create(IDENTITY);
     await coordinator.receive({
       sessionId: IDENTITY.sessionId,
@@ -293,10 +291,10 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('does not requeue a live outbox claim during a normal scoped dispatch', async () => {
-    const repository = new TessDurableSessionRepository(handle.db);
+    const repository = new DurableSessionRepository(handle.db);
     const coordinator = new DurableSessionCoordinator(repository);
     const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
-    const service = new TessDurableSessionService(repository, runtimeProviders as never);
+    const service = new DurableSessionService(repository, runtimeProviders as never);
     const input = {
       sessionId: IDENTITY.sessionId,
       idempotencyKey: 'live-effect',
@@ -333,10 +331,10 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('rejects an outbox correlation mismatch before claiming the pending effect', async () => {
-    const repository = new TessDurableSessionRepository(handle.db);
+    const repository = new DurableSessionRepository(handle.db);
     const coordinator = new DurableSessionCoordinator(repository);
     const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
-    const service = new TessDurableSessionService(repository, runtimeProviders as never);
+    const service = new DurableSessionService(repository, runtimeProviders as never);
     const input = {
       sessionId: IDENTITY.sessionId,
       idempotencyKey: 'mismatch-effect',
@@ -366,10 +364,10 @@ describe('TessDurableSessionRepository', () => {
   }, 30_000);
 
   it('dispatches only the outbox record bound to the supplied correlation and channel', async () => {
-    const repository = new TessDurableSessionRepository(handle.db);
+    const repository = new DurableSessionRepository(handle.db);
     const coordinator = new DurableSessionCoordinator(repository);
     const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
-    const service = new TessDurableSessionService(repository, runtimeProviders as never);
+    const service = new DurableSessionService(repository, runtimeProviders as never);
     const first = {
       sessionId: IDENTITY.sessionId,
       idempotencyKey: 'scoped-effect-one',

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

@@ -33,7 +33,7 @@ import type {
 import { DB } from '../database/database.module.js';
 
 @Injectable()
-export class TessDurableSessionRepository implements DurableSessionStore {
+export class DurableSessionRepository implements DurableSessionStore {
   constructor(@Inject(DB) private readonly db: Db) {}
 
   async create(identity: DurableSessionIdentity): Promise<void> {
@@ -50,8 +50,19 @@ export class TessDurableSessionRepository implements DurableSessionStore {
       .onConflictDoNothing();
 
     const existing = await this.session(identity.sessionId);
-    if (!existing || !sameIdentity(existing, identity)) {
-      throw new Error(`Durable Tess session identity conflict: ${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));
     }
   }
 
@@ -124,13 +135,13 @@ export class TessDurableSessionRepository implements DurableSessionStore {
         ),
       )
       .limit(1);
-    if (!existing[0]) throw new Error(`Durable Tess inbox enqueue failed: ${input.idempotencyKey}`);
+    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 Tess inbox idempotency conflict: ${input.idempotencyKey}`);
+      throw new Error(`Durable inbox idempotency conflict: ${input.idempotencyKey}`);
     }
     return { accepted: false, status: entry.status };
   }
@@ -213,14 +224,13 @@ export class TessDurableSessionRepository implements DurableSessionStore {
         ),
       )
       .limit(1);
-    if (!existing[0])
-      throw new Error(`Durable Tess outbox enqueue failed: ${input.idempotencyKey}`);
+    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 Tess outbox idempotency conflict: ${input.idempotencyKey}`);
+      throw new Error(`Durable outbox idempotency conflict: ${input.idempotencyKey}`);
     }
     return { accepted: false, status: entry.status };
   }
@@ -327,7 +337,7 @@ export class TessDurableSessionRepository implements DurableSessionStore {
       !sameCheckpoint(toCheckpoint(existing[0]), checkpoint) ||
       !matchesCheckpointDigest(existing[0].contentDigest, digest)
     ) {
-      throw new Error(`Durable Tess checkpoint identity conflict: ${input.checkpointId}`);
+      throw new Error(`Durable checkpoint identity conflict: ${input.checkpointId}`);
     }
   }
 
@@ -349,7 +359,7 @@ export class TessDurableSessionRepository implements DurableSessionStore {
   async handoff(input: DurableHandoffInput): Promise<void> {
     const checkpoint = await this.findCheckpoint(input.sessionId, input.checkpointId);
     if (!checkpoint) {
-      throw new Error(`Durable Tess handoff checkpoint is unavailable: ${input.checkpointId}`);
+      throw new Error(`Durable handoff checkpoint is unavailable: ${input.checkpointId}`);
     }
     const inserted = await this.db
       .insert(interactionHandoffs)
@@ -360,7 +370,7 @@ export class TessDurableSessionRepository implements DurableSessionStore {
 
     const existing = await this.findHandoff(input.handoffId);
     if (!existing || !sameHandoff(existing, input)) {
-      throw new Error(`Durable Tess handoff identity conflict: ${input.handoffId}`);
+      throw new Error(`Durable handoff identity conflict: ${input.handoffId}`);
     }
   }
 
@@ -427,14 +437,12 @@ function matchesCheckpointDigest(stored: string, digest: string): boolean {
   return stored === digest;
 }
 
-function sameIdentity(left: DurableSessionIdentity, right: DurableSessionIdentity): boolean {
+function sameEnrollmentScope(left: DurableSessionIdentity, right: DurableSessionIdentity): boolean {
   return (
     left.agentName === right.agentName &&
     left.sessionId === right.sessionId &&
     left.tenantId === right.tenantId &&
-    left.ownerId === right.ownerId &&
-    left.providerId === right.providerId &&
-    left.runtimeSessionId === right.runtimeSessionId
+    left.ownerId === right.ownerId
   );
 }
 

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

@@ -1,29 +1,43 @@
 import { ForbiddenException, Inject, Injectable } from '@nestjs/common';
-import { DurableSessionCoordinator } from '@mosaicstack/agent';
-import type { TessProviderOutboxDto } from './tess-durable-session.dto.js';
-import { TessDurableSessionRepository } from './tess-durable-session.repository.js';
+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 Tess state machine. It deliberately
+ * 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 TessDurableSessionService {
+export class DurableSessionService {
   private readonly coordinator: DurableSessionCoordinator;
 
   constructor(
-    @Inject(TessDurableSessionRepository) repository: TessDurableSessionRepository,
+    @Inject(DurableSessionRepository) repository: DurableSessionRepository,
     @Inject(RuntimeProviderService) private readonly runtimeProviders: RuntimeProviderService,
   ) {
     this.coordinator = new DurableSessionCoordinator(repository);
   }
 
-  async queueProviderSend(input: TessProviderOutboxDto): Promise<void> {
+  /** 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({
@@ -36,9 +50,9 @@ export class TessDurableSessionService {
     });
   }
 
-  async dispatchProviderOutbox(sessionId: string, input: TessProviderOutboxDto): Promise<void> {
+  async dispatchProviderOutbox(sessionId: string, input: ProviderOutboxDto): Promise<void> {
     if (sessionId !== input.sessionId) {
-      throw new ForbiddenException('Durable Tess outbox session mismatch');
+      throw new ForbiddenException('Durable outbox session mismatch');
     }
     const snapshot = await this.coordinator.snapshot(sessionId);
     this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
@@ -78,7 +92,7 @@ export class TessDurableSessionService {
   }
 
   /** Startup/recovery-only path; normal queue/dispatch methods never requeue live work. */
-  async recoverProviderSession(sessionId: string, input: TessProviderOutboxDto): Promise<void> {
+  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);
@@ -86,24 +100,24 @@ export class TessDurableSessionService {
 
   private assertOutboxScope(
     entry: { kind: string; correlationId: string; channelId: string },
-    input: TessProviderOutboxDto,
+    input: ProviderOutboxDto,
   ): void {
     if (
       entry.kind !== 'provider.send' ||
       entry.correlationId !== input.correlationId ||
       entry.channelId !== input.context.channelId
     ) {
-      throw new ForbiddenException('Durable Tess outbox scope or correlation mismatch');
+      throw new ForbiddenException('Durable outbox scope or correlation mismatch');
     }
   }
 
-  private assertScope(ownerId: string, tenantId: string, input: TessProviderOutboxDto): void {
+  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 Tess session scope or correlation mismatch');
+      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

@@ -1,9 +1,31 @@
+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';
@@ -21,6 +43,32 @@ describe('InteractionController', (): void => {
     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);
@@ -30,6 +78,36 @@ describe('InteractionController', (): void => {
     );
   });
 
+  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);
@@ -39,6 +117,121 @@ describe('InteractionController', (): void => {
     ).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) };

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

@@ -4,17 +4,21 @@ import {
   ForbiddenException,
   Get,
   Headers,
+  Sse,
   Inject,
   Param,
   Post,
   Query,
   UseGuards,
+  UseFilters,
 } from '@nestjs/common';
-import type { RuntimeAttachMode } from '@mosaicstack/types';
+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 { TessDurableSessionService } from './tess-durable-session.service.js';
+import { DurableSessionService } from './durable-session.service.js';
+import { RuntimeApprovalDeniedFilter } from './runtime-approval-denied.filter.js';
 import {
   RuntimeProviderService,
   type RuntimeProviderRequestContext,
@@ -26,10 +30,11 @@ import {
  */
 @Controller('api/interaction/:agentName')
 @UseGuards(AuthGuard)
+@UseFilters(RuntimeApprovalDeniedFilter)
 export class InteractionController {
   constructor(
     @Inject(RuntimeProviderService) private readonly runtime: RuntimeProviderService,
-    @Inject(TessDurableSessionService) private readonly durable: TessDurableSessionService,
+    @Inject(DurableSessionService) private readonly durable: DurableSessionService,
   ) {}
 
   @Get('sessions')
@@ -46,6 +51,20 @@ export class InteractionController {
     );
   }
 
+  @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,
@@ -60,6 +79,41 @@ export class InteractionController {
     );
   }
 
+  /**
+   * 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,
@@ -84,6 +138,53 @@ export class InteractionController {
     );
   }
 
+  @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,

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

@@ -17,6 +17,8 @@ import type {
   RuntimeSession,
   RuntimeSessionTree,
   RuntimeStreamEvent,
+  TransitionalCapabilityInventoryEntry,
+  TransitionalCapabilityInventoryProvider,
 } from '@mosaicstack/types';
 import type { ActorTenantScope } from '../auth/session-scope.js';
 import { LOG_SERVICE } from '../log/log.tokens.js';
@@ -28,7 +30,8 @@ export const RUNTIME_APPROVAL_VERIFIER = Symbol('RUNTIME_APPROVAL_VERIFIER');
 export type RuntimeProviderOperation =
   | RuntimeCapability
   | 'runtime.capabilities'
-  | 'runtime.health';
+  | 'runtime.health'
+  | 'runtime.transitional-capabilities';
 export type RuntimeProviderAuditOutcome = 'requested' | 'succeeded' | 'denied' | 'failed';
 
 /** Trusted server-side context only; it intentionally excludes client-provided identity fields. */
@@ -71,13 +74,22 @@ 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;
 }
 
-class RuntimeApprovalDeniedError extends Error {
+export class RuntimeApprovalDeniedError extends Error {
   constructor() {
     super('Runtime termination approval denied');
   }
@@ -151,6 +163,25 @@ export class RuntimeProviderService {
     );
   }
 
+  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,
@@ -301,7 +332,7 @@ export class RuntimeProviderService {
       return result;
     } catch (error: unknown) {
       const durationMs = Date.now() - startedAt;
-      if (invocationStarted && !(error instanceof RuntimeApprovalDeniedError)) {
+      if (invocationStarted && !this.isAuthorizationDenied(error)) {
         await this.recordFailure(providerId, operation, scope, resourceId, durationMs);
       } else {
         await this.record(
@@ -360,6 +391,17 @@ export class RuntimeProviderService {
     }
   }
 
+  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);

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/chat/chat.dto.ts

@@ -1,3 +1,4 @@
+import type { ChannelAttachmentDto } from '@mosaicstack/types';
 import { IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
 
 export class ChatRequestDto {
@@ -32,4 +33,7 @@ export class ChatSocketMessageDto {
   @IsOptional()
   @IsUUID()
   agentId?: string;
+
+  /** Validated channel attachment references; binary content is not embedded. */
+  attachments?: readonly ChannelAttachmentDto[];
 }

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

@@ -4,6 +4,10 @@ import { ChatGateway } from './chat.gateway.js';
 const CONVERSATION_ID = 'conversation-1';
 const CANARY = 'sk_canary12345678';
 
+function clientConversationKey(clientId: string, conversationId: string): string {
+  return `${clientId}\u0000${conversationId}`;
+}
+
 type GatewayInternals = {
   clientSessions: Map<string, unknown>;
   relayEvent(client: unknown, conversationId: string, event: unknown): void;
@@ -40,6 +44,7 @@ describe('ChatGateway redaction boundary', (): void => {
       emit: vi.fn(),
     };
     const session = {
+      clientId: client.id,
       conversationId: CONVERSATION_ID,
       cleanup: vi.fn(),
       assistantText: '',
@@ -47,7 +52,7 @@ describe('ChatGateway redaction boundary', (): void => {
       pendingToolCalls: new Map(),
       scope: { userId: 'user-1', tenantId: 'tenant-1' },
     };
-    gateway.clientSessions.set(client.id, session);
+    gateway.clientSessions.set(clientConversationKey(client.id, CONVERSATION_ID), session);
 
     gateway.relayEvent(client, CONVERSATION_ID, {
       type: 'message_update',
@@ -139,6 +144,51 @@ describe('ChatGateway redaction boundary', (): void => {
     });
   });
 
+  it('isolates concurrent conversation streams sharing one Discord socket', (): void => {
+    const { gateway } = buildGateway();
+    const client = {
+      connected: true,
+      id: 'discord-client',
+      data: { user: { id: 'user-1' } },
+      emit: vi.fn(),
+    };
+    const firstConversation = 'Nova:discord:thread-1';
+    const secondConversation = 'Nova:discord:thread-2';
+    const createSession = (conversationId: string) => ({
+      clientId: client.id,
+      conversationId,
+      cleanup: vi.fn(),
+      assistantText: '',
+      toolCalls: [],
+      pendingToolCalls: new Map(),
+      scope: { userId: 'user-1', tenantId: 'tenant-1' },
+    });
+    const firstSession = createSession(firstConversation);
+    const secondSession = createSession(secondConversation);
+    gateway.clientSessions.set(clientConversationKey(client.id, firstConversation), firstSession);
+    gateway.clientSessions.set(clientConversationKey(client.id, secondConversation), secondSession);
+
+    gateway.relayEvent(client, firstConversation, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: 'first response ' },
+    });
+    gateway.relayEvent(client, secondConversation, {
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: 'second response ' },
+    });
+
+    expect(firstSession.assistantText).toBe('first response ');
+    expect(secondSession.assistantText).toBe('second response ');
+    expect(client.emit).toHaveBeenCalledWith('agent:text', {
+      conversationId: firstConversation,
+      text: 'first response ',
+    });
+    expect(client.emit).toHaveBeenCalledWith('agent:text', {
+      conversationId: secondConversation,
+      text: 'second response ',
+    });
+  });
+
   it('persists only redacted assistant content with classifications', (): void => {
     const { gateway, brain } = buildGateway();
     const client = {
@@ -147,7 +197,8 @@ describe('ChatGateway redaction boundary', (): void => {
       data: { user: { id: 'user-1' } },
       emit: vi.fn(),
     };
-    gateway.clientSessions.set(client.id, {
+    gateway.clientSessions.set(clientConversationKey(client.id, CONVERSATION_ID), {
+      clientId: client.id,
       conversationId: CONVERSATION_ID,
       cleanup: vi.fn(),
       assistantText: CANARY,

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

@@ -17,6 +17,7 @@ import {
   parseDiscordInteractionBindings,
   resolveDiscordInteractionActorId,
   resolveDiscordInteractionBinding,
+  type DiscordAttachment,
   type DiscordIngressEnvelope,
   type DiscordIngressPayload,
 } from '@mosaicstack/discord-plugin';
@@ -30,9 +31,15 @@ import type {
   SystemReloadPayload,
   RoutingDecisionInfo,
   AbortPayload,
+  ChannelAttachmentDto,
 } from '@mosaicstack/types';
 import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
-import { RuntimeProviderService } from '../agent/runtime-provider-registry.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,
@@ -51,6 +58,7 @@ import { DiscordReplayProtector } from '../plugin/discord-replay-protector.js';
 
 /** Per-client state tracking streaming accumulation for persistence. */
 interface ClientSession {
+  clientId: string;
   conversationId: string;
   cleanup: () => void;
   /** Accumulated assistant response text for the current turn. */
@@ -71,6 +79,68 @@ interface ClientSession {
  */
 const modelOverrides = new Map<string, string>();
 const MAX_REDACTION_BUFFER_LENGTH = 8_192;
+const MAX_CHANNEL_ATTACHMENTS = 10;
+const MAX_ATTACHMENT_METADATA_BYTES = 16_384;
+const MAX_ATTACHMENT_ID_LENGTH = 128;
+const MAX_ATTACHMENT_NAME_LENGTH = 255;
+const MAX_ATTACHMENT_URL_LENGTH = 2_048;
+const MAX_ATTACHMENT_MIME_LENGTH = 255;
+
+function isSafeAttachmentUrl(value: string): boolean {
+  if (value.length === 0 || value.length > MAX_ATTACHMENT_URL_LENGTH) return false;
+  try {
+    const url = new URL(value);
+    return (
+      url.protocol === 'https:' &&
+      !url.username &&
+      !url.password &&
+      !url.hash &&
+      url.search.length === 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+function hasValidAttachmentBounds(value: {
+  id: string;
+  name: string;
+  url: string;
+  sizeBytes?: number;
+}): boolean {
+  return (
+    value.id.length > 0 &&
+    value.id.length <= MAX_ATTACHMENT_ID_LENGTH &&
+    value.name.length > 0 &&
+    value.name.length <= MAX_ATTACHMENT_NAME_LENGTH &&
+    isSafeAttachmentUrl(value.url) &&
+    (value.sizeBytes === undefined || (Number.isFinite(value.sizeBytes) && value.sizeBytes >= 0))
+  );
+}
+
+function isDiscordAttachment(value: unknown): value is DiscordAttachment {
+  if (typeof value !== 'object' || value === null) return false;
+  const attachment = value as Partial<DiscordAttachment>;
+  return (
+    typeof attachment.id === 'string' &&
+    typeof attachment.name === 'string' &&
+    typeof attachment.url === 'string' &&
+    (attachment.contentType === null ||
+      (typeof attachment.contentType === 'string' &&
+        attachment.contentType.length <= MAX_ATTACHMENT_MIME_LENGTH)) &&
+    (attachment.sizeBytes === undefined || typeof attachment.sizeBytes === 'number') &&
+    hasValidAttachmentBounds(attachment as DiscordAttachment)
+  );
+}
+
+function hasValidAttachmentArray(value: unknown, guard: (attachment: unknown) => boolean): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length <= MAX_CHANNEL_ATTACHMENTS &&
+    JSON.stringify(value).length <= MAX_ATTACHMENT_METADATA_BYTES &&
+    value.every(guard)
+  );
+}
 
 function isDiscordIngressEnvelope(value: unknown): value is DiscordIngressEnvelope {
   if (typeof value !== 'object' || value === null) return false;
@@ -83,23 +153,49 @@ function isDiscordIngressEnvelope(value: unknown): value is DiscordIngressEnvelo
     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');
+  return (
+    [
+      payload['correlationId'],
+      payload['messageId'],
+      payload['guildId'],
+      payload['channelId'],
+      payload['userId'],
+      payload['conversationId'],
+      payload['content'],
+    ].every((field: unknown): boolean => typeof field === 'string') &&
+    (payload['threadId'] === undefined || typeof payload['threadId'] === 'string') &&
+    (payload['attachments'] === undefined ||
+      hasValidAttachmentArray(payload['attachments'], isDiscordAttachment))
+  );
+}
+
+function isChannelAttachment(value: unknown): value is ChannelAttachmentDto {
+  if (typeof value !== 'object' || value === null) return false;
+  const attachment = value as Partial<ChannelAttachmentDto>;
+  return (
+    typeof attachment.id === 'string' &&
+    typeof attachment.name === 'string' &&
+    typeof attachment.url === 'string' &&
+    (attachment.mimeType === null ||
+      (typeof attachment.mimeType === 'string' &&
+        attachment.mimeType.length <= MAX_ATTACHMENT_MIME_LENGTH)) &&
+    (attachment.sizeBytes === undefined || typeof attachment.sizeBytes === 'number') &&
+    hasValidAttachmentBounds(attachment as ChannelAttachmentDto)
+  );
 }
 
 function isChatSocketMessage(value: unknown): value is ChatSocketMessageDto {
   if (typeof value !== 'object' || value === null) return false;
-  const payload = value as { content?: unknown; conversationId?: unknown };
+  const payload = value as {
+    content?: unknown;
+    conversationId?: unknown;
+    attachments?: unknown;
+  };
   return (
     typeof payload.content === 'string' &&
-    (payload.conversationId === undefined || typeof payload.conversationId === 'string')
+    (payload.conversationId === undefined || typeof payload.conversationId === 'string') &&
+    (payload.attachments === undefined ||
+      hasValidAttachmentArray(payload.attachments, isChannelAttachment))
   );
 }
 
@@ -134,6 +230,12 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     @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 {
@@ -163,20 +265,24 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
   handleDisconnect(client: Socket): void {
     this.logger.log(`Client disconnected: ${client.id}`);
-    const session = this.clientSessions.get(client.id);
-    if (session) {
+    for (const [key, session] of this.clientSessions) {
+      if (session.clientId !== client.id) continue;
       session.cleanup();
       this.agentService.removeChannel(
         session.conversationId,
         `websocket:${client.id}`,
         session.scope,
       );
-      this.clientSessions.delete(client.id);
+      this.clientSessions.delete(key);
+      this.textEgressBuffers.delete(key);
+      this.thinkingEgressBuffers.delete(key);
+      this.overflowedEgress.delete(`${key}:agent:text`);
+      this.overflowedEgress.delete(`${key}:agent:thinking`);
     }
-    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 clientConversationKey(client: Pick<Socket, 'id'>, conversationId: string): string {
+    return `${client.id}\u0000${conversationId}`;
   }
 
   private getClientScope(client: Socket): ActorTenantScope | null {
@@ -207,7 +313,25 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       }
       discordIngress = this.resolveDiscordIngress(client, rawData);
       if (!discordIngress) return;
-      data = { conversationId: discordIngress.conversationId, content: discordIngress.content };
+      data = {
+        conversationId: discordIngress.conversationId,
+        content: discordIngress.content,
+        ...(discordIngress.attachments
+          ? {
+              attachments: discordIngress.attachments.map(
+                (attachment): ChannelAttachmentDto => ({
+                  id: attachment.id,
+                  name: attachment.name,
+                  url: attachment.url,
+                  mimeType: attachment.contentType,
+                  ...(attachment.sizeBytes !== undefined
+                    ? { sizeBytes: attachment.sizeBytes }
+                    : {}),
+                }),
+              ),
+            }
+          : {}),
+      };
     } else {
       if (!isChatSocketMessage(rawData)) {
         this.logger.warn(`Rejected malformed chat message from ${client.id}`);
@@ -216,6 +340,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       data = rawData;
     }
     const conversationId = data.conversationId ?? uuid();
+    const clientConversationKey = this.clientConversationKey(client, conversationId);
     const discordServiceUserId = process.env['DISCORD_SERVICE_USER_ID'];
     if (discordIngress && !discordServiceUserId) {
       this.logger.warn(
@@ -270,7 +395,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
           this.logger.log(
             `Using /model override "${modelOverride}" for conversation=${conversationId}`,
           );
-        } else if (!resolvedProvider && !resolvedModelId) {
+        } else if (!resolvedProvider && !resolvedModelId && !discordIngress) {
           // No explicit provider/model from client — use routing engine (M4-012)
           try {
             const routingDecision = await this.routingEngine.resolve(data.content, userId);
@@ -293,12 +418,24 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
           }
         }
 
+        let resolvedAgentConfigId = data.agentId;
+        if (discordIngress) {
+          const binding = this.discordBindingFor(discordIngress, 'send');
+          const agentConfig = binding
+            ? await this.brain.agents.findById(binding.agentConfigId)
+            : undefined;
+          if (!binding || !agentConfig || agentConfig.name !== binding.instanceId) {
+            throw new Error('Configured Discord logical agent is not provisioned');
+          }
+          resolvedAgentConfigId = agentConfig.id;
+        }
+
         // M5-004: Use existingSessionId as sessionId when available (session reuse)
         const sessionIdToCreate = existingSessionId ?? conversationId;
         agentSession = await this.agentService.createSession(sessionIdToCreate, {
           provider: resolvedProvider,
           modelId: resolvedModelId,
-          agentConfigId: data.agentId,
+          agentConfigId: resolvedAgentConfigId,
           userId,
           tenantId: scope.tenantId,
           conversationHistory: conversationHistory.length > 0 ? conversationHistory : undefined,
@@ -349,6 +486,17 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
                     discordUserId: discordIngress?.userId,
                   }
                 : {}),
+              ...(data.attachments && data.attachments.length > 0
+                ? {
+                    channelAttachments: data.attachments.map(
+                      (attachment): ChannelAttachmentDto => ({
+                        ...attachment,
+                        name: redactSensitiveContent(attachment.name).content,
+                        url: redactSensitiveContent(attachment.url).content,
+                      }),
+                    ),
+                  }
+                : {}),
               classifications: redactSensitiveContent(data.content).classifications,
             },
           },
@@ -363,7 +511,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     }
 
     // Always clean up previous listener to prevent leak
-    const existing = this.clientSessions.get(client.id);
+    const existing = this.clientSessions.get(clientConversationKey);
     if (existing) {
       existing.cleanup();
     }
@@ -378,10 +526,11 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     );
 
     // Preserve routing decision from the existing client session if we didn't get a new one
-    const prevClientSession = this.clientSessions.get(client.id);
+    const prevClientSession = this.clientSessions.get(clientConversationKey);
     const routingDecisionToStore = sessionRoutingDecision ?? prevClientSession?.lastRoutingDecision;
 
-    this.clientSessions.set(client.id, {
+    this.clientSessions.set(clientConversationKey, {
+      clientId: client.id,
       conversationId,
       cleanup,
       assistantText: '',
@@ -427,7 +576,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
     // Dispatch to agent
     try {
-      await this.agentService.prompt(conversationId, data.content, scope);
+      await this.agentService.prompt(conversationId, data.content, scope, data.attachments);
     } catch (err) {
       this.logger.error(
         `Agent prompt failed for client=${client.id}, conversation=${conversationId}`,
@@ -634,9 +783,9 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     };
 
     // Emit to all clients currently subscribed to this conversation
-    for (const [clientId, session] of this.clientSessions) {
+    for (const session of this.clientSessions.values()) {
       if (session.conversationId === conversationId && this.scopesEqual(session.scope, scope)) {
-        const socket = this.server.sockets.sockets.get(clientId);
+        const socket = this.server.sockets.sockets.get(session.clientId);
         if (socket?.connected) {
           socket.emit('session:info', payload);
         }
@@ -656,19 +805,20 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
   ): Promise<void> {
     if (!client.data.discordService) return;
     const ingress = this.resolveDiscordIngress(client, envelope, 'approve');
-    const actionParts = ingress?.content.match(/^\/approve\s+([^\s]+)\s+([^\s]+)$/i);
+    const isApprovalCommand = /^\/approve\s*$/i.test(ingress?.content ?? '');
     const tenantId = process.env['DISCORD_SERVICE_TENANT_ID']?.trim();
-    if (!ingress || !actionParts || !tenantId || !this.commandAuthorization) return;
-    const binding = resolveDiscordInteractionBinding(
-      parseDiscordInteractionBindings(process.env['DISCORD_INTERACTION_BINDINGS']),
-      ingress.guildId,
-      ingress.channelId,
-      ingress.userId,
-      'approve',
-    );
+    if (
+      !ingress ||
+      !isApprovalCommand ||
+      !tenantId ||
+      !this.commandAuthorization ||
+      !this.durableSessions
+    )
+      return;
+    const binding = this.discordBindingFor(ingress, 'approve');
     const actorId = binding && resolveDiscordInteractionActorId(binding, ingress.userId);
-    const agentName = process.env['MOSAIC_AGENT_NAME']?.trim();
-    if (!actorId || !agentName || binding.instanceId !== agentName) {
+    const agentName = binding?.instanceId;
+    if (!actorId || !agentName) {
       this.logger.warn(
         `Rejected Discord approval without a matching runtime agent from ${client.id}`,
       );
@@ -680,22 +830,63 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       });
       return;
     }
-    const providerId = actionParts[1]!;
-    const sessionId = actionParts[2]!;
+    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,
-      sessionId,
+      providerId: snapshot.identity.providerId,
+      sessionId: snapshot.identity.runtimeSessionId,
       actorId,
       tenantId,
       channelId: ingress.channelId,
       correlationId: this.discordRuntimeActionCorrelation(
         binding.instanceId,
         ingress,
-        providerId,
-        sessionId,
+        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,
@@ -711,37 +902,38 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
   ): Promise<void> {
     if (!client.data.discordService) return;
     const ingress = this.resolveDiscordIngress(client, envelope, 'stop');
-    const actionParts = ingress?.content.match(/^\/stop\s+([^\s]+)\s+([^\s]+)\s+([^\s]+)$/i);
+    const approvalRef = /^\/stop\s+([^\s]+)$/i.exec(ingress?.content ?? '')?.[1];
     const tenantId = process.env['DISCORD_SERVICE_TENANT_ID']?.trim();
-    if (!ingress || !actionParts || !tenantId || !this.runtimeRegistry) return;
-    const binding = resolveDiscordInteractionBinding(
-      parseDiscordInteractionBindings(process.env['DISCORD_INTERACTION_BINDINGS']),
-      ingress.guildId,
-      ingress.channelId,
-      ingress.userId,
-      'stop',
-    );
+    if (!ingress || !approvalRef || !tenantId || !this.runtimeRegistry || !this.durableSessions)
+      return;
+    const binding = this.discordBindingFor(ingress, 'stop');
     const actorId = binding && resolveDiscordInteractionActorId(binding, ingress.userId);
     if (!actorId) return;
-    const providerId = actionParts[1]!;
-    const sessionId = actionParts[2]!;
 
     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(providerId, sessionId, actionParts[3]!, {
-        actorScope: {
-          userId: actorId,
-          tenantId,
+      await this.runtimeRegistry.terminate(
+        snapshot.identity.providerId,
+        snapshot.identity.runtimeSessionId,
+        approvalRef,
+        {
+          ...context,
+          correlationId: this.discordRuntimeActionCorrelation(
+            binding.instanceId,
+            ingress,
+            snapshot.identity.providerId,
+            snapshot.identity.runtimeSessionId,
+          ),
         },
-        channelId: ingress.channelId,
-        correlationId: this.discordRuntimeActionCorrelation(
-          binding.instanceId,
-          ingress,
-          providerId,
-          sessionId,
-        ),
-      });
+      );
       client.emit('discord:stop', { correlationId: ingress.correlationId, success: true });
     } catch {
       client.emit('discord:stop', { correlationId: ingress.correlationId, success: false });
@@ -788,17 +980,18 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       return null;
     }
     try {
-      const binding = resolveDiscordInteractionBinding(
-        parseDiscordInteractionBindings(process.env['DISCORD_INTERACTION_BINDINGS']),
-        payload.guildId,
-        payload.channelId,
-        payload.userId,
-        operation,
-      );
+      const binding = this.discordBindingFor(payload, operation);
       if (!binding) {
         this.logger.warn(`Rejected unpaired Discord ingress from ${client.id}`);
         return null;
       }
+      const expectedConversationId = `${binding.instanceId}:discord:${payload.threadId ?? payload.channelId}`;
+      if (payload.conversationId !== expectedConversationId) {
+        this.logger.warn(
+          `Rejected Discord ingress for a different logical agent from ${client.id}`,
+        );
+        return null;
+      }
     } catch {
       this.logger.warn(
         `Rejected Discord ingress without valid binding configuration from ${client.id}`,
@@ -814,6 +1007,19 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     return payload;
   }
 
+  private discordBindingFor(
+    payload: DiscordIngressPayload,
+    operation: 'send' | 'approve' | 'stop',
+  ) {
+    return resolveDiscordInteractionBinding(
+      parseDiscordInteractionBindings(process.env['DISCORD_INTERACTION_BINDINGS']),
+      payload.guildId,
+      payload.channelId,
+      payload.userId,
+      operation,
+    );
+  }
+
   private readDiscordAllowlist(name: string): string[] {
     return (process.env[name] ?? '')
       .split(',')
@@ -892,11 +1098,15 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       const messages = await this.brain.conversations.findMessages(conversationId, userId);
       if (messages.length === 0) return [];
 
-      return messages.map((msg) => ({
-        role: msg.role as 'user' | 'assistant' | 'system',
-        content: msg.content,
-        createdAt: msg.createdAt,
-      }));
+      return messages.map((msg) => {
+        const attachments = this.persistedChannelAttachments(msg.metadata);
+        return {
+          role: msg.role as 'user' | 'assistant' | 'system',
+          content: msg.content,
+          createdAt: msg.createdAt,
+          ...(attachments ? { attachments } : {}),
+        };
+      });
     } catch (err) {
       this.logger.error(
         `Failed to load conversation history for conversation=${conversationId}`,
@@ -906,6 +1116,14 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     }
   }
 
+  private persistedChannelAttachments(metadata: unknown): readonly ChannelAttachmentDto[] | null {
+    if (typeof metadata !== 'object' || metadata === null) return null;
+    const attachments = (metadata as { channelAttachments?: unknown }).channelAttachments;
+    return hasValidAttachmentArray(attachments, isChannelAttachment)
+      ? (attachments as readonly ChannelAttachmentDto[])
+      : null;
+  }
+
   private appendAndFlushRedactedEgress(
     client: Socket,
     conversationId: string,
@@ -913,18 +1131,19 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     buffers: Map<string, string>,
     delta: string,
   ): void {
-    const key = this.egressKey(client, eventName);
+    const sessionKey = this.clientConversationKey(client, conversationId);
+    const key = this.egressKey(client, conversationId, eventName);
     if (this.overflowedEgress.has(key)) return;
 
-    const buffered = `${buffers.get(client.id) ?? ''}${delta}`;
+    const buffered = `${buffers.get(sessionKey) ?? ''}${delta}`;
     if (buffered.length > MAX_REDACTION_BUFFER_LENGTH) {
-      buffers.delete(client.id);
+      buffers.delete(sessionKey);
       this.overflowedEgress.add(key);
       client.emit(eventName, { conversationId, text: '[REDACTED_STREAM_OVERFLOW]' });
       return;
     }
 
-    buffers.set(client.id, buffered);
+    buffers.set(sessionKey, buffered);
     this.flushRedactedEgress(client, conversationId, eventName, buffers, false);
   }
 
@@ -940,21 +1159,22 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     buffers: Map<string, string>,
     final: boolean,
   ): void {
-    const key = this.egressKey(client, eventName);
+    const sessionKey = this.clientConversationKey(client, conversationId);
+    const key = this.egressKey(client, conversationId, eventName);
     if (this.overflowedEgress.has(key)) {
       if (final) this.overflowedEgress.delete(key);
       return;
     }
 
-    const buffered = buffers.get(client.id) ?? '';
+    const buffered = buffers.get(sessionKey) ?? '';
     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);
+      buffers.set(sessionKey, pending);
     } else {
-      buffers.delete(client.id);
+      buffers.delete(sessionKey);
     }
 
     if (released) {
@@ -1023,8 +1243,12 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     return retainedFrom;
   }
 
-  private egressKey(client: Socket, eventName: 'agent:text' | 'agent:thinking'): string {
-    return `${client.id}:${eventName}`;
+  private egressKey(
+    client: Socket,
+    conversationId: string,
+    eventName: 'agent:text' | 'agent:thinking',
+  ): string {
+    return `${this.clientConversationKey(client, conversationId)}:${eventName}`;
   }
 
   private relayEvent(client: Socket, conversationId: string, event: AgentSessionEvent): void {
@@ -1035,26 +1259,27 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       return;
     }
 
+    const sessionKey = this.clientConversationKey(client, conversationId);
     switch (event.type) {
       case 'agent_start': {
         // Reset accumulation buffers for the new turn
-        const cs = this.clientSessions.get(client.id);
+        const cs = this.clientSessions.get(sessionKey);
         if (cs) {
           cs.assistantText = '';
           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'));
+        this.textEgressBuffers.set(sessionKey, '');
+        this.thinkingEgressBuffers.set(sessionKey, '');
+        this.overflowedEgress.delete(this.egressKey(client, conversationId, 'agent:text'));
+        this.overflowedEgress.delete(this.egressKey(client, conversationId, 'agent:thinking'));
         client.emit('agent:start', { conversationId });
         break;
       }
 
       case 'agent_end': {
         // Gather usage stats from the Pi session
-        const activeClientSession = this.clientSessions.get(client.id);
+        const activeClientSession = this.clientSessions.get(sessionKey);
         const agentSession = activeClientSession
           ? this.agentService.getSession(conversationId, activeClientSession.scope)
           : undefined;
@@ -1107,7 +1332,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
         }
 
         // Persist the assistant message with metadata
-        const cs = this.clientSessions.get(client.id);
+        const cs = this.clientSessions.get(sessionKey);
         const userId = (client.data.user as { id: string } | undefined)?.id;
         if (cs && userId && cs.assistantText.trim().length > 0) {
           const metadata: Record<string, unknown> = {
@@ -1159,7 +1384,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
         const assistantEvent = event.assistantMessageEvent;
         if (assistantEvent.type === 'text_delta') {
           // Keep raw stream material in memory only; persist and emit only redacted text.
-          const cs = this.clientSessions.get(client.id);
+          const cs = this.clientSessions.get(sessionKey);
           if (cs) {
             cs.assistantText += assistantEvent.delta;
           }
@@ -1184,7 +1409,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
       case 'tool_execution_start': {
         // Track pending tool call for later recording
-        const cs = this.clientSessions.get(client.id);
+        const cs = this.clientSessions.get(sessionKey);
         if (cs) {
           cs.pendingToolCalls.set(event.toolCallId, {
             toolName: event.toolName,
@@ -1201,7 +1426,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
       case 'tool_execution_end': {
         // Finalise tool call record
-        const cs = this.clientSessions.get(client.id);
+        const cs = this.clientSessions.get(sessionKey);
         if (cs) {
           const pending = cs.pendingToolCalls.get(event.toolCallId);
           cs.toolCalls.push({

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

@@ -1,3 +1,4 @@
+import { Logger } from '@nestjs/common';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { CommandExecutorService } from './command-executor.service.js';
 import type { SlashCommandPayload } from '@mosaicstack/types';
@@ -12,6 +13,7 @@ const mockRegistry = {
       { name: 'agent', aliases: ['a'], scope: 'agent', execution: 'socket', available: true },
       { name: 'prdy', aliases: [], scope: 'agent', execution: 'socket', available: true },
       { name: 'tools', aliases: [], scope: 'agent', execution: 'socket', available: true },
+      { name: 'mcp', aliases: [], scope: 'agent', execution: 'socket', available: true },
     ],
     skills: [],
   })),
@@ -72,17 +74,24 @@ const mockChatGateway = {
   broadcastSessionInfo: vi.fn(),
 };
 
-function buildService(): CommandExecutorService {
+function buildService(
+  redis: typeof mockRedis | null = mockRedis,
+  mcpClient: {
+    reconnectServer: ReturnType<typeof vi.fn>;
+    getServerStatuses: ReturnType<typeof vi.fn>;
+    getToolDefinitions: ReturnType<typeof vi.fn>;
+  } | null = null,
+): CommandExecutorService {
   return new CommandExecutorService(
     mockRegistry as never,
     mockAgentService as never,
     mockSystemOverride as never,
     mockSessionGC as never,
-    mockRedis as never,
+    redis as never,
     mockBrain as never,
     null,
     mockChatGateway as never,
-    null,
+    mcpClient as never,
   );
 }
 
@@ -131,6 +140,22 @@ describe('CommandExecutorService — P8-012 commands', () => {
     expect(ttl).toBe(300);
   });
 
+  it('/provider login remains available without Redis on the local tier', async () => {
+    const localService = buildService(null);
+    const payload: SlashCommandPayload = {
+      command: 'provider',
+      args: 'login anthropic',
+      conversationId,
+    };
+
+    const result = await localService.execute(payload, userScope);
+
+    expect(result.success).toBe(true);
+    expect(result.message).not.toContain('token=');
+    expect(result.data).toEqual({ provider: 'anthropic' });
+    expect(mockRedis.set).not.toHaveBeenCalled();
+  });
+
   // /provider with no args — returns usage
   it('/provider with no args returns usage message', async () => {
     const payload: SlashCommandPayload = { command: 'provider', conversationId };
@@ -242,4 +267,124 @@ describe('CommandExecutorService — P8-012 commands', () => {
     expect(result.command).toBe('tools');
     expect(result.message).toContain('tools');
   });
+
+  // Top-level catch sanitization (P3-4 re-review finding #1): a rejected
+  // Redis `set` inside /provider login is the only reachable path into the
+  // top-level catch in `execute()`. The raw exception must be logged
+  // server-side but never handed back to the socket client.
+  it('sanitizes the top-level command catch, logging the raw exception but never returning it to the client', async () => {
+    const distinctiveRawFailure = 'ECONNREFUSED distinctive-raw-redis-failure-token-9f31';
+    const rawError = new Error(distinctiveRawFailure);
+    const failingRedis = {
+      set: vi.fn().mockRejectedValue(rawError),
+      get: vi.fn(),
+      del: vi.fn(),
+    };
+    const failingService = buildService(failingRedis as unknown as typeof mockRedis);
+    const loggerErrorSpy = vi.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+
+    const payload: SlashCommandPayload = {
+      command: 'provider',
+      args: 'login anthropic',
+      conversationId,
+    };
+    const result = await failingService.execute(payload, userScope);
+
+    expect(result.success).toBe(false);
+    expect(result.command).toBe('provider');
+    expect(result.message).toBe('Command failed due to an internal error.');
+    expect(result.message).not.toContain(distinctiveRawFailure);
+    expect(result.message).not.toContain('ECONNREFUSED');
+
+    // The real exception is still logged server-side, as the raw Error
+    // object itself (not stringified/interpolated into the log message).
+    expect(loggerErrorSpy).toHaveBeenCalled();
+    const loggedRawError = loggerErrorSpy.mock.calls.some((call) => call.includes(rawError));
+    expect(loggedRawError).toBe(true);
+
+    loggerErrorSpy.mockRestore();
+  });
+
+  // Inner catch sanitization (P3-5 operator ruling): every catch in
+  // command-executor.service.ts that returns a SlashCommandResultPayload
+  // must sanitize the client-facing message the same way the top-level
+  // catch does, while still logging the raw exception server-side.
+  it('/agent new sanitizes agent-creation failures, logging the raw exception but never returning it to the client', async () => {
+    const marker = new Error('distinctive-agent-create-failure-token-A17f');
+    mockBrain.agents.create.mockRejectedValueOnce(marker);
+    const loggerErrorSpy = vi.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+
+    const payload: SlashCommandPayload = {
+      command: 'agent',
+      args: 'new my-new-agent',
+      conversationId,
+    };
+    const result = await service.execute(payload, userScope);
+
+    expect(result.success).toBe(false);
+    expect(result.command).toBe('agent');
+    expect(result.message).toBe('Failed to create agent due to an internal error.');
+    expect(result.message).not.toContain('distinctive-agent-create-failure-token-A17f');
+
+    expect(loggerErrorSpy).toHaveBeenCalled();
+    const loggedRawError = loggerErrorSpy.mock.calls.some((call) => call.includes(marker));
+    expect(loggedRawError).toBe(true);
+
+    loggerErrorSpy.mockRestore();
+  });
+
+  it('/agent <name> switch sanitizes agent-lookup failures, logging the raw exception but never returning it to the client', async () => {
+    const marker = new Error('distinctive-agent-switch-failure-token-B29c');
+    mockBrain.agents.findByName.mockRejectedValueOnce(marker);
+    const loggerErrorSpy = vi.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+
+    const payload: SlashCommandPayload = {
+      command: 'agent',
+      args: 'some-other-agent',
+      conversationId,
+    };
+    const result = await service.execute(payload, userScope);
+
+    expect(result.success).toBe(false);
+    expect(result.command).toBe('agent');
+    expect(result.message).toBe('Failed to switch agent due to an internal error.');
+    expect(result.message).not.toContain('distinctive-agent-switch-failure-token-B29c');
+
+    expect(loggerErrorSpy).toHaveBeenCalled();
+    const loggedRawError = loggerErrorSpy.mock.calls.some((call) => call.includes(marker));
+    expect(loggedRawError).toBe(true);
+
+    loggerErrorSpy.mockRestore();
+  });
+
+  it('/mcp reconnect sanitizes MCP client failures, logging the raw exception but never returning it to the client', async () => {
+    const marker = new Error('distinctive-mcp-reconnect-failure-token-C33e');
+    const mockMcpClient = {
+      reconnectServer: vi.fn().mockRejectedValue(marker),
+      getServerStatuses: vi.fn(() => []),
+      getToolDefinitions: vi.fn(() => []),
+    };
+    const mcpService = buildService(mockRedis, mockMcpClient);
+    const loggerErrorSpy = vi.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+
+    const payload: SlashCommandPayload = {
+      command: 'mcp',
+      args: 'reconnect my-server',
+      conversationId,
+    };
+    const result = await mcpService.execute(payload, userScope);
+
+    expect(result.success).toBe(false);
+    expect(result.command).toBe('mcp');
+    expect(result.message).toBe(
+      'Failed to reconnect MCP server "my-server" due to an internal error.',
+    );
+    expect(result.message).not.toContain('distinctive-mcp-reconnect-failure-token-C33e');
+
+    expect(loggerErrorSpy).toHaveBeenCalled();
+    const loggedRawError = loggerErrorSpy.mock.calls.some((call) => call.includes(marker));
+    expect(loggedRawError).toBe(true);
+
+    loggerErrorSpy.mockRestore();
+  });
 });

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

@@ -23,7 +23,10 @@ export class CommandExecutorService {
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(SystemOverrideService) private readonly systemOverride: SystemOverrideService,
     @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
-    @Inject(COMMANDS_REDIS) private readonly redis: QueueHandle['redis'],
+    // On Local tier COMMANDS_REDIS is null — provider login caching is skipped.
+    @Optional()
+    @Inject(COMMANDS_REDIS)
+    private readonly redis: QueueHandle['redis'] | null,
     @Inject(BRAIN) private readonly brain: Brain,
     @Optional()
     @Inject(forwardRef(() => ReloadService))
@@ -156,8 +159,13 @@ export class CommandExecutorService {
           };
       }
     } catch (err) {
-      this.logger.error(`Command /${command} failed: ${err}`);
-      return { command, conversationId, success: false, message: String(err) };
+      this.logger.error(`Command /${command} failed`, err);
+      return {
+        command,
+        conversationId,
+        success: false,
+        message: 'Command failed due to an internal error.',
+      };
     }
   }
 
@@ -333,11 +341,11 @@ export class CommandExecutorService {
           data: { agentId: newAgent.id, agentName: newAgent.name },
         };
       } catch (err) {
-        this.logger.error(`Failed to create agent: ${err}`);
+        this.logger.error(`Failed to create agent "${namePart}" for user ${userId}`, err);
         return {
           command: 'agent',
           success: false,
-          message: `Failed to create agent: ${String(err)}`,
+          message: 'Failed to create agent due to an internal error.',
           conversationId,
         };
       }
@@ -388,11 +396,11 @@ export class CommandExecutorService {
         data: { agentId: agentConfig.id, agentName: agentConfig.name, model: agentConfig.model },
       };
     } catch (err) {
-      this.logger.error(`Failed to switch agent "${agentName}": ${err}`);
+      this.logger.error(`Failed to switch agent "${agentName}"`, err);
       return {
         command: 'agent',
         success: false,
-        message: `Failed to switch agent: ${String(err)}`,
+        message: 'Failed to switch agent due to an internal error.',
         conversationId,
       };
     }
@@ -443,14 +451,16 @@ export class CommandExecutorService {
           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,
-        );
+        if (this.redis) {
+          // 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,
@@ -603,11 +613,12 @@ export class CommandExecutorService {
             message: `MCP server "${serverName}" reconnected successfully.`,
           };
         } catch (err) {
+          this.logger.error(`Failed to reconnect MCP server "${serverName}"`, err);
           return {
             command: 'mcp',
             conversationId,
             success: false,
-            message: `Failed to reconnect MCP server "${serverName}": ${err instanceof Error ? err.message : String(err)}`,
+            message: `Failed to reconnect MCP server "${serverName}" due to an internal error.`,
           };
         }
       }

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

@@ -1,5 +1,7 @@
-import { forwardRef, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
+import { forwardRef, Inject, Module, Optional, 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';
@@ -16,13 +18,17 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
   providers: [
     {
       provide: COMMANDS_QUEUE_HANDLE,
-      useFactory: (): QueueHandle => {
+      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;
         return createQueue();
       },
+      inject: [MOSAIC_CONFIG],
     },
     {
       provide: COMMANDS_REDIS,
-      useFactory: (handle: QueueHandle) => handle.redis,
+      useFactory: (handle: QueueHandle | null) => handle?.redis ?? null,
       inject: [COMMANDS_QUEUE_HANDLE],
     },
     CommandRegistryService,
@@ -38,9 +44,13 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
   ],
 })
 export class CommandsModule implements OnApplicationShutdown {
-  constructor(@Inject(COMMANDS_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
+  constructor(
+    @Optional()
+    @Inject(COMMANDS_QUEUE_HANDLE)
+    private readonly handle: QueueHandle | null,
+  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await this.handle.close().catch(() => {});
+    await this.handle?.close().catch(() => {});
   }
 }

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,6 +5,8 @@ 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';
@@ -12,7 +14,13 @@ import { ListController } from './server/verbs/list.controller.js';
 import { FederationListQueryService } from './server/verbs/list-query.service.js';
 
 @Module({
-  controllers: [EnrollmentController, FederationController, CapabilitiesController, ListController],
+  controllers: [
+    EnrollmentController,
+    FederationController,
+    CapabilitiesController,
+    ListController,
+    GetController,
+  ],
   providers: [
     AdminGuard,
     CaService,
@@ -23,6 +31,7 @@ import { FederationListQueryService } from './server/verbs/list-query.service.js
     FederationAuthGuard,
     FederationScopeService,
     FederationListQueryService,
+    FederationGetQueryService,
   ],
   exports: [
     CaService,
@@ -33,6 +42,7 @@ 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

@@ -0,0 +1,348 @@
+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

@@ -0,0 +1,207 @@
+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

@@ -0,0 +1,311 @@
+/**
+ * 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

@@ -0,0 +1,100 @@
+/**
+ * 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,5 +1,7 @@
-import { Module, type OnApplicationShutdown, Inject } from '@nestjs/common';
+import { Module, type OnApplicationShutdown, Inject, Optional } 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';
 
@@ -9,13 +11,17 @@ const GC_QUEUE_HANDLE = 'GC_QUEUE_HANDLE';
   providers: [
     {
       provide: GC_QUEUE_HANDLE,
-      useFactory: (): QueueHandle => {
+      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;
         return createQueue();
       },
+      inject: [MOSAIC_CONFIG],
     },
     {
       provide: REDIS,
-      useFactory: (handle: QueueHandle) => handle.redis,
+      useFactory: (handle: QueueHandle | null) => handle?.redis ?? null,
       inject: [GC_QUEUE_HANDLE],
     },
     SessionGCService,
@@ -23,9 +29,13 @@ const GC_QUEUE_HANDLE = 'GC_QUEUE_HANDLE';
   exports: [SessionGCService],
 })
 export class GCModule implements OnApplicationShutdown {
-  constructor(@Inject(GC_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
+  constructor(
+    @Optional()
+    @Inject(GC_QUEUE_HANDLE)
+    private readonly handle: QueueHandle | null,
+  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await this.handle.close().catch(() => {});
+    await this.handle?.close().catch(() => {});
   }
 }

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

@@ -119,6 +119,19 @@ describe('SessionGCService', () => {
     ).resolves.toEqual({ allowed: true });
   });
 
+  it('collect() skips Valkey but still demotes only the requested session on local tier', async () => {
+    const localService = new SessionGCService(null, mockLogService as unknown as LogService);
+
+    const result = await localService.collect('local-session');
+
+    expect(result.sessionId).toBe('local-session');
+    expect(result.cleaned.valkeyKeys).toBeUndefined();
+    expect(mockLogService.logs.promoteSessionToWarm).toHaveBeenCalledWith(
+      'local-session',
+      expect.any(Date),
+    );
+  });
+
   it('collect() returns sessionId in result', async () => {
     const result = await service.collect('test-session-id');
     expect(result.sessionId).toBe('test-session-id');

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

@@ -1,4 +1,4 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { Inject, Injectable, Optional } from '@nestjs/common';
 import type { QueueHandle } from '@mosaicstack/queue';
 import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
@@ -21,7 +21,10 @@ function escapeRedisGlobLiteral(value: string): string {
 @Injectable()
 export class SessionGCService {
   constructor(
-    @Inject(REDIS) private readonly redis: QueueHandle['redis'],
+    // Local tier has no Redis; lifecycle cleanup still demotes this session's logs.
+    @Optional()
+    @Inject(REDIS)
+    private readonly redis: QueueHandle['redis'] | null,
     @Inject(LOG_SERVICE) private readonly logService: LogService,
   ) {}
 
@@ -29,8 +32,10 @@ export class SessionGCService {
    * 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 an empty population on the Local tier where Redis is disabled.
    */
   private async scanKeys(pattern: string): Promise<string[]> {
+    if (!this.redis) return [];
     const collected: string[] = [];
     let cursor = '0';
     do {
@@ -47,12 +52,14 @@ export class SessionGCService {
   async collect(sessionId: string): Promise<GCResult> {
     const result: GCResult = { sessionId, cleaned: {} };
 
-    // 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;
+    // 1. Valkey: delete all session-scoped keys (skipped on Local tier).
+    if (this.redis) {
+      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 only.

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

@@ -18,7 +18,7 @@ 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: Worker<MosaicJobData>[] = [];
+  private readonly registeredWorkers: Array<Worker<MosaicJobData>> = [];
 
   constructor(
     @Inject(SummarizationService) private readonly summarization: SummarizationService,
@@ -26,6 +26,12 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
   ) {}
 
   async onModuleInit(): Promise<void> {
+    // Local tier deliberately has no BullMQ consumers or repeatable jobs.
+    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
 
@@ -39,7 +45,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const summarizationWorker = this.queueService.registerWorker(QUEUE_SUMMARIZATION, async () => {
       await this.summarization.runSummarization();
     });
-    this.registeredWorkers.push(summarizationWorker);
+    if (summarizationWorker) this.registeredWorkers.push(summarizationWorker);
 
     // M6-005: Tier management repeatable job
     await this.queueService.addRepeatableJob(
@@ -51,7 +57,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const tierWorker = this.queueService.registerWorker(QUEUE_TIER_MANAGEMENT, async () => {
       await this.summarization.runTierManagement();
     });
-    this.registeredWorkers.push(tierWorker);
+    if (tierWorker) this.registeredWorkers.push(tierWorker);
 
     // Retire any repeatable global GC schedule created by older deployments.
     // Session cleanup is now triggered only by an authorized session lifecycle operation.

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

@@ -0,0 +1,44 @@
+import { Logger } from '@nestjs/common';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { McpClientService } from './mcp-client.service.js';
+
+const MCP_LEAK_MARKER = 'MCP_LEAK_MARKER /srv/secret';
+
+describe('McpClientService — failed connect error sanitization', () => {
+  const originalMcpServers = process.env['MCP_SERVERS'];
+
+  beforeEach(() => {
+    process.env['MCP_SERVERS'] = JSON.stringify([
+      { name: 'leaky-server', url: 'http://localhost:9999/mcp' },
+    ]);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (originalMcpServers === undefined) {
+      delete process.env['MCP_SERVERS'];
+    } else {
+      process.env['MCP_SERVERS'] = originalMcpServers;
+    }
+  });
+
+  it('stores a generic serverEntry.error while logging the raw exception server-side', async () => {
+    vi.spyOn(Client.prototype, 'connect').mockRejectedValue(new Error(MCP_LEAK_MARKER));
+    const errorSpy = vi.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+
+    const service = new McpClientService();
+    await service.onModuleInit();
+
+    const statuses = service.getServerStatuses();
+    expect(statuses).toHaveLength(1);
+    expect(statuses[0]?.connected).toBe(false);
+    expect(statuses[0]?.error).toBe('Connection failed (see server logs).');
+    expect(statuses[0]?.error).not.toContain(MCP_LEAK_MARKER);
+
+    const loggedRawMarker = errorSpy.mock.calls.some((call) =>
+      call.some((arg) => typeof arg === 'string' && arg.includes(MCP_LEAK_MARKER)),
+    );
+    expect(loggedRawMarker).toBe(true);
+  });
+});

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

@@ -189,7 +189,7 @@ export class McpClientService implements OnModuleInit, OnModuleDestroy {
       );
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      serverEntry.error = message;
+      serverEntry.error = 'Connection failed (see server logs).';
       serverEntry.connected = false;
       this.logger.error(`Failed to connect to MCP server "${config.name}": ${message}`);
     }

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

@@ -24,6 +24,7 @@ const ENV_KEYS = [
   'DISCORD_ALLOWED_CHANNEL_IDS',
   'DISCORD_ALLOWED_USER_IDS',
   'MOSAIC_AGENT_NAME',
+  'MOSAIC_AGENT_CONFIG_ID',
 ] as const;
 const savedEnv = new Map<string, string | undefined>();
 
@@ -33,12 +34,14 @@ function configureDiscordEnv(role: 'admin' | 'member' = 'admin'): void {
   process.env['DISCORD_SERVICE_USER_ID'] = 'discord-service';
   process.env['DISCORD_SERVICE_TENANT_ID'] = 'tenant-discord';
   process.env['MOSAIC_AGENT_NAME'] = 'Nova';
+  process.env['MOSAIC_AGENT_CONFIG_ID'] = 'agent-config-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',
+      agentConfigId: 'agent-config-nova',
       guildId: 'guild-001',
       channelId: 'channel-001',
       pairedUsers: {
@@ -77,9 +80,17 @@ 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: () => ({
@@ -105,9 +116,13 @@ function discordGateway(role: 'admin' | 'member'): {
       {} as never,
       authorization,
       runtimeRegistry,
+      durable as never,
+      audit as never,
     ),
     client: { data: { discordService: true }, emit: vi.fn() },
     consumedActions,
+    durable,
+    audit,
   };
 }
 
@@ -129,7 +144,7 @@ function createPayload(overrides: Partial<DiscordIngressPayload> = {}): DiscordI
     guildId: 'guild-001',
     channelId: 'channel-001',
     userId: 'user-001',
-    conversationId: 'discord-channel-001',
+    conversationId: 'Nova:discord:channel-001',
     content: 'hello Tess',
     ...overrides,
   };
@@ -141,6 +156,7 @@ describe('Discord ingress security', () => {
       JSON.stringify([
         {
           instanceId: 'Nova',
+          agentConfigId: 'agent-config-nova',
           guildId: 'guild-001',
           channelId: 'channel-001',
           pairedUsers: { 'user-001': 'admin' },
@@ -158,6 +174,7 @@ describe('Discord ingress security', () => {
       [
         {
           instanceId: 'Nova',
+          agentConfigId: 'agent-config-nova',
           guildId: 'guild-001',
           channelId: 'channel-001',
           pairedUsers: { 'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' } },
@@ -241,7 +258,7 @@ describe('Discord ingress security', () => {
     const { gateway, client, consumedActions } = discordGateway('admin');
     await gateway.handleDiscordApproval(
       client as never,
-      ingressEnvelope('/approve fleet runtime-1', 'approve-message', {
+      ingressEnvelope('/approve', 'approve-message', {
         correlationId: 'approval-ingress-correlation',
       }),
     );
@@ -255,7 +272,7 @@ describe('Discord ingress security', () => {
 
     await gateway.handleDiscordStop(
       client as never,
-      ingressEnvelope(`/stop fleet runtime-1 ${approval.approvalId}`, 'stop-message', {
+      ingressEnvelope(`/stop ${approval.approvalId}`, 'stop-message', {
         correlationId: 'stop-ingress-correlation',
       }),
     );
@@ -271,14 +288,40 @@ describe('Discord ingress security', () => {
     ]);
   });
 
-  it('rejects approval when the binding targets a different runtime agent', async () => {
+  it('audits a Discord mint-side authorization denial', async () => {
     configureDiscordEnv();
-    process.env['MOSAIC_AGENT_NAME'] = 'Other';
-    const { gateway, client } = discordGateway('admin');
+    const { gateway, client, audit } = discordGateway('member');
 
     await gateway.handleDiscordApproval(
       client as never,
-      ingressEnvelope('/approve fleet runtime-1', 'mismatched-agent-approve'),
+      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('rejects approval when the durable session targets a different logical agent', async () => {
+    configureDiscordEnv();
+    const { gateway, client, durable } = discordGateway('admin');
+    durable.getSnapshot.mockResolvedValueOnce({
+      identity: { agentName: 'Other', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
+    });
+
+    await gateway.handleDiscordApproval(
+      client as never,
+      ingressEnvelope('/approve', 'mismatched-agent-approve'),
     );
 
     expect(client.emit).toHaveBeenCalledWith('discord:approval', {
@@ -289,12 +332,33 @@ describe('Discord ingress security', () => {
     });
   });
 
+  it('rejects privileged envelopes with a forged current conversation route', async () => {
+    configureDiscordEnv();
+    const { gateway, client } = discordGateway('admin');
+
+    await gateway.handleDiscordApproval(
+      client as never,
+      ingressEnvelope('/approve', 'forged-approval-route', {
+        conversationId: 'Nova:discord:other-channel',
+      }),
+    );
+    await gateway.handleDiscordStop(
+      client as never,
+      ingressEnvelope('/stop forged', 'forged-stop-route', {
+        conversationId: 'Nova:discord:other-channel',
+      }),
+    );
+
+    expect(client.emit).not.toHaveBeenCalledWith('discord:approval', expect.anything());
+    expect(client.emit).not.toHaveBeenCalledWith('discord:stop', expect.anything());
+  });
+
   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 fleet runtime-1', 'member-approve'),
+      ingressEnvelope('/approve', 'member-approve'),
     );
     expect(client.emit).toHaveBeenCalledWith('discord:approval', {
       correlationId: 'correlation-001',
@@ -306,7 +370,7 @@ describe('Discord ingress security', () => {
     process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([]);
     await gateway.handleDiscordStop(
       client as never,
-      ingressEnvelope('/stop fleet runtime-1 forged', 'unpaired-stop'),
+      ingressEnvelope('/stop forged', 'unpaired-stop'),
     );
     expect(client.emit).not.toHaveBeenCalledWith('discord:stop', expect.anything());
   });
@@ -316,7 +380,7 @@ describe('Discord ingress security', () => {
     const { gateway, client } = discordGateway('admin');
     await gateway.handleDiscordApproval(
       client as never,
-      ingressEnvelope('/approve fleet runtime-1', 'replay-approve', {
+      ingressEnvelope('/approve', 'replay-approve', {
         correlationId: 'replay-approval-correlation',
       }),
     );
@@ -327,13 +391,13 @@ describe('Discord ingress security', () => {
     };
     await gateway.handleDiscordStop(
       client as never,
-      ingressEnvelope(`/stop fleet runtime-1 ${approval.approvalId}`, 'replay-stop-one', {
+      ingressEnvelope(`/stop ${approval.approvalId}`, 'replay-stop-one', {
         correlationId: 'replay-stop-correlation-one',
       }),
     );
     await gateway.handleDiscordStop(
       client as never,
-      ingressEnvelope(`/stop fleet runtime-1 ${approval.approvalId}`, 'replay-stop-two', {
+      ingressEnvelope(`/stop ${approval.approvalId}`, 'replay-stop-two', {
         correlationId: 'replay-stop-correlation-two',
       }),
     );
@@ -344,6 +408,267 @@ describe('Discord ingress security', () => {
     ]);
   });
 
+  it.each([
+    'https://user:[email protected]/diagram.png',
+    'https://cdn.example.test/diagram.png?token=secret',
+    'https://cdn.example.test/diagram.png?X-Amz-Signature=secret',
+    'https://cdn.example.test/diagram.png?auth=secret',
+    'https://cdn.example.test/diagram.png?hm=secret',
+  ])('rejects credential-bearing attachment URLs before gateway dispatch', async (url) => {
+    configureDiscordEnv();
+    const { gateway, client } = discordGateway('admin');
+
+    await gateway.handleMessage(
+      client as never,
+      ingressEnvelope('', `credential-url-${url.length}`, {
+        conversationId: 'Nova:discord:channel-001',
+        attachments: [
+          { id: 'attachment-credential', name: 'diagram.png', url, contentType: 'image/png' },
+        ],
+      }),
+    );
+
+    expect(client.emit).not.toHaveBeenCalledWith('message:ack', expect.anything());
+  });
+
+  it("selects each binding's trusted logical-agent config when creating Discord sessions", async () => {
+    configureDiscordEnv();
+    process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001,channel-002';
+    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
+      {
+        instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
+        guildId: 'guild-001',
+        channelId: 'channel-001',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+      {
+        instanceId: 'Orion',
+        agentConfigId: 'agent-config-orion',
+        guildId: 'guild-001',
+        channelId: 'channel-002',
+        pairedUsers: {
+          'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' },
+        },
+      },
+    ]);
+    const session = {
+      provider: 'configured-provider',
+      modelId: 'configured-model',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const createSession = vi.fn().mockResolvedValue(session);
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(undefined),
+      createSession,
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      prompt: vi.fn().mockResolvedValue(undefined),
+    };
+    const brain = {
+      agents: {
+        findById: vi.fn((id: string) =>
+          Promise.resolve({
+            id,
+            name: id === 'agent-config-orion' ? 'Orion' : 'Nova',
+          }),
+        ),
+      },
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        findMessages: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+    const routingEngine = { resolve: vi.fn() };
+    const gateway = new ChatGateway(
+      agentService as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      routingEngine as never,
+    );
+    const client = {
+      id: 'discord-client-new-session',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+
+    await gateway.handleMessage(
+      client as never,
+      ingressEnvelope('start configured session', 'configured-session-001', {
+        conversationId: 'Nova:discord:channel-001',
+      }),
+    );
+
+    await gateway.handleMessage(
+      client as never,
+      ingressEnvelope('start second configured session', 'configured-session-002', {
+        channelId: 'channel-002',
+        conversationId: 'Orion:discord:channel-002',
+      }),
+    );
+
+    expect(createSession).toHaveBeenCalledWith(
+      'Nova:discord:channel-001',
+      expect.objectContaining({
+        agentConfigId: 'agent-config-nova',
+        userId: 'discord-service',
+        tenantId: 'tenant-discord',
+      }),
+    );
+    expect(createSession).toHaveBeenCalledWith(
+      'Orion:discord:channel-002',
+      expect.objectContaining({ agentConfigId: 'agent-config-orion' }),
+    );
+    expect(routingEngine.resolve).not.toHaveBeenCalled();
+  });
+
+  it('retains validated persisted attachments in resumed conversation history', async () => {
+    const attachment = {
+      id: 'attachment-history',
+      name: 'diagram.png',
+      url: 'https://cdn.example.test/diagram.png',
+      mimeType: 'image/png',
+      sizeBytes: 4_096,
+    };
+    const gateway = new ChatGateway(
+      {} as never,
+      {} as never,
+      {
+        conversations: {
+          findMessages: vi.fn().mockResolvedValue([
+            {
+              role: 'user',
+              content: '',
+              createdAt: new Date('2026-07-14T12:00:00.000Z'),
+              metadata: { channelAttachments: [attachment] },
+            },
+          ]),
+        },
+      } as never,
+      {} as never,
+      {} as never,
+      {} as never,
+    ) as unknown as {
+      loadConversationHistory(
+        conversationId: string,
+        userId: string,
+      ): Promise<Array<{ attachments?: readonly (typeof attachment)[] }>>;
+    };
+
+    await expect(
+      gateway.loadConversationHistory('Nova:discord:channel-001', 'discord-service'),
+    ).resolves.toEqual([expect.objectContaining({ attachments: [attachment] })]);
+  });
+
+  it('rejects malformed signed attachment payloads before gateway dispatch', async () => {
+    configureDiscordEnv();
+    const { gateway, client } = discordGateway('admin');
+    const malformedPayload: Record<string, unknown> = {
+      ...createPayload({
+        messageId: 'malformed-attachments-001',
+        conversationId: 'Nova:discord:channel-001',
+      }),
+      attachments: { id: 'not-an-array' },
+    };
+    const envelope = createDiscordIngressEnvelope(
+      malformedPayload as unknown as DiscordIngressPayload,
+      SERVICE_TOKEN,
+    );
+
+    await gateway.handleMessage(client as never, envelope);
+
+    expect(client.emit).not.toHaveBeenCalledWith('message:ack', expect.anything());
+  });
+
+  it('preserves authenticated attachment metadata through persistence and agent dispatch', async () => {
+    configureDiscordEnv();
+    const prompt = vi.fn().mockResolvedValue(undefined);
+    const addMessage = vi.fn().mockResolvedValue(undefined);
+    const session = {
+      provider: 'test-provider',
+      modelId: 'test-model',
+      piSession: {
+        thinkingLevel: 'medium',
+        getAvailableThinkingLevels: (): string[] => ['medium'],
+      },
+    };
+    const agentService = {
+      getSession: vi.fn().mockReturnValue(session),
+      recordMessage: vi.fn(),
+      onEvent: vi.fn().mockReturnValue((): void => undefined),
+      addChannel: vi.fn(),
+      prompt,
+    };
+    const brain = {
+      conversations: {
+        findById: vi.fn().mockResolvedValue({ id: 'Nova:discord:channel-001' }),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        addMessage,
+      },
+    };
+    const gateway = new ChatGateway(
+      agentService as never,
+      {} as never,
+      brain as never,
+      {} as never,
+      {} as never,
+      {} as never,
+    );
+    const client = {
+      id: 'discord-client-001',
+      data: { discordService: true },
+      emit: vi.fn(),
+    };
+    const attachment = {
+      id: 'attachment-001',
+      name: 'diagram.png',
+      url: 'https://cdn.example.test/diagram.png',
+      contentType: 'image/png',
+      sizeBytes: 4_096,
+    };
+
+    await gateway.handleMessage(
+      client as never,
+      ingressEnvelope('', 'attachment-message-001', {
+        conversationId: 'Nova:discord:channel-001',
+        attachments: [attachment],
+      }),
+    );
+
+    const expectedAttachment = {
+      id: attachment.id,
+      name: attachment.name,
+      url: attachment.url,
+      mimeType: attachment.contentType,
+      sizeBytes: attachment.sizeBytes,
+    };
+    expect(prompt).toHaveBeenCalledWith(
+      'Nova:discord:channel-001',
+      '',
+      { userId: 'discord-service', tenantId: 'tenant-discord' },
+      [expectedAttachment],
+    );
+    expect(addMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        conversationId: 'Nova:discord:channel-001',
+        metadata: expect.objectContaining({ channelAttachments: [expectedAttachment] }),
+      }),
+      'discord-service',
+    );
+  });
+
   it('accepts a thread message through its allowed bound parent channel', () => {
     const emitted = vi.fn();
     const plugin = new DiscordPlugin({
@@ -356,6 +681,7 @@ describe('Discord ingress security', () => {
       interactionBindings: [
         {
           instanceId: 'Nova',
+          agentConfigId: 'agent-config-nova',
           guildId: 'guild-001',
           channelId: 'channel-001',
           pairedUsers: { 'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' } },

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

@@ -61,6 +61,16 @@ function requiredDiscordAllowlist(name: string): string[] {
   return value;
 }
 
+function optionalPositiveInteger(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer when configured`);
+  }
+  return value;
+}
+
 function createPluginRegistry(): IChannelPlugin[] {
   const plugins: IChannelPlugin[] = [];
   const discordToken = process.env['DISCORD_BOT_TOKEN'];
@@ -82,6 +92,10 @@ function createPluginRegistry(): IChannelPlugin[] {
           guildId: discordGuildId,
           gatewayUrl: discordGatewayUrl,
           serviceToken: discordServiceToken,
+          messageRateLimitPerMinute: optionalPositiveInteger(
+            'DISCORD_MESSAGE_RATE_LIMIT_PER_MINUTE',
+          ),
+          threadRateLimitPerMinute: optionalPositiveInteger('DISCORD_THREAD_RATE_LIMIT_PER_MINUTE'),
           allowedGuildIds: requiredDiscordAllowlist('DISCORD_ALLOWED_GUILD_IDS'),
           allowedChannelIds: requiredDiscordAllowlist('DISCORD_ALLOWED_CHANNEL_IDS'),
           allowedUserIds: requiredDiscordAllowlist('DISCORD_ALLOWED_USER_IDS'),

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

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import type { MosaicConfig } from '@mosaicstack/config';
+import { SystemOverrideService } from './system-override.service.js';
+
+const localConfig = { queue: { type: 'local' } } as MosaicConfig;
+
+describe('SystemOverrideService local tier', () => {
+  it('keeps ephemeral overrides isolated by tenant and user scope', async () => {
+    const service = new SystemOverrideService(localConfig);
+    const firstScope = { tenantId: 'tenant-a', userId: 'user-a' };
+    const secondScope = { tenantId: 'tenant-b', userId: 'user-b' };
+
+    await service.set('shared-session', 'first override', firstScope);
+    await service.set('shared-session', 'second override', secondScope);
+
+    await expect(service.get('shared-session', firstScope)).resolves.toBe('first override');
+    await expect(service.get('shared-session', secondScope)).resolves.toBe('second override');
+
+    await service.clear('shared-session', firstScope);
+    await expect(service.get('shared-session', firstScope)).resolves.toBeNull();
+    await expect(service.get('shared-session', secondScope)).resolves.toBe('second override');
+  });
+});

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

@@ -1,6 +1,8 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable, Logger, Optional, type OnApplicationShutdown } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
+import type { MosaicConfig } from '@mosaicstack/config';
 import type { ActorTenantScope } from '../auth/session-scope.js';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 
 const scopedSessionId = (sessionId: string, scope: ActorTenantScope) =>
   `${scope.tenantId}:${scope.userId}:${sessionId}`;
@@ -15,16 +17,45 @@ interface OverrideFragment {
   addedAt: number;
 }
 
-@Injectable()
-export class SystemOverrideService {
-  private readonly logger = new Logger(SystemOverrideService.name);
-  private readonly handle: QueueHandle;
+interface LocalOverrideEntry {
+  condensed: string;
+  fragments: OverrideFragment[];
+}
 
-  constructor() {
-    this.handle = createQueue();
+@Injectable()
+export class SystemOverrideService implements OnApplicationShutdown {
+  private readonly logger = new Logger(SystemOverrideService.name);
+  private readonly handle: QueueHandle | null;
+  /** Local-tier fallback, keyed by the same tenant/user/session scope as Redis. */
+  private readonly localStore = new Map<string, LocalOverrideEntry>();
+
+  constructor(
+    @Optional()
+    @Inject(MOSAIC_CONFIG)
+    private readonly mosaicConfig: MosaicConfig | null,
+  ) {
+    this.handle = this.mosaicConfig?.queue?.type === 'local' ? null : createQueue();
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    await this.handle?.close().catch(() => {});
   }
 
   async set(sessionId: string, override: string, scope: ActorTenantScope): Promise<void> {
+    if (!this.handle) {
+      const key = scopedSessionId(sessionId, scope);
+      const entry = this.localStore.get(key) ?? { condensed: '', fragments: [] };
+      entry.fragments.push({ text: override, addedAt: Date.now() });
+      entry.condensed = await this.condenseOverrides(
+        entry.fragments.map((fragment) => fragment.text),
+      );
+      this.localStore.set(key, entry);
+      this.logger.debug(
+        `Set system override for session ${sessionId} (local, ${entry.fragments.length} fragment(s))`,
+      );
+      return;
+    }
+
     // Load existing fragments
     const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope));
     const fragments: OverrideFragment[] = existing
@@ -54,10 +85,14 @@ export class SystemOverrideService {
   }
 
   async get(sessionId: string, scope: ActorTenantScope): Promise<string | null> {
+    if (!this.handle) {
+      return this.localStore.get(scopedSessionId(sessionId, scope))?.condensed ?? null;
+    }
     return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId, scope));
   }
 
   async renew(sessionId: string, scope: ActorTenantScope): Promise<void> {
+    if (!this.handle) return;
     const pipeline = this.handle.redis.pipeline();
     pipeline.expire(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
     pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
@@ -65,6 +100,11 @@ export class SystemOverrideService {
   }
 
   async clear(sessionId: string, scope: ActorTenantScope): Promise<void> {
+    if (!this.handle) {
+      this.localStore.delete(scopedSessionId(sessionId, scope));
+      this.logger.debug(`Cleared system override for session ${sessionId} (local)`);
+      return;
+    }
     await this.handle.redis.del(
       SESSION_SYSTEM_KEY(sessionId, scope),
       SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),

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

@@ -0,0 +1,36 @@
+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.removeRepeatableJobs('mosaic-test', 'local-noop')).resolves.toBe(0);
+    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,7 +8,9 @@ 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';
 
 // ---------------------------------------------------------------------------
@@ -108,21 +110,42 @@ 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.connection = getConnection();
+    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;
   }
 
   onModuleInit(): void {
-    this.logger.log('QueueService initialised (BullMQ)');
+    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',
+      );
+    }
   }
 
   async onModuleDestroy(): Promise<void> {
-    await this.closeAll();
+    if (this.enabled) {
+      await this.closeAll();
+    }
   }
 
   // -------------------------------------------------------------------------
@@ -131,8 +154,10 @@ 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> {
+  getQueue<T extends MosaicJobData = MosaicJobData>(name: string): Queue<T> | null {
+    if (!this.enabled) return null;
     let queue = this.queues.get(name) as Queue<T> | undefined;
     if (!queue) {
       queue = new Queue<T>(name, { connection: this.connection });
@@ -144,6 +169,7 @@ 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,
@@ -151,7 +177,13 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
     data: T,
     cronExpression: string,
   ): Promise<void> {
-    const queue = this.getQueue<T>(queueName);
+    if (!this.enabled) {
+      this.logger.debug(
+        `Skipping repeatable job "${jobName}" on "${queueName}" (local tier — BullMQ disabled)`,
+      );
+      return;
+    }
+    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 },
@@ -167,7 +199,14 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * safe retirement of previously registered system-wide jobs.
    */
   async removeRepeatableJobs(queueName: string, jobName: string): Promise<number> {
+    if (!this.enabled) {
+      this.logger.debug(
+        `Skipping repeatable-job removal for "${jobName}" on "${queueName}" (local tier — BullMQ disabled)`,
+      );
+      return 0;
+    }
     const queue = this.getQueue(queueName);
+    if (!queue) return 0;
     const jobs = await queue.getRepeatableJobs();
     const matchingJobs = jobs.filter((job) => job.name === jobName);
     await Promise.all(matchingJobs.map((job) => queue.removeRepeatableByKey(job.key)));
@@ -182,8 +221,18 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   /**
    * 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> {
+  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;
+    }
     const worker = new Worker<T>(
       queueName,
       async (job) => {
@@ -240,8 +289,12 @@ 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;
 
@@ -272,8 +325,10 @@ 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]
@@ -300,8 +355,10 @@ 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>".' };
@@ -333,6 +390,7 @@ 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();
@@ -344,6 +402,7 @@ 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();

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

@@ -1,5 +1,8 @@
+import { Logger } from '@nestjs/common';
 import { describe, expect, it, vi } from 'vitest';
+import type { SlashCommandPayload, SystemReloadPayload } from '@mosaicstack/types';
 import { ReloadService } from './reload.service.js';
+import { CommandExecutorService } from '../commands/command-executor.service.js';
 
 function createMockCommandRegistry() {
   return {
@@ -104,3 +107,79 @@ describe('ReloadService', () => {
     expect(() => service.registerPlugin('my-plugin', {})).not.toThrow();
   });
 });
+
+describe('ReloadService — /reload command sanitizes plugin errors', () => {
+  it('generic per-plugin errors reach the chat surface while raw markers stay server-side only', async () => {
+    const registry = {
+      getManifest: vi.fn().mockReturnValue({
+        version: 1,
+        commands: [
+          { name: 'reload', aliases: [], scope: 'core', execution: 'socket', available: true },
+        ],
+        skills: [],
+      }),
+    };
+    const reloadService = new ReloadService(registry as never);
+
+    const RELOAD_LOAD_LEAK_MARKER = 'RELOAD_LOAD_LEAK_MARKER /srv/load-secret';
+    const RELOAD_UNLOAD_LEAK_MARKER = 'RELOAD_UNLOAD_LEAK_MARKER /srv/unload-secret';
+
+    reloadService.registerPlugin('unload-fails', {
+      pluginName: 'unload-fails',
+      onLoad: vi.fn().mockResolvedValue(undefined),
+      onUnload: vi.fn().mockRejectedValue(new Error(RELOAD_UNLOAD_LEAK_MARKER)),
+    });
+    reloadService.registerPlugin('load-fails', {
+      pluginName: 'load-fails',
+      onLoad: vi.fn().mockRejectedValue(new Error(RELOAD_LOAD_LEAK_MARKER)),
+      onUnload: vi.fn().mockResolvedValue(undefined),
+    });
+
+    const errorSpy = vi.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+    const broadcastReload = vi.fn();
+    const mockChatGateway = { broadcastReload };
+    const mockAgentService = { getSession: vi.fn(), applyAgentConfig: vi.fn() };
+    const mockSystemOverride = { set: vi.fn(), get: vi.fn(), clear: vi.fn() };
+    const mockSessionGC = { sweepOrphans: vi.fn() };
+    const mockBrain = { agents: { findByName: vi.fn(), findById: vi.fn(), create: vi.fn() } };
+
+    const executor = new CommandExecutorService(
+      registry as never,
+      mockAgentService as never,
+      mockSystemOverride as never,
+      mockSessionGC as never,
+      null,
+      mockBrain as never,
+      reloadService,
+      mockChatGateway as never,
+      null,
+    );
+
+    const payload: SlashCommandPayload = { command: 'reload', conversationId: 'conv-1' };
+    const result = await executor.execute(payload, { userId: 'user-1', tenantId: 'user-1' });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('unload-fails: unload failed (internal error)');
+    expect(result.message).toContain('load-fails: load failed (internal error)');
+    expect(result.message).not.toContain(RELOAD_UNLOAD_LEAK_MARKER);
+    expect(result.message).not.toContain(RELOAD_LOAD_LEAK_MARKER);
+
+    expect(broadcastReload).toHaveBeenCalledOnce();
+    const broadcastPayload = broadcastReload.mock.calls[0]?.[0] as SystemReloadPayload;
+    expect(broadcastPayload.message).toContain('unload-fails: unload failed (internal error)');
+    expect(broadcastPayload.message).toContain('load-fails: load failed (internal error)');
+    expect(broadcastPayload.message).not.toContain(RELOAD_UNLOAD_LEAK_MARKER);
+    expect(broadcastPayload.message).not.toContain(RELOAD_LOAD_LEAK_MARKER);
+
+    const loggedUnloadMarker = errorSpy.mock.calls.some((call) =>
+      call.some((arg) => typeof arg === 'string' && arg.includes(RELOAD_UNLOAD_LEAK_MARKER)),
+    );
+    const loggedLoadMarker = errorSpy.mock.calls.some((call) =>
+      call.some((arg) => typeof arg === 'string' && arg.includes(RELOAD_LOAD_LEAK_MARKER)),
+    );
+    expect(loggedUnloadMarker).toBe(true);
+    expect(loggedLoadMarker).toBe(true);
+
+    errorSpy.mockRestore();
+  });
+});

apps/gateway/src/reload/reload.service.ts

@@ -58,7 +58,8 @@ export class ReloadService implements OnApplicationBootstrap, OnApplicationShutd
           await plugin.onUnload();
           reloaded.push(name);
         } catch (err) {
-          errors.push(`${name}: unload failed — ${err}`);
+          this.logger.error(`Plugin "${name}" failed during onUnload: ${err}`);
+          errors.push(`${name}: unload failed (internal error)`);
         }
       }
     }
@@ -69,7 +70,8 @@ export class ReloadService implements OnApplicationBootstrap, OnApplicationShutd
         try {
           await plugin.onLoad();
         } catch (err) {
-          errors.push(`${name}: load failed — ${err}`);
+          this.logger.error(`Plugin "${name}" failed during onLoad: ${err}`);
+          errors.push(`${name}: load failed (internal error)`);
         }
       }
     }

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

@@ -0,0 +1,104 @@
+import 'reflect-metadata';
+import {
+  type CanActivate,
+  type ExecutionContext,
+  type INestApplication,
+  ValidationPipe,
+} from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { ProjectBootstrapService } from './project-bootstrap.service.js';
+import { WorkspaceController } from './workspace.controller.js';
+
+const bootstrapMock = vi.fn(() =>
+  Promise.resolve({
+    projectId: 'project-1',
+    workspacePath: '/opt/mosaic/.workspaces/users/user-1/project-1',
+  }),
+);
+
+const authGuard: CanActivate = {
+  canActivate(context: ExecutionContext): boolean {
+    const requestContext = context.switchToHttp().getRequest<{ user?: { id: string } }>();
+    requestContext.user = { id: 'user-1' };
+    return true;
+  },
+};
+
+describe('POST /api/workspaces repoUrl validation', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [WorkspaceController],
+      providers: [
+        {
+          provide: ProjectBootstrapService,
+          useValue: { bootstrap: bootstrapMock },
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(authGuard)
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    app.useGlobalPipes(
+      new ValidationPipe({
+        whitelist: true,
+        forbidNonWhitelisted: true,
+        transform: true,
+      }),
+    );
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  beforeEach(() => {
+    bootstrapMock.mockClear();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it.each([
+    ['a leading-dash value', '--upload-pack=sh -c id'],
+    ['an ext remote helper', 'ext::sh -c id'],
+    ['a file URL', 'file:///tmp/repository'],
+    ['an unparseable value', 'not a url'],
+    ['an SSH shorthand', '[email protected]:acme/repository.git'],
+    ['a scheme without //', 'https:example.com/acme/repository.git'],
+    ['a hostless git URL', 'git:///tmp/repository'],
+  ])('returns 400 for %s', async (_description, repoUrl) => {
+    const response = await request(app.getHttpServer())
+      .post('/api/workspaces')
+      .send({ name: 'Example', repoUrl })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(400);
+    expect(bootstrapMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['a plain HTTPS repository URL', 'https://example.com/acme/repository.git'],
+    ['a git protocol repository URL', 'git://example.com/acme/repository.git'],
+  ])('accepts %s', async (_description, repoUrl) => {
+    const response = await request(app.getHttpServer())
+      .post('/api/workspaces')
+      .send({ name: 'Example', repoUrl })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(201);
+    expect(bootstrapMock).toHaveBeenCalledWith({
+      name: 'Example',
+      description: undefined,
+      userId: 'user-1',
+      teamId: undefined,
+      repoUrl,
+    });
+  });
+});

apps/gateway/src/workspace/workspace.controller.ts

@@ -1,7 +1,11 @@
 import { Body, Controller, Post, UseGuards } from '@nestjs/common';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
-import { ProjectBootstrapService } from './project-bootstrap.service.js';
+import {
+  ProjectBootstrapService,
+  type BootstrapProjectResult,
+} from './project-bootstrap.service.js';
+import { CreateWorkspaceDto } from './workspace.dto.js';
 
 @Controller('api/workspaces')
 @UseGuards(AuthGuard)
@@ -11,20 +15,14 @@ export class WorkspaceController {
   @Post()
   async create(
     @CurrentUser() user: { id: string },
-    @Body()
-    body: {
-      name: string;
-      description?: string;
-      teamId?: string;
-      repoUrl?: string;
-    },
-  ) {
+    @Body() dto: CreateWorkspaceDto,
+  ): Promise<BootstrapProjectResult> {
     return this.bootstrap.bootstrap({
-      name: body.name,
-      description: body.description,
+      name: dto.name,
+      description: dto.description,
       userId: user.id,
-      teamId: body.teamId,
-      repoUrl: body.repoUrl,
+      teamId: dto.teamId,
+      repoUrl: dto.repoUrl,
     });
   }
 }

apps/gateway/src/workspace/workspace.dto.ts

@@ -0,0 +1,33 @@
+import { IsOptional, IsString, IsUrl, Matches, MaxLength } from 'class-validator';
+
+export class CreateWorkspaceDto {
+  @IsString()
+  @MaxLength(255)
+  name!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
+  description?: string;
+
+  @IsOptional()
+  @IsString()
+  teamId?: string;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^(?:https|git):\/\//i, {
+    message: 'repoUrl must be a valid https:// or git:// URL',
+  })
+  @IsUrl(
+    {
+      protocols: ['https', 'git'],
+      require_host: true,
+      require_protocol: true,
+      require_tld: false,
+      require_valid_protocol: true,
+    },
+    { message: 'repoUrl must be a valid https:// or git:// URL' },
+  )
+  repoUrl?: string;
+}

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

@@ -1,11 +1,33 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { WorkspaceService } from './workspace.service.js';
+import { BadRequestException } from '@nestjs/common';
+import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { WorkspaceService } from './workspace.service.js';
+
+type ExecFileMock = (
+  command: string,
+  args: readonly string[],
+  options: { cwd: string },
+  callback: (error: Error | null, stdout: string, stderr: string) => void,
+) => void;
+
+const { execFileMock } = vi.hoisted(() => ({
+  execFileMock: vi.fn<ExecFileMock>(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: execFileMock,
+}));
 
 describe('WorkspaceService', () => {
   let service: WorkspaceService;
 
   beforeEach(() => {
+    execFileMock.mockReset();
+    execFileMock.mockImplementation((_command, _args, _options, callback) => {
+      callback(null, '', '');
+    });
     service = new WorkspaceService();
   });
 
@@ -76,4 +98,69 @@ describe('WorkspaceService', () => {
       }
     });
   });
+
+  describe('create', () => {
+    const project = {
+      id: 'project-1',
+      ownerType: 'user',
+      userId: 'user-1',
+      teamId: null,
+    } as const;
+
+    let originalRoot: string | undefined;
+    let temporaryRoot: string;
+
+    beforeEach(async () => {
+      originalRoot = process.env['MOSAIC_ROOT'];
+      temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'mosaic-workspace-'));
+      process.env['MOSAIC_ROOT'] = temporaryRoot;
+      service = new WorkspaceService();
+    });
+
+    afterEach(async () => {
+      if (originalRoot === undefined) {
+        delete process.env['MOSAIC_ROOT'];
+      } else {
+        process.env['MOSAIC_ROOT'] = originalRoot;
+      }
+      await fs.rm(temporaryRoot, { recursive: true, force: true });
+    });
+
+    it.each([
+      ['a leading-dash URL', '--upload-pack=sh -c id'],
+      ['an ext remote helper', 'ext::sh -c id'],
+      ['a file URL', 'file:///tmp/repository'],
+      ['an unparseable value', 'not a url'],
+      ['an SSH shorthand', '[email protected]:acme/repository.git'],
+      ['a scheme without //', 'https:example.com/acme/repository.git'],
+      ['a hostless git URL', 'git:///tmp/repository'],
+    ])('rejects %s before invoking git', async (_description, repoUrl) => {
+      await expect(service.create(project, repoUrl)).rejects.toBeInstanceOf(BadRequestException);
+      expect(execFileMock).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['an HTTPS URL', 'https://example.com/acme/repository.git'],
+      ['a git protocol URL', 'git://example.com/acme/repository.git'],
+    ])('accepts %s and invokes hardened git clone arguments', async (_description, repoUrl) => {
+      const workspacePath = await service.create(project, repoUrl);
+
+      expect(execFileMock).toHaveBeenCalledOnce();
+      expect(execFileMock).toHaveBeenCalledWith(
+        'git',
+        [
+          '-c',
+          'protocol.ext.allow=never',
+          '-c',
+          'protocol.file.allow=never',
+          'clone',
+          '--',
+          repoUrl,
+          '.',
+        ],
+        { cwd: workspacePath },
+        expect.any(Function),
+      );
+    });
+  });
 });

apps/gateway/src/workspace/workspace.service.ts

@@ -1,10 +1,30 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
+const allowedRepositoryProtocols = new Set(['https:', 'git:']);
+const repositoryUrlPrefixPattern = /^(?:https|git):\/\//i;
+const repositoryUrlError = 'repoUrl must be a valid https:// or git:// URL';
+
+function assertAllowedRepositoryUrl(repoUrl: string): void {
+  if (repoUrl.startsWith('-') || !repositoryUrlPrefixPattern.test(repoUrl)) {
+    throw new BadRequestException(repositoryUrlError);
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(repoUrl);
+  } catch {
+    throw new BadRequestException(repositoryUrlError);
+  }
+
+  if (!allowedRepositoryProtocols.has(parsedUrl.protocol) || parsedUrl.hostname.length === 0) {
+    throw new BadRequestException(repositoryUrlError);
+  }
+}
 
 export interface WorkspaceProject {
   id: string;
@@ -39,14 +59,32 @@ export class WorkspaceService {
    * If repoUrl is provided, clone instead of init.
    */
   async create(project: WorkspaceProject, repoUrl?: string): Promise<string> {
+    if (repoUrl !== undefined) {
+      assertAllowedRepositoryUrl(repoUrl);
+    }
+
     const workspacePath = this.resolvePath(project);
 
     // Create directory
     await fs.mkdir(workspacePath, { recursive: true });
 
-    if (repoUrl) {
-      // Clone existing repo
-      await execFileAsync('git', ['clone', repoUrl, '.'], { cwd: workspacePath });
+    if (repoUrl !== undefined) {
+      // Clone existing repo. Defense in depth keeps dangerous local helpers
+      // disabled and terminates option parsing before positional arguments.
+      await execFileAsync(
+        'git',
+        [
+          '-c',
+          'protocol.ext.allow=never',
+          '-c',
+          'protocol.file.allow=never',
+          'clone',
+          '--',
+          repoUrl,
+          '.',
+        ],
+        { cwd: workspacePath },
+      );
       this.logger.log(`Cloned ${repoUrl} into workspace ${workspacePath}`);
     } else {
       // Init new git repo

apps/web/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Mosaic</title>
+    <meta name="description" content="Mosaic Stack Dashboard" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Fira+Code:wght@400;500&display=swap"
+    />
+    <script>
+      // set data-theme before first paint so the stored theme never flashes
+      (function () {
+        try {
+          var theme = window.localStorage.getItem('mosaic-theme') || 'dark';
+          document.documentElement.setAttribute('data-theme', theme === 'light' ? 'light' : 'dark');
+        } catch (error) {
+          document.documentElement.setAttribute('data-theme', 'dark');
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/web/package.json

@@ -3,8 +3,10 @@
   "version": "0.0.2",
   "private": true,
   "scripts": {
-    "build": "next build",
+    "build": "node ../../scripts/build-web.mjs",
+    "build:vite": "vite build",
     "dev": "next dev",
+    "dev:vite": "vite",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
@@ -13,12 +15,14 @@
   },
   "dependencies": {
     "@mosaicstack/design-tokens": "workspace:^",
+    "@mosaicstack/types": "workspace:^",
     "better-auth": "^1.5.5",
     "clsx": "^2.1.0",
     "next": "^16.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.18.2",
     "socket.io-client": "^4.8.0",
     "tailwind-merge": "^3.5.0"
   },
@@ -28,9 +32,11 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.5",
     "jsdom": "^29.0.0",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.8.0",
-    "vitest": "^2.0.0"
+    "vite": "^8.2.1",
+    "vitest": "^3.2.7"
   }
 }

apps/web/src/app/auth/provider/[provider]/page.tsx

@@ -3,41 +3,56 @@
 import Link from 'next/link';
 import { useEffect, useState } from 'react';
 import { useParams, useSearchParams } from 'next/navigation';
+import { api } from '@/lib/api';
+import { resolveAuthCallbackURL } from '@/lib/auth-redirect';
 import { signIn } from '@/lib/auth-client';
-import { getSsoProvider } from '@/lib/sso-providers';
+import type { SsoProviderDiscovery } from '@/lib/sso';
 
 export default function AuthProviderRedirectPage(): React.ReactElement {
   const params = useParams<{ provider: string }>();
   const searchParams = useSearchParams();
   const providerId = typeof params.provider === 'string' ? params.provider : '';
-  const provider = getSsoProvider(providerId);
-  const callbackURL = searchParams.get('callbackURL') ?? '/chat';
+  const requestedCallbackURL = searchParams.get('callbackURL');
+  const [providerName, setProviderName] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
-    const currentProvider = provider;
-
-    if (!currentProvider) {
-      setError('Unknown SSO provider.');
-      return;
-    }
-
-    if (!currentProvider.enabled) {
-      setError(`${currentProvider.buttonLabel} is not enabled in this deployment.`);
-      return;
-    }
-
-    const activeProvider = currentProvider;
     let cancelled = false;
 
     async function redirectToProvider(): Promise<void> {
-      const result = await signIn.oauth2({
-        providerId: activeProvider.id,
-        callbackURL,
-      });
+      try {
+        const callbackURL = resolveAuthCallbackURL(requestedCallbackURL, window.location.origin);
+        const providers = await api<SsoProviderDiscovery[]>('/api/sso/providers');
+        if (cancelled) return;
 
-      if (!cancelled && result?.error) {
-        setError(result.error.message ?? `${activeProvider.buttonLabel} sign in failed.`);
+        const provider = providers.find((candidate) => candidate.id === providerId);
+        if (!provider) {
+          setError('Unknown SSO provider.');
+          return;
+        }
+
+        setProviderName(provider.name);
+        if (!provider.configured) {
+          setError(`${provider.name} is not enabled in this deployment.`);
+          return;
+        }
+        if (provider.loginMode !== 'oidc') {
+          setError(`${provider.name} is not available for OIDC sign in.`);
+          return;
+        }
+
+        const result = await signIn.oauth2({
+          providerId: provider.id,
+          callbackURL,
+        });
+
+        if (!cancelled && result?.error) {
+          setError(result.error.message ?? `${provider.name} sign in failed.`);
+        }
+      } catch (caught: unknown) {
+        if (!cancelled) {
+          setError(caught instanceof Error ? caught.message : 'Unable to start single sign-on.');
+        }
       }
     }
 
@@ -46,19 +61,22 @@ export default function AuthProviderRedirectPage(): React.ReactElement {
     return () => {
       cancelled = true;
     };
-  }, [callbackURL, provider]);
+  }, [providerId, requestedCallbackURL]);
 
   return (
     <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
       <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
       <p className="mt-2 text-sm text-text-secondary">
-        {provider
-          ? `Redirecting you to ${provider.buttonLabel.replace('Continue with ', '')}...`
+        {providerName
+          ? `Redirecting you to ${providerName}...`
           : 'Preparing your sign-in request...'}
       </p>
 
       {error ? (
-        <div className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error">
+        <div
+          role="alert"
+          className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
           <p>{error}</p>
           <Link
             href="/login"

apps/web/src/lib/api.spec.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { api } from './api';
+
+describe('api', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('fetches the supplied relative path with credentials and a JSON body', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(
+      api<{ ok: boolean }>('/api/projects', {
+        method: 'POST',
+        body: { name: 'Mosaic' },
+      }),
+    ).resolves.toEqual({ ok: true });
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/projects',
+      expect.objectContaining({
+        method: 'POST',
+        credentials: 'include',
+        body: JSON.stringify({ name: 'Mosaic' }),
+        headers: expect.objectContaining({
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        }),
+      }),
+    );
+  });
+
+  it('throws the gateway JSON error with its statusCode', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ statusCode: 403, message: 'Forbidden' }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(api('/api/admin/users')).rejects.toMatchObject({
+      name: 'Error',
+      message: 'Forbidden',
+      statusCode: 403,
+    });
+  });
+});

apps/web/src/lib/api.ts

@@ -1,5 +1,3 @@
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
-
 export interface ApiRequestInit extends Omit<RequestInit, 'body'> {
   body?: unknown;
 }
@@ -25,7 +23,7 @@ export async function api<T>(path: string, init?: ApiRequestInit): Promise<T> {
     headers['Content-Type'] = 'application/json';
   }
 
-  const res = await fetch(`${GATEWAY_URL}${path}`, {
+  const res = await fetch(path, {
     credentials: 'include',
     ...rest,
     headers,

apps/web/src/lib/auth-client.spec.ts

@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+describe('auth client origin contract', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('uses the same-origin BetterAuth mount at /api/auth', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ session: null, user: null }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { authClient } = await import('./auth-client');
+    await authClient.getSession();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const firstCall = fetchMock.mock.calls.at(0);
+    expect(firstCall).toBeDefined();
+    const requestURL = new URL(String(firstCall?.[0]), window.location.origin);
+    expect(requestURL.origin).toBe(window.location.origin);
+    expect(requestURL.pathname).toBe('/api/auth/get-session');
+  });
+});

apps/web/src/lib/auth-client.ts

@@ -1,8 +1,9 @@
 import { createAuthClient } from 'better-auth/react';
 import { adminClient, genericOAuthClient } from 'better-auth/client/plugins';
 
+// The gateway and BetterAuth client both use /api/auth. Omitting baseURL keeps
+// every browser request on the current origin in development and production.
 export const authClient = createAuthClient({
-  baseURL: process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242',
   plugins: [adminClient(), genericOAuthClient()],
 });
 

apps/web/src/lib/auth-redirect.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { resolveAuthCallbackURL } from './auth-redirect';
+
+const CURRENT_ORIGIN = 'https://mosaic.example';
+
+describe('resolveAuthCallbackURL', () => {
+  it('preserves a canonical same-origin path with search and hash', () => {
+    expect(resolveAuthCallbackURL('/projects?view=active#current', CURRENT_ORIGIN)).toBe(
+      '/projects?view=active#current',
+    );
+  });
+
+  it.each([
+    null,
+    'chat',
+    '//evil.example',
+    '/..//evil.com',
+    '/..//evil.com/x',
+    '/./..//evil.com',
+    '/../..//evil.com',
+    '/foo/..//evil.com',
+    '/\\evil.example',
+    '/\n//evil.example',
+    '/\r//evil.example',
+    '/\t//evil.example',
+    'https://evil.example/phish',
+  ])('falls back to chat for an unsafe callback target %#', (candidate) => {
+    expect(resolveAuthCallbackURL(candidate, CURRENT_ORIGIN)).toBe('/chat');
+  });
+});

apps/web/src/lib/auth-redirect.ts

@@ -0,0 +1,23 @@
+const DEFAULT_AUTH_CALLBACK_URL = '/chat';
+
+/**
+ * Return a canonical same-origin path for post-auth navigation.
+ *
+ * Parsing before comparing origins rejects protocol-relative URLs, backslash
+ * variants, and control characters that the WHATWG parser normalizes away.
+ */
+export function resolveAuthCallbackURL(candidate: string | null, currentOrigin: string): string {
+  if (!candidate?.startsWith('/')) return DEFAULT_AUTH_CALLBACK_URL;
+
+  try {
+    const expectedOrigin = new URL(currentOrigin).origin;
+    const resolved = new URL(candidate, expectedOrigin);
+    if (resolved.origin !== expectedOrigin || resolved.pathname.startsWith('//')) {
+      return DEFAULT_AUTH_CALLBACK_URL;
+    }
+
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+  } catch {
+    return DEFAULT_AUTH_CALLBACK_URL;
+  }
+}

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

@@ -0,0 +1,61 @@
+// Centralizes the type-only import of the shared `/chat` Socket.IO contract from
+// the public `@mosaicstack/types` package. `import type` is erased at compile
+// time, so this introduces no runtime dependency — it only reuses the exact
+// payload shapes instead of redeclaring them.
+import type { Socket } from 'socket.io-client';
+import type {
+  AbortPayload,
+  AgentEndPayload,
+  AgentStartPayload,
+  AgentTextPayload,
+  AgentThinkingPayload,
+  ChatMessagePayload,
+  ClientToServerEvents,
+  CommandDef,
+  CommandManifest,
+  CommandManifestPayload,
+  ErrorPayload,
+  MessageAckPayload,
+  RoutingDecisionInfo,
+  ServerToClientEvents,
+  SessionInfoPayload,
+  SessionUsagePayload,
+  SetThinkingPayload,
+  SkillCommandDef,
+  SlashCommandApprovalResultPayload,
+  SlashCommandPayload,
+  SlashCommandResultPayload,
+  SystemReloadPayload,
+  ToolEndPayload,
+  ToolStartPayload,
+} from '@mosaicstack/types';
+
+export type {
+  AbortPayload,
+  AgentEndPayload,
+  AgentStartPayload,
+  AgentTextPayload,
+  AgentThinkingPayload,
+  ChatMessagePayload,
+  ClientToServerEvents,
+  CommandDef,
+  CommandManifest,
+  CommandManifestPayload,
+  ErrorPayload,
+  MessageAckPayload,
+  RoutingDecisionInfo,
+  ServerToClientEvents,
+  SessionInfoPayload,
+  SessionUsagePayload,
+  SetThinkingPayload,
+  SkillCommandDef,
+  SlashCommandApprovalResultPayload,
+  SlashCommandPayload,
+  SlashCommandResultPayload,
+  SystemReloadPayload,
+  ToolEndPayload,
+  ToolStartPayload,
+};
+
+/** The `/chat` namespace socket, narrowed to the exact typed event contract. */
+export type ChatSocket = Socket<ServerToClientEvents, ClientToServerEvents>;

apps/web/src/lib/socket.spec.ts

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { ioMock } = vi.hoisted(() => ({
+  ioMock: vi.fn(),
+}));
+
+vi.mock('socket.io-client', () => ({
+  io: ioMock,
+}));
+
+import { destroySocket, getSocket } from './socket';
+
+interface MockChatSocket {
+  on: ReturnType<typeof vi.fn>;
+  offAny: ReturnType<typeof vi.fn>;
+  disconnect: ReturnType<typeof vi.fn>;
+  /** Test-only helper: fires every handler registered for `event` via
+   * `.on`, mirroring how a real socket.io-client instance invokes its own
+   * listeners (e.g. calling the registered `disconnect` handler(s) on a
+   * real transient disconnect). */
+  trigger(event: string): void;
+}
+
+function createMockSocket(): MockChatSocket {
+  const handlers = new Map<string, Set<() => void>>();
+  const mockSocket: MockChatSocket = {
+    on: vi.fn((event: string, handler: () => void) => {
+      if (!handlers.has(event)) handlers.set(event, new Set());
+      handlers.get(event)?.add(handler);
+      return mockSocket;
+    }),
+    offAny: vi.fn(() => mockSocket),
+    disconnect: vi.fn(() => mockSocket),
+    trigger(event: string): void {
+      for (const handler of handlers.get(event) ?? []) handler();
+    },
+  };
+  return mockSocket;
+}
+
+let currentMock!: MockChatSocket;
+
+describe('chat socket', () => {
+  beforeEach(() => {
+    ioMock.mockReset();
+    // A fresh object per io() call so identity assertions (same singleton vs.
+    // a genuinely new instance) are meaningful.
+    ioMock.mockImplementation(() => {
+      currentMock = createMockSocket();
+      return currentMock;
+    });
+  });
+
+  afterEach(() => {
+    destroySocket();
+  });
+
+  it('creates one same-origin /chat namespace socket', () => {
+    const first = getSocket();
+    const second = getSocket();
+
+    expect(first).toBe(second);
+    expect(ioMock).toHaveBeenCalledOnce();
+    expect(ioMock).toHaveBeenCalledWith('/chat', {
+      withCredentials: true,
+      autoConnect: false,
+      transports: ['websocket', 'polling'],
+    });
+  });
+
+  it('keeps the same singleton instance across a transient disconnect', () => {
+    const first = getSocket();
+
+    // socket.ts must not react to a real socket's `disconnect` event by
+    // nulling the singleton — it registers no such handler at all now.
+    // Actually fire every handler registered via `.on('disconnect', ...)`
+    // (mirroring a real socket.io-client reconnect) instead of merely
+    // calling getSocket() again: this is what makes the test fail if
+    // production reintroduces `socket.on('disconnect', () => { socket =
+    // null; })`, since that handler would run here and null the singleton
+    // before the next getSocket() call.
+    currentMock.trigger('disconnect');
+    const second = getSocket();
+
+    expect(second).toBe(first);
+    expect(ioMock).toHaveBeenCalledOnce();
+  });
+
+  it('only creates a new singleton after an explicit destroySocket()', () => {
+    const first = getSocket();
+
+    destroySocket();
+    const second = getSocket();
+
+    expect(second).not.toBe(first);
+    expect(ioMock).toHaveBeenCalledTimes(2);
+  });
+});

apps/web/src/lib/socket.ts

@@ -1,23 +1,27 @@
-import { io, type Socket } from 'socket.io-client';
+import { io } from 'socket.io-client';
+import type { ChatSocket } from './chat-contract';
 
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
+let socket: ChatSocket | null = null;
 
-let socket: Socket | null = null;
-
-export function getSocket(): Socket {
+export function getSocket(): ChatSocket {
   if (!socket) {
-    socket = io(`${GATEWAY_URL}/chat`, {
+    // socket.io-client 4.8.3's `io()` factory declaration always returns the
+    // default unparameterized Socket (it accepts no <ListenEvents, EmitEvents>
+    // generics), so this one cast is the unavoidable boundary between that and the
+    // typed `/chat` contract. Every other call site uses the resulting ChatSocket
+    // with no further assertions.
+    socket = io('/chat', {
       withCredentials: true,
       autoConnect: false,
       transports: ['websocket', 'polling'],
-    });
+    }) as unknown as ChatSocket;
 
-    // Reset singleton reference when socket is fully closed so the next
-    // getSocket() call creates a fresh instance instead of returning a
-    // closed/dead socket.
-    socket.on('disconnect', () => {
-      socket = null;
-    });
+    // A transient `disconnect` (network blip, server restart) must NOT null
+    // the singleton: socket.io-client auto-reconnects this same instance,
+    // and its listeners stay registered across that reconnect. Nulling here
+    // previously orphaned those listeners on the next getSocket() call by
+    // handing back a brand-new, unconnected instance. Only destroySocket()
+    // (an explicit, intentional teardown) may reset the singleton.
   }
   return socket;
 }

apps/web/src/lib/sso-providers.test.ts

@@ -1,48 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { getEnabledSsoProviders, getSsoProvider } from './sso-providers';
-
-describe('sso-providers', () => {
-  afterEach(() => {
-    vi.unstubAllEnvs();
-  });
-
-  it('returns the enabled providers in login button order', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'true');
-
-    expect(getEnabledSsoProviders()).toEqual([
-      {
-        id: 'workos',
-        buttonLabel: 'Continue with WorkOS',
-        description: 'Enterprise SSO via WorkOS',
-        enabled: true,
-        href: '/auth/provider/workos',
-      },
-      {
-        id: 'keycloak',
-        buttonLabel: 'Continue with Keycloak',
-        description: 'Enterprise SSO via Keycloak',
-        enabled: true,
-        href: '/auth/provider/keycloak',
-      },
-    ]);
-  });
-
-  it('marks disabled providers without exposing them in the enabled list', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'false');
-
-    expect(getEnabledSsoProviders().map((provider) => provider.id)).toEqual(['workos']);
-    expect(getSsoProvider('keycloak')).toEqual({
-      id: 'keycloak',
-      buttonLabel: 'Continue with Keycloak',
-      description: 'Enterprise SSO via Keycloak',
-      enabled: false,
-      href: '/auth/provider/keycloak',
-    });
-  });
-
-  it('returns null for unknown providers', () => {
-    expect(getSsoProvider('authentik')).toBeNull();
-  });
-});

apps/web/src/lib/sso-providers.ts

@@ -1,53 +0,0 @@
-export type SsoProviderId = 'workos' | 'keycloak';
-
-export interface SsoProvider {
-  id: SsoProviderId;
-  buttonLabel: string;
-  description: string;
-  enabled: boolean;
-  href: string;
-}
-
-const PROVIDER_METADATA: Record<SsoProviderId, Omit<SsoProvider, 'enabled' | 'href'>> = {
-  workos: {
-    id: 'workos',
-    buttonLabel: 'Continue with WorkOS',
-    description: 'Enterprise SSO via WorkOS',
-  },
-  keycloak: {
-    id: 'keycloak',
-    buttonLabel: 'Continue with Keycloak',
-    description: 'Enterprise SSO via Keycloak',
-  },
-};
-
-export function getEnabledSsoProviders(): SsoProvider[] {
-  return (Object.keys(PROVIDER_METADATA) as SsoProviderId[])
-    .map((providerId) => getSsoProvider(providerId))
-    .filter((provider): provider is SsoProvider => provider?.enabled === true);
-}
-
-export function getSsoProvider(providerId: string): SsoProvider | null {
-  if (!isSsoProviderId(providerId)) {
-    return null;
-  }
-
-  return {
-    ...PROVIDER_METADATA[providerId],
-    enabled: isSsoProviderEnabled(providerId),
-    href: `/auth/provider/${providerId}`,
-  };
-}
-
-function isSsoProviderId(value: string): value is SsoProviderId {
-  return value === 'workos' || value === 'keycloak';
-}
-
-function isSsoProviderEnabled(providerId: SsoProviderId): boolean {
-  switch (providerId) {
-    case 'workos':
-      return process.env['NEXT_PUBLIC_WORKOS_ENABLED'] === 'true';
-    case 'keycloak':
-      return process.env['NEXT_PUBLIC_KEYCLOAK_ENABLED'] === 'true';
-  }
-}

apps/web/src/main.tsx

@@ -0,0 +1,19 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from 'react-router-dom';
+import { ThemeProvider } from '@/providers/theme-provider';
+import { createAppRouter } from '@/routes';
+import '@/app/globals.css';
+
+const container = document.getElementById('root');
+if (!container) {
+  throw new Error('missing #root element');
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <ThemeProvider>
+      <RouterProvider router={createAppRouter()} />
+    </ThemeProvider>
+  </StrictMode>,
+);

apps/web/src/routes.tsx

@@ -0,0 +1,51 @@
+import type { ReactElement } from 'react';
+import { createBrowserRouter, Navigate, Outlet, type RouteObject } from 'react-router-dom';
+import { LoginPage } from '@/spa/pages/login';
+import { RegisterPage } from '@/spa/pages/register';
+import { SsoCallbackPage } from '@/spa/pages/sso-callback';
+import { ChatPage } from '@/spa/pages/chat';
+import { ChatRouteErrorBoundary } from '@/spa/pages/chat-error-boundary';
+import { AuthGuard, GuestGuard } from '@/spa/guards';
+import { Placeholder } from '@/spa/placeholder';
+
+function GuestLayout(): ReactElement {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-surface-bg px-4 py-8">
+      <div className="w-full max-w-md rounded-xl border border-surface-border bg-surface-card p-8 shadow-lg">
+        <Outlet />
+      </div>
+    </div>
+  );
+}
+
+export const routes: RouteObject[] = [
+  {
+    element: <GuestGuard />,
+    children: [
+      {
+        element: <GuestLayout />,
+        children: [
+          { path: '/login', element: <LoginPage /> },
+          { path: '/register', element: <RegisterPage /> },
+          { path: '/auth/provider/:provider', element: <SsoCallbackPage /> },
+        ],
+      },
+    ],
+  },
+  {
+    element: <AuthGuard />,
+    children: [
+      { path: '/', element: <Navigate to="/chat" replace /> },
+      { path: '/chat', element: <ChatPage />, errorElement: <ChatRouteErrorBoundary /> },
+      { path: '/projects', element: <Placeholder title="Projects" /> },
+      { path: '/projects/:id', element: <Placeholder title="Project" /> },
+      { path: '/tasks', element: <Placeholder title="Tasks" /> },
+      { path: '/settings', element: <Placeholder title="Settings" /> },
+      { path: '/admin', element: <Placeholder title="Admin" /> },
+    ],
+  },
+];
+
+export function createAppRouter(): ReturnType<typeof createBrowserRouter> {
+  return createBrowserRouter(routes);
+}

apps/web/src/spa/chat/commands-panel.spec.tsx

@@ -0,0 +1,280 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { CommandsPanel } from './commands-panel';
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+let root: Root | null;
+let container: HTMLElement | null;
+
+async function render(node: Parameters<Root['render']>[0]): Promise<void> {
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+  await act(async () => {
+    root?.render(node);
+  });
+}
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  root = null;
+  container = null;
+});
+
+describe('CommandsPanel', () => {
+  it('shows the frozen local pendingApproval args in the confirmation area, regardless of misleading server message text', async () => {
+    await render(
+      <CommandsPanel
+        manifest={null}
+        results={[]}
+        approval={{
+          conversationId: 'c1',
+          command: 'deploy', // matches pendingApproval — this is a legitimately approved request
+          success: true,
+          approvalId: 'ap1',
+          expiresAt: '2026-01-01T00:00:00.000Z',
+          // Free-text server message claims a different, less alarming target
+          // than what will actually be sent — the UI must not rely on this.
+          message: 'This will only affect the staging environment.',
+        }}
+        pendingApproval={{ command: 'deploy', args: 'prod' }}
+        hasConversation
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    // The exact frozen combined action is visible...
+    expect(container?.textContent).toContain('/deploy');
+    expect(container?.textContent).toContain('prod');
+    // ...and the misleading server free-text is never shown next to it.
+    expect(container?.textContent).not.toContain('staging environment');
+  });
+
+  it('does not throw when a manifest commands entry is null', async () => {
+    const manifest = {
+      commands: [
+        null,
+        {
+          name: 'model',
+          aliases: [],
+          description: 'Change the active model',
+          scope: 'core',
+          execution: 'socket',
+          available: true,
+        },
+      ],
+      skills: [null],
+      version: 1,
+    } as unknown as Parameters<typeof CommandsPanel>[0]['manifest'];
+
+    await expect(
+      render(
+        <CommandsPanel
+          manifest={manifest}
+          results={[]}
+          approval={null}
+          pendingApproval={null}
+          hasConversation={false}
+          onExecute={vi.fn()}
+          onApprove={vi.fn()}
+          onRunApproved={vi.fn()}
+        />,
+      ),
+    ).resolves.not.toThrow();
+
+    expect(container?.textContent).toContain('model');
+  });
+
+  it('shows an explicit no-args fallback when the frozen pendingApproval has no args', async () => {
+    await render(
+      <CommandsPanel
+        manifest={null}
+        results={[]}
+        approval={{
+          conversationId: 'c1',
+          command: 'deploy',
+          success: true,
+          approvalId: 'ap1',
+          expiresAt: '2026-01-01T00:00:00.000Z',
+        }}
+        pendingApproval={{ command: 'deploy' }}
+        hasConversation
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    expect(container?.textContent?.toLowerCase()).toContain('no args');
+  });
+
+  it('renders skills from a skills-only manifest', async () => {
+    await render(
+      <CommandsPanel
+        manifest={{
+          commands: [],
+          skills: [{ name: 'brave-search', description: 'Search the web', available: true }],
+          version: 1,
+        }}
+        results={[]}
+        approval={null}
+        pendingApproval={null}
+        hasConversation={false}
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    expect(container?.textContent).toContain('brave-search');
+    expect(container?.textContent).toContain('Search the web');
+  });
+
+  it('does not show the Run affordance when approval.success/approvalId are objects, even though command matches pendingApproval', async () => {
+    const approval = {
+      conversationId: 'c1',
+      command: 'deploy',
+      success: { truthy: 'object' },
+      approvalId: { also: 'object' },
+    } as unknown as Parameters<typeof CommandsPanel>[0]['approval'];
+
+    await render(
+      <CommandsPanel
+        manifest={null}
+        results={[]}
+        approval={approval}
+        pendingApproval={{ command: 'deploy', args: 'prod' }}
+        hasConversation
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    expect(
+      [...(container?.querySelectorAll('button') ?? [])].some((button) =>
+        button.textContent?.includes('Run approved command'),
+      ),
+    ).toBe(false);
+  });
+
+  it('shows the guarded server-provided denial reason for a denied approval', async () => {
+    await render(
+      <CommandsPanel
+        manifest={null}
+        results={[]}
+        approval={{
+          conversationId: 'c1',
+          command: 'deploy',
+          success: false,
+          message: 'Not authorized',
+        }}
+        pendingApproval={{ command: 'deploy', args: 'prod' }}
+        hasConversation
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    expect(container?.textContent).toContain('Not authorized');
+  });
+
+  it('falls back to a stable "Denied." copy when a denial has no usable message', async () => {
+    await render(
+      <CommandsPanel
+        manifest={null}
+        results={[]}
+        approval={{ conversationId: 'c1', command: 'deploy', success: false }}
+        pendingApproval={{ command: 'deploy', args: 'prod' }}
+        hasConversation
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    expect(container?.textContent).toContain('Denied.');
+  });
+
+  it('shows the guarded contract-provided reason for a failed command result, falling back to a stable copy only when absent', async () => {
+    await render(
+      <CommandsPanel
+        manifest={null}
+        results={[
+          { conversationId: 'c1', command: 'model', success: false, message: 'Unknown model' },
+          { conversationId: 'c1', command: 'deploy', success: false },
+        ]}
+        approval={null}
+        pendingApproval={null}
+        hasConversation={false}
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    expect(container?.textContent).toContain('Unknown model');
+    expect(container?.textContent).toContain('Command failed.');
+  });
+
+  it('bounds an oversized command result message at the render site as defense-in-depth', async () => {
+    const hostileMessage = 'y'.repeat(50_000);
+    await render(
+      <CommandsPanel
+        manifest={null}
+        results={[
+          { conversationId: 'c1', command: 'model', success: false, message: hostileMessage },
+        ]}
+        approval={null}
+        pendingApproval={null}
+        hasConversation={false}
+        onExecute={vi.fn()}
+        onApprove={vi.fn()}
+        onRunApproved={vi.fn()}
+      />,
+    );
+
+    const text = container?.textContent ?? '';
+    expect(text.length).toBeLessThan(hostileMessage.length);
+  });
+
+  it('does not throw when the manifest fields are malformed (non-array commands/skills)', async () => {
+    const manifest = {
+      commands: 'not-an-array',
+      skills: null,
+      version: 1,
+    } as unknown as Parameters<typeof CommandsPanel>[0]['manifest'];
+
+    await expect(
+      render(
+        <CommandsPanel
+          manifest={manifest}
+          results={[]}
+          approval={null}
+          pendingApproval={null}
+          hasConversation={false}
+          onExecute={vi.fn()}
+          onApprove={vi.fn()}
+          onRunApproved={vi.fn()}
+        />,
+      ),
+    ).resolves.not.toThrow();
+  });
+});

apps/web/src/spa/chat/commands-panel.tsx

@@ -0,0 +1,164 @@
+import { useState, type ReactElement } from 'react';
+import type { PendingApproval } from './use-chat-connection';
+import { MAX_COMMAND_MESSAGE_CHARS } from './limits';
+import { asNonEmptyString, asString } from './runtime-guards';
+import type {
+  CommandManifest,
+  SlashCommandApprovalResultPayload,
+  SlashCommandResultPayload,
+} from '@/lib/chat-contract';
+
+/** Stable fallback copy shown for a failed command only when the server's
+ * own guarded, non-empty `message` (e.g. "Unknown model") is absent or
+ * malformed — the structured contract reason itself is otherwise shown
+ * directly, never a raw thrown exception, stack trace, or object value. */
+const COMMAND_FAILURE_COPY = 'Command failed.';
+
+/** Render-site defense-in-depth: `use-chat-connection.ts` already bounds a
+ * stored command:result message at ingestion, but this component must never
+ * assume every caller went through that path — bounding again here means a
+ * hostile/oversized message can never force an unbounded render. */
+function boundMessage(value: string): string {
+  return value.length > MAX_COMMAND_MESSAGE_CHARS
+    ? value.slice(0, MAX_COMMAND_MESSAGE_CHARS)
+    : value;
+}
+
+interface CommandsPanelProps {
+  manifest: CommandManifest | null;
+  results: SlashCommandResultPayload[];
+  approval: SlashCommandApprovalResultPayload | null;
+  pendingApproval: PendingApproval | null;
+  hasConversation: boolean;
+  onExecute: (input: { command: string; args?: string }) => void;
+  onApprove: (input: { command: string; args?: string }) => void;
+  onRunApproved: () => void;
+}
+
+export function CommandsPanel({
+  manifest,
+  results,
+  approval,
+  pendingApproval,
+  hasConversation,
+  onExecute,
+  onApprove,
+  onRunApproved,
+}: CommandsPanelProps): ReactElement {
+  const [command, setCommand] = useState('');
+  const [args, setArgs] = useState('');
+
+  // Defense-in-depth: the reducer already normalizes success/approvalId
+  // before storing `approval`, but a matching command string alone must
+  // never be trusted here either — require the literal boolean `true` and a
+  // non-empty string approvalId, not merely truthy values.
+  const canRunApproved =
+    approval?.success === true &&
+    typeof approval.approvalId === 'string' &&
+    approval.approvalId.length > 0 &&
+    !!pendingApproval &&
+    pendingApproval.command === approval.command;
+
+  // A manifest arrives from the server as untyped JSON at runtime — guard
+  // both collections before mapping so a malformed manifest cannot throw.
+  const commands = Array.isArray(manifest?.commands) ? manifest.commands : [];
+  const skills = Array.isArray(manifest?.skills) ? manifest.skills : [];
+
+  return (
+    <section aria-label="Commands" className="flex flex-col gap-2 border-b px-4 py-3 text-xs">
+      {commands.length > 0 ? (
+        <ul aria-label="Available commands" className="flex flex-col gap-1">
+          {commands.map((cmd, index) => (
+            <li key={asString(cmd?.name) || `cmd-${index}`}>
+              <strong>/{asString(cmd?.name)}</strong> — {asString(cmd?.description)}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+
+      {skills.length > 0 ? (
+        <ul aria-label="Available skills" className="flex flex-col gap-1">
+          {skills.map((skill, index) => (
+            <li key={asString(skill?.name) || `skill-${index}`}>
+              <strong>/skill:{asString(skill?.name)}</strong> — {asString(skill?.description)}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+
+      <div className="flex flex-wrap items-center gap-2">
+        <input
+          aria-label="Command name"
+          value={command}
+          onChange={(event) => setCommand(event.target.value)}
+          placeholder="command"
+        />
+        <input
+          aria-label="Command arguments"
+          value={args}
+          onChange={(event) => setArgs(event.target.value)}
+          placeholder="args (optional)"
+        />
+        <button
+          type="button"
+          disabled={!hasConversation || !command.trim()}
+          onClick={() => onExecute({ command: command.trim(), args: args.trim() || undefined })}
+        >
+          Run command
+        </button>
+        <button
+          type="button"
+          disabled={!hasConversation || !command.trim()}
+          onClick={() => onApprove({ command: command.trim(), args: args.trim() || undefined })}
+        >
+          Request approval
+        </button>
+      </div>
+
+      {approval ? (
+        <div role={approval.success ? 'status' : 'alert'} className="flex items-center gap-2">
+          {/* A successful approval shows stable client copy only — never
+              the server-controlled approval.message or echoed
+              approval.command as the primary confirmation. The frozen local
+              pendingApproval below (not this line) is the sole authoritative
+              statement of what will run. A denial, by contrast, is not an
+              execution authority and safely surfaces the guarded structured
+              reason the server gave (e.g. "Not authorized"), falling back to
+              a stable copy only when absent/malformed. */}
+          <span>
+            {approval.success ? 'Approved.' : asNonEmptyString(approval.message, 'Denied.')}
+          </span>
+          {canRunApproved && pendingApproval ? (
+            <>
+              {/* Authoritative frozen local command+args — what the click below
+                  will actually emit. The server's `approval` above is display-only
+                  and must never be trusted to represent the executed payload. */}
+              <span>
+                Will run: /{pendingApproval.command}{' '}
+                {pendingApproval.args ? pendingApproval.args : '(no args)'}
+              </span>
+              <button type="button" onClick={onRunApproved}>
+                Run approved command
+              </button>
+            </>
+          ) : null}
+        </div>
+      ) : null}
+
+      {results.length > 0 ? (
+        <ul aria-label="Command results" className="flex flex-col gap-1">
+          {results.map((result, index) => (
+            <li key={`${result.command}-${index}`} role={result.success ? 'status' : 'alert'}>
+              /{asString(result.command)}: {result.success ? 'success' : 'failed'}
+              {result.success
+                ? typeof result.message === 'string' && result.message
+                  ? ` — ${boundMessage(result.message)}`
+                  : ''
+                : ` — ${boundMessage(asNonEmptyString(result.message, COMMAND_FAILURE_COPY))}`}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </section>
+  );
+}

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

@@ -0,0 +1,98 @@
+import { useState, type KeyboardEvent, type ReactElement } from 'react';
+
+interface ComposerProps {
+  onSend: (input: { content: string; provider?: string; modelId?: string }) => void;
+  onStop: () => void;
+  streaming: boolean;
+  /** True from local send time through server turn startup/ack and
+   * throughout streaming — a superset of `streaming` that also covers the
+   * pre-ack window where a second send could otherwise slip through. */
+  sending: boolean;
+  hasConversation: boolean;
+}
+
+export function Composer({
+  onSend,
+  onStop,
+  streaming,
+  sending,
+  hasConversation,
+}: ComposerProps): ReactElement {
+  const [content, setContent] = useState('');
+  const [provider, setProvider] = useState('');
+  const [modelId, setModelId] = useState('');
+  const busy = streaming || sending;
+
+  function submit(): void {
+    if (busy) return;
+    const trimmed = content.trim();
+    if (!trimmed) return;
+    onSend({
+      content: trimmed,
+      provider: provider.trim() || undefined,
+      modelId: modelId.trim() || undefined,
+    });
+    setContent('');
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>): void {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      submit();
+    }
+  }
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        submit();
+      }}
+      className="flex flex-col gap-2 border-t p-4"
+    >
+      <div className="flex flex-wrap gap-2">
+        <input
+          aria-label="Provider"
+          value={provider}
+          onChange={(event) => setProvider(event.target.value)}
+          placeholder="Provider (optional)"
+          className="rounded border px-2 py-1 text-xs"
+        />
+        <input
+          aria-label="Model"
+          value={modelId}
+          onChange={(event) => setModelId(event.target.value)}
+          placeholder="Model (optional)"
+          className="rounded border px-2 py-1 text-xs"
+        />
+      </div>
+      <div className="flex items-end gap-2">
+        <textarea
+          aria-label="Message"
+          value={content}
+          onChange={(event) => setContent(event.target.value)}
+          onKeyDown={handleKeyDown}
+          rows={2}
+          placeholder="Message… (Enter to send, Shift+Enter for a new line)"
+          className="flex-1 resize-none rounded border px-3 py-2 text-sm"
+        />
+        <button
+          type="submit"
+          disabled={!content.trim() || busy}
+          className="rounded px-3 py-2 text-sm font-medium"
+        >
+          Send
+        </button>
+        <button
+          type="button"
+          aria-label="Stop"
+          disabled={!hasConversation || !streaming}
+          onClick={onStop}
+          className="rounded px-3 py-2 text-sm font-medium"
+        >
+          Stop
+        </button>
+      </div>
+    </form>
+  );
+}

apps/web/src/spa/chat/limits.ts

@@ -0,0 +1,22 @@
+/**
+ * Bounds on server-fed chat state. A hostile or malfunctioning gateway can
+ * flood any of these collections; caps keep memory/render cost flat instead
+ * of growing unboundedly for the lifetime of the connection.
+ */
+
+/** Max characters retained for the in-flight streamed text/thinking buffers. */
+export const MAX_STREAM_CHARS = 20_000;
+/** Max transcript turns retained (oldest dropped first). */
+export const MAX_MESSAGES = 500;
+/** Max tool-call entries (including anomaly entries) retained per turn history. */
+export const MAX_TOOLS = 200;
+/** Max slash-command results retained. */
+export const MAX_COMMAND_RESULTS = 200;
+/** Max commands/skills accepted from a single manifest push. */
+export const MAX_MANIFEST_ITEMS = 500;
+/** Max executed approval IDs remembered for single-flight dedup. */
+export const MAX_EXECUTED_APPROVAL_IDS = 200;
+/** Max characters retained for a single command:result message — a hostile
+ * or malfunctioning gateway must not be able to push an unbounded curated
+ * success/failure reason into state (or, defensively, onto the page). */
+export const MAX_COMMAND_MESSAGE_CHARS = 1_000;

apps/web/src/spa/chat/message-transcript.tsx

@@ -0,0 +1,39 @@
+import type { ReactElement } from 'react';
+import type { ChatTranscriptMessage } from './use-chat-connection';
+
+interface MessageTranscriptProps {
+  messages: ChatTranscriptMessage[];
+  streaming: boolean;
+  text: string;
+}
+
+export function MessageTranscript({
+  messages,
+  streaming,
+  text,
+}: MessageTranscriptProps): ReactElement {
+  return (
+    <div
+      role="log"
+      aria-live="polite"
+      aria-label="Conversation"
+      className="flex flex-1 flex-col gap-3 overflow-y-auto p-4"
+    >
+      {messages.map((message) => (
+        <div key={message.id} data-role={message.role} className="whitespace-pre-wrap text-sm">
+          <span className="font-medium">{message.role === 'user' ? 'You' : 'Assistant'}: </span>
+          <span>{message.text}</span>
+          {message.thinking ? (
+            <div className="pt-1 text-xs italic opacity-70">{message.thinking}</div>
+          ) : null}
+        </div>
+      ))}
+      {streaming ? (
+        <div data-role="assistant-streaming" className="whitespace-pre-wrap text-sm">
+          <span className="font-medium">Assistant: </span>
+          <span>{text || 'Thinking…'}</span>
+        </div>
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Socket.IO payloads are only statically typed at the call site — a
+ * misbehaving or compromised gateway can send anything at runtime. These
+ * guards protect the dereference sites that would otherwise throw (`.map` on
+ * a non-array, `.toFixed` on a non-number) or render an object as a React
+ * child.
+ */
+
+export function asString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+/** Like `asString`, but an empty string also falls back — used for guarded
+ * contract-provided reason strings (e.g. a denial or failure message) where
+ * an empty string is not a meaningful value to display in place of the
+ * stable fallback copy. */
+export function asNonEmptyString(value: unknown, fallback: string): string {
+  return typeof value === 'string' && value.length > 0 ? value : fallback;
+}
+
+export function asFiniteNumber(value: unknown, fallback = 0): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+/** Like `asFiniteNumber`, but returns `null` on failure instead of a numeric
+ * fallback — callers that must not fabricate a plausible-looking value (e.g.
+ * `0 tokens` / `$0.0000` for genuinely unknown usage) use this to render an
+ * honest "unavailable" label instead. */
+export function asFiniteNumberOrNull(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : [];
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** The single point of truth for what counts as a valid conversation ID
+ * anywhere a scoped server event may adopt one into state — a non-empty
+ * string, nothing else. Every site that establishes or compares
+ * `state.conversationId` against a raw socket payload must route through
+ * this guard so a malformed first frame (null/object/number/empty string)
+ * can never be adopted verbatim. */
+export function asConversationId(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}

apps/web/src/spa/chat/session-panel.tsx

@@ -0,0 +1,68 @@
+import type { ReactElement } from 'react';
+import type { SessionInfoPayload } from '@/lib/chat-contract';
+import { MAX_MANIFEST_ITEMS } from './limits';
+import { asString, asStringArray } from './runtime-guards';
+
+interface SessionPanelProps {
+  sessionInfo: SessionInfoPayload | null;
+  onSetThinking: (level: string) => void;
+}
+
+const THINKING_LEVEL_UNAVAILABLE = '';
+
+export function SessionPanel({
+  sessionInfo,
+  onSetThinking,
+}: SessionPanelProps): ReactElement | null {
+  if (!sessionInfo) return null;
+
+  // The reducer already caps this before storing it, but the render site
+  // defends independently — a hostile payload must never be able to force
+  // this <select> to lay out an unbounded number of options.
+  const availableThinkingLevels = asStringArray(sessionInfo.availableThinkingLevels).slice(
+    0,
+    MAX_MANIFEST_ITEMS,
+  );
+  const hasThinkingLevels = availableThinkingLevels.length > 0;
+
+  return (
+    <section
+      aria-label="Session info"
+      className="flex flex-wrap items-center gap-3 border-b px-4 py-2 text-xs"
+    >
+      <span>{asString(sessionInfo.provider, 'unknown')}</span>
+      <span>{asString(sessionInfo.modelId, 'unknown')}</span>
+      <label className="flex items-center gap-2">
+        <span>Thinking level</span>
+        <select
+          aria-label="Thinking level"
+          value={
+            hasThinkingLevels ? asString(sessionInfo.thinkingLevel) : THINKING_LEVEL_UNAVAILABLE
+          }
+          onChange={(event) => {
+            // The placeholder option is not a real, settable level — a
+            // malformed availableThinkingLevels list must never let the
+            // client emit set:thinking for it.
+            if (!hasThinkingLevels) return;
+            onSetThinking(event.target.value);
+          }}
+        >
+          {hasThinkingLevels ? (
+            availableThinkingLevels.map((level) => (
+              <option key={level} value={level}>
+                {level}
+              </option>
+            ))
+          ) : (
+            <option value={THINKING_LEVEL_UNAVAILABLE}>Thinking level unavailable</option>
+          )}
+        </select>
+      </label>
+      {sessionInfo.routingDecision ? (
+        <span title={asString(sessionInfo.routingDecision.ruleName)}>
+          {asString(sessionInfo.routingDecision.reason)}
+        </span>
+      ) : null}
+    </section>
+  );
+}

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

@@ -0,0 +1,125 @@
+import { vi } from 'vitest';
+import type { ClientToServerEvents, ServerToClientEvents } from '@/lib/chat-contract';
+
+type ServerEvent = keyof ServerToClientEvents;
+type ClientEvent = keyof ClientToServerEvents;
+type ServerHandler<K extends ServerEvent> = ServerToClientEvents[K];
+type ClientPayload<K extends ClientEvent> = Parameters<ClientToServerEvents[K]>[0];
+
+export interface EmittedEvent<K extends ClientEvent = ClientEvent> {
+  event: K;
+  payload: ClientPayload<K>;
+}
+
+/** The subset of a Socket.IO `ChatSocket` that `useChatConnection` drives. */
+export interface FakeChatSocket {
+  connected: boolean;
+  connect(): FakeChatSocket;
+  on<K extends ServerEvent>(event: K, handler: ServerHandler<K>): FakeChatSocket;
+  off<K extends ServerEvent>(event: K, handler: ServerHandler<K>): FakeChatSocket;
+  emit<K extends ClientEvent>(event: K, payload: ClientPayload<K>): FakeChatSocket;
+}
+
+/**
+ * A typed in-memory stand-in for `getSocket()`. Unlike a bare
+ * `(event: string, payload: unknown) => void` mock, every public method here is
+ * checked against the real `/chat` contract — a typo'd event name or a payload
+ * missing a required field fails to compile instead of silently no-op'ing at
+ * runtime.
+ */
+/** Socket.IO's built-in connection-state events. Not part of the app-level
+ * ServerToClientEvents contract, but real sockets always support them and
+ * `useChatConnection` registers a `disconnect` handler on the real socket. */
+type LifecycleEvent = 'connect' | 'disconnect';
+
+export function createFakeChatSocket(): {
+  socket: FakeChatSocket;
+  listeners: Map<ServerEvent, Set<(payload: never) => void>>;
+  emitted: EmittedEvent[];
+  serverEmit<K extends ServerEvent>(
+    event: K,
+    payload: Parameters<ServerToClientEvents[K]>[0],
+  ): void;
+  /** Escape hatch for malformed-payload tests: bypasses the compile-time
+   * payload contract to simulate a genuinely untrusted runtime value from the
+   * server, e.g. a `session:info` with a non-array `availableThinkingLevels`. */
+  serverEmitRaw(event: ServerEvent, payload: unknown): void;
+  /** Simulates a transient Socket.IO `disconnect` — fires any handler(s)
+   * registered via `socket.on('disconnect', ...)` without clearing any
+   * listeners, mirroring how a real reconnecting socket behaves. */
+  simulateDisconnect(): void;
+  /** Simulates socket.io-client's automatic reconnect of the *same*
+   * instance after a transient disconnect: marks the socket connected again
+   * and fires any handler(s) registered via `socket.on('connect', ...)`,
+   * without clearing or replacing any listeners. */
+  simulateReconnect(): void;
+} {
+  const listeners = new Map<ServerEvent, Set<(payload: never) => void>>();
+  const emitted: EmittedEvent[] = [];
+
+  // Internal storage is intentionally keyed loosely (the per-event handler shape
+  // varies by K, which a single Map can't express); the generic signatures on the
+  // exported `socket`/`serverEmit` above and below are what keep test call sites
+  // type-checked against ServerToClientEvents/ClientToServerEvents.
+  const socket = {
+    connected: false,
+    connect: vi.fn(function connect(this: void) {
+      socket.connected = true;
+      return socket;
+    }),
+    on: vi.fn(function on(this: void, event: ServerEvent, handler: (payload: never) => void) {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)?.add(handler);
+      return socket;
+    }),
+    off: vi.fn(function off(this: void, event: ServerEvent, handler: (payload: never) => void) {
+      listeners.get(event)?.delete(handler);
+      return socket;
+    }),
+    emit: vi.fn(function emit(this: void, event: ClientEvent, payload: unknown) {
+      emitted.push({ event, payload } as EmittedEvent);
+      return socket;
+    }),
+  } as unknown as FakeChatSocket;
+
+  function serverEmit<K extends ServerEvent>(
+    event: K,
+    payload: Parameters<ServerToClientEvents[K]>[0],
+  ): void {
+    for (const handler of listeners.get(event) ?? []) {
+      (handler as (payload: Parameters<ServerToClientEvents[K]>[0]) => void)(payload);
+    }
+  }
+
+  function serverEmitRaw(event: ServerEvent, payload: unknown): void {
+    for (const handler of listeners.get(event) ?? []) {
+      (handler as (payload: unknown) => void)(payload);
+    }
+  }
+
+  function simulateDisconnect(): void {
+    socket.connected = false;
+    const lifecycleKey = 'disconnect' satisfies LifecycleEvent as unknown as ServerEvent;
+    for (const handler of listeners.get(lifecycleKey) ?? []) {
+      (handler as () => void)();
+    }
+  }
+
+  function simulateReconnect(): void {
+    socket.connected = true;
+    const lifecycleKey = 'connect' satisfies LifecycleEvent as unknown as ServerEvent;
+    for (const handler of listeners.get(lifecycleKey) ?? []) {
+      (handler as () => void)();
+    }
+  }
+
+  return {
+    socket,
+    listeners,
+    emitted,
+    serverEmit,
+    serverEmitRaw,
+    simulateDisconnect,
+    simulateReconnect,
+  };
+}

apps/web/src/spa/chat/tool-call-list.spec.tsx

@@ -0,0 +1,63 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { ToolCallList } from './tool-call-list';
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+let root: Root | null;
+let container: HTMLElement | null;
+
+async function render(node: Parameters<Root['render']>[0]): Promise<void> {
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+  await act(async () => {
+    root?.render(node);
+  });
+}
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  root = null;
+  container = null;
+});
+
+describe('ToolCallList', () => {
+  it('renders two entries independently, without a duplicate-key warning, when a valid toolCallId is shared', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    await render(
+      <ToolCallList
+        tools={[
+          { toolCallId: 'dup', toolName: 'search', status: 'success' },
+          { toolCallId: 'dup', toolName: 'search', status: 'running' },
+        ]}
+      />,
+    );
+
+    const items = [...(container?.querySelectorAll('li') ?? [])];
+    expect(items).toHaveLength(2);
+    expect(items[0]?.textContent).toContain('success');
+    expect(items[1]?.textContent).toContain('running');
+
+    const duplicateKeyWarning = consoleError.mock.calls.some((args) =>
+      args.some((arg) => typeof arg === 'string' && arg.includes('same key')),
+    );
+    expect(duplicateKeyWarning).toBe(false);
+
+    consoleError.mockRestore();
+  });
+});

apps/web/src/spa/chat/tool-call-list.tsx

@@ -0,0 +1,24 @@
+import type { ReactElement } from 'react';
+import type { ToolCallState } from './use-chat-connection';
+
+export function ToolCallList({ tools }: { tools: ToolCallState[] }): ReactElement | null {
+  if (tools.length === 0) return null;
+
+  return (
+    <ul aria-label="Tool calls" className="flex flex-col gap-1 px-4 pb-2 text-xs">
+      {tools.map((tool, index) => (
+        <li
+          // A valid server-controlled toolCallId can legitimately repeat
+          // (e.g. two tool:start events sharing one id) — keying on it alone
+          // would give React two identical keys. Pairing it with its
+          // (stable, append-only) render index keeps every key unique.
+          key={`${tool.toolCallId}-${index}`}
+          role={tool.status === 'error' || tool.status === 'anomaly' ? 'alert' : 'status'}
+        >
+          {tool.toolName} —{' '}
+          {tool.status === 'anomaly' ? 'unexpected end (unknown tool call)' : tool.status}
+        </li>
+      ))}
+    </ul>
+  );
+}