fix(tess): route bare Discord approvals

.prettierignore

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

.woodpecker/ci.yml

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

apps/gateway/package.json

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

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

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

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

@@ -20,7 +20,7 @@ export class AdminHealthController {
   async check(): Promise<HealthStatusDto> {
     const [database, cache] = await Promise.all([this.checkDatabase(), this.checkCache()]);
 
-    const sessions = this.agentService.listSessions();
+    const sessions = this.agentService.listAllSessionsForSystem();
     const providers = this.providerService.listProviders();
 
     const allOk = database.status === 'ok' && cache.status === 'ok';

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

@@ -0,0 +1,142 @@
+import { ForbiddenException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+import { AgentService, type AgentSession } from '../agent.service.js';
+import type { ActorTenantScope } from '../../auth/session-scope.js';
+
+const CONVERSATION_ID = '22222222-2222-4222-8222-222222222222';
+const OWNER_SCOPE: ActorTenantScope = { userId: 'owner-user', tenantId: 'owner-tenant' };
+const FOREIGN_SCOPE: ActorTenantScope = { userId: 'foreign-user', tenantId: 'foreign-tenant' };
+
+type AgentServiceInternals = {
+  sessions: Map<string, AgentSession>;
+  creating: Map<string, Promise<AgentSession>>;
+};
+
+function makeService(): AgentService {
+  return new AgentService(
+    {} as never,
+    {} as never,
+    {} as never,
+    { available: false } as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    null,
+    null,
+    { collect: vi.fn().mockResolvedValue(undefined) } as never,
+  );
+}
+
+function internals(service: AgentService): AgentServiceInternals {
+  return service as unknown as AgentServiceInternals;
+}
+
+function makeSession(scope: ActorTenantScope = OWNER_SCOPE): AgentSession {
+  return {
+    id: CONVERSATION_ID,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    piSession: {
+      thinkingLevel: 'off',
+      getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
+      setThinkingLevel: vi.fn(),
+      abort: vi.fn().mockResolvedValue(undefined),
+      prompt: vi.fn().mockResolvedValue(undefined),
+      dispose: vi.fn(),
+      getSessionStats: vi.fn(),
+      getContextUsage: vi.fn(),
+    } as unknown as AgentSession['piSession'],
+    listeners: new Set(),
+    unsubscribe: vi.fn(),
+    createdAt: Date.now(),
+    promptCount: 0,
+    channels: new Set(),
+    skillPromptAdditions: [],
+    sandboxDir: '/tmp/tess-session-ownership-test',
+    allowedTools: null,
+    userId: scope.userId,
+    tenantId: scope.tenantId,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    },
+  };
+}
+
+describe('AgentService owner/tenant scope enforcement', () => {
+  it('allows owner-scoped operations and rejects foreign scopes for seeded sessions', async () => {
+    const service = makeService();
+    const session = makeSession();
+    internals(service).sessions.set(CONVERSATION_ID, session);
+
+    expect(service.getSession(CONVERSATION_ID, OWNER_SCOPE)).toBe(session);
+    expect(service.getSession(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
+    expect(service.getSessionInfo(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
+    expect(service.listSessions(OWNER_SCOPE)).toHaveLength(1);
+    expect(service.listSessions(FOREIGN_SCOPE)).toEqual([]);
+
+    service.addChannel(CONVERSATION_ID, 'websocket:owner', OWNER_SCOPE);
+    expect(session.channels.has('websocket:owner')).toBe(true);
+    expect(() => service.addChannel(CONVERSATION_ID, 'websocket:foreign', FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+    expect(() => service.removeChannel(CONVERSATION_ID, 'websocket:owner', FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+
+    expect(() =>
+      service.updateSessionModel(CONVERSATION_ID, 'foreign-model', FOREIGN_SCOPE),
+    ).toThrow(ForbiddenException);
+    service.updateSessionModel(CONVERSATION_ID, 'owner-model', OWNER_SCOPE);
+    expect(session.modelId).toBe('owner-model');
+
+    expect(() =>
+      service.applyAgentConfig(CONVERSATION_ID, 'agent-foreign', 'Foreign Agent', FOREIGN_SCOPE),
+    ).toThrow(ForbiddenException);
+    service.applyAgentConfig(CONVERSATION_ID, 'agent-owner', 'Owner Agent', OWNER_SCOPE);
+    expect(session.agentConfigId).toBe('agent-owner');
+
+    expect(() => service.onEvent(CONVERSATION_ID, vi.fn(), FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+    const cleanup = service.onEvent(CONVERSATION_ID, vi.fn(), OWNER_SCOPE);
+    cleanup();
+
+    await expect(
+      service.prompt(CONVERSATION_ID, 'foreign prompt', FOREIGN_SCOPE),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await service.prompt(CONVERSATION_ID, 'owner prompt', OWNER_SCOPE);
+    expect(session.piSession.prompt).toHaveBeenCalledWith('owner prompt');
+
+    await expect(service.destroySession(CONVERSATION_ID, FOREIGN_SCOPE)).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+    expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(true);
+
+    await service.destroySession(CONVERSATION_ID, OWNER_SCOPE);
+    expect(session.piSession.dispose).toHaveBeenCalled();
+    expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(false);
+  });
+
+  it('checks owner/tenant scope before returning an in-flight session creation', async () => {
+    const service = makeService();
+    const session = makeSession();
+    internals(service).creating.set(CONVERSATION_ID, Promise.resolve(session));
+
+    await expect(
+      service.createSession(CONVERSATION_ID, {
+        userId: FOREIGN_SCOPE.userId,
+        tenantId: FOREIGN_SCOPE.tenantId,
+      }),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+
+    await expect(
+      service.createSession(CONVERSATION_ID, {
+        userId: OWNER_SCOPE.userId,
+        tenantId: OWNER_SCOPE.tenantId,
+      }),
+    ).resolves.toBe(session);
+  });
+});

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

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

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

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

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

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

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

@@ -1,4 +1,11 @@
-import { Inject, Injectable, Logger, Optional, type OnModuleDestroy } from '@nestjs/common';
+import {
+  ForbiddenException,
+  Inject,
+  Injectable,
+  Logger,
+  Optional,
+  type OnModuleDestroy,
+} from '@nestjs/common';
 import {
   createAgentSession,
   DefaultResourceLoader,
@@ -28,6 +35,7 @@ import type { SessionInfoDto, SessionMetrics } from './session.dto.js';
 import { SystemOverrideService } from '../preferences/system-override.service.js';
 import { PreferencesService } from '../preferences/preferences.service.js';
 import { SessionGCService } from '../gc/session-gc.service.js';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 
 /** A single message from DB conversation history, used for context injection. */
 export interface ConversationHistoryMessage {
@@ -68,6 +76,8 @@ export interface AgentSessionOptions {
   agentConfigId?: string;
   /** ID of the user who owns this session. Used for preferences and system override lookups. */
   userId?: string;
+  /** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
+  tenantId?: string;
   /**
    * Prior conversation messages to inject as context when resuming a session.
    * These messages are formatted and prepended to the system prompt so the
@@ -94,6 +104,8 @@ export interface AgentSession {
   allowedTools: string[] | null;
   /** User ID that owns this session, used for preference lookups. */
   userId?: string;
+  /** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
+  tenantId?: string;
   /** Agent config ID applied to this session, if any (M5-001). */
   agentConfigId?: string;
   /** Human-readable agent name applied to this session, if any (M5-001). */
@@ -174,12 +186,20 @@ export class AgentService implements OnModuleDestroy {
       .filter((t) => t.length > 0);
   }
 
-  async createSession(sessionId: string, options?: AgentSessionOptions): Promise<AgentSession> {
+  async createSession(sessionId: string, options: AgentSessionOptions): Promise<AgentSession> {
+    const scope = this.scopeFromOptions(options);
     const existing = this.sessions.get(sessionId);
-    if (existing) return existing;
+    if (existing) {
+      this.assertSessionScope(existing, scope);
+      return existing;
+    }
 
     const inflight = this.creating.get(sessionId);
-    if (inflight) return inflight;
+    if (inflight) {
+      const session = await inflight;
+      this.assertSessionScope(session, scope);
+      return session;
+    }
 
     const promise = this.doCreateSession(sessionId, options).finally(() => {
       this.creating.delete(sessionId);
@@ -342,6 +362,7 @@ export class AgentService implements OnModuleDestroy {
       sandboxDir,
       allowedTools,
       userId: mergedOptions?.userId,
+      tenantId: this.tenantIdFor(mergedOptions?.userId, mergedOptions?.tenantId),
       agentConfigId: mergedOptions?.agentConfigId,
       agentName: resolvedAgentName,
       metrics: {
@@ -473,38 +494,70 @@ export class AgentService implements OnModuleDestroy {
     return this.providerService.getDefaultModel() ?? null;
   }
 
-  getSession(sessionId: string): AgentSession | undefined {
-    return this.sessions.get(sessionId);
+  getSession(sessionId: string, scope: ActorTenantScope): AgentSession | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session || !this.sessionMatchesScope(session, scope)) return undefined;
+    return session;
   }
 
-  listSessions(): SessionInfoDto[] {
+  listSessions(scope: ActorTenantScope): SessionInfoDto[] {
     const now = Date.now();
-    return Array.from(this.sessions.values()).map((s) => ({
-      id: s.id,
-      provider: s.provider,
-      modelId: s.modelId,
-      ...(s.agentName ? { agentName: s.agentName } : {}),
-      createdAt: new Date(s.createdAt).toISOString(),
-      promptCount: s.promptCount,
-      channels: Array.from(s.channels),
-      durationMs: now - s.createdAt,
-      metrics: { ...s.metrics },
-    }));
+    return Array.from(this.sessions.values())
+      .filter((s) => this.sessionMatchesScope(s, scope))
+      .map((s) => this.toSessionInfo(s, now));
   }
 
-  getSessionInfo(sessionId: string): SessionInfoDto | undefined {
+  listAllSessionsForSystem(): SessionInfoDto[] {
+    const now = Date.now();
+    return Array.from(this.sessions.values()).map((s) => this.toSessionInfo(s, now));
+  }
+
+  getSessionInfo(sessionId: string, scope: ActorTenantScope): SessionInfoDto | undefined {
     const s = this.sessions.get(sessionId);
-    if (!s) return undefined;
+    if (!s || !this.sessionMatchesScope(s, scope)) return undefined;
+    return this.toSessionInfo(s);
+  }
+
+  private scopeFromOptions(options: AgentSessionOptions): ActorTenantScope {
+    if (!options.userId) {
+      throw new ForbiddenException('Session owner scope is required');
+    }
     return {
-      id: s.id,
-      provider: s.provider,
-      modelId: s.modelId,
-      ...(s.agentName ? { agentName: s.agentName } : {}),
-      createdAt: new Date(s.createdAt).toISOString(),
-      promptCount: s.promptCount,
-      channels: Array.from(s.channels),
-      durationMs: Date.now() - s.createdAt,
-      metrics: { ...s.metrics },
+      userId: options.userId,
+      tenantId: this.tenantIdFor(options.userId, options.tenantId) ?? options.userId,
+    };
+  }
+
+  private tenantIdFor(
+    userId: string | undefined,
+    tenantId: string | undefined,
+  ): string | undefined {
+    return tenantId ?? userId;
+  }
+
+  private sessionMatchesScope(session: AgentSession, scope: ActorTenantScope): boolean {
+    return (
+      session.userId === scope.userId && (session.tenantId ?? session.userId) === scope.tenantId
+    );
+  }
+
+  private assertSessionScope(session: AgentSession, scope: ActorTenantScope): void {
+    if (!this.sessionMatchesScope(session, scope)) {
+      throw new ForbiddenException('Session does not belong to the current owner/tenant scope');
+    }
+  }
+
+  private toSessionInfo(session: AgentSession, now = Date.now()): SessionInfoDto {
+    return {
+      id: session.id,
+      provider: session.provider,
+      modelId: session.modelId,
+      ...(session.agentName ? { agentName: session.agentName } : {}),
+      createdAt: new Date(session.createdAt).toISOString(),
+      promptCount: session.promptCount,
+      channels: Array.from(session.channels),
+      durationMs: now - session.createdAt,
+      metrics: { ...session.metrics },
     };
   }
 
@@ -553,9 +606,10 @@ export class AgentService implements OnModuleDestroy {
    * not reconstructed — the model is used on the next createSession call for
    * the same conversationId when the session is torn down or a new one is created.
    */
-  updateSessionModel(sessionId: string, modelId: string): void {
+  updateSessionModel(sessionId: string, modelId: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    this.assertSessionScope(session, scope);
     const prev = session.modelId;
     session.modelId = modelId;
     this.recordModelSwitch(sessionId);
@@ -572,48 +626,51 @@ export class AgentService implements OnModuleDestroy {
     sessionId: string,
     agentConfigId: string,
     agentName: string,
+    scope: ActorTenantScope,
     modelId?: string,
   ): void {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    this.assertSessionScope(session, scope);
     session.agentConfigId = agentConfigId;
     session.agentName = agentName;
     if (modelId) {
-      this.updateSessionModel(sessionId, modelId);
+      this.updateSessionModel(sessionId, modelId, scope);
     }
     this.logger.log(
       `Session ${sessionId}: agent switched to "${agentName}" (${agentConfigId}) (M5-003)`,
     );
   }
 
-  addChannel(sessionId: string, channel: string): void {
+  addChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
-    if (session) {
-      session.channels.add(channel);
-    }
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    session.channels.add(channel);
   }
 
-  removeChannel(sessionId: string, channel: string): void {
+  removeChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
-    if (session) {
-      session.channels.delete(channel);
-    }
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    session.channels.delete(channel);
   }
 
-  async prompt(sessionId: string, message: string): Promise<void> {
+  async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
     }
+    this.assertSessionScope(session, scope);
     session.promptCount += 1;
 
     // Prepend session-scoped system override if present (renew TTL on each turn)
     let effectiveMessage = message;
     if (this.systemOverride) {
-      const override = await this.systemOverride.get(sessionId);
+      const override = await this.systemOverride.get(sessionId, scope);
       if (override) {
         effectiveMessage = `[System Override]\n${override}\n\n${message}`;
-        await this.systemOverride.renew(sessionId);
+        await this.systemOverride.renew(sessionId, scope);
         this.logger.debug(`Applied system override for session ${sessionId}`);
       }
     }
@@ -629,16 +686,28 @@ export class AgentService implements OnModuleDestroy {
     }
   }
 
-  onEvent(sessionId: string, listener: (event: AgentSessionEvent) => void): () => void {
+  onEvent(
+    sessionId: string,
+    listener: (event: AgentSessionEvent) => void,
+    scope: ActorTenantScope,
+  ): () => void {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
     }
+    this.assertSessionScope(session, scope);
     session.listeners.add(listener);
     return () => session.listeners.delete(listener);
   }
 
-  async destroySession(sessionId: string): Promise<void> {
+  async destroySession(sessionId: string, scope: ActorTenantScope): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    await this.destroySessionForSystem(sessionId);
+  }
+
+  private async destroySessionForSystem(sessionId: string): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) return;
     this.logger.log(`Destroying agent session ${sessionId}`);
@@ -667,7 +736,7 @@ export class AgentService implements OnModuleDestroy {
 
   async onModuleDestroy(): Promise<void> {
     this.logger.log('Shutting down all agent sessions');
-    const stops = Array.from(this.sessions.keys()).map((id) => this.destroySession(id));
+    const stops = Array.from(this.sessions.keys()).map((id) => this.destroySessionForSystem(id));
     const results = await Promise.allSettled(stops);
     for (const result of results) {
       if (result.status === 'rejected') {

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,123 @@
+import { ForbiddenException, Inject, Injectable } from '@nestjs/common';
+import { DurableSessionCoordinator, type DurableSessionIdentity } from '@mosaicstack/agent';
+import type { TessProviderOutboxDto } from './tess-durable-session.dto.js';
+import { TessDurableSessionRepository } from './tess-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
+ * 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 {
+  private readonly coordinator: DurableSessionCoordinator;
+
+  constructor(
+    @Inject(TessDurableSessionRepository) repository: TessDurableSessionRepository,
+    @Inject(RuntimeProviderService) private readonly runtimeProviders: RuntimeProviderService,
+  ) {
+    this.coordinator = new DurableSessionCoordinator(repository);
+  }
+
+  /** Enroll a verified runtime session under the stable cross-surface conversation handle. */
+  async enroll(
+    identity: DurableSessionIdentity,
+    context: RuntimeProviderRequestContext,
+  ): Promise<void> {
+    if (
+      identity.ownerId !== context.actorScope.userId ||
+      identity.tenantId !== context.actorScope.tenantId
+    ) {
+      throw new ForbiddenException('Durable Tess enrollment scope mismatch');
+    }
+    await this.coordinator.create(identity);
+  }
+
+  async queueProviderSend(input: TessProviderOutboxDto): Promise<void> {
+    const snapshot = await this.coordinator.snapshot(input.sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    await this.coordinator.enqueueOutbox({
+      sessionId: input.sessionId,
+      idempotencyKey: input.idempotencyKey,
+      correlationId: input.correlationId,
+      channelId: input.context.channelId,
+      kind: 'provider.send',
+      content: input.content,
+    });
+  }
+
+  async dispatchProviderOutbox(sessionId: string, input: TessProviderOutboxDto): Promise<void> {
+    if (sessionId !== input.sessionId) {
+      throw new ForbiddenException('Durable Tess outbox session mismatch');
+    }
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    const pendingEntry = snapshot.outbox.find(
+      (entry): boolean => entry.idempotencyKey === input.idempotencyKey,
+    );
+    if (!pendingEntry) return;
+    // Validate immutable routing before claiming. A caller with a mismatched
+    // correlation/channel must not strand a pending external side effect.
+    this.assertOutboxScope(pendingEntry, input);
+    await this.coordinator.dispatchOutboxEntry(
+      sessionId,
+      input.idempotencyKey,
+      async (entry): Promise<void> => {
+        this.assertOutboxScope(entry, input);
+        await this.runtimeProviders.sendMessage(
+          snapshot.identity.providerId,
+          snapshot.identity.runtimeSessionId,
+          { content: entry.content, idempotencyKey: entry.idempotencyKey },
+          input.context,
+        );
+      },
+    );
+  }
+
+  /** Read durable identity/state only after deriving and checking the server-side actor scope. */
+  async getSnapshot(sessionId: string, context: RuntimeProviderRequestContext) {
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, {
+      sessionId,
+      content: '',
+      idempotencyKey: 'read-only',
+      correlationId: context.correlationId,
+      context,
+    });
+    return snapshot;
+  }
+
+  /** Startup/recovery-only path; normal queue/dispatch methods never requeue live work. */
+  async recoverProviderSession(sessionId: string, input: TessProviderOutboxDto): Promise<void> {
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    await this.coordinator.recover(sessionId);
+  }
+
+  private assertOutboxScope(
+    entry: { kind: string; correlationId: string; channelId: string },
+    input: TessProviderOutboxDto,
+  ): 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');
+    }
+  }
+
+  private assertScope(ownerId: string, tenantId: string, input: TessProviderOutboxDto): 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');
+    }
+  }
+}

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

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

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

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

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

@@ -3,8 +3,10 @@ import {
   Post,
   Body,
   Logger,
+  ForbiddenException,
   HttpException,
   HttpStatus,
+  NotFoundException,
   Inject,
   UseGuards,
 } from '@nestjs/common';
@@ -13,6 +15,7 @@ import { Throttle } from '@nestjs/throttler';
 import { AgentService } from '../agent/agent.service.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
+import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
 import { v4 as uuid } from 'uuid';
 import { ChatRequestDto } from './chat.dto.js';
 
@@ -32,16 +35,23 @@ export class ChatController {
   @Throttle({ default: { limit: 10, ttl: 60_000 } })
   async chat(
     @Body() body: ChatRequestDto,
-    @CurrentUser() user: { id: string },
+    @CurrentUser() user: AuthenticatedUserLike,
   ): Promise<ChatResponse> {
     const conversationId = body.conversationId ?? uuid();
+    const scope = scopeFromUser(user);
 
     try {
-      let agentSession = this.agentService.getSession(conversationId);
+      let agentSession = this.agentService.getSession(conversationId, scope);
       if (!agentSession) {
-        agentSession = await this.agentService.createSession(conversationId);
+        agentSession = await this.agentService.createSession(conversationId, {
+          userId: scope.userId,
+          tenantId: scope.tenantId,
+        });
       }
     } catch (err) {
+      if (err instanceof ForbiddenException) {
+        throw new NotFoundException('Session not found');
+      }
       this.logger.error(
         `Session creation failed for conversation=${conversationId}`,
         err instanceof Error ? err.stack : String(err),
@@ -60,20 +70,27 @@ export class ChatController {
         reject(new Error('Agent response timed out'));
       }, 120_000);
 
-      const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
-        if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-          responseText += event.assistantMessageEvent.delta;
-        }
-        if (event.type === 'agent_end') {
-          clearTimeout(timer);
-          cleanup();
-          resolve();
-        }
-      });
+      const cleanup = this.agentService.onEvent(
+        conversationId,
+        (event: AgentSessionEvent) => {
+          if (
+            event.type === 'message_update' &&
+            event.assistantMessageEvent.type === 'text_delta'
+          ) {
+            responseText += event.assistantMessageEvent.delta;
+          }
+          if (event.type === 'agent_end') {
+            clearTimeout(timer);
+            cleanup();
+            resolve();
+          }
+        },
+        scope,
+      );
     });
 
     try {
-      await this.agentService.prompt(conversationId, body.content);
+      await this.agentService.prompt(conversationId, body.content, scope);
       await done;
     } catch (err) {
       if (err instanceof HttpException) throw err;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -3,8 +3,10 @@ import { createQueue, type QueueHandle } from '@mosaicstack/queue';
 import { ChatModule } from '../chat/chat.module.js';
 import { GCModule } from '../gc/gc.module.js';
 import { ReloadModule } from '../reload/reload.module.js';
+import { CommandAuthorizationService } from './command-authorization.service.js';
 import { CommandExecutorService } from './command-executor.service.js';
 import { CommandRegistryService } from './command-registry.service.js';
+import { CommandRuntimeApprovalVerifier } from './runtime-approval-verifier.js';
 import { COMMANDS_REDIS } from './commands.tokens.js';
 
 const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
@@ -24,9 +26,16 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
       inject: [COMMANDS_QUEUE_HANDLE],
     },
     CommandRegistryService,
+    CommandAuthorizationService,
+    CommandRuntimeApprovalVerifier,
+    CommandExecutorService,
+  ],
+  exports: [
+    CommandRegistryService,
+    CommandAuthorizationService,
+    CommandRuntimeApprovalVerifier,
     CommandExecutorService,
   ],
-  exports: [CommandRegistryService, CommandExecutorService],
 })
 export class CommandsModule implements OnApplicationShutdown {
   constructor(@Inject(COMMANDS_QUEUE_HANDLE) private readonly handle: QueueHandle) {}

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

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

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

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

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

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

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

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

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

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

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

@@ -6,11 +6,10 @@ import {
   type OnModuleDestroy,
 } from '@nestjs/common';
 import { SummarizationService } from './summarization.service.js';
-import { SessionGCService } from '../gc/session-gc.service.js';
 import {
   QueueService,
-  QUEUE_SUMMARIZATION,
   QUEUE_GC,
+  QUEUE_SUMMARIZATION,
   QUEUE_TIER_MANAGEMENT,
 } from '../queue/queue.service.js';
 import type { Worker } from 'bullmq';
@@ -23,14 +22,12 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
 
   constructor(
     @Inject(SummarizationService) private readonly summarization: SummarizationService,
-    @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
     @Inject(QueueService) private readonly queueService: QueueService,
   ) {}
 
   async onModuleInit(): Promise<void> {
     const summarizationSchedule = process.env['SUMMARIZATION_CRON'] ?? '0 */6 * * *'; // every 6 hours
     const tierManagementSchedule = process.env['TIER_MANAGEMENT_CRON'] ?? '0 3 * * *'; // daily at 3am
-    const gcSchedule = process.env['SESSION_GC_CRON'] ?? '0 4 * * *'; // daily at 4am
 
     // M6-003: Summarization repeatable job
     await this.queueService.addRepeatableJob(
@@ -56,15 +53,12 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     });
     this.registeredWorkers.push(tierWorker);
 
-    // M6-004: GC repeatable job
-    await this.queueService.addRepeatableJob(QUEUE_GC, 'session-gc', {}, gcSchedule);
-    const gcWorker = this.queueService.registerWorker(QUEUE_GC, async () => {
-      await this.sessionGC.sweepOrphans();
-    });
-    this.registeredWorkers.push(gcWorker);
+    // Retire any repeatable global GC schedule created by older deployments.
+    // Session cleanup is now triggered only by an authorized session lifecycle operation.
+    await this.queueService.removeRepeatableJobs(QUEUE_GC, 'session-gc');
 
     this.logger.log(
-      `BullMQ jobs scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}", gc="${gcSchedule}"`,
+      `BullMQ jobs scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}"`,
     );
   }
 

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,9 +1,13 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 
-const SESSION_SYSTEM_KEY = (sessionId: string) => `mosaic:session:${sessionId}:system`;
-const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string) =>
-  `mosaic:session:${sessionId}:system:fragments`;
+const scopedSessionId = (sessionId: string, scope: ActorTenantScope) =>
+  `${scope.tenantId}:${scope.userId}:${sessionId}`;
+const SESSION_SYSTEM_KEY = (sessionId: string, scope: ActorTenantScope) =>
+  `mosaic:session:${scopedSessionId(sessionId, scope)}:system`;
+const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string, scope: ActorTenantScope) =>
+  `mosaic:session:${scopedSessionId(sessionId, scope)}:system:fragments`;
 const SYSTEM_OVERRIDE_TTL_SECONDS = 604800; // 7 days
 
 interface OverrideFragment {
@@ -20,9 +24,9 @@ export class SystemOverrideService {
     this.handle = createQueue();
   }
 
-  async set(sessionId: string, override: string): Promise<void> {
+  async set(sessionId: string, override: string, scope: ActorTenantScope): Promise<void> {
     // Load existing fragments
-    const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId));
+    const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope));
     const fragments: OverrideFragment[] = existing
       ? (JSON.parse(existing) as OverrideFragment[])
       : [];
@@ -37,11 +41,11 @@ export class SystemOverrideService {
     // Store both: fragments array and condensed result
     const pipeline = this.handle.redis.pipeline();
     pipeline.setex(
-      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
+      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
       SYSTEM_OVERRIDE_TTL_SECONDS,
       JSON.stringify(fragments),
     );
-    pipeline.setex(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
+    pipeline.setex(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
     await pipeline.exec();
 
     this.logger.debug(
@@ -49,21 +53,21 @@ export class SystemOverrideService {
     );
   }
 
-  async get(sessionId: string): Promise<string | null> {
-    return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId));
+  async get(sessionId: string, scope: ActorTenantScope): Promise<string | null> {
+    return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId, scope));
   }
 
-  async renew(sessionId: string): Promise<void> {
+  async renew(sessionId: string, scope: ActorTenantScope): Promise<void> {
     const pipeline = this.handle.redis.pipeline();
-    pipeline.expire(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
-    pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
+    pipeline.expire(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
+    pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
     await pipeline.exec();
   }
 
-  async clear(sessionId: string): Promise<void> {
+  async clear(sessionId: string, scope: ActorTenantScope): Promise<void> {
     await this.handle.redis.del(
-      SESSION_SYSTEM_KEY(sessionId),
-      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
+      SESSION_SYSTEM_KEY(sessionId, scope),
+      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
     );
     this.logger.debug(`Cleared system override for session ${sessionId}`);
   }

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

@@ -162,6 +162,23 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
     );
   }
 
+  /**
+   * Remove every existing repeatable schedule for a job name. This supports
+   * safe retirement of previously registered system-wide jobs.
+   */
+  async removeRepeatableJobs(queueName: string, jobName: string): Promise<number> {
+    const queue = this.getQueue(queueName);
+    const jobs = await queue.getRepeatableJobs();
+    const matchingJobs = jobs.filter((job) => job.name === jobName);
+    await Promise.all(matchingJobs.map((job) => queue.removeRepeatableByKey(job.key)));
+    if (matchingJobs.length > 0) {
+      this.logger.log(
+        `Removed ${matchingJobs.length} repeatable "${jobName}" job(s) from "${queueName}"`,
+      );
+    }
+    return matchingJobs.length;
+  }
+
   /**
    * Register a Worker for the given queue name with error handling and
    * exponential backoff.

docs/MISSION-MANIFEST.md

@@ -67,10 +67,11 @@ The MVP is complete when ALL declared workstreams are complete AND every cross-c
 
 ## Workstreams
 
-| #   | ID  | Name                                        | Status            | Manifest                                                                | Notes                                               |
-| --- | --- | ------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
-| W1  | FED | Federation v1                               | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) | 7 milestones, ~175K tokens, issues #460–#466 filed  |
-| W2+ | TBD | (additional workstreams declared as scoped) | —                 | —                                                                       | Scope creep is expected and explicitly accommodated |
+| #   | ID   | Name                                        | Status            | Manifest                                                                | Notes                                               |
+| --- | ---- | ------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
+| W1  | FED  | Federation v1                               | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) | 7 milestones, ~175K tokens, issues #460–#466 filed  |
+| W2  | TESS | Tess interaction agent                      | planning-complete | [docs/tess/MISSION-MANIFEST.md](./tess/MISSION-MANIFEST.md)             | 5 milestones; issue #706; M1 issue #707 ready       |
+| W3+ | TBD  | (additional workstreams declared as scoped) | —                 | —                                                                       | Scope creep is expected and explicitly accommodated |
 
 ### Likely Additional Workstreams (Not Yet Declared)
 

docs/PRD.md

@@ -79,6 +79,102 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 
 ---
 
+## Tess Interaction Agent Workstream (TESS)
+
+### Problem and Objective
+
+Jason needs one durable, operator-facing Mosaic agent outside Hermes that is reachable through a dedicated Discord channel and CLI, can attach to and operate the Mosaic fleet and transitional Hermes agents, and preserves context across restarts and compaction. Mos remains the coding/general fleet orchestrator; Tess is the complementary human interaction, visibility, control, and migration agent.
+
+The objective is to ship **Tess** (from _tessera_, a piece of a mosaic) as a Pi-native, GPT-5.6 Sol agent with high reasoning. Tess must use Mosaic-owned contracts and plugins so Hermes can be replaced incrementally rather than becoming a permanent architectural dependency.
+
+### Scope
+
+#### In Scope
+
+1. `TESS-ARP-001`: A runtime-neutral `AgentRuntimeProvider` contract supporting `listSessions`, `streamSession`, `sendMessage`, `terminate`, `getSessionTree`, `attach`, health, capability discovery, and normalized events/errors.
+2. `TESS-PI-001`: A long-running Pi-native Tess agent profile/service pinned to GPT-5.6 Sol with high reasoning, explicit tool policy, lifecycle hooks, durable checkpoints, and restart recovery.
+3. `TESS-DSC-001`: Dedicated Discord channel binding to Tess through the Mosaic gateway, with allowlists/RBAC, thread/reply policy, streaming, attachments, approvals, and correlation IDs.
+4. `TESS-CLI-001`: `mosaic tess` CLI commands for chat, status, session listing, attach/detach, send/steer/stop, provider health, and recovery.
+5. `TESS-FLT-001`: Fleet plugin capabilities for roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, and controlled restart/recovery.
+6. `TESS-MOS-001`: Explicit Mos coordination boundary and tools: hand off orchestration requests, observe mission/task state, receive results, and never silently compete for orchestration authority.
+7. `TESS-HRM-001`: Transitional Hermes adapter for profiles/agents, sessions, streaming/messages, Kanban, skills, memory, tools, cron, and health, using capability negotiation and fail-closed unsupported operations.
+8. `TESS-MEM-001`: Unified memory/retrieval plugin with scoped search/recent/capture/stats, startup context injection, provenance, redaction, namespace isolation, and flat-file/project truth precedence.
+9. `TESS-STA-001`: Durable agent state, inbox, handoff, compaction-recovery, and resume reconstruction.
+10. `TESS-PLG-001`: Plugin/tool catalog covering runtime bootstrap, repository/PR workflow, fleet diagnostics, incident-safe read operations, Discord interaction, and extensible MCP/skill discovery.
+11. `TESS-TRN-001`: Replaceable transport providers: tmux/fleet now, Matrix/native Mosaic transport later, with no Discord/CLI business logic coupled to transport details.
+12. `TESS-SEC-001`: RBAC, per-operation authorization, explicit approval for destructive/privileged/customer-visible actions, audit events, secret/PII redaction, tenant isolation, and bounded command execution.
+13. `TESS-SEC-002`: Command execution SHALL enforce declared scope/role server-side; admin/system and destructive operations SHALL require policy-bound durable approval.
+14. `TESS-SEC-003`: Every session list/read/attach/send/terminate operation SHALL enforce server-derived owner and tenant scope; guessed or client-supplied IDs SHALL grant no authority.
+15. `TESS-SEC-004`: MCP tools SHALL derive actor/tenant from authenticated context and SHALL NOT accept caller-controlled identity fields.
+16. `TESS-SEC-005`: Discord plugin ingress SHALL authenticate service identity, enforce guild/channel/user allowlists, propagate correlation/message IDs, and reject replay.
+17. `TESS-SEC-006`: Secret/PII classification and redaction SHALL occur before persistence and before channel egress, including tool metadata and authentication flows.
+18. `TESS-SEC-007`: Approvals SHALL be one-time, expiring, actor/tenant-bound, and cryptographically bound to the exact structured action digest.
+19. `TESS-SEC-008`: Ingress, provider sends, tool side effects, and responses SHALL use durable inbox/outbox/checkpoints and idempotency records for restart-safe replay.
+20. `TESS-SEC-009`: Garbage collection and retention SHALL be session/tenant scoped unless executed as a separately authorized and audited system-wide job.
+21. `TESS-OBS-001`: Structured logs, traces, health/readiness, provider latency/errors, session lifecycle, tool audit, and actionable recovery diagnostics.
+22. `TESS-MIG-001`: Capability inventory and staged Hermes-to-Mosaic migration matrix with coexistence, cutover, rollback, and deprecation gates.
+
+#### Out of Scope
+
+1. Replacing Mos as coding/general fleet orchestrator.
+2. Making Hermes the Mosaic core or coupling Mosaic domain logic to Hermes schemas.
+3. Migrating every historical chat verbatim; only policy-compliant indexed summaries and user-selected sessions are migrated.
+4. Unrestricted shell execution from Discord.
+5. Full web UI parity in the first Tess operational milestone; gateway contracts must remain web-consumable.
+6. Replacing tmux before Matrix/native transport reaches operational parity.
+
+### Stakeholder and User Requirements
+
+- Jason must be able to converse with the same Tess session from Discord and CLI.
+- Jason must be able to see what is running, stale, blocked, or unhealthy without attaching manually to every session.
+- Jason must be able to attach to Tess and authorized fleet sessions through supported CLI controls.
+- Tess must collaborate with Mos and the fleet while preserving a single clear orchestration authority.
+- The system must migrate useful Hermes/OpenClaw capabilities intentionally, with evidence, instead of copying implementations wholesale.
+
+### Non-Functional Requirements
+
+1. **Security:** default-deny provider/tool capabilities, least privilege, no secrets in logs/prompts/commits, Discord user/channel authorization, and auditable approvals.
+2. **Reliability:** durable inbox/checkpoints; idempotent message handling; reconnect with bounded backoff; no message loss or duplicate execution across gateway restart.
+3. **Performance:** first acknowledgement within 2 seconds when connected; streamed agent output begins within 5 seconds excluding model/provider delay; status reads return within 2 seconds under nominal local conditions.
+4. **Observability:** every ingress message and resulting provider/tool operation carries a correlation ID across Discord, gateway, Tess, provider, and audit events.
+5. **Maintainability:** channel, runtime, transport, memory, and external-agent integrations remain adapter-based with contract tests.
+6. **Privacy:** only scoped context enters external runtimes; persisted messages/memories follow retention and redaction policy.
+7. **Portability:** Tess runs through Pi/Mosaic contracts and does not require Hermes to start or serve native Mosaic operations.
+
+### Acceptance Criteria
+
+1. `AC-TESS-01`: A dedicated Discord channel and `mosaic tess chat` connect to one durable Tess session and stream responses bidirectionally.
+2. `AC-TESS-02`: `mosaic tess status|sessions|tree|attach|send|stop` operate against authorized provider capabilities with stable typed outputs and actionable errors.
+3. `AC-TESS-03`: Tess runs GPT-5.6 Sol at high reasoning and its effective runtime/model/tool policy is visible through status without exposing credentials.
+4. `AC-TESS-04`: Tess can inspect and message the Mosaic fleet, hand orchestration work to Mos, and demonstrate that Tess does not independently claim Mos-owned orchestration work.
+5. `AC-TESS-05`: Hermes adapter demonstrates session listing, streaming/message delivery, hierarchy mapping, and at least one approved capability in each of Kanban, skills, memory, tools, and cron—or reports unsupported capabilities fail-closed.
+6. `AC-TESS-06`: Restart/compaction test preserves session identity, pending inbox, last durable checkpoint, and a resumable handoff without duplicate side effects.
+7. `AC-TESS-07`: Unauthorized Discord users/channels, cross-tenant access, unsafe tool calls, forged approvals, and sensitive-output cases are denied and audited.
+8. `AC-TESS-08`: tmux/fleet and Matrix/native transport implementations pass the same provider contract suite; Matrix may remain non-default until readiness gates pass.
+9. `AC-TESS-09`: Baseline quality gates, unit/integration/contract tests, Discord+CLI E2E, restart/recovery tests, independent code review, and security review are green.
+10. `AC-TESS-10`: Migration matrix documents every audited Hermes/OpenClaw capability as native, adapted, deferred, or rejected, with cutover and rollback evidence.
+11. `AC-TESS-11`: User, admin, developer, API/OpenAPI, operations/recovery, and plugin-authoring documentation is current and linked from the sitemap.
+
+### Constraints, Dependencies, Risks, and Assumptions
+
+- Dependency: Mosaic gateway remains the single API surface; Pi is the native runtime; Valkey/PostgreSQL provide canonical durable state where required.
+- Dependency: Discord bot credentials and dedicated channel ID are deployment secrets provisioned outside source control.
+- Risk: Tess could drift into a second orchestrator. Mitigation: explicit role policy, Mos handoff contract, authority checks, and E2E boundary tests.
+- Risk: broad Hermes compatibility can freeze legacy semantics into Mosaic. Mitigation: Mosaic-owned normalized contracts and capability negotiation.
+- Risk: Discord creates a privileged remote-control surface. Mitigation: pairing/allowlists, RBAC, approvals, rate limits, audit, and safe tool classes.
+- Risk: transcript ingestion can violate privacy or overload memory. Mitigation: scoped opt-in import, redacted summaries, provenance, retention, and deduplication.
+- Risk: current root filesystem has limited headroom. Mitigation: isolated worktrees, no duplicated dependency installation unless required, and cleanup only after active-lane verification.
+- `ASSUMPTION:` The public name is **Tess**, because the user requested a name and the tessera/Mosaic relationship is distinctive; config must permit later display-name changes without renaming APIs or storage keys.
+- `ASSUMPTION:` The dedicated Discord channel ID and final guild policy will be supplied/provisioned during deployment, so implementation uses explicit configuration and fail-fast startup validation.
+- `ASSUMPTION:` tmux/fleet is the production transport for the first operational milestone; Matrix/native transport is implemented behind the same contract and promoted only after parity/reliability verification.
+- `ASSUMPTION:` Project/task truth remains in canonical Mosaic/project stores; semantic memory systems are retrieval/mirror layers, not hidden authorities.
+
+### Testing and Delivery Intent
+
+Delivery uses five gated milestones: runtime contracts/security; Pi service/state; Discord/CLI; fleet/Hermes/plugin suite; migration/Matrix/recovery/qualification. Every source-code task requires tests, independent review, a PR to `main`, terminal-green CI, and issue/task closure. Production activation additionally requires a clean-host Pi launch, dedicated Discord channel smoke test, CLI attach test, restart/recovery drill, and rollback procedure.
+
+---
+
 ## Architecture
 
 ### High-Level System Diagram

docs/TASKS.md

@@ -14,9 +14,10 @@
 
 ## Workstream Rollup
 
-| id  | status            | workstream          | progress         | tasks file                                        | notes                                                           |
-| --- | ----------------- | ------------------- | ---------------- | ------------------------------------------------- | --------------------------------------------------------------- |
-| W1  | planning-complete | Federation v1 (FED) | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md) | M1 task breakdown populated; M2–M7 deferred to mission planning |
+| id  | status            | workstream             | progress         | tasks file                                        | notes                                                           |
+| --- | ----------------- | ---------------------- | ---------------- | ------------------------------------------------- | --------------------------------------------------------------- |
+| W1  | planning-complete | Federation v1 (FED)    | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md) | M1 task breakdown populated; M2–M7 deferred to mission planning |
+| W2  | planning-complete | Tess interaction agent | 0 / 5 milestones | [docs/tess/TASKS.md](./tess/TASKS.md)             | Issue #706; independent planning gate PASS; M1 issue #707 ready |
 
 ## Cross-Cutting Tracking
 

docs/architecture/channel-protocol.md

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

docs/fleet/proposals/mosaic-platform-prd/DEBATE-FINDINGS.md

@@ -1,61 +0,0 @@
-# Debate Findings & Dispositions — Mosaic Platform PRD
-
-> **Convener:** mos-claude-1 · **Date:** 2026-07-09 · **Panel:** 9 personas × 2 rounds (8 Claude lenses + independent Codex runtime), 20 agents, ~1.05M tokens
-> **Artifacts:** `jarvis-brain:docs/scratchpads/mosaic-platform-prd-debate/` (THREAD.md — full transcript · SYNTHESIS.md — Principal-Engineer close-out)
-> **Mandate (Jason, 2026-07-09):** "debate and make judgment calls." D1–D12 were held fixed; the panel attacked only the implementing structure. Dispositions below are the convener's judgment calls, folded into the sibling docs in this directory. Items marked **OPEN — Jason** need his call at ratification.
-
-## How to read this
-
-Every synthesis finding (SYNTHESIS.md §1, items 1–24) is dispositioned here. **Accepted** findings are folded into the PRDs/YAML as inline fixes or "Debate-accepted deltas" rows; this file is the traceability record. Severity labels are the panel's (P0 blocker → P3 note).
-
-## P0 findings — all accepted, folded inline
-
-| #   | Finding                                                                                                                                                  | Disposition                                                                                                                                                                                                                                                       |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | Storage-authority contradiction (X2 "relational + flat-file backends" vs Q "Postgres sole record")                                                       | **Accepted.** X2 rewritten: Postgres authoritative for all product entities; flat-file backend is a derived, regenerated, **read-only projection**.                                                                                                               |
-| 2   | Phase-1 Jarvis executes external PA ops before the relay exists (J2 vs NS-11)                                                                            | **Accepted.** J2 split: **J2a** workspace-internal entities (phase 1) / **J2b** external integrations (phase 2, `depends_on: [P2]`). Phase-1 has no external credential path at all.                                                                              |
-| 3   | `phase` vs `depends_on` disagree; dispatcher obedience undefined                                                                                         | **Accepted.** Phases encoded as real DAG edges (`X2 depends_on [J2a, P2]`, J2b gate above); sandbox dispatch-test added to ratification checklist (README Gate Zero §).                                                                                           |
-| 4   | Four load-bearing upstream artifacts unverified (memory subsystem, Hermes-MCP tool equivalents, push pipeline, wake/event router)                        | **Accepted.** README gains **Gate Zero** (pre-ratification artifact audit); presumed-MISSING rows get goal cards now: **M1** (memory subsystem), **J6** (event/wake router), **K3** (push pipeline). Parity map's MCP row re-pointed at concrete deliverables.    |
-| 5   | X-R4 migration manifest wrong about its own source tree (phantom `tickets.json`, unlisted dirs, six divergent memory stores, live Vikunja sync unmapped) | **Accepted.** X-R4 rewritten: migrator stage 1 = machine-generated source census (incl. untracked paths + all memory stores), per-path disposition, any `unknown` blocks; re-point list generated from `tools/sync_*.py`; Vikunja disposition line added to X-R6. |
-
-## P1 findings — all accepted
-
-| #   | Finding                                                                                                   | Disposition (folded as deltas)                                                                                                                                                                                                                                                                                            |
-| --- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 6   | Events have no provider join key; re-point duplicates the calendar                                        | **Accepted.** Provider-sourced events migrate **from the provider**; flat files supply only brain-native events. DST/recurrence fixture is the AC (X-R6 delta).                                                                                                                                                           |
-| 7   | Approval pipeline has no state machine (double-execute / approve≠execute)                                 | **Accepted.** P deltas: CAS on one durable row, terminal states, consumed-event dedupe table (shared substrate with bridge + wake dedupe), payload persisted at request time, poll/ack outcomes, per-capability retry class, staleness bound, `approved_unexecuted` alarm, re-surface = re-**prepare** with machine diff. |
-| 8   | "Cannot bypass by construction" false: agent-readable vault creds + host-resident creds outside the relay | **Accepted.** Credentials gateway-only + scoped capability tokens; P1 gains host credential inventory with continuous scheduled scan in the health floor; clean-host AC passes with empty exemption list.                                                                                                                 |
-| 9   | Silent auto-deny steady state (fail-closed TTL + single surface + unprovisioned push)                     | **Accepted.** K gains homeserver ops + monitored push (K3); CLI approval surface ships **with** P2; delivered/seen tracking + TTL/2 escalation; `denied` / `expired_seen` / `expired_unseen` distinct terminal states.                                                                                                    |
-| 10  | Prompt injection → durable memory; wake turns add system-role injection                                   | **Accepted.** J2 write-side trust rule (transitive `source_trust=external`; standing-instruction-shaped content needs user ratification before retrievable); wake turns templated with provenance-tagged data fields.                                                                                                     |
-| 11  | Exactly-one-Jarvis has no fencing incl. the Matrix send path                                              | **Accepted.** New **J-R16** workspace lease `(workspace_id, epoch)` CAS row in product Postgres; epoch on every write; pre-send lease re-check; takeover notice; degraded = mute-with-notice. NS-10 amended: one main agent per **workspace**.                                                                            |
-| 12  | Matrix principal resolution undefined (Codex #2, unanswered in R2)                                        | **Accepted.** K/P delta: immutable Matrix user ID + bridge provenance + workspace membership → product principal; unlinked/bridged-unlinked identities read-only, cannot approve/butt-in/trigger external writes. All four Codex fixtures = deny + audit.                                                                 |
-| 13  | Policy evaluation time undefined (Codex #7, unanswered in R2)                                             | **Accepted.** Immutable policy snapshot on every prepared action/card; execution revalidates or fails `policy_changed`; delegated effects gated by grant **intersection**.                                                                                                                                                |
-
-## P2/P3 findings — accepted (see per-PRD delta sections)
-
-14 Hermes evidence snapshot **before** stop (machine gate) · 15 Q1 crash barriers + `external_refs` unique-index table (one mechanism, three consumers) · 16 rollback honestly scoped (transport-only, point-of-no-return = first native card) + bounded day-30 review with three recorded outcomes · 17 human-attention budget (rate limits, quotas, deferrable flag, away state) · 18 self-referential-loop containment (provenance labels, source-grounded retrieval preference, retrieval eval gate ≥50 queries / ≥90% baseline recall@5 + negative queries, tombstones, priority budget, day-1 trend telemetry) · 19 butt-in exclusive lease + structured control-plane API + break-glass doctrine · 20 default-closed capability gating with `unclassified` third state · 21 per-agent atomic approval-routing cutover table · 22 `needs-decision` card lifecycle (immutable spec + typed amendments; `ratified_by` authorizes dispatch, never merge) · 23 retention class per durable table; dedupe pruning checkpoint-coupled · 24 AC-NS-8 made measurable (distinct quota pools pinned in profile; TTFT p95 ≤ 1.2× baseline, ≥30 interleaved turns).
-
-**All accepted.** None conflicts with D1–D12.
-
-## Open disagreements — convener judgment calls
-
-| §   | Question                                                                                                                                                 | Call                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 3.1 | Gate architecture: tiered blocking pack (Moonshot+Ops+ML-Cal) vs 4 artifact-existence machine gates + pass/fail-free pre-registered dossier (Contrarian) | **Adopted the agreed floor now** (4 machine gates on irreversible transitions, pre-registration, priced amendments, day-1 emission — folded into X). Superstructure choice is **OPEN — Jason**. Convener recommendation: **Contrarian's dossier + dumb gates** — the tier demonstrably gamed itself within one debate round (13+ claims vs cap 10, slot-riding, zero demotions); simple machine gates don't degrade under pressure. |
-| 3.2 | Audit schema: additive-only typed schema (Coder-Data) vs six-field mandatory envelope + typed payloads + pinned checked-in queries (Contrarian)          | **Adopted: minimal envelope + schema-on-read** (folded into P1 delta). Rationale: preserves "can't add data later" essentials without a god-schema by committee; an additive typed layer can be grown later where query pain proves it.                                                                                                                                                                                             |
-| 3.3 | Unclassified capability: reject at call time vs version-scoped activation hold vs capability-scoped hold                                                 | **Adopted: capability-scoped hold** (Contrarian R2#6a, synthesis editor concurs) — gate the capability, ship the version; security patches are never pinned behind classification.                                                                                                                                                                                                                                                  |
-| 3.4 | Away mode: fail-closed expiry labeled `expired_during_away` vs suppress preparation while away                                                           | **Adopted: suppress preparation** of non-deferrable requests while away + audited suppressed-preparations list swept on return. Cleaner than labeling corpses; nothing expires that was never surfaced.                                                                                                                                                                                                                             |
-| 3.5 | Memory-exclusion scope for measurement artifacts                                                                                                         | **Adopted: normative/parametric split** (Contrarian R2#4) — rules the agent is scored against stay retrievable; thresholds/seeds/drill timings/canary templates are excluded.                                                                                                                                                                                                                                                       |
-| 3.6 | Statistical instruments                                                                                                                                  | **Adopted:** deterministic named crash barriers as the gate; residual randomized soak is **trace-directed**, not wall-clock-uniform.                                                                                                                                                                                                                                                                                                |
-| 3.7 | K2 scope narrowing by Hermes traffic audit                                                                                                               | **Adopted as a Gate Zero action:** run the audit pre-ratification; platforms with live traffic become the must-have subset gating X3.                                                                                                                                                                                                                                                                                               |
-
-## Process rules adopted (README)
-
-- **Gate Zero** — pre-ratification upstream-artifact audit (`present @ SHA` or MISSING → goal card).
-- **Conflict register** — spec contradictions block the requirement, not the mission ("alert, don't auto-resolve" promoted to specs).
-- **DoD line** on every goal card (runbook, health-floor alerts, AGENTS.md).
-- **Silent-roster rule** — a panel member's silent round records their open findings as open items, never consensus (Codex's R2 silence on #2/#7 is the instance; both were folded as P1 items 12–13 above, explicitly not consensus-resolved).
-
-## Addendum — logging & telemetry (Jason, 2026-07-09, post-debate)
-
-Requirement raised outside the panel, folded in the same pass: Mosaic Stack must support **inbound error reporting/logging** from agents and installs, plus **optional anonymous agentic-efficiency telemetry** — no IP or PII capture, opt-in. The P0 of this capability already exists: **MALS** (Mosaic Agent Log System, FastAPI+Postgres, `~/src/mals`), currently dark because its k3s migration landed without an Ingress (tracked: infrastructure #135). Folded as new **workstream L** (L1 restore MALS · L2 Mosaic-native ingestion · L3 anonymous telemetry) + standing objective **NS-14**. Day-1 trial-metric emission (finding 18) targets MALS until W3 panels exist.

docs/fleet/proposals/mosaic-platform-prd/PRD-backlog-providers.md

@@ -1,58 +0,0 @@
-# PRD — Backlog Provider Sync Adapters · Workstream Q
-
-> **Status:** DRAFT for ratification · **Goals:** Q1–Q3 · **Doctrine:** NS-12 (ratified D3)
-> **Debate pass 2026-07-09:** panel findings folded — see `DEBATE-FINDINGS.md`.
-
-## Mission
-
-Users choose where they _see and touch_ work — Gitea, GitHub, a local kanban — while the **Mosaic Backlog on native Postgres stays the sole record and dispatch engine** (upholds ASM-1; NS-3/NS-4/NS-5 guarantees never depend on an external provider). Providers attach as bidirectional sync adapters.
-
-## Requirements
-
-### Adapter interface + Gitea (Q1)
-
-| ID   | Requirement                                                                                                                                                         |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Q-R1 | A `BacklogProviderAdapter` interface: map card ⇄ external item (create/update/close/comment/label), with stable external-id linkage stored on the card.             |
-| Q-R2 | Sync is bidirectional and conflict-safe: native record wins on divergence; external edits arrive as proposed mutations (applied if non-conflicting, else surfaced). |
-| Q-R3 | Claims, TTLs, depends_on DAG, and dispatch state live **only** in the native record; adapters project them (e.g. as labels/comments) but never own them.            |
-| Q-R4 | Gitea adapter first (webhook + API), configured per workspace: repo mapping, label conventions, direction (mirror-out / mirror-in / full).                          |
-| Q-R5 | Adapter enable/disable is workspace configuration; zero adapters is a fully supported mode.                                                                         |
-
-### GitHub (Q2)
-
-| ID   | Requirement                                                                                                                                                             |
-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Q-R6 | Same interface, GitHub Issues backend. Existing `packages/cli-tools` platform detection informs but does not implement this (that is dev tooling, not product runtime). |
-
-### Local kanban (Q3)
-
-| ID   | Requirement                                                                                                                                                                                                          |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Q-R7 | A webUI kanban board over the native backlog (no external provider needed) — the "local kanban" choice. Builds on W3's card views and/or the existing `KanbanBoard` component upgraded from demo-grade to live data. |
-
-## Debate-accepted deltas (2026-07-09) — normative
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                          |
-| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Q-R8  | **External-ref linkage is one shared mechanism:** a unique-indexed `external_refs(entity_id, system, external_id)` table serves adapter linkage (Q-R1), migration idempotency (X-R4 anti-join), and re-point verification (X-R6) — built once, three consumers. Idempotent upsert; a violated unique index is a converge signal, never an overwrite. |
-| Q-R9  | **Crash-safe external creates:** the adapter writes a `pending-link` row **before** any external create and embeds a deterministic card-id marker in the created item, so a crash between create and link-back is recovered by scan, never by duplicate creation.                                                                                    |
-| Q-R10 | **Echo-loop guard:** both directions carry revision counters; adapter-authored external edits are tagged (marker/actor) and skipped on read-back. A sync cycle that would re-import its own write is a hard test failure.                                                                                                                            |
-| Q-R11 | The sync engine is a **level-triggered reconciler** over desired-vs-observed state (same doctrine as J6), not a webhook-only event chase: webhooks accelerate convergence, the reconciler guarantees it. Missed webhooks are a latency event, not a correctness event.                                                                               |
-| Q-R12 | Card spec immutability (J-R20) projects cleanly: the mirrored issue body is the pinned spec revision; amendments append as **ordered provider comments**, never body rewrites, so external watchers see the same amendment history as the native record.                                                                                             |
-
-## Acceptance criteria
-
-1. A card created by Jarvis (J3) appears as a Gitea issue within one sync interval; closing the issue in Gitea marks the card for review, not silent closure; dispatch/claims never round-trip through Gitea.
-2. Killing the adapter mid-mission: dispatch continues unaffected (record is native); on restart, sync converges without duplicates.
-3. The same mission can be mirrored to Gitea and viewed on the local kanban simultaneously without state divergence.
-4. **Named crash barriers** at every external-call boundary (`before_external_create`, `after_create_before_link`, `after_link_before_ack`): kill the adapter at each; zero duplicate external items, zero orphaned cards. CI rule: a new external call site without a named barrier + kill test **fails the build**. Residual randomized soak is trace-directed (§3.6 disposition).
-
-## Non-goals
-
-- External provider AS the backlog (vetoed — "truly swappable backends" option declined 2026-07-09).
-- Two-way sync of claims/TTL semantics (external systems can't express them; projection only).
-
-## Assumptions
-
-- ASSUMPTION: the delivery fleet's _engineering_ PR/issue flow on the stack repo itself continues to use `cli-tools`/Gitea directly — workstream Q is the product feature for user workspaces, not a replacement for the dev workflow.

docs/fleet/proposals/mosaic-platform-prd/PRD-hermes-decommission.md

@@ -1,83 +0,0 @@
-# PRD — Hermes Decommission & Tenant-1 Migration · Workstream X
-
-> **Status:** DRAFT for ratification · **Goals:** X1–X3 · **Doctrine:** NS-13, ASM-8 (Hermes untouched until verified parity)
-> Ratified direction (D2, 2026-07-09): Mosaic absorbs **all four** Hermes functions — messaging bridge, task board, permission relay, multi-platform reach.
-> **Debate pass 2026-07-09:** panel findings folded — this PRD took the heaviest rewrite (storage authority, migration census, memory-store hygiene, honest rollback scope). See `DEBATE-FINDINGS.md`.
-
-## Deployment scope (D12/ASM-9)
-
-The trial runs in the **homelab**. Hermes and the primitive-era stack (`mos-claude.service`, jarvis-brain boards) live in the **USC/web1 environment**, which is untouched during the trial. This workstream therefore lands in two stages: **X-in-homelab** (prove parity where the fleet is native — mainly K/P/Q verification plus tenant-1 migration) and **X-at-USC** (post-trial adoption: apply the parity checklist to web1, migrate Mos-on-web1 to `mosaic-agent@orchestrator`, then decommission Hermes there, with `/src/infrastructure` GitOps updates in the same delivery set).
-
-**Trial go/no-go (D12/ASM-9 gate):** the homelab→USC promotion is **owner-judgment**, not an automated metric. The stage gate is: _Jason instantiates and operates the split-agent stack in the homelab and is satisfied with its operation._ Only on that explicit sign-off does X-at-USC begin. The capability ACs (AC-NS-8…11) are the evidence Jason weighs; they inform the decision but do not auto-trigger USC deployment.
-
-## Mission
-
-Retire Hermes entirely. Mosaic becomes the platform for transport (Matrix connector), task board (native backlog + webUI/adapters), approvals (permission relay), and multi-platform reach (mautrix bridges). In the same arc, Jason's jarvis-brain flat-file data migrates into the product as **tenant #1**, making the product's PA feature set the dogfooded default.
-
-## Parity map (what replaces what)
-
-| Hermes function                       | Mosaic replacement                                                                                                                            | Workstream |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Messaging bridge (Discord/Telegram/…) | Matrix connector + mautrix bridges                                                                                                            | K1, K2     |
-| Kanban / task board                   | Native Mosaic Backlog + webUI board + provider adapters                                                                                       | A\*, Q, W3 |
-| Permission relay (`permissions_*`)    | Guard-rails engine + approval queue (Matrix + webUI)                                                                                          | P1–P3      |
-| Cross-platform user reach             | mautrix bridges (agents speak Matrix only)                                                                                                    | K2         |
-| Hermes MCP tools in agent sessions    | **Per-tool equivalence table** (Gate Zero artifact): approvals → P2, board ops → Q1/A\*, messaging → K1 — not a generic "gateway API" gesture | P2, Q1, K1 |
-
-## Requirements
-
-### Parity checklist + cutover plan (X1)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| X-R1  | A written, testable parity checklist per row above; each item verified in production before its Hermes counterpart is disabled. The checklist is seeded from a **pre-trial usage audit**: per-MCP-tool and per-capability call counts over a trailing window, plus an inventory of Hermes-held provider callbacks/webhooks and secrets. Parity rows with `n < 5` real invocations in the window cannot be "verified by traffic" — they get **scheduled drills in weeks 1–3** of the observation window instead of silent green. |
-| X-R1a | **Approval-routing cutover is per-agent atomic:** a cutover table states, per agent, the single moment its `permissions_*` path flips from Hermes to the P relay. No agent ever has two live approval paths; no approval window where neither path is live.                                                                                                                                                                                                                                                                     |
-| X-R2  | Cutover is staged with rollback at every stage; Hermes runs untouched until AC-NS-11 is verified (ASM-8). **Rollback is honestly scoped (debate #16): it restores _transport_ (Hermes services + MCP registrations) — board/approval state created natively during the trial does NOT back-migrate.** The **point of no return is the first native-only card**; the runbook says so explicitly, and the abort path (below) is written before cutover, not during an incident.                                                   |
-| X-R3  | The Matrix charter's live-cutover rules apply: stated window, announce before/after, rollback ready.                                                                                                                                                                                                                                                                                                                                                                                                                            |
-
-### Tenant-1 migration (X2)
-
-**Framing (ratified 2026-07-09, storage authority clarified by debate P0 #1):** jarvis-brain **is the P0 (prototype) Mosaic Stack** — its flat-file data layer is the zeroth implementation of what the product does properly. Migration is therefore _P0 → proper Mosaic Stack_. **Native Postgres is the sole authoritative store for every product entity** (consistent with workstream Q's "sole record" doctrine and NS-3/NS-4/NS-5). A flat-file backend, where offered, is a **derived, regenerated, read-only projection** — the same relationship generated views have to JSON in the P0 today — never a co-equal write target. Two distinct data classes migrate — they are not the same destination and neither is frozen:
-
-- **(a) PA data** (projects, tasks, events, tickets, knowledge) → product entities in the Jason workspace (Project/Task/Event/KnowledgeEntry), authoritative in Postgres; flat-file export available as a read-only projection.
-- **(b) Agent memory & operational knowledge** (runbooks, digests, scratchpads, OpenBrain thoughts) → the **enhanced memory subsystem (goal M1: vector DB + memory service)**. This flow stays **live and writable** throughout — it was never Hermes and must not be frozen by the PA cutover.
-
-| ID   | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| X-R4 | **Stage 1 of the migrator is a machine-generated source census, not a hand-written file list** (debate P0 #5 — the hand list was already wrong about its own tree). The census walks the live repo (tracked + untracked), inventories every data path — `data/**`, all memory stores (`memory/`, `memories/`, `memory_store*`, `memory.md`, `brain.jsonl`, `jarvis.db`, digests), scratchpads, notes, prior-generation artifacts — and assigns each a disposition: `migrate-as-PA(entity type)` / `migrate-as-memory(M1 class)` / `derived-regenerate` / `retire-with-history`. **Any path dispositioned `unknown` blocks the run.** Stage 2 migrates per-disposition, preserving source ids in metadata; idempotency via anti-join on the shared `external_refs` table (Q-R8); named crash barriers at each phase boundary. A **field-map table** covers the full `brain.py` query surface (status, progress, due, priority, domain, notes, staleness) → product entity fields, so AC 2 is checkable field-by-field.                                                                                                                                                                                                                              |
-| X-R5 | Dry-run mode with a diffable report **generated from the census** (counts per disposition, per-entity field mapping, unmapped-field list — must be empty or explicitly waived); Jason ratifies the report before the real run (canonical-data gate — this is the one migration step that is his call).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| X-R6 | External sync jobs (GLPI, Google Calendar, ICS, Gmail, **Vikunja — disposition decided here: re-point or retire, not silently dropped**) each get a **written per-integration transition protocol**: freeze flat-file sync job → verify product integration live → re-point → verify → retire old job. **Provider-sourced events migrate FROM the provider, not from flat files** (flat files supply only brain-native events) — the provider join key is authoritative, so re-pointing cannot duplicate the calendar (debate #6). Calendar fixture (Codex): a DST-crossing recurring event with one moved and one cancelled occurrence, plus an all-day event, round-trips with zero duplicates and correct local times.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| X-R7 | Agent memory/operational knowledge (b) is migrated into the M1 memory subsystem **before** any jarvis-brain retirement; the memory write path stays continuously available (no read-only freeze of an active substrate). The census classifies every memory item: `ratified` / `superseded` / `draft` / `rejected` / `debate-artifact` / `protocol-normative` / `protocol-parametric`. **Parametric measurement artifacts (thresholds, seeds, drill timings, canary templates) are excluded from embedding** (§3.5 disposition — rules the agent is scored against stay retrievable; the knobs do not). Superseded/rejected items get **tombstones**, and supersession triggers re-embedding of affected summaries. **Retirement gate: a retrieval eval — ≥50 representative queries, ≥90% of baseline recall@5, plus negative queries (rejected/superseded content must NOT surface) — passes against M1 before any flat-file store goes read-only.** After cutover: write paths to retired stores are killed and a CI lint fails any reintroduction. Only once **both** (a) and (b) are migrated and verified is the jarvis-brain repo retired read-only (history preserved); generated views and brain.py retire. This closes the P0 prototype. |
-
-### Decommission (X3)
-
-| ID   | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| X-R8 | **Pre-stop evidence snapshot is a machine gate:** before Hermes stops, a checksummed snapshot of its state (board items, pending approvals, bridge registrations, per-tool usage counts) is captured and stored with the trial artifacts. The drill schedule (X-R1) and the credential-revocation report both **cite the snapshot checksum** — no snapshot, no stop. Then: services stopped, disabled, and removed from infra (GitOps: `/src/infrastructure` updated in the same delivery set); credentials revoked — the revocation report cites a **final scan** showing zero live references; MCP registrations removed from agent runtimes.              |
-| X-R9 | **Bounded day-30 review** between stop and removal, pre-registered before cutover (dossier: what will be measured, panels cited, drill results attached — see W-R15/L1 for where the metrics live, `stack_version`-segmented so mid-window upgrades don't blur rates). The review records exactly one of three outcomes: **promote** (remove Hermes), **extend with named blockers** (each blocker a card with an owner), or **abort** (execute the pre-written abort runbook; transport-only rollback per X-R2). "Insufficient data" is a recordable outcome that forces extend — never a shrug into promote. Any in-window regression flips back per X-R2. |
-
-## Machine gates on irreversible transitions (debate §3.1 agreed floor)
-
-Four **artifact-existence gates** — dumb, checkable, ungameable — sit on the irreversible transitions. Each is "the artifact exists and passes its check", not a scored rubric:
-
-1. **Pre-stop snapshot** exists with valid checksum (X-R8) — gates Hermes stop.
-2. **Census with zero `unknown` rows** exists (X-R4) — gates the PA migration run.
-3. **Retrieval eval pass record** exists (X-R7) — gates memory-store retirement.
-4. **All parity rows green-or-drilled** (X-R1: verified by traffic or by scheduled drill; no silent low-n green) — gates Hermes removal at day-30.
-
-The gate _superstructure_ beyond this floor (tiered blocking pack vs pre-registered dossier) is **OPEN — Jason** at ratification; convener recommendation in `DEBATE-FINDINGS.md` §3.1.
-
-## Acceptance criteria
-
-1. AC-NS-11: with Hermes stopped, no fleet or main-agent capability regresses.
-2. `python tools/brain.py today`'s information content is fully answerable by Jarvis from the product workspace post-X2, verified field-by-field against the X-R4 field-map table.
-3. Zero references to Hermes MCP tools in any active agent runtime config after X3.
-4. The X-R6 calendar fixture (DST-crossing recurrence, moved + cancelled occurrence, all-day event) round-trips with zero duplicates.
-5. The X-R7 retrieval eval passes against M1 before any memory store goes read-only; negative queries return no superseded/rejected content.
-6. All four machine gates above have their artifacts on record before their respective transitions execute.
-
-## Sequencing note
-
-X depends on the longest chains (K1→K2, P2, Q1, J2a→J2b, **M1** — X2 cannot complete class (b) without the memory subsystem existing). Dependencies are real DAG edges in `north-star-additions.yaml` (`X2 depends_on [J2a, P2, M1]`), not prose phases (debate P0 #3). Expected order of value delivery: J1–J4 (Jarvis on existing transport interim) → K1/J5 (Matrix room) → P2, W1–W3, Q1 in parallel → X1 checklist → X2 migration → K2 bridges → X3 decommission.
-
-- ASSUMPTION (interim transport): until K1 lands, Jarvis may run against the tmux connector (CLI/`agent send`) rather than standing up any Discord channel — keeps D1 (Matrix-first, no #jarvis Discord) intact.

docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md

@@ -1,89 +0,0 @@
-# PRD — HMI Main Agent ("Jarvis") · Workstream J
-
-> **Status:** DRAFT for ratification · **Source of truth once landed:** NORTH_STAR.yaml goals J1–J6
-> **Depends on upstream:** H2 (system-type profiles), A3a (card lifecycle), B1 (supervisor tick), F4/K1 (Matrix connector)
-> **Debate pass 2026-07-09:** panel findings folded — see `DEBATE-FINDINGS.md` for dispositions.
-
-## Mission
-
-Every Mosaic **workspace** gets exactly one always-on human-machine-interface agent — default alias **Jarvis**, unit `mosaic-agent@main.service` — that owns the human relationship: conversation, idea development, schedule, email, tasks, knowledge. It delegates all engineering/research/ops work to the orchestrator (**Mos**, `mosaic-agent@orchestrator.service`) through the Mosaic Backlog, and reports fleet status to the user without ever interrupting the orchestrator.
-
-Jarvis is a **Level-0 orchestrator**: it accomplishes its own work through _delegation and subagents_, never by executing coding/infra tasks itself. PA mutations (tasks/events/knowledge) are direct API calls; everything heavier is either a spawned subagent (research, drafting, analysis) or a backlog card handed to Mos (engineering/infra/fleet). This keeps the main agent's context conversational and light.
-
-This solves the observed failure mode: a busy orchestrator that can't respond, accumulates conversational context rot, and derails over time. Post-split, the orchestrator's context is execution-only.
-
-Because Jarvis and Mos are **separate agents with separate model capacity** (D11: Jarvis on Opus, Mos on Fable; independent inference quota), orchestrator load cannot degrade conversational latency — the isolation in AC-NS-8 is a capacity guarantee, not merely a separate process.
-
-## Requirements
-
-### Persona & runtime (J1)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| J-R1  | Jarvis is provisioned from the personal-assistant persona baseline via system-type profiles (H2/H3); alias, model tier, host, and channel are profile fields, not code.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| J-R2  | Default model tier **Opus** (ratified D11); the orchestrator's tier is independent. Always-_available_ ≠ always-_billed_: Opus is provisioned 24/7 but cost is per-interaction — an idle Jarvis (no user turn in flight) incurs no model spend, so "always-on" carries no standing token bill.                                                                                                                                                                                                                                                                                                           |
-| J-R3  | Jarvis survives reboot under systemd (`mosaic-agent@main`), participates in the fleet heartbeat protocol, and is counted in the supervisor's health floor.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| J-R4  | Persona customization is update-surviving per H4 (override layer wins on merge).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| J-R16 | **Workspace lease (exactly-one fencing):** Jarvis acquires `workspace_lease(workspace_id, epoch)` — a CAS row in product Postgres — before processing any turn. Every PA write, card, and approval carries the epoch; stale-epoch writes are rejected server-side; the connector re-checks the lease immediately before every outbound send. Takeover posts an in-room/in-channel epoch notice. Degraded mode (lease unobtainable) = **mute-with-notice**, never conversational-while-unfenced. Clean shutdown releases the lease. This primitive also excludes homelab/USC split-brain during adoption. |
-| J-R17 | Per-agent spend metering with a daily budget alarm for `mosaic-agent@main`; a main-agent crash-loop is a distinct, escalated supervisor condition (not a generic restart count).                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| J-R18 | **Resume protocol (promoted from open item):** resume context is reconstructed from authoritative queries (board, heartbeats, workspace entities), with narrative summary layered on top; a session-start divergence check flags contradictions between narrative and authoritative state. Jarvis is never re-instantiated from its own lossy summaries alone.                                                                                                                                                                                                                                           |
-
-### PA toolchain (J2a workspace-internal · J2b external)
-
-**Split (debate P0 #2):** phase-1 Jarvis operates only on workspace-internal entities — **no external-write credential path exists** until the permission relay (P2) is live. External integrations arrive in phase 2 as J2b, `depends_on: [J2a, P2]`. Test: in a phase-1 deployment, `email:send` is _impossible_ (no credential provisioned), not merely unapproved.
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                   |
-| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| J-R5  | (J2a) Jarvis executes personal-assistant mutations **directly** in the user's workspace via the product API: tasks, events/calendar, knowledge entries, ideas. No delegation for PA ops (ratified D4).                                                                                                                                                                                        |
-| J-R6  | (J2b) External PA integrations (email, external calendars, helpdesk) are workspace-scoped integrations; **raw credentials are held exclusively by the gateway** — Jarvis receives scoped capability tokens, never provider secrets; actions flagged `requires_approval` route through the permission relay (workstream P).                                                                    |
-| J-R7  | Until tenant-1 migration (X2) completes, Jarvis may read/write the jarvis-brain flat files as a transitional adapter; the adapter is deleted after the **last verified X-R6 re-point** (not at a nominal "X2 cutover" date). A per-phase, per-entity-type source-of-truth table in the J1 profile states which store is authoritative at every moment.                                        |
-| J-R19 | **Write-side trust rule:** externally-sourced content (email bodies, bridged messages, webhook payloads) written into workspace entities or memory inherits `source_trust=external` **transitively through summarization**. Standing-instruction-shaped external content requires explicit user ratification before it becomes retrievable. This closes the injection→durable-memory channel. |
-
-### Delegation contract (J3)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                   |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| J-R8  | The Jarvis→Mos handoff is **only** via Mosaic Backlog cards: goal, acceptance criteria, priority, depends_on, advisory budget. Never via chat messages to the orchestrator.                                                                                                                                                                                                                                   |
-| J-R9  | Jarvis translates conversation outcomes into card sets; ambiguity is resolved with the user _before_ card creation — the orchestrator receives only decision-complete work.                                                                                                                                                                                                                                   |
-| J-R10 | Card authorship is attributed (author=main-agent, ratified-by=user where applicable) for audit.                                                                                                                                                                                                                                                                                                               |
-| J-R11 | Authority line: Mos holds all execution and merge authority (NS-4). Jarvis relays the user's GO/NO-GO gates as card state, and never acquires fleet mutation, merge, or dispatch rights. `ratified_by=user` authorizes **dispatch only** — it never substitutes for the reviewer-of-record merge gate.                                                                                                        |
-| J-R20 | Card sets are drafted then **published atomically** with client idempotency keys (no partial card sets on crash). Card spec is **immutable after publish**; changes arrive as typed, ordered amendments with a revision counter; reviewer sign-offs pin the spec revision; scope-expanding amendments re-enter ratification.                                                                                  |
-| J-R21 | **`needs-decision` lifecycle:** a worker hitting genuine ambiguity sets `needs-decision(question, options)` on the card **with a durable checkpoint** (pushed branch + card note) — resume after days is a re-dispatch, not a context continuation. Jarvis relays the question to the user and writes the answer back as an amendment. This is the sanctioned clarification path; J-R8's no-chat rule stands. |
-| J-R22 | Jarvis-authored cards draw from a **priority budget** (quota per priority class per window) — priority inflation by the card author degrades the field for the whole fleet and is structurally capped, not policed by review.                                                                                                                                                                                 |
-
-### Passive observability (J4)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| J-R12 | Jarvis answers "what's the fleet doing" from read-only sources: heartbeat files, `mosaic fleet ps` JSON, backlog card states, CI status. Zero messages to the orchestrator for status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| J-R13 | Jarvis proactively surfaces to the user: blocked cards, failed CI on user-ratified missions, approval requests pending, budget advisories. (PDA-friendly phrasing per SOUL.md.) Delivered via the **J6 event/wake router** — per-agent polling is forbidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| J-R23 | **Event/wake router (J6):** one shared, level-triggered reconciler over durable state (heartbeats, card states, approval queue) wakes Jarvis on state _change_ with hysteretic per-condition suppression (wake once, then only on change or declared backoff; suppression survives restarts). Wake turns are **templated** — fixed instruction frame, workspace data only in delimited, provenance-tagged data fields (closes the injection→system-role channel). Idempotent on source event id via the shared consumed-events table. Router is in the health floor; its cost model and latency bound are stated in the J6 card. Reconciles J-R2: an idle Jarvis costs nothing _because waking is event-driven, not poll-driven_. |
-
-### Channel (J5)
-
-| ID     | Requirement                                                                                                                                                                                                                                                                                                                                                                             |
-| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| J-R14  | **Phase 2 (target channel):** Jarvis's conversation lives in a dedicated Matrix room on the self-hosted homeserver via `OrchestratorConnector(matrix)` (K1 = f4 Phase 2). Matrix-first: no Discord channel is created for Jarvis (ratified D1).                                                                                                                                         |
-| J-R14a | **Phase 1 (interim channel, ratified):** Jarvis runs on the **tmux/CLI connector** — the f4 Phase-1 default connector. The operator launches the `mosaic-agent@main` tmux session and issues `/remote-control` to grant interactive access; this is the day-one conversation surface. No Discord, no Matrix dependency in Phase 1 (keeps D1 intact and unblocks J1–J4 before K1 lands). |
-| J-R15  | Multi-platform user reach arrives via mautrix bridges (K2); Jarvis's code path is Matrix-only (from Phase 2 onward).                                                                                                                                                                                                                                                                    |
-
-## Acceptance criteria
-
-1. AC-NS-8 **(made measurable)**: distinct credential/quota pools for Jarvis and Mos are pinned in the J1 profile; scripted suite of ≥30 interleaved turns under full orchestrator load; TTFT p95 ≤ 1.2× idle baseline with bootstrap CI; orchestrator receives zero conversational traffic.
-2. AC-NS-9: a conversationally-agreed mission round-trips (cards → drained → completed → reported by Jarvis) with no chat handoff.
-3. Kill the orchestrator mid-conversation: Jarvis conversation is unaffected; Jarvis reports the outage from heartbeat state. (Directly exercises the separate-capacity guarantee.)
-4. `!sys`-equivalent admin verbs work in Jarvis's active channel — the tmux/CLI session in Phase 1, the Matrix room in Phase 2 (status/logs/clear/restart of the main agent).
-5. **Phase-1 channel:** operator launches the `mosaic-agent@main` tmux session, issues `/remote-control`, and holds a full conversation with Jarvis over CLI with no Matrix/Discord dependency.
-6. **Fencing:** start a second `mosaic-agent@main` by hand — it fails to acquire the workspace lease, posts a notice, and stays mute; zero duplicate writes or cards reach the workspace (J-R16).
-7. **Phase-1 credential surface:** audit of a phase-1 install finds no external-provider credential readable by the Jarvis runtime (J2a/J2b split holds by construction).
-
-## Non-goals
-
-- Jarvis executing code/infra changes (that is Mos + fleet).
-- Horizontal sharding of the main agent (rejected in the Matrix charter: split-brain).
-- Per-workspace fleets (post-MVP per ASM-6).
-
-## Open items (for Mos's planner)
-
-- ~~Context hygiene / resume protocol~~ — promoted to J-R18 by the 2026-07-09 debate pass.
-- Reconcile the old `apps/api` matrix-bot-sdk workspace bridge with the F4 connector design (one Matrix stack, not two). NOTE (verified 2026-07-09): no matrix dependency remains in `apps/api` on `origin/main` — this item is likely already moot; confirm before K1 build.

docs/fleet/proposals/mosaic-platform-prd/PRD-permission-relay.md

@@ -1,98 +0,0 @@
-# PRD — Permission Relay · Workstream P
-
-> **Status:** DRAFT for ratification · **Goals:** P1–P3
-> **Debate pass 2026-07-09:** panel findings folded — see `DEBATE-FINDINGS.md`. The relay was the panel's densest target; the deltas below are normative.
-> **Design origin (historical):** `docs/3-architecture/guard-rails-capability-permissions.md` — the "prepare freely, execute with approval" snapshot. **Not present on `origin/main`** (survives only in the stale `/src/mosaic-stack` clone), so its essential model is folded into this PRD below; **this document is the authoritative, self-contained spec for P.**
-> **Replaces:** Hermes `permissions_list_open` / `permissions_respond` relay (Hermes exit prerequisite, NS-13)
-
-## Mission
-
-A human-in-the-loop approval mechanism for agent actions: any capability listed as `requires_approval` is prepared by the agent, queued, and executed only after an explicit human approve — from the Matrix room or the webUI. Today this exists only as a bare `applyGuardRails()` method; Hermes currently fills the gap and must be replaced before decommission.
-
-## Design model (folded in — the authoritative spec, since the origin snapshot is off-main)
-
-**Doctrine — "prepare freely, execute with approval":** an agent may plan, draft, and stage any action without friction; only the _committing_ step of a `requires_approval` capability blocks on a human decision.
-
-**Permission levels (least→most):** `read` → `organize` → `draft` → `execute` → `admin`. A capability grant names a level; `requires_approval` gates the transition into `execute`/`admin` for the capabilities a workspace marks sensitive.
-
-**Grant shape:** `resource:action` (e.g. `email:send`, `git:push_main`, `dns:update`), scoped per workspace and per agent-persona, stored as configuration (profile field) so a user tightens/loosens without a code change.
-
-## Requirements
-
-### Guard-rails engine (P1)
-
-| ID   | Requirement                                                                                                                                                                                  |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| P-R1 | Capabilities are `resource:action` grants (e.g. `email:send`, `git:push_main`, `dns:update`) with permission levels (read / organize / draft / execute / admin) per the existing design doc. |
-| P-R2 | Each integration declares its `requires_approval` list; grants are workspace-scoped and per-agent-persona.                                                                                   |
-| P-R3 | Enforcement sits in the gateway/API dispatch path — an agent cannot bypass it by construction; bypass attempts are audited and denied.                                                       |
-| P-R4 | Policy is configuration (profile field), honoring the configurability pillar: a user can tighten/loosen per capability without code change.                                                  |
-
-### Approval queue + chat approvals (P2)
-
-| ID   | Requirement                                                                                                                                                                                                                                  |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| P-R5 | A pending approval is a durable queue record: requesting agent, capability, human-readable intent summary, prepared payload reference, TTL.                                                                                                  |
-| P-R6 | Approve/deny from the Matrix room (message action or reply verb); the requesting agent is notified of the outcome and proceeds/aborts.                                                                                                       |
-| P-R7 | Timeout = deny (fail-closed), with **per-capability TTLs** and distinct terminal states: `denied` / `expired_seen` / `expired_unseen` — agents must not reason about an expiry as a human "no". Deny and timeout leave the system unchanged. |
-| P-R8 | Full audit trail: who approved what, when, from which surface (AC-NS-10).                                                                                                                                                                    |
-| P-R9 | The main agent (Jarvis) surfaces pending approvals conversationally (J-R13) but approval authority is the human's — Jarvis never auto-approves.                                                                                              |
-
-### webUI surface (P3)
-
-| ID    | Requirement                                                                                                                         |
-| ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| P-R10 | Pending-approval queue view in `apps/web` with one-click approve/deny, filterable per workspace/agent (depends W3 dashboard shell). |
-
-## Debate-accepted deltas (2026-07-09) — normative
-
-### State machine & delivery (extends P-R5–P-R7)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                       |
-| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| P-R11 | Approval lifecycle is a **CAS state machine on one durable row**: `pending → approved \| denied \| expired_seen \| expired_unseen`, all terminal. Concurrent surfaces (Matrix, webUI, CLI, TTL reaper) contend via compare-and-swap; exactly one wins.                                                                                                            |
-| P-R12 | The **prepared payload is persisted in the record at request time** — never a reference to requesting-agent process state (the agent may be dead when approval lands). Outcome delivery is **poll/ack**, not push-only; `approved_unexecuted > N min` raises an alarm.                                                                                            |
-| P-R13 | A **consumed-event dedupe table** (shared substrate with bridged-message and wake-turn dedupe — built once, three consumers) makes approval consumption idempotent under Matrix at-least-once replay. Dedupe retention is **checkpoint-coupled**: events older than the durable sync token are dropped before lookup, so pruning never reopens the replay window. |
-| P-R14 | Each capability declares `retry: safe \| at-most-once`; a prepare→execute **staleness bound** rejects execution of stale payloads. Re-surfacing an expired item **re-prepares** (new linked record with a rendered machine diff against the original) — never re-queues a stale payload.                                                                          |
-| P-R15 | **CLI approval surface** (`mosaic approvals list\|approve\|deny`) ships **with P2** as must-have — the newest infra (Matrix) is never the only approval path. Per-request delivered/seen tracking; TTL/2 escalation via a second path.                                                                                                                            |
-
-### Identity & policy (closes Codex #2/#7)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| P-R16 | **Principal resolution:** every inbound approve/deny maps to a product principal via immutable Matrix user ID + bridge provenance + workspace membership. Unlinked identities and bridged puppets without an account link converse read-only and **cannot approve, butt-in, or trigger external writes**. Fixtures: bridged puppet, renamed user, invited non-admin, removed-member-with-lagging-room-membership — all deny + audit with reason. |
-| P-R17 | **Policy snapshot:** every prepared action and card stores an immutable snapshot (profile id/version, grants evaluated). Execution **revalidates against current policy** or fails with explicit `policy_changed`. Profile changes are audited with schema validation + dry-run impact report. Delegated work (subagent, Jarvis-authored card) executes under the **intersection** of originator and executor grants.                            |
-
-### Credential boundary (makes P-R3 true)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| P-R18 | Raw provider credentials are held **exclusively by the gateway**; agents receive scoped capability tokens; the gateway injects secrets server-side. If the agent runtime can read the provider secret, P-R3 is decoration.                                                                                                                                                                                                                                                          |
-| P-R19 | P1 delivers a **fleet-host credential inventory**: every host-resident credential (SSH keys, kubeconfigs, tool tokens) classified `moved-behind-gateway` or `explicitly-exempt(reason, owner, expiry)`. Enforced by a **continuous scheduled scan** of agent-readable paths (alert on unclassified), registered in the health floor. The clean-host install AC passes with an **empty exemption list**. Break-glass is one standing exempt row (owner: operator; audited post-hoc). |
-
-### Gating defaults & load (closes default-open + human-overdraw)
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| P-R20 | **Default-closed inversion:** `execute`/`admin` capabilities on external integrations require approval **unless** workspace-allowlisted. Third state `unclassified`: a capability with no classification **rejects** at the gate. Classification happens at integration-version activation, scoped to the **capability, not the version** — a security patch bundling one new capability ships same-day; only the new capability rejects until classified. Manifest-less capabilities reject + integrity alert. |
-| P-R21 | Rate limits + `max_pending_per_agent_per_capability`; queue depth and human decision latency are exported metrics with thresholds (rubber-stamping guard). Capabilities carry a `deferrable` flag; a declared **away state** pauses deferrable TTLs, batches pings, and **suppresses preparation** of non-deferrable requests (suppressed list swept, priority-ordered and paginated, on return).                                                                                                               |
-| P-R22 | Approval summaries render **machine-extracted payload facts unconditionally** (recipient, amount, target host — no tunable similarity threshold); agent prose is secondary. **Canary approvals** are gateway-generated, short-circuited at the gateway (never executable), immediately disclosed after decision, timing seeded outside agent-readable stores; the gated criterion is machine-flag correctness — human catch rate is reported with binomial CI, non-blocking.                                    |
-| P-R23 | Every durable table introduced by P declares a **retention class**, linted in CI; pruning jobs are health-floor registered. Minimal mandatory audit envelope: `ts, workspace, actor, correlation_id, stack_version, schema_version` — payloads are typed free-form with pinned, checked-in queries (debate §3.2 disposition).                                                                                                                                                                                   |
-
-## Acceptance criteria
-
-1. AC-NS-10 end-to-end: a `requires_approval` action executes only post-approve; deny/timeout paths verified unchanged + audited.
-2. Approval round-trip from a phone Matrix client (Element) in under 3 taps — **and** the same round-trip via `mosaic approvals` CLI with the homeserver stopped.
-3. With Hermes stopped, permission flow fully served by Mosaic (feeds AC-NS-11).
-4. Crash-consistency: kill the gateway at each named barrier (`before_persist`, `after_approve_before_execute`, `after_execute_before_ack`); zero double-executions, zero lost approvals across the suite.
-5. All four principal-resolution fixtures (P-R16) deny + audit; policy-change race (P-R17) fails `policy_changed`, never executes under stale grants.
-
-## Non-goals
-
-- Automated quality gates (coordinator/CI approvals) — different system, already exists.
-- Fine-grained LLM output moderation — out of scope; this governs _actions_.
-
-## Assumptions
-
-- ASSUMPTION: the durable queue rides the native Postgres storage service (same substrate as the backlog), not a new datastore.
-- ASSUMPTION: routine delivery operations already hard-gated as no-confirmation (push/merge per Mosaic contract) are NOT routed through the relay — the relay is for `requires_approval` capabilities only, so it does not reintroduce routine confirmation prompts.

docs/fleet/proposals/mosaic-platform-prd/PRD-webui-fleet-control.md

@@ -1,64 +0,0 @@
-# PRD — webUI Fleet Control · Workstream W (realizes F6)
-
-> **Status:** DRAFT for ratification · **Goals:** W1–W3 · **Upstream anchor:** `PRD-fleet-suite.md` Phase F6 ("webUI hooks — stable JSON contract + terminate/attach(butt-in) surface")
-> Confirmed gap: zero xterm/pty/tmux code in `apps/web` on either the old snapshot or `origin/main`.
-> **Debate pass 2026-07-09:** panel findings folded — see `DEBATE-FINDINGS.md`.
-
-## Mission
-
-The user can pop in on **any** agentic tmux session from the web, and get a full top-down view of the system — fleet roster, health, work in flight, spend — without touching a terminal. This is the product surface for "user has ability to pop in on any agent session; full top-down view available."
-
-## Requirements
-
-### Attach service (W1)
-
-| ID   | Requirement                                                                                                                                                                                                            |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| W-R1 | A gateway service exposes per-agent session streams over WebSocket: **watch** (read-only pane view, cannot type) and **butt-in** (interactive takeover), mirroring the existing CLI verbs `mosaic agent watch/attach`. |
-| W-R2 | Authz is workspace-scoped through the product auth stack (BetterAuth/Authentik); watch and butt-in are separate grants; butt-in may be `requires_approval` per workspace policy (workstream P).                        |
-| W-R3 | Every attach (watch or butt-in) is audited: who, which agent, when, duration.                                                                                                                                          |
-| W-R4 | Butt-in visibly flags the session to the agent runtime and other viewers (no silent takeover).                                                                                                                         |
-| W-R5 | Contract is stable JSON + streaming frames per F6's "stable JSON contract" requirement, so TUI/CLI and webUI share it.                                                                                                 |
-
-### Web terminal (W2)
-
-| ID   | Requirement                                                                                                 |
-| ---- | ----------------------------------------------------------------------------------------------------------- |
-| W-R6 | xterm.js view in `apps/web` wired to W1: session list → click → live pane; toggle watch↔butt-in per grants. |
-| W-R7 | Reconnect-safe (network blips resume the stream), mobile-usable read-only view.                             |
-
-### Top-down dashboard (W3)
-
-| ID    | Requirement                                                                                                                                                              |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| W-R8  | Fleet dashboard: roster with per-agent state (systemd + tmux + heartbeat join, as `fleet ps` provides), current card/task, last activity, drift/boot-enable warnings.    |
-| W-R9  | Work-in-flight view: backlog cards by state with depends_on DAG rendering; advisory spend per card (NS-2/NS-5).                                                          |
-| W-R10 | Operator controls: PAUSE kill-switch (NS-8), per-agent terminate (killswitch service), queue pause/resume — each gated + audited; destructive controls confirm.          |
-| W-R11 | Existing widget framework (`AgentStatusWidget`, `OrchestratorEventsWidget`, SSE proxy routes) is the starting point, upgraded to the fleet contract rather than rebuilt. |
-
-## Debate-accepted deltas (2026-07-09) — normative
-
-| ID    | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| W-R12 | **Butt-in is an exclusive lease** with explicit, visible takeover: at most one interactive holder per session at any instant; a second client must take the lease and both parties see the transfer. Input frames are sequenced and deduped so a reconnect never double-sends; a heartbeat/idle timeout closes both the lease and its audit span — audit spans always terminate (extends W-R1/W-R3/W-R4).                                                                         |
-| W-R13 | **Structured control plane:** PAUSE, terminate, restart, approve/deny, and queue operations are typed API verbs with RBAC and audit — never bytes typed into a tmux pane. Raw terminal input via butt-in is **rescue-only** and a separately-grantable permission from the control verbs.                                                                                                                                                                                         |
-| W-R14 | **Break-glass doctrine (documented, not prevented):** SSH + `tmux attach` on the fleet host bypasses W1 and P **by design**; it is inventoried under P-R19, audited post-hoc from host logs, and never treated as a product path. PAUSE additionally has an **on-host file/CLI actuator** so a dead gateway can never lock the operator out of the control that fixes the gateway.                                                                                                |
-| W-R15 | W3 ships the **trial metric panels** as workspace-scoped product views over product storage: canary machine-flag correctness, approval decision latency, card priority distribution, wake→ack rate, agent-authored memory retrieval fraction, human interaction load, fixed-input probe stability. The X-R9 trial evidence pack cites these panels; until W3 exists, day-1 emission targets MALS (L1). Workspace isolation fixture: workspace-2 admin sees zero workspace-1 rows. |
-
-## Acceptance criteria
-
-1. From a browser (desktop + phone), the user watches a live coder-agent pane read-only, then butt-ins with the right grant, types a message, detaches; agent session continues; audit log shows both.
-2. Dashboard reflects an agent crash within one heartbeat interval; PAUSE flip halts dispatch within one tick (AC-NS-5) from the UI.
-3. A user without butt-in grant can watch but cannot type (enforced server-side).
-4. Two clients contend for butt-in: exactly one holds the lease at any instant, the takeover is visible to both, and after a forced reconnect the input stream shows zero duplicated or interleaved frames (W-R12).
-5. With the gateway stopped, the operator PAUSEs the fleet via the on-host actuator; the bypass appears in the post-hoc audit (W-R14).
-
-## Non-goals
-
-- Replacing tmux as the session substrate (tmux remains the transport; web is a view).
-- Cross-host federation of the dashboard (rides the existing federation workstream later, per upstream note "Phase 5 rides federation").
-
-## Assumptions
-
-- ASSUMPTION: pty bridging terminates at the gateway on the fleet host (web1), not in `apps/web`; Next.js only speaks WebSocket to the gateway.
-- ASSUMPTION: the jarvis-brain dashboard's node-pty/xterm work (`dashboard/server/terminal.ts`) serves as reference implementation only; code is not ported wholesale into the multi-tenant product without the authz layer above.

docs/fleet/proposals/mosaic-platform-prd/README.md

@@ -1,62 +0,0 @@
-# Mosaic Platform PRD — Jarvis HMI + Hermes Decommission (DRAFT for ratification)
-
-**Date:** 2026-07-09 · **Author:** proto-Jarvis session with Jason · **Status:** Decisions D1–D12 **ratified** (fixed inputs); implementing PRD structure **DRAFT** — refined 2026-07-09 post-review, then stress-tested by a 9-persona × 2-round debate panel the same day; all 24 panel findings dispositioned and folded (see `DEBATE-FINDINGS.md`; one item **OPEN — Jason**: gate superstructure, §3.1)
-**Target home:** `mosaicstack/stack` → `docs/fleet/` (NORTH_STAR.yaml additions + per-phase PRDs)
-
-> **For the homelab orchestrator:** D1–D12 below are settled constraints, not open questions — do not reopen them. What is under review is only the _implementation_ (workstreams, goals, sequencing) that realizes them.
-> **Execution:** hand to the **homelab orchestrator** as orchestrated missions once ratified (D12). Land in `docs/fleet/` from `origin/main` — the `/src/mosaic-stack` clone on web1 is 5 months stale and must not be the base. The USC/web1 environment is out of scope for the trial; its cutover (workstream X applied to web1's Hermes + mos-claude) is a post-trial phase.
-
-## Ratified decisions (Jason, 2026-07-09)
-
-| #   | Decision                                                                                                                                                                                                                                                                                                                                                        |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| D1  | Jarvis conversation channel is **Matrix-first** — no #jarvis Discord channel is ever created.                                                                                                                                                                                                                                                                   |
-| D2  | Mosaic absorbs **all four** Hermes functions before decommission: messaging bridge, Kanban/task board, permission relay, multi-platform reach.                                                                                                                                                                                                                  |
-| D3  | Task handoff: **native Mosaic Backlog is the record; Gitea/GitHub/local-kanban attach as bidirectional sync adapters** (upholds ASM-1).                                                                                                                                                                                                                         |
-| D4  | Jarvis executes **PA ops directly** (email, calendar, tasks, knowledge, tickets, research); all code/infra/fleet work is delegated to Mos via the backlog.                                                                                                                                                                                                      |
-| D5  | Mosaic Stack is a **product from day one** — multi-user, Authentik tenancy, per-workspace isolation.                                                                                                                                                                                                                                                            |
-| D6  | Multi-platform reach via **Matrix + mautrix bridges** (telegram/signal/whatsapp/slack/discord); agents only ever speak Matrix.                                                                                                                                                                                                                                  |
-| D7  | webUI builds on the existing `mosaicstack/stack` monorepo (`apps/web`), realizing the already-scoped F6 phase.                                                                                                                                                                                                                                                  |
-| D8  | **PRD first, then Mos runs it** as orchestrated missions.                                                                                                                                                                                                                                                                                                       |
-| D9  | jarvis-brain flat-file data **migrates into the product as tenant #1** (workspace = Jason); brain.py/flat files retire after cutover.                                                                                                                                                                                                                           |
-| D10 | PRD form: **extend NORTH_STAR.yaml + per-phase docs in docs/fleet/** (NS-1 compliant).                                                                                                                                                                                                                                                                          |
-| D11 | Jarvis runs **Opus**; Fable stays exclusive to Mos per the standing cost directive. Model tier is a persona/profile field.                                                                                                                                                                                                                                      |
-| D12 | **Trial in the homelab** (the proper mosaic-fleet deployment, built by the homelab agents from `origin/main`), NOT at USC. The USC/web1 environment runs the primitive-era implementation (`mos-claude.service`, Hermes, jarvis-brain boards) and adopts only after the homelab trial validates. Jason relays this PRD to the homelab agent for implementation. |
-
-## Artifacts in this draft
-
-| File                         | Content                                                                                                                                          |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `north-star-additions.yaml`  | Proposed NORTH_STAR.yaml merge: NS-10…NS-14, workstreams J/K/W/P/Q/X + **M** (memory subsystem) + **L** (logging/telemetry), goal cards with DAG |
-| `PRD-jarvis-main-agent.md`   | Workstream J — the HMI main agent                                                                                                                |
-| `PRD-permission-relay.md`    | Workstream P — human-in-the-loop approvals                                                                                                       |
-| `PRD-webui-fleet-control.md` | Workstream W — tmux pop-in + top-down view (realizes F6)                                                                                         |
-| `PRD-backlog-providers.md`   | Workstream Q — provider sync adapters                                                                                                            |
-| `PRD-hermes-decommission.md` | Workstream X — parity checklist, tenant-1 migration, cutover                                                                                     |
-| `DEBATE-FINDINGS.md`         | 2026-07-09 debate pass — all 24 findings dispositioned, open-disagreement judgment calls, process rules                                          |
-
-Workstreams **M** (M1 enhanced memory subsystem) and **L** (L1 restore MALS · L2 Mosaic-native log ingestion · L3 anonymous agentic telemetry, NS-14) carry no standalone PRD doc: M1's scope is defined by its consumers (X-R7 retrieval eval, J memory rules) and L's by the MALS lineage (`~/src/mals`, infrastructure #135); both live as goal cards in the YAML.
-
-Workstream K (Matrix connector + mautrix bridges) intentionally has no new PRD doc: it extends the existing `docs/fleet/f4-matrix-connector.md`; its deltas are captured as K-goals in the YAML additions and referenced from the J/P/X PRDs.
-
-## Relationship to existing upstream work
-
-- Fleet CLI, persona library, system-type profiles (H1–H4), supervisor/dispatch (B), native backlog (A): **already exist or in flight upstream — not re-specified here.**
-- `f4-matrix-connector.md`: K1 = its Phase 2 implementation (verified present on `origin/main`; Phase 1 already ships the **tmux-default connector** that serves the P1 CLI channel per J-R14a). K2 (mautrix bridges) is additive infra.
-- F6 (webUI hooks) in `PRD-fleet-suite.md`: realized by workstream W (verified present on `origin/main`).
-- `docs/3-architecture/guard-rails-capability-permissions.md`: original design snapshot for workstream P — **not present on `origin/main`** (lives only in the stale `/src/mosaic-stack` clone). Its essential model is therefore folded into `PRD-permission-relay.md`, which is now the **self-contained authoritative spec** for P; the old path is cited as historical origin only.
-
-## Gate Zero — pre-ratification checklist (debate P0 #3/#4, §3.7)
-
-Ratification does not proceed on presumption. Before D-level sign-off, run and record:
-
-1. **Upstream-artifact audit.** Every artifact this PRD load-bears on is verified `present @ <SHA>` on `origin/main` or marked **MISSING → goal card**. Presumed-missing rows already carded by this draft: **M1** (enhanced memory subsystem — nothing on main provides vector DB + memory service today), **J6** (event/wake router), **K3** (Matrix push pipeline + homeserver ops). If an audit finds one of these actually exists, retire the card and pin the SHA; if it finds _another_ gap, card it — no silent presumption in either direction.
-2. **Hermes traffic audit** (§3.7): per-platform bridge traffic + per-MCP-tool call counts over a trailing window. Platforms with live traffic become the must-have K2 subset gating X3; zero-traffic platforms become post-trial nice-to-haves. Feeds the X-R1 parity checklist and its low-n drill list.
-3. **Sandbox dispatch-test** of the DAG: load `north-star-additions.yaml` into a sandbox backlog and verify the dispatcher's actual claim order respects every `depends_on` edge (phases are documentation; edges are law).
-
-## Process rules adopted from the debate pass (normative for this PRD's execution)
-
-- **Conflict register:** a discovered contradiction between spec documents **blocks the affected requirement** (not the whole mission) until a register entry records the resolution. "Alert, don't auto-resolve" is promoted from data conflicts to spec conflicts. A CI lint greps for register references in amended docs.
-- **DoD line on every goal card:** each card states its definition-of-done additions — runbook updated, health-floor alert registered, AGENTS.md touched — so operational debt can't silently accrue card-by-card.
-- **Silent-roster rule:** in any panel/review round, a member's silence records their open findings as **open items, never consensus** (instance: Codex's unanswered principal-resolution and policy-evaluation-time findings were folded as P-R16/P-R17, explicitly not consensus-resolved).
-- **Immutable spec + typed amendments** (J-R20) applies to these PRD docs themselves post-ratification: changes arrive as amendments with a revision counter, and sign-offs pin the revision.

docs/fleet/proposals/mosaic-platform-prd/north-star-additions.yaml

@@ -1,279 +0,0 @@
-# Proposed additions to docs/fleet/NORTH_STAR.yaml — DRAFT (Jason ratification pending, 2026-07-09)
-#
-# Merge these entries into the existing NORTH_STAR.yaml sections, then regenerate
-# NORTH_STAR.md via renderNorthStarMarkdown (packages/mosaic/src/commands/fleet.ts).
-# Ids chosen to avoid collision with existing workstreams A–H and goals.
-
-standing_objectives:
-  - id: NS-10
-    text: >-
-      Every Mosaic workspace runs exactly one always-on HMI main agent (default
-      alias "Jarvis", unit mosaic-agent@main) that owns all human conversation
-      and user-level personal-assistant work (ideas, schedule, email, tasks,
-      knowledge) and delegates engineering/research/ops missions to the
-      orchestrator as Mosaic Backlog cards. It is a Level-0 orchestrator:
-      it accomplishes work through delegation and subagents, never by executing
-      coding/infra tasks itself, and it runs on model capacity separate from the
-      orchestrator so its conversational latency is isolated from fleet load. The
-      main agent never executes fleet work itself and never interrupts the
-      orchestrator for status. Exactly-one-per-workspace is enforced by a
-      workspace lease (J-R16), not by convention.
-  - id: NS-11
-    text: >-
-      Irreversible or externally-visible agent actions pass a human-in-the-loop
-      permission relay (approve/deny from chat or webUI) governed by
-      per-capability guard rails; prepare freely, execute with approval.
-  - id: NS-12
-    text: >-
-      The Mosaic Backlog remains the sole backlog of record; external providers
-      (Gitea, GitHub, local kanban, …) attach as bidirectional sync adapters,
-      never as the record.
-  - id: NS-13
-    text: >-
-      Hermes is fully decommissioned once Mosaic reaches verified parity on
-      transport (Matrix connector), task board (native backlog + webUI),
-      permission relay, and multi-platform reach (mautrix bridges).
-  - id: NS-14
-    text: >-
-      Mosaic Stack accepts inbound structured error/log reporting from every
-      agent and install (MALS-lineage logging service); agentic-efficiency
-      telemetry is optional, opt-in, and anonymous by construction — no IP or
-      PII is captured or derivable from the ingestion path.
-
-success_criteria:
-  - id: AC-NS-8
-    text: >-
-      A user converses with the main agent in its channel while the
-      orchestrator is under full load; because the main agent runs on separate
-      model capacity (distinct credential/quota pools pinned in the J1
-      profile), its response latency is unaffected and the orchestrator
-      receives zero conversational traffic. Measured, not vibes: scripted
-      suite, >=30 interleaved turns, TTFT p95 <= 1.2x idle baseline with
-      bootstrap CI.
-  - id: AC-NS-9
-    text: >-
-      A mission agreed in the main-agent conversation appears as a backlog card
-      set with acceptance criteria, is drained by the orchestrator without
-      chat-level handoff, and its completion is reported back to the user by the
-      main agent from board/heartbeat state alone.
-  - id: AC-NS-10
-    text: >-
-      An action listed as requires_approval executes only after an explicit
-      human approve from Matrix or webUI; deny and timeout paths leave the
-      system unchanged and audited.
-  - id: AC-NS-11
-    text: >-
-      With Hermes stopped, no fleet or main-agent capability regresses
-      (transport, board, approvals, multi-platform reach all served by Mosaic).
-
-workstreams:
-  - id: J
-    title: HMI main agent ("Jarvis") — persona, PA toolchain, delegation contract
-  - id: K
-    title: Connectors & multi-platform reach — F4 Matrix implementation + mautrix bridges
-  - id: W
-    title: webUI fleet control — tmux pop-in, top-down view (realizes F6)
-  - id: P
-    title: Permission relay — capability guard rails + human approval queue
-  - id: Q
-    title: Backlog provider sync adapters — Gitea/GitHub/local kanban
-  - id: X
-    title: Hermes decommission & tenant-1 migration
-  - id: M
-    title: Enhanced memory subsystem — vector DB + memory service + provenance/tombstones (Gate Zero MISSING artifact)
-  - id: L
-    title: Logging & telemetry — MALS-lineage inbound error reporting + optional anonymous efficiency telemetry
-
-goals:
-  # J — HMI main agent
-  - id: J1
-    title: Main-agent persona + profile — instantiate personal-assistant system type as mosaic-agent@main (alias Jarvis), model tier a profile field (Opus default)
-    phase: 1
-    priority: must-have
-    depends_on: [H2]
-  # J2 split (debate P0 #2): phase-1 Jarvis must not hold an external-write
-  # credential path before the permission relay (P2) exists — NS-11 by DAG.
-  - id: J2a
-    title: PA toolchain (workspace-internal) — tasks, events, knowledge, ideas executed directly against the product API in the user's workspace; no external credentials provisioned
-    phase: 1
-    priority: must-have
-    depends_on: [J1]
-  - id: J2b
-    title: PA toolchain (external integrations) — email, external calendars, helpdesk via workspace-scoped integrations; credentials gateway-held; requires_approval routes through the relay
-    phase: 2
-    priority: must-have
-    depends_on: [J2a, P2]
-  - id: J3
-    title: Delegation contract — main agent authors mission cards (goal, acceptance criteria, budget advisory) onto the backlog; orchestrator drains; no chat-level handoff
-    phase: 1
-    priority: must-have
-    depends_on: [J1, A3a]
-  - id: J4
-    title: Passive fleet observability — main agent answers status from heartbeats, fleet ps JSON, and board state; zero orchestrator interrupts
-    phase: 1
-    priority: must-have
-    depends_on: [J1, B1]
-  - id: J5
-    title: Main-agent Matrix room via OrchestratorConnector(matrix)
-    phase: 2
-    priority: must-have
-    depends_on: [J1, K1]
-  - id: J6
-    title: Shared event/wake router — level-triggered reconciler over durable state (heartbeats, cards, approvals) with hysteretic per-condition suppression; templated provenance-tagged wake turns; per-agent polling forbidden (Gate Zero MISSING artifact; J-R13 depends on it)
-    phase: 1
-    priority: must-have
-    depends_on: [J1]
-
-  # K — connectors & reach (extends f4-matrix-connector.md)
-  - id: K1
-    title: Matrix connector implementation — CS-API client factory per f4 Phase 2, self-hosted homeserver
-    phase: 2
-    priority: must-have
-    depends_on: []
-  # K2 scope (debate §3.7): a pre-ratification Hermes traffic audit narrows the
-  # must-have bridge subset to platforms with live traffic; only that subset
-  # gates X3 — remaining bridges are genuinely optional post-X3.
-  - id: K2
-    title: mautrix bridge deployment (telegram/signal/whatsapp/slack/discord) as GitOps-managed infra; agents speak only Matrix; must-have subset = platforms carrying live Hermes traffic per Gate Zero audit
-    phase: 3
-    priority: should-have
-    depends_on: [K1]
-  - id: K3
-    title: Push pipeline (Sygnal or equivalent) + homeserver ops — monitored delivery checks, health-floor registration, rehearsed backup/restore (Gate Zero MISSING artifact; P2 phone-approval AC depends on it)
-    phase: 2
-    priority: must-have
-    depends_on: [K1]
-
-  # W — webUI fleet control (realizes F6)
-  - id: W1
-    title: Gateway pty/tmux attach service — read-only watch and interactive butt-in verbs, workspace-scoped authz, audit log
-    phase: 2
-    priority: must-have
-    depends_on: []
-  - id: W2
-    title: xterm.js session view in apps/web wired to W1 (watch + butt-in)
-    phase: 2
-    priority: must-have
-    depends_on: [W1]
-  - id: W3
-    title: Top-down fleet dashboard — roster, heartbeats, cards in flight, advisory spend, PAUSE control
-    phase: 2
-    priority: must-have
-    depends_on: [B1]
-
-  # P — permission relay
-  - id: P1
-    title: Capability guard-rails engine — resource:action grants, permission levels, requires_approval list per integration
-    phase: 2
-    priority: must-have
-    depends_on: []
-  - id: P2
-    title: Approval queue + approve/deny from the Matrix room (timeout = deny; full audit)
-    phase: 2
-    priority: must-have
-    depends_on: [P1, K1]
-  - id: P3
-    title: Approval surface in webUI (pending queue, one-click approve/deny)
-    phase: 3
-    priority: should-have
-    depends_on: [P1, W3]
-
-  # Q — backlog provider sync adapters
-  - id: Q1
-    title: Provider adapter interface + Gitea adapter (bidirectional card↔issue sync; native backlog stays record)
-    phase: 2
-    priority: must-have
-    depends_on: [A2]
-  - id: Q2
-    title: GitHub adapter
-    phase: 3
-    priority: should-have
-    depends_on: [Q1]
-  - id: Q3
-    title: Local kanban surface — webUI board view over the native backlog (no external provider required)
-    phase: 2
-    priority: should-have
-    depends_on: [A2, W3]
-
-  # X — Hermes decommission & tenant-1 migration
-  - id: X1
-    title: Hermes parity checklist + cutover plan (transport, board, approvals, reach) with rollback
-    phase: 3
-    priority: must-have
-    depends_on: [K1, P2, Q1]
-    # jarvis-brain is the P0 (prototype) Mosaic Stack; migration targets the proper
-    # stack storage layer. Storage authority (debate P0 #1): Postgres is
-    # authoritative for ALL product entities; the flat-file backend is a derived,
-    # regenerated, READ-ONLY projection — never a second writable store.
-  - id: X2
-    title: 'Tenant-1 migration — P0 (jarvis-brain) into the proper Mosaic Stack: (a) PA data (projects/tasks/events/knowledge) into the Jason workspace, (b) agent memory/runbooks into the enhanced memory subsystem M1 (kept live, not frozen); jarvis-brain retires read-only only after both are verified'
-    phase: 3
-    priority: must-have
-    depends_on: [J2a, P2, M1]
-  - id: X3
-    title: Hermes decommission — stop and remove Hermes services after AC-NS-11 verified; pre-stop evidence snapshot (logs/config/callback inventory + checksum) is a machine gate
-    phase: 4
-    priority: must-have
-    depends_on: [X1, X2, K2]
-
-  # M — enhanced memory subsystem (Gate Zero: cited by X2(b) but not built by
-  # any prior workstream — this card closes that gap)
-  - id: M1
-    title: Enhanced memory subsystem — vector DB + memory service with mandatory provenance (human/agent/external), source-grounded retrieval preference, tombstones + re-embedding on source update, normative/parametric corpus split
-    phase: 2
-    priority: must-have
-    depends_on: []
-
-  # L — logging & telemetry (Jason 2026-07-09; NS-14). MALS (~/src/mals) is the
-  # P0 of this capability; restoring it is infra work tracked as
-  # infrastructure#135 (k3s migration landed without an Ingress).
-  - id: L1
-    title: MALS restored & exposed — k3s Ingress for mals.mosaicstack.dev, health verified, authenticated write smoke-tested (infrastructure#135); trial day-1 metric emission targets MALS until W3 panels exist
-    phase: 1
-    priority: must-have
-    depends_on: []
-  - id: L2
-    title: Mosaic-native log ingestion — gateway/API endpoint for structured inbound error reporting from agents and installs (MALS-compatible schema; levels, categories, trace ids), workspace-scoped keys
-    phase: 2
-    priority: must-have
-    depends_on: [L1]
-  - id: L3
-    title: Anonymous agentic-efficiency telemetry — opt-in, aggregate-only, no IP/PII captured or derivable at ingestion (NS-14); feeds W3 trend panels
-    phase: 3
-    priority: should-have
-    depends_on: [L2, W3]
-
-assumptions:
-  - id: ASM-5
-    vetoable: true
-    text: >-
-      The main agent initially runs on the homelab fleet host alongside the
-      orchestrator under mosaic-agent@main.service; host placement is a config
-      field, not a code assumption. Host co-location does NOT imply shared
-      inference: Jarvis (Opus) and Mos (Fable) hold separate model capacity/quota
-      so orchestrator load cannot degrade conversational latency (AC-NS-8).
-  - id: ASM-6
-    vetoable: true
-    text: >-
-      Product multi-tenancy at MVP means self-hosted installs with multiple
-      workspaces per install (Authentik OIDC); per-tenant isolated FLEETS
-      (agents per workspace) are post-MVP.
-  - id: ASM-7
-    vetoable: true
-    text: >-
-      mautrix bridges are deployed as infrastructure (GitOps), not as Mosaic
-      application code; Mosaic's only conversational protocol is Matrix.
-  - id: ASM-8
-    vetoable: true
-    text: >-
-      During migration (before X3), Hermes remains running untouched; no
-      Hermes-dependent capability is removed until its Mosaic replacement is
-      verified in production.
-  - id: ASM-9
-    vetoable: true
-    text: >-
-      The trial environment is the homelab fleet deployment (D12). Environments
-      running the primitive-era implementation (USC/web1: mos-claude.service,
-      Hermes, jarvis-brain boards) are untouched during the trial; workstream X
-      executes there as a post-trial adoption phase, environment by
-      environment.

docs/guides/admin-guide.md

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

docs/scratchpads/703-wrapper-interactive-auth.md

@@ -0,0 +1,49 @@
+# #703 Git Wrapper Interactive and Auth Resilience
+
+## Objective
+
+Restore the deployed Git wrapper contract: issue-create supports interactive invocation and Gitea mutation behavior tolerates a stale Tea authenticated user by validating current identity and using the existing host-scoped API fallback.
+
+## Scope
+
+- `packages/mosaic/framework/tools/git/issue-create.sh`
+- `packages/mosaic/framework/tools/git/detect-platform.sh`
+- Git wrapper regression harnesses
+- This scratchpad
+
+## Requirements / acceptance evidence
+
+1. `issue-create -i` and `--interactive` prompt for missing issue fields without exposing credentials.
+2. Explicit command-line fields retain precedence and do not trigger prompt input.
+3. Gitea wrapper resolves the current user dynamically from the target host and does not rely on the saved Tea user identity.
+4. A Tea `GetUserByName` failure falls back to authenticated API creation.
+5. Existing body-safety, login-resolution, issue-create, and pr-create paths remain green.
+6. Source framework is re-seeded to deployed `~/.config/mosaic`, then deployed wrappers are verified end to end.
+
+## Plan
+
+1. Add failing shell regression harness for interactive input and stale Tea user fallback.
+2. Implement minimal helper and parser changes.
+3. Run wrapper harnesses, syntax checks, and repository baseline checks.
+4. Re-seed deployed framework and run live wrapper verification.
+5. Commit, queue guard, push, open PR, and stop for independent review.
+
+## Progress
+
+- Issue #703 filed before code; issue comment records #536 root cause and stale-login trigger.
+- Deployed wrapper `issue-create.sh -i` reproduced: `Unknown option: -i` (exit 1).
+- Live Tea mutation did not reproduce `GetUserByName` on this host because the current mosaicstack Tea login is valid. The test harness models the reported stale authenticated-user condition.
+- Implemented `-i` / `--interactive` prompt collection and a dynamic Tea `/user` validation. A stale Tea identity now selects the existing host-scoped Gitea API fallback before mutation for both issue and PR creation.
+- Re-seeded the framework with `MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash packages/mosaic/framework/install.sh`. Installed and source wrapper SHA-256 values matched.
+- Live deployed verification: interactive issue-create opened then closed #704; installed dynamic identity resolved `jason.woltje`.
+
+## Verification
+
+- PASS: `packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh`
+- PASS: `packages/mosaic/framework/tools/git/test-issue-create-body-safety.sh`
+- PASS: `packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh`
+- PASS: `packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`
+- PASS: `packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
+- PASS: `bash packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh`
+- PASS: `bash -n packages/mosaic/framework/tools/git/*.sh`
+- PASS: Prettier check for this scratchpad

docs/scratchpads/tess-20260712.md

@@ -0,0 +1,66 @@
+# Scratchpad — Tess Interaction Agent
+
+## 2026-07-12 — Mission intake
+
+**Objective:** Build a Pi-native GPT-5.6 Sol high-reasoning Mosaic interaction agent, named Tess, as Jason's primary Discord/CLI access point for Mosaic fleet and transitional Hermes capabilities. Tess complements Mos and must not become a competing orchestrator.
+
+**Issue:** #706
+
+**Budget:** No explicit cap provided. Original working estimate was 290K implementation/review tokens. That estimate is superseded after six security prerequisite tasks were added; revised arithmetic total is pending because the calculation tool was blocked by runtime consent. Run at most two workers; prefer one implementation lane plus one independent review/discovery lane. Re-estimate after planning approval and each milestone.
+
+**Evidence gathered:**
+- Mosaic already provides Pi lifecycle hooks, fleet/tmux sessions, Matrix connector/controller pieces, typed chat events, Discord/Telegram channel plugins, and command/plugin registries.
+- Current `IProviderAdapter` is an LLM model/completion abstraction, not an external agent/session provider.
+- Required new seam is `AgentRuntimeProvider`: sessions, stream, message, terminate, hierarchy, attach, health, capabilities.
+- Recurring cross-runtime needs: unified memory/retrieval, Discord routing/approvals, agent state/inbox/compaction recovery, runtime bootstrap, fleet/incident controls, and GitOps workflow.
+- Project truth must remain in canonical project/Mosaic stores; semantic memory is retrieval/mirror.
+
+**Decisions:**
+1. Name: Tess (tessera). Stable machine key `tess`; display name configurable.
+2. Mos owns orchestration; Tess delegates Mos-owned work through an explicit coordination contract.
+3. Gateway owns ingress/auth/routing; Discord and CLI remain thin clients.
+4. tmux/fleet ships first behind an adapter; Matrix/native Mosaic is the forward transport.
+5. Hermes integration is transitional and capability-negotiated; unsupported operations fail closed.
+6. No unrestricted Discord shell. Privileged/destructive/customer-visible actions require authorization and approval.
+
+**Plan:**
+1. Land requirements/architecture/task graph.
+2. Deliver runtime contracts and security model.
+3. Deliver durable Pi service/state.
+4. Deliver Discord and CLI.
+5. Deliver fleet/Mos/Hermes/memory/tool plugins.
+6. Deliver Matrix/native transport, migration matrix, recovery, docs, and qualification.
+
+**Progress:** Issue #706 created. PRD/manifest/tasks initialized on clean branch `feat/tess-interaction-agent` from `origin/main`.
+
+**Risks:** 14 GB root filesystem headroom; active fleet lanes; broad migration scope; Discord privilege boundary; possible duplicate orchestration authority.
+
+## 2026-07-12 — Independent planning and threat review
+
+**Verdict received:** BLOCK TESS-PLAN-001. Coding remains stopped.
+
+**Blocking findings:** formal threat model absent; verification matrix absent; migration inventory implied but absent; non-existent task paths; AC-TESS-03 lacked a crisp test. Security review also identified command scope bypass, cross-tenant session attachment, MCP actor impersonation, unsafe Discord service ingress, pre-persistence/egress secret leakage, non-durable replay, and globally scoped GC.
+
+**Remediation applied:**
+- Added `docs/tess/ARCHITECTURE.md`.
+- Added `docs/tess/THREAT-MODEL.md` with TM-01..12.
+- Added `docs/tess/VERIFICATION-MATRIX.md` mapping AC-TESS-01..11.
+- Added `docs/tess/MIGRATION-INVENTORY.md`.
+- Added hard requirements TESS-SEC-002..009.
+- Added six prerequisite security tasks before provider/ingress implementation.
+- Corrected task paths to existing package surfaces.
+- Added explicit GPT-5.6 Sol/high/tool-policy status verification for AC-TESS-03.
+
+**Re-review 1:** BLOCK only on composite `repo` values that looked like nonexistent paths. Remediated by declaring comma-separated roots and validating every root.
+
+**Final focused review:** PASS. Deterministic audit validated all task repository roots with zero missing paths; no planning placeholders remained; security prerequisites still gate Tess exposure; observability traceability is explicit.
+
+**Current gate:** planning PR must merge to `main` with terminal-green CI before any source-code worker starts.
+
+## 2026-07-13 — M3 cross-surface delivery
+
+**Branch:** `feat/tess-m3-integration` from `main` at `84d884b9`.
+
+**Delivered:** Stable Discord `conversationId` enrollment after a visible provider/runtime session is known; idempotent provider-session rebinding that preserves agent/tenant/owner scope; Discord approval/stop target resolution through the durable snapshot; SSE runtime streaming after CLI attach; denial/audit parity including provider authorization denials and HTTP 403 approval-denial mapping.
+
+**Evidence:** Gateway targeted suite: 37 tests passed; Mosaic CLI interaction test passed; agent durable-session test passed; gateway and CLI typechecks passed; changed-file format and whitespace checks passed. Codex security review found no confident vulnerability. Code review identified a Fastify exception-response mismatch and two UX/acknowledgement issues; all were corrected before the final validation run.

docs/scratchpads/tess-m1-002-provider-registry.md

@@ -0,0 +1,38 @@
+# TESS-M1-002 — Provider Registry
+
+- **Issue:** #707
+- **Branch:** `feat/tess-provider-registry`
+- **Objective:** Build the runtime provider registry/service boundary that derives immutable actor/tenant/channel/correlation scope server-side, fail-closes unsupported and destructive runtime operations, binds termination approval to the exact structured action, and emits correlation-safe audit events.
+
+## Plan
+
+1. Add a provider-agnostic registry in `@mosaicstack/agent` over the merged `AgentRuntimeProvider` contract.
+2. Write abuse-case tests before implementation for duplicate/unknown providers, immutable server-derived scope, capability denial, approval mismatch/absence, and audit failure.
+3. Implement the Gateway service that converts only authenticated `ActorTenantScope` plus trusted ingress metadata into a frozen `RuntimeScope`, gates capabilities and terminate approval, and records metadata-only audits.
+4. Register the service in `AgentModule`, then run focused, baseline, cold-cache, and independent-review gates.
+
+## Security Invariants
+
+- Caller-supplied actor/tenant identity never reaches runtime providers.
+- Provider capability absence and approval/audit failure deny before side effects.
+- Termination approval is verified against provider, session, actor, tenant, channel, and correlation context.
+- Audit events retain correlation and authority metadata but never message content or approval material.
+
+## Progress
+
+- 2026-07-12: Created fresh worktree from `origin/main` at `119f64e6`; source and Tess planning/security documentation reviewed.
+- 2026-07-12: Security TDD added registry and gateway abuse tests before implementation.
+- 2026-07-12: Implemented `AgentRuntimeProviderRegistry` and gateway `RuntimeProviderService`; registered both in `AgentModule` and documented the internal boundary.
+- 2026-07-12: Independent review found two audit correctness issues. Remediated completion-audit failure handling and provider execution failures: pre-invocation denials are audited as `denied`; post-invocation errors as `failed`; completion audit failure does not misreport a completed effect as retryable.
+- 2026-07-12: Final independent security review: no findings. Final code review had one false positive: `@mosaicstack/types` is already declared in `packages/agent/package.json`.
+
+## Tests
+
+- TDD red: `pnpm --filter @mosaicstack/gateway test -- runtime-provider-registry.service.test.ts` failed before both audit remediations, as expected.
+- Focused: package registry 2 tests and gateway security boundary 7 tests pass.
+- Cold-cache: removed this worktree's `node_modules`, then `pnpm install --offline --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store` passed.
+- Cold-cache baseline: `TURBO_FORCE=true pnpm typecheck` — 42/42 tasks passed; `TURBO_FORCE=true pnpm lint` — 23/23 tasks passed; `TURBO_FORCE=true pnpm format:check` passed; `TURBO_FORCE=true pnpm test` — 42/42 tasks passed (gateway 548 tests passed, 11 intentionally skipped).
+
+## Risks / Blockers
+
+- The canonical durable approval implementation is currently command-specific. This card introduces a fail-closed runtime approval verifier boundary so a runtime provider cannot terminate until its exact-action verifier is wired; later provider implementations cannot bypass it.

docs/scratchpads/tess-m1-003-fleet-provider.md

@@ -0,0 +1,75 @@
+# TESS-M1-003 — Fleet/tmux Runtime Provider
+
+- **Task:** `TESS-M1-003`
+- **Issue:** `#707`
+- **Branch:** `feat/tess-fleet-provider`
+- **PR target:** `main`
+- **Budget:** 30K estimate from `docs/tess/TASKS.md`; work remains scoped to `packages/mosaic`, `packages/agent`, and Tess architecture/scratchpad documentation.
+
+## Objective
+
+Implement `TESS-FLT-001` as a tmux/fleet `AgentRuntimeProvider` on the M1 registry contract. Operations must use roster-bound, exact tmux targets; fail closed on missing or mismatched peer identity; allow read-only attach only; use exact-target message delivery and termination; and expose no arbitrary shell, socket, or fuzzy session targeting.
+
+## Requirements and Security Invariants
+
+- `TESS-FLT-001`: fleet roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, controlled termination/recovery.
+- `TESS-ARP-001` / `TESS-TRN-001`: conform to the runtime provider contract and advertise only implemented capabilities.
+- TM-10: exact target/socket binding and peer identity verification; wrong socket, target, or identity must refuse delivery/attach.
+- Gateway supplies immutable actor/tenant/channel/correlation scope and consumes durable termination approvals before provider invocation.
+- `control` attach is denied. A provider attach is a scoped read-only logical handle; it never opens a server-side interactive terminal or exposes a raw tmux target.
+- M2 will make durable attachment/session state available. This M1 provider does not claim durable attachment handles or durable message idempotency.
+
+## Plan
+
+1. Add security TDD cases first for fuzzy/unrostered targets, incorrect socket/identity, control attach, attachment scope replay, and termination exact targeting.
+2. Add Mosaic fleet primitives for exact target validation and identity probing from the roster/socket.
+3. Implement and export the fleet/tmux provider in `@mosaicstack/agent`, using only those primitives and a command-runner seam.
+4. Update Tess architecture docs and this evidence log.
+5. Run focused tests, independent code/security reviews, cold-cache forced gates, then create a PR with `Refs #707`.
+
+## Branch/Base Note
+
+The orchestrator corrected the initial brief: `feat/tess-interaction-agent` is a stale planning branch. This branch was correctly created from `origin/main` at `e92186d7` (including M1-002) and will open a clean PR to `main` with `Refs #707`.
+
+## Progress
+
+- [x] Read PRD, Tess architecture, threat model, runtime contract, registry, fleet command primitives, task record, and issue #707.
+- [x] Created clean worktree from `origin/main` at `e92186d7`.
+- [x] Security TDD tests written before implementation; initially failed because the transport/provider modules did not exist.
+- [x] Fleet transport and capability-limited provider implemented; read/list/attach and direct Tess write/control default to deny pending scope-aware authority adapters.
+- [x] Focused typecheck, lint, formatting, and abuse tests passed (transport: 7; provider: 14).
+- [x] Cold-cache forced workspace gates passed after reinstall; final workspace gates also passed.
+- [x] Independent Codex code and security reviews passed with no findings.
+
+## Verification Evidence
+
+- `pnpm --filter @mosaicstack/mosaic typecheck` — pass.
+- `pnpm --filter @mosaicstack/agent typecheck` — pass.
+- `pnpm --filter @mosaicstack/mosaic lint` — pass.
+- `pnpm --filter @mosaicstack/agent lint` — pass.
+- `pnpm --filter @mosaicstack/mosaic test -- src/fleet/tmux-runtime-transport.test.ts` — 7 passed.
+- `pnpm --filter @mosaicstack/agent test -- src/tmux-fleet-runtime-provider.test.ts` — 14 passed.
+- The worktree dependency install must use `--store-dir /home/jarvis/.local/share/pnpm/store` because machine pnpm config points to an unreadable root-owned store. This is a local tool configuration issue, not an application workaround.
+
+## Documentation Checklist
+
+- [x] Canonical PRD and Tess architecture are current for this internal provider; no HTTP/API endpoint changed.
+- [x] `docs/tess/ARCHITECTURE.md` documents the internal fleet target/identity, read-only attach, and Mos authority boundary.
+- [x] No user/admin/API sitemap updates are applicable because no user-facing or HTTP API surface was introduced.
+
+## Acceptance Criteria to Evidence
+
+| Acceptance criterion | Evidence target |
+| --- | --- |
+| Only roster-bound exact targets are operated | Provider abuse tests prove unknown/prefix targets yield typed denial and runner is untouched. |
+| Socket and peer runtime identity are exact | Provider abuse tests prove wrong socket/no pane/runtime drift deny before send/attach/terminate. |
+| Message sends are capability-safe and exact | Tests assert the maintained sender receives only the configured socket and exact roster session. |
+| Fleet reads cannot cross an authority boundary | Tests prove list and read attach default-deny without a scope-aware read authority; per-target authority filtering is enforced. |
+| Attach cannot grant control or replay across scope | Tests deny `control`; attachment handles are random, scoped, short-lived, single-use for detach, and pruned after expiry. |
+| Termination is exact and caller cannot select arbitrary target | Tests assert roster/identity validation precedes exact `tmux kill-session -t =<agent>`. Gateway tests from M1-002 cover approval consumption. |
+| Documentation describes the boundary | `docs/tess/ARCHITECTURE.md` documents fleet capability, scope, and non-goals. |
+
+## Risks / Decisions
+
+- Runtime process identity can only be verified from the declared fleet roster and exact tmux pane command in M1. The tmux server itself is a trusted local transport boundary; stronger authenticated peer attestations are deferred to the Matrix/native provider.
+- The current roster schema does not encode per-agent tenant/owner. Scope-aware read/write authority adapters remain the integration point for gateway/Mos ownership policy; provider scope is bound to logical attachment handles to prevent replay.

docs/scratchpads/tess-m1-obs-001.md

@@ -0,0 +1,9 @@
+# TESS-M1-OBS-001 Scratchpad
+
+- Branch: `feat/tess-observability-terra` (the requested name is checked out by an abandoned worktree; orchestrator approved this clean branch).
+- Base: `origin/main` at `e92186d7`.
+- Scope: correlation propagation; metadata-only structured runtime/provider/tool audit; health/readiness; safe effective-policy status.
+- Security invariant: audit and status data use an allowlist; no message bodies, credentials, approval references, tool arguments, or tool output.
+- TDD: `packages/log/src/runtime-audit.test.ts` and `apps/gateway/src/health/health.controller.test.ts` failed before implementation and now pass.
+- Verification: full `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, and `pnpm test` passed after implementation (2026-07-12).
+- Review: corrected audit sanitizer findings by hashing every resource ID. Durable audit persistence remains fail-closed by design: the pre-existing M1 provider-boundary suite requires it to prevent an unaudited side effect.

docs/scratchpads/tess-m1-sec-001.md

@@ -0,0 +1,27 @@
+# TESS-M1-SEC-001 — Command authorization and exact-action approval
+
+- Issue/milestone: #707 / M1
+- Branch: `fix/tess-command-authz`
+- Requirement: `TESS-SEC-002`, with approval binding controls from `TESS-SEC-007`
+- Scope: `apps/gateway` only, plus required in-repo security/developer documentation.
+
+## Plan
+
+1. Locate the gateway command executor, command metadata, authorization context, and existing test conventions.
+2. Write abuse/authz tests before production changes. Expected red cases: non-admin blocked from admin/system command; forged caller scope cannot authorize; privileged/destructive action requires durable exact-action approval; expired/replayed/mutated approvals deny.
+3. Implement server-derived role/scope enforcement and durable approval validation/consumption with audit results.
+4. Run focused security tests, then repository baseline gates: typecheck, lint, format-check, test.
+5. Run independent security/code review, commit, queue-guard, push, and open the PR to `main` through the stated Gitea API fallback. Stop after PR creation.
+
+## Assumptions
+
+- The existing gateway persistence interface is the available durable approval boundary. If no persistence abstraction exists, a minimal injectable repository interface will be introduced rather than an in-memory approval implementation, because TESS-SEC-002/007 require durable enforcement.
+- “Exact action” is a canonical digest over structured command identity and normalized arguments; role/scope checks always use authenticated server context, not client-declared claims.
+
+## TDD evidence
+
+- Pending: abuse/authz test written and observed red before implementation.
+
+## Verification evidence
+
+- Pending.

docs/scratchpads/tess-m1-sec-004-discord-ingress.md

@@ -0,0 +1,35 @@
+# Scratchpad — TESS-M1-SEC-004 Discord ingress
+
+- **Task / issue:** TESS-M1-SEC-004 / #707
+- **Branch:** `fix/tess-discord-ingress` from `origin/main` at `59e49cfd`
+- **Objective:** Authenticate the Discord plugin service at gateway ingress; enforce explicit guild/channel/user allowlists; attach Discord message and generated correlation IDs; reject replayed native message IDs.
+- **Scope:** `plugins/discord`, `apps/gateway`, and existing Discord admin/developer protocol docs.
+- **Budget:** Task estimate 28K; no explicit hard cap supplied.
+- **Assumptions:** The Discord plugin and gateway share an injected high-entropy `DISCORD_SERVICE_TOKEN`; a configured Discord plugin fails closed without it. Allowlist configuration is comma-separated Discord snowflakes. Discord native message ID is the replay key, with bounded in-memory retention pending the M2 durable inbox/idempotency work.
+
+## Plan
+
+1. Add failing tests covering ingress service authentication/signing, unlisted guild/channel/user rejection, correlation propagation, and replay rejection.
+2. Implement the signed Discord ingress envelope and allowlist validation in the plugin.
+3. Authenticate and validate the envelope at the gateway boundary, then enforce bounded replay protection before agent dispatch.
+4. Document the service-token and allowlist operations; run focused and baseline gates; obtain independent review.
+
+## Progress
+
+- 2026-07-12: Intake complete; PRD TESS-SEC-005, architecture, and threat model reviewed.
+- Added service-token Socket.IO authentication, HMAC-signed Discord envelopes, default-deny guild/channel/user allowlists, correlated message metadata, bounded replay rejection, and fail-fast configuration checks.
+- Code and security reviews completed. Code review findings on service persistence ownership, package-boundary tests, disconnected ingress observability, and chat payload validation were remediated; final independent code review approved.
+
+## Risks / blockers
+
+- Existing `main` has known unrelated Prettier debt; only changed files will be held format-clean. Durable replay persistence is intentionally out of scope for this M1 prerequisite and belongs to TESS-M2 durable inbox/idempotency work.
+
+## Verification evidence
+
+- Focused ingress suite: `pnpm --filter @mosaicstack/gateway test -- discord-ingress.security.spec.ts` — 7 passed.
+- Gateway suite: `pnpm --filter @mosaicstack/gateway test` — 513 passed, 11 skipped.
+- Plugin suite: `pnpm --filter @mosaicstack/discord-plugin test` — no tests, passed by configured `--passWithNoTests`.
+- `pnpm typecheck` — passed.
+- `pnpm lint` — passed.
+- `pnpm format:check` — fails only on the known pre-existing Tess documentation debt listed in the task dispatch; changed files pass targeted Prettier verification.
+- Codex security review — no findings; final Codex code review — approved.

docs/scratchpads/tess-m1-sec-006-session-gc-scope.md

@@ -0,0 +1,22 @@
+# Scratchpad — TESS-M1-SEC-006 Session GC scope
+
+- **Task / issue:** TESS-M1-SEC-006 / #707
+- **Branch:** `fix/tess-session-gc-scope` from `origin/main` at `59e49cfd`
+- **Objective:** Make session cleanup session-scoped and prevent automatic global retention/GC without an authorized, auditable operation.
+- **Scope:** `apps/gateway`, `packages/log`, admin/developer operations documentation.
+- **Budget:** Task estimate 18K; no explicit hard cap supplied.
+- **Assumption:** No authorized global retention service exists today. Existing full/sweep GC must therefore be disabled from startup and cron paths, while single-session cleanup remains available.
+
+## Plan
+
+1. Add failing isolation tests proving single-session cleanup only demotes its own logs and automatic startup/scheduled GC cannot globally delete session data.
+2. Add session-scoped log repository retention and make `collect(sessionId)` use it.
+3. Remove automatic full/sweep GC invocation; preserve any future global operation behind an explicit authorization/audit seam.
+4. Document the operational boundary, run gates, review, and commit without push.
+
+## Verification evidence
+
+- Isolation TDD: `pnpm --filter @mosaicstack/gateway test -- session-gc.service.spec.ts commands.integration.spec.ts command-executor-p8012.spec.ts` — 61 passed.
+- `pnpm typecheck` — passed.
+- `pnpm lint` — passed.
+- `pnpm format:check` remains red only on the known pre-existing Tess documentation debt; changed files are Prettier-clean.

docs/scratchpads/tess-m2-001-pi-service.md

@@ -0,0 +1,40 @@
+# TESS-M2-001 — Pi Interaction Service
+
+## Scope
+
+- Add a generic rostered/systemd Pi operator-interaction service in
+  `packages/mosaic/framework`.
+- Pin the service to `openai/gpt-5.6-sol`, high reasoning, and the
+  `operator-interaction` tool policy.
+- Keep identity as provisioning data; the product name appears only in the
+  committed example roster.
+
+## Security and Configuration Invariants
+
+1. The chosen display/roster name is supplied as data and must exactly match the
+   generic systemd instance.
+2. The service fails before launch if runtime, model, reasoning, or tool policy
+   differs from the pinned policy.
+3. Effective-policy output includes only name, runtime, model, reasoning, and
+   tool policy; it does not inspect or output credential variables.
+4. The default example is replaceable without a source change; the TDD suite
+   provisions `Nova` from the same profile.
+
+## Evidence
+
+- `src/fleet/tess-service-profile.test.ts` proves a `Nova` provisioning path,
+  roster parser/env serialization, effective-policy output, fail-fast drift
+  rejection, and absence of the product name from generic source/profile.
+- `test-fleet-units.sh` validates the generic interaction systemd unit requires
+  per-agent config and invokes fail-fast startup validation.
+- `test-start-agent-session.sh` proves the tool-policy value is exported into
+  the Pi pane; `compose-contract.spec.ts` proves it becomes an explicit
+  runtime contract block.
+- Fresh-worktree dependency install plus root `pnpm typecheck`, `pnpm lint`,
+  `pnpm format:check`, and `pnpm test` passed; package/full fleet suites passed.
+- Independent Codex code and security reviews passed with no remaining findings.
+
+## Delivery Notes
+
+- Branch starts from fresh `origin/main` at `86a50138`.
+- PR targets `main` and references issue `#708`.

docs/scratchpads/tess-m2-002-durable-state.md

@@ -0,0 +1,63 @@
+# TESS-M2-002 — Durable Tess State
+
+- **Issue:** #708
+- **Task:** `TESS-M2-002` / `TESS-STA-001`, `TESS-SEC-007..008`
+- **Branch:** `feat/tess-durable-state`
+- **Base:** fresh `origin/main` at `e3b5113be21e51d015fa1ae54572929b2a4acd9f`
+- **Budget assumption:** 38K task estimate; no explicit cap. Use focused TDD plus workspace validation.
+
+## Objective
+
+Persist a Tess session's immutable identity, inbox/outbox idempotency state, checkpoints,
+handoffs, and approval bindings so a new service instance can recover it after a process
+restart or context compaction without replaying a completed message or applied side effect.
+
+## Plan
+
+1. Write recovery/idempotency tests first in `packages/agent/src/tess-durable-session.test.ts`.
+2. Add transport-neutral durable-state contracts/state machine in `packages/agent`.
+3. Add canonical PostgreSQL schema/migration and a gateway Drizzle repository adapter.
+4. Wire gateway service/module and reuse `tess:command-approval:*` durable approval semantics
+   for exact, actor/tenant/action-bound approval consumption.
+5. Test PGlite restart recovery with separate service instances sharing the same durable DB.
+6. Document the recovery/compaction operation and update Tess architecture evidence.
+7. Run focused, cold-cache, workspace, migration, review, commit, push, and open PR to `main`.
+
+## Required Evidence
+
+| Requirement | Primary evidence |
+| --- | --- |
+| Restart recovery | Test creates a second coordinator over unchanged durable store after simulated process death. |
+| No duplicate side effects | Duplicate ingress and post-restart dispatch assert one handler/effect invocation. |
+| Compaction survival | Checkpoint/handoff/reconstructed state preserve the same session identity and pending records. |
+| Durable approvals | Existing `tess:command-approval` record is consumed only once and survives a new authorization service instance. |
+| Handoff | Stored handoff is portable and reconstructed without live process state. |
+
+## Progress
+
+- Intake complete: PRD AC-TESS-06, threat TM-07/TM-08, and verification matrix reviewed.
+- Affected surfaces: `packages/agent`, `apps/gateway`, `packages/db`; auth/authorization and DB migration tests required.
+- TDD is required (security authorization and critical state mutation).
+
+## Risks
+
+- An external provider action cannot be atomically committed with the database. The outbox
+  gives the receiver a stable idempotency key; generic recovery never replays an ambiguous
+  `processing` effect, and completed effects are never redispatched.
+- PostgreSQL is canonical; PGlite is the local/restart test implementation.
+
+## Verification
+
+- TDD red: `pnpm --filter @mosaicstack/agent test src/tess-durable-session.test.ts`
+  initially failed because the durable-state module did not exist.
+- Focused green: 7 agent state-machine tests; 6 PGlite repository tests (including
+  close/reopen recovery and encrypted-at-rest redaction); 5 durable-approval tests; DB migration tests.
+- Full cold-cache green: `pnpm turbo run typecheck lint test --force` completed
+  88 tasks with zero cache hits; `pnpm format:check` and `git diff --check` passed.
+- Fresh worktree dependency install passed with
+  `pnpm install --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store`.
+  The default pnpm store path was inaccessible to this harness, so the explicit
+  user-owned store path was required.
+- Codex review identified plaintext durable payload risk; resolved by AES-256-GCM sealing
+  after redaction, with an at-rest ciphertext assertion in the PGlite suite.
+- Pending final clean review, commit, and PR.

docs/tess/ARCHITECTURE.md

@@ -0,0 +1,108 @@
+# Tess Architecture
+
+## Purpose
+
+Tess is the Mosaic operator interaction plane. Mos remains the coding/general fleet orchestration authority. Tess receives authorized operator intent, presents fleet/session state, delegates Mos-owned work to Mos, and exposes native Mosaic plus transitional external-agent capabilities through normalized providers.
+
+## Component Boundaries
+
+```text
+Discord plugin ─┐
+                ├─ authenticated ingress envelope ─> Mosaic Gateway
+mosaic tess CLI ┘                                  │
+                                                   ├─ policy/approval/audit
+                                                   ├─ Tess durable session service (Pi GPT-5.6 Sol high)
+                                                   ├─ AgentRuntimeProvider registry
+                                                   │   ├─ native Pi provider
+                                                   │   ├─ fleet/tmux provider
+                                                   │   ├─ Hermes adapter
+                                                   │   └─ Matrix/native transport provider
+                                                   ├─ memory/state/inbox plugins
+                                                   └─ Mos coordination adapter ─> Mos / fleet queue
+```
+
+## Core Contract
+
+`AgentRuntimeProvider` is separate from the existing model-completion `IProviderAdapter`. It normalizes external and native agent runtimes without leaking provider-specific schemas.
+
+Required operations:
+
+- `capabilities()` and `health()`
+- `listSessions(scope)`
+- `getSessionTree(scope)`
+- `streamSession(sessionRef, cursor, scope)`
+- `sendMessage(sessionRef, message, idempotencyKey, scope)`
+- `attach(sessionRef, mode, scope)` / `detach()`
+- `terminate(sessionRef, approvalRef, scope)`
+
+Every call receives an immutable, server-derived actor/tenant/channel scope and correlation ID. Caller-supplied actor IDs are forbidden. Unsupported capabilities fail closed with typed errors.
+
+### M1 Registry Boundary
+
+`@mosaicstack/agent` owns the explicit `AgentRuntimeProviderRegistry`; duplicate provider IDs are rejected rather than replaced. Gateway owns `RuntimeProviderService`, which creates a frozen `RuntimeScope` from authenticated `ActorTenantScope` and trusted ingress channel/correlation metadata before every provider call. The service checks the declared provider capability before invoking a side effect and records metadata-only audit events (`providerId`, operation, outcome, actor/tenant/channel, correlation, and resource ID). It never records message bodies, idempotency keys, or approval references.
+
+Termination is fail-closed: a runtime approval verifier consumes a one-time, exact action binding for the provider, session, actor, tenant, channel, and correlation ID before `terminate` reaches a provider. The verifier reuses the Redis-backed `interaction:command-approval:*` store and its expiry/delete-on-consume semantics; it has no parallel approval store. This internal service introduces no HTTP endpoint; later Discord, CLI, MCP, and provider adapters consume the same gateway boundary.
+
+## Authority Model
+
+| Intent                                                                      | Owner                   | Tess behavior                                                          |
+| --------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------- |
+| Conversation, status, retrieval, safe diagnostics                           | Tess                    | Execute within policy                                                  |
+| Code/project decomposition, worker assignment, reviews, merge orchestration | Mos                     | Create a correlated handoff and observe result                         |
+| Destructive, privileged, external/customer-visible action                   | Human approval + policy | Propose, wait for durable one-time approval, then execute idempotently |
+| Provider-specific unsupported action                                        | None                    | Fail closed; never emulate silently                                    |
+
+## Session and State Model
+
+A Tess session has stable `sessionId`, `tenantId`, `ownerId`, provider/runtime identity, ingress bindings, cursor, checkpoint, inbox/outbox, and idempotency records. Discord and CLI bind to the same authorized session. Ownership is verified server-side on every list/read/attach/send/terminate operation.
+
+Valkey holds the existing short-lived, one-time command-approval records; PostgreSQL is canonical for durable session bindings, checkpoints, inbox/outbox, and idempotency. Pi session files are replay sources, not cross-agent truth.
+
+### M2 Durable Recovery
+
+`@mosaicstack/agent` owns a transport-neutral state machine and `apps/gateway` provides its
+PostgreSQL adapter. `interaction_sessions` holds immutable identity; inbox/outbox records use a
+per-session unique idempotency key and transition `pending → processing → processed|delivered`.
+Checkpoints are immutable history scoped by session and checkpoint ID: the latest checkpoint
+supports compaction recovery, while a handoff always resolves the exact checkpoint it references.
+Recovery requeues only interrupted inbox work; an ambiguous `processing` outbox record is preserved
+until separately authorized reconciliation can establish its external delivery state.
+
+Provider sends travel through the existing `RuntimeProviderService` with the persisted outbox
+idempotency key. A normal dispatch claims exactly one outbox record and verifies its stored
+correlation and channel against the server-derived request scope; it never requeues or drains
+another live record. Inbox/outbox payloads and checkpoint cursor/summary pass through the existing
+secret/PII redactor and AES-256-GCM sealing before persistence; decryption occurs only in the
+scoped gateway repository path, and runtime audit remains metadata-only.
+
+An external effect cannot share a database transaction. If a process dies after an effect begins
+but before its terminal outbox transition, automatic recovery does not replay that ambiguous claim.
+It remains `processing` until separately authorized reconciliation can establish delivery state;
+completed effects are never redispatched. Operators can therefore restart the gateway/Pi service,
+reconstruct the session, and resume pending inbox work without relying on process-local state.
+
+## Transport Strategy
+
+- **Initial:** fleet/tmux provider, including exact target, socket, identity, heartbeat, and safe attach semantics.
+- **Forward:** Matrix/native Mosaic provider using authenticated identity, idempotent transaction IDs, replay cursors, and the same contract suite.
+- Discord/CLI never call tmux or Matrix directly.
+
+### Fleet/tmux Provider Boundary
+
+`TmuxFleetRuntimeProvider` supports only rostered fleet peers. Its transport resolves the configured roster socket itself and verifies the exact `=<agent>:0.0` pane and declared runtime command before every attach, message, or termination operation. Prefixes, unrostered session IDs, unavailable sockets, dead panes, and runtime identity mismatches fail closed; callers cannot supply a socket or raw tmux target.
+
+The provider advertises list, tree, read-only attach, send, and terminate. List/tree/health and read attach all default-deny until a scope-aware read authority permits the operation and exact peer. Attach produces a short-lived handle bound to the immutable actor, tenant, channel, and correlation scope; it never opens a server-side terminal and rejects `control` mode. Fleet stream support is intentionally absent. Tess has no direct write/control authority: send and terminate default-deny until a Mos authority adapter explicitly allows the exact session and immutable scope. The gateway registry remains the audit boundary for every requested, denied, and successful provider operation, and still consumes the exact-action termination approval before the provider is invoked.
+
+## Plugin Families
+
+1. Channel: Discord now; other channels later.
+2. Runtime: Pi, fleet/tmux, Hermes, Matrix/native.
+3. Operator tools: fleet health, Mos handoff, GitOps wrappers, incident-safe diagnostics.
+4. Memory/state: search/recent/capture, durable inbox, checkpoint, handoff, compaction recovery.
+5. Migration: capability inventory, adapters, cutover, rollback, telemetry.
+
+## Deployment
+
+Tess runs as a rostered, systemd-supervised Pi agent using GPT-5.6 Sol and high reasoning. Secrets are supplied through approved runtime secret mechanisms. Startup fails when required model, gateway identity, Discord binding, or durable-state dependencies are missing. Health reports effective model/reasoning/tool policy without credential material.
+
+The interaction-service identity is provisioning data, not a source identifier: the roster and per-agent environment carry the chosen display/roster name into a generic systemd instance. The service rejects a name mismatch or any drift from its pinned Pi/GPT-5.6 Sol/high/operator-interaction effective policy before launch. Its policy printer exposes only those resolved safe fields.

docs/tess/MIGRATION-INVENTORY.md

@@ -0,0 +1,34 @@
+# Tess Capability Migration Inventory
+
+Status values: `native` · `adapt` · `defer` · `reject`. This is the initial inventory; M5 requires implementation and evidence fields to be completed before cutover.
+
+| Capability                               | Current source                           | Target                                     | Initial status | Cutover/rollback intent                                                 |
+| ---------------------------------------- | ---------------------------------------- | ------------------------------------------ | -------------- | ----------------------------------------------------------------------- |
+| Interactive agent chat/session streaming | Hermes/Pi/OpenClaw                       | Mosaic Tess session service                | native         | Dual-run per channel; revert binding to legacy gateway                  |
+| Discord dedicated-channel routing        | Hermes/Claude/OpenClaw plugins           | Mosaic Discord plugin + gateway            | native         | Per-channel binding switch; legacy bot disabled only after soak         |
+| CLI/TUI session interaction and attach   | Hermes/Pi/tmux                           | `mosaic tess` + AgentRuntimeProvider       | native         | Keep direct tmux attach as break-glass rollback                         |
+| Session list/tree/send/terminate         | Hermes/fleet                             | AgentRuntimeProvider                       | native         | Capability-negotiated adapter remains during migration                  |
+| Mos/fleet orchestration handoff          | tmux messaging/Mosaic fleet              | Mosaic coord/fleet provider                | native         | tmux handoff remains initial transport                                  |
+| Kanban/projects/tasks                    | Hermes Kanban                            | Mosaic queue/coord/project providers       | adapt          | Read projection first; mutating cutover after parity/audit              |
+| Skills catalog/load/manage               | Hermes skills/Pi skills                  | Mosaic skill registry/provider             | adapt          | Import metadata/provenance; preserve source skill until validated       |
+| Tools and MCP                            | Hermes/OpenClaw/MCP                      | Mosaic tool registry/MCP                   | adapt          | Default deny; migrate allowlisted tools one capability at a time        |
+| Cron/scheduled work                      | Hermes cron                              | Mosaic scheduler/queue                     | adapt          | Shadow schedules; prevent duplicate execution; rollback owner field     |
+| Memory search/recent/capture             | jarvis-brain/OpenViking/OpenBrain/Hermes | Mosaic memory provider                     | adapt          | Flat/project stores remain truth; semantic systems are mirrors          |
+| User/profile preferences                 | Hermes memory/user profile               | Mosaic user/memory domain                  | adapt          | Provenance + explicit conflict rules; exportable rollback snapshot      |
+| Agent state/inbox/handoff                | OpenClaw extensions/session files        | Mosaic durable state service               | native         | Read legacy handoff during coexistence; write Mosaic only after cutover |
+| Runtime contract/bootstrap               | Mosaic framework/Hermes/OpenClaw         | Mosaic compose/runtime provider            | native         | Legacy launchers remain until clean-host parity passes                  |
+| Repository/PR workflow                   | Mosaic wrappers/Hermes tools             | Mosaic operator plugin                     | native         | Wrapper-only; no raw-provider fallback                                  |
+| Incident-safe diagnostics                | Hermes skills/tools                      | Mosaic scoped operator plugin              | adapt          | Read-only first; privileged recovery requires approval                  |
+| Broad unrestricted shell from Discord    | Hermes/OpenClaw configurations           | None                                       | reject         | No cutover; replace with allowlisted typed operations                   |
+| Raw full transcript bulk migration       | Hermes/Claude/OpenClaw histories         | Indexed summaries/selective import         | reject         | Keep source archives subject to retention; no automatic copy            |
+| Voice/video interaction                  | Hermes optional tools                    | Future Mosaic channel plugins              | defer          | Not required for Tess operational release                               |
+| Matrix transport                         | Mosaic connector                         | AgentRuntimeProvider Matrix implementation | native         | Non-default until contract/reliability parity; tmux rollback            |
+
+## Cutover Gates
+
+1. Capability contract and security tests pass.
+2. Data mapping/provenance and retention are documented.
+3. Shadow or dual-run shows no unauthorized access, loss, or duplicate effects.
+4. Operator runbook and rollback are exercised.
+5. Channel/provider binding changes are reversible without schema rollback.
+6. Legacy capability is disabled only after a defined soak period and evidence review.

docs/tess/MISSION-MANIFEST.md

@@ -0,0 +1,46 @@
+# Mission Manifest — Tess Interaction Agent
+
+## Mission
+
+- **ID:** tess-20260712
+- **Issue:** #706
+- **Branch:** `feat/tess-interaction-agent`
+- **Phase:** Execution
+- **Current Milestone:** TESS-M1 — Runtime contracts and security foundation
+- **Progress:** 0 / 5 delivery milestones complete
+- **Status:** active
+- **Owner:** Mosaic orchestrator; Mos is coordinating fleet authority
+- **Source PRD:** `docs/PRD.md` — `TESS-*` requirements
+- **Scratchpad:** `docs/scratchpads/tess-20260712.md`
+
+## Mission Statement
+
+Ship Tess as Jason's durable Pi-native GPT-5.6 Sol high-reasoning interaction agent for Discord and CLI, with safe visibility/control of Mosaic fleet and transitional Hermes capabilities, while Mos remains the coding/general orchestration authority.
+
+## Invariants
+
+1. Mosaic is the enterprise AI hub; Hermes is a reference migration adapter.
+2. Gateway is the single API surface.
+3. Mos owns coding/general fleet orchestration; Tess owns human interaction, visibility, mediation, and migration access.
+4. Runtime, transport, channel, memory, and external-agent integrations are replaceable adapters.
+5. No source task completes before merged PR, terminal-green CI, independent review, and linked task/issue closure.
+
+## Milestones
+
+| ID      | Issue | Name                                                                | Status      | Exit gate                                                                                                         |
+| ------- | ----- | ------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| TESS-M1 | #707  | Runtime contracts and security foundation                           | ready       | AgentRuntimeProvider, normalized events/capabilities/errors, RBAC/audit contracts and contract tests merged       |
+| TESS-M2 | #708  | Durable Pi Tess service and state                                   | not-started | GPT-5.6 Sol high service starts, resumes, checkpoints, and passes restart/compaction tests                        |
+| TESS-M3 | #709  | Discord and CLI interaction surfaces                                | not-started | One durable session works through dedicated Discord binding and `mosaic tess`, including attach and approvals     |
+| TESS-M4 | #710  | Fleet, Mos, Hermes, memory, state, and tool plugins                 | not-started | Fleet/Mos boundary and transitional capability matrix demonstrated end-to-end                                     |
+| TESS-M5 | #711  | Matrix/native migration, recovery, documentation, and qualification | not-started | Transport parity, migration/rollback matrix, security review, docs, greenfield and deployment validation complete |
+
+## Success Criteria
+
+All `AC-TESS-*` criteria in `docs/PRD.md` are mapped to reproducible evidence. The final operational test must prove Discord + CLI session continuity, fleet/Mos coordination, authorized Hermes transition capabilities, denial/audit paths, restart recovery, and rollback.
+
+## Session History
+
+| Session | Date       | Runtime              | Outcome                                                                                                                                     |
+| ------- | ---------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| S1      | 2026-07-12 | Hermes / GPT-5.6 Sol | User commission captured; Mosaic/OpenViking/session/code archaeology completed; issue #706 created; PRD and task control plane initialized. |

docs/tess/TASKS.md

@@ -0,0 +1,36 @@
+# Tasks — Tess Interaction Agent
+
+> Mission: `tess-20260712` · Issue: #706 · PRD requirements: `TESS-*`
+> Orchestrator is sole writer. Workers must not modify this file.
+> `repo` contains one or more comma-separated repository-relative roots; every listed root must exist before dispatch.
+> **BASE CONVENTION (Mos-locked 2026-07-12):** EVERY M1 dispatch targets `base=main` and branches from fresh `origin/main`. Do NOT base on `feat/tess-interaction-agent` — that is the STALE planning branch (merged via #712); basing on it yields `mergeable=False` + intervening-commit noise (cf. #723/SEC-005 re-base). Every dispatch brief must state base=main + branch-from-origin/main.
+
+| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| TESS-PLAN-001 | done | Finalize PRD, architecture, authority boundary, threat model, migration inventory, and verification matrix | #706 | sonnet | docs, packages/types, apps/gateway | feat/tess-interaction-agent | — | 22K | Independent gate PASS after two remediation rounds; completion effective when planning PR merges |
+| TESS-M1-SEC-001 | done | Enforce command scopes/roles and durable exact-action approval for privileged/destructive commands | #707 | codex | apps/gateway | fix/tess-command-authz | TESS-PLAN-001 | 25K | TESS-SEC-002; diskhygiene-terra; PR #718 head e3d98d73 MERGED (ROR 16829) |
+| TESS-M1-SEC-002 | done | Enforce owner/tenant binding on session list/read/attach/send/terminate across REST and WS | #707 | codex | apps/gateway | fix/tess-session-ownership | TESS-PLAN-001 | 30K | TESS-SEC-003; coder0; PR #715 head 43ffbe7b MERGED (ROR 16808) |
+| TESS-M1-SEC-003 | done | Bind MCP actor/tenant to authenticated context and add per-tool scopes | #707 | codex | apps/gateway | fix/tess-mcp-identity | TESS-PLAN-001 | 22K | TESS-SEC-004; coder1; PR #717 head 9ab776f9 MERGED (ROR 16819) |
+| TESS-M1-SEC-004 | done | Add authenticated Discord service ingress, allowlists, correlation and replay protection | #707 | codex | plugins/discord, apps/gateway | fix/tess-discord-ingress | TESS-PLAN-001 | 28K | TESS-SEC-005; coder4; PR #716 head 55ae77b6 MERGED (ROR 16830) |
+| TESS-M1-SEC-005 | done | Redact/classify secret and PII before persistence/egress; harden provider login flow | #707 | codex | apps/gateway, packages/log | fix/tess-redaction | TESS-PLAN-001 | 28K | TESS-SEC-006; coder1 (Mos-routed from blocked wrapfix-terra); mis-based #723 CLOSED superseded. MERGED to main: PR #725 head 726f7ab7 (ROR 16880). Verified chat persistence + egress redaction hooks; canary tests split-secret/private-key/overflow/persistence classification; provider login no auth URL/raw token in chat output |
+| TESS-M1-SEC-006 | done | Scope session GC/retention or separate authorized global retention job | #707 | codex | apps/gateway, packages/log | fix/tess-session-gc-scope | TESS-PLAN-001 | 18K | TESS-SEC-009; coder4; PR #720 base=main. MERGED to main: head 37be090e (ROR 16861). Both blockers fixed: glob metachar sessionIds escaped+regression; durable approval survives GC pass (create→GC→key remains→authz succeeds); /gc disabled, per-session log demotion, no fullCollect/sweepOrphans entry, legacy repeatable GC schedule removed |
+| TESS-M1-001 | done | Define AgentRuntimeProvider, capabilities, session tree, normalized stream events/errors, attach semantics | #707 | codex | packages/types, packages/agent | feat/tess-runtime-contract | TESS-PLAN-001 | 25K | TESS-ARP-001, TESS-TRN-001; wrapfix-terra; PR #719 head 5c42e67f MERGED (ROR 16813) |
+| TESS-M1-002 | done | Implement provider registry/service with immutable actor scope, approval, audit and correlation boundaries | #707 | codex | apps/gateway, packages/agent | feat/tess-provider-registry | TESS-M1-001,TESS-M1-SEC-001,TESS-M1-SEC-002,TESS-M1-SEC-003 | 30K | TESS-SEC-001..004,007; coder0; PR #722 head c529022d MERGED (ROR 16849) |
+| TESS-M1-003 | done | Implement tmux/fleet runtime provider and safe attach/message/terminate capability policy | #707 | codex | packages/mosaic, packages/agent | feat/tess-fleet-provider | TESS-M1-002 | 30K | TESS-FLT-001; coder0; PR #724 base=main. MERGED to main: head 355d814f (ROR 16868). HARD BOUNDARY verified: writes/control default-deny before tmux probing unless write authority permits; final exact-target authz after roster/socket/runtime verification; exact target/prefix/runtime-drift tests; read-only attach with immutable scope handles; empty-msg/default-deny/unverified-target tests; no credential material |
+| TESS-M1-OBS-001 | done | Implement correlation propagation, structured runtime/provider/tool audit, health/readiness and safe effective-policy status | #707 | codex | apps/gateway, packages/agent, packages/log | feat/tess-observability-terra | TESS-M1-002 | 24K | TESS-OBS-001; SOLE owner=diskhygiene-terra. MERGED to main at REBASED head: PR #726 head 53f5414 (re-ROR comment 16886, prior 16881@adfa5c06 discarded after head move), CI 1723 green. Both @mosaicstack/log barrel exports coexist (redaction + runtime-audit), metadata-only/SHA-256 audit intact, fail-closed audit-before-side-effects intact, safe status/effective-policy/readiness |
+| TESS-M1-V | done | Independent architecture/security review and complete contract/abuse-suite verification | #707 | mos-reviewer | apps/gateway, packages/agent, packages/log, plugins/discord | review/tess-m1 | TESS-M1-SEC-001,TESS-M1-SEC-002,TESS-M1-SEC-003,TESS-M1-SEC-004,TESS-M1-SEC-005,TESS-M1-SEC-006,TESS-M1-003,TESS-M1-OBS-001 | 20K | Gate M2 = PASS (Mos-owned independent non-author reviewer, 2026-07-12): all 5 priority seams verified live, 60+ tests green. M2 (#708) OPEN. Orchestrator did NOT run a competing lane (prior reviewer-lane dispatch recalled). Non-gating follow-up from this review captured as TESS-M1-FUP-001 (execute() authz-error mis-classification), scheduled to land before/with TESS-M3-001 — not now |
+| TESS-M1-FUP-001 | not-started | RuntimeProviderService.execute() records provider-thrown authorization errors as failed/provider_error instead of denied/policy_denied | #707 | — | apps/gateway, packages/agent | — | — | 6K | NON-GATING follow-up from M1-V review (2026-07-12). Provider-thrown authz errors (e.g. FleetRuntimeProviderError 'forbidden' from M1-003 write-authority) mis-classify as outcome:'failed'/'provider_error' rather than 'denied'/'policy_denied'. Low-priority. Land BEFORE/WITH TESS-M3-001 fleet-provider registry wiring (#709), NOT now |
+| TESS-M2-001 | in-progress | Add Tess roster/profile/service pinned to GPT-5.6 Sol high with fail-fast config and observable effective policy | #708 | coder0 | packages/mosaic | feat/tess-pi-service | TESS-M1-V | 22K | TESS-PI-001; explicit AC-TESS-03 test. Mos-dispatched DIRECTLY to coder0 (2026-07-12) — orchestrator tracks, does NOT dispatch a competing lane. Branch feat/tess-pi-service from fresh origin/main 86a50138; first TDD packages/mosaic/src/fleet/tess-service-profile.test.ts. NAME-AS-CONFIG INVARIANT (MISSION-MANIFEST #6, b01fdf11): agent name = config parameter (default example only), NO hardcoded key/identifier/default; profile carries name as DATA; M2 exit gate must prove a DISTINCT name provisions cleanly with ZERO code change (coder0 enforcing via a 'Nova' provisioning case). base=main, PR-open-STOP, independent non-author ROR then Mos merges. |
+| TESS-M2-002 | not-started | Implement durable session identity, inbox/outbox, approval, checkpoint, handoff, compaction and restart recovery | #708 | codex | apps/gateway, packages/agent, packages/db | feat/tess-durable-state | TESS-M2-001 | 38K | TESS-STA-001, TESS-SEC-007..008; recovery TDD |
+| TESS-M2-V | not-started | Clean-host Pi launch plus model/policy status and restart/compaction/duplicate-side-effect verification | #708 | sonnet | apps/gateway/src/__tests__/integration, packages/mosaic/src | review/tess-m2 | TESS-M2-002 | 18K | Gate M3; AC-TESS-03/06 |
+| TESS-M3-001 | not-started | Bind dedicated Tess Discord channel with streaming, threads, attachments, pairing/RBAC and approvals | #709 | codex | plugins/discord, apps/gateway | feat/tess-discord | TESS-M2-V,TESS-M1-SEC-004 | 35K | TESS-DSC-001 |
+| TESS-M3-002 | not-started | Implement `mosaic tess` chat/status/sessions/tree/attach/send/stop/health/recover CLI | #709 | codex | packages/mosaic | feat/tess-cli | TESS-M2-V | 30K | TESS-CLI-001 |
+| TESS-M3-V | not-started | Discord+CLI same-session E2E, denial/approval tests, and operator-flow review | #709 | sonnet | apps/gateway/src/__tests__/integration, plugins/discord, packages/mosaic/src | review/tess-m3 | TESS-M3-001,TESS-M3-002 | 20K | Gate M4 |
+| TESS-M4-001 | not-started | Implement Mos coordination handoff/observe/result contract with authority-boundary tests | #710 | codex | packages/coord, apps/gateway | feat/tess-mos-coordination | TESS-M3-V | 25K | TESS-MOS-001 |
+| TESS-M4-002 | not-started | Implement transitional Hermes runtime/capability adapter | #710 | codex | packages/agent, apps/gateway | feat/tess-hermes-adapter | TESS-M3-V | 40K | TESS-HRM-001; no legacy schema in core contracts |
+| TESS-M4-003 | not-started | Implement memory/retrieval, state/inbox, runtime bootstrap, fleet diagnostics and GitOps plugin foundations | #710 | codex | packages/memory, packages/agent, packages/mosaic | feat/tess-operator-plugins | TESS-M3-V | 40K | TESS-MEM-001, TESS-PLG-001 |
+| TESS-M4-V | not-started | Cross-provider capability, privacy, authority and failure-path qualification | #710 | sonnet | apps/gateway/src/__tests__/integration, packages/agent | review/tess-m4 | TESS-M4-001,TESS-M4-002,TESS-M4-003 | 22K | Gate M5 |
+| TESS-M5-001 | not-started | Implement Matrix/native runtime provider behind common contracts and parity suite | #711 | codex | packages/mosaic, packages/agent | feat/tess-matrix-provider | TESS-M4-V | 30K | TESS-TRN-001 |
+| TESS-M5-002 | not-started | Complete migration inventory, cutover, rollback, retention and deprecation evidence | #711 | sonnet | docs/tess | feat/tess-migration-docs | TESS-M4-V | 18K | TESS-MIG-001 |
+| TESS-M5-003 | not-started | Complete OpenAPI, user/admin/developer/plugin/operations docs and checklist | #711 | codex | docs | feat/tess-docs | TESS-M5-001,TESS-M5-002 | 22K | Documentation hard gate |
+| TESS-M5-V | not-started | Full baseline, contract, integration, Discord/CLI E2E, security review, recovery drill and rollback qualification | #711 | sonnet | apps/gateway, packages/agent, plugins/discord, packages/mosaic | review/tess-final | TESS-M5-003 | 35K | Maps AC-TESS-01..11 to evidence |

docs/tess/THREAT-MODEL.md

@@ -0,0 +1,46 @@
+# Tess Threat Model
+
+## Assets and Trust Boundaries
+
+Assets: operator identity, tenant/project data, agent sessions, fleet control, approvals, credentials, memories, tool outputs, audit evidence, and provider transports.
+
+Trust boundaries: Discord→plugin, CLI→gateway, plugin→gateway service identity, gateway→Pi/provider, Tess→Mos/fleet, Tess→Hermes, MCP→gateway, persistence, and tmux/Matrix transports.
+
+## Threat Matrix
+
+| ID    | Severity | Threat                                                                   | Required control                                                                                                                     | Required verification                                                     |
+| ----- | -------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| TM-01 | critical | Client invokes admin/system command without role                         | Server-side scope/role enforcement in executor; durable approval for privileged/destructive commands                                 | Authenticated non-admin and forged-scope tests deny and audit             |
+| TM-02 | critical | Cross-user/tenant list, attach, send, or terminate by guessed session ID | Owner/tenant binding on every session operation; admin override is explicit and audited                                              | Cross-tenant matrix for REST, WS, CLI, Discord and provider methods       |
+| TM-03 | high     | MCP caller supplies another `userId`                                     | Remove actor IDs from schemas; derive actor/tenant from authenticated context; per-tool scopes                                       | Forged actor/tool calls deny; no victim data returned                     |
+| TM-04 | high     | Discord ingress impersonates user/channel or bypasses gateway auth       | Service-to-service identity, guild/channel/user allowlists, signed/correlated envelope, replay protection                            | Invalid service identity, unlisted IDs, replayed message IDs all deny     |
+| TM-05 | high     | Secrets/PII leak in chat, auth links, tool args, logs, memory, or DB     | Redact before persistence/egress; DM/out-of-band auth flow; short-lived hashed token state; output classification                    | Seeded secret/PII canary absent from durable stores/logs/public channel   |
+| TM-06 | high     | Prompt/tool injection escalates from content to privileged action        | Treat messages/files/tool output as untrusted data; structured proposals only; allowlisted tools; approval binds exact action digest | Injection corpus cannot invoke unapproved tools or alter authority        |
+| TM-07 | high     | Approval forged, replayed, or applied to modified action                 | One-time approval with actor, tenant, action digest, expiry, correlation and consumption record                                      | Forged/replayed/expired/mutated approvals deny and audit                  |
+| TM-08 | medium   | Restart causes message loss or duplicate side effects                    | Durable inbox/outbox/checkpoint; idempotency keys; transactional state transitions; bounded replay                                   | Kill/restart at each state transition; exactly-once effect or safe dedupe |
+| TM-09 | medium   | Session GC/retention crosses tenant/session scope                        | Session/user-scoped GC or separately authorized global retention job                                                                 | GC one session; unrelated logs/memory remain unchanged                    |
+| TM-10 | high     | tmux/Matrix transport target or identity spoofing                        | Exact target/socket binding, peer identity verification, Matrix whoami, authenticated transport metadata                             | Wrong socket/peer/room/identity refuses delivery/attach                   |
+| TM-11 | medium   | Hermes adapter exposes unsupported or broader legacy powers              | Capability negotiation, default deny, normalized scopes, adapter sandbox/timeouts                                                    | Unsupported and over-scoped operations fail closed                        |
+| TM-12 | medium   | Tess competes with Mos or bypasses orchestration gates                   | Authority policy and correlated Mos handoff; no Tess worker-claim capability by default                                              | Coding/decomposition intent produces handoff, not direct claim            |
+
+## Security Invariants
+
+1. Authentication is not authorization; every command/tool/provider operation is authorized server-side.
+2. Actor, tenant, roles, and channel bindings come only from authenticated gateway context.
+3. No client-provided session ID grants ownership or attachment.
+4. No privileged action executes without a matching, unexpired, one-time approval when policy requires it.
+5. Redaction occurs before persistence and before channel egress.
+6. Every externally caused operation is replay-safe and correlated.
+7. Provider capability absence is a denial, not an invitation to shell around it.
+
+## Existing Findings That Block Tess
+
+- Command executor lacks server-side enforcement for declared scopes.
+- Session list/reuse/destroy surfaces are not owner-filtered consistently.
+- MCP schemas accept caller-supplied user identity.
+- Discord plugin lacks a complete authenticated service ingress and user/channel allowlists.
+- Chat/tool persistence lacks mandatory redaction.
+- Sessions/pending Discord output are in-memory and not restart-safe.
+- Session GC currently performs globally scoped promotion.
+
+These are tracked as M1 security prerequisites and must pass independent security review before Tess ingress is enabled.

docs/tess/VERIFICATION-MATRIX.md

@@ -0,0 +1,30 @@
+# Tess Verification Matrix
+
+| Acceptance criterion | Requirements                             | Planned evidence                                                                                                                | Gate             |
+| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| AC-TESS-01           | TESS-PI-001, TESS-DSC-001, TESS-CLI-001  | Discord/CLI same-session integration and streaming E2E                                                                          | M3-V             |
+| AC-TESS-02           | TESS-ARP-001, TESS-CLI-001, TESS-FLT-001 | CLI contract tests for status/sessions/tree/attach/send/stop, typed denial/error snapshots                                      | M3-V             |
+| AC-TESS-03           | TESS-PI-001, TESS-OBS-001                | Clean service launch; status asserts GPT-5.6 Sol, high reasoning and effective tool policy with secret canaries absent          | M2-V, M3-V       |
+| AC-TESS-04           | TESS-MOS-001, TESS-FLT-001               | Authority E2E: coding request creates Mos handoff; safe status runs in Tess; no competing worker claim                          | M4-V             |
+| AC-TESS-05           | TESS-HRM-001                             | Hermes capability contract suite: sessions/stream/send/tree plus Kanban/skills/memory/tools/cron supported-or-denied matrix     | M4-V             |
+| AC-TESS-06           | TESS-STA-001, TESS-SEC-008               | Kill/restart/compaction fault injection across inbox/outbox/checkpoint transitions; duplicate side-effect detector              | M2-V, M5-V       |
+| AC-TESS-07           | TESS-SEC-001..009                        | Threat-model abuse suite: authz, tenant isolation, forged identity/approval, injection, redaction, transport identity, GC scope | M1-V, M3-V, M5-V |
+| AC-TESS-08           | TESS-TRN-001                             | Common provider contract suite against tmux/fleet and Matrix/native; identity and replay tests                                  | M5-V             |
+| AC-TESS-09           | all                                      | `pnpm typecheck`, lint, format, unit/integration/contract/E2E; independent code and security reviews; CI URLs                   | Every milestone  |
+| AC-TESS-10           | TESS-MIG-001                             | Completed capability inventory with native/adapted/deferred/rejected state, owner, cutover/rollback evidence                    | M5-V             |
+| AC-TESS-11           | TESS-PLG-001, TESS-OBS-001               | OpenAPI and user/admin/developer/plugin/ops docs, sitemap links, documentation checklist                                        | M5-V             |
+
+## Security Abuse Suite Minimum
+
+- Role/scope matrix for every command and provider capability.
+- Cross-tenant and cross-user session ID matrix across REST, WS, Discord, CLI, MCP, and providers.
+- Discord service identity, guild/channel/user allowlist, replay, attachment, and mention/DM policy cases.
+- Prompt/tool injection corpus and structured-proposal enforcement.
+- Approval action-digest mutation, replay, expiry, tenant, and actor mismatch cases.
+- Secret/PII canaries through message, attachment, tool args/output, logs, memory, audit, and error paths.
+- Restart fault injection before/after enqueue, provider send, side effect, response persistence, and acknowledgement.
+- Wrong tmux socket/target and Matrix identity/room/replay cases.
+
+## Evidence Rules
+
+Evidence must include command/test name, terminal result, CI run URL, PR/merge reference, environment, and artifact/log location. A worker self-report is not evidence until independently verified.

packages/agent/src/index.ts

@@ -1 +1,5 @@
 export const VERSION = '0.0.0';
+
+export * from './runtime-provider-registry.js';
+export * from './tmux-fleet-runtime-provider.js';
+export * from './tess-durable-session.js';

packages/agent/src/runtime-provider-registry.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  AgentRuntimeProvider,
+  RuntimeAttachHandle,
+  RuntimeAttachMode,
+  RuntimeCapabilitySet,
+  RuntimeHealth,
+  RuntimeMessage,
+  RuntimeScope,
+  RuntimeSession,
+  RuntimeSessionTree,
+  RuntimeStreamEvent,
+} from '@mosaicstack/types';
+import { AgentRuntimeProviderRegistry } from './runtime-provider-registry.js';
+
+class TestRuntimeProvider implements AgentRuntimeProvider {
+  readonly id = 'test-runtime';
+
+  async capabilities(_scope: RuntimeScope): Promise<RuntimeCapabilitySet> {
+    return { supported: ['session.list'] };
+  }
+
+  async health(_scope: RuntimeScope): Promise<RuntimeHealth> {
+    return { status: 'healthy', checkedAt: '2026-07-12T00:00:00.000Z' };
+  }
+
+  async listSessions(_scope: RuntimeScope): Promise<RuntimeSession[]> {
+    return [];
+  }
+
+  async getSessionTree(_scope: RuntimeScope): Promise<RuntimeSessionTree[]> {
+    return [];
+  }
+
+  async *streamSession(
+    _sessionId: string,
+    _cursor: string | undefined,
+    _scope: RuntimeScope,
+  ): AsyncIterable<RuntimeStreamEvent> {
+    return;
+  }
+
+  async sendMessage(
+    _sessionId: string,
+    _message: RuntimeMessage,
+    _scope: RuntimeScope,
+  ): Promise<void> {}
+
+  async attach(
+    _sessionId: string,
+    _mode: RuntimeAttachMode,
+    _scope: RuntimeScope,
+  ): Promise<RuntimeAttachHandle> {
+    return {
+      attachmentId: 'attachment-1',
+      sessionId: 'session-1',
+      mode: 'read',
+      expiresAt: '2026-07-12T00:00:00.000Z',
+    };
+  }
+
+  async detach(_attachmentId: string, _scope: RuntimeScope): Promise<void> {}
+
+  async terminate(_sessionId: string, _approvalRef: string, _scope: RuntimeScope): Promise<void> {}
+}
+
+describe('AgentRuntimeProviderRegistry', (): void => {
+  it('resolves only registered runtime providers', (): void => {
+    const registry = new AgentRuntimeProviderRegistry();
+    const provider = new TestRuntimeProvider();
+
+    registry.register(provider);
+
+    expect(registry.get(provider.id)).toBe(provider);
+    expect(registry.get('unknown-runtime')).toBeUndefined();
+    expect(registry.list()).toEqual([provider]);
+  });
+
+  it('rejects duplicate and blank provider identities rather than silently replacing a runtime', (): void => {
+    const registry = new AgentRuntimeProviderRegistry();
+    const provider = new TestRuntimeProvider();
+
+    registry.register(provider);
+
+    expect((): void => {
+      registry.register(provider);
+    }).toThrow(/already registered/);
+    expect((): void => {
+      registry.require('');
+    }).toThrow(/provider ID is required/);
+    expect((): void => {
+      registry.require('unknown-runtime');
+    }).toThrow(/not registered/);
+  });
+});

packages/agent/src/runtime-provider-registry.ts

@@ -0,0 +1,40 @@
+import type { AgentRuntimeProvider } from '@mosaicstack/types';
+
+/**
+ * Registry for runtime providers. Registration is explicit and replacement is
+ * forbidden so a provider identity cannot be silently hijacked at runtime.
+ */
+export class AgentRuntimeProviderRegistry {
+  private readonly providers = new Map<string, AgentRuntimeProvider>();
+
+  register(provider: AgentRuntimeProvider): void {
+    const providerId = provider.id.trim();
+    if (providerId.length === 0) {
+      throw new Error('Runtime provider ID is required');
+    }
+    if (this.providers.has(providerId)) {
+      throw new Error(`Runtime provider is already registered: ${providerId}`);
+    }
+    this.providers.set(providerId, provider);
+  }
+
+  get(providerId: string): AgentRuntimeProvider | undefined {
+    return this.providers.get(providerId);
+  }
+
+  require(providerId: string): AgentRuntimeProvider {
+    const normalizedProviderId = providerId.trim();
+    if (normalizedProviderId.length === 0) {
+      throw new Error('Runtime provider ID is required');
+    }
+    const provider = this.providers.get(normalizedProviderId);
+    if (!provider) {
+      throw new Error(`Runtime provider is not registered: ${normalizedProviderId}`);
+    }
+    return provider;
+  }
+
+  list(): AgentRuntimeProvider[] {
+    return Array.from(this.providers.values());
+  }
+}

packages/agent/src/tess-durable-session.test.ts

@@ -0,0 +1,305 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DurableSessionCoordinator,
+  InMemoryDurableSessionStore,
+  type DurableSessionIdentity,
+} from './tess-durable-session.js';
+
+const IDENTITY: DurableSessionIdentity = {
+  agentName: 'Nova',
+  sessionId: 'tess-session-1',
+  tenantId: 'tenant-1',
+  ownerId: 'owner-1',
+  providerId: 'fleet',
+  runtimeSessionId: 'nova',
+};
+
+describe('DurableSessionCoordinator', () => {
+  it('reconstructs an exact session identity, pending inbox/outbox, checkpoint, and handoff after a simulated process restart', async () => {
+    const store = new InMemoryDurableSessionStore();
+    const beforeRestart = new DurableSessionCoordinator(store);
+
+    await beforeRestart.create(IDENTITY);
+    await beforeRestart.receive({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'ingress-1',
+      correlationId: 'correlation-1',
+      content: 'continue the session',
+    });
+    await beforeRestart.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-1',
+      correlationId: 'correlation-1',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'resumable response',
+    });
+    await beforeRestart.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-1',
+      cursor: 'cursor-42',
+      summary: 'operator asked for recovery proof',
+      compactionEpoch: 0,
+    });
+    await beforeRestart.handoff({
+      sessionId: IDENTITY.sessionId,
+      handoffId: 'handoff-1',
+      destination: 'mos',
+      correlationId: 'correlation-1',
+      checkpointId: 'checkpoint-1',
+      status: 'pending',
+    });
+
+    // Simulate an ungraceful process death: no in-memory coordinator state survives.
+    const afterRestart = new DurableSessionCoordinator(store);
+    const recovered = await afterRestart.recover(IDENTITY.sessionId);
+
+    expect(recovered.identity).toEqual(IDENTITY);
+    expect(recovered.inbox).toMatchObject([{ idempotencyKey: 'ingress-1', status: 'pending' }]);
+    expect(recovered.outbox).toMatchObject([{ idempotencyKey: 'outbox-1', status: 'pending' }]);
+    expect(recovered.checkpoint).toMatchObject({
+      checkpointId: 'checkpoint-1',
+      cursor: 'cursor-42',
+    });
+    expect(recovered.handoffs).toMatchObject([{ handoffId: 'handoff-1', status: 'pending' }]);
+  });
+
+  it('rebinds a recovered runtime while preserving the immutable conversation owner scope', async () => {
+    const coordinator = new DurableSessionCoordinator(new InMemoryDurableSessionStore());
+    await coordinator.create(IDENTITY);
+    await coordinator.create({
+      ...IDENTITY,
+      providerId: 'fleet-next',
+      runtimeSessionId: 'nova-next',
+    });
+
+    await expect(coordinator.snapshot(IDENTITY.sessionId)).resolves.toMatchObject({
+      identity: { ...IDENTITY, providerId: 'fleet-next', runtimeSessionId: 'nova-next' },
+    });
+    await expect(coordinator.create({ ...IDENTITY, ownerId: 'other-owner' })).rejects.toThrow(
+      /identity conflict/,
+    );
+  });
+
+  it('deduplicates duplicate ingress and never reprocesses an inbox record after restart or compaction', async () => {
+    const store = new InMemoryDurableSessionStore();
+    const firstProcess = new DurableSessionCoordinator(store);
+    const handled: string[] = [];
+
+    await firstProcess.create(IDENTITY);
+    await expect(
+      firstProcess.receive({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'ingress-duplicate',
+        correlationId: 'correlation-2',
+        content: 'only process me once',
+      }),
+    ).resolves.toMatchObject({ accepted: true });
+    await expect(
+      firstProcess.receive({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'ingress-duplicate',
+        correlationId: 'correlation-2',
+        content: 'only process me once',
+      }),
+    ).resolves.toMatchObject({ accepted: false, status: 'pending' });
+    await expect(
+      firstProcess.receive({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'ingress-duplicate',
+        correlationId: 'forged-correlation',
+        content: 'only process me once',
+      }),
+    ).rejects.toThrow(/idempotency conflict/);
+
+    await firstProcess.drainInbox(IDENTITY.sessionId, async (entry) => {
+      handled.push(entry.idempotencyKey);
+    });
+    await firstProcess.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-after-inbox',
+      cursor: 'cursor-43',
+      summary: 'safe to compact',
+      compactionEpoch: 1,
+    });
+
+    const afterRestartAndCompaction = new DurableSessionCoordinator(store);
+    await afterRestartAndCompaction.recover(IDENTITY.sessionId);
+    await afterRestartAndCompaction.drainInbox(IDENTITY.sessionId, async (entry) => {
+      handled.push(entry.idempotencyKey);
+    });
+
+    expect(handled).toEqual(['ingress-duplicate']);
+  });
+
+  it('does not redispatch an already applied outbox side effect after replay, restart, or compaction', async () => {
+    const store = new InMemoryDurableSessionStore();
+    const beforeRestart = new DurableSessionCoordinator(store);
+    const appliedEffects: string[] = [];
+
+    await beforeRestart.create(IDENTITY);
+    await beforeRestart.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'effect-1',
+      correlationId: 'correlation-3',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'send exactly once',
+    });
+    await expect(
+      beforeRestart.enqueueOutbox({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'effect-1',
+        correlationId: 'correlation-3',
+        channelId: 'cli',
+        kind: 'provider.send',
+        content: 'send exactly once',
+      }),
+    ).resolves.toMatchObject({ accepted: false, status: 'pending' });
+
+    await beforeRestart.dispatchOutbox(IDENTITY.sessionId, async (entry) => {
+      appliedEffects.push(entry.idempotencyKey);
+    });
+    await beforeRestart.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-after-effect',
+      cursor: 'cursor-44',
+      summary: 'effect persisted before compaction',
+      compactionEpoch: 1,
+    });
+
+    const afterRestartAndCompaction = new DurableSessionCoordinator(store);
+    await afterRestartAndCompaction.recover(IDENTITY.sessionId);
+    await afterRestartAndCompaction.dispatchOutbox(IDENTITY.sessionId, async (entry) => {
+      appliedEffects.push(entry.idempotencyKey);
+    });
+
+    expect(appliedEffects).toEqual(['effect-1']);
+  });
+
+  it('rejects outbox idempotency-key reuse when immutable effect data differs', async () => {
+    const store = new InMemoryDurableSessionStore();
+    const coordinator = new DurableSessionCoordinator(store);
+
+    await coordinator.create(IDENTITY);
+    await coordinator.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-conflict',
+      correlationId: 'correlation-outbox',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'original effect',
+    });
+    await expect(
+      coordinator.enqueueOutbox({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'outbox-conflict',
+        correlationId: 'correlation-outbox',
+        channelId: 'forged-channel',
+        kind: 'provider.send',
+        content: 'original effect',
+      }),
+    ).rejects.toThrow(/idempotency conflict/);
+  });
+
+  it('retains an ambiguous failed provider effect as processing until explicit recovery', async () => {
+    const store = new InMemoryDurableSessionStore();
+    const beforeRestart = new DurableSessionCoordinator(store);
+
+    await beforeRestart.create(IDENTITY);
+    await beforeRestart.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'ambiguous-effect',
+      correlationId: 'correlation-ambiguous',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'preserve this effect claim',
+    });
+    await expect(
+      beforeRestart.dispatchOutbox(IDENTITY.sessionId, async (): Promise<void> => {
+        throw new Error('provider connection dropped after submit');
+      }),
+    ).rejects.toThrow(/connection dropped/);
+
+    const afterRestart = new DurableSessionCoordinator(store);
+    await afterRestart.recover(IDENTITY.sessionId);
+    const calls: string[] = [];
+    await afterRestart.dispatchOutbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      calls.push(entry.idempotencyKey);
+    });
+
+    expect(calls).toEqual([]);
+    expect(await afterRestart.snapshot(IDENTITY.sessionId)).toMatchObject({
+      outbox: [{ idempotencyKey: 'ambiguous-effect', status: 'processing' }],
+    });
+  });
+
+  it('rejects a handoff-id replay with different immutable state', async () => {
+    const store = new InMemoryDurableSessionStore();
+    const coordinator = new DurableSessionCoordinator(store);
+
+    await coordinator.create(IDENTITY);
+    await coordinator.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-conflict',
+      cursor: 'cursor-conflict',
+      summary: 'handoff conflict proof',
+      compactionEpoch: 0,
+    });
+    await coordinator.handoff({
+      sessionId: IDENTITY.sessionId,
+      handoffId: 'handoff-conflict',
+      destination: 'mos',
+      correlationId: 'correlation-conflict',
+      checkpointId: 'checkpoint-conflict',
+      status: 'pending',
+    });
+
+    await expect(
+      coordinator.handoff({
+        sessionId: IDENTITY.sessionId,
+        handoffId: 'handoff-conflict',
+        destination: 'forged-destination',
+        correlationId: 'correlation-conflict',
+        checkpointId: 'checkpoint-conflict',
+        status: 'pending',
+      }),
+    ).rejects.toThrow(/identity conflict/);
+  });
+
+  it('keeps a handoff portable and resumes it from its durable checkpoint without process-local references', async () => {
+    const store = new InMemoryDurableSessionStore();
+    const source = new DurableSessionCoordinator(store);
+
+    await source.create(IDENTITY);
+    await source.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-handoff',
+      cursor: 'cursor-45',
+      summary: 'portable state',
+      compactionEpoch: 2,
+    });
+    await source.handoff({
+      sessionId: IDENTITY.sessionId,
+      handoffId: 'handoff-portable',
+      destination: 'mos',
+      correlationId: 'correlation-4',
+      checkpointId: 'checkpoint-handoff',
+      status: 'pending',
+    });
+    await source.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-later',
+      cursor: 'cursor-46',
+      summary: 'newer compacted state must not strand the handoff',
+      compactionEpoch: 3,
+    });
+
+    const receivingProcess = new DurableSessionCoordinator(store);
+    const handoff = await receivingProcess.resumeHandoff('handoff-portable');
+
+    expect(handoff.identity).toEqual(IDENTITY);
+    expect(handoff.checkpoint).toMatchObject({ checkpointId: 'checkpoint-handoff' });
+    expect(handoff.handoff).toMatchObject({ handoffId: 'handoff-portable', destination: 'mos' });
+  });
+});

packages/agent/src/tess-durable-session.ts

@@ -0,0 +1,498 @@
+export interface DurableSessionIdentity {
+  /** Provisioned roster identity; isolates durable state between named agents. */
+  agentName: string;
+  sessionId: string;
+  tenantId: string;
+  ownerId: string;
+  providerId: string;
+  runtimeSessionId: string;
+}
+
+export type DurableInboxStatus = 'pending' | 'processing' | 'processed';
+export type DurableOutboxStatus = 'pending' | 'processing' | 'delivered';
+
+export interface DurableInboxInput {
+  sessionId: string;
+  idempotencyKey: string;
+  correlationId: string;
+  content: string;
+}
+
+export interface DurableInboxEntry extends DurableInboxInput {
+  status: DurableInboxStatus;
+}
+
+export interface DurableOutboxInput {
+  sessionId: string;
+  idempotencyKey: string;
+  correlationId: string;
+  channelId: string;
+  kind: string;
+  content: string;
+}
+
+export interface DurableOutboxEntry extends DurableOutboxInput {
+  status: DurableOutboxStatus;
+}
+
+export interface DurableCheckpointInput {
+  sessionId: string;
+  checkpointId: string;
+  cursor: string;
+  summary: string;
+  compactionEpoch: number;
+}
+
+export interface DurableCheckpoint extends DurableCheckpointInput {}
+
+export interface DurableHandoffInput {
+  sessionId: string;
+  handoffId: string;
+  destination: string;
+  correlationId: string;
+  checkpointId: string;
+  status: 'pending' | 'accepted';
+}
+
+export interface DurableHandoff extends DurableHandoffInput {}
+
+export interface DurableSessionSnapshot {
+  identity: DurableSessionIdentity;
+  inbox: DurableInboxEntry[];
+  outbox: DurableOutboxEntry[];
+  checkpoint?: DurableCheckpoint;
+  handoffs: DurableHandoff[];
+}
+
+export interface DurableHandoffRecovery {
+  identity: DurableSessionIdentity;
+  checkpoint: DurableCheckpoint;
+  handoff: DurableHandoff;
+}
+
+export interface DurableEnqueueResult<TStatus extends string> {
+  accepted: boolean;
+  status: TStatus;
+}
+
+/**
+ * A durable-state port. Implementations must atomically claim and complete work
+ * records. Recovery may requeue interrupted inbox work, but never an
+ * externally visible outbox effect: an ambiguous provider result remains
+ * claimed until a separately authorized reconciliation proves it safe.
+ */
+export interface DurableSessionStore {
+  create(identity: DurableSessionIdentity): Promise<void>;
+  snapshot(sessionId: string): Promise<DurableSessionSnapshot | null>;
+  enqueueInbox(input: DurableInboxInput): Promise<DurableEnqueueResult<DurableInboxStatus>>;
+  claimInbox(sessionId: string): Promise<DurableInboxEntry | null>;
+  completeInbox(sessionId: string, idempotencyKey: string): Promise<void>;
+  releaseInbox(sessionId: string, idempotencyKey: string): Promise<void>;
+  enqueueOutbox(input: DurableOutboxInput): Promise<DurableEnqueueResult<DurableOutboxStatus>>;
+  claimOutbox(sessionId: string): Promise<DurableOutboxEntry | null>;
+  claimOutboxByKey(sessionId: string, idempotencyKey: string): Promise<DurableOutboxEntry | null>;
+  completeOutbox(sessionId: string, idempotencyKey: string): Promise<void>;
+  releaseOutbox(sessionId: string, idempotencyKey: string): Promise<void>;
+  checkpoint(input: DurableCheckpointInput): Promise<void>;
+  findCheckpoint(sessionId: string, checkpointId: string): Promise<DurableCheckpoint | null>;
+  handoff(input: DurableHandoffInput): Promise<void>;
+  findHandoff(handoffId: string): Promise<DurableHandoff | null>;
+  requeueInFlight(sessionId: string): Promise<void>;
+}
+
+export class DurableSessionNotFoundError extends Error {
+  constructor(sessionId: string) {
+    super(`Durable Tess session not found: ${sessionId}`);
+    this.name = 'DurableSessionNotFoundError';
+  }
+}
+
+export class DurableSessionCoordinator {
+  constructor(private readonly store: DurableSessionStore) {}
+
+  async create(identity: DurableSessionIdentity): Promise<void> {
+    this.assertIdentity(identity);
+    await this.store.create(identity);
+  }
+
+  async receive(input: DurableInboxInput): Promise<DurableEnqueueResult<DurableInboxStatus>> {
+    this.assertRecord(input.sessionId, input.idempotencyKey, input.correlationId, input.content);
+    return this.store.enqueueInbox(input);
+  }
+
+  async enqueueOutbox(
+    input: DurableOutboxInput,
+  ): Promise<DurableEnqueueResult<DurableOutboxStatus>> {
+    this.assertRecord(
+      input.sessionId,
+      input.idempotencyKey,
+      input.correlationId,
+      input.channelId,
+      input.content,
+    );
+    if (input.kind.trim().length === 0) throw new Error('Durable outbox kind is required');
+    return this.store.enqueueOutbox(input);
+  }
+
+  async checkpoint(input: DurableCheckpointInput): Promise<void> {
+    this.assertRecord(input.sessionId, input.checkpointId, input.cursor, input.summary);
+    if (!Number.isInteger(input.compactionEpoch) || input.compactionEpoch < 0) {
+      throw new Error('Durable checkpoint compaction epoch must be a non-negative integer');
+    }
+    await this.store.checkpoint(input);
+  }
+
+  async handoff(input: DurableHandoffInput): Promise<void> {
+    this.assertRecord(input.sessionId, input.handoffId, input.destination, input.correlationId);
+    if (input.checkpointId.trim().length === 0)
+      throw new Error('Durable handoff checkpoint is required');
+    await this.store.handoff(input);
+  }
+
+  /** Read durable state without changing claim status; safe during normal operation. */
+  async snapshot(sessionId: string): Promise<DurableSessionSnapshot> {
+    const snapshot = await this.store.snapshot(sessionId);
+    if (!snapshot) throw new DurableSessionNotFoundError(sessionId);
+    return snapshot;
+  }
+
+  /** Requeue interrupted inbox work during recovery; preserve ambiguous outbox claims. */
+  async recover(sessionId: string): Promise<DurableSessionSnapshot> {
+    await this.store.requeueInFlight(sessionId);
+    return this.snapshot(sessionId);
+  }
+
+  async drainInbox(
+    sessionId: string,
+    handler: (entry: DurableInboxEntry) => Promise<void>,
+  ): Promise<void> {
+    for (;;) {
+      const entry = await this.store.claimInbox(sessionId);
+      if (!entry) return;
+      try {
+        await handler(entry);
+      } catch (error: unknown) {
+        await this.store.releaseInbox(sessionId, entry.idempotencyKey);
+        throw error;
+      }
+      // If this write fails after the handler succeeded, leave the record
+      // processing. A recovery path can retry it with its stable idempotency key.
+      await this.store.completeInbox(sessionId, entry.idempotencyKey);
+    }
+  }
+
+  async dispatchOutbox(
+    sessionId: string,
+    dispatcher: (entry: DurableOutboxEntry) => Promise<void>,
+  ): Promise<void> {
+    for (;;) {
+      const entry = await this.store.claimOutbox(sessionId);
+      if (!entry) return;
+      // A provider failure can be ambiguous: it may occur after the receiver
+      // accepted the idempotency key. Preserve the claim for reconciliation.
+      await dispatcher(entry);
+      // Do not requeue an effect after it has been applied but before its
+      // terminal state could be persisted; recovery preserves the claim.
+      await this.store.completeOutbox(sessionId, entry.idempotencyKey);
+    }
+  }
+
+  async dispatchOutboxEntry(
+    sessionId: string,
+    idempotencyKey: string,
+    dispatcher: (entry: DurableOutboxEntry) => Promise<void>,
+  ): Promise<void> {
+    const entry = await this.store.claimOutboxByKey(sessionId, idempotencyKey);
+    if (!entry) return;
+    // A provider failure can be ambiguous, so this stays processing until
+    // separately authorized reconciliation proves it safe to resolve.
+    await dispatcher(entry);
+    await this.store.completeOutbox(sessionId, entry.idempotencyKey);
+  }
+
+  async resumeHandoff(handoffId: string): Promise<DurableHandoffRecovery> {
+    const handoff = await this.store.findHandoff(handoffId);
+    if (!handoff) throw new Error(`Durable Tess handoff not found: ${handoffId}`);
+    const snapshot = await this.snapshot(handoff.sessionId);
+    const checkpoint = await this.store.findCheckpoint(handoff.sessionId, handoff.checkpointId);
+    if (!checkpoint) {
+      throw new Error(`Durable Tess handoff checkpoint is unavailable: ${handoff.checkpointId}`);
+    }
+    return { identity: snapshot.identity, checkpoint, handoff };
+  }
+
+  private assertIdentity(identity: DurableSessionIdentity): void {
+    this.assertRecord(
+      identity.agentName,
+      identity.sessionId,
+      identity.tenantId,
+      identity.ownerId,
+      identity.providerId,
+    );
+    if (identity.runtimeSessionId.trim().length === 0) {
+      throw new Error('Durable runtime session identity is required');
+    }
+  }
+
+  private assertRecord(...values: string[]): void {
+    if (values.some((value: string): boolean => value.trim().length === 0)) {
+      throw new Error('Durable session records require non-empty fields');
+    }
+  }
+}
+
+interface InMemorySessionState {
+  identity: DurableSessionIdentity;
+  inbox: Map<string, DurableInboxEntry>;
+  outbox: Map<string, DurableOutboxEntry>;
+  checkpoints: Map<string, DurableCheckpoint>;
+  handoffs: Map<string, DurableHandoff>;
+}
+
+/** Reference store for deterministic domain tests; production uses the gateway DB adapter. */
+export class InMemoryDurableSessionStore implements DurableSessionStore {
+  private readonly sessions = new Map<string, InMemorySessionState>();
+
+  async create(identity: DurableSessionIdentity): Promise<void> {
+    const existing = this.sessions.get(identity.sessionId);
+    if (existing) {
+      if (!sameEnrollmentScope(existing.identity, identity)) {
+        throw new Error(`Durable Tess session identity conflict: ${identity.sessionId}`);
+      }
+      existing.identity.providerId = identity.providerId;
+      existing.identity.runtimeSessionId = identity.runtimeSessionId;
+      return;
+    }
+    this.sessions.set(identity.sessionId, {
+      identity: copyIdentity(identity),
+      inbox: new Map(),
+      outbox: new Map(),
+      checkpoints: new Map(),
+      handoffs: new Map(),
+    });
+  }
+
+  async snapshot(sessionId: string): Promise<DurableSessionSnapshot | null> {
+    const state = this.sessions.get(sessionId);
+    if (!state) return null;
+    const checkpoint = latestCheckpoint(state.checkpoints);
+    return {
+      identity: copyIdentity(state.identity),
+      inbox: [...state.inbox.values()].map(copyInbox),
+      outbox: [...state.outbox.values()].map(copyOutbox),
+      ...(checkpoint ? { checkpoint: copyCheckpoint(checkpoint) } : {}),
+      handoffs: [...state.handoffs.values()].map(copyHandoff),
+    };
+  }
+
+  async enqueueInbox(input: DurableInboxInput): Promise<DurableEnqueueResult<DurableInboxStatus>> {
+    const state = this.require(input.sessionId);
+    const existing = state.inbox.get(input.idempotencyKey);
+    if (existing) {
+      if (!sameInbox(existing, input)) {
+        throw new Error(`Durable Tess inbox idempotency conflict: ${input.idempotencyKey}`);
+      }
+      return { accepted: false, status: existing.status };
+    }
+    state.inbox.set(input.idempotencyKey, { ...input, status: 'pending' });
+    return { accepted: true, status: 'pending' };
+  }
+
+  async claimInbox(sessionId: string): Promise<DurableInboxEntry | null> {
+    const state = this.require(sessionId);
+    const entry = [...state.inbox.values()].find(
+      (candidate: DurableInboxEntry): boolean => candidate.status === 'pending',
+    );
+    if (!entry) return null;
+    entry.status = 'processing';
+    return copyInbox(entry);
+  }
+
+  async completeInbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    this.requireEntry(this.require(sessionId).inbox, idempotencyKey, 'inbox').status = 'processed';
+  }
+
+  async releaseInbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    this.requireEntry(this.require(sessionId).inbox, idempotencyKey, 'inbox').status = 'pending';
+  }
+
+  async enqueueOutbox(
+    input: DurableOutboxInput,
+  ): Promise<DurableEnqueueResult<DurableOutboxStatus>> {
+    const state = this.require(input.sessionId);
+    const existing = state.outbox.get(input.idempotencyKey);
+    if (existing) {
+      if (!sameOutbox(existing, input)) {
+        throw new Error(`Durable Tess outbox idempotency conflict: ${input.idempotencyKey}`);
+      }
+      return { accepted: false, status: existing.status };
+    }
+    state.outbox.set(input.idempotencyKey, { ...input, status: 'pending' });
+    return { accepted: true, status: 'pending' };
+  }
+
+  async claimOutbox(sessionId: string): Promise<DurableOutboxEntry | null> {
+    const state = this.require(sessionId);
+    const entry = [...state.outbox.values()].find(
+      (candidate: DurableOutboxEntry): boolean => candidate.status === 'pending',
+    );
+    if (!entry) return null;
+    entry.status = 'processing';
+    return copyOutbox(entry);
+  }
+
+  async claimOutboxByKey(
+    sessionId: string,
+    idempotencyKey: string,
+  ): Promise<DurableOutboxEntry | null> {
+    const entry = this.require(sessionId).outbox.get(idempotencyKey);
+    if (!entry || entry.status !== 'pending') return null;
+    entry.status = 'processing';
+    return copyOutbox(entry);
+  }
+
+  async completeOutbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    this.requireEntry(this.require(sessionId).outbox, idempotencyKey, 'outbox').status =
+      'delivered';
+  }
+
+  async releaseOutbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    this.requireEntry(this.require(sessionId).outbox, idempotencyKey, 'outbox').status = 'pending';
+  }
+
+  async checkpoint(input: DurableCheckpointInput): Promise<void> {
+    const checkpoints = this.require(input.sessionId).checkpoints;
+    const existing = checkpoints.get(input.checkpointId);
+    if (existing && !sameCheckpoint(existing, input)) {
+      throw new Error(`Durable Tess checkpoint identity conflict: ${input.checkpointId}`);
+    }
+    if (!existing) checkpoints.set(input.checkpointId, { ...input });
+  }
+
+  async findCheckpoint(sessionId: string, checkpointId: string): Promise<DurableCheckpoint | null> {
+    const checkpoint = this.require(sessionId).checkpoints.get(checkpointId);
+    return checkpoint ? copyCheckpoint(checkpoint) : null;
+  }
+
+  async handoff(input: DurableHandoffInput): Promise<void> {
+    const state = this.require(input.sessionId);
+    if (!state.checkpoints.has(input.checkpointId)) {
+      throw new Error(`Durable Tess handoff checkpoint is unavailable: ${input.checkpointId}`);
+    }
+    const existing = state.handoffs.get(input.handoffId);
+    if (existing && !sameHandoff(existing, input)) {
+      throw new Error(`Durable Tess handoff identity conflict: ${input.handoffId}`);
+    }
+    if (!existing) state.handoffs.set(input.handoffId, { ...input });
+  }
+
+  async findHandoff(handoffId: string): Promise<DurableHandoff | null> {
+    for (const state of this.sessions.values()) {
+      const handoff = state.handoffs.get(handoffId);
+      if (handoff) return copyHandoff(handoff);
+    }
+    return null;
+  }
+
+  async requeueInFlight(sessionId: string): Promise<void> {
+    const state = this.require(sessionId);
+    for (const entry of state.inbox.values()) {
+      if (entry.status === 'processing') entry.status = 'pending';
+    }
+  }
+
+  private require(sessionId: string): InMemorySessionState {
+    const state = this.sessions.get(sessionId);
+    if (!state) throw new DurableSessionNotFoundError(sessionId);
+    return state;
+  }
+
+  private requireEntry<T extends { status: string }>(
+    records: Map<string, T>,
+    idempotencyKey: string,
+    kind: string,
+  ): T {
+    const entry = records.get(idempotencyKey);
+    if (!entry) throw new Error(`Durable Tess ${kind} entry not found: ${idempotencyKey}`);
+    return entry;
+  }
+}
+
+function sameEnrollmentScope(left: DurableSessionIdentity, right: DurableSessionIdentity): boolean {
+  return (
+    left.agentName === right.agentName &&
+    left.sessionId === right.sessionId &&
+    left.tenantId === right.tenantId &&
+    left.ownerId === right.ownerId
+  );
+}
+
+function sameInbox(left: DurableInboxEntry, right: DurableInboxInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.idempotencyKey === right.idempotencyKey &&
+    left.correlationId === right.correlationId &&
+    left.content === right.content
+  );
+}
+
+function sameOutbox(left: DurableOutboxEntry, right: DurableOutboxInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.idempotencyKey === right.idempotencyKey &&
+    left.correlationId === right.correlationId &&
+    left.channelId === right.channelId &&
+    left.kind === right.kind &&
+    left.content === right.content
+  );
+}
+
+function sameCheckpoint(left: DurableCheckpoint, right: DurableCheckpointInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.checkpointId === right.checkpointId &&
+    left.cursor === right.cursor &&
+    left.summary === right.summary &&
+    left.compactionEpoch === right.compactionEpoch
+  );
+}
+
+function latestCheckpoint(
+  checkpoints: Map<string, DurableCheckpoint>,
+): DurableCheckpoint | undefined {
+  return [...checkpoints.values()].sort(
+    (left: DurableCheckpoint, right: DurableCheckpoint): number =>
+      right.compactionEpoch - left.compactionEpoch,
+  )[0];
+}
+
+function sameHandoff(left: DurableHandoff, right: DurableHandoffInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.handoffId === right.handoffId &&
+    left.destination === right.destination &&
+    left.correlationId === right.correlationId &&
+    left.checkpointId === right.checkpointId &&
+    left.status === right.status
+  );
+}
+
+function copyIdentity(identity: DurableSessionIdentity): DurableSessionIdentity {
+  return { ...identity };
+}
+
+function copyInbox(entry: DurableInboxEntry): DurableInboxEntry {
+  return { ...entry };
+}
+
+function copyOutbox(entry: DurableOutboxEntry): DurableOutboxEntry {
+  return { ...entry };
+}
+
+function copyCheckpoint(checkpoint: DurableCheckpoint): DurableCheckpoint {
+  return { ...checkpoint };
+}
+
+function copyHandoff(handoff: DurableHandoff): DurableHandoff {
+  return { ...handoff };
+}

packages/agent/src/tmux-fleet-runtime-provider.test.ts

@@ -0,0 +1,261 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { RuntimeScope } from '@mosaicstack/types';
+import {
+  type FleetReadAuthority,
+  type FleetWriteAuthority,
+  TmuxFleetRuntimeProvider,
+} from './tmux-fleet-runtime-provider.js';
+import type {
+  FleetRuntimeProviderError,
+  FleetRuntimeTarget,
+  FleetRuntimeTransport,
+} from './tmux-fleet-runtime-provider.js';
+
+const scope: RuntimeScope = {
+  actorId: 'operator-1',
+  tenantId: 'tenant-a',
+  channelId: 'discord-1',
+  correlationId: 'corr-1',
+};
+
+const target: FleetRuntimeTarget = {
+  id: 'coder0',
+  runtimeId: 'codex',
+  socketName: 'tess-fleet',
+};
+
+function transport(): FleetRuntimeTransport {
+  return {
+    verifySession: vi.fn(async (): Promise<FleetRuntimeTarget> => target),
+    listSessions: vi.fn(async (): Promise<FleetRuntimeTarget[]> => [target]),
+    sendMessage: vi.fn(async (): Promise<void> => undefined),
+    terminate: vi.fn(async (): Promise<void> => undefined),
+  };
+}
+
+function readAuthority(): FleetReadAuthority {
+  return { canRead: vi.fn(async (): Promise<boolean> => true) };
+}
+
+describe('TmuxFleetRuntimeProvider security policy', (): void => {
+  it('advertises only fleet operations it can safely implement', async (): Promise<void> => {
+    const provider = new TmuxFleetRuntimeProvider({ transport: transport() });
+
+    await expect(provider.capabilities(scope)).resolves.toEqual({
+      supported: [
+        'session.list',
+        'session.tree',
+        'session.send',
+        'session.attach',
+        'session.terminate',
+      ],
+    });
+  });
+
+  it('rejects control attach without consulting the tmux transport', async (): Promise<void> => {
+    const fleet = transport();
+    const provider = new TmuxFleetRuntimeProvider({ transport: fleet });
+
+    await expect(provider.attach('coder0', 'control', scope)).rejects.toMatchObject({
+      code: 'forbidden',
+    } satisfies Partial<FleetRuntimeProviderError>);
+    expect(fleet.verifySession).not.toHaveBeenCalled();
+  });
+
+  it('denies fleet listing without an exact-scope read authority decision', async (): Promise<void> => {
+    const fleet = transport();
+    const provider = new TmuxFleetRuntimeProvider({ transport: fleet });
+
+    await expect(provider.listSessions(scope)).rejects.toMatchObject({
+      code: 'forbidden',
+    } satisfies Partial<FleetRuntimeProviderError>);
+    expect(fleet.listSessions).not.toHaveBeenCalled();
+  });
+
+  it('denies read attachment without an exact-scope read authority decision', async (): Promise<void> => {
+    const fleet = transport();
+    const provider = new TmuxFleetRuntimeProvider({ transport: fleet });
+
+    await expect(provider.attach('coder0', 'read', scope)).rejects.toMatchObject({
+      code: 'forbidden',
+    } satisfies Partial<FleetRuntimeProviderError>);
+    expect(fleet.verifySession).not.toHaveBeenCalled();
+  });
+
+  it('creates a read-only attachment only after exact target verification', async (): Promise<void> => {
+    const fleet = transport();
+    const provider = new TmuxFleetRuntimeProvider({
+      transport: fleet,
+      readAuthority: readAuthority(),
+      attachmentIdFactory: (): string => 'attachment-1',
+      now: (): Date => new Date('2026-07-12T00:00:00.000Z'),
+    });
+
+    await expect(provider.attach('coder0', 'read', scope)).resolves.toEqual({
+      attachmentId: 'attachment-1',
+      sessionId: 'coder0',
+      mode: 'read',
+      expiresAt: '2026-07-12T00:05:00.000Z',
+    });
+    expect(fleet.verifySession).toHaveBeenCalledWith('coder0');
+  });
+
+  it('denies attachment-handle replay from another immutable actor scope', async (): Promise<void> => {
+    const fleet = transport();
+    const provider = new TmuxFleetRuntimeProvider({
+      transport: fleet,
+      readAuthority: readAuthority(),
+      attachmentIdFactory: (): string => 'attachment-1',
+      now: (): Date => new Date('2026-07-12T00:00:00.000Z'),
+    });
+    await provider.attach('coder0', 'read', scope);
+
+    await expect(
+      provider.detach('attachment-1', { ...scope, actorId: 'operator-2' }),
+    ).rejects.toMatchObject({
+      code: 'forbidden',
+    } satisfies Partial<FleetRuntimeProviderError>);
+  });
+
+  it('keeps attachment scope immutable after caller-side scope mutation', async (): Promise<void> => {
+    const mutableScope = { ...scope };
+    const provider = new TmuxFleetRuntimeProvider({
+      transport: transport(),
+      readAuthority: readAuthority(),
+      attachmentIdFactory: (): string => 'attachment-1',
+      now: (): Date => new Date('2026-07-12T00:00:00.000Z'),
+    });
+    await provider.attach('coder0', 'read', mutableScope);
+    mutableScope.actorId = 'operator-2';
+
+    await expect(provider.detach('attachment-1', scope)).resolves.toBeUndefined();
+  });
+
+  it('denies expired attachment handles and removes them', async (): Promise<void> => {
+    let now = new Date('2026-07-12T00:00:00.000Z');
+    const provider = new TmuxFleetRuntimeProvider({
+      transport: transport(),
+      readAuthority: readAuthority(),
+      attachmentIdFactory: (): string => 'attachment-1',
+      now: (): Date => now,
+    });
+    await provider.attach('coder0', 'read', scope);
+    now = new Date('2026-07-12T00:05:00.001Z');
+
+    await expect(provider.detach('attachment-1', scope)).rejects.toMatchObject({
+      code: 'forbidden',
+    } satisfies Partial<FleetRuntimeProviderError>);
+    await expect(provider.detach('attachment-1', scope)).rejects.toMatchObject({
+      code: 'not_found',
+    } satisfies Partial<FleetRuntimeProviderError>);
+  });
+
+  it('prunes expired attachment handles before creating a new handle', async (): Promise<void> => {
+    let now = new Date('2026-07-12T00:00:00.000Z');
+    let attachmentSequence = 0;
+    const provider = new TmuxFleetRuntimeProvider({
+      transport: transport(),
+      readAuthority: readAuthority(),
+      attachmentIdFactory: (): string => `attachment-${++attachmentSequence}`,
+      now: (): Date => now,
+    });
+    await provider.attach('coder0', 'read', scope);
+    now = new Date('2026-07-12T00:05:00.001Z');
+    await provider.attach('coder0', 'read', scope);
+
+    await expect(provider.detach('attachment-1', scope)).rejects.toMatchObject({
+      code: 'not_found',
+    } satisfies Partial<FleetRuntimeProviderError>);
+  });
+
+  it('rejects an empty message before consulting write authority or tmux', async (): Promise<void> => {
+    const fleet = transport();
+    const writeAuthority: FleetWriteAuthority = {
+      canWrite: vi.fn(async (): Promise<boolean> => true),
+      assertAuthorized: vi.fn(async (): Promise<void> => undefined),
+    };
+    const provider = new TmuxFleetRuntimeProvider({ transport: fleet, writeAuthority });
+
+    await expect(
+      provider.sendMessage('coder0', { content: '', idempotencyKey: 'message-1' }, scope),
+    ).rejects.toMatchObject({
+      code: 'invalid_request',
+    } satisfies Partial<FleetRuntimeProviderError>);
+    expect(writeAuthority.canWrite).not.toHaveBeenCalled();
+    expect(writeAuthority.assertAuthorized).not.toHaveBeenCalled();
+    expect(fleet.verifySession).not.toHaveBeenCalled();
+    expect(fleet.sendMessage).not.toHaveBeenCalled();
+  });
+
+  it('denies fleet writes by default before probing the tmux transport', async (): Promise<void> => {
+    const fleet = transport();
+    const provider = new TmuxFleetRuntimeProvider({ transport: fleet });
+
+    await expect(
+      provider.sendMessage('coder0', { content: 'hello', idempotencyKey: 'message-1' }, scope),
+    ).rejects.toMatchObject({ code: 'forbidden' } satisfies Partial<FleetRuntimeProviderError>);
+    await expect(provider.terminate('coder0', 'approval-1', scope)).rejects.toMatchObject({
+      code: 'forbidden',
+    } satisfies Partial<FleetRuntimeProviderError>);
+    expect(fleet.verifySession).not.toHaveBeenCalled();
+    expect(fleet.sendMessage).not.toHaveBeenCalled();
+    expect(fleet.terminate).not.toHaveBeenCalled();
+  });
+
+  it('rejects an unverified target before consulting Mos write authority', async (): Promise<void> => {
+    const fleet = transport();
+    fleet.verifySession = vi.fn(async (): Promise<FleetRuntimeTarget> => {
+      throw new Error('target identity mismatch');
+    });
+    const writeAuthority: FleetWriteAuthority = {
+      canWrite: vi.fn(async (): Promise<boolean> => true),
+      assertAuthorized: vi.fn(async (): Promise<void> => undefined),
+    };
+    const provider = new TmuxFleetRuntimeProvider({ transport: fleet, writeAuthority });
+
+    await expect(
+      provider.sendMessage('coder', { content: 'hello', idempotencyKey: 'message-1' }, scope),
+    ).rejects.toThrow('target identity mismatch');
+    expect(writeAuthority.assertAuthorized).not.toHaveBeenCalled();
+    expect(fleet.sendMessage).not.toHaveBeenCalled();
+  });
+
+  it('passes an exact session ID to the fleet transport only through authorized Mos writes', async (): Promise<void> => {
+    const fleet = transport();
+    const writeAuthority: FleetWriteAuthority = {
+      canWrite: vi.fn(async (): Promise<boolean> => true),
+      assertAuthorized: vi.fn(async (): Promise<void> => undefined),
+    };
+    const provider = new TmuxFleetRuntimeProvider({
+      transport: fleet,
+      sourceLabel: 'tess',
+      writeAuthority,
+    });
+
+    await provider.sendMessage('coder0', { content: 'hello', idempotencyKey: 'message-1' }, scope);
+    await provider.terminate('coder0', 'approval-1', scope);
+
+    expect(writeAuthority.assertAuthorized).toHaveBeenCalledWith({
+      operation: 'session.send',
+      sessionId: 'coder0',
+      scope,
+    });
+    expect(writeAuthority.assertAuthorized).toHaveBeenCalledWith({
+      operation: 'session.terminate',
+      sessionId: 'coder0',
+      scope,
+      approvalRef: 'approval-1',
+    });
+    expect(fleet.sendMessage).toHaveBeenCalledWith('coder0', 'hello', 'tess');
+    expect(fleet.terminate).toHaveBeenCalledWith('coder0');
+  });
+
+  it('fails closed when consumers ask for session streaming', async (): Promise<void> => {
+    const provider = new TmuxFleetRuntimeProvider({ transport: transport() });
+    const stream = provider.streamSession('coder0', undefined, scope)[Symbol.asyncIterator]();
+
+    await expect(stream.next()).rejects.toMatchObject({
+      code: 'capability_unsupported',
+    } satisfies Partial<FleetRuntimeProviderError>);
+  });
+});

packages/agent/src/tmux-fleet-runtime-provider.ts

@@ -0,0 +1,368 @@
+import { randomUUID } from 'node:crypto';
+import type {
+  AgentRuntimeProvider,
+  RuntimeAttachHandle,
+  RuntimeAttachMode,
+  RuntimeCapabilitySet,
+  RuntimeHealth,
+  RuntimeMessage,
+  RuntimeScope,
+  RuntimeSession,
+  RuntimeSessionTree,
+  RuntimeStreamEvent,
+} from '@mosaicstack/types';
+const FLEET_PROVIDER_ID = 'fleet.tmux';
+const ATTACHMENT_TTL_MS = 5 * 60 * 1_000;
+
+export type FleetRuntimeProviderErrorCode =
+  | 'capability_unsupported'
+  | 'forbidden'
+  | 'invalid_request'
+  | 'not_found';
+
+/** A roster-bound target verified by the concrete fleet transport. */
+export interface FleetRuntimeTarget {
+  id: string;
+  runtimeId: string;
+  socketName: string;
+}
+
+/**
+ * Narrow transport boundary implemented by the Mosaic tmux adapter. Keeping it
+ * here prevents the runtime package from depending on the Mosaic CLI package.
+ */
+export interface FleetRuntimeTransport {
+  verifySession(sessionId: string): Promise<FleetRuntimeTarget>;
+  listSessions(): Promise<FleetRuntimeTarget[]>;
+  sendMessage(sessionId: string, message: string, sourceLabel: string): Promise<void>;
+  terminate(sessionId: string): Promise<void>;
+}
+
+export type FleetReadOperation =
+  | 'runtime.health'
+  | 'session.list'
+  | 'session.tree'
+  | 'session.attach';
+
+export interface FleetReadAuthorization {
+  operation: FleetReadOperation;
+  scope: RuntimeScope;
+  sessionId?: string;
+}
+
+/** Authorization for fleet inspection and read-only attachments. */
+export interface FleetReadAuthority {
+  canRead(authorization: FleetReadAuthorization): Promise<boolean>;
+}
+
+export interface FleetWriteAuthorization {
+  operation: 'session.send' | 'session.terminate';
+  sessionId: string;
+  scope: RuntimeScope;
+  /** Present only for terminate; authority adapters bind it to the exact action. */
+  approvalRef?: string;
+}
+
+/**
+ * Mos is the only authority that may permit Tess write/control requests to a
+ * fleet peer. Gateway records the request and denial/success around provider
+ * invocation; the default authority prevents direct Tess writes by design.
+ */
+export interface FleetWriteAuthority {
+  /** Non-consuming preflight used before probing the fleet transport. */
+  canWrite(authorization: FleetWriteAuthorization): Promise<boolean>;
+  /** Final exact-target authorization; may consume a Mos grant. */
+  assertAuthorized(authorization: FleetWriteAuthorization): Promise<void>;
+}
+
+export interface TmuxFleetRuntimeProviderOptions {
+  transport: FleetRuntimeTransport;
+  readAuthority?: FleetReadAuthority;
+  writeAuthority?: FleetWriteAuthority;
+  sourceLabel?: string;
+  attachmentIdFactory?: () => string;
+  now?: () => Date;
+  attachmentTtlMs?: number;
+}
+
+interface FleetAttachment {
+  sessionId: string;
+  scope: RuntimeScope;
+  expiresAtMs: number;
+}
+
+/** A typed, fail-closed provider error that callers can normalize at the boundary. */
+export class FleetRuntimeProviderError extends Error {
+  constructor(
+    readonly code: FleetRuntimeProviderErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = FleetRuntimeProviderError.name;
+  }
+}
+
+class DenyFleetReadAuthority implements FleetReadAuthority {
+  async canRead(_authorization: FleetReadAuthorization): Promise<boolean> {
+    return false;
+  }
+}
+
+class DenyFleetWriteAuthority implements FleetWriteAuthority {
+  async canWrite(_authorization: FleetWriteAuthorization): Promise<boolean> {
+    return false;
+  }
+
+  async assertAuthorized(_authorization: FleetWriteAuthorization): Promise<void> {
+    throw new FleetRuntimeProviderError(
+      'forbidden',
+      'Fleet writes require an explicit Mos authority decision',
+    );
+  }
+}
+
+/**
+ * A capability-limited provider for rostered local fleet peers. It never
+ * permits raw tmux socket/target selection, interactive control attach, or
+ * direct Tess writes; all side effects pass through exact transport checks.
+ */
+export class TmuxFleetRuntimeProvider implements AgentRuntimeProvider {
+  readonly id = FLEET_PROVIDER_ID;
+  private readonly attachments = new Map<string, FleetAttachment>();
+  private readonly readAuthority: FleetReadAuthority;
+  private readonly writeAuthority: FleetWriteAuthority;
+  private readonly sourceLabel: string;
+  private readonly attachmentIdFactory: () => string;
+  private readonly now: () => Date;
+  private readonly attachmentTtlMs: number;
+
+  constructor(private readonly options: TmuxFleetRuntimeProviderOptions) {
+    this.readAuthority = options.readAuthority ?? new DenyFleetReadAuthority();
+    this.writeAuthority = options.writeAuthority ?? new DenyFleetWriteAuthority();
+    this.sourceLabel = options.sourceLabel ?? 'tess';
+    this.attachmentIdFactory = options.attachmentIdFactory ?? randomUUID;
+    this.now = options.now ?? (() => new Date());
+    this.attachmentTtlMs = options.attachmentTtlMs ?? ATTACHMENT_TTL_MS;
+  }
+
+  async capabilities(_scope: RuntimeScope): Promise<RuntimeCapabilitySet> {
+    return {
+      supported: [
+        'session.list',
+        'session.tree',
+        'session.send',
+        'session.attach',
+        'session.terminate',
+      ],
+    };
+  }
+
+  async health(scope: RuntimeScope): Promise<RuntimeHealth> {
+    const targets = await this.readTargets('runtime.health', scope);
+    return {
+      status: targets.length > 0 ? 'healthy' : 'down',
+      checkedAt: this.now().toISOString(),
+      detail:
+        targets.length > 0
+          ? 'Authorized rostered fleet peers are reachable'
+          : 'No authorized rostered fleet peers are reachable',
+    };
+  }
+
+  async listSessions(scope: RuntimeScope): Promise<RuntimeSession[]> {
+    const targets = await this.readTargets('session.list', scope);
+    return this.toRuntimeSessions(targets);
+  }
+
+  async getSessionTree(scope: RuntimeScope): Promise<RuntimeSessionTree[]> {
+    const targets = await this.readTargets('session.tree', scope);
+    return this.toRuntimeSessions(targets).map(
+      (session): RuntimeSessionTree => ({
+        session,
+        children: [],
+      }),
+    );
+  }
+
+  async *streamSession(
+    _sessionId: string,
+    _cursor: string | undefined,
+    _scope: RuntimeScope,
+  ): AsyncIterable<RuntimeStreamEvent> {
+    throw new FleetRuntimeProviderError(
+      'capability_unsupported',
+      'Fleet session streaming is not supported by the tmux provider',
+    );
+  }
+
+  async sendMessage(
+    sessionId: string,
+    message: RuntimeMessage,
+    scope: RuntimeScope,
+  ): Promise<void> {
+    if (message.content.length === 0) {
+      throw new FleetRuntimeProviderError('invalid_request', 'Fleet message content is required');
+    }
+    await this.assertWritePermitted('session.send', sessionId, scope);
+    const target = await this.options.transport.verifySession(sessionId);
+    await this.assertWriteAuthorized('session.send', target.id, scope);
+    await this.options.transport.sendMessage(target.id, message.content, this.sourceLabel);
+  }
+
+  async attach(
+    sessionId: string,
+    mode: RuntimeAttachMode,
+    scope: RuntimeScope,
+  ): Promise<RuntimeAttachHandle> {
+    if (mode !== 'read') {
+      throw new FleetRuntimeProviderError('forbidden', 'Fleet control attach is not permitted');
+    }
+    await this.assertReadAuthorized('session.attach', sessionId, scope);
+    const target = await this.options.transport.verifySession(sessionId);
+    await this.assertReadAuthorized('session.attach', target.id, scope);
+    const attachmentId = this.attachmentIdFactory();
+    const nowMs = this.now().getTime();
+    this.pruneExpiredAttachments(nowMs);
+    const expiresAtMs = nowMs + this.attachmentTtlMs;
+    this.attachments.set(attachmentId, {
+      sessionId: target.id,
+      scope: snapshotScope(scope),
+      expiresAtMs,
+    });
+    return {
+      attachmentId,
+      sessionId: target.id,
+      mode,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+    };
+  }
+
+  async detach(attachmentId: string, scope: RuntimeScope): Promise<void> {
+    const attachment = this.attachments.get(attachmentId);
+    if (!attachment) {
+      throw new FleetRuntimeProviderError('not_found', 'Fleet attachment is not active');
+    }
+    if (this.now().getTime() >= attachment.expiresAtMs) {
+      this.attachments.delete(attachmentId);
+      throw new FleetRuntimeProviderError('forbidden', 'Fleet attachment has expired');
+    }
+    if (!sameScope(attachment.scope, scope)) {
+      throw new FleetRuntimeProviderError('forbidden', 'Fleet attachment scope does not match');
+    }
+    this.attachments.delete(attachmentId);
+  }
+
+  async terminate(sessionId: string, approvalRef: string, scope: RuntimeScope): Promise<void> {
+    if (approvalRef.trim().length === 0) {
+      throw new FleetRuntimeProviderError(
+        'invalid_request',
+        'Fleet termination approval is required',
+      );
+    }
+    await this.assertWritePermitted('session.terminate', sessionId, scope, approvalRef);
+    const target = await this.options.transport.verifySession(sessionId);
+    await this.assertWriteAuthorized('session.terminate', target.id, scope, approvalRef);
+    await this.options.transport.terminate(target.id);
+  }
+
+  private async readTargets(
+    operation: FleetReadOperation,
+    scope: RuntimeScope,
+  ): Promise<FleetRuntimeTarget[]> {
+    await this.assertReadAuthorized(operation, undefined, scope);
+    const targets = await this.options.transport.listSessions();
+    const authorization = await Promise.all(
+      targets.map(
+        async (target): Promise<boolean> =>
+          this.readAuthority.canRead({ operation, sessionId: target.id, scope }),
+      ),
+    );
+    return targets.filter((_target, index): boolean => authorization[index] === true);
+  }
+
+  private toRuntimeSessions(targets: FleetRuntimeTarget[]): RuntimeSession[] {
+    const timestamp = this.now().toISOString();
+    return targets.map(
+      (target): RuntimeSession => ({
+        id: target.id,
+        providerId: this.id,
+        runtimeId: target.runtimeId,
+        state: 'active',
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      }),
+    );
+  }
+
+  private async assertReadAuthorized(
+    operation: FleetReadOperation,
+    sessionId: string | undefined,
+    scope: RuntimeScope,
+  ): Promise<void> {
+    const allowed = await this.readAuthority.canRead({
+      operation,
+      scope,
+      ...(sessionId ? { sessionId } : {}),
+    });
+    if (!allowed) {
+      throw new FleetRuntimeProviderError('forbidden', 'Fleet read is not authorized');
+    }
+  }
+
+  private pruneExpiredAttachments(nowMs: number): void {
+    for (const [attachmentId, attachment] of this.attachments) {
+      if (attachment.expiresAtMs <= nowMs) {
+        this.attachments.delete(attachmentId);
+      }
+    }
+  }
+
+  private async assertWritePermitted(
+    operation: FleetWriteAuthorization['operation'],
+    sessionId: string,
+    scope: RuntimeScope,
+    approvalRef?: string,
+  ): Promise<void> {
+    const permitted = await this.writeAuthority.canWrite({
+      operation,
+      sessionId,
+      scope,
+      ...(approvalRef ? { approvalRef } : {}),
+    });
+    if (!permitted) {
+      throw new FleetRuntimeProviderError('forbidden', 'Fleet write is not authorized');
+    }
+  }
+
+  private async assertWriteAuthorized(
+    operation: FleetWriteAuthorization['operation'],
+    sessionId: string,
+    scope: RuntimeScope,
+    approvalRef?: string,
+  ): Promise<void> {
+    await this.writeAuthority.assertAuthorized({
+      operation,
+      sessionId,
+      scope,
+      ...(approvalRef ? { approvalRef } : {}),
+    });
+  }
+}
+
+function snapshotScope(scope: RuntimeScope): RuntimeScope {
+  return Object.freeze({
+    actorId: scope.actorId,
+    tenantId: scope.tenantId,
+    channelId: scope.channelId,
+    correlationId: scope.correlationId,
+  });
+}
+
+function sameScope(left: RuntimeScope, right: RuntimeScope): boolean {
+  return (
+    left.actorId === right.actorId &&
+    left.tenantId === right.tenantId &&
+    left.channelId === right.channelId &&
+    left.correlationId === right.correlationId
+  );
+}

packages/db/drizzle/0012_interaction_durable_state.sql

@@ -0,0 +1,71 @@
+CREATE TYPE "public"."interaction_handoff_status" AS ENUM('pending', 'accepted');--> statement-breakpoint
+CREATE TYPE "public"."interaction_inbox_status" AS ENUM('pending', 'processing', 'processed');--> statement-breakpoint
+CREATE TYPE "public"."interaction_outbox_status" AS ENUM('pending', 'processing', 'delivered');--> statement-breakpoint
+CREATE TABLE "interaction_checkpoints" (
+	"session_id" text PRIMARY KEY NOT NULL,
+	"checkpoint_id" text NOT NULL,
+	"cursor" text NOT NULL,
+	"summary" text NOT NULL,
+	"compaction_epoch" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "interaction_checkpoints_checkpoint_id_unique" UNIQUE("checkpoint_id")
+);
+--> statement-breakpoint
+CREATE TABLE "interaction_handoffs" (
+	"handoff_id" text PRIMARY KEY NOT NULL,
+	"session_id" text NOT NULL,
+	"destination" text NOT NULL,
+	"correlation_id" text NOT NULL,
+	"checkpoint_id" text NOT NULL,
+	"status" "interaction_handoff_status" DEFAULT 'pending' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "interaction_inbox" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"session_id" text NOT NULL,
+	"idempotency_key" text NOT NULL,
+	"correlation_id" text NOT NULL,
+	"content" text NOT NULL,
+	"content_digest" text NOT NULL,
+	"status" "interaction_inbox_status" DEFAULT 'pending' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "interaction_outbox" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"session_id" text NOT NULL,
+	"idempotency_key" text NOT NULL,
+	"correlation_id" text NOT NULL,
+	"kind" text NOT NULL,
+	"content" text NOT NULL,
+	"content_digest" text NOT NULL,
+	"status" "interaction_outbox_status" DEFAULT 'pending' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "interaction_sessions" (
+	"id" text PRIMARY KEY NOT NULL,
+	"agent_name" text NOT NULL,
+	"tenant_id" text NOT NULL,
+	"owner_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"runtime_session_id" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "interaction_checkpoints" ADD CONSTRAINT "interaction_checkpoints_session_id_interaction_sessions_id_fk" FOREIGN KEY ("session_id") REFERENCES "public"."interaction_sessions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "interaction_handoffs" ADD CONSTRAINT "interaction_handoffs_session_id_interaction_sessions_id_fk" FOREIGN KEY ("session_id") REFERENCES "public"."interaction_sessions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "interaction_inbox" ADD CONSTRAINT "interaction_inbox_session_id_interaction_sessions_id_fk" FOREIGN KEY ("session_id") REFERENCES "public"."interaction_sessions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "interaction_outbox" ADD CONSTRAINT "interaction_outbox_session_id_interaction_sessions_id_fk" FOREIGN KEY ("session_id") REFERENCES "public"."interaction_sessions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "interaction_sessions" ADD CONSTRAINT "interaction_sessions_owner_id_users_id_fk" FOREIGN KEY ("owner_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "interaction_handoffs_session_status_idx" ON "interaction_handoffs" USING btree ("session_id","status");--> statement-breakpoint
+CREATE UNIQUE INDEX "interaction_inbox_session_idempotency_idx" ON "interaction_inbox" USING btree ("session_id","idempotency_key");--> statement-breakpoint
+CREATE INDEX "interaction_inbox_session_status_created_idx" ON "interaction_inbox" USING btree ("session_id","status","created_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "interaction_outbox_session_idempotency_idx" ON "interaction_outbox" USING btree ("session_id","idempotency_key");--> statement-breakpoint
+CREATE INDEX "interaction_outbox_session_status_created_idx" ON "interaction_outbox" USING btree ("session_id","status","created_at");

packages/db/drizzle/0013_interaction_checkpoint_history.sql

@@ -0,0 +1,5 @@
+ALTER TABLE "interaction_checkpoints" DROP CONSTRAINT "interaction_checkpoints_checkpoint_id_unique";--> statement-breakpoint
+ALTER TABLE "interaction_checkpoints" DROP CONSTRAINT "interaction_checkpoints_pkey";--> statement-breakpoint
+ALTER TABLE "interaction_checkpoints" ADD COLUMN "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL;--> statement-breakpoint
+CREATE UNIQUE INDEX "interaction_checkpoints_session_idempotency_idx" ON "interaction_checkpoints" USING btree ("session_id","checkpoint_id");--> statement-breakpoint
+CREATE INDEX "interaction_checkpoints_session_epoch_idx" ON "interaction_checkpoints" USING btree ("session_id","compaction_epoch");

packages/db/drizzle/0014_interaction_outbox_channel_scope.sql

@@ -0,0 +1,5 @@
+ALTER TABLE "interaction_outbox" ADD COLUMN "channel_id" text;
+--> statement-breakpoint
+UPDATE "interaction_outbox" SET "channel_id" = 'legacy:unknown' WHERE "channel_id" IS NULL;
+--> statement-breakpoint
+ALTER TABLE "interaction_outbox" ALTER COLUMN "channel_id" SET NOT NULL;

packages/db/drizzle/0015_interaction_checkpoint_payload_digest.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "interaction_checkpoints" ADD COLUMN "content_digest" text;--> statement-breakpoint
+UPDATE "interaction_checkpoints" SET "content_digest" = 'legacy' WHERE "content_digest" IS NULL;--> statement-breakpoint
+ALTER TABLE "interaction_checkpoints" ALTER COLUMN "content_digest" SET NOT NULL;

packages/db/drizzle/meta/_journal.json

@@ -85,6 +85,34 @@
       "when": 1782310438919,
       "tag": "0011_bitter_gateway",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1783911983447,
+      "tag": "0012_interaction_durable_state",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1783913232578,
+      "tag": "0013_interaction_checkpoint_history",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1783913398006,
+      "tag": "0014_interaction_outbox_channel_scope",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1783942610000,
+      "tag": "0015_interaction_checkpoint_payload_digest",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -487,6 +487,120 @@ export const agentLogs = pgTable(
   ],
 );
 
+// ─── Tess durable session state ─────────────────────────────────────────────
+// PostgreSQL is canonical for restart-safe Tess session recovery. The state
+// machine lives in @mosaicstack/agent; these records are its durable adapter.
+
+export const interactionInboxStatusEnum = pgEnum('interaction_inbox_status', [
+  'pending',
+  'processing',
+  'processed',
+]);
+export const interactionOutboxStatusEnum = pgEnum('interaction_outbox_status', [
+  'pending',
+  'processing',
+  'delivered',
+]);
+export const interactionHandoffStatusEnum = pgEnum('interaction_handoff_status', [
+  'pending',
+  'accepted',
+]);
+
+export const interactionSessions = pgTable('interaction_sessions', {
+  id: text('id').primaryKey(),
+  agentName: text('agent_name').notNull(),
+  tenantId: text('tenant_id').notNull(),
+  ownerId: text('owner_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  providerId: text('provider_id').notNull(),
+  runtimeSessionId: text('runtime_session_id').notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const interactionInbox = pgTable(
+  'interaction_inbox',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    sessionId: text('session_id')
+      .notNull()
+      .references(() => interactionSessions.id, { onDelete: 'cascade' }),
+    idempotencyKey: text('idempotency_key').notNull(),
+    correlationId: text('correlation_id').notNull(),
+    content: text('content').notNull(),
+    contentDigest: text('content_digest').notNull(),
+    status: interactionInboxStatusEnum('status').notNull().default('pending'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('interaction_inbox_session_idempotency_idx').on(t.sessionId, t.idempotencyKey),
+    index('interaction_inbox_session_status_created_idx').on(t.sessionId, t.status, t.createdAt),
+  ],
+);
+
+export const interactionOutbox = pgTable(
+  'interaction_outbox',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    sessionId: text('session_id')
+      .notNull()
+      .references(() => interactionSessions.id, { onDelete: 'cascade' }),
+    idempotencyKey: text('idempotency_key').notNull(),
+    correlationId: text('correlation_id').notNull(),
+    channelId: text('channel_id').notNull(),
+    kind: text('kind').notNull(),
+    content: text('content').notNull(),
+    contentDigest: text('content_digest').notNull(),
+    status: interactionOutboxStatusEnum('status').notNull().default('pending'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('interaction_outbox_session_idempotency_idx').on(t.sessionId, t.idempotencyKey),
+    index('interaction_outbox_session_status_created_idx').on(t.sessionId, t.status, t.createdAt),
+  ],
+);
+
+export const interactionCheckpoints = pgTable(
+  'interaction_checkpoints',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    sessionId: text('session_id')
+      .notNull()
+      .references(() => interactionSessions.id, { onDelete: 'cascade' }),
+    checkpointId: text('checkpoint_id').notNull(),
+    contentDigest: text('content_digest').notNull(),
+    cursor: text('cursor').notNull(),
+    summary: text('summary').notNull(),
+    compactionEpoch: integer('compaction_epoch').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('interaction_checkpoints_session_idempotency_idx').on(t.sessionId, t.checkpointId),
+    index('interaction_checkpoints_session_epoch_idx').on(t.sessionId, t.compactionEpoch),
+  ],
+);
+
+export const interactionHandoffs = pgTable(
+  'interaction_handoffs',
+  {
+    handoffId: text('handoff_id').primaryKey(),
+    sessionId: text('session_id')
+      .notNull()
+      .references(() => interactionSessions.id, { onDelete: 'cascade' }),
+    destination: text('destination').notNull(),
+    correlationId: text('correlation_id').notNull(),
+    checkpointId: text('checkpoint_id').notNull(),
+    status: interactionHandoffStatusEnum('status').notNull().default('pending'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index('interaction_handoffs_session_status_idx').on(t.sessionId, t.status)],
+);
+
 // ─── Skills ─────────────────────────────────────────────────────────────────
 
 export const skills = pgTable(

packages/log/src/agent-logs.ts

@@ -58,9 +58,28 @@ export function createAgentLogsRepo(db: Db) {
       return rows[0];
     },
 
+    /**
+     * Transition hot logs for one session to warm tier. Session retention is
+     * default-deny: no other session's logs can be changed by this operation.
+     */
+    async promoteSessionToWarm(sessionId: string, olderThan: Date): Promise<number> {
+      const result = await db
+        .update(agentLogs)
+        .set({ tier: 'warm', summarizedAt: new Date() })
+        .where(
+          and(
+            eq(agentLogs.sessionId, sessionId),
+            eq(agentLogs.tier, 'hot'),
+            lt(agentLogs.createdAt, olderThan),
+          ),
+        )
+        .returning();
+      return result.length;
+    },
+
     /**
      * Transition hot logs older than the cutoff to warm tier.
-     * Returns the number of logs transitioned.
+     * Reserved for a separately authorized global retention job.
      */
     async promoteToWarm(olderThan: Date): Promise<number> {
       const result = await db

packages/log/src/index.ts

@@ -10,3 +10,15 @@ export {
   type LogQuery,
 } from './agent-logs.js';
 export { registerLogCommand } from './cli.js';
+export {
+  redactSensitiveContent,
+  type RedactionResult,
+  type SensitiveClassification,
+} from './redaction.js';
+export {
+  createRuntimeAuditLogEntry,
+  type RuntimeAuditEvent,
+  type RuntimeAuditErrorCode,
+  type RuntimeAuditOperation,
+  type RuntimeAuditOutcome,
+} from './runtime-audit.js';

packages/log/src/redaction.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { redactSensitiveContent } from './redaction.js';
+
+describe('redactSensitiveContent', (): void => {
+  it('redacts seeded secret and PII canaries before persistence or egress', (): void => {
+    const result = redactSensitiveContent(
+      'email canary@example.test token=sk_CANARY12345678 phone +1 555 555 1212',
+    );
+    expect(result.content).not.toContain('canary@example.test');
+    expect(result.content).not.toContain('sk_CANARY12345678');
+    expect(result.content).not.toContain('+1 555 555 1212');
+    expect(result.classifications).toEqual(['secret', 'pii']);
+  });
+
+  it('redacts common provider credential formats', (): void => {
+    const result = redactSensitiveContent(
+      'Authorization: Bearer canary.bearer.token jwt eyJcanary.eyJpayload.eyJsignature aws AKIACANARY1234567890',
+    );
+
+    expect(result.content).not.toContain('canary.bearer.token');
+    expect(result.content).not.toContain('eyJcanary.eyJpayload.eyJsignature');
+    expect(result.content).not.toContain('AKIACANARY1234567890');
+    expect(result.classifications).toEqual(['secret']);
+  });
+});

packages/log/src/redaction.ts

@@ -0,0 +1,40 @@
+export type SensitiveClassification = 'secret' | 'pii';
+
+export interface RedactionResult {
+  content: string;
+  classifications: SensitiveClassification[];
+}
+
+const SECRET_PATTERNS: RegExp[] = [
+  /\b(?:sk|ghp|gitea)_[A-Za-z0-9_-]{8,}\b/g,
+  /\b(?:api[_-]?key|token|password|secret)\s*[:=]\s*[^\s,;]+/gi,
+  /\b(?:authorization\s*:\s*)?bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+  /-----BEGIN(?: [A-Z]+)* KEY-----[\s\S]*?-----END(?: [A-Z]+)* KEY-----/g,
+  /https?:\/\/[^\s?#]+[^\s]*[?&](?:token|key|secret|signature|sig)=[^\s&#]+/gi,
+];
+const PII_PATTERNS: RegExp[] = [
+  /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi,
+  /\b\+?\d[\d(). -]{7,}\d\b/g,
+];
+
+export function redactSensitiveContent(content: string): RedactionResult {
+  let redacted = content;
+  const classifications: SensitiveClassification[] = [];
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.test(redacted)) {
+      classifications.push('secret');
+      redacted = redacted.replace(pattern, '[REDACTED_SECRET]');
+    }
+    pattern.lastIndex = 0;
+  }
+  for (const pattern of PII_PATTERNS) {
+    if (pattern.test(redacted)) {
+      classifications.push('pii');
+      redacted = redacted.replace(pattern, '[REDACTED_PII]');
+    }
+    pattern.lastIndex = 0;
+  }
+  return { content: redacted, classifications: [...new Set(classifications)] };
+}