docs(#771): record attestation remediation delivery

CLAUDE.md

@@ -26,9 +26,10 @@ pnpm test             # Vitest (all packages)
 pnpm build            # Build all packages
 
 # Database
-pnpm --filter @mosaicstack/db db:push      # Push schema to PG (dev)
-pnpm --filter @mosaicstack/db db:generate  # Generate migrations
-pnpm --filter @mosaicstack/db db:migrate   # Run migrations
+pnpm --filter @mosaicstack/db db:generate  # Offline migration artifact generation
+mosaic-db-migrator --run                   # Sole PostgreSQL DDL runner
+mosaic-db-migrator --verify                # Verified readiness; no URL/SQL/schema/role argv
+# db:push is disposable-local-only; db:migrate/storage migrate --run must delegate only to the runner.
 
 # Dev
 docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger

README.md

@@ -157,7 +157,10 @@ mosaic storage status
 mosaic storage tier
 mosaic storage export
 mosaic storage import
-mosaic storage migrate
+# `mosaic storage migrate --run` is a schema-wrapper compatibility command only;
+# it delegates solely to mosaic-db-migrator and is not tier data copy.
+# Tier data copy is the KBN-101 secure migrate-tier route after activation, with
+# --target-url-file and --target-attestation-file references only.
 ```
 
 ### Telemetry
@@ -198,8 +201,9 @@ docker compose up -d
 # Install dependencies
 pnpm install
 
-# Run migrations
-pnpm --filter @mosaicstack/db run db:migrate
+# Run PostgreSQL migrations (sole DDL control plane)
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 
 # Start all services in dev mode
 pnpm dev

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

@@ -72,6 +72,7 @@ describe('interaction Discord/CLI durable-session integration', () => {
     process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
       {
         instanceId: 'Nova',
+        agentConfigId: 'agent-config-nova',
         guildId: 'guild-1',
         channelId: 'channel-1',
         pairedUsers: {
@@ -133,6 +134,7 @@ describe('interaction Discord/CLI durable-session integration', () => {
       interactionBindings: [
         {
           instanceId: 'Nova',
+          agentConfigId: 'agent-config-nova',
           guildId: 'guild-1',
           channelId: 'channel-1',
           pairedUsers: {

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

@@ -115,6 +115,18 @@ describe('AgentService owner/tenant scope enforcement', () => {
     ).rejects.toBeInstanceOf(ForbiddenException);
     await service.prompt(CONVERSATION_ID, 'owner prompt', OWNER_SCOPE);
     expect(session.piSession.prompt).toHaveBeenCalledWith('owner prompt');
+    await service.prompt(CONVERSATION_ID, '', OWNER_SCOPE, [
+      {
+        id: 'attachment-001',
+        name: 'diagram.png',
+        url: 'https://cdn.example.test/diagram.png',
+        mimeType: 'image/png',
+      },
+    ]);
+    expect(session.piSession.prompt).toHaveBeenLastCalledWith(
+      '\n\n[Untrusted channel attachments]\n' +
+        '{"id":"attachment-001","name":"diagram.png","mimeType":"image/png","url":"https://cdn.example.test/diagram.png"}',
+    );
 
     await expect(service.destroySession(CONVERSATION_ID, FOREIGN_SCOPE)).rejects.toBeInstanceOf(
       ForbiddenException,

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

@@ -21,6 +21,12 @@ import { LogModule } from '../log/log.module.js';
 import { CommandsModule } from '../commands/commands.module.js';
 import { CommandRuntimeApprovalVerifier } from '../commands/runtime-approval-verifier.js';
 import { GatewayHermesRuntimeTransport } from './hermes-runtime.transport.js';
+import { ConnectorLeaseRepository } from './connector-lease.repository.js';
+import {
+  CONNECTOR_LEASE_POLICY,
+  ConnectorLeaseService,
+  DenyConnectorLeasePolicy,
+} from './connector-lease.service.js';
 import {
   AGENT_RUNTIME_PROVIDER_REGISTRY,
   RUNTIME_APPROVAL_VERIFIER,
@@ -46,6 +52,13 @@ export function createGatewayRuntimeProviderRegistry(): AgentRuntimeProviderRegi
     SkillLoaderService,
     DurableSessionRepository,
     DurableSessionService,
+    ConnectorLeaseRepository,
+    DenyConnectorLeasePolicy,
+    {
+      provide: CONNECTOR_LEASE_POLICY,
+      useExisting: DenyConnectorLeasePolicy,
+    },
+    ConnectorLeaseService,
     {
       provide: AGENT_RUNTIME_PROVIDER_REGISTRY,
       useFactory: createGatewayRuntimeProviderRegistry,
@@ -78,6 +91,7 @@ export function createGatewayRuntimeProviderRegistry(): AgentRuntimeProviderRegi
     SkillLoaderService,
     DurableSessionService,
     RuntimeProviderService,
+    ConnectorLeaseService,
     AGENT_RUNTIME_PROVIDER_REGISTRY,
   ],
 })

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

@@ -15,6 +15,7 @@ import {
   type ToolDefinition,
 } from '@mariozechner/pi-coding-agent';
 import type { Brain } from '@mosaicstack/brain';
+import type { ChannelAttachmentDto } from '@mosaicstack/types';
 import type { Memory, OperatorMemoryPlugin } from '@mosaicstack/memory';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { MEMORY } from '../memory/memory.tokens.js';
@@ -43,6 +44,8 @@ export interface ConversationHistoryMessage {
   role: 'user' | 'assistant' | 'system';
   content: string;
   createdAt: Date;
+  /** Validated, URI-referenced channel attachments preserved on session resume. */
+  attachments?: readonly ChannelAttachmentDto[];
 }
 
 export interface AgentSessionOptions {
@@ -428,7 +431,7 @@ export class AgentService implements OnModuleDestroy {
     const formatMessage = (msg: ConversationHistoryMessage): string => {
       const roleLabel =
         msg.role === 'user' ? 'User' : msg.role === 'assistant' ? 'Assistant' : 'System';
-      return `**${roleLabel}:** ${msg.content}`;
+      return `**${roleLabel}:** ${msg.content}${this.attachmentContext(msg.attachments ?? [])}`;
     };
 
     const formatted = history.map((msg) => formatMessage(msg));
@@ -487,6 +490,21 @@ export class AgentService implements OnModuleDestroy {
     return result;
   }
 
+  private attachmentContext(attachments: readonly ChannelAttachmentDto[]): string {
+    if (attachments.length === 0) return '';
+    return `\n\n[Untrusted channel attachments]\n${attachments
+      .map((attachment: ChannelAttachmentDto): string =>
+        JSON.stringify({
+          id: attachment.id,
+          name: attachment.name,
+          mimeType: attachment.mimeType,
+          url: attachment.url,
+          ...(attachment.sizeBytes !== undefined ? { sizeBytes: attachment.sizeBytes } : {}),
+        }),
+      )
+      .join('\n')}`;
+  }
+
   private resolveModel(options?: AgentSessionOptions) {
     if (!options?.provider && !options?.modelId) {
       return this.providerService.getDefaultModel() ?? null;
@@ -673,7 +691,19 @@ export class AgentService implements OnModuleDestroy {
     session.channels.delete(channel);
   }
 
-  async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void> {
+  async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void>;
+  async prompt(
+    sessionId: string,
+    message: string,
+    scope: ActorTenantScope,
+    attachments: readonly ChannelAttachmentDto[] | undefined,
+  ): Promise<void>;
+  async prompt(
+    sessionId: string,
+    message: string,
+    scope: ActorTenantScope,
+    attachments: readonly ChannelAttachmentDto[] = [],
+  ): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
@@ -681,12 +711,16 @@ export class AgentService implements OnModuleDestroy {
     this.assertSessionScope(session, scope);
     session.promptCount += 1;
 
+    // Channel attachments are untrusted URI references. Preserve exact,
+    // authenticated metadata for the agent without treating it as authority.
+    const attachmentContext = this.attachmentContext(attachments);
+
     // Prepend session-scoped system override if present (renew TTL on each turn)
-    let effectiveMessage = message;
+    let effectiveMessage = `${message}${attachmentContext}`;
     if (this.systemOverride) {
       const override = await this.systemOverride.get(sessionId, scope);
       if (override) {
-        effectiveMessage = `[System Override]\n${override}\n\n${message}`;
+        effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
         await this.systemOverride.renew(sessionId, scope);
         this.logger.debug(`Applied system override for session ${sessionId}`);
       }

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

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

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

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

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

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

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

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

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

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

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

@@ -115,6 +115,38 @@ describe('Hermes runtime provider reachability', (): void => {
     await app?.close();
   });
 
+  it('returns gateway denial responses from the actual guarded interaction routes', async (): Promise<void> => {
+    if (!app) throw new Error('Nest application did not initialize');
+
+    const attachDenied = await app.inject({
+      method: 'POST',
+      url: '/api/interaction/Nova/sessions/session-1/attach',
+      headers: { 'x-correlation-id': 'correlation-1' },
+      payload: { mode: 'read' },
+    });
+    expect(attachDenied.statusCode).toBe(401);
+
+    const sendDenied = await app.inject({
+      method: 'POST',
+      url: '/api/interaction/Nova/sessions/session-1/send',
+      headers: { cookie: 'session=trusted', 'x-correlation-id': 'correlation-1' },
+      payload: {},
+    });
+    expect(sendDenied.statusCode).toBe(403);
+    expect(sendDenied.json()).toMatchObject({
+      message: 'Content and idempotency key are required',
+    });
+
+    const stopDenied = await app.inject({
+      method: 'POST',
+      url: '/api/interaction/Nova/sessions/session-1/stop',
+      headers: { cookie: 'session=trusted', 'x-correlation-id': 'correlation-1' },
+      payload: {},
+    });
+    expect(stopDenied.statusCode).toBe(403);
+    expect(stopDenied.json()).toMatchObject({ message: 'Exact-action approval is required' });
+  });
+
   it('requires authentication and reaches the Hermes provider registered by AgentModule', async (): Promise<void> => {
     if (!app) throw new Error('Nest application did not initialize');
     const registry = app.get(AGENT_RUNTIME_PROVIDER_REGISTRY);

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

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

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

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

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

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

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

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

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

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

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

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

docs/MISSION-MANIFEST.md

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

docs/PERFORMANCE.md

@@ -152,11 +152,10 @@ for any `<Image>` components added in the future.
 ## How to Apply
 
 ```bash
-# Run the DB migration (requires a live DB)
-pnpm --filter @mosaicstack/db exec drizzle-kit migrate
-
-# Or, in Docker/Swarm — migrations run automatically on gateway startup
-# via runMigrations() in packages/db/src/migrate.ts
+# PostgreSQL migration is a dedicated pre-runtime phase.
+# Deployment injects migration-only credentials/TLS material; Gateway startup only verifies readiness.
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 ```
 
 ---

docs/PRD.md

@@ -79,6 +79,81 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 
 ---
 
+## Fleet Declarative Configuration Management Workstream (FCM, #758)
+
+### Problem and objective
+
+The local Mosaic fleet has a roster, generated agent environment files, user-systemd units, tmux
+sessions, heartbeat files, examples, profiles, and separate gateway-backed agent records. These
+planes have drifted and are not one safe operator lifecycle. The objective is one **local fleet
+roster** as the desired-state SSOT, with generated environment, systemd, tmux, and heartbeat
+artifacts as rebuildable projections; it does not merge the local fleet control plane with the
+gateway-backed agent catalog.
+
+### Normative requirements
+
+| ID           | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FCM-REQ-01` | The roster SHALL be the sole writable desired-state source for local fleet membership, launch policy, and persisted lifecycle target. Generated environment files, systemd enablement, tmux sessions, and heartbeat state SHALL be non-authoritative projections.                                                                                                                                                                                                         |
+| `FCM-REQ-02` | The implementation SHALL provide one executable structural contract for YAML/JSON input and one shared semantic validator. Roster load, profile validation, provision, migration, and apply SHALL reuse the existing baseline-plus-`roles.local` profile/persona resolver; a parallel role resolver is forbidden.                                                                                                                                                         |
+| `FCM-REQ-03` | The local fleet CLI SHALL expose documented programmatic validate, show, plan, apply/reconcile, create, inspect, update, delete, start, stop, restart, status, verify, and doctor operations with stable JSON and exit-code behavior. Existing `fleet add/remove` compatibility aliases may remain during the stated deprecation window.                                                                                                                                  |
+| `FCM-REQ-04` | A fresh create SHALL persist `enabled:true` and `desired_state:stopped` unless an explicit persisted start is requested. The model SHALL distinguish enabled state, persisted desired state, and observed state. Migration, apply, reboot, and rollback SHALL not start an agent that was observed stopped before cutover.                                                                                                                                                |
+| `FCM-REQ-05` | The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash.                     |
+| `FCM-REQ-06` | Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name.                                                                                                                                    |
+| `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities. |
+| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note.                                                |
+| `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model.                                                                                                                                                                                              |
+| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence.                                                                                                  |
+
+### Acceptance criteria
+
+1. `AC-FCM-01`: A valid local v2 roster can be parsed from YAML or JSON, validated structurally and semantically through the shared resolver, and rendered canonically; invalid fields, duplicate names, unresolved classes, unsupported runtime/model combinations, socket ambiguity, and incompatible options fail closed.
+2. `AC-FCM-02`: `plan` reports deterministic desired-versus-observed differences for roster, generated environment, systemd enablement, tmux/session, heartbeat, installed-asset revision, and provable orphans without mutation; `apply --check` reports drift without mutation.
+3. `AC-FCM-03`: Local create/update/delete is generation-guarded, atomic, idempotent, and safe by default; it permits supported runtime/model/harness/effort/workdir/role changes without direct editing of generated environment files and does not start a newly created agent unless explicitly persisted.
+4. `AC-FCM-04`: The generated-env/local-override launch chain rejects generated-key shadowing, arbitrary command override, unknown keys, shell evaluation, and sensitive-value diagnostics before any agent starts; known-safe legacy input is regenerated or strictly relocated, and forbidden input is quarantined.
+5. `AC-FCM-05`: Local lifecycle reconciliation implements the persisted/transient start-stop rules, exact default/named tmux socket targeting, systemd/tmux status, stale generated state, unmanaged-session reporting, and rollback without surprise restarts or fuzzy destructive targeting.
+6. `AC-FCM-06`: A v1 roster migration previews field-by-field disposition, preserves observed stopped/running state, inventories rather than reconciles remote/schema-only entries, supports a canary and rollback, and classifies every shipped example, profile, and service preset according to the M0 inventory.
+7. `AC-FCM-07`: Required role authority is validated: validator certificate is consumed but does not merge, merge-gate is the sole merge authority, team-leader leases do not change roster/credentials/authority, and interaction/Tess cannot claim orchestration or merge powers.
+8. `AC-FCM-08`: Documentation, examples, migration, troubleshooting, operational recovery, package/update asset drift, schema/example/profile validation, independent code/security review, validator certificate, and terminal-green CI are complete before #758 closes.
+
+### M0 implementation gate
+
+No source, schema, role, example, profile, systemd, or live-fleet change is authorized before M0
+lands. M0 consists only of these normative requirements, the complete task DAG, the scoped
+documentation IA checklist, and the legacy example/profile disposition inventory. Subsequent cards
+are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
+
+---
+
+## KBN-101 Database Runtime/Migration Role Split (#771)
+
+### Problem and objective
+
+PostgreSQL Gateway/storage currently uses one `DATABASE_URL` for runtime queries and migrations. That makes the deployed application identity an owner and prevents certification that KBN immutable event, artifact, checkpoint, and evidence relations reject runtime `UPDATE`/`DELETE`. KBN-101 freezes a least-privilege runtime/migration split before KBN-100 schema work.
+
+### Normative requirements
+
+1. `K101-REQ-01`: `DATABASE_URL` SHALL be the non-owner PostgreSQL runtime connection and `DATABASE_MIGRATION_URL` SHALL be the migration-only owner/migrator connection. They are required respectively for runtime and the dedicated `mosaic-db-migrator --run|--verify` phase in `standalone`/`federated`; local PGlite is the explicit exception. The published `@mosaicstack/db` bin maps exactly `mosaic-db-migrator` to `./dist/cli.js`, its image entrypoint is exactly `mosaic-db-migrator`, accepts no URL/SQL/schema/role argv, and returns stable sanitized exits. Every current/future PostgreSQL DDL entrypoint SHALL route to that runner or be denied, and SHALL reject `DATABASE_URL`-only execution before connection/DDL. Data migration may connect only after the runner prepares and verifies the PostgreSQL target, through dedicated non-DDL `mosaic_data_importer` and exactly `--target-url-file /run/secrets/mosaic_migrate_target_url` plus `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. The trusted runner verifies TLS/identity/manifest, reads the exact importer URL file only after strict safety checks, and signs a credential-free JCS/Ed25519 attestation using its runner-only fixed root-owned private-key file; no signing key reaches importer/runtime. The artifact binds secret version and SHA-256 of exact high-entropy credential-file bytes, canonical TLS host/port/database, CA/SPKI, PostgreSQL system identifier/database OID, importer role, manifest/schema fingerprints, producer invocation/build/image digest, issued/expires/nonce, and correlation. Before target connection the importer validates files/signature/key/expiry/replay/secret/digest/bindings; after verified TLS and before DML it validates server/database/role/CA/schema identity, with same-fd/in-memory-byte TOCTOU protection, rotation/revocation, atomic artifacts, and sanitized errors. Raw `--target-url`, `DATABASE_URL` fallback, runtime-owner use, missing/unsafe/substituted files, stale/replayed/tampered/wrong-key attestation, wrong binding, and DDL attempt fail before target connection/DDL; post-connect mismatch closes with zero DML/DDL. A reviewed finite classifier inventories executable current source/scripts/package bins, operator docs, deploy manifests, and exact normative contracts by path; active secure records pin both options/files, producer/key/bindings/tests, while normative contracts cannot mask instructions. Unknown active commands, duplicate-owner, ownerless, missing-path, and historical/status-only masking hits fail. `db:push` is forbidden outside an explicitly disposable local developer database and cannot accept a production-like URL.
+2. `K101-REQ-02`: Gateway runtime/replicas SHALL not execute migrations or DDL. The runner SHALL hold one `max:1` session and fixed two-int advisory namespace `1297044289` (`MOSA`), `1262636593` (`KBN1`) across preflight, reconciliation, migration, verification, and release. It SHALL compare the versioned canonical manifest v1 tuple (journal logical index/tag plus exact SQL-byte SHA-256) to the complete observed ledger mapping; count/set-only, timestamps, and physical insertion order are non-normative and insufficient.
+3. `K101-REQ-03`: PostgreSQL SHALL separate non-login platform database owner, non-login schema owner, dedicated `NOLOGIN SUPERUSER` `mosaic_extension_owner`, login migrator, dedicated login non-DDL data importer, non-login runtime capability, and login runtime roles. For PostgreSQL 17 + pgvector 0.8.2, `vector` is untrusted (`trusted` is absent and `relocatable=true`): only an externally controlled audited platform-bootstrap superuser session may `SET ROLE mosaic_extension_owner` for CREATE/UPDATE/SET SCHEMA, then `RESET ROLE`; the role has `rolcanlogin=false`, `rolsuper=true`, zero members, no runtime credential/Vault secret, and is never provided to app containers. It owns `mosaic_extensions`, fresh `vector`, and owner-bearing extension members, while `mosaic_schema_owner` receives only `USAGE` for type resolution and never ownership/`CREATE`/`ALTER`/`DROP`/member-change/default-privilege authority there. Superuser cannot be constrained by `GRANT`/`REVOKE`; this is identity/non-login/no-membership/external-control/audit isolation, not a false least-privilege claim. Extension operations require control-plane change, independent review, backup/rollback, maintenance window, and audit evidence. Managed targets that cannot establish this exact role are ineligible until an independently approved versioned provider-owned extension-owner profile exists; app/migrator ownership is never silently retained. Existing approved-owner extension relocation validates exact `pg_namespace.nspowner`, `pg_extension.extowner`, member ownership/schema/version, while legacy runtime-owned extension fails closed to a controlled shadow-database migration—never unsupported ownership alteration, catalog mutation, ownership adoption, or `DROP CASCADE`. Runtime, migrator, schema owner, importer, and all service roles must fail `SET ROLE`, catalog/direct `ALTER`/`UPDATE`/`DROP`/membership-change denial, role ownership, superuser/role-creation/schema-creation/TEMPORARY, unsafe membership, untrusted search path, missing grants, unauthenticated TLS, and immutable privilege drift checks. Application schema is fixed `mosaic` with exact `pg_catalog,mosaic` session path; historical public migrations remain byte-immutable legacy bootstrap only, every future Drizzle application declaration targets `mosaic`, and `vector` is explicitly qualified from non-writable `mosaic_extensions`. No config-derived SQL identifier is permitted.
+4. `K101-REQ-04`: `mosaicstack/stack` KBN-101-00 SHALL exclusively own `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, and bootstrap tests; KBN-101-05 SHALL exclusively own `tools/db/render-postgres-secrets.ts`, its tests, and current Compose/Portainer/two-gateway deployment declarations, consuming the versioned bootstrap interface without overlap. Environment IaC/Vault is named input and Mosaic deployment control plane/Jason is activation authority. Distinct runtime/migrator URL, CA, Gateway leaf, and PostgreSQL server key/certificate secrets are provisioned before a production-like database starts; runtime and migrator require mounted CA plus `sslmode=verify-full`. Exact UID/GID/mode/rendering, service-DNS SANs, Vault/compose/Swarm consumer isolation, two-gateway pair ordering, server activation, pre-enforcement legacy-client drain and `hostssl` zero-plaintext-session proof, fresh/existing transition, CA-overlap rotation, TLS-only rollback, and standalone/federated/Swarm/two-gateway positive/negative TLS evidence are required. No application-generated production certificate or plaintext bootstrap exception is permitted.
+5. `K101-REQ-05`: KBN immutable relations SHALL permit the real runtime role INSERT/SELECT only and deny UPDATE/DELETE; parent retention remains RESTRICT/no-cascade. Role/password/Vault creation is external platform control, never application migration/source.
+6. `K101-REQ-06`: N-1 single-URL compatibility, rollout/rollback, Vault ownership/rotation/redaction, CI, installer, compose/Portainer, observability, and deployment handoffs SHALL be separately bounded one-card/one-PR work. Prepared slices remain inactive while current owner-runtime deployments stay N-1; Mosaic control plane/Jason alone authorizes one final atomic activation or rollback, with no force-on-red/bypass. KBN-101 planning itself SHALL not mutate production.
+7. `K101-REQ-07`: KBN-100 SHALL begin only after the KBN-101 foundation role/schema-boundary certificate; it SHALL rebase on that main head, restore generated Drizzle declaration/snapshot/journal consistency, and bound procedural immutable-table grant/trigger/backfill additions to its schema slice. KBN-101 real deployed-role immutable-operation certification SHALL complete after KBN-100 creates those relations and before KBN-105.
+
+### Acceptance criteria
+
+1. `AC-K101-01`: DTO/command-matrix tests prove required modes, PGlite exception, `mosaic-db-migrator --help|--run|--verify`/stable exits/argv refusal, public-import negative, every finite classified DDL/static-bypass inventory path and both harness pairs reject `DATABASE_URL`-only before connection/DDL, no migration-to-runtime fallback, and `db:push` refusal outside an allowlisted disposable DB. The active `docs/guides/migrate-tier.md` route is inventoried to KBN-101-07 and proves runner-produced `--target-url-file /run/secrets/mosaic_migrate_target_url` plus `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`; runner-only signing/private-key isolation; JCS/Ed25519 signature/key rotation/revocation, atomic artifact, expiry/replay, secret-version/digest, canonical TLS/CA/server/database/role/manifest/schema bindings, same-fd TOCTOU defense, dedicated non-DDL importer, and exact no-connection versus zero-DML rejection for missing/wrong/stale/replayed/tampered/wrong-key/substituted/binding-mismatched inputs. The full current non-normative docs inventory—including user guide and federation historical task status—has an exact safe disposition, and normative-contract classification cannot hide an instruction.
+2. `AC-K101-02`: Fixed namespace lock contention/crash/readiness/non-interference and exact manifest-v1 reconciliation tests prove no replica race/runtime auto-migration and fail closed on every missing/unknown/duplicate/ambiguous/corrupt/stale ledger state.
+3. `AC-K101-03`: Actual PostgreSQL 17 + pgvector 0.8.2 control-file, catalog, Drizzle-generation, vector-query/operator, fresh/approved-owner/legacy-shadow/partial/resume/rollback/N-1, and real deployed-role tests prove `trusted` absent/untrusted plus relocatability, external-superuser `SET ROLE` create/update/`RESET ROLE` audit, exact `rolcanlogin=false`/`rolsuper=true`/zero-membership/no-runtime-secret state, platform/schema/extension-owner/migrator/importer/runtime separation, `pg_extension.extowner` plus owner-bearing extension-member/schema/version assertions, and runtime/migrator/schema-owner/importer/all-service-role `SET ROLE`/ALTER/DROP/member-update denial. They also prove `pg_catalog,mosaic` per-session pool safety, `mosaic_extensions` qualification, identifier injection denial, ownership/membership/ledger-read/TEMP/default grants, and unsafe privilege denial.
+4. `AC-K101-04`: Disposable standalone, federated/Swarm, and two-gateway verified-TLS positives plus for both pairs missing CA/wrong CA/wrong SAN/sslmode downgrade, server/Gateway key mode, UID/GID, secret-consumer isolation, and legacy-drain/`hostssl` negatives prove server bootstrap, ordering, and readiness; PGlite is expressly excluded from this PostgreSQL evidence.
+5. `AC-K101-05`: Real runtime-role evidence proves INSERT/SELECT succeeds and UPDATE/DELETE fails for every frozen immutable KBN relation.
+6. `AC-K101-06`: N-1/atomic activation/rollback, Vault/CA-overlap rotation/redaction, health/operator behavior, CI/deployment handoff, independent exact-head security review, and terminal-green CI evidence the foundation before KBN-100; after KBN-100, the real deployed-role immutable-operation certificate and Ultron approval release KBN-105.
+
+**Normative implementation contract:** [`docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md`](./native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md). `ASSUMPTION:` existing `standalone` and `federated` are all PostgreSQL production-like modes; any new PostgreSQL tier inherits these requirements until an explicit versioned amendment.
+
+---
+
 ## Tess Interaction Agent Workstream (TESS)
 
 ### Problem and Objective
@@ -175,6 +250,100 @@ Delivery uses five gated milestones: runtime contracts/security; Pi service/stat
 
 ---
 
+## Official Channel Plugin Workstream (#756)
+
+### Problem and Objective
+
+The Discord plugin currently couples Discord event handling, gateway bridging, and reply routing in one implementation and activates only on mentions. Mosaic needs an official channel adapter that behaves the same no matter whether the bound logical agent currently runs through Claude, Codex, Pi, OpenCode, or a future harness. The Discord connection and conversation address must remain stable while the gateway changes the runtime provider behind that logical session.
+
+The objective is to make Discord the first implementation of a transport-neutral official channel contract, with explicit authorization and deterministic channel/thread routing that future Matrix, Slack, and other adapters can share.
+
+### Scope
+
+#### In Scope
+
+1. `CHN-001`: Transport-neutral channel adapter, route, message, attachment, authorization-principal, response-target, and health contracts in `@mosaicstack/types`, including trusted per-binding logical-agent configuration selection.
+2. `CHN-002`: Stable channel conversation addresses based on logical agent plus channel/thread identity; harness, model, and runtime-provider IDs are forbidden from channel session keys.
+3. `DSC-001`: An authorized untagged message in a configured agent-bound channel routes to the agent and receives its response in that channel.
+4. `DSC-002`: A bot mention in a configured parent channel creates a Discord thread, or reuses the thread already attached to that same native message; the mentioned turn and subsequent thread turns route and respond in that thread.
+5. `DSC-003`: A message already inside an authorized thread inherits authorization from its configured parent and never attempts a nested thread.
+6. `DSC-004`: Guild, parent channel, user, pairing, and role authorization remains default-deny before thread creation or gateway dispatch.
+7. `DSC-005`: Discord service authentication, HMAC envelope integrity, replay protection, attachments, approvals, response chunking, and correlation behavior remain intact.
+8. `DSC-006`: The Discord adapter exposes lifecycle and health behavior through the shared channel contract without importing a harness SDK.
+
+#### Out of Scope
+
+1. The logical-agent lease, fencing epoch, execution grant, checkpoint, or cross-harness takeover implementation tracked by #754/#755.
+2. Dynamic Discord authorization administration in the web UI.
+3. Multi-guild tenant isolation, DMs, slash commands, voice, reactions, or production bot deployment.
+4. Implementing Matrix or Slack adapters in this slice.
+
+### Non-Functional Requirements
+
+1. **Security:** no thread or dispatch side effect occurs until guild, parent channel, user, pairing, role, and bounded per-user/channel rate checks pass; attachment metadata is shape- and size-bounded; credentials never enter source, messages, session keys, or logs.
+2. **Portability:** channel contracts and stable conversation IDs contain no Claude, Codex, Pi, OpenCode, model, process, or provider-specific field; each configuration-owned binding selects its trusted logical agent without changing the channel identity.
+3. **Reliability:** repeated messages for one channel/thread resolve the same conversation handle; reconnecting the adapter does not require a harness-specific rebinding.
+4. **Maintainability:** Discord-specific API translation stays in the Discord package; gateway and future adapters depend on transport-neutral contracts.
+5. **Observability:** thread creation or routing failure is reported without message content or credential material.
+
+### Acceptance Criteria
+
+1. `AC-CHN-01`: Contract and behavior tests prove the plugin route contains only logical agent plus channel/thread identity and produces the same stable conversation handle regardless of underlying harness selection.
+2. `AC-CHN-02`: A mentioned authorized parent-channel message creates a thread (or reuses its already-attached thread), dispatches to the thread conversation, and targets the response to that thread.
+3. `AC-CHN-03`: An untagged authorized parent-channel message dispatches to the parent conversation and targets the response to the parent channel.
+4. `AC-CHN-04`: Untagged follow-ups inside an authorized thread dispatch and respond in that same thread without creating a nested thread.
+5. `AC-CHN-05`: Unauthorized guilds, channels, users, unpaired users, insufficient roles, and rate-limited senders produce no thread and no gateway dispatch.
+6. `AC-CHN-06`: Shared channel contracts are exported from `@mosaicstack/types`, Discord implements the lifecycle/health seam, and no harness SDK is imported by the plugin.
+7. `AC-CHN-07`: Focused routing/auth tests, package tests, typecheck, lint, formatting, coverage, independent code/security review, and terminal-green CI pass.
+
+### Constraints, Risks, and Assumptions
+
+- Dependency: Mosaic gateway remains the policy, durable-session, audit, and runtime-provider boundary.
+- Constraint: This work must not modify orchestrator-to-Pi migration or #754/#755 lease/fencing files.
+- Risk: accepting untagged messages could create noisy or unintended agent input. Mitigation: only explicitly configured channels and paired, role-authorized users are accepted, with bounded per-user/channel message and thread rates.
+- Risk: Discord thread creation can fail because of channel permissions, archived state, or API rate limits. Mitigation: fail without dispatching a turn whose response destination cannot be honored, and emit sanitized diagnostics.
+- `ASSUMPTION:` Configured channels are dedicated agent interaction surfaces, so authorized untagged human messages are intentional agent input.
+- `ASSUMPTION:` Mention in a parent channel selects a public thread; messages already in a thread remain there because Discord has no nested threads.
+- `ASSUMPTION:` One Discord bot may serve multiple configuration-owned logical-agent bindings.
+- `ASSUMPTION:` Static allowlists and paired-user roles are the authorization administration surface for this slice.
+
+### Testing and Delivery Intent
+
+Use TDD for remote-ingress routing and permission boundaries. Required evidence includes parent-channel mention, untagged parent message, existing-thread follow-up, existing-thread mention, thread reuse, unauthorized side-effect denial, stable harness-neutral conversation identity, adapter health, and regression coverage for signed envelopes and approvals. Deliver through issue #756, a reviewed squash PR to `main`, terminal-green CI, and issue closure.
+
+---
+
+## Mos Runtime Portability Workstream (MOS-PORT)
+
+### Problem and Objective
+
+Mos is currently identified partly by a harness-native session and communication process. Replacement/rebinding exists, but no gateway-enforced logical identity or fencing prevents a stale harness from continuing to reply or execute effects after takeover.
+
+The objective is to make Mos a server-derived logical Mosaic identity whose authority can move safely among runtime connectors. The gateway owns identity, lease, policy, and audit; harnesses remain replaceable adapters.
+
+### M1 Requirements
+
+1. `MOS-PORT-ID-001`: Define a normalized logical-agent identity independent of Claude Code, Pi, Codex, tmux, Matrix, and provider-native session IDs.
+2. `MOS-PORT-LEASE-001`: Persist one exclusive connector lease per tenant/logical-agent/binding with CAS acquisition, monotonic fencing epoch, TTL, heartbeat, explicit release, and takeover.
+3. `MOS-PORT-FENCE-001`: Bind every connector dispatch/execution grant to the current server-derived tenant, logical identity, binding, connector, scopes, expiry, and lease epoch.
+4. `MOS-PORT-FENCE-002`: Reject and audit stale, expired, forged, cross-tenant, cross-binding, and unauthorized grants before connector, channel, provider, or tool side effects.
+5. `MOS-PORT-OBS-001`: Emit credential-safe correlation/audit events for lease acquire, renew, takeover, reject, release, and expiry.
+6. `MOS-PORT-ARCH-001`: Runtime/provider adapters consume normalized lease context without adding harness-native schemas to Mosaic core.
+
+### M1 Acceptance Criteria
+
+1. `AC-MOS-PORT-01`: Two contenders for one binding cannot simultaneously hold current authority under concurrency.
+2. `AC-MOS-PORT-02`: Successful takeover increments the fencing epoch and every operation from the old epoch fails closed before side effects.
+3. `AC-MOS-PORT-03`: Gateway/database restart preserves lease and epoch state; expired leases can be recovered only through the authorized takeover path.
+4. `AC-MOS-PORT-04`: Cross-tenant, cross-agent, cross-binding, forged, and expired lease/grant cases are denied and audited.
+5. `AC-MOS-PORT-05`: Unit, migration, repository close/reopen, concurrency, abuse, gateway integration, independent security review, CI, and documentation gates pass.
+
+### Deferred to Later #754 Milestones
+
+Canonical checkpoint/handoff payloads, exactly-once connector receipts, concrete Claude/Pi/Codex adapters, channel cutover, and full cross-harness failover/rollback E2E are explicitly out of M1 scope.
+
+---
+
 ## Architecture
 
 ### High-Level System Diagram
@@ -529,7 +698,8 @@ Discord remote control channel. Architecture inspired by OpenClaw (https://githu
 - Single-guild binding only (v0.1.0) — prevents data leaks between servers
 - Receives Discord messages, dispatches through gateway routing
 - Streams agent responses back to Discord (chunked for 2000-char limit)
-- Supports mention-based activation, thread management for multi-turn
+- Routes authorized untagged messages in-channel; mentions create threads (or reuse the same message's attached thread) for multi-turn topics
+- Uses stable logical-agent/channel conversation addresses independent of the active harness/provider
 - Bot pairing and permission management (Discord user → Mosaic user mapping)
 - DM support for private conversations
 
@@ -702,10 +872,12 @@ Telegram remote control channel.
 
 ### FR-9: Remote Control — Discord
 
-- Discord bot that connects to the gateway
-- Mention-based activation in channels
+- Discord bot that connects to the gateway through a transport-neutral channel adapter contract
+- Authorized messages in configured agent-bound channels work without a mention and respond in-channel
+- Mentions in parent channels create threads, or reuse a thread already attached to that same native message, for multi-turn conversations
+- Messages already in a thread remain there without requiring repeated mentions
+- Stable logical-agent/channel conversation identity survives underlying harness/provider changes
 - DM support for private conversations
-- Thread creation for multi-turn conversations
 - Chunked message delivery (Discord 2000-char limit)
 - Bot configuration via web dashboard
 - Permission management (which Discord users/roles can interact)
@@ -889,10 +1061,13 @@ Telegram remote control channel.
 
 ### AC-3: Discord Remote Control
 
-- [ ] Discord bot connects and responds to mentions
-- [ ] Messages route through gateway to agent pool
+- [ ] Discord bot connects through the harness-neutral channel contract
+- [ ] Authorized untagged channel messages route through the gateway and respond in-channel
+- [ ] Mentioned parent-channel messages create a thread (or reuse their already-attached thread) and respond there
+- [ ] Existing-thread follow-ups stay in the thread without repeated mentions
+- [ ] Channel/session identity remains stable while the underlying harness/provider changes
 - [ ] Responses stream back to Discord (chunked)
-- [ ] Thread creation for multi-turn conversations
+- [ ] Unauthorized guilds, channels, users, pairings, and roles create no thread and dispatch no message
 
 ### AC-4: Gateway Orchestration
 
@@ -1091,7 +1266,7 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
 
 6. ASSUMPTION: **Log summarization uses Haiku-tier LLM by default, configurable.** Haiku is well-suited for summarization (compression, not generation — source material is in context). Guardrails: structured output via Zod schema (force extraction of decisions/tools/outcomes/errors as discrete fields), chunked per-session processing (no bulk conflation), extraction-focused prompts. Raw logs stay in hot tier (7 days) as safety net. Users can override the summarization model via routing engine config if they want higher fidelity. Rationale: Haiku is 10-20x cheaper than Sonnet; log summarization runs on schedule against large volumes where cost matters.
 
-7. ASSUMPTION: **Discord plugin starts minimal and single-guild only** — DM support, mention-based channel activation, thread management, chunked responses. Single guild binding to prevent data leaks between servers. Advanced features (voice, components, slash commands, multi-guild) are post-beta. Rationale: Proven pattern from OpenClaw; ship core interaction first; data isolation is non-negotiable.
+7. ASSUMPTION: **Discord plugin starts minimal and single-guild only** — explicitly configured agent-bound channels accept authorized untagged messages in-channel, while mentions create threads or reuse a thread already attached to that same native message; responses are chunked. Single guild binding prevents data leaks between servers. DM support, voice, components, slash commands, and multi-guild operation are post-beta. Rationale: Ship the requested core interaction model while preserving default-deny data isolation.
 
 8. ASSUMPTION: **Telegram plugin is lower priority than Discord** and may ship as v0.0.7 or later if Discord takes longer than expected. Rationale: Jason indicated Discord as the high-priority remote channel.
 

docs/SITEMAP.md

@@ -0,0 +1,63 @@
+# Documentation Sitemap
+
+## Official channel plugins
+
+- [Channel protocol architecture](architecture/channel-protocol.md) — shared lifecycle, message, stable-route, authorization, and response-target contracts.
+- [Discord administrator configuration](guides/admin-guide.md#discord-ingress-security) — secrets, allowlists, bindings, role policy, and thread permissions.
+- [Discord user workflow](tess/USER-GUIDE.md#discord-conversations) — in-channel messages, mention-created threads, and runtime-transparent continuity.
+- [Channel plugin authoring](tess/PLUGIN-GUIDE.md#official-channel-adapter-contract) — requirements for future Matrix, Slack, and other official adapters.
+- [Discord package guide](../plugins/discord/README.md) — package behavior, configuration shape, and development commands.
+
+## Native Kanban and canonical task SOT
+
+- [Canonical requirements](requirements/native-kanban-sot.md) — ratified P0–P3 requirements and acceptance criteria.
+- [Workstream index](native-kanban-sot/INDEX.md) — artifact map, lane partition, and delivery order.
+- [Mission manifest](native-kanban-sot/MISSION-MANIFEST.md) — scope, authority, invariants, and gate model.
+- [Task decomposition](native-kanban-sot/TASKS.md) — dependency-ordered implementation slices and ownership boundaries.
+- [KBN-101 database role split](native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md) — rc.11 runner-signed target-bound importer attestation, complete operator-route inventory, PostgreSQL-valid pgvector owner exception, disjoint card manifests, classifier, runner, verified TLS, activation, and certification prerequisite.
+- [Federated tier data migration](guides/migrate-tier.md) — active KBN-101-07 operator route: runner-produced target attestation, dedicated non-DDL importer, and paired credential-/attestation-file references only.
+- [Frozen shared contract](native-kanban-sot/SHARED-CONTRACT.md) — schema, API, Coordinator, health, recovery, and migration contracts.
+- [KBN-101 exact-head security review](reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) — retained prior REQUEST CHANGES evidence for `da742ca`; rc.11 awaits independent exact-head re-review after closing the target-attestation and operator-inventory HIGH findings.
+- [Initial independent review](reports/native-kanban-sot/canon-initial-review-no-go.md) — KCR-001–016 findings that blocked the first draft.
+- [Final independent re-review](reports/native-kanban-sot/canon-final-rereview-go.md) — closure evidence and GO verdict.
+- [Ultron final gate](reports/native-kanban-sot/ultron-final-go.md) — final requirements, authority, schema, migration, recovery, and evidence review.
+
+## Tess interaction agent
+
+### Operator guides
+
+- [User guide](tess/USER-GUIDE.md) — authorized session, attach, send, stop, and handoff workflows.
+- [Admin guide](tess/ADMIN-GUIDE.md) — deployment configuration, policy, and approval controls.
+- [Developer guide](tess/DEVELOPER-GUIDE.md) — provider contracts, scope boundaries, and test workflow.
+- [Plugin guide](tess/PLUGIN-GUIDE.md) — adapter, redaction, and identity-as-data requirements.
+- [Operations guide](tess/OPERATIONS-GUIDE.md) — readiness, recovery, and incident-safe procedures.
+
+### Architecture and security
+
+- [Architecture](tess/ARCHITECTURE.md)
+- [Threat model](tess/THREAT-MODEL.md)
+- [Mos coordination boundary](tess/MOS-COORDINATION.md)
+- [Hermes runtime adapter design](tess/hermes-runtime-adapter-design.md)
+- [Operator plugin sketch](tess/M4-003-OPERATOR-PLUGIN-SKETCH.md)
+
+### API contract
+
+- [Tess OpenAPI contract](openapi-tess.yaml)
+
+### Migration and qualification
+
+- [Migration inventory](tess/M5-MIGRATION-INVENTORY.md)
+- [Cutover procedure](tess/M5-MIGRATION-CUTOVER.md)
+- [Rollback procedure](tess/M5-MIGRATION-ROLLBACK.md)
+- [Retention and deprecation evidence](tess/M5-MIGRATION-RETENTION-DEPRECATION.md)
+- [Verification matrix](tess/VERIFICATION-MATRIX.md)
+- [Documentation checklist](tess/M5-003-DOCUMENTATION-CHECKLIST.md)
+- [Independent Option 2 runtime-portability qualification (2026-07-14)](tess/qualification/2026-07-14-option2-runtime-portability.md)
+
+## Runtime-neutral Mos portability
+
+- [Optional AI egress gateway ADR](architecture/ADR-MOS-EGRESS-GATEWAYS.md) — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies.
+- [Runtime-neutral Mos identity and failover mission](https://git.mosaicstack.dev/mosaicstack/stack/issues/754)
+- [Logical identity and connector lease/fencing implementation](https://git.mosaicstack.dev/mosaicstack/stack/issues/755)
+- [M1 logical identity and fencing architecture](architecture/mos-runtime-portability-m1.md)
+- [M1 connector lease operations](guides/mos-connector-lease-operations.md)

docs/TASKS.md

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

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

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

docs/architecture/channel-protocol.md

@@ -1,9 +1,9 @@
 # Channel Protocol Architecture
 
-**Status:** Draft
+**Status:** Official adapter baseline implemented by #756; extended registry/multiplexing remains iterative
 **Authors:** Mosaic Core Team
-**Last Updated:** 2026-03-22
-**Covers:** M7-001 (IChannelAdapter interface), M7-002 (ChannelMessage protocol), M7-003 (Matrix integration design), M7-004 (conversation multiplexing), M7-005 (remote auth bridging), M7-006 (agent-to-agent communication via Matrix), M7-007 (multi-user isolation in Matrix)
+**Last Updated:** 2026-07-14
+**Covers:** M7-001 (OfficialChannelAdapter interface), M7-002 (ChannelMessageDto protocol), M7-003 (Matrix integration design), M7-004 (conversation multiplexing), M7-005 (remote auth bridging), M7-006 (agent-to-agent communication via Matrix), M7-007 (multi-user isolation in Matrix)
 
 ---
 
@@ -11,93 +11,80 @@
 
 The channel protocol defines a unified abstraction layer between Mosaic's core messaging infrastructure and the external communication channels it supports (Matrix, Discord, Telegram, TUI, WebUI, and future channels).
 
-The protocol consists of two main contracts:
+The implemented baseline is exported from `@mosaicstack/types` and consists of four contract groups:
 
-1. `IChannelAdapter` — the interface each channel driver must implement.
-2. `ChannelMessage` — the canonical message format that flows through the system.
+1. `OfficialChannelAdapter` — transport lifecycle and connection health.
+2. `ChannelMessageDto` / `ChannelAttachmentDto` — canonical transport data.
+3. `ChannelConversationRouteDto` — stable logical-agent conversation and authorization address.
+4. `ChannelResponseTargetDto` — channel/thread destination for replies.
 
-All channel-specific translation logic lives inside the adapter implementation. The rest of Mosaic works exclusively with `ChannelMessage` objects.
+All channel-specific translation logic lives inside the adapter implementation. Runtime selection does not: gateway durable-session and provider services may rebind the logical session from Claude to Codex, Pi, OpenCode, or another harness without reconnecting the channel adapter.
 
 ---
 
-## M7-001: IChannelAdapter Interface
+## M7-001: OfficialChannelAdapter Interface
 
 ```typescript
-interface IChannelAdapter {
-  /**
-   * Stable, lowercase identifier for this channel (e.g. "matrix", "discord").
-   * Used as a namespace key in registry lookups and log metadata.
-   */
+interface OfficialChannelAdapter {
+  /** Stable, lowercase adapter identifier such as "discord" or "matrix". */
   readonly name: string;
-
-  /**
-   * Establish a connection to the external channel backend.
-   * Called once at application startup. Must be idempotent (safe to call
-   * when already connected).
-   */
-  connect(): Promise<void>;
-
-  /**
-   * Gracefully disconnect from the channel backend.
-   * Must flush in-flight sends and release resources before resolving.
-   */
-  disconnect(): Promise<void>;
-
-  /**
-   * Return the current health of the adapter connection.
-   * Used by the admin health endpoint and alerting.
-   *
-   * - "connected"    — fully operational
-   * - "degraded"     — partial connectivity (e.g. read-only, rate-limited)
-   * - "disconnected" — no connection to channel backend
-   */
-  health(): Promise<{ status: 'connected' | 'degraded' | 'disconnected' }>;
-
-  /**
-   * Register an inbound message handler.
-   * The adapter calls `handler` for every message received from the channel.
-   * Multiple calls replace the previous handler (last-write-wins).
-   * The handler is async; the adapter must not deliver new messages until
-   * the previous handler promise resolves (back-pressure).
-   */
-  onMessage(handler: (msg: ChannelMessage) => Promise<void>): void;
-
-  /**
-   * Send a ChannelMessage to the given channel/room/conversation.
-   * `channelId` is the channel-native identifier (e.g. Matrix room ID,
-   * Discord channel snowflake, Telegram chat ID).
-   */
-  sendMessage(channelId: string, msg: ChannelMessage): Promise<void>;
-
-  /**
-   * Map a channel-native user identifier to the Mosaic internal userId.
-   * Returns null when no matching Mosaic account exists for the given
-   * channelUserId (anonymous or unlinked user).
-   */
-  mapIdentity(channelUserId: string): Promise<string | null>;
+  /** Establish both native-channel and gateway connections. */
+  start(): Promise<void>;
+  /** Gracefully close connections and release resources. */
+  stop(): Promise<void>;
+  /** Best-effort health; ordinary disconnection is a result, not an exception. */
+  health(): Promise<{
+    status: 'connected' | 'degraded' | 'disconnected';
+    detail?: string;
+  }>;
 }
 ```
 
+The small lifecycle seam lets the gateway host official plugins uniformly without moving native message translation into gateway core. Message ingress remains adapter-owned; gateway policy, durable session routing, auditing, and runtime/provider selection remain gateway-owned.
+
+### Stable conversation route
+
+```typescript
+interface ChannelConversationRouteDto {
+  bindingId: string;
+  logicalAgentId: string;
+  conversationId: string;
+  channelName: string;
+  authorizationChannelId: string;
+  responseTarget: { channelId: string; threadId?: string };
+}
+```
+
+Harness, provider, model, process, and native runtime-session identifiers are forbidden from this route. Runtime adapters consume the gateway's durable logical-session binding; channel adapters consume only the stable route and response target.
+
+### Typed ingress and egress ports
+
+`ChannelIngressPort` is the transport-neutral direct-integration seam for official adapters. The current deployed Discord adapter preserves its existing HMAC-signed Socket.IO compatibility ingress so gateway-side service authentication, replay protection, approval handling, and correlation semantics remain unchanged; it normalizes the same `ChannelIngressDto` before signing. The adapter uses a supplied `ChannelIngressPort` directly when a future gateway registration provides one. New adapters must use the shared ports rather than adding channel branches to gateway core.
+
+`ChannelBindingDto` contains the configuration-owned workspace/channel→logical-agent mapping and paired external principals; credentials are absent. After native allowlist, pairing, and role checks pass, an adapter submits `ChannelIngressDto` to `ChannelIngressPort.receive()`. It includes the normalized message, `ChannelAuthorizedPrincipalDto`, operation, correlation ID, native message ID, and stable route. Unauthorized input never reaches the port.
+
+Gateway policy and runtime routing produce `ChannelEgressDto`, which `ChannelEgressPort.send()` delivers to the route's response target. Discord's existing HMAC envelope is its authenticated wire encoding of this boundary; future Matrix/Slack adapters use their native authenticated transports while preserving the same actor/operation/correlation semantics.
+
 ### Adapter Registration
 
-Adapters are registered with the `ChannelRegistry` service at startup. The registry calls `connect()` on each adapter and monitors `health()` on a configurable interval (default: 30 s).
+Adapters are registered with the gateway plugin host at startup. The host calls `start()`/`stop()` and may monitor `health()` on a configurable interval. A richer dynamic `ChannelRegistry` remains a compatible future extension of this lifecycle contract.
 
 ```
 ChannelRegistry
-  └── register(adapter: IChannelAdapter): void
-  └── getAdapter(name: string): IChannelAdapter | null
-  └── listAdapters(): IChannelAdapter[]
+  └── register(adapter: OfficialChannelAdapter): void
+  └── getAdapter(name: string): OfficialChannelAdapter | null
+  └── listAdapters(): OfficialChannelAdapter[]
   └── healthAll(): Promise<Record<string, AdapterHealth>>
 ```
 
 ---
 
-## M7-002: ChannelMessage Protocol
+## M7-002: ChannelMessageDto Protocol
 
 ### Canonical Message Format
 
 ```typescript
-interface ChannelMessage {
+interface ChannelMessageDto {
   /**
    * Globally unique message ID.
    * Format: UUID v4. Generated by the adapter when receiving, or by Mosaic
@@ -110,6 +97,7 @@ interface ChannelMessage {
    * The adapter populates this from the inbound message.
    * For outbound messages, the caller supplies the target channel.
    */
+  channelName: string;
   channelId: string;
 
   /**
@@ -119,7 +107,7 @@ interface ChannelMessage {
   senderId: string;
 
   /** Sender classification. */
-  senderType: 'user' | 'agent' | 'system';
+  senderKind: 'user' | 'agent' | 'system';
 
   /**
    * Textual content of the message.
@@ -136,7 +124,7 @@ interface ChannelMessage {
    * - "image"    — binary image; content is empty, see attachments
    * - "file"     — binary file; content is empty, see attachments
    */
-  contentType: 'text' | 'markdown' | 'code' | 'image' | 'file';
+  contentKind: 'text' | 'markdown' | 'code' | 'image' | 'file';
 
   /**
    * Arbitrary key-value metadata for channel-specific extension fields.
@@ -144,7 +132,7 @@ interface ChannelMessage {
    * Adapters should store channel-native IDs here so round-trip correlation
    * is possible without altering the canonical fields.
    */
-  metadata: Record<string, unknown>;
+  metadata: Readonly<Record<string, ChannelMetadataValue>>;
 
   /**
    * Optional thread or reply-chain identifier.
@@ -163,18 +151,21 @@ interface ChannelMessage {
    * Binary or URI-referenced attachments.
    * Each attachment carries its MIME type and a URL or base64 payload.
    */
-  attachments?: ChannelAttachment[];
+  attachments?: readonly ChannelAttachmentDto[];
 
-  /** Wall-clock timestamp when the message was sent/received. */
-  timestamp: Date;
+  /** ISO-8601 wall-clock timestamp when the message was sent/received. */
+  timestamp: string;
 }
 
-interface ChannelAttachment {
-  /** Filename or identifier. */
+interface ChannelAttachmentDto {
+  /** Channel-native attachment identifier. */
+  id: string;
+
+  /** Filename or display name. */
   name: string;
 
-  /** MIME type (e.g. "image/png", "application/pdf"). */
-  mimeType: string;
+  /** MIME type when supplied by the channel. */
+  mimeType: string | null;
 
   /**
    * URL pointing to the attachment, OR a `data:` URI with base64 payload.
@@ -192,23 +183,23 @@ interface ChannelAttachment {
 
 ## Channel Translation Reference
 
-The following sections document how each supported channel maps its native message format to and from `ChannelMessage`.
+The following sections document how each supported channel maps its native message format to and from `ChannelMessageDto`.
 
 ### Matrix
 
-| ChannelMessage field | Matrix equivalent                                                                                                                 |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                 | Generated UUID; `metadata.channelMessageId` = Matrix event ID (`$...`)                                                            |
-| `channelId`          | Matrix room ID (`!roomid:homeserver`)                                                                                             |
-| `senderId`           | Matrix user ID (`@user:homeserver`)                                                                                               |
-| `senderType`         | Always `"user"` for inbound; `"agent"` or `"system"` for outbound                                                                 |
-| `content`            | `event.content.body`                                                                                                              |
-| `contentType`        | `"markdown"` if `msgtype = m.text` and body contains markdown; `"text"` otherwise; `"image"` for `m.image`; `"file"` for `m.file` |
-| `threadId`           | `event.content['m.relates_to']['event_id']` when `rel_type = m.thread`                                                            |
-| `replyToId`          | Mosaic ID looked up from `event.content['m.relates_to']['m.in_reply_to']['event_id']`                                             |
-| `attachments`        | Populated from `url` in `m.image` / `m.file` events                                                                               |
-| `timestamp`          | `new Date(event.origin_server_ts)`                                                                                                |
-| `metadata`           | `{ channelMessageId, roomId, eventType, unsigned }`                                                                               |
+| ChannelMessageDto field | Matrix equivalent                                                                                                                 |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                    | Generated UUID; `metadata.channelMessageId` = Matrix event ID (`$...`)                                                            |
+| `channelId`             | Matrix room ID (`!roomid:homeserver`)                                                                                             |
+| `senderId`              | Matrix user ID (`@user:homeserver`)                                                                                               |
+| `senderKind`            | Always `"user"` for inbound; `"agent"` or `"system"` for outbound                                                                 |
+| `content`               | `event.content.body`                                                                                                              |
+| `contentKind`           | `"markdown"` if `msgtype = m.text` and body contains markdown; `"text"` otherwise; `"image"` for `m.image`; `"file"` for `m.file` |
+| `threadId`              | `event.content['m.relates_to']['event_id']` when `rel_type = m.thread`                                                            |
+| `replyToId`             | Mosaic ID looked up from `event.content['m.relates_to']['m.in_reply_to']['event_id']`                                             |
+| `attachments`           | Populated from `url` in `m.image` / `m.file` events                                                                               |
+| `timestamp`             | `new Date(event.origin_server_ts)`                                                                                                |
+| `metadata`              | `{ channelMessageId, roomId, eventType, unsigned }`                                                                               |
 
 **Outbound:** Adapter sends `m.room.message` with `msgtype = m.text` (or `m.notice` for system messages). Markdown content is sent with `format = org.matrix.custom.html` and a rendered HTML body.
 
@@ -216,21 +207,34 @@ The following sections document how each supported channel maps its native messa
 
 ### Discord
 
-| ChannelMessage field | Discord equivalent                                                      |
-| -------------------- | ----------------------------------------------------------------------- |
-| `id`                 | Generated UUID; `metadata.channelMessageId` = Discord message snowflake |
-| `channelId`          | Discord channel ID (snowflake string)                                   |
-| `senderId`           | Discord user ID (snowflake)                                             |
-| `senderType`         | `"user"` for human members; `"agent"` for bot messages                  |
-| `content`            | `message.content`                                                       |
-| `contentType`        | `"markdown"` (Discord uses a markdown-like syntax natively)             |
-| `threadId`           | `message.thread.id` when the message is inside a thread channel         |
-| `replyToId`          | Mosaic ID looked up from `message.referenced_message.id`                |
-| `attachments`        | `message.attachments` mapped to `ChannelAttachment`                     |
-| `timestamp`          | `new Date(message.timestamp)`                                           |
-| `metadata`           | `{ channelMessageId, guildId, channelType, mentions, embeds }`          |
+| ChannelMessageDto field | Discord equivalent                                                      |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `id`                    | Generated UUID; `metadata.channelMessageId` = Discord message snowflake |
+| `channelId`             | Discord channel ID (snowflake string)                                   |
+| `senderId`              | Discord user ID (snowflake)                                             |
+| `senderKind`            | `"user"` for human members; `"agent"` for bot messages                  |
+| `content`               | `message.content`                                                       |
+| `contentKind`           | `"markdown"` (Discord uses a markdown-like syntax natively)             |
+| `threadId`              | `message.thread.id` when the message is inside a thread channel         |
+| `replyToId`             | Mosaic ID looked up from `message.referenced_message.id`                |
+| `attachments`           | `message.attachments` mapped to `ChannelAttachmentDto`                  |
+| `timestamp`             | `new Date(message.timestamp)`                                           |
+| `metadata`              | `{ channelMessageId, guildId, channelType, mentions, embeds }`          |
 
-**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.
+**Outbound:** Adapter calls Discord REST `POST /channels/{id}/messages`. Markdown content is sent as-is (Discord renders it). For `contentKind = "code"` the adapter wraps in triple-backtick fences with the `metadata.language` tag.
+
+### Discord routing and thread policy
+
+A configured Discord binding maps `(guildId, parentChannelId)` to a stable logical agent and a trusted gateway agent-config ID. Gateway verifies that configuration's name matches the binding logical agent before session creation. The stable conversation handle is derived from logical agent plus response channel/thread and never includes the active harness, provider, model, process, or agent-config ID.
+
+| Inbound location/trigger                   | Conversation and response target                                |
+| ------------------------------------------ | --------------------------------------------------------------- |
+| Authorized untagged parent-channel message | Parent channel; response is sent in-channel                     |
+| Authorized bot mention in parent channel   | Thread already attached to that message, or a new public thread |
+| Authorized message already in a thread     | Existing thread; no repeated mention and no nested thread       |
+| `/approve` or `/stop <approval>`           | Current parent/thread durable session; no new topic is created  |
+
+Authorization order is fixed: guild allowlist → parent-channel allowlist → user allowlist → configured binding/pairing → operation role → per-user/channel message and thread rate limits → thread creation/dispatch. A normal Discord channel's category parent is never treated as the thread authorization parent. If requested thread creation fails, dispatch does not occur because the adapter cannot honor the response target.
 
 ### Discord service ingress security
 
@@ -240,21 +244,21 @@ The Discord adapter is an authenticated gateway service, not an anonymous Socket
 
 ### Telegram
 
-| ChannelMessage field | Telegram equivalent                                                                                           |
-| -------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `id`                 | Generated UUID; `metadata.channelMessageId` = Telegram `message_id` (integer)                                 |
-| `channelId`          | Telegram `chat_id` (integer as string)                                                                        |
-| `senderId`           | Telegram `from.id` (integer as string)                                                                        |
-| `senderType`         | `"user"` for human senders; `"agent"` for bot-originated messages                                             |
-| `content`            | `message.text` or `message.caption`                                                                           |
-| `contentType`        | `"text"` for plain; `"markdown"` if `parse_mode = MarkdownV2`; `"image"` for `photo`; `"file"` for `document` |
-| `threadId`           | `message.message_thread_id` (for supergroup topics)                                                           |
-| `replyToId`          | Mosaic ID looked up from `message.reply_to_message.message_id`                                                |
-| `attachments`        | `photo`, `document`, `video` fields mapped to `ChannelAttachment`                                             |
-| `timestamp`          | `new Date(message.date * 1000)`                                                                               |
-| `metadata`           | `{ channelMessageId, chatType, fromUsername, forwardFrom }`                                                   |
+| ChannelMessageDto field | Telegram equivalent                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `id`                    | Generated UUID; `metadata.channelMessageId` = Telegram `message_id` (integer)                                 |
+| `channelId`             | Telegram `chat_id` (integer as string)                                                                        |
+| `senderId`              | Telegram `from.id` (integer as string)                                                                        |
+| `senderKind`            | `"user"` for human senders; `"agent"` for bot-originated messages                                             |
+| `content`               | `message.text` or `message.caption`                                                                           |
+| `contentKind`           | `"text"` for plain; `"markdown"` if `parse_mode = MarkdownV2`; `"image"` for `photo`; `"file"` for `document` |
+| `threadId`              | `message.message_thread_id` (for supergroup topics)                                                           |
+| `replyToId`             | Mosaic ID looked up from `message.reply_to_message.message_id`                                                |
+| `attachments`           | `photo`, `document`, `video` fields mapped to `ChannelAttachmentDto`                                          |
+| `timestamp`             | `new Date(message.date * 1000)`                                                                               |
+| `metadata`              | `{ channelMessageId, chatType, fromUsername, forwardFrom }`                                                   |
 
-**Outbound:** Adapter calls Telegram Bot API `sendMessage` with `parse_mode = MarkdownV2` for markdown content. For `contentType = "image"` or `"file"` it uses `sendPhoto` / `sendDocument`.
+**Outbound:** Adapter calls Telegram Bot API `sendMessage` with `parse_mode = MarkdownV2` for markdown content. For `contentKind = "image"` or `"file"` it uses `sendPhoto` / `sendDocument`.
 
 ---
 
@@ -262,19 +266,19 @@ The Discord adapter is an authenticated gateway service, not an anonymous Socket
 
 The TUI adapter bridges Mosaic's terminal interface (`packages/cli`) to the channel protocol so that TUI sessions can be treated as a first-class channel.
 
-| ChannelMessage field | TUI equivalent                                                     |
-| -------------------- | ------------------------------------------------------------------ |
-| `id`                 | Generated UUID (TUI has no native message IDs)                     |
-| `channelId`          | `"tui:<conversationId>"` — the active conversation ID              |
-| `senderId`           | Authenticated Mosaic `userId`                                      |
-| `senderType`         | `"user"` for human input; `"agent"` for agent replies              |
-| `content`            | Raw text from stdin / agent output                                 |
-| `contentType`        | `"text"` for input; `"markdown"` for agent responses               |
-| `threadId`           | Not used (TUI sessions are linear)                                 |
-| `replyToId`          | Not used                                                           |
-| `attachments`        | File paths dragged/pasted into the TUI; resolved to `file://` URLs |
-| `timestamp`          | `new Date()` at the moment of send                                 |
-| `metadata`           | `{ conversationId, sessionId, ttyWidth, colorSupport }`            |
+| ChannelMessageDto field | TUI equivalent                                                     |
+| ----------------------- | ------------------------------------------------------------------ |
+| `id`                    | Generated UUID (TUI has no native message IDs)                     |
+| `channelId`             | `"tui:<conversationId>"` — the active conversation ID              |
+| `senderId`              | Authenticated Mosaic `userId`                                      |
+| `senderKind`            | `"user"` for human input; `"agent"` for agent replies              |
+| `content`               | Raw text from stdin / agent output                                 |
+| `contentKind`           | `"text"` for input; `"markdown"` for agent responses               |
+| `threadId`              | Not used (TUI sessions are linear)                                 |
+| `replyToId`             | Not used                                                           |
+| `attachments`           | File paths dragged/pasted into the TUI; resolved to `file://` URLs |
+| `timestamp`             | `new Date()` at the moment of send                                 |
+| `metadata`              | `{ conversationId, sessionId, ttyWidth, colorSupport }`            |
 
 **Outbound:** The adapter writes rendered content to stdout. Markdown is rendered via a terminal markdown renderer (e.g. `marked-terminal`). Code blocks are syntax-highlighted when `metadata.colorSupport = true`.
 
@@ -284,19 +288,19 @@ The TUI adapter bridges Mosaic's terminal interface (`packages/cli`) to the chan
 
 The WebUI adapter connects the Next.js frontend (`apps/web`) to the channel protocol over the existing Socket.IO gateway (`apps/gateway`).
 
-| ChannelMessage field | WebUI equivalent                                             |
-| -------------------- | ------------------------------------------------------------ |
-| `id`                 | Generated UUID; echoed back in the WebSocket event           |
-| `channelId`          | `"webui:<conversationId>"`                                   |
-| `senderId`           | Authenticated Mosaic `userId`                                |
-| `senderType`         | `"user"` for browser input; `"agent"` for agent responses    |
-| `content`            | Message text from the input field                            |
-| `contentType`        | `"text"` or `"markdown"`                                     |
-| `threadId`           | Not used (conversation model handles threading)              |
-| `replyToId`          | Message ID the user replied to (UI reply affordance)         |
-| `attachments`        | Files uploaded via the file picker; stored to object storage |
-| `timestamp`          | `new Date()` at send, or server timestamp from event         |
-| `metadata`           | `{ conversationId, sessionId, clientTimezone, userAgent }`   |
+| ChannelMessageDto field | WebUI equivalent                                             |
+| ----------------------- | ------------------------------------------------------------ |
+| `id`                    | Generated UUID; echoed back in the WebSocket event           |
+| `channelId`             | `"webui:<conversationId>"`                                   |
+| `senderId`              | Authenticated Mosaic `userId`                                |
+| `senderKind`            | `"user"` for browser input; `"agent"` for agent responses    |
+| `content`               | Message text from the input field                            |
+| `contentKind`           | `"text"` or `"markdown"`                                     |
+| `threadId`              | Not used (conversation model handles threading)              |
+| `replyToId`             | Message ID the user replied to (UI reply affordance)         |
+| `attachments`           | Files uploaded via the file picker; stored to object storage |
+| `timestamp`             | `new Date()` at send, or server timestamp from event         |
+| `metadata`              | `{ conversationId, sessionId, clientTimezone, userAgent }`   |
 
 **Outbound:** Adapter emits a `chat:message` Socket.IO event. The WebUI React component receives it and appends to the conversation list. Markdown content is rendered client-side via the existing markdown renderer component.
 
@@ -304,7 +308,7 @@ The WebUI adapter connects the Next.js frontend (`apps/web`) to the channel prot
 
 ## Identity Mapping
 
-`mapIdentity(channelUserId)` resolves a channel-native user identifier to a Mosaic `userId`. This is required to attribute inbound messages to authenticated Mosaic accounts.
+Gateway identity-linking policy resolves a channel-native user identifier to a Mosaic `userId` and produces `ChannelAuthorizedPrincipalDto`. Adapters provide native identity evidence but cannot self-authorize Mosaic scope. Discord currently uses configuration-owned paired users; database-backed linking remains the canonical direction for dynamic Matrix/Slack identity.
 
 The implementation must query a `channel_identities` table (or equivalent) keyed on `(channel_name, channel_user_id)`. When no mapping exists the method returns `null` and the message is treated as anonymous (no Mosaic session context).
 
@@ -323,8 +327,8 @@ Identity linking flows (OAuth dance, deep-link verification token, etc.) are out
 
 ## Error Handling Conventions
 
-- `connect()` must throw a structured error (subclass of `ChannelConnectError`) if the initial connection cannot be established within a reasonable timeout (default: 10 s).
-- `sendMessage()` must throw `ChannelSendError` on terminal failures (auth revoked, channel not found). Transient failures (rate limit, network blip) should be retried internally with exponential backoff before throwing.
+- `start()` must establish the native channel transport or throw a structured connection error. An adapter hosted inside the gateway must not wait for a loopback connection to that same not-yet-listening process; it starts the native transport, lets Socket.IO reconnect, and reports `degraded` until both links are ready.
+- `ChannelEgressPort.send()` implementations must throw a typed terminal error for revoked auth, an invalid route, or a missing channel. Only transient rate/network/server failures are retried with bounded exponential backoff; Discord retries reuse a stable enforced nonce to prevent duplicate chunks, while permanent 4xx failures are not retried.
 - `health()` must never throw — it returns `{ status: 'disconnected' }` on error.
 - Adapters must emit structured logs with `{ channel: adapter.name, event, ... }` metadata for observability.
 
@@ -332,7 +336,7 @@ Identity linking flows (OAuth dance, deep-link verification token, etc.) are out
 
 ## Versioning
 
-The `ChannelMessage` protocol follows semantic versioning. Non-breaking field additions (new optional fields) are minor version bumps. Breaking changes (type changes, required field additions) require a major version bump and a migration guide.
+The `ChannelMessageDto` protocol follows semantic versioning. Non-breaking field additions (new optional fields) are minor version bumps. Breaking changes (type changes, required field additions) require a major version bump and a migration guide.
 
 Current version: **1.0.0**
 
@@ -473,7 +477,7 @@ A single Mosaic conversation can be accessed simultaneously from multiple surfac
 ### Real-Time Sync Flow
 
 1. A message arrives on any surface (TUI keystroke, browser send, Matrix event).
-2. The surface's adapter normalizes the message to `ChannelMessage` and delivers it to `ConversationService`.
+2. The surface's adapter normalizes the message to `ChannelMessageDto` and delivers it to `ConversationService`.
 3. `ConversationService` persists the message to PostgreSQL, assigns a canonical `id`, and publishes a `message:new` event to the Valkey pub/sub channel keyed by `conversationId`.
 4. All active surfaces subscribed to that `conversationId` receive the fanout event and push it to their respective clients:
    - TUI adapter: writes rendered output to the connected terminal session.
@@ -561,7 +565,7 @@ Matrix sessions for linked users are persistent and long-lived. Unlike TUI sessi
 - Their `channel_identities` row exists (link not revoked).
 - They remain members of the relevant Matrix rooms.
 
-Revoking a Matrix link (`DELETE /auth/channel-link/matrix/<matrixUserId>`) removes the `channel_identities` row and causes `mapIdentity()` to return `null`. The appservice optionally kicks the Matrix user from all Mosaic-managed rooms as part of the revocation flow (configurable, default: off).
+Revoking a Matrix link (`DELETE /auth/channel-link/matrix/<matrixUserId>`) removes the `channel_identities` row and causes gateway principal resolution to deny the identity. The appservice optionally kicks the Matrix user from all Mosaic-managed rooms as part of the revocation flow (configurable, default: off).
 
 ---
 
@@ -733,7 +737,7 @@ room_retention_policies
   created_at       TIMESTAMP
 ```
 
-The retention policy is enforced by a background job in the gateway that calls Conduit's admin API to purge events older than the configured threshold. Purged events are removed from the Conduit store but Mosaic's PostgreSQL message store retains the canonical `ChannelMessage` record unless the Mosaic retention policy also covers it.
+The retention policy is enforced by a background job in the gateway that calls Conduit's admin API to purge events older than the configured threshold. Purged events are removed from the Conduit store but Mosaic's PostgreSQL message store retains the canonical `ChannelMessageDto` record unless the Mosaic retention policy also covers it.
 
 Default retention values:
 

docs/architecture/mos-runtime-portability-m1.md

@@ -0,0 +1,49 @@
+# Mos Runtime Portability M1 — Logical Identity and Fencing
+
+## Boundary
+
+M1 separates the logical Mosaic agent from any Claude, Pi, Codex, tmux, Matrix, or provider-native session. The normalized identity is:
+
+```text
+(tenant_id, logical_agent_id, binding_id)
+```
+
+`logical_agent_id` is a server-owned stable identifier. A connector is a replaceable holder of a lease for one binding; it is not the agent identity.
+
+## Durable lease model
+
+PostgreSQL table `logical_agent_connector_leases` has one unique row per identity/binding tuple. The current row records:
+
+- an opaque lease UUID;
+- connector ID and normalized allowed scopes;
+- a positive decimal fencing epoch stored as PostgreSQL `bigint`;
+- acquired, heartbeat, expiry, release, and update timestamps.
+
+Initial acquisition is insert-only. An existing active row causes `lease_held`. An expired or released row causes `takeover_required`; ordinary acquisition cannot recover it. Authorized takeover uses compare-and-swap against the expected epoch, rotates the lease UUID, and increments the epoch atomically. Heartbeat and release match the full identity, binding, connector, lease UUID, and epoch.
+
+The companion `connector_lease_audit_log` is append-only metadata. It stores lifecycle event, outcome/reason, identity/binding/connector, epoch, correlation ID, and timestamp. It deliberately excludes scopes, grant objects, payloads, approval references, tokens, and credentials.
+
+## Execution grants
+
+`ConnectorLeaseCoordinator` issues a short-lived internal grant only after rereading the durable current lease. Defense-in-depth caps leases at 5 minutes and grants at 30 seconds by default; constructor options may tighten these limits. A grant is bound to tenant, logical agent, binding, connector, lease UUID, scope subset, expiry, and epoch.
+
+Validation occurs immediately before adapter invocation and rereads PostgreSQL. The adapter receives only `ConnectorExecutionContext`; harness-native schemas remain behind the adapter. Validation denies:
+
+- grants not minted by the current gateway process (including cloned/forged objects);
+- expired grants or leases;
+- released leases;
+- stale epochs or replaced connector/lease UUIDs;
+- missing/cross-tenant/cross-agent/cross-binding leases;
+- scopes not authorized by both grant and current lease.
+
+A gateway restart intentionally invalidates process-local grants. The durable lease and epoch survive, and a fresh grant may be issued only after current-lease and gateway-policy validation.
+
+## Concurrency and side-effect rule
+
+The database CAS determines the sole current holder. A successful takeover makes every old-epoch validation fail. Connector adapters must consume and propagate the normalized lease epoch/context so downstream effect boundaries can also fence races that occur after gateway validation.
+
+M1 does not provide exactly-once receipts or a side-effect journal. Those remain later #754 work; callers must not infer exactly-once delivery from lease fencing.
+
+## Extension boundary
+
+`ConnectorLeaseService` is the gateway-owned policy surface. Every policy decision receives the normalized requested scopes and TTL (or explicit `null` where no TTL applies), so a concrete policy can enforce least privilege and duration limits. Its production default policy denies every lease/grant operation until a server-configured connector policy is supplied. No M1 HTTP endpoint accepts caller-controlled tenant or logical identity, and no concrete Claude/Pi/Codex adapter or channel cutover is included.

docs/design/storage-abstraction-middleware.md

@@ -70,6 +70,10 @@ export function createQueue(config?: QueueConfig): QueueHandle {
 
 ### `@mosaicstack/db` (packages/db/src/client.ts)
 
+> **Historical design specimen — status-only, not an operator instruction.** KBN-101 supersedes
+> this pre-split `DATABASE_URL` fallback shape; it cannot authorize runtime migration, DDL, or a
+> connection-string fallback. See the KBN-101 runner/role contract for the produced interface.
+
 ```typescript
 import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import postgres from 'postgres';

docs/federation/SETUP.md

@@ -30,22 +30,11 @@ Expected output shows `postgres-federated` and `valkey-federated` both healthy.
 
 ## Configure mosaic for federated tier
 
-Create or update your `mosaic.config.json`:
-
-```json
-{
-  "tier": "federated",
-  "database": "postgresql://mosaic:mosaic@localhost:5433/mosaic",
-  "queue": "redis://localhost:6380"
-}
-```
-
-If you're using environment variables instead:
-
-```bash
-export DATABASE_URL="postgresql://mosaic:mosaic@localhost:5433/mosaic"
-export REDIS_URL="redis://localhost:6380"
-```
+KBN-101 supersedes the former inline federated database configuration. Do not put a DSN in
+`mosaic.config.json` or export one in a shell. The reviewed deployment renderer mounts the
+runtime secret only to Gateway and the migration secret only to the one-shot runner; the runtime
+uses verified TLS and the runner verifies schema readiness before Gateway starts. Queue
+configuration remains deployment-owned.
 
 ## Verify health
 
@@ -190,11 +179,8 @@ PG_FEDERATED_HOST_PORT=5434 VALKEY_FEDERATED_HOST_PORT=6381 \
 docker compose -f docker-compose.federated.yml logs postgres-federated | grep -i vector
 ```
 
-If missing, exec into the container and create it manually:
-
-```bash
-docker exec <postgres-federated-id> psql -U mosaic -d mosaic -c "CREATE EXTENSION vector;"
-```
+Do not create it manually. A missing extension is a failed reviewed bootstrap/runner
+precondition: stop the stack and remediate through the KBN-101 external bootstrap control plane.
 
 ### Valkey connection refused
 

docs/federation/TASKS.md

@@ -15,20 +15,20 @@
 
 Goal: Gateway runs in `federated` tier with containerized PG+pgvector+Valkey. No federation logic yet. Existing standalone behavior does not regress.
 
-| id        | status | description                                                                                                                                                                                                        | issue | agent  | branch                             | depends_on | estimate | notes                                                                                                                                            |
-| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FED-M1-01 | done   | Extend `mosaic.config.json` schema: add `"federated"` to `tier` enum in validator + TS types. Keep `local` and `standalone` working. Update schema docs/README where referenced.                                   | #460  | sonnet | feat/federation-m1-tier-config     | —          | 4K       | Shipped in PR #470. Renamed `team` → `standalone`; added `team` deprecation alias; added `DEFAULT_FEDERATED_CONFIG`.                             |
-| FED-M1-02 | done   | Author `docker-compose.federated.yml` as an overlay profile: Postgres 17 + pgvector extension (port 5433), Valkey (6380), named volumes, healthchecks. Compose-up should boot cleanly on a clean machine.          | #460  | sonnet | feat/federation-m1-compose         | FED-M1-01  | 5K       | Shipped in PR #471. Overlay defines `postgres-federated`/`valkey-federated`, profile-gated, with pg-init for pgvector extension.                 |
-| FED-M1-03 | done   | Add pgvector support to `packages/storage/src/adapters/postgres.ts`: create extension on init (idempotent), expose vector column type in schema helpers. No adapter changes for non-federated tiers.               | #460  | sonnet | feat/federation-m1-pgvector        | FED-M1-02  | 8K       | Shipped in PR #472. `enableVector` flag on postgres StorageConfig; idempotent CREATE EXTENSION before migrations.                                |
-| FED-M1-04 | done   | Implement `apps/gateway/src/bootstrap/tier-detector.ts`: reads config, asserts PG/Valkey/pgvector reachable for `federated`, fail-fast with actionable error message on failure. Unit tests for each failure mode. | #460  | sonnet | feat/federation-m1-detector        | FED-M1-03  | 8K       | Shipped in PR #473. 12 tests; 5s timeouts on probes; pgvector library/permission discrimination; rejects non-bullmq for federated.               |
-| FED-M1-05 | done   | Write `scripts/migrate-to-federated.ts`: one-way migration from `local` (PGlite) / `standalone` (PG without pgvector) → `federated`. Dumps, transforms, loads; dry-run + confirm UX. Idempotent on re-run.         | #460  | sonnet | feat/federation-m1-migrate         | FED-M1-04  | 10K      | Shipped in PR #474. `mosaic storage migrate-tier`; DrizzleMigrationSource (corrects P0 found in review); 32 tests; idempotent.                   |
-| FED-M1-06 | done   | Update `mosaic doctor`: report current tier, required services, actual health per service, pgvector presence, overall green/yellow/red. Machine-readable JSON output flag for CI use.                              | #460  | sonnet | feat/federation-m1-doctor          | FED-M1-04  | 6K       | Shipped in PR #475 as `mosaic gateway doctor`. Probes lifted to @mosaicstack/storage; structural TierConfig breaks dep cycle.                    |
-| FED-M1-07 | done   | Integration test: gateway boots in `federated` tier with docker-compose `federated` profile; refuses to boot when PG unreachable (asserts fail-fast); pgvector extension query succeeds.                           | #460  | sonnet | feat/federation-m1-integration     | FED-M1-04  | 8K       | Shipped in PR #476. 3 test files, 4 tests, gated by FEDERATED_INTEGRATION=1; reserved-port helper avoids host collisions.                        |
-| FED-M1-08 | done   | Integration test for migration script: seed a local PGlite with representative data (tasks, notes, users, teams), run migration, assert row counts + key samples equal on federated PG.                            | #460  | sonnet | feat/federation-m1-migrate-test    | FED-M1-05  | 6K       | Shipped in PR #477. Caught P0 in M1-05 (camelCase→snake_case) missed by mocked unit tests; fix in same PR.                                       |
-| FED-M1-09 | done   | Standalone regression: full agent-session E2E on existing `standalone` tier with a gateway built from this branch. Must pass without referencing any federation module.                                            | #460  | sonnet | feat/federation-m1-regression      | FED-M1-07  | 4K       | Clean canary. 351 gateway tests + 85 storage unit tests + full pnpm test all green; only FEDERATED_INTEGRATION-gated tests skip.                 |
-| FED-M1-10 | done   | Code review pass: security-focused on the migration script (data-at-rest during migration) + tier detector (error-message sensitivity leakage). Independent reviewer, not authors of tasks 01-09.                  | #460  | sonnet | feat/federation-m1-security-review | FED-M1-09  | 8K       | 2 review rounds caught 7 issues: credential leak in pg/valkey/pgvector errors + redact-error util; missing advisory lock; SKIP_TABLES rationale. |
-| FED-M1-11 | done   | Docs update: `docs/federation/` operator notes for tier setup; README blurb on federated tier; `docs/guides/` entry for migration. Do NOT touch runbook yet (deferred to FED-M7).                                  | #460  | haiku  | feat/federation-m1-docs            | FED-M1-10  | 4K       | Shipped: `docs/federation/SETUP.md` (119 lines), `docs/guides/migrate-tier.md` (147 lines), README Configuration blurb.                          |
-| FED-M1-12 | done   | PR, CI green, merge to main, close #460.                                                                                                                                                                           | #460  | sonnet | feat/federation-m1-close           | FED-M1-11  | 3K       | M1 closed. PRs #470-#480 merged across 11 tasks. Issue #460 closed; release tag `fed-v0.1.0-m1` published.                                       |
+| id        | status | description                                                                                                                                                                                                        | issue | agent  | branch                             | depends_on | estimate | notes                                                                                                                                                                                                                                                 |
+| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FED-M1-01 | done   | Extend `mosaic.config.json` schema: add `"federated"` to `tier` enum in validator + TS types. Keep `local` and `standalone` working. Update schema docs/README where referenced.                                   | #460  | sonnet | feat/federation-m1-tier-config     | —          | 4K       | Shipped in PR #470. Renamed `team` → `standalone`; added `team` deprecation alias; added `DEFAULT_FEDERATED_CONFIG`.                                                                                                                                  |
+| FED-M1-02 | done   | Author `docker-compose.federated.yml` as an overlay profile: Postgres 17 + pgvector extension (port 5433), Valkey (6380), named volumes, healthchecks. Compose-up should boot cleanly on a clean machine.          | #460  | sonnet | feat/federation-m1-compose         | FED-M1-01  | 5K       | Shipped in PR #471. Overlay defines `postgres-federated`/`valkey-federated`, profile-gated, with pg-init for pgvector extension.                                                                                                                      |
+| FED-M1-03 | done   | Historical shipped-status record: add pgvector support to `packages/storage/src/adapters/postgres.ts`; no adapter changes for non-federated tiers.                                                                 | #460  | sonnet | feat/federation-m1-pgvector        | FED-M1-02  | 8K       | Shipped in PR #472 status only. **KBN-101 supersedes this behavior:** it cannot authorize current runtime extension creation or any DDL; only the runner/external bootstrap contract may do so.                                                       |
+| FED-M1-04 | done   | Implement `apps/gateway/src/bootstrap/tier-detector.ts`: reads config, asserts PG/Valkey/pgvector reachable for `federated`, fail-fast with actionable error message on failure. Unit tests for each failure mode. | #460  | sonnet | feat/federation-m1-detector        | FED-M1-03  | 8K       | Shipped in PR #473. 12 tests; 5s timeouts on probes; pgvector library/permission discrimination; rejects non-bullmq for federated.                                                                                                                    |
+| FED-M1-05 | done   | Historical shipped-status record: prior tier migration implementation.                                                                                                                                             | #460  | sonnet | feat/federation-m1-migrate         | FED-M1-04  | 10K      | Shipped in PR #474 status only. **KBN-101 supersedes this route:** it cannot authorize current credentials, target connection, or DDL. The future active route requires runner verification plus target URL-file and signed attestation-file binding. |
+| FED-M1-06 | done   | Update `mosaic doctor`: report current tier, required services, actual health per service, pgvector presence, overall green/yellow/red. Machine-readable JSON output flag for CI use.                              | #460  | sonnet | feat/federation-m1-doctor          | FED-M1-04  | 6K       | Shipped in PR #475 as `mosaic gateway doctor`. Probes lifted to @mosaicstack/storage; structural TierConfig breaks dep cycle.                                                                                                                         |
+| FED-M1-07 | done   | Integration test: gateway boots in `federated` tier with docker-compose `federated` profile; refuses to boot when PG unreachable (asserts fail-fast); pgvector extension query succeeds.                           | #460  | sonnet | feat/federation-m1-integration     | FED-M1-04  | 8K       | Shipped in PR #476. 3 test files, 4 tests, gated by FEDERATED_INTEGRATION=1; reserved-port helper avoids host collisions.                                                                                                                             |
+| FED-M1-08 | done   | Integration test for migration script: seed a local PGlite with representative data (tasks, notes, users, teams), run migration, assert row counts + key samples equal on federated PG.                            | #460  | sonnet | feat/federation-m1-migrate-test    | FED-M1-05  | 6K       | Shipped in PR #477. Caught P0 in M1-05 (camelCase→snake_case) missed by mocked unit tests; fix in same PR.                                                                                                                                            |
+| FED-M1-09 | done   | Standalone regression: full agent-session E2E on existing `standalone` tier with a gateway built from this branch. Must pass without referencing any federation module.                                            | #460  | sonnet | feat/federation-m1-regression      | FED-M1-07  | 4K       | Clean canary. 351 gateway tests + 85 storage unit tests + full pnpm test all green; only FEDERATED_INTEGRATION-gated tests skip.                                                                                                                      |
+| FED-M1-10 | done   | Code review pass: security-focused on the migration script (data-at-rest during migration) + tier detector (error-message sensitivity leakage). Independent reviewer, not authors of tasks 01-09.                  | #460  | sonnet | feat/federation-m1-security-review | FED-M1-09  | 8K       | 2 review rounds caught 7 issues: credential leak in pg/valkey/pgvector errors + redact-error util; missing advisory lock; SKIP_TABLES rationale.                                                                                                      |
+| FED-M1-11 | done   | Docs update: `docs/federation/` operator notes for tier setup; README blurb on federated tier; `docs/guides/` entry for migration. Do NOT touch runbook yet (deferred to FED-M7).                                  | #460  | haiku  | feat/federation-m1-docs            | FED-M1-10  | 4K       | Shipped: `docs/federation/SETUP.md` (119 lines), `docs/guides/migrate-tier.md` (147 lines), README Configuration blurb.                                                                                                                               |
+| FED-M1-12 | done   | PR, CI green, merge to main, close #460.                                                                                                                                                                           | #460  | sonnet | feat/federation-m1-close           | FED-M1-11  | 3K       | M1 closed. PRs #470-#480 merged across 11 tasks. Issue #460 closed; release tag `fed-v0.1.0-m1` published.                                                                                                                                            |
 
 **M1 total estimate:** ~74K tokens (over-budget vs 20K PRD estimate — explanation below)
 

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

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

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

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

docs/fleet/backlog-conventions.md

@@ -14,18 +14,17 @@ and surfaced as `mosaic fleet backlog <sub> --json`.
 The backlog uses the existing Mosaic storage layer; there is **no** new database
 engine (no sqlite, no raw client).
 
-| Condition                      | Tier                 | Data location                    |
-| ------------------------------ | -------------------- | -------------------------------- |
-| `DATABASE_URL` set             | Full server Postgres | the configured database          |
-| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite      | that directory                   |
-| neither (default)              | Embedded PGlite      | `~/.config/mosaic/fleet/backlog` |
+| Condition                          | Tier                 | Data location                                                    |
+| ---------------------------------- | -------------------- | ---------------------------------------------------------------- |
+| `DATABASE_URL` injected at runtime | Full server Postgres | the verified runtime database; it never authorizes migration/DDL |
+| `PGLITE_DATA_DIR` set (no URL)     | Embedded PGlite      | that directory                                                   |
+| neither (default)                  | Embedded PGlite      | `~/.config/mosaic/fleet/backlog`                                 |
 
 PGlite is real Postgres semantics in-process — including the row locks the atomic
 claim relies on — so the **same code** runs on a laptop (embedded, single-host
 default) and on a full Postgres deployment. Switching tiers is config-only.
 
-The schema (`backlog` table) is created automatically on first CLI use:
-`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
+For embedded PGlite only, the local backlog routine may prepare its local schema on first use. PostgreSQL never migrates on CLI first use: it requires the dedicated `mosaic-db-migrator --run` phase and its read-only runtime readiness check before `mosaic fleet backlog` connects.
 
 ### Update safety
 

docs/fleet/how-to/customize-roles.md

@@ -0,0 +1,54 @@
+# Customize Fleet Roles
+
+Mosaic resolves persona contracts through two layers:
+
+1. `fleet/roles/<canonical-class>.md` — seeded baseline contract.
+2. `fleet/roles.local/<canonical-class>.md` — operator override or custom role; this layer wins.
+
+The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation,
+and launch-time persona injection.
+
+## Override a baseline role
+
+Create a readable Markdown contract under `roles.local` with the canonical filename and class marker:
+
+```markdown
+# Code — local role definition
+
+The local code role (`class: code`) follows the operator's repository conventions.
+```
+
+Save it as `fleet/roles.local/code.md`. Do not edit generated or seeded baseline assets when the goal
+is a durable local customization.
+
+Legacy aliases canonicalize before lookup. Therefore `roles.local/implementer.md` does not override
+`code`; use `roles.local/code.md`. See [Legacy Fleet Class Aliases](../migration/legacy-class-aliases.md).
+
+## Add a custom class
+
+A custom class remains supported when a readable contract exists for the exact identifier:
+
+```markdown
+# Release notes — local role definition
+
+The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
+```
+
+Save it as `fleet/roles.local/release-notes.md`, then reference `class: release-notes` and a matching
+`tool_policy: release-notes` in roster v2. Adding only a `LIBRARY.md` row is insufficient.
+
+Names such as `worker`, `analyst`, and `canary` are not built-in aliases; they need genuine custom
+contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.
+
+## Validation and authority boundaries
+
+Semantic validation reads the winning contract and rejects missing, unreadable, or empty files.
+Protected authority is derived from canonical class metadata in code, never from role prose. A custom
+contract cannot claim merge, validation-certificate, orchestration, lease, or interaction authority.
+
+Roster v2 also fails closed when a protected class and tool policy do not match after canonicalization,
+or when an unprotected class claims a protected tool policy. The legacy `operator-interaction` policy
+canonicalizes to `interaction`.
+
+Role customization does not issue leases, store validation certificates, mutate credentials, or
+change lifecycle state.

docs/fleet/migration/example-profile-disposition.md

@@ -0,0 +1,52 @@
+# Executable Fleet Example, Profile, and Service-Preset Dispositions
+
+**Issue:** #758 · **Card:** FCM-M1-003 · **Status:** M1 executable disposition evidence
+
+This document records the executable disposition for every currently shipped fleet YAML artifact.
+The authoritative baseline classification remains the
+[legacy inventory](../LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md). The executable guard is
+`packages/mosaic/src/fleet/example-profile-dispositions.ts`; its test fails if a shipped YAML
+artifact is added, removed, or left without one of the dispositions below.
+
+## Disposition rules
+
+- **Explicit v1 fixture:** the artifact is loaded through the existing v1 roster parser and must
+  declare `version: 1`. It remains a compatibility fixture; it is not silently treated as a v2
+  roster or given inferred aliases.
+- **Canonical profile:** the artifact is loaded through `loadProfiles`, which uses the shared
+  baseline-plus-`roles.local` persona resolver and rejects unreadable or unresolved classes.
+- **Canonical service policy:** the artifact is loaded through the operator-interaction service
+  policy reader and provisioned with a generic supplied identity. It validates its runtime, model,
+  reasoning, and legacy tool-policy compatibility without hardcoding a product identity.
+
+No artifact is retired in this card. A later retirement requires both a replacement link and a
+visible deprecation note; the executable guard must then record the new disposition before the
+artifact can be removed.
+
+## Shipped artifacts
+
+| Artifact                             | Disposition              | Executable path                   | Compatibility notes                                                                              |
+| ------------------------------------ | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `examples/coding.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains approved `implementer` and `reviewer` compatibility inputs.                              |
+| `examples/general.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains unresolved `worker` without an inferred canonical role.                                  |
+| `examples/hybrid.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains `implementer`, `reviewer`, and resolver-dependent `researcher`.                          |
+| `examples/local-canary.yaml`         | Explicit v1 fixture      | v1 roster parser                  | Retains the local-tmux canary topology.                                                          |
+| `examples/minimal.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains `canary` without an inferred canonical role.                                             |
+| `examples/operator-interaction.yaml` | Explicit v1 fixture      | v1 roster parser                  | Keeps Tess only as an example instance name; `operator-interaction` remains compatibility input. |
+| `examples/research.yaml`             | Explicit v1 fixture      | v1 roster parser                  | Retains resolver-dependent `researcher` and `analyst`.                                           |
+| `profiles/business.yaml`             | Canonical profile        | shared profile/persona resolver   | Every referenced business class must resolve to a readable contract.                             |
+| `profiles/marketing.yaml`            | Canonical profile        | shared profile/persona resolver   | Every referenced marketing class must resolve to a readable contract.                            |
+| `profiles/personal-assistant.yaml`   | Canonical profile        | shared profile/persona resolver   | No interaction equivalence is inferred.                                                          |
+| `profiles/research.yaml`             | Canonical profile        | shared profile/persona resolver   | Every research class must resolve to a readable contract.                                        |
+| `profiles/software-delivery.yaml`    | Canonical profile        | shared profile/persona resolver   | Retains the governance profile; authority validation remains FCM-M1-002 evidence.                |
+| `services/operator-interaction.yaml` | Canonical service policy | service-policy reader/provisioner | Generic provisioning supplies the instance name; the policy itself never names Tess.             |
+
+## Running the guard
+
+```bash
+pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts
+```
+
+The guard is intentionally limited to shipped assets and validation. It does not generate
+environment files, mutate a roster, reconcile a fleet, migrate an installed roster, or launch an
+agent.

docs/fleet/migration/legacy-class-aliases.md

@@ -0,0 +1,40 @@
+# Legacy Fleet Class Aliases
+
+Fleet class compatibility is intentionally narrow. The shared resolver accepts exactly three legacy
+class names and converts them to canonical classes before persona lookup:
+
+| Legacy value           | Canonical value | Migration action                                                                                                       |
+| ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `implementer`          | `code`          | Replace class and tool-policy references with `code`.                                                                  |
+| `reviewer`             | `review`        | Replace class and tool-policy references with `review`.                                                                |
+| `operator-interaction` | `interaction`   | Replace class and roster-v2 tool-policy references with `interaction`. The legacy service artifact remains compatible. |
+
+Alias support preserves existing inputs while provisioning and typed semantic output use canonical
+identities. Requested and canonical class values remain separately observable during semantic
+validation.
+
+## Lookup and override behavior
+
+Canonicalization precedes baseline and `roles.local` lookup. A legacy-named override such as
+`roles.local/implementer.md` is not a separate authority and is not selected for an `implementer`
+request. Customize the canonical role instead, for example `roles.local/code.md`.
+
+The compatibility file `operator-interaction.md` remains shipped, but `interaction` is the canonical
+role class. Tess is an example display name only.
+
+## Unresolved and custom classes
+
+No names are inferred from historical usage, instance names, or similar wording. `worker`, `analyst`,
+`canary`, Tess, and Ultron are not aliases. An otherwise unknown class is accepted only if the shared
+resolver can read an actual baseline or `roles.local` contract for that exact class. A `LIBRARY.md`
+row without a readable contract fails semantic validation.
+
+Custom classes receive no protected authority implicitly. Protected class/tool-policy mismatches
+fail closed.
+
+## Retirement guidance
+
+New configuration should emit canonical values. Existing inputs may use the three aliases during the
+compatibility period, but operators should migrate class and tool-policy fields together. Do not
+create new legacy-named role overrides; move their intended content to the canonical filename and
+validate the roster/profile before removing the old artifact.

docs/fleet/reference/role-classes.md

@@ -0,0 +1,45 @@
+# Fleet Role Classes and Authority
+
+A fleet role class is a machine identity resolved from the persona library. Resolution uses the
+canonical class before consulting the baseline `fleet/roles/` and operator `fleet/roles.local/`
+layers. A readable role contract is required; an index entry alone is not semantic success.
+
+## Canonicalization
+
+Only these legacy class aliases are recognized:
+
+| Requested class        | Canonical class |
+| ---------------------- | --------------- |
+| `implementer`          | `code`          |
+| `reviewer`             | `review`        |
+| `operator-interaction` | `interaction`   |
+
+No other alias is inferred. In particular, `worker`, `analyst`, and `canary` are custom classes only
+when an operator supplies a readable contract for that exact class. Tess and Ultron are instance
+names, not classes. `agents[].alias` is display-only and cannot grant authority.
+
+Canonicalization happens before role lookup. For example, requesting `implementer` resolves
+`code.md`; a separate `roles.local/implementer.md` cannot redefine the legacy alias. A canonical
+`roles.local/code.md` still overrides the baseline `roles/code.md` contract.
+
+## Protected authority
+
+Protected authority is immutable metadata derived only from canonical class. Role prose, instance
+name, display alias, tool policy, runtime, and custom role files cannot grant it.
+
+| Canonical class   | Granted authority                                  | Explicit limits                                                                   |
+| ----------------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `merge-gate`      | Sole approve-to-land and merge authority           | No authority is inferred by similarly named custom roles or policies.             |
+| `validator`       | May issue a validation certificate                 | Cannot approve-to-land or merge.                                                  |
+| `orchestrator`    | May orchestrate, manage topology, and issue leases | Cannot approve-to-land or merge.                                                  |
+| `team-leader`     | May use orchestrator-leased capacity               | Cannot issue leases or mutate roster, configuration, credentials, or merge state. |
+| `interaction`     | Request and status surface                         | Cannot orchestrate, issue leases, mutate roster/configuration, or merge.          |
+| all other classes | No protected authority implicitly                  | Custom contracts do not acquire protected powers from prose.                      |
+
+Roster-v2 semantic validation requires a protected class and its canonical tool policy to match. It
+also rejects an unprotected class paired with a protected tool policy. The legacy tool-policy name
+`operator-interaction` canonicalizes to `interaction`.
+
+This mapping describes authority metadata only. Lease issuance, validation-certificate storage or
+workflow, lifecycle reconciliation, credentials, roster mutation, and merge execution are outside
+this resolver contract.

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

@@ -0,0 +1,124 @@
+# Fleet Roster v2 Structural Contract
+
+**Status:** FCM-M1-001 local-tmux structural compiler contract. This document describes parsing,
+strict structural validation, normalized in-memory representation, and deterministic rendering only.
+It does not authorize role resolution, lifecycle reconciliation, mutation, migration, remote
+placement, connector configuration, secret references, arbitrary commands, channels, gateway
+mapping, or any live-fleet change.
+
+The executable schema is [`roster-v2.schema.json`](./roster-v2.schema.json). The compiler exports
+the same schema and its test parses this file and compares it structurally with the executable contract.
+
+## Format and canonical shape
+
+The compiler accepts YAML or JSON. It reads only snake_case source fields and renders canonical,
+snake_case YAML. Rendering sorts runtime keys and agents by stable name. Agent names, class names,
+and tool-policy names are structural identifiers; whether a class or policy resolves is a later
+shared-resolver concern.
+
+```yaml
+version: 2
+generation: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~/src
+  runtime: pi
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: coder0
+    alias: Coder 0
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: high
+    tool_policy: code
+    working_directory: ~/src
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+```
+
+## Root fields
+
+| Field        | Required | Constraint            | Meaning                                                                                                                               |
+| ------------ | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`    | yes      | integer constant `2`  | Identifies this contract. Version `1` is explicitly rejected by this compiler and remains on the existing v1 path until M4 migration. |
+| `generation` | yes      | positive safe integer | Desired-state generation. M2 uses it for mutation guards; M1 does not mutate it.                                                      |
+| `transport`  | yes      | constant `tmux`       | M1–M5 support local tmux only.                                                                                                        |
+| `tmux`       | yes      | strict object         | Explicit local socket and holder-session configuration.                                                                               |
+| `defaults`   | yes      | strict object         | Default work directory and one supported local runtime.                                                                               |
+| `runtimes`   | yes      | non-empty object      | Declared local runtime reset policy map.                                                                                              |
+| `agents`     | yes      | non-empty array       | Local fleet entries. Duplicate stable names are rejected.                                                                             |
+
+## Nested fields
+
+| Path                                                 | Required | Constraint                                                                                           |
+| ---------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `tmux.socket_name`                                   | yes      | non-empty `[A-Za-z0-9_.-]+`; an explicit named socket prevents default-versus-named socket ambiguity |
+| `tmux.holder_session`                                | yes      | non-empty `[A-Za-z0-9_.-]+`                                                                          |
+| `defaults.working_directory`                         | yes      | non-empty string                                                                                     |
+| `defaults.runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                            |
+| `runtimes.<runtime>.reset_command`                   | yes      | non-empty string; runtime key must be a supported local runtime                                      |
+| `agents[].name`                                      | yes      | unique `[A-Za-z0-9][A-Za-z0-9_.-]*` stable machine identity                                          |
+| `agents[].alias`                                     | yes      | non-empty display string                                                                             |
+| `agents[].class`                                     | yes      | `[a-z][a-z0-9-]*`; structural only in M1, semantic role resolution is FCM-M1-002                     |
+| `agents[].runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                            |
+| `agents[].provider`, `model`, `working_directory`    | yes      | non-empty strings; provider/model capability resolution is a later card                              |
+| `agents[].reasoning`                                 | yes      | `low`, `medium`, or `high`                                                                           |
+| `agents[].tool_policy`                               | yes      | `[a-z][a-z0-9-]*`; structural only in M1                                                             |
+| `agents[].persistent_persona`, `reset_between_tasks` | yes      | booleans                                                                                             |
+| `agents[].lifecycle.enabled`                         | yes      | boolean; stored now, reconciled in FCM-M3-001                                                        |
+| `agents[].lifecycle.desired_state`                   | yes      | `running` or `stopped`                                                                               |
+| `agents[].launch.yolo`                               | yes      | boolean; structured data only, not an arbitrary command escape hatch                                 |
+
+## Semantic handoff
+
+`parseRosterV2` and `normalizeRosterV2` remain synchronous and structural. After structural success,
+call the asynchronous `validateRosterV2Semantics` handoff before using persona identity or authority.
+That validator batches the baseline `fleet/roles/` and operator `fleet/roles.local/` scans, then
+delegates every agent to the shared persona resolver.
+
+Semantic validation:
+
+- requires the winning role contract to be readable and non-empty; `LIBRARY.md` membership alone does
+  not resolve a class;
+- retains `requestedClass` separately from `canonicalClass` in typed output;
+- canonicalizes only `implementer` to `code`, `reviewer` to `review`, and
+  `operator-interaction` to `interaction`;
+- canonicalizes `tool_policy` with the same exact alias table;
+- rejects protected class/tool-policy mismatches in either direction, while accepting
+  `class: operator-interaction` with `tool_policy: operator-interaction` as canonical
+  `interaction`;
+- derives immutable protected authority only from canonical class; and
+- accepts custom baseline or `roles.local` classes without granting protected authority.
+
+`agents[].alias` remains display-only. Tess and Ultron are instance names, never semantic classes.
+Canonicalization happens before role-layer lookup, so a legacy-named override cannot redefine an
+alias as separate authority. See [Role Classes and Authority](./role-classes.md) and
+[Customize Fleet Roles](../how-to/customize-roles.md).
+
+This handoff performs no filesystem, systemd, tmux, roster, credential, lease, certificate, or
+lifecycle mutation.
+
+## Fail-closed boundary
+
+Every object is `additionalProperties: false`. The compiler rejects unknown, missing, malformed,
+and wrong-type fields before producing a model. It specifically rejects remote/SSH/host/socket
+per-agent fields, connector blocks, secret references, channel fields, arbitrary command fields,
+and gateway fields because they are unsupported in the local-tmux M1 contract. It does not silently
+ignore v1 camelCase input, version `1`, or a source that does not parse to an object.
+
+The v2 compiler is intentionally isolated from the existing v1 loader. Existing v1 rosters and
+current examples/profiles continue on their current path; FCM-M4 owns explicit inventory, preview,
+migration, and rollback. FCM-M2 owns generated-file/local-override quarantine, and FCM-M3 owns
+runtime lifecycle and reconciliation.

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

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

docs/guides/admin-guide.md

@@ -223,10 +223,10 @@ external clients. Authentication requires a valid BetterAuth session (cookie or
 
 ### Required
 
-| Variable             | Description                                                                               |
-| -------------------- | ----------------------------------------------------------------------------------------- |
-| `BETTER_AUTH_SECRET` | Secret key for BetterAuth session signing. Must be set or gateway will not start.         |
-| `DATABASE_URL`       | PostgreSQL connection string. Default: `postgresql://mosaic:mosaic@localhost:5433/mosaic` |
+| Variable             | Description                                                                                                 |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET` | Secret key for BetterAuth session signing. Must be set or gateway will not start.                           |
+| `DATABASE_URL`       | Runtime-only PostgreSQL connection injected from the dedicated deployment secret; no default or inline DSN. |
 
 ### Gateway
 
@@ -293,24 +293,64 @@ 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_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                                                                                                   |
+| 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                                                                   |
+| `DISCORD_INTERACTION_BINDINGS`          | Required JSON bindings from guild/channel to logical agent and paired Discord users with `viewer`, `operator`, or `admin` roles           |
+| `DISCORD_MESSAGE_RATE_LIMIT_PER_MINUTE` | Optional positive integer; authorized turns per guild/channel/user each minute (default: `30`)                                            |
+| `DISCORD_THREAD_RATE_LIMIT_PER_MINUTE`  | Optional positive integer; mention-thread routes per guild/channel/user each minute (default: `5`)                                        |
+| `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.
+Inbound Discord messages must originate from an allowed guild and configured parent channel, come from an allowed and paired user whose role permits sending, and carry a signed envelope containing the native Discord message ID and a generated correlation ID. Attachment references are limited in count, metadata size, field length, and declared size; only query-free HTTPS URLs without credentials or fragments are accepted, so bearer or presigned URLs never reach persistence or an agent prompt. The gateway validates the service identity, envelope signature, allowlists, pairing, and role 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.
+
+Configured channels are dedicated agent interaction surfaces. An authorized untagged message routes to the bound logical agent and the response returns in that channel. Mentioning the bot on a normal channel message creates a public Discord thread, or reuses the thread already attached to that same message; the response and later thread messages stay in that thread without repeated mentions. A normal channel's category is not an authorization parent—only a Discord thread inherits authorization from its configured parent channel. Runtime control commands such as `/approve` and `/stop <approval>` remain on the current channel/thread because they target that durable session rather than opening a new topic.
+
+Authorization and per-user/channel rate limits are evaluated before thread creation, so an unlisted guild/channel/user, unpaired user, `viewer`, or rate-limited sender cannot create bot threads or dispatch gateway work. The bot needs Discord permissions to view/send in configured channels and create/send in public threads. If thread creation fails, the turn is not dispatched because the requested response destination cannot be honored.
+
+Conversation handles use the configured logical agent plus Discord channel/thread identity. They do not contain a Claude, Codex, Pi, OpenCode, model, process, or runtime-provider identifier; changing the runtime behind the logical session therefore does not require reconnecting the Discord bot.
+
+#### Interaction binding format
+
+`DISCORD_INTERACTION_BINDINGS` must be a non-empty JSON array. Each item requires `instanceId`, trusted `agentConfigId`, `guildId`, `channelId`, and a non-empty `pairedUsers` object. `instanceId` is the configured logical-agent name; its trusted database `agentConfigId` must resolve to an agent configuration with exactly that name, preserving provider/model/prompt/tool selection per binding. The guild/channel must also appear in their corresponding allowlists. IDs below are placeholders:
+
+```json
+[
+  {
+    "instanceId": "interaction-agent",
+    "agentConfigId": "agent-config-id",
+    "guildId": "guild-id",
+    "channelId": "channel-id",
+    "pairedUsers": {
+      "discord-user-id": {
+        "role": "operator",
+        "mosaicUserId": "mosaic-user-id"
+      }
+    }
+  }
+]
+```
+
+| Pairing role | Send message | Create/continue thread | Approve | Stop |
+| ------------ | ------------ | ---------------------- | ------- | ---- |
+| `viewer`     | No           | No                     | No      | No   |
+| `operator`   | Yes          | Yes                    | No      | No   |
+| `admin`      | Yes          | Yes                    | Yes     | Yes  |
+
+A legacy role-only value such as `"discord-user-id": "operator"` remains valid for non-privileged ingress. Approval and stop require the object form with a provisioned `mosaicUserId`; gateway policy checks that Mosaic identity and consumes one exact-action approval once. Do not make the Discord service principal an approving administrator.
+
+After changing bindings or allowlists, restart the gateway/plugin through the normal service manager and verify both Discord and gateway connectivity. The adapter reports `connected` only when both links are ready, `degraded` when one is ready, and `disconnected` when neither is ready. Test one authorized untagged channel turn, one mention-created thread, one thread follow-up, and one unauthorized user denial without using production credential values in logs or evidence.
 
 ### Session retention and garbage collection
 

docs/guides/deployment.md

@@ -61,9 +61,13 @@ pnpm install
 ### 4. Initialize the database
 
 ```bash
-pnpm --filter @mosaicstack/db db:migrate
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 ```
 
+This is the sole PostgreSQL DDL/readiness control plane. It receives migration-only credentials
+through deployment secret mounts and accepts no URL, SQL, schema, or role argv.
+
 ### 5. Build all packages
 
 ```bash
@@ -118,34 +122,25 @@ sudo apt-get install -y postgresql-17 postgresql-17-pgvector
 # Follow https://valkey.io/download/ for your distribution
 ```
 
-### Step 2 — Create the database
+### Step 2 — Provision the database
 
-```sql
--- Run as the postgres superuser
-CREATE USER mosaic WITH PASSWORD 'change-me';
-CREATE DATABASE mosaic OWNER mosaic;
-\c mosaic
-CREATE EXTENSION IF NOT EXISTS vector;
-```
+Do not run ad hoc SQL, create application roles, or create extensions from this guide. The
+external reviewed bootstrap artifact provisions roles/pgvector, then the migration Job runs
+`mosaic-db-migrator --run` and `mosaic-db-migrator --verify` over verified TLS. This guide does
+not authorize a plaintext, owner-runtime, or manual-extension bootstrap.
 
 ### Step 3 — Clone and configure
 
 ```bash
 git clone <repo-url> /opt/mosaic
 cd /opt/mosaic
-cp .env.example .env
 ```
 
-Edit `/opt/mosaic/.env`. Required fields:
-
-```dotenv
-DATABASE_URL=postgresql://mosaic:<password>@localhost:5432/mosaic
-VALKEY_URL=redis://localhost:6379
-BETTER_AUTH_SECRET=<openssl rand -base64 32>
-BETTER_AUTH_URL=https://your-domain.example.com
-GATEWAY_CORS_ORIGIN=https://your-domain.example.com
-NEXT_PUBLIC_GATEWAY_URL=https://your-domain.example.com
-```
+Production deployment does **not** read a committed or local `.env` file. Use the reviewed
+secret renderer/deployment control plane: it injects runtime secrets only at process exec,
+migration secrets only to the one-shot runner, and non-secret endpoint configuration separately.
+Validate required values at startup; never write a DSN or BetterAuth secret into this guide or a
+production filesystem `.env`.
 
 ### Step 4 — Install dependencies and build
 
@@ -157,9 +152,12 @@ pnpm build
 ### Step 5 — Run database migrations
 
 ```bash
-pnpm --filter @mosaicstack/db db:migrate
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 ```
 
+The one-shot migrator alone receives the migration secret; Gateway/runtime never receives it.
+
 ### Step 6 — Start the gateway
 
 ```bash
@@ -340,20 +338,12 @@ MaxRetentionSec=30day
 
 `BETTER_AUTH_SECRET` is missing or empty. Set it in `.env` and restart.
 
-### `DATABASE_URL` connection refused
+### Runtime database connection refused
 
-Verify PostgreSQL is running and the port matches. The Docker Compose default is `5433`; bare-metal typically uses `5432`.
-
-```bash
-psql "$DATABASE_URL" -c '\conninfo'
-```
-
-### pgvector extension missing
-
-```sql
-\c mosaic
-CREATE EXTENSION IF NOT EXISTS vector;
-```
+Verify PostgreSQL service/TLS readiness and the deployment-mounted runtime secret reference. Do
+not print or test a DSN from a shell. Run the sanitized `mosaic-db-migrator --verify` readiness
+procedure; if pgvector or schema verification fails, stop and remediate through the reviewed
+bootstrap/runner control plane. Manual extension SQL is unavailable.
 
 ### Valkey / Redis connection refused
 

docs/guides/dev-guide.md

@@ -106,7 +106,8 @@ This starts:
 Create a `.env` file in the monorepo root:
 
 ```env
-# Database (matches docker-compose defaults)
+# Runtime database connection (local-development placeholder only; never a production secret)
+# KBN-101 production-like runtime injects DATABASE_URL from its dedicated secret mount.
 DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
 
 # Auth (required — generate a random 32+ char string)
@@ -127,14 +128,16 @@ OLLAMA_MODELS=llama3.2
 The gateway loads `.env` from the monorepo root via `dotenv` at startup
 (`apps/gateway/src/main.ts`).
 
-### 4. Push the Database Schema
+### 4. Prepare the PostgreSQL Schema
 
 ```bash
-pnpm --filter @mosaicstack/db db:push
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 ```
 
-This applies the Drizzle schema directly to the database (development only; use
-migrations in production).
+KBN-101 makes this the sole PostgreSQL DDL/readiness sequence. Direct schema push is not an
+operator workflow; a disposable local experiment is separately guarded and cannot use a
+production-like tier or URL.
 
 ### 5. Start the Gateway
 
@@ -355,12 +358,13 @@ The schema lives in a single file:
 
 The `insights` table uses a `vector(1536)` column (pgvector) for semantic search.
 
-### Development: Push Schema
+### Development: Prepare Schema
 
-Apply schema changes directly to the dev database (no migration files created):
+Prepare a PostgreSQL development target through the same sole runner:
 
 ```bash
-pnpm --filter @mosaicstack/db db:push
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 ```
 
 ### Generating Migrations
@@ -376,7 +380,8 @@ This creates a new SQL migration file in `packages/db/drizzle/`.
 ### Running Migrations
 
 ```bash
-pnpm --filter @mosaicstack/db db:migrate
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 ```
 
 ### Drizzle Config
@@ -388,9 +393,9 @@ directory are defined there.
 
 1. Add the table definition to `packages/db/src/schema.ts`.
 2. Export it from `packages/db/src/index.ts`.
-3. Run `pnpm --filter @mosaicstack/db db:push` (dev) or
-   `pnpm --filter @mosaicstack/db db:generate && pnpm --filter @mosaicstack/db db:migrate`
-   (production).
+3. Generate the offline artifact with `pnpm --filter @mosaicstack/db db:generate`, then run
+   `mosaic-db-migrator --run` and `mosaic-db-migrator --verify`. Direct schema push is not a
+   production-like workflow and the migration runner accepts no URL/SQL/schema/role argv.
 
 ---
 

docs/guides/migrate-tier.md

@@ -1,39 +1,86 @@
 # Migrating to the Federated Tier
 
-Step-by-step guide to migrate from `local` (PGlite) or `standalone` (PostgreSQL without pgvector) to `federated` (PostgreSQL 17 + pgvector + Valkey).
+> **KBN-101-07 ownership:** this is an **active** operator guide, exclusively owned by
+> KBN-101-07. It is not a historical document. The KBN-101-06 finite operator-document
+> inventory records this route and its secure-interface fields.
 
-## When to migrate
+This guide is active documentation but a **non-operative KBN-101 contract** until
+KBN-101-02, -03, and -06 land and KBN-101-08 activates the reviewed artifacts. The command
+blocks below specify the produced interface; they are not available on the current branch and
+MUST NOT be attempted until the activation certificate names the exact release. Until then, do
+not use a direct PostgreSQL target URL, raw SQL, or any legacy storage migration command as a
+production procedure.
 
-Migrate to federated tier when:
+## Non-negotiable boundary
 
-- Scaling from single-user to multi-user deployments
-- Adding vector embeddings or RAG features
-- Running Mosaic across multiple hosts
-- Requires distributed task queueing and caching
-- Moving to production with high availability
+The PostgreSQL destination schema is prepared separately before data migration:
+
+1. The dedicated DDL runner executes `mosaic-db-migrator --run` using its migration-only
+   identity.
+2. The same runner succeeds at `mosaic-db-migrator --verify` against the exact destination and,
+   only then, emits a signed target-bound attestation.
+3. Only then may `mosaic storage migrate-tier` verify that attestation and connect as dedicated
+   non-DDL `mosaic_data_importer` to copy data.
+
+The data migration never executes DDL or changes PostgreSQL roles, memberships, schemas,
+extensions, extension members, system catalogs, or the Drizzle ledger. Its only target writes are
+an allowlisted data-copy DML registry: inserts and idempotent conflict updates on declared mutable
+application tables. It has no DML grant for immutable KBN relations, extension/catalog objects, or
+any schema authority. It is not a schema bootstrap, extension installer, or repair procedure.
+PostgreSQL is always pre-migrated and runner-verified, including when the source is PGlite.
 
 ## Prerequisites
 
-- Federated stack running and healthy (see [Federated Tier Setup](../federation/SETUP.md))
-- Source database accessible and empty target database at the federated URL
-- Backup of source database (recommended before any migration)
+- Federated stack is running and healthy (see [Federated Tier Setup](../federation/SETUP.md)).
+- An approved source backup exists and the target is identified in the KBN-101 change record.
+- The target passed the runner `--run` and `--verify` sequence above; `--verify` is the only
+  trusted attestation producer after verified TLS, identity, manifest, and schema checks.
+- The operator has an approved, dedicated high-entropy importer credential file at
+  `/run/secrets/mosaic_migrate_target_url` and its paired non-secret attestation artifact at
+  `/run/mosaic-attestations/migrate-target.v1.json`. Neither file contents are printed, copied,
+  committed, or placed on argv.
+- KBN-101-02 validates both references before any target connection: each is a regular,
+  non-symlink file with the exact required owner/mode. The importer gets only pinned public
+  verification key(s) and the attestation; the runner-only Ed25519 private key never reaches
+  importer/runtime. The URL file is opened, digested, parsed, and connected from the same
+  in-memory bytes with no reread.
+
+### Source modes
+
+- **Local PGlite:** the source is the explicit `PGLITE_DATA_DIR`; it does not read or
+  interpret a PostgreSQL URL.
+- **PostgreSQL source:** this active route does not accept `DATABASE_URL` as a source or
+  target fallback. A PostgreSQL-source procedure needs its own independently approved,
+  non-secret credential-reference contract before it is enabled.
 
 ## Dry-run first
 
-Always run a dry-run to validate the migration:
+Run the migration only after the target schema is prepared and verified:
 
 ```bash
+mosaic-db-migrator --run
+mosaic-db-migrator --verify
 mosaic storage migrate-tier --to federated \
-  --target-url postgresql://mosaic:mosaic@localhost:5433/mosaic \
+  --target-url-file /run/secrets/mosaic_migrate_target_url \
+  --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \
   --dry-run
 ```
 
-Expected output (partial example):
+The frozen KBN-101-02 options are exactly
+`--target-url-file /run/secrets/mosaic_migrate_target_url` and
+`--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. They are
+non-secret file references, not URL options. The runner and importer use distinct connections:
+the runner has migration DDL authority; the importer has only approved data-copy DML authority.
 
-```
-[migrate-tier] Analyzing source tier: pglite
-[migrate-tier] Analyzing target tier: federated
-[migrate-tier] Precondition: target is empty ✓
+Expected dry-run output is sanitized and contains no connection string, username, host,
+database name, SQL, or credential value:
+
+```text
+[migrate-tier] Source tier: pglite
+[migrate-tier] Target tier: federated
+[migrate-tier] Target schema: verified by mosaic-db-migrator
+[migrate-tier] Target connection: dedicated importer
+[migrate-tier] Precondition: target is ready
   users: 5 rows
   teams: 2 rows
   conversations: 12 rows
@@ -43,26 +90,64 @@ Expected output (partial example):
 [migrate-tier] DRY-RUN COMPLETE (no data written). 206 total rows would be migrated.
 ```
 
-Review the output. If it shows an error (e.g., target not empty), address it before proceeding.
+Review the output. If it reports a failed runner verification, unexpected role, unsafe
+secret-file owner/mode, non-empty target, or any connection/DDL precondition error, stop
+and remediate through the KBN-101 control plane.
 
-## Run the migration
+## Run the data migration
 
-When ready, run without `--dry-run`:
+After a reviewed dry-run, repeat the same verified route with `--yes`:
 
 ```bash
+mosaic-db-migrator --verify
 mosaic storage migrate-tier --to federated \
-  --target-url postgresql://mosaic:mosaic@localhost:5433/mosaic \
+  --target-url-file /run/secrets/mosaic_migrate_target_url \
+  --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \
   --yes
 ```
 
-The `--yes` flag skips the confirmation prompt (required in non-TTY environments like CI).
+`--yes` only confirms data copy in non-TTY automation. It does not bypass schema
+verification, target-file validation, role checks, redaction, or the no-DDL boundary.
 
 The command will:
 
-1. Acquire an advisory lock (blocks concurrent invocations)
-2. Copy data from source to target in dependency order
-3. Report rows migrated per table
-4. Display any warnings (e.g., null vector embeddings)
+1. Before target connection, validate both files, JCS/Ed25519 signature and pinned key ID,
+   expiry, nonce replay, secret version/digest, canonical TLS host/port/database, CA/SPKI,
+   expected importer role, and manifest/schema bindings.
+2. Connect only from the once-opened in-memory URL bytes, then before transaction/DML compare
+   PostgreSQL system identifier, database OID, `current_user`, CA/SPKI, and manifest/schema
+   fingerprints to the attestation; mismatch closes with zero DML/DDL.
+3. Copy data in dependency order without DDL.
+4. Report sanitized row counts and warnings.
+
+## Rejected interfaces and failure-before-connect rules
+
+KBN-101-02 and KBN-101-06 must prove these failures occur before a target connection or
+DDL attempt:
+
+- Raw `--target-url` or any URL/credential value on argv.
+- `DATABASE_URL` as a target or source fallback.
+- A runtime owner, migrator, schema owner, or extension owner used as the data importer.
+- Missing, non-regular, symlinked, wrong-owner, wrong-mode, substituted, or changed-after-check
+  credential file.
+- Missing, stale, replayed, tampered, wrong-key, revoked-key, expired, malformed, or wrong-binding
+  attestation file.
+- Wrong host, database, CA/SPKI, PostgreSQL system identifier, database OID, importer role,
+  manifest, schema, or credential secret-version/digest.
+- Any mode other than the runner-prepared/verified PostgreSQL destination route.
+- Any direct DDL attempt by the migration command or its target connection.
+
+The signed attestation has canonical UTF-8/JCS bytes and detached Ed25519 signature. Its
+credential-free v1 payload binds format/version/key ID; issued/expiry/nonce; exact credential
+secret version and SHA-256; canonical TLS host/port/database; CA/SPKI; PostgreSQL system
+identifier/database OID; importer role; manifest/schema; and producer invocation/build/image/
+correlation. Artifacts are atomically written/renamed `0444`; the replay cache survives until
+expiry; public-key overlap/revocation and credential rotation force a fresh runner verification.
+
+KBN-101-02 SHALL add `packages/storage/src/migrate-tier.spec.ts::secureTargetRouteAndAttestation`
+and its integration counterpart. They prove zero target connection for pre-connect failures and
+zero DML/DDL for post-connect identity mismatch. The finite operator-document scanner rejects an
+unowned route or a guide that reintroduces a credential-bearing command.
 
 ## What gets migrated
 
@@ -88,60 +173,28 @@ Three tables are intentionally not migrated:
 | **verifications** | One-time tokens (email verify, password reset) that have either expired or been consumed        |
 | **admin_tokens**  | Hashed tokens bound to the old environment's secret keys; must be re-issued                     |
 
-**Note on accounts and provider_credentials:** These durable credentials ARE migrated because they are user-bound and required for resuming agent work on the target environment. After migration to a multi-tenant federated deployment, operators may want to audit or wipe these if users are untrusted or credentials should not be shared.
+**Note on accounts and provider_credentials:** These durable credentials are migrated because
+they are user-bound and required for resuming agent work on the target. After migration to a
+multi-tenant federated deployment, operators may want to audit or wipe these if users are
+untrusted or credentials should not be shared.
 
-## Idempotency and concurrency
+## Idempotency, concurrency, and verification
 
-The migration is **idempotent**:
+The data copy is idempotent and uses an importer-scoped advisory lock. It may be retried only
+through the same runner-verified, file-reference route. Do not inspect, unlock, or repair the
+target with ad hoc SQL; a failed or ambiguous run is a control-plane incident with backup and
+rollback evidence.
 
-- Re-running is safe (uses `ON CONFLICT DO UPDATE` internally)
-- Ideal for retries on transient failures
-- Concurrent invocations are blocked by a Postgres advisory lock; the second caller will wait
-
-If a previous run is stuck, check for advisory locks:
-
-```sql
-SELECT * FROM pg_locks WHERE locktype='advisory';
-```
-
-If you need to force-unlock (dangerous):
-
-```sql
-SELECT pg_advisory_unlock(<lock_id>);
-```
-
-## Verify the migration
-
-After migration completes, spot-check the target:
-
-```bash
-# Count rows on a few critical tables
-psql postgresql://mosaic:mosaic@localhost:5433/mosaic -c \
-  "SELECT 'users' as table, COUNT(*) FROM users UNION ALL
-   SELECT 'conversations' as table, COUNT(*) FROM conversations UNION ALL
-   SELECT 'messages' as table, COUNT(*) FROM messages;"
-```
-
-Verify a known user or project exists by ID:
-
-```bash
-psql postgresql://mosaic:mosaic@localhost:5433/mosaic -c \
-  "SELECT id, email FROM users WHERE email='<your-email>';"
-```
-
-Ensure vector embeddings are NULL (if source was PGlite) or populated (if source was postgres + pgvector):
-
-```bash
-psql postgresql://mosaic:mosaic@localhost:5433/mosaic -c \
-  "SELECT embedding IS NOT NULL as has_vector FROM insights LIMIT 5;"
-```
+After a successful migration, use the KBN-101-approved sanitized verification command or
+read-only operator report. Do not paste a target connection string into a shell command,
+terminal history, ticket, or documentation.
 
 ## Rollback
 
-There is no in-place rollback. If the migration fails:
+There is no in-place rollback. If data migration fails:
 
-1. Restore the target database from a pre-migration backup
-2. Investigate the failure logs
-3. Rerun the migration
+1. Keep the previous target state and restore the approved pre-migration backup where required.
+2. Preserve sanitized failure and audit evidence; do not expose the credential file or contents.
+3. Investigate through the KBN-101 control plane and rerun only after independent review.
 
-Always test migrations in a staging environment first.
+Always rehearse this route in a staging environment first.

docs/guides/mos-connector-lease-operations.md

@@ -0,0 +1,43 @@
+# Mos Connector Lease Operations — M1
+
+## Operational status
+
+M1 installs the durable schema and gateway policy/adapter boundary. It does **not** activate a connector, expose a lease administration endpoint, or cut over a channel. The default gateway connector-lease policy is deny-all until a later work package supplies an authorized server-side policy and concrete adapter.
+
+## Events to monitor
+
+Use correlation IDs to follow `connector_lease_audit_log` events:
+
+| Event      | Meaning                                                               |
+| ---------- | --------------------------------------------------------------------- |
+| `acquire`  | First holder inserted for an unused binding                           |
+| `renew`    | Current holder heartbeat extended the TTL                             |
+| `takeover` | Authorized CAS replaced the holder and incremented epoch              |
+| `release`  | Current holder explicitly relinquished authority                      |
+| `expiry`   | An expired current lease was observed                                 |
+| `reject`   | Policy, CAS, expiry, scope, or fencing validation denied an operation |
+
+Audit data is metadata-only. Raw grant objects, connector payloads, scopes, tokens, approval references, and credentials must never be added to audit output.
+
+## Incident checks
+
+For suspected duplicate/stale connector effects:
+
+1. Correlate the attempted operation with its `reject`, `takeover`, or `expiry` event.
+2. Compare the current row's connector ID, lease UUID, epoch, expiry, and release time with the adapter's normalized execution context.
+3. Treat an old epoch, old lease UUID, expired lease, or released lease as non-authoritative. Do not retry it as the old holder.
+4. Recovery uses the authorized takeover path with the observed expected epoch. Ordinary acquire is intentionally rejected for expired/released rows.
+5. If an external effect may already have happened, preserve evidence and do not assume lease fencing provides exactly-once replay safety.
+
+## Migration and rollback safety
+
+Migration `0016_salty_morlocks.sql` is additive: it creates two new tables and indexes without modifying existing authorization/session tables. Before rollout, normal database backup and migration verification still apply. Rolling application code back leaves unused additive tables in place; dropping tables is not part of automated rollback because it would destroy lease/audit evidence.
+
+## Security constraints
+
+- Tenant comes from authenticated gateway context, never a connector request field.
+- Logical agent, binding, connector, and scope identifiers use normalized constrained forms.
+- Takeover requires explicit gateway policy authorization and an expected epoch.
+- Default defense-in-depth TTL caps are 5 minutes for leases and 30 seconds for grants; policy may enforce stricter limits.
+- Validation and rejection audit complete before adapter side effects.
+- Existing authz and exact-action approval controls remain additional required gates; a valid connector lease does not bypass them.

docs/guides/user-guide.md

@@ -522,8 +522,13 @@ mosaic storage export --bucket agent-artifacts --output ./artifacts.tar.gz
 # Import data into storage
 mosaic storage import --bucket agent-artifacts --input ./artifacts.tar.gz
 
-# Migrate data between tiers
-mosaic storage migrate --from hot --to cold --older-than 30d
+# Schema migration (compatibility wrapper only; not a tier data copy)
+mosaic storage migrate --run  # delegates only to mosaic-db-migrator
+
+# Tier data copy is unavailable until KBN-101 activation. Its only produced interface is:
+# mosaic storage migrate-tier --target-url-file /run/secrets/mosaic_migrate_target_url \
+#   --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json
+# Never use a legacy --from/--to storage-migrate command or pass a credential on argv.
 ```
 
 ---

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

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

docs/native-kanban-sot/INDEX.md

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

docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md

@@ -0,0 +1,415 @@
+# KBN-010 — Threat, Authorization, and Constraint-Impact Gate
+
+- **Issue:** [#753](https://git.mosaicstack.dev/mosaicstack/stack/issues/753)
+- **Gate status:** **PASS / GO**
+- **Reviewed baseline:** `origin/main` at `49e8a54` (2026-07-14)
+- **Frozen target:** `SHARED-CONTRACT.md` v1.0.0-rc.4 and `contracts/*.v1.ts`
+- **Disposition input:** contract commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`, tree `7ebab8fa530a7180036928cea9527f808548aa14`
+- **Scope:** documentation and future-test planning only; no runtime, schema, migration, API, configuration, dependency, CI, or deployment change
+
+## 1. Decision
+
+KBN-010 is **PASS / GO** against frozen contract rc.4. The original rc.3 finding remains historical detection evidence:
+
+- **KBN010-SI-001 — rc.3 invalid mission composite-FK candidate key.** At rc.3, `missionsV1` declared a primary key on `id` and a unique key on `(workspace_id, project_id, id)`, but not a candidate key on `(workspace_id, id)`. Both `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk` referenced exactly `(missions.workspace_id, missions.id)`. PostgreSQL requires the referenced column list of a foreign key to match a non-partial unique/primary candidate key; uniqueness of `id` alone did not satisfy that two-column reference. The rc.3 DDL was therefore invalid, and KBN-010 correctly blocked it.
+
+Contract rc.4 resolves SI-001 by adding the non-partial `missions_workspace_id_uidx` candidate key on `(workspace_id, id)` while retaining the global `id` primary key and the project-congruent `(workspace_id, project_id, id)` key. Both polymorphic child FKs retain their exact workspace-safe ordered columns and `ON DELETE RESTRICT`; no target, tenancy, project-congruence, exactly-one-target, N-1, rollback, no-cascade, identity, approval, or fencing authority is weakened.
+
+Independent Homelab non-author schema/security review returned **APPROVE** for the exact rc.4 commit/tree/content and found no collision with #757 connector fencing. SI-001 has no unresolved contract/schema-design impact.
+
+This GO completes the KBN-010 analysis/review prerequisite only. It does **not** claim that runtime schema or migration DDL exists. KBN-100 remains held and may be released only after this PR squash-merges, the merged change reaches terminal-green CI on `main`, and issue #753 closes.
+
+### 1.1 Independent rc.4 evidence identity
+
+- **Commit:** `3f6a3387b419eb99453ee10dd25ba888faaab0b5`
+- **Tree:** `7ebab8fa530a7180036928cea9527f808548aa14`
+- **Stable full-index SHA-256:** `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`
+- **Stable patch-id:** `058cf98026fcd1043703c866aee047c8bb144740`
+- **Verdict:** Homelab independent non-author schema/security review **APPROVE**.
+- **Reviewed conclusions:** the candidate key repairs both dependent FKs; tenant safety, polymorphic exactly-one-target semantics, RESTRICT/no-cascade behavior, and N-1/rollback semantics remain valid; #757 uses separate tables/indexes/FKs/identity/fence authority and has no collision.
+
+A command-rendered patch SHA may differ when Git rendering options, headers, or command form differ. That rendering digest is non-authoritative. Canonical review identity is the Git commit object plus tree and exact file content; the stable full-index digest and stable patch-id above are corroborating identities.
+
+## 2. Method and trust boundaries
+
+### 2.1 Inputs inspected
+
+- Canonical requirements: `docs/requirements/native-kanban-sot.md`.
+- Workstream manifest and read-only task plan.
+- Frozen health, schema, Mechanical Coordinator, and recovery contracts in full.
+- Actual current-main schema, Better Auth guard/scope helpers, project/task/mission/team controllers and repositories, fleet backlog, and `TASKS.md` parser/writer.
+- Issue #753 through the Mosaic provider wrapper.
+
+### 2.2 Current-main exposure that the target must replace, not inherit
+
+| Current-main fact                                                                                                                                         | Constraint on future implementation                                                                                               |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Teams are global; projects, missions, tasks, agents, and fleet backlog have no `workspace_id`.                                                            | KBN-100 must add the workspace boundary and KBN-110 must query by server-derived workspace in every repository operation.         |
+| `AuthGuard` authenticates a Better Auth user, while `scopeFromUser` falls back through optional tenant/team/org claims and finally user ID.               | Kanban tenancy must derive from an authenticated **active workspace membership**, not this compatibility fallback or caller data. |
+| Team list/get/member endpoints return global team data to any authenticated user.                                                                         | New Kanban endpoints must use a uniform no-oracle denial and must not reuse global team lookup as authorization.                  |
+| Project/task repositories load and mutate by bare IDs; controller checks are separate and sometimes distinguish not-found from forbidden.                 | Workspace predicates and authorization must be inside the authoritative transaction/repository command path.                      |
+| Tasks can have nullable project/mission links, free-text assignee, JSON tags, no aggregate version, and no fence.                                         | Expand/backfill/quarantine must precede NOT NULL/composite constraints; new commands cannot trust legacy fields.                  |
+| `mission_tasks.status` is a second status writer.                                                                                                         | Pre-expand must prohibit it as a write source and later retire it only after N-1 evidence.                                        |
+| Fleet `backlog` has global JSON dependencies and TTL claims without workspace, assignment, approval, session, or fencing.                                 | It must be frozen and imported as non-dispatching shadow data; it cannot be adapted into the canonical lease path.                |
+| `packages/coord/src/tasks-file.ts` parses and mutates `TASKS.md`.                                                                                         | KBN-120 must replace production use with generated, read-only projection code and prove there is no import/mutation path.         |
+| No Kanban transaction-local health proof, semantic audit/event chain, change proposals, canonical outbox, approval binding, or fenced lease model exists. | These are new frozen invariants, not behaviors that may be inferred from current endpoints.                                       |
+
+## 3. Authorization matrix
+
+The exact route/DTO freeze belongs to KBN-105. This matrix fixes the minimum authorization behavior that freeze and later implementation must preserve.
+
+| Principal/state                                    | Permitted authority                                                                   | Required authoritative checks                                                                                                                     | Explicit denials                                                                                                |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Unauthenticated caller                             | Public health observation only, if deployment exposes it                              | Health DTO validation; no proof field accepted                                                                                                    | All canonical reads/mutations; health observation never authorizes a write                                      |
+| Active workspace `owner`/`admin` user              | Policy-allowed workspace administration and domain commands                           | Better Auth session; active membership; server-derived workspace; command-family role; expected version/idempotency                               | Foreign workspace, suspended workspace, revoked membership, caller workspace override                           |
+| Active workspace `member` user                     | Policy-allowed project/task/proposal commands                                         | Active membership plus project/team capability and target checks in the same transaction                                                          | Admin, approval, purge, service-only Coordinator, and unrelated project commands                                |
+| Active workspace `auditor` user                    | Workspace-scoped reads and audit/evidence inspection                                  | Active membership and read capability                                                                                                             | Every mutation, approval, lease, token issuance, purge                                                          |
+| Active workspace `service` identity                | Only explicitly issued command families                                               | Credential maps to workspace+agent+session; agent enabled; session live; role/capability allowlist; token expiry/audience; DB recheck per command | Raw DB credentials, user/admin fallback, cross-workspace scope, command families absent from token and registry |
+| Enabled agent with live session                    | Agent commands matching its declared and policy-approved specialist role/capabilities | Exact workspace+agent+session binding, heartbeat/state, assignment target, lease, current decimal-string fence                                    | Ended/offline/degraded session where policy disallows; disabled agent; another assignment/session/fence         |
+| Mechanical Coordinator engine                      | Pure eligibility/order/expiry decisions from immutable snapshots                      | Complete workspace-local snapshot and policy revision                                                                                             | Authentication, ID loading, SQL, proof minting, scope invention, approval, certification, merge                 |
+| Coordinator persistence service                    | Service-only assignment/lease/checkpoint/recovery commands                            | Fresh transaction-local proof; locks; current assignment/approval/task/session/policy/fence                                                       | Public/user proof-by-value, stale approval/policy, direct completion/certification/merge                        |
+| Reviewer/SecReview/Certifier                       | Attributable evidence decisions allowed by gate policy                                | Active authority, author differs from reviewer, mandatory SecReview classification, immutable artifacts                                           | Self-review; missing evidence; Certifier merge/issue-close/release                                              |
+| Break-glass retention operator                     | Narrow, time-bounded purge procedure only                                             | Separate break-glass authority, reason, scope, approvals, immutable pre-purge evidence, semantic audit, post-action reconciliation                | Normal application role DELETE/UPDATE, bulk unscoped purge, unaudited hard delete                               |
+| Revoked/expired/disabled identity or ended session | None beyond policy-permitted public observation                                       | Revocation/lifecycle checked from PostgreSQL on every command                                                                                     | Cached token/Valkey state cannot preserve authority                                                             |
+
+**No-oracle rule:** authentication may return 401, but once authenticated, a foreign-workspace, nonexistent, inaccessible, or wrong-project identifier must follow the one KBN-105-frozen 404/403 policy with the same response shape and no foreign metadata, timing-derived detail, or WebSocket/MCP discrepancy.
+
+## 4. Threat matrix
+
+Every disposition is against the frozen target, not a claim about current-main behavior.
+
+| ID  | Attacker or failure                                                                     | Asset                                   | Precondition and abuse path                                                                                             | Frozen preventive/detective control                                                                                                                           | Required schema/API/negative-test evidence                                                                                                                                   | Future owner                     | Residual risk                                                       | Disposition                                                                          |
+| --- | --------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| T01 | Authenticated user supplies a foreign workspace/resource ID                             | Tenant confidentiality and integrity    | Caller knows or guesses project/task/mission/team IDs and probes REST, MCP, WebSocket, repository, or Coordinator paths | `workspace_id` on every canonical row; composite relations; server-derived tenant; uniform no-oracle denial                                                   | Composite FK/unique DDL; every repository predicate includes workspace; N100-01/02, N110-01..05, N130-01                                                                     | KBN-100, 105, 110, 130           | Timing/volume side channels require operational review              | Controlled after evidence                                                            |
+| T02 | Revoked or inactive member retains an old session                                       | Ownership and mutation authority        | Authentication remains valid after workspace membership revocation                                                      | Active membership rechecked in the authoritative transaction for owners, principals, proposers, and decision actors                                           | Active/inactive membership fixtures; N100-03, N110-06/07; no cached membership authority                                                                                     | KBN-100, 110                     | Better Auth session may remain valid for unrelated features         | Controlled after evidence                                                            |
+| T03 | User joins/forges a team relation outside its workspace                                 | Team-owned projects and tasks           | Global-current-main team behavior or a stale membership is reused                                                       | Team is intra-workspace only; workspace/team composites; active workspace membership precedes team authorization                                              | Cross-workspace team/member/owner insert and command denials; N100-04/05, N110-08                                                                                            | KBN-100, 110                     | Team-role policy mistakes remain possible                           | Controlled after evidence                                                            |
+| T04 | Same-workspace IDs from a different project are combined                                | Planning hierarchy integrity            | Valid mission/milestone/parent/current-milestone UUIDs are substituted                                                  | Project-congruent composite relations and serialized hierarchy validation                                                                                     | Mission/milestone/parent/current milestone mismatch and parent-cycle tests; N100-06..10, N110-09                                                                             | KBN-100, 110                     | Deep hierarchy checks can be expensive                              | Controlled after evidence                                                            |
+| T05 | Foreign or unrelated evidence/link/artifact IDs are attached                            | Review and audit truth                  | Caller has a valid same-workspace or foreign artifact UUID                                                              | Workspace-aware joins; immutable artifact digest/revision; semantic same-target validation in authoritative transaction                                       | Mixed-workspace and same-workspace wrong-task/mission checkpoint/approval evidence tests; N100-11..14, N210-15/16                                                            | KBN-100, 110, 210                | Same-workspace semantic validation is application-enforced          | Controlled after evidence                                                            |
+| T06 | Stolen, over-scoped, or replayed service token                                          | Coordinator and task mutation authority | Service credential is accepted as admin/user or claims are trusted without DB state                                     | Command-family least privilege; agent/session workspace binding; no raw DB credentials; enabled/live state checked per command                                | Auth registry fixtures prove audience/expiry/role/capability; revoked agent and ended session denials; N105-01, N110-10..13, N210-01/02                                      | KBN-105, 110, 210                | Credential theft until expiry/revocation check                      | Controlled after evidence                                                            |
+| T07 | Caller forges public `healthy` or replays a stale health response                       | Sole-writer/fail-closed invariant       | Public health body or caller field reaches mutation context                                                             | Public DTO is observation only; public DTOs reject proof/health fields; Gateway mints internal proof after live PG transaction probe                          | Contradictory union and forbidden-field tests; N105-02, N110-14..17                                                                                                          | KBN-105, 110, 140                | Health endpoint can still be used for reconnaissance                | Controlled after evidence                                                            |
+| T08 | Internal stale, wrong-policy, or wrong-transaction proof is reused                      | Transaction integrity                   | A branded value leaks or an adapter fails to revalidate it                                                              | Non-exported brand; transaction identity, `checkedAt <= now < validUntil`, and policy revision revalidated immediately before mutation                        | Wrong transaction, expiry boundary, future timestamp, policy mismatch, commit-after-expiry tests; N110-18..22                                                                | KBN-110, 140                     | In-process code can bypass TypeScript; runtime checks are mandatory | Controlled after evidence                                                            |
+| T09 | DB/transport uncertainty is mislabeled as deliberate denial or conflict                 | Safe retry and exactly-once result      | Timeout occurs before/after commit and client changes key or retries 503                                                | Exact 503/502/504/timeout/409 union; unknown outcome retries only with same idempotency key                                                                   | Exhaustive fixture mapping and commit-before-timeout replay; N105-03, N110-23..27, N120-01/02                                                                                | KBN-105, 110, 120, 140           | External client may ignore retry rules                              | Controlled after evidence                                                            |
+| T10 | Assignment payload forges task version, target agent/session, role, expiry, or proposer | Work routing authority                  | Lease service trusts command DTO rather than persisted assignment                                                       | Persisted assignment identity; exactly-one principal/proposer; exact agent/session composite; acquire accepts IDs then reloads+locks                          | Cross-workspace and same-workspace target substitutions, stale task version, invalid role, expired assignment; N100-15..18, N210-03..08                                      | KBN-100, 200, 210                | Compromised authorized proposer can make harmful proposals          | Controlled by approval/audit                                                         |
+| T11 | Approval proof is forged by value or borrowed from another assignment                   | Gate integrity                          | Caller submits `approved=true`, unrelated decision ID, stale policy, or self-approval                                   | Relational approval bound to assignment; lock/reload; policy revision; author≠reviewer and mandatory SecReview                                                | No proof-by-value DTO; wrong assignment/task/workspace/policy/actor/decision tests; N105-04, N210-09..14, N230-01                                                            | KBN-105, 210, 230                | Colluding principals remain an organizational risk                  | Controlled after evidence                                                            |
+| T12 | Revoked policy or expired proposal/assignment is raced against lease acquisition        | Routing policy                          | Approval and lease transactions do not lock/revalidate current rows                                                     | Lock assignment, approval, task, target session; compare current policy and expiry inside fresh-proof transaction                                             | Concurrent revoke/expire/acquire tests with one valid terminal result; N210-17..19                                                                                           | KBN-210, 230                     | Clock skew if DB time is not canonical                              | Controlled after evidence                                                            |
+| T13 | Stale worker sends ack/heartbeat/checkpoint/review after reassignment                   | Canonical task and evidence state       | Old process retains task/session IDs                                                                                    | Task-row-locked atomic monotonic bigint fence; every worker command carries exact lease/session/fence                                                         | Lower, expired, future, and other-task fences denied; old worker loses after new lease; N100-19/20, N210-20..24                                                              | KBN-100, 210, 230                | Signed bigint exhaustion is theoretical                             | Controlled after evidence                                                            |
+| T14 | JavaScript precision truncates a fence                                                  | Stale-worker exclusion                  | bigint token is serialized as number above `2^53-1`                                                                     | Drizzle bigint and decimal-string wire type only                                                                                                              | `9007199254740993` and near-`int8` boundary round trips; numeric JSON rejected; N105-05, N210-25                                                                             | KBN-105, 210                     | Nonconforming external clients                                      | Controlled after evidence                                                            |
+| T15 | Checkpoint/evidence from another lease/task/session is submitted                        | Recovery and certification evidence     | Same-workspace valid IDs are mixed                                                                                      | Exact lease composite binds workspace+task+assignment/session+fence; checkpoint composite binds lease+fence; evidence join plus semantic artifact-owner check | Same-workspace mismatched task/assignment/lease/session/checkpoint/artifact tests; N100-21..23, N210-26..31                                                                  | KBN-100, 210                     | Artifact URI target may disappear outside DB                        | Controlled with digest/retention                                                     |
+| T16 | Outage note or pending/rejected proposal mutates/orders work                            | Sole SOT and gate integrity             | Importer/UI treats note/proposal as task state                                                                          | Proposals are inert; only explicit accept invokes normal typed command after recovery                                                                         | Row/outbox/task counts unchanged for pending/rejected; no readiness/dependency/lease effect; N110-28..31                                                                     | KBN-110, 140                     | Humans may act outside Mosaic operationally                         | Accepted as attributable residual                                                    |
+| T17 | Submission event is missing, foreign, or for another proposal                           | Proposal audit chain                    | Caller supplies an existing event UUID                                                                                  | Preallocated proposal ID; event-first same transaction; workspace composite FK; exact event type/aggregate/version semantic check                             | Missing/foreign/wrong-type/wrong-proposal event rolls back event+proposal; N100-24/25, N110-32..36                                                                           | KBN-100, 110                     | Semantic checks are transaction code, not only FK                   | Controlled after evidence                                                            |
+| T18 | Acceptance borrows an unrelated command event                                           | Proposal and target integrity           | Same-workspace event exists for another target/command/proposal                                                         | Accept locks proposal+target, executes normal command, requires workspace/target match, causation=submission event, payload proposal ID                       | Foreign, wrong target/type/command/causation/payload event aborts target/event/proposal atomically; N100-26, N110-37..43                                                     | KBN-100, 110                     | Event payload schema drift                                          | Controlled by KBN-105 fixtures                                                       |
+| T19 | Application role updates/deletes audit, approval evidence, checkpoint, or artifact      | Nonrepudiation                          | Broad DB grants or parent cascade exists                                                                                | INSERT/SELECT-only application roles; RESTRICT parent deletes; archive/cancel normal lifecycle                                                                | Role-level UPDATE/DELETE denied; parent delete RESTRICT; digest unchanged; N100-27..31                                                                                       | KBN-100                          | DB superuser can alter state                                        | Break-glass/infra audit residual                                                     |
+| T20 | Break-glass purge is used as routine deletion or erases its own evidence                | Retention and incident forensics        | Elevated credential available                                                                                           | Separate audited retention procedure, bounded scope, reason, pre/post evidence, authority separation                                                          | Normal role denied; expired/missing approval denied; purge cannot delete its authorizing audit package; N115-01, N230-02/03                                                  | KBN-115, 230                     | Privileged DBA compromise                                           | Accepted operational residual                                                        |
+| T21 | PostgreSQL unavailable or partitioned                                                   | Canonical state                         | Public health/Valkey remains live while transaction probe fails                                                         | Fail closed; no alternate writer/hidden queue; 503 only for proven not-applied; transport uncertainty remains unknown                                         | Fault injection proves DB rows/outbox/files/Valkey unchanged on deliberate denial; commit-unknown replay; N110-44..48, N140-01                                               | KBN-110, 140, 230                | Availability loss is intentional                                    | Accepted by Option A                                                                 |
+| T22 | Valkey unavailable, duplicated, stale, or partitioned                                   | Scheduling notifications                | Queue wake is treated as truth or publication fails                                                                     | Valkey derived/expendable; transactional outbox in PG; idempotent publisher; recovery from PG                                                                 | Commit with Valkey down leaves pending outbox; replay publishes once logically; stale wake reloads PG; N110-49, N140-02, N230-04..06                                         | KBN-110, 210, 230                | Duplicate at-least-once delivery                                    | Consumers must be idempotent                                                         |
+| T23 | Coordinator restarts between assignment, lease, checkpoint, or outbox steps             | Durable orchestration truth             | Process-local cache is treated as authority                                                                             | PostgreSQL stores assignments, execution state, leases, fences, checkpoints, events, outbox; `recoverFromPostgres`                                            | Restart at every transaction boundary reconstructs identical active/expired/pending sets without Valkey/files; N210-32..36, N230-07                                          | KBN-210, 230                     | Recovery latency                                                    | Controlled after evidence                                                            |
+| T24 | Dependency cycle or concurrent reciprocal edge                                          | Readiness and dispatch safety           | Two transactions each see an acyclic graph before inserting                                                             | Unique directed edge; no self-edge; serialized recursive cycle check; readiness evaluates all blockers                                                        | Self/duplicate/cycle and concurrent A→B/B→A tests; all predecessor property test; N100-32..35, N200-01/02                                                                    | KBN-100, 200, 230                | Very large DAG performance                                          | Bounded operational residual                                                         |
+| T25 | Parent-task cycle or project-incongruent relation                                       | Planning hierarchy                      | Valid same-workspace IDs are arranged into an invalid tree                                                              | Project-congruent composites; serialized parent-cycle/orphan validation required by REQ-PLAN-001                                                              | Self/indirect parent cycle, orphan, and cross-project mission/milestone/parent tests; N100-06..10                                                                            | KBN-100, 110                     | Cycle validation is service/transaction enforced                    | Controlled after evidence                                                            |
+| T26 | Concurrent update, duplicate retry, or idempotency payload drift                        | Aggregate consistency                   | Two clients use same version/key with different payloads                                                                | Expected-version check; semantic event and outbox in same transaction; key returns prior immutable result only for identical command                          | One update wins; stale gets 409; duplicate identical returns prior; payload drift rejected; N110-50..54, N140-03                                                             | KBN-105, 110, 140                | Long-lived clients face visible conflicts                           | Intentional user-visible residual                                                    |
+| T27 | State/event/outbox partial commit                                                       | Audit and notification consistency      | Separate transactions or exception after state write                                                                    | One PostgreSQL transaction for state+semantic event+outbox                                                                                                    | Failure injected after each insert rolls all three back; success revisions align; N110-55..58                                                                                | KBN-110, 140                     | Outbox publication remains asynchronous                             | Controlled after evidence                                                            |
+| T28 | Malicious/incorrect importer injects foreign workspace data or dispatchable work        | Migration integrity                     | Source keys collide, lineage is absent, or importer has direct DB authority                                             | Immutable source snapshots/checksums; one-way Gateway/migration-only port; workspace-safe idempotent modes; shadow records cannot dispatch                    | Foreign/malformed/duplicate/partial-resume/lineage checksum and no-dispatch tests; N300-01..08                                                                               | KBN-300, 330                     | Source data may be semantically ambiguous                           | Quarantine and owner sign-off                                                        |
+| T29 | Cutover leaves legacy writer or forward/reverse sync active                             | Sole-writer invariant                   | Credentials/processes survive switch or rollback is improvised                                                          | Writer inventory, freeze, final delta, Gateway switch, credential shutdown, no dual write; rollback authority changes after first DB mutation                 | Process/credential inventory; concurrent-writer assertion; before/after-mutation rollback rehearsal; N320-01..06, N330-01                                                    | KBN-320, 330, 340                | Missed external automation                                          | Owner-gated residual                                                                 |
+| T30 | Generated `TASKS.md`/`mission.json` is edited or parsed into DB                         | Canonical state                         | Current-main parser/writer remains reachable or file watcher imports changes                                            | Generated non-authoritative header/IDs/time/revision; no production importer; regenerate/overwrite only                                                       | Static import search, tamper/regeneration, read-only permission, source-revision parity; N120-03..07, N140-04                                                                | KBN-120, 140                     | Humans may mistake snapshots for live data                          | Header and docs mitigate                                                             |
+| T31 | N-1 compatibility copies legacy ambiguity into canonical authority                      | Data integrity                          | Nullable/global/current-main fields are guessed during backfill                                                         | Nullable-first expand; deterministic mapping or quarantine; checksums; no new-only status before switch; legacy fields retained                               | Production-shape, ambiguous owner/assignee, status shadow, JSON/config/digest, rollback tests; N100-36..44                                                                   | KBN-100                          | Quarantined records require human decision                          | Controlled by signed reconciliation                                                  |
+| T32 | Recovery posture claims durability not provided by mechanisms                           | Availability and audit retention        | Shape-only validation or optimistic RPO is accepted                                                                     | Normative validator; WAL/PITR/RPO/storage/high-assurance constraints; mechanism and restore evidence                                                          | Unknown/impossible/weakened configuration plus actual mechanism/restore tests; N115-02..08                                                                                   | KBN-115                          | Backup operator or storage compromise                               | Separate failure domain residual                                                     |
+| T33 | rc.3 frozen DDL could not create mission-scoped evidence/approval FKs                   | Tenant/evidence relational integrity    | KBN-100 generated DDL from the rc.3 contract without an exact composite candidate key                                   | rc.4 adds non-partial `missions_workspace_id_uidx(workspace_id,id)` before both dependent FKs while retaining global and project-congruent keys               | KBN-100 must execute N100-45..50: exact-key reconciliation, candidate-before-FKs, duplicate feasibility, empty/prod/N-1/rollback, and both-child foreign-workspace negatives | KBN-100 after PR/CI/#753 release | Runtime DDL remains unimplemented and must prove the frozen order   | **Resolved by rc.4 + independent APPROVE; implementation evidence remains required** |
+
+## 5. Constraint-impact matrix
+
+| Impact ID | Required invariant                          | Frozen schema impact                                                                                          | API/transaction impact                                                                                 | Required evidence                                                                                                                             | Owner                            | Status                                                                            |
+| --------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------- |
+| CI-01     | Hard workspace tenancy and no oracle        | `workspace_id`, workspace-aware unique/FKs on all canonical rows                                              | Server-derived workspace; uniform denial on all surfaces                                               | N100-01..14; N110-01..09; N130-01                                                                                                             | KBN-100/105/110/130              | Resolved by frozen controls                                                       |
+| CI-02     | Active user membership                      | Membership row plus unique `(workspace_id,user_id)`; active state retained                                    | Recheck active membership in same authoritative transaction                                            | N100-03; N110-06/07                                                                                                                           | KBN-100/110                      | Resolved; not FK-only                                                             |
+| CI-03     | Service identity least privilege/revocation | Agent/session workspace, lifecycle, state, roles, capabilities                                                | Token maps to exact agent/session; command-family allowlist; DB recheck; no admin/raw DB fallback      | N105-01; N110-10..13; N210-01/02                                                                                                              | KBN-105/110/210                  | Resolved at auth/API layer                                                        |
+| CI-04     | Project-congruent hierarchy                 | Composite project/mission/milestone/parent/current-milestone relations                                        | Lock/serialized parent-cycle and orphan validation                                                     | N100-06..10                                                                                                                                   | KBN-100/110                      | Resolved; cycle behavior required                                                 |
+| CI-05     | Health-proof authority                      | Internal branded proof has transaction/time/policy fields                                                     | Probe and revalidate on same PG transaction; no public field                                           | N105-02/03; N110-14..27                                                                                                                       | KBN-105/110                      | Resolved by frozen controls                                                       |
+| CI-06     | Assignment/approval identity                | Exactly-one principal/proposer, exact agent/session assignment, relational approval                           | Reload+lock all IDs; compare version/target/state/expiry/policy/decision                               | N100-15..18; N210-03..19                                                                                                                      | KBN-100/210                      | Resolved by frozen controls                                                       |
+| CI-07     | Monotonic bigint fencing                    | Durable bigint counter, exact lease/fence keys, one active lease                                              | Atomic increment/RETURNING; decimal-string DTO; reject every stale worker command                      | N100-19..23; N210-20..31                                                                                                                      | KBN-100/105/210                  | Resolved by frozen controls                                                       |
+| CI-08     | Proposal event chain                        | Both workspace-aware event FKs; event table created first                                                     | Exact submission/acceptance semantic checks in one transaction                                         | N100-24..26; N110-28..43                                                                                                                      | KBN-100/110                      | Resolved; semantic checks not FK-only                                             |
+| CI-09     | Immutable audit/evidence retention          | RESTRICT parents; INSERT/SELECT-only immutable tables                                                         | Archive/cancel normal flow; separately authorized purge                                                | N100-27..31; N115-01; N230-02/03                                                                                                              | KBN-100/115/230                  | Resolved by frozen controls                                                       |
+| CI-10     | DB/Valkey/outbox/restart semantics          | PG outbox and durable orchestration rows                                                                      | Fail closed; same-key uncertainty retry; Valkey reloads PG; restart from PG                            | N110-44..49; N140-01/02; N230-04..07                                                                                                          | KBN-110/210/230                  | Resolved by frozen controls                                                       |
+| CI-11     | DAG/race/idempotency/version                | Unique edge; self check; event idempotency; aggregate versions                                                | Serialized recursive cycle check; payload binding; expected-version conflict                           | N100-32..35; N110-50..58; N200-01/02                                                                                                          | KBN-100/110/200                  | Resolved by frozen controls                                                       |
+| CI-12     | Import/cutover trust boundary               | Lineage/artifact/event fields; shadow state cannot dispatch                                                   | One-way scoped importer, freeze, no direct DB/file authority, no dual writer                           | N300-01..08; N320-01..06                                                                                                                      | KBN-300/320/330                  | Resolved by frozen controls                                                       |
+| CI-13     | Generated-file no-import                    | No canonical file schema/import contract                                                                      | Projection-only package; static reachability check removes current parser from production Kanban paths | N120-03..07; N140-04                                                                                                                          | KBN-120/140                      | Resolved by frozen controls                                                       |
+| CI-14     | Mission-scoped artifact and approval FKs    | rc.4 adds non-partial `missions_workspace_id_uidx(workspace_id,id)` and retains global/project-congruent keys | KBN-100 must emit the candidate before both exact RESTRICT FKs and preserve N-1/rollback order         | N100-45..50: exact reconciliation, duplicate feasibility, empty/prod/N-1/rollback, and separate artifact/approval foreign-workspace negatives | KBN-100 after PR/CI/#753 release | **Resolved by rc.4 and independent APPROVE; future executable evidence required** |
+
+## 6. Exact future negative-test catalog
+
+These names are normative evidence identifiers for future slices. Equivalent test-file names are acceptable only if traceability retains these IDs and expected outcomes.
+
+### KBN-100 — schema and migration
+
+- **N100-01** reject every canonical child row whose `workspace_id` differs from its parent.
+- **N100-02** reject foreign-workspace link, artifact, proposal target, dependency, assignment, lease, checkpoint, approval, and event relationships.
+- **N100-03** reject an inactive/revoked member as accountable owner, proposer, decision actor, archive actor, or user principal in the authoritative command transaction.
+- **N100-04** reject a team/project relation crossing workspaces.
+- **N100-05** reject a team authorization path when the user lacks active membership in the team's workspace.
+- **N100-06** reject task→mission project mismatch.
+- **N100-07** reject task→milestone and project→current-milestone project mismatch.
+- **N100-08** reject task→parent project mismatch and self-parent.
+- **N100-09** reject indirect parent cycles under concurrent transactions.
+- **N100-10** reject mission→milestone project mismatch/orphan.
+- **N100-11** reject checkpoint artifact from another workspace.
+- **N100-12** reject checkpoint artifact owned by another same-workspace task/mission unless an explicitly frozen evidence rule permits it.
+- **N100-13** reject approval evidence from another workspace.
+- **N100-14** reject same-workspace approval evidence unrelated to the approval target.
+- **N100-15** reject zero/multiple assignment principals and zero/multiple proposers.
+- **N100-16** reject target session without its exact target agent.
+- **N100-17** reject assignment task/agent/session crossing workspaces.
+- **N100-18** reject non-positive task version and expired assignment acquisition.
+- **N100-19** concurrent lease insert permits one active lease and returns one winner.
+- **N100-20** successive leases return strictly increasing bigint fences.
+- **N100-21** reject checkpoint with another task, lease, or fence.
+- **N100-22** reject duplicate/non-monotonic checkpoint sequence.
+- **N100-23** reject evidence join for a mismatched checkpoint/task.
+- **N100-24** proposal insert without exact submission event fails atomically.
+- **N100-25** foreign/wrong-type/wrong-proposal submission event fails atomically.
+- **N100-26** foreign/wrong-target/unrelated acceptance event fails atomically.
+- **N100-27** application role cannot UPDATE/DELETE `task_events`.
+- **N100-28** application role cannot UPDATE/DELETE checkpoints/artifacts/evidence joins.
+- **N100-29** parent hard delete is RESTRICTed while audit/evidence children exist.
+- **N100-30** archive does not alter canonical lifecycle status.
+- **N100-31** purge without break-glass authority/evidence is denied.
+- **N100-32** reject dependency self-edge and duplicate directed pair regardless of type.
+- **N100-33** reject direct and indirect dependency cycles.
+- **N100-34** concurrent reciprocal dependency inserts cannot both commit.
+- **N100-35** readiness remains false until every blocking predecessor and completion condition passes.
+- **N100-36** empty DB migration succeeds after the contract amendment.
+- **N100-37** production-shape expand retains all legacy declarations.
+- **N100-38** crash/resume backfill is idempotent and checksum-stable.
+- **N100-39** ambiguous workspace/owner/assignee is quarantined, never guessed.
+- **N100-40** no `ready`/`in_review` status is emitted to N-1 readers before switch.
+- **N100-41** `mission_tasks.status` cannot remain a write source.
+- **N100-42** tags/assignee/date/mission JSON/config/description/agent fields reconcile without loss.
+- **N100-43** claimed fleet backlog rows are quarantined and imported rows cannot dispatch.
+- **N100-44** pre-switch rollback works while post-first-mutation rollback requires freeze/reconciliation.
+- **N100-45** reconcile both exact child FK column lists to the rc.4 `(workspace_id,id)` mission candidate while retaining the global `id` primary key and `(workspace_id,project_id,id)` key.
+- **N100-46** empty-DB migration creates `missions_workspace_id_uidx` before `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk`.
+- **N100-47** production-shape preflight finds no duplicate `(workspace_id,id)` groups, preserves global `id` uniqueness, and applies the candidate before both dependent FKs.
+- **N100-48** N-1 startup/read/write remains unchanged; pre-switch rollback drops both dependents before the candidate and preserves the global/project-congruent keys.
+- **N100-49** artifact insert using a valid mission ID paired with a foreign workspace fails before commit.
+- **N100-50** approval-decision insert using a valid mission ID paired with a foreign workspace fails before commit.
+
+### KBN-105/KBN-110/KBN-120/KBN-130/KBN-140 — API and P1
+
+- **N105-01** every route has an explicit user/service command-family policy; user/admin tokens cannot call service-only Coordinator mutations.
+- **N105-02** public DTO validation rejects `writeProof`, internal context, body `workspaceId`, and caller-asserted health.
+- **N105-03** fixture exhaustiveness prevents 503, 502/504/timeout, and 409 cross-mapping.
+- **N105-04** approval DTO accepts an ID and decision command only, never approval proof-by-value.
+- **N105-05** all fence fields accept/emit decimal strings and reject JSON numbers.
+- **N110-01** listing with a foreign `workspaceId` or foreign filter ID follows the frozen no-oracle denial and returns no rows/counts/cursors.
+- **N110-02** get by foreign or nonexistent aggregate ID has the same frozen denial shape and no foreign metadata.
+- **N110-03** create/update/archive with a foreign owner, parent, project, mission, milestone, tag, or target ID is denied before mutation.
+- **N110-04** dependency/proposal commands with foreign target IDs are denied with unchanged state/event/outbox counts.
+- **N110-05** REST, MCP, WebSocket, and internal Coordinator paths produce equivalent no-oracle behavior for the same foreign ID.
+- **N110-06** a revoked/inactive owner is denied even with a still-valid Better Auth session.
+- **N110-07** stale membership/team cache cannot authorize a proposer, decision actor, archive actor, or principal after revocation.
+- **N110-08** a team ID from another workspace cannot authorize or own the command target.
+- **N110-09** same-workspace but wrong-project mission/milestone/parent IDs are denied inside the transaction.
+- **N110-10** an expired service token is denied before repository access.
+- **N110-11** an audience- or workspace-mismatched service token is denied without an existence oracle.
+- **N110-12** an over-scoped service token cannot call a command family absent from its role/capability allowlist.
+- **N110-13** disabled agent or ended session revokes service-token command authority immediately on PostgreSQL recheck.
+- **N110-14** contradictory public health state/boolean combinations fail validation.
+- **N110-15** Valkey-only liveness cannot mint or substitute a PostgreSQL write proof.
+- **N110-16** caller-forged public `healthy` cannot enter internal mutation context.
+- **N110-17** public REST/MCP/CLI bodies containing health/proof fields are rejected.
+- **N110-18** an expired internal proof produces no state/event/outbox write.
+- **N110-19** a future-dated or not-yet-valid proof produces no write.
+- **N110-20** a policy-revision-mismatched proof produces no write.
+- **N110-21** a proof minted on another transaction/connection produces no write.
+- **N110-22** a proof that expires before the final pre-mutation check produces no write.
+- **N110-23** deliberate read-only/write-unavailable denial maps only to authoritative 503/not-applied/non-retryable.
+- **N110-24** timeout before commit maps to transport-unknown and permits only same-key retry.
+- **N110-25** timeout after commit maps to transport-unknown and same-key retry returns the committed canonical result once.
+- **N110-26** expected-version mismatch maps only to 409/not-applied/non-retryable.
+- **N110-27** recovery replay with a changed idempotency key cannot masquerade as the original uncertain request.
+- **N110-28** pending proposal cannot alter target fields/status/rank/version.
+- **N110-29** rejected proposal cannot affect readiness, dependencies, or gates.
+- **N110-30** pending/rejected proposal cannot create an assignment or lease.
+- **N110-31** direct proposal-row state manipulation cannot bypass normal command execution.
+- **N110-32** proposal submission without a submission event rolls back fully.
+- **N110-33** foreign-workspace submission event rolls back fully.
+- **N110-34** wrong aggregate/event type submission event rolls back fully.
+- **N110-35** same-workspace event for another proposal rolls back fully.
+- **N110-36** submission event with wrong previous/new version semantics rolls back fully.
+- **N110-37** foreign-workspace acceptance event rolls back proposal, target, event, and outbox.
+- **N110-38** same-workspace event for another target aggregate rolls back acceptance.
+- **N110-39** event from an unrelated normal command rolls back acceptance.
+- **N110-40** event caused by a different submission event rolls back acceptance.
+- **N110-41** event whose payload lacks or changes `changeProposalId` rolls back acceptance.
+- **N110-42** event for another proposal with the same target/command rolls back acceptance.
+- **N110-43** missing accepted-command event after target handling rolls back the entire transaction.
+- **N110-44** read-only-degraded denial changes no DB row/outbox/file/Valkey/provider state.
+- **N110-45** write-unavailable denial changes no DB row/outbox/file/Valkey/provider state.
+- **N110-46** PostgreSQL disconnect cannot redirect a command to any fallback writer.
+- **N110-47** commit uncertainty remains `unknown` and never becomes a fabricated 503/not-applied result.
+- **N110-48** same-key replay after recovery returns one canonical result with no duplicate event/outbox row.
+- **N110-49** Valkey publication failure leaves committed PG outbox pending and replayable.
+- **N110-50** two same-version updates produce one winner and one visible 409 loser.
+- **N110-51** identical duplicate key+payload returns the prior immutable result without another event/outbox row.
+- **N110-52** same key with payload/command drift is rejected as an idempotency conflict.
+- **N110-53** the same key in another workspace cannot reveal or reuse the first workspace's result.
+- **N110-54** stale reconnect/update cannot silently overwrite a newer aggregate revision.
+- **N110-55** failure after state write but before semantic event rolls back state.
+- **N110-56** failure after semantic event but before outbox rolls back state and event.
+- **N110-57** failure after outbox insert but before commit rolls back state, event, and outbox.
+- **N110-58** success commits matching aggregate/event/outbox revisions and correlation/causation.
+- **N120-01** CLI never retries an authoritative 503 deliberate denial.
+- **N120-02** CLI retries only transport-unknown outcomes and preserves the exact idempotency key.
+- **N120-03** generated projection header contains non-authoritative warning, workspace/project IDs, generated time, and source revision.
+- **N120-04** projection revision and records match the API snapshot revision exactly.
+- **N120-05** hand-tampering is overwritten or rejected by regeneration and never mutates PostgreSQL.
+- **N120-06** static/runtime reachability finds no parser/import path from `TASKS.md`, `mission.json`, or another export.
+- **N120-07** projection writer has no domain mutation/raw SQL/Valkey authority.
+- **N130-01** UI foreign/no-access/not-found state follows the frozen no-oracle response and renders no stale foreign data.
+- **N140-01** real-Gateway DB fault journey proves fail-closed no-fallback behavior.
+- **N140-02** real-Gateway Valkey-loss journey proves pending outbox replay.
+- **N140-03** real-Gateway concurrent update/retry journey proves version and idempotency semantics.
+- **N140-04** generated-file tamper journey proves projection parity and no import.
+
+### KBN-115/KBN-200/KBN-210/KBN-230 — recovery and coordination
+
+- **N115-01** retention purge without current break-glass authority, reason, immutable evidence, or bounded scope is denied and audited.
+- **N115-02** recovery posture with an unknown top-level or storage field is rejected.
+- **N115-03** PITR retention without WAL archival is rejected.
+- **N115-04** WAL archival with zero PITR retention is rejected.
+- **N115-05** claimed RPO better than the configured backup/WAL mechanism is rejected.
+- **N115-06** unencrypted, optional, or same-failure-domain storage is rejected.
+- **N115-07** weakened high-assurance values are rejected.
+- **N115-08** shape-only validation cannot pass without normative mechanism and restore evidence.
+- **N200-01** cyclic/incomplete dependency snapshots never become eligible.
+- **N200-02** identical immutable snapshot+policy+time returns identical ordering and explanation with no I/O/model import.
+- **N210-01** disabled agent cannot claim, ack, heartbeat, checkpoint, or submit review.
+- **N210-02** ended/offline/mismatched session cannot claim, ack, heartbeat, checkpoint, or submit review.
+- **N210-03** foreign-workspace task is rejected after lock/reload without an oracle.
+- **N210-04** stale task version is rejected before fence increment.
+- **N210-05** assignment target agent mismatch is rejected.
+- **N210-06** target session mismatch is rejected.
+- **N210-07** expired assignment is rejected.
+- **N210-08** assignment in rejected/released/expired/superseded/leased-invalid state is rejected.
+- **N210-09** missing approval is rejected.
+- **N210-10** rejected/escalated/requested approval is rejected as approval authority.
+- **N210-11** stale policy-revision approval is rejected.
+- **N210-12** foreign-workspace approval is rejected without an oracle.
+- **N210-13** approval for another assignment is rejected.
+- **N210-14** author self-approval/review is rejected when independence is required.
+- **N210-15** foreign-workspace artifact evidence is rejected.
+- **N210-16** same-workspace artifact unrelated to the assignment/task/gate is rejected.
+- **N210-17** concurrent policy revocation versus acquire cannot produce a lease under the revoked revision.
+- **N210-18** concurrent assignment expiry versus acquire cannot produce a lease after expiry.
+- **N210-19** concurrent session end versus acquire cannot produce a lease for the ended session.
+- **N210-20** lower fencing token is rejected without writes.
+- **N210-21** token from an older lease is rejected without writes.
+- **N210-22** token paired with another task is rejected without writes.
+- **N210-23** token paired with another session is rejected without writes.
+- **N210-24** token on an expired/revoked/released lease is rejected without writes.
+- **N210-25** fences above JavaScript safe integer round-trip exactly as decimal strings.
+- **N210-26** lease task does not match assignment task and is rejected.
+- **N210-27** lease agent/session does not match assignment target and is rejected.
+- **N210-28** checkpoint task does not match lease task and is rejected.
+- **N210-29** checkpoint fence does not match exact lease fence and is rejected.
+- **N210-30** checkpoint sequence duplicate/regression is rejected.
+- **N210-31** checkpoint artifact does not match workspace/task/evidence semantics and is rejected.
+- **N210-32** restart after assignment persistence reconstructs the pending assignment.
+- **N210-33** restart after lease commit reconstructs exact active lease and fence.
+- **N210-34** restart after checkpoint commit reconstructs checkpoint/recovery state.
+- **N210-35** restart during expiry/retry/quarantine reconstructs durable disposition and eligibility.
+- **N210-36** restart with pending outbox reconstructs publication work without Valkey/files.
+- **N230-01** author=self-review and missing mandatory SecReview cannot certify or complete.
+- **N230-02** normal application role cannot execute retention purge.
+- **N230-03** break-glass purge cannot delete or alter its own authorization/evidence chain.
+- **N230-04** Valkey down leaves canonical work in PostgreSQL/outbox.
+- **N230-05** duplicate wake produces one logical effect after PostgreSQL reload/idempotency.
+- **N230-06** stale wake cannot revive an expired/revoked assignment or lease.
+- **N230-07** restart with no Valkey/files reconstructs leases/retry/quarantine/outbox exactly.
+
+### KBN-300/KBN-320/KBN-330/KBN-340 — migration and cutover
+
+- **N300-01** source record targeting another workspace is denied/quarantined without an oracle.
+- **N300-02** malformed source record is rejected with attributable reject evidence.
+- **N300-03** duplicate source system/key/batch replay is idempotent.
+- **N300-04** source snapshot/checksum drift aborts apply/verify.
+- **N300-05** partial import resumes from durable lineage without duplicating state/events.
+- **N300-06** imported shadow record cannot become ready, assigned, or leased automatically.
+- **N300-07** missing source key/file/checksum/batch lineage prevents apply/sign-off.
+- **N300-08** importer cannot use direct DB, generated file, Valkey, or provider issue as canonical write authority.
+- **N320-01** cutover without a verified write freeze fails safe.
+- **N320-02** active legacy writer process or credential blocks cutover.
+- **N320-03** reverse and forward synchronization cannot run concurrently.
+- **N320-04** failed final delta/reconciliation blocks client switch.
+- **N320-05** rollback before first canonical DB mutation may switch authority back only after freeze assertion.
+- **N320-06** rollback after first canonical mutation requires freeze, DB-delta export/reconciliation, and owner decision.
+- **N330-01** rehearsal cannot sign off while counts/checksums/exceptions/writer inventory differ.
+- **N340-01** cutover cannot proceed without owner authorization, terminal evidence, scoped identities, and zero active legacy writers.
+
+## 7. Requirements traceability
+
+| Requirement      | Threats/impacts              | Planned evidence                                                |
+| ---------------- | ---------------------------- | --------------------------------------------------------------- |
+| REQ-SOT-001      | T16, T21, T22, T27, T29, T30 | N110-28..31, N110-44..49, N110-55..58, N120-03..07, N320-01..06 |
+| REQ-SOT-002      | T07, T08, T09, T21           | N105-02/03, N110-14..27, N110-44..48                            |
+| REQ-SOT-003      | T30                          | N120-03..07, N140-04                                            |
+| REQ-SOT-004      | T16..18                      | N100-24..26, N110-28..43                                        |
+| REQ-TEN-001      | T01..05, T15, T33            | N100-01..14, N100-45..50, N110-01..09, N210-15/16               |
+| REQ-ID-001       | T02, T03, T06, T10..12       | N105-01, N110-06..13, N210-01..19                               |
+| REQ-PLAN-001     | T04, T25                     | N100-06..10                                                     |
+| REQ-TASK-001     | T13, T26, T31                | N100-20, N100-37..42, N110-50..54                               |
+| REQ-TASK-002     | T16, T24                     | N110-28..31, N100-35, N200-01                                   |
+| REQ-DEP-001      | T24                          | N100-32..35, N200-01                                            |
+| REQ-ASN-001      | T10..12                      | N100-15..18, N210-03..19                                        |
+| REQ-AUD-001      | T17..20, T22, T27            | N100-24..31, N110-32..43, N110-49, N110-55..58                  |
+| REQ-API-001      | T01, T06..18, T26            | N105-01..05 plus KBN-110 catalog                                |
+| REQ-UI-002/003   | T01, T15, T26                | N130-01 and real-Gateway KBN-140 journeys                       |
+| REQ-COORD-001    | T22..24                      | N200-01/02, N210-32..36                                         |
+| REQ-COORD-002    | T10..12, T16                 | N210-03..19, N110-28..31                                        |
+| REQ-COORD-003    | T13..15, T23                 | N100-19..23, N210-20..36                                        |
+| REQ-COORD-004    | T23, T26                     | N210-32..36, N230-07                                            |
+| REQ-GATE-001/002 | T11, T19, T20                | N210-09..14, N230-01..03                                        |
+| REQ-REC-001      | T20, T32                     | N115-01..08                                                     |
+| REQ-MIG-001/002  | T28, T29, T31                | N100-37..44, N300-01..08, N320-01..06, N330-01, N340-01         |
+
+REQ-UI-001 and REQ-UI-004 are downstream functional/accessibility requirements rather than schema-threat controls; they remain owned by KBN-130/KBN-140. Their security-relevant tenancy, conflict, and stale-reconnect portions are covered above.
+
+## 8. Issue #753 acceptance mapping
+
+| Issue requirement/criterion                                     | Evidence in this document                           | Result                                         |
+| --------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------- |
+| Cross-workspace owners, principals, evidence, project hierarchy | T01–T05, T15, T25; CI-01–04                         | Mapped                                         |
+| Active membership and service-token boundaries                  | Authorization matrix; T02, T03, T06; CI-02/03       | Mapped                                         |
+| Stale/forged health and transaction-local proof                 | T07–T09, T21; CI-05                                 | Mapped                                         |
+| Assignment/approval forgery and monotonic fencing               | T10–T15; CI-06/07                                   | Mapped                                         |
+| Change-proposal abuse and event binding                         | T16–T18; CI-08                                      | Mapped                                         |
+| Immutable audit and break-glass                                 | T19/T20; CI-09                                      | Mapped                                         |
+| PostgreSQL/Valkey failures                                      | T21–T23; CI-10                                      | Mapped                                         |
+| Dependency/idempotency/version races                            | T24–T27; CI-11                                      | Mapped                                         |
+| Import/cutover and generated-file boundary                      | T28–T31; CI-12/13                                   | Mapped                                         |
+| Every schema/API/test impact explicit                           | Constraint matrix and negative-test catalog         | Mapped                                         |
+| No unresolved schema impact                                     | CI-14; rc.4 resolved-impact record                  | **PASS — none unresolved**                     |
+| Independent SecReview                                           | Homelab non-author exact commit/tree/content review | **PASS / APPROVE**                             |
+| PR merge, terminal-green main CI, and #753 closure              | Orchestrator-owned post-worker gates                | Pending; KBN-100 remains held until completion |
+
+## 9. UNRESOLVED SCHEMA IMPACTS
+
+none
+
+### Resolved-impact record — KBN010-SI-001
+
+- **Historical detection:** rc.3 lacked an exact `(workspace_id,id)` candidate key for the artifact and approval-decision mission FKs. This document's original BLOCKED verdict was correct and remains preserved in §1 and T33.
+- **Resolution:** rc.4 adds non-partial `missions_workspace_id_uidx(workspace_id,id)` before both exact dependent FKs while retaining the global primary key and project-congruent key.
+- **Reviewed object:** commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`, tree `7ebab8fa530a7180036928cea9527f808548aa14`.
+- **Corroborating identities:** full-index SHA-256 `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`; stable patch-id `058cf98026fcd1043703c866aee047c8bb144740`.
+- **Independent verdict:** Homelab non-author schema/security review **APPROVE**. It confirmed PostgreSQL candidate/FK validity, unchanged tenant and polymorphic exactly-one-target safety, RESTRICT/no-cascade semantics, N-1/rollback validity, and no shared table/index/FK/identity/fence authority collision with #757.
+- **Digest interpretation:** a command-rendered patch digest varied with rendering command/options and is non-authoritative. Git commit + tree + exact file content are canonical; stable full-index SHA-256 and stable patch-id corroborate that identity.
+- **Residual implementation obligations:** KBN-100 must create the candidate before both dependent FKs; prove production-shape duplicate feasibility without weakening global uniqueness; pass empty/prod/N-1/rollback tests; reconcile both exact FK targets; and separately reject foreign-workspace mission references for artifacts and approval decisions (N100-45..50).
+- **Implementation status:** no runtime schema, migration, API, or deployment implementation is claimed by this gate disposition.
+
+## 10. Residual risk and handoff
+
+- Active membership, polymorphic targets, same-task evidence semantics, parent/DAG cycle checks, token scope, and no-oracle behavior depend on authoritative transaction code and must not be treated as FK-only guarantees.
+- DB superuser and break-glass compromise cannot be eliminated by application constraints; separation of duties, immutable external backup/audit evidence, drills, and monitoring remain required.
+- PostgreSQL unavailability intentionally sacrifices writes for integrity. Transport-unknown outcomes remain safe only when clients preserve the exact idempotency key.
+- Imported ambiguous records remain quarantined until owner sign-off; no automated mapping may convert ambiguity into authority.
+- SI-001 is resolved at frozen contract/design-review level only. KBN-100 still owes N100-45..50 executable migration evidence.
+
+**Handoff status:** KBN-010 **PASS / GO** at rc.4. KBN-100 remains held until this PR squash-merges, terminal-green CI completes on `main`, and issue #753 closes; the orchestrator owns those remaining gates.

docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md

@@ -0,0 +1,252 @@
+# KBN-101 — Database Runtime/Migration Role Split
+
+**Status:** frozen implementation contract; rc.11 closes the target-bound importer-attestation and complete operator-document-inventory HIGH findings, awaiting independent exact-head re-review for [#771](https://git.mosaicstack.dev/mosaicstack/stack/issues/771)
+
+**Version:** 1.0.0-rc.11
+
+**Dependency:** KBN-010 → **KBN-101 foundation** → KBN-100 → **KBN-101 deployed-role certification** → KBN-105
+**Scope:** PostgreSQL standalone/federated runtime identity, the sole application DDL runner, TLS bootstrap, readiness, deployment handoff, and evidence. This documentation card changes no database, secret, deployment, CI, runtime, migration, or compose artifact.
+
+## 1. Decision, modes, and non-negotiable boundaries
+
+Current `main` has one `DATABASE_URL` path in `packages/db/src/client.ts`, `migrate.ts`, `drizzle.config.ts`, storage adapters/CLI, Gateway startup, fleet-backlog, CI, installer output, compose, and Portainer. It also has PostgreSQL DDL outside a controlled migration phase: direct Drizzle scripts, `CREATE EXTENSION` probes, a direct-DDL federated integration test, and platform init SQL. None of those current paths is certified by this contract; every implementation card below must close its listed path.
+
+| Item          | Exact name / shape                     | Rule                                                                                                                                                                                    |
+| ------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Runtime URL   | `DATABASE_URL`                         | PostgreSQL **non-owner runtime** connection. Required only by runtime services in `standalone`/`federated`; those services never receive `DATABASE_MIGRATION_URL`.                      |
+| Migration URL | `DATABASE_MIGRATION_URL`               | Required only by `mosaic-db-migrator`, the dedicated one-shot runner/Job. It is forbidden in Gateway, storage runtime, fleet, and ordinary CLI environments.                            |
+| Runtime DTO   | `DatabaseRuntimeConnectionConfigDto`   | `tier`, `databaseUrl`, `runtimeMode`; maps only `DATABASE_URL`. It is not constructible from migration configuration.                                                                   |
+| Migration DTO | `DatabaseMigrationConnectionConfigDto` | `tier`, `migrationDatabaseUrl`, `migrationMode`; maps only `DATABASE_MIGRATION_URL`, is accepted only by `mosaic-db-migrator`, and has no runtime-bootstrap import path.                |
+| TLS DTO       | `DatabaseTlsConfigDto`                 | `caCertificatePath`, `rejectUnauthorized: true`, `serverName`; validates the mounted CA without serializing its bytes. `serverName` is derived only from the validated connection host. |
+| Readiness DTO | `DatabaseSchemaReadinessDto`           | `state`, `expectedSchemaVersion`, `observedSchemaVersion`, `migrationRequired`, `roleCheck`, `checkedAt`; no URL, user, host, database name, or secret.                                 |
+| Modes         | `local`, `standalone`, `federated`     | `local` is the explicit PGlite-only exception. `standalone` and `federated` are production-like PostgreSQL modes.                                                                       |
+
+**No fallback or plaintext:** in production-like modes, missing `DATABASE_URL`, `DATABASE_MIGRATION_URL`, or `DATABASE_TLS_CA_CERT_PATH` is a phase-specific error. No command may substitute a runtime URL, config-file URL, default URL, inferred URL, or hard-coded URL. PostgreSQL URLs must use `sslmode=verify-full` with `rejectUnauthorized: true`; `disable`, `allow`, `prefer`, `require`, `no-verify`, an absent CA, a wrong CA, an unverified certificate, or host/SAN mismatch fails before readiness. PGlite uses only its configured local data directory and explicit PGlite routine; it neither reads nor interprets PostgreSQL URL/TLS variables.
+
+**ASSUMPTION K101-A1:** `standalone` and `federated` are the complete current PostgreSQL production-like modes. A future PostgreSQL tier inherits this contract until a versioned amendment names its DNS, secrets, bootstrap, and evidence.
+
+## 2. The sole PostgreSQL DDL control plane
+
+`mosaic-db-migrator` is the **only application/CI/test command that may connect with DDL authority to PostgreSQL**. It owns, in one `max: 1` PostgreSQL session: migration-DTO parse, TLS/identity/search-path preflight, advisory-lock acquisition, manifest/ledger reconciliation, migration execution, postflight/readiness verification, lock release, and session close. It rejects `DATABASE_URL`-only invocation **before opening a connection or emitting DDL**. The only exception is the external privileged platform/IaC bootstrap actor (§4/§7), which is not an application command, never receives either application URL, and executes only the fixed bootstrap artifact.
+
+**Executable contract (KBN-101-03 exclusive):** `packages/db/package.json` publishes the exact mapping `"mosaic-db-migrator": "./dist/cli.js"`; `packages/db/src/cli.ts` compiles to that target. `docker/db-migrator.Dockerfile` builds that package and has the exact image entrypoint `ENTRYPOINT ["mosaic-db-migrator"]`. KBN-101-03 alone owns package/bin/build/pack/discovery tests that execute this compiled bin and image as `mosaic-db-migrator --help|--run|--verify`. The CLI imports only private implementation modules in `packages/db/src/migrator/`; package root exports do **not** expose `runMigrations`, and no other programmatic migration API is public. The sole typed programmatic runner is private to the package/CLI boundary and accepts the typed migration DTO, never a URL/string/SQL/schema/role argument.
+
+The exact user-facing interface is `mosaic-db-migrator --run` and `mosaic-db-migrator --verify`. `--help` is required and is the only discovery mode. Both commands use the fixed packaged migration folder and accept only `DATABASE_MIGRATION_URL`, `DATABASE_TLS_CA_CERT_PATH`, and non-secret `MOSAIC_DATABASE_TIER`/correlation input from the environment. They reject `DATABASE_URL` as fallback and reject URL, SQL, schema, role, database, migration-folder, and identifier arguments in argv. Stable sanitized process exits are: `0` success; `64` configuration; `65` TLS; `66` unsafe identity; `67` ledger/schema; `68` lock contention; `69` migration failure. CI, Compose, Swarm, and each two-gateway migration Job invoke the immutable db-migrator image with exactly `mosaic-db-migrator --run`; their readiness verification invokes exactly `mosaic-db-migrator --verify`. Required tests cover `--help`, argv rejection, runtime-only refusal before connect, migration-only success, each sanitized error/lock exit, and ordered `postgres-a → mosaic-db-migrator-a → gateway-a` plus `postgres-b → mosaic-db-migrator-b → gateway-b` execution.
+
+The implementation must inventory and close every present and future entrypoint as follows:
+
+| Current entrypoint                                                                                                                                                                                                                                                                                                                    | Required rc.11 disposition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `packages/db/src/migrate.ts:runMigrations()`                                                                                                                                                                                                                                                                                          | Remove its optional URL, `DATABASE_URL`, and default fallback API from public/runtime exports. Its PostgreSQL behavior moves behind `mosaic-db-migrator`; callers cannot invoke it with an arbitrary URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `packages/db/src/index.ts`                                                                                                                                                                                                                                                                                                            | `KBN-101-03` removes the public `runMigrations` re-export; only the explicit PGlite-local API remains as separately typed local behavior. A compile/import-negative proves `@mosaicstack/db` cannot directly import `runMigrations`; a `DATABASE_URL`-only direct-library attempt fails before connect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `packages/db/drizzle.config.ts` and direct `drizzle-kit migrate`                                                                                                                                                                                                                                                                      | A database-connecting Drizzle configuration reads only `DATABASE_MIGRATION_URL` through the migration DTO and rejects its absence before connection. Replace direct `drizzle-kit migrate` exposure with `mosaic-db-migrator`. `db:generate` is an offline schema artifact command and must neither resolve nor connect to a URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `pnpm --filter @mosaicstack/db db:migrate` and CI invocation                                                                                                                                                                                                                                                                          | Make it a thin `mosaic-db-migrator` wrapper; no direct Drizzle migrator invocation remains. CI supplies an isolated disposable migration URL only to that job.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `db:push` / direct `drizzle-kit push`                                                                                                                                                                                                                                                                                                 | Forbidden for standalone, federated, CI production-like, Portainer, and any URL outside a disposable developer database. If retained for local experimentation, a wrapper requires `MOSAIC_DISPOSABLE_DEVELOPER_DB=1`, a locally allowlisted disposable target, `DATABASE_MIGRATION_URL`, verified TLS when PostgreSQL is used, and rejects `DATABASE_URL`, any production-like tier, and every non-allowlisted host/database before connection. It is never a release, repair, or migration procedure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `mosaic storage migrate --run`                                                                                                                                                                                                                                                                                                        | Delegates only to `mosaic-db-migrator`; it rejects `DATABASE_URL`-only execution before spawning or connecting. Its PGlite form remains explicitly local-only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `PostgresAdapter.migrate()`, Gateway `DatabaseModule`/startup, and PostgreSQL adapter factories                                                                                                                                                                                                                                       | Runtime PostgreSQL migration is removed: no `runMigrations`, DDL, `CREATE EXTENSION`, or migration-compatible handle is reachable from startup. Gateway performs read-only identity, TLS, `search_path`, and manifest-ledger readiness checks only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `packages/mosaic/src/commands/fleet-backlog.ts`                                                                                                                                                                                                                                                                                       | PostgreSQL fleet backlog never migrates or creates tables. It consumes a ready runtime connection; PGlite may use only its explicit local migration routine.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `packages/storage/src/{adapters/postgres,tier-detection}.ts` extension work and `infra/pg-init/01-extensions.sql`                                                                                                                                                                                                                     | Runtime probes become read-only catalog/extension-presence checks. Extension provisioning is a fixed external bootstrap prerequisite or a reviewed runner migration where the migrator has the required scoped authority; it is never a probe side effect or a reason to grant runtime database CREATE.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `packages/db/src/federation.integration.test.ts` direct type/table/index DDL                                                                                                                                                                                                                                                          | `KBN-101-02` replaces it with a pre-migrated disposable database created by `mosaic-db-migrator`, or makes the test invoke that runner. The test itself has runtime credentials and no direct DDL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `apps/gateway/src/__tests__/integration/federated-pgvector.integration.test.ts` `CREATE TEMP TABLE`                                                                                                                                                                                                                                   | `KBN-101-02` replaces the temporary runtime DDL with a runner-prepared disposable **persistent** `mosaic.federated_pgvector_fixture` database/table. The test receives only its runtime URL/CA and performs read/query-only qualified-vector assertions (including the selected vector operator); it has no setup hook, temporary privilege, or DDL. Runtime `TEMPORARY` remains denied.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `docker/init-db.sql` and `infra/pg-init/01-extensions.sql`                                                                                                                                                                                                                                                                            | `KBN-101-02` retires these duplicate tracked init artifacts; neither may remain as a hidden extension authority. The sole extension action is the fixed external bootstrap artifact described in §4/§5, or the runner only when its reviewed implementation card explicitly grants that authority.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `packages/storage/src/{cli,migrate-tier}.ts` operator/runtime command closure                                                                                                                                                                                                                                                         | `KBN-101-02` alone replaces raw SQL/DDL behavior with delegation to `mosaic-db-migrator --run` (or the explicit PGlite-local path). Data copy requires the exact paired non-secret argv references `--target-url-file /run/secrets/mosaic_migrate_target_url` and `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. The trusted `mosaic-db-migrator --verify` producer reads the exact importer target-secret file only to bind and attest it; it never uses importer credentials for DDL/DML. Before target connection the importer verifies strict files, signed target attestation, credential-file digest/version, canonical TLS/database binding, role, manifest, expiry, and replay; after verified TLS but before transaction/DML it verifies server/database identity and schema. It opens only a dedicated non-DDL `mosaic_data_importer` target connection. Its DML registry is limited to declared mutable application tables and excludes schemas, roles, memberships, extensions, extension/catalog objects, Drizzle ledger, and immutable KBN relations. Raw `--target-url`, `DATABASE_URL` fallback, runtime-owner/importer role confusion, missing/unsafe/substituted files, stale/replayed/tampered/wrong-key attestation, wrong binding, and any DDL attempt fail before target connection/DDL or copy. KBN-101-07 documents that produced interface but owns neither source file. |
+| `tools/federation-harness/docker-compose.two-gateways.yml`                                                                                                                                                                                                                                                                            | Active topology; `KBN-101-05` migrates it rather than retires it. It must contain `postgres-a`, `postgres-b`, `mosaic-db-migrator-a`, `mosaic-db-migrator-b`, `gateway-a`, and `gateway-b`; each database has separate runtime/migrator URL and CA consumers, TLS server material, verified-TLS readiness, and runner-before-Gateway ordering. Its existing plaintext URLs/init mount are forbidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `docs/fleet/backlog-conventions.md`                                                                                                                                                                                                                                                                                                   | `KBN-101-07` removes the current automatic first-use PostgreSQL `runMigrations()` claim. It points PostgreSQL operators to the sole runner/readiness sequence and labels only the PGlite routine as local-only. A documentation-route `DATABASE_URL`-only test asserts no first-use/migration instruction is executable before connect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `docs/PERFORMANCE.md`                                                                                                                                                                                                                                                                                                                 | `KBN-101-07` removes direct `drizzle-kit migrate` and Gateway-startup `runMigrations()` instructions. It points to the sole runner/readiness sequence. A documentation-route `DATABASE_URL`-only test asserts neither direct command nor Gateway fallback remains.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `README.md`, `CLAUDE.md`, `docs/guides/{admin-guide,dev-guide,deployment,migrate-tier,user-guide}.md`, `docs/federation/{SETUP,TASKS}.md`, `docs/fleet/backlog-conventions.md`, `docs/PERFORMANCE.md`, `docs/design/storage-abstraction-middleware.md`, and `docs/plans/2026-03-15-agent-platform-architecture.md` documentation hits | `KBN-101-07` owns the non-normative disposition inventory in §2.2. It replaces, retires, or labels status-only every direct `db:migrate`, `db:push`, `CREATE EXTENSION`, first-use migration, Gateway-startup migration, and generic `mosaic storage migrate` instruction with the runner/bootstrap or secure `migrate-tier` route. The architecture plan explicitly marks direct `db:migrate` superseded. Historical shipped-status language is adjacent to an exact non-authorizing KBN-101 note. Documentation is a DDL entrypoint and cannot advertise a bypass.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| New package scripts, test helpers, setup hooks, CLI commands, installers, CI steps, adapters, or operator docs                                                                                                                                                                                                                        | A repository check rejects any new PostgreSQL DDL-capable entrypoint or instruction unless it is the dedicated runner or the named external bootstrap artifact. No future script may accept a URL parameter or `DATABASE_URL` as a DDL escape hatch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+The runner must run the original migration bytes, including shipped `0009`; no migration command may repair a ledger by manual insertion, adoption, `db:push`, or schema diff. Tests requiring PostgreSQL schema consume a pre-migrated disposable database or invoke this exact runner.
+
+`KBN-101-06` alone owns `.woodpecker/ci.yml`, `tools/ci/kbn101-ddl-inventory.ts`, `tools/ci/kbn101-ddl-inventory.spec.ts`, `tools/ci/fixtures/kbn101-ddl-inventory.json`, `tools/ci/kbn101-entrypoint-matrix.ts`, and `tools/ci/kbn101-entrypoint-matrix.spec.ts`. The scanner inventory is canonical JSON whose every record has exactly `path`, `class`, `ownerCard`, `disposition`, `allowedTokens`, `rationale`, `expiry`, and `reviewRevision`. `class` is one of `executable-source`, `script-or-package-bin`, `operator-document`, `deploy-manifest`, or `normative-contract`; `ownerCard` is one KBN-101 card; `disposition` is one of `runner`, `delegate`, `deny`, `retire`, `superseded-document`, `active-secure-data-migration`, `status-only`, or `allowlisted`; and `allowedTokens` is a nonempty subset of the fixed rules below only for `allowlisted` or `superseded-document`. `normative-contract` is excluded from **operator execution**, never from scanning: it is valid only for the exact KBN PRD/contract/shared/task canonical paths, must carry declarative requirements rather than an executable shell instruction, and a fenced executable instruction or an imperative bypass in that class fails rather than being masked. An `active-secure-data-migration` record has empty `allowedTokens` and additionally pins `route`, `targetCredentialOption`, `targetCredentialFile`, `targetAttestationOption`, `targetAttestationFile`, `attestationProducer`, `attestationKeyIds`, `attestationBindings`, `targetSchemaPrerequisite`, `targetConnectionRole`, `forbiddenInputs`, and `routeTest`; its parser rejects a missing field, a route that accepts a credential value on argv, an attestation missing any canonical binding, or a target that is not runner-prepared/verified. The latter `superseded-document` disposition is allowed only for the exact architecture-plan path when adjacent text says the direct command is superseded/MUST NOT run and names `mosaic-db-migrator --run`. The scanner rejects duplicate path owners, ownerless non-allowlisted rows, missing paths, malformed fields, an inventory path outside its declared class, and every unrecognized active command. The classifier's exact case-insensitive token/rule set is: `runMigrations\\s*\\(`; `drizzle-kit\\s+(?:migrate|push)`; `\\bdb:(?:migrate|push)\\b`; `mosaic\\s+storage\\s+migrate`; `CREATE\\s+(?:TEMP(?:ORARY)?\\s+)?(?:EXTENSION|TABLE|TYPE|INDEX|SCHEMA)`; `ALTER\\s+(?:EXTENSION|TABLE|TYPE|SCHEMA)`; `DROP\\s+(?:EXTENSION|TABLE|TYPE|INDEX|SCHEMA)`; and `DATABASE_URL` when it occurs in the same file as any preceding rule. It scans exact-path current executable source/scripts/package bins, operator documents, deploy manifests, and named normative contracts; any hit not represented by a permitted inventory record fails. The matrix harness invokes the compiled runner/package/image and produced deployment artifacts; it edits no producer file.
+
+The canonical inventory includes this active—not historical—operator route record: `path=docs/guides/migrate-tier.md`, `class=operator-document`, `ownerCard=KBN-101-07`, `disposition=active-secure-data-migration`, `allowedTokens=[]`, `route=mosaic storage migrate-tier`, `targetCredentialOption=--target-url-file`, `targetCredentialFile=/run/secrets/mosaic_migrate_target_url`, `targetAttestationOption=--target-attestation-file`, `targetAttestationFile=/run/mosaic-attestations/migrate-target.v1.json`, `attestationProducer=mosaic-db-migrator --verify`, `attestationKeyIds=[migrate-target-v1-active,migrate-target-v1-overlap]`, `attestationBindings=[credentialSecretVersion,credentialFileSha256,tlsHostPortDatabase,caSpkiFingerprint,postgresSystemIdentifier,databaseOid,expectedImporterRole,manifestFingerprint,schemaFingerprint]`, `targetSchemaPrerequisite=mosaic-db-migrator --verify`, `targetConnectionRole=mosaic_data_importer`, `forbiddenInputs=[--target-url,DATABASE_URL,runtime-owner,signing-key]`, and `routeTest=packages/storage/src/migrate-tier.spec.ts::secureTargetRouteAndAttestation`. The -06 scanner/matrix must reject a changed/missing field, any `--target-url` or credential-bearing argv, a `DATABASE_URL` target fallback, a missing/unsafe/substituted credential file, missing/stale/replayed/tampered/wrong-key attestation, wrong binding, wrong mode, runtime-owner/importer confusion, target connection before attestation verification, or any DDL attempt before target connection/DDL.
+
+### 2.1 Target-bound importer attestation v1
+
+`mosaic-db-migrator --verify` is the trusted producer only after its verified-TLS identity, manifest/ledger, and schema checks pass. Its root-owned launch wrapper is the sole reader of the fixed `MOSAIC_DB_ATTESTATION_SIGNING_KEY_FILE=/run/secrets/mosaic-db-migrate-target-ed25519` reference: that regular, non-symlink `root:root` `0400` Ed25519 private-key file is mounted only to the one-shot runner. It opens the key once, passes signing capability only in memory to `mosaic-db-migrator`, and never mounts, forwards, logs, prints, or otherwise exposes the private key to the importer, runtime, or an application container. KBN-101-05 renders both that runner-only secret and the importer-only pinned public-key/key-ring mount; an alternative env path, unsafe key file, or key material in importer/runtime is a hard failure.
+
+After verification the runner atomically emits the credential-free, non-secret `0444` controlled artifact `/run/mosaic-attestations/migrate-target.v1.json`: write a same-directory `0600` temporary file, write canonical bytes, `fsync` file and directory, set final owner/mode, and rename atomically. The single JSON envelope carries an RFC 8785 JCS canonical UTF-8 `attestation` payload plus a detached Ed25519 `signature` envelope (`algorithm`, `keyId`, base64 signature); the signature covers only the canonical payload bytes, never a reformatted document. The v1 payload fields are exactly `format`, `version`, `keyId`, `issuedAt`, `expiresAt`, `nonce`, `targetCredentialSecretVersion`, `targetCredentialFileSha256`, `tlsHost`, `tlsPort`, `database`, `caSpkiFingerprint`, `postgresSystemIdentifier`, `databaseOid`, `expectedImporterRole`, `manifestFingerprint`, `schemaFingerprint`, `producerInvocation`, `producerBuildDigest`, `producerImageDigest`, and `correlationId`. It contains no URL/DSN, username, password, private key, or credential bytes. The target credential must be a high-entropy DSN secret because its SHA-256 is non-secret binding evidence, never a substitute secret.
+
+For binding, the runner receives and reads the exact importer target-secret file only after `lstat` regular-file/no-symlink/owner/mode checks. It derives the secret version and SHA-256 from those exact bytes, parses only canonical TLS host/port/database without retaining username/password, verifies that tuple plus CA/SPKI, PostgreSQL system identifier, database OID, manifest/schema fingerprints, and expected `mosaic_data_importer` role against its verified target, then signs. The runner uses `DATABASE_MIGRATION_URL` for its verification connection; it does not use importer credentials for DDL or DML.
+
+`mosaic storage migrate-tier` accepts exactly `--target-url-file /run/secrets/mosaic_migrate_target_url` and `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. Before **any** target connection it `lstat`s both files; validates the pinned public key/key ID, signature, JCS canonicality, expiry, nonce replay cache, secret version, target-file digest, canonical host/port/database, CA binding, expected importer role, and manifest/schema fields; then opens the validated URL fd once, digests and parses those in-memory bytes, and connects from those same bytes with no reread. Missing, substituted, changed-after-check, stale, replayed, tampered, wrong-key, or wrong-binding inputs return stable sanitized attestation errors with **zero target connection and zero DDL**. The nonce replay cache is durable through the artifact expiry window and atomically claims `(keyId, nonce, credentialFileSha256)` before connecting; a replay is terminal. New active and overlap public keys are pinned by key ID; rotation accepts only the bounded overlap, revocation removes a key immediately, and any credential secret-version rotation invalidates prior artifacts and requires a fresh runner verification/signature.
+
+Only after verified TLS connection and before transaction/DML, the importer compares server system identifier, database OID, `current_user`, CA/SPKI, and manifest/schema fingerprint with the attestation. A mismatch closes the connection with **zero DML/DDL**. Its grants and statement classifier make DDL impossible. KBN-101-02 tests missing/wrong/stale/replayed/tampered attestation, wrong/revoked key, substituted URL file, file changed after check, wrong host/database/CA/role/manifest/system ID, digest/version mismatch, and both `zero target connection` versus `connection then zero DML` outcomes. KBN-101-03 tests JCS/signing/atomic producer semantics; KBN-101-05 tests private/public key and artifact mounts/rendering; KBN-101-06 invokes the complete matrix; KBN-101-07 owns the operator guide only.
+
+### 2.2 Complete current documentation disposition inventory
+
+The KBN-101-06 fixture records these exact non-normative paths: `README.md`, `CLAUDE.md`, `docs/federation/SETUP.md`, `docs/guides/admin-guide.md`, `docs/guides/dev-guide.md`, `docs/guides/deployment.md`, `docs/guides/migrate-tier.md`, `docs/guides/user-guide.md`, `docs/fleet/backlog-conventions.md`, `docs/PERFORMANCE.md`, `docs/plans/2026-03-15-agent-platform-architecture.md`, and `docs/design/storage-abstraction-middleware.md` as `operator-document`; each is runner/delegate/deny/superseded/active-secure as adjacent text specifies. `docs/federation/TASKS.md` is an exact `operator-document` `status-only` historical record: its shipped M1 language is superseded and cannot authorize current DDL, extension creation, or importer execution. `docs/PRD.md`, this contract, `SHARED-CONTRACT.md`, and `native-kanban-sot/TASKS.md` are exact `normative-contract` records; their declarative KBN requirements are scan-visible but excluded from operator execution and cannot mask an instruction. The full-doc scanner must fail an unknown active command, a missing record, or a status-only/normative path containing executable bypass guidance.
+
+The only allowlist categories are `historical-sql` (`packages/db/drizzle/**`, byte-immutable runner input only), `pglite-local` (an explicitly PGlite-only source/test path), `negative-test-literal` (a focused negative test), `vendored-generated` (a generated or vendored artifact), and `historical-review-report` (`docs/reports/**` only). Every allowed record names its exact path, token(s), rationale, expiry, and review revision. No allowlist category is valid for an executable current source/script/package bin, operator document, deploy manifest, `README.md`, `CLAUDE.md`, `docs/plans/**`, or `docs/guides/**`; `historical-review-report` cannot contain an operative command. Scanner self-tests place each token in an unowned current path, prove duplicate-owner/ownerless/path-existence failure, and prove an operative `db:migrate` instruction in a path labeled historical fails rather than being masked. The scanner is a classifier plus path inventory and review—not a naive token scan alone—and never by itself proves DDL authority. For every non-allowlisted inventory row and `gateway-a`/`gateway-b`, the matrix proves `DATABASE_URL`-only, missing migration URL, direct library import, direct Drizzle, `db:push`, init artifact, operator route, runtime-only fixture/test, and each harness migration Job/Gateway fail before connection/DDL as applicable. The `db:push` negatives also cover production-like tier and production-like URL rejection.
+
+## 3. Exact migration manifest, ledger, and lock
+
+### 3.1 Manifest v1
+
+The runner generates and verifies a source-controlled **migration manifest v1** from the shipped Drizzle journal and SQL files. A record has exactly:
+
+```text
+logicalIndex: non-negative integer from journal array position
+journalTag: exact journal `tag` string
+migrationSha256: lowercase SHA-256 of the exact migration `.sql` file bytes
+```
+
+The canonical SQL bytes are the raw Git blob bytes at the signed source-release commit, not workstation checkout bytes. KBN-101-03 adds/validates an LF-pinning `.gitattributes` rule for `packages/db/drizzle/**/*.sql`, generates the source-controlled manifest from those canonical blobs in CI, and makes the runner verify deployed file bytes against the manifest before DDL. No newline, Unicode, whitespace, SQL, or line-ending normalization is applied. Manifest canonical serialization is UTF-8 bytes of:
+
+```text
+mosaic-drizzle-manifest-v1\n
+<logicalIndex>\t<JSON.stringify(journalTag)>\t<migrationSha256>\n
+... in ascending logicalIndex with no omitted index
+```
+
+`manifestSha256` is SHA-256 of those canonical bytes. The manifest has no timestamp-derived ordering; `folderMillis`, legacy ledger `id`, and `created_at` are diagnostic only. KBN-101-03 corrects journal **logical** order metadata (including the current `0008`/`0009` anomaly) without changing shipped `0009` bytes.
+
+The runner stores certification in `drizzle.__mosaic_migration_manifest` with exactly one active v1 row (`manifest_version=1`, `manifest_sha256`, `certified_at`). It is owned by `mosaic_schema_owner`; only the migrator after `SET ROLE mosaic_schema_owner` may insert/update it; runtime gets `SELECT` only, and `PUBLIC` gets no schema/table privilege. Existing databases receive this table through the runner after backup/preflight; it is not created by Gateway, a test, or manual SQL.
+
+### 3.2 Reconciliation and 0009 transition
+
+The expected ledger is the ordered list of v1 manifest tuples. The runner reads every observed `drizzle.__drizzle_migrations.hash`, maps **each observed hash to exactly one** manifest tuple, and rejects a missing, unknown, duplicate, ambiguous, corrupt, or stale-replica mapping. Equality is tuple-complete: every expected tuple occurs once, no additional tuple occurs, and the manifest digest matches. A count comparison or hash-set comparison is forbidden. Physical legacy insertion `id`, insertion timestamp, and order are expressly non-normative.
+
+For an existing database:
+
+1. take the KBN-101-07 approved backup and capture a read-only inventory before changing anything;
+2. if `0009` is missing **and** its effects are absent, run the original shipped `0009` through `mosaic-db-migrator` and record it normally;
+3. if the `0009` hash is present but physically late, accept it when its one-to-one tuple mapping is exact;
+4. if an expected hash is missing while its effects are partial or complete, or catalog/ledger evidence conflicts, fail closed as `DATABASE_MIGRATION_RECONCILIATION_AMBIGUOUS`. Recovery is backup restoration or an explicit separately reviewed repair artifact with its own owner, tests, backup, rollback, and approval—not manual ledger insertion/adoption; and
+5. write/update the v1 certification row only after exact reconciliation and final catalog/readiness verification.
+
+Required runner tests cover clean, pre-0009, skipped-0009/effects-absent, applied-late, duplicate, unknown, missing, corrupt tuple-pair, partial/full-effect ambiguity, stale replica, backup/restore, and rerun idempotence. The tests prove the `0009` SQL bytes are unchanged and logical journal ordering—not physical ledger order—controls reconciliation.
+
+### 3.3 Fixed advisory-lock namespace
+
+Before any preflight that can decide migration state, `mosaic-db-migrator` acquires `pg_try_advisory_lock(1297044289, 1262636593)`. The constants are signed-int4-safe fixed namespace values: class `1297044289` (`MOSA`) and object `1262636593` (`KBN1`). The same `max: 1` session retains it for preflight, reconcile, migrate, verify, release, and close. Failure returns `DATABASE_MIGRATION_LOCKED` immediately; a process crash releases it when the PostgreSQL connection closes. Runtime readiness remains unready while a holder is active and never waits by running migrations. Tests prove concurrent contention, crash/connection-loss release, readiness while held, and non-interference from an unrelated advisory key.
+
+## 4. PostgreSQL roles, identifiers, and trusted sessions
+
+Role creation, passwords, membership, database ownership, certificates, and Vault values are platform/IaC/operator work—not Drizzle/application migrations. Application SQL must not issue credential/role management statements or embed credentials.
+
+| Role                              | Attributes and ownership                                                                                                                                                                                                                                                    | Membership / session use                                                                                                                                                                                                                                                                                                                                                                                                             |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mosaic_platform_database_owner`  | `NOLOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`; platform-only database owner after bootstrap.                                                                                                                                                      | Never granted to application roles.                                                                                                                                                                                                                                                                                                                                                                                                  |
+| external platform bootstrap actor | Provider/operator/IaC-controlled, externally audited **superuser** identity outside the Mosaic role graph and Vault/application configuration.                                                                                                                              | Creates/transitions the database and roles, then retires from application use. It alone `SET ROLE`s the extension owner for `CREATE EXTENSION`, `ALTER EXTENSION ... UPDATE`, or `ALTER EXTENSION ... SET SCHEMA`, records the action, and `RESET ROLE`s.                                                                                                                                                                            |
+| `mosaic_schema_owner`             | `NOLOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`; owns only `mosaic`/`drizzle` schemas and application/ledger objects. It has only `USAGE` on `mosaic_extensions` for fixed legacy type resolution.                                                  | Never an application login; no ownership, `CREATE`, `ALTER`, `DROP`, extension/member-change, or default-privilege authority in `mosaic_extensions`; its migrator subphase never receives temporary `CREATE` there.                                                                                                                                                                                                                  |
+| `mosaic_extension_owner`          | Dedicated `NOLOGIN SUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS` extension owner, distinct from platform/schema/migrator/runtime. It is used solely to own/maintain untrusted `vector`, `mosaic_extensions`, and every owner-bearing extension member there. | `rolcanlogin=false`, `rolsuper=true`, and **zero members** are catalog-proven. No application role has membership, `SET ROLE`, credential, or inheritable grant. An externally controlled, audited platform-bootstrap **superuser** session alone executes `SET ROLE mosaic_extension_owner` for fresh creation, approved-owner update/relocation, or shadow bootstrap, then `RESET ROLE`; no persistent membership is ever granted. |
+| `mosaic_migrator`                 | `LOGIN NOINHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`.                                                                                                                                                                                            | Only `mosaic_schema_owner`; runner verifies `session_user=mosaic_migrator`, `SET ROLE mosaic_schema_owner`, then `current_user=mosaic_schema_owner`.                                                                                                                                                                                                                                                                                 |
+| `mosaic_data_importer`            | `LOGIN NOINHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`; dedicated data-copy identity, not a DDL or schema owner.                                                                                                                                   | It is used only after runner preparation/verification through the KBN-101-02 file-reference interface. It has no owner/migrator/extension membership and cannot `SET ROLE mosaic_extension_owner`, or `ALTER`/catalog-or-extension-member `UPDATE`/`DROP`/change extension membership. Its bounded data-copy DML is not extension authority.                                                                                         |
+| `mosaic_runtime_capability`       | `NOLOGIN` and no ownership/administrative attributes.                                                                                                                                                                                                                       | Holds only named runtime grants.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `mosaic_runtime`                  | `LOGIN INHERIT` with no ownership/administrative attributes.                                                                                                                                                                                                                | Only `mosaic_runtime_capability WITH INHERIT TRUE, SET FALSE, ADMIN FALSE`; never owner/migrator member.                                                                                                                                                                                                                                                                                                                             |
+
+The fixed application/runtime schema is **`mosaic`**. Every application/runtime pooled connection executes and verifies exactly `SET search_path TO pg_catalog, mosaic` before its first application query; connection checkout repeats this after reset/reconnect. Transactional application operations use `SET LOCAL search_path TO pg_catalog, mosaic` and verify it before query execution. `public` and `$user` are forbidden in all runtime paths.
+
+The sole runner has one narrowly bounded **legacy-history bootstrap subphase** for the immutable current journal: before it runs, external bootstrap revokes `CREATE` on `public` from `PUBLIC`, temporarily assigns its ownership to `mosaic_schema_owner`, and denies all runtime connections. The externally controlled audited bootstrap-superuser session first executes `SET ROLE mosaic_extension_owner` to create/own `mosaic_extensions` and fresh `vector`, or to perform approved-owner relocation/update, records that control-plane action, and executes `RESET ROLE`; it receives no membership because a superuser can assume the role without one. In its locked `max:1` migration session only, after `SET ROLE mosaic_schema_owner`, the runner has only `USAGE` (not ownership or `CREATE`) on `mosaic_extensions` and uses the fixed legacy-only `SET LOCAL search_path TO pg_catalog, public, mosaic_extensions` solely so immutable `0001` resolves its unqualified existing `vector` type. It cannot create, alter, drop, reassign, or change a member there. The preflight catalogs `pg_namespace.nspowner`, schema ACL/default ACLs, `pg_extension.extowner`, and member owners, then directly proves `CREATE`/`ALTER`/`DROP`/member-change denial for runtime, migrator, and schema owner. After relocation/catalog verification and before manifest certification or any runtime readiness, the runner transfers `public` ownership to `mosaic_platform_database_owner`, revokes application `USAGE`/`CREATE`, and restores `pg_catalog,mosaic`. This compatibility subphase is not a runtime/operator option, accepts no configuration identifier, has no fallback, and is removed/disabled before KBN-101-08.
+
+`KBN-101-03` exclusively owns `packages/db/src/schema.ts`, `packages/db/drizzle/meta/*`, `packages/db/drizzle/meta/_journal.json`, the generated relocation migration, and exact database/Drizzle tests. It freezes one exported `export const mosaic = pgSchema('mosaic')`; every application `pgTable` and every application `pgEnum` must be declared through that export. The generated snapshot/journal and future `db:generate` output must target `mosaic` only; a static declaration/SQL test rejects a default-schema application `pgTable`/`pgEnum`, `public` application declaration, or future generated application DDL outside `mosaic`. Historical `0000` through current SQL and the shipped journal provenance are byte-immutable and execute only in the trusted legacy-`public` subphase; they are never rewritten to claim they originally targeted `mosaic`.
+
+### 4.1 pgvector ownership and supported transition
+
+The selected extension policy is fixed for PostgreSQL 17 + pgvector 0.8.2. Its actual target-image `vector.control` evidence must show `relocatable = true` and no `trusted = true` or `superuser = false` setting: `vector` is therefore untrusted and creation requires superuser authority. Fresh databases: the external audited bootstrap-superuser session executes `SET ROLE mosaic_extension_owner`, creates and owns `mosaic_extensions`, then creates `vector` as `CREATE EXTENSION vector WITH SCHEMA mosaic_extensions`; it records the control-plane action and executes `RESET ROLE`. Under that role it revokes default `TABLES`, `SEQUENCES`, `FUNCTIONS`, `TYPES`, and `SCHEMAS` privileges from `PUBLIC`, `mosaic_schema_owner`, `mosaic_migrator`, `mosaic_data_importer`, and `mosaic_runtime`, then grants only the explicitly required read/type/function privileges. It validates `rolcanlogin=false`, `rolsuper=true`, zero role members, `pg_namespace.nspowner`, `pg_extension.extowner`, and owner-bearing extension-member ownership/schema/version (ownerless PostgreSQL catalog member classes are verified as ownerless, never falsely assigned), schema/default privileges, `RESET ROLE`, and the external audit record. Approved-owner update/relocation is likewise performed only by that external session while set to `mosaic_extension_owner`; the existing path is eligible only when `extowner` is already exact. `mosaic_extensions` remains non-writable by runtime, migrator, schema owner, importer, and every service role. They have no membership in `mosaic_extension_owner` and must fail catalog assertions plus `SET ROLE`, `CREATE`/`ALTER`/`DROP EXTENSION`, extension-member `UPDATE`/DDL, and role-membership change denials. Shadow migration and rollback repeat these owner/default-privilege/preflight assertions before copying, before atomic switch, after resume, and before read-only rollback.
+
+PostgreSQL has **no supported** `ALTER EXTENSION ... OWNER TO`. No card may invent it, mutate system catalogs, use `DROP ... CASCADE`, or adopt legacy extension ownership. An existing `vector` is eligible for the clean in-place path only when `pg_extension.extowner` already resolves to the approved `mosaic_extension_owner`; after exact supported-version, `extrelocatable=true`, dependency, and complete expected member-set checks, the bootstrap actor may perform the tested `ALTER EXTENSION vector SET SCHEMA mosaic_extensions`. The same postflight verifies `extowner`, each member owner/schema, version, dependency inventory, and denial for runtime/migrator/schema owner.
+
+A `vector` extension owned by a legacy runtime/single login is **not activated in place**. It fails closed before activation and requires this controlled shadow-database migration: (1) approved backup and read-only inventory; (2) create new database/roles; (3) the audited external bootstrap-superuser session `SET ROLE mosaic_extension_owner`, creates `mosaic_extensions`/`vector`, records the audit event, and `RESET ROLE`; (4) sole runner applies migrations and relocation; (5) copy data with vector dimensions, row counts, checksums, FK, and sequence evidence; (6) quiesce/drain writers; (7) apply and verify final delta; (8) prove role/TLS/readiness; (9) atomically switch connections; and (10) retain the old database read-only for the approved rollback window. Partial/cancel/resume and rollback preserve the old read-only source until the switch; no target unable to shadow-migrate is eligible until separately reviewed. Required tests cover fresh, approved-owner clean existing relocation, legacy-owner shadow path, partial/resume/rollback, N-1, exact `extowner`/member/schema/version assertions, and `SET ROLE`/ALTER/DROP/member-update denials for runtime, migrator, schema owner, importer, and all service roles.
+
+**Superuser exception and threat boundary:** PostgreSQL superuser authority cannot be privilege-limited by `GRANT`/`REVOKE`; this is deliberately **not** a least-privilege claim for `mosaic_extension_owner`. The containment is its dedicated identity, `NOLOGIN`, zero membership, absence from runtime credentials/Vault/application containers, external control-plane-only audited use, and independent review. Any extension create/update/schema operation is a control-plane change requiring independent review, approved backup/rollback, maintenance window, and audit evidence. A managed target that cannot establish this exact `NOLOGIN SUPERUSER`, zero-member, externally controlled role is ineligible until an independently approved, versioned provider-owned extension-owner profile exists; it must not silently retain app/migrator ownership.
+
+`schema.ts` must emit `mosaic_extensions.vector(...)`, and all vector casts/operators/functions in runner, application queries, fixtures, and generated SQL must explicitly qualify `mosaic_extensions` (for example `OPERATOR(mosaic_extensions.<->)`); `mosaic_extensions` is deliberately **not** added to runtime `search_path`.
+
+Before relocation, the runner records a parameterized catalog inventory and dependency graph. It must classify, in dependency order, application enum/domain/base types; owned and identity sequences; application tables; table columns/defaults; functions/procedures; views/materialized views; extension-owned objects; then triggers, constraints/FKs, indexes, and dependent rules/policies. It moves base types, sequences, tables, and functions as required; OID-bound constraints/indexes follow their owning objects and are catalog-verified rather than recreated blindly. Every object must be expected exactly once and be in either the immutable legacy/bootstrap allowlist, the `mosaic` application allowlist, or the selected `mosaic_extensions` extension membership; unknown, extra, duplicate, cross-schema, dependency-cycle, or partial-resume state fails closed. No raw client-side identifier interpolation is allowed.
+
+`KBN-101-00` owns bootstrap-role/schema/extension/default-privilege and direct-denial tests. `KBN-101-03` owns the runner integration tests that consume those bootstrap fixtures: approved-owner existing relocation, legacy-owner shadow migration, interrupted/partial relocation resume, partial/cancel shadow resume, and pre-activation reverse rollback-before-activation. Reverse rollback is allowed only before KBN-101-08 and restores the approved backup or the reviewed inverse relocation, never a runtime `search_path` bypass. Its N-1 order is: current legacy release → inactive bootstrap/runner and `mosaic` declarations → catalog relocation/generated-artifact verification or approved shadow migration → verified non-owner runtime activation. The combined evidence includes byte-immutable historical execution, no public application objects/declarations/future SQL, vector type/cast/operator query success under fixed `pg_catalog,mosaic`, exact extension-owner/member/schema/version assertions, catalog and direct ALTER/DROP/member-change denials for runtime/migrator/schema owner, and all extension eligibility negatives.
+
+No SQL identifier may come from URL/config/environment/operator input. Catalog comparisons use parameter values. The fixed identifiers above are constants; the external bootstrap artifact alone may use server-side `format('%I', fixed_allowlisted_identifier)` after allowlist validation. Raw client-side interpolation for identifiers, `SET search_path`, database, schema, role, table, or extension names is forbidden. Tests include injection-shaped values, a poisoned pooled-session reset, and transaction `SET LOCAL` restoration negatives.
+
+External bootstrap executes `REVOKE CONNECT, TEMPORARY ON DATABASE <fixed_database> FROM PUBLIC`, then grants `CONNECT` only to `mosaic_runtime`, `mosaic_migrator`, and the time-bounded external bootstrap actor while it is required. Certification fails if an unrelated login retains `CONNECT` or either application login retains `TEMPORARY`. Runtime receives `USAGE` on `mosaic`, named table/sequence grants through `mosaic_runtime_capability`, and `USAGE` on `drizzle` plus `SELECT` only on `drizzle.__drizzle_migrations` and `drizzle.__mosaic_migration_manifest`. `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and DDL rights on ledger/manifest are revoked. Revoke public CREATE and function EXECUTE; `SECURITY DEFINER` is forbidden unless a separately reviewed exception pins trusted path and grants only the capability role. Database TEMPORARY, role management, extension, schema, and object ownership are denied.
+
+Immutable KBN relations, after KBN-100 creates them, grant runtime only `SELECT, INSERT` and explicitly deny `UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER`: `task_events`, `artifacts`, `task_checkpoints`, `task_checkpoint_artifacts`, and `approval_decision_artifacts`. KBN-100 retains RESTRICT/no-cascade semantics. Foundation certification verifies the role/schema boundary only; post-KBN-100 certification verifies this real deployed-role matrix.
+
+## 5. Deployable verified-TLS bootstrap
+
+`mosaicstack/stack` is the named repository/control plane. Ownership is intentionally non-overlapping: **KBN-101-00 exclusively owns** the versioned external bootstrap interface `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, and `infra/pg-bootstrap/README.md`, plus its bootstrap tests—roles, extension-owner transition, and no renderer/deployment manifests. **KBN-101-05 exclusively owns** `tools/db/render-postgres-secrets.ts`, its tests, the current `docker-compose.yml`, `docker-compose.federated.yml`, `deploy/portainer/federated-test.stack.yml`, `tools/federation-harness/docker-compose.two-gateways.yml`, and `apps/gateway/Dockerfile`; it consumes the versioned KBN-101-00 bootstrap interface and owns no bootstrap SQL. The named **Mosaic deployment control plane / Jason** is activation authority; the environment-specific IaC/Vault owner supplies only approved input secret versions and may not substitute an unreviewed current-repository artifact. The KBN-101-05 renderer is the only deployment handoff: it reads secret-provider references, validates owners/modes/digests/SANs, writes each output atomically (`mkstemp` on the target tmpfs, `fsync`, `chmod`/`chown`, atomic rename), and records only secret-version identifiers and hashes.
+
+`KBN-101-05` changes the Gateway image to fixed non-root `USER 10001:10001`. Gateway CA and Gateway leaf-certificate mounts, and its own Gateway private key only when it terminates its HTTPS listener, must be readable by `10001:10001`; PostgreSQL private keys and migration-only material are never mounted there, and no secret is world-readable. PostgreSQL is not assigned a guessed UID/GID: its image must first be pinned by digest, and an image-inspection plus rendered Compose/Swarm test freezes the image's effective PostgreSQL UID:GID before the renderer selects mount owner/group. A digest, service UID/GID, rendered secret `uid`/`gid`/`mode`, or container `USER` mismatch is a KBN-101-05 failure. Mosaic applications never generate, self-sign, copy, or persist production certificates; the external bootstrap actor receives them only through the deployment secret mechanism and no plaintext development exception exists for production-like modes.
+
+| Material                    | Vault target / deployment secret                                                                                        | Mount, injection, and authorized consumer                                                                                                                                                                                                                         |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Runtime URL                 | `secret-{env}/mosaic-stack/database/runtime` (`url`) → `mosaic-db-runtime-url-v1`                                       | Gateway only: `/run/secrets/mosaic-db-runtime-url`, `0600`, `10001:10001`; entrypoint maps it to `DATABASE_URL` only at process exec. It is denied to every migrator, storage runtime, fleet, ordinary CLI, and test except an explicit runtime-negative fixture. |
+| Migration URL               | `secret-{env}/mosaic-stack/database/migrator` (`url`) → `mosaic-db-migrator-url-v1`                                     | Each one-shot migrator only: `/run/secrets/mosaic-db-migrator-url`, `0600`, fixed migrator UID:GID asserted by the image/render test; entrypoint maps it only to `DATABASE_MIGRATION_URL`. It is denied to Gateway, storage runtime, fleet, and ordinary CLI.     |
+| Attestation signing key     | `secret-{env}/mosaic-stack/database/migrate-target-attestation` (`private_key`) → `mosaic-db-migrate-target-ed25519-v1` | Runner root-wrapper only: fixed `/run/secrets/mosaic-db-migrate-target-ed25519`, `root:root` `0400`, referenced only by `MOSAIC_DB_ATTESTATION_SIGNING_KEY_FILE`; no importer/runtime/Gateway mount or log/export is permitted.                                   |
+| Attestation public key ring | versioned deployment public-key bundle → `mosaic-db-migrate-target-ed25519-public-v1`                                   | Importer only: pinned `/run/mosaic-attestations/migrate-target.ed25519.pub`, `0444`; active/overlap key IDs are explicit and revoked IDs fail closed. It contains no private key.                                                                                 |
+| Target attestation artifact | runner-produced non-secret file                                                                                         | Controlled shared mount `/run/mosaic-attestations/migrate-target.v1.json`, `0444`, atomic write/rename only; importer may read it but cannot write it.                                                                                                            |
+| CA bundle                   | `secret-{env}/mosaic-stack/database/tls-ca` (`certificate`) → `mosaic-db-ca-v1`                                         | Gateway/migrator: `/run/secrets/mosaic-db-ca.crt`, `0444`, owned by the consuming UID:GID; CA is public trust material. PostgreSQL receives a distinct read-only CA copy only when client-cert validation is enabled.                                             |
+| Gateway leaf certificate    | `secret-{env}/mosaic-stack/federation/gateway-server-tls` (`certificate`) → `mosaic-gateway-server-cert-v1`             | Gateway only: `/run/secrets/mosaic-gateway-server.crt`, `0444`, `10001:10001`; renderer emits this exact Compose and Swarm target and validates it before start.                                                                                                  |
+| Gateway private key         | same Vault record (`private_key`) → `mosaic-gateway-server-key-v1`                                                      | Gateway only: `/run/secrets/mosaic-gateway-server.key`, `0400`, `10001:10001`; not mounted to migrator or PostgreSQL and never world-readable.                                                                                                                    |
+| PostgreSQL leaf certificate | `secret-{env}/mosaic-stack/database/postgres-server-tls` (`certificate`) → `mosaic-postgres-server-cert-v1`             | PostgreSQL only: `/run/secrets/mosaic-postgres-server.crt`, `0444`, frozen verified postgres UID:GID.                                                                                                                                                             |
+| PostgreSQL private key      | same Vault record (`private_key`) → `mosaic-postgres-server-key-v1`                                                     | PostgreSQL only: `/run/secrets/mosaic-postgres-server.key`, `0400`, frozen verified postgres UID:GID; never mounted to Gateway or migrator.                                                                                                                       |
+
+Compose uses identically named local **secret references** rendered by the named renderer into non-repository tmpfs paths; Swarm declares the same secrets and target paths with the tested `uid`, `gid`, and mode. KBN-101-05 rejects bind-mounted committed cert/key files, environment-encoded PEM, missing secrets, non-atomic renderer output, private-key access outside its named consumer (Gateway for Gateway key; PostgreSQL for PostgreSQL key), and any world-readable URL/key. The existing target Vault names are planned canonical paths and must be verified/provisioned by the deployment-owner input; the planning card does not claim they exist.
+
+The server leaf SANs are frozen to actual connection DNS names, not a configurable alias:
+
+| topology                             | PostgreSQL service DNS names that must be SANs                                                     | Gateway leaf SANs / consumers                                                                                                                                                       |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| standalone compose                   | `DNS:postgres`, `DNS:localhost` (only for the documented host-port disposable test path)           | `DNS:gateway`; its Gateway process consumes runtime URL + CA + Gateway leaf/key only                                                                                                |
+| federated compose                    | `DNS:postgres-federated`, `DNS:localhost` (only for the documented host-port disposable test path) | `DNS:gateway-federated`; runtime/migrator consume only their database-specific material                                                                                             |
+| Portainer/Swarm federated test stack | `DNS:postgres` (the in-stack service endpoint used by Gateway and migrator)                        | `DNS:gateway`; same consumer isolation                                                                                                                                              |
+| two-gateway harness                  | `DNS:postgres-a`, `DNS:postgres-b`                                                                 | `DNS:gateway-a`, `DNS:gateway-b`; each Gateway gets only its own runtime URL, CA, and Gateway leaf/key; each `mosaic-db-migrator-{a,b}` gets only the matching migration URL and CA |
+
+A new topology requires a versioned amendment before issuance. The PostgreSQL container activation artifact sets `ssl=on`, `ssl_cert_file`, and `ssl_key_file` to those paths, uses a locked-down `postgresql.conf` include, and verifies file ownership/mode before start. The server health/readiness gate makes a `verify-full` CA/SAN-validated connection as the approved runtime/migrator identity; `pg_isready` alone is insufficient. Migration Job starts only after server TLS readiness. Gateway replicas start only after a successful runner result and independently pass verified-TLS, identity, search-path, and ledger readiness. In the two-gateway harness this ordering occurs independently as `postgres-a → mosaic-db-migrator-a → gateway-a` and `postgres-b → mosaic-db-migrator-b → gateway-b`; no Gateway starts against its database before its own runner certificate succeeds.
+
+**Fresh DB:** provision CA/leaf/secrets and server TLS configuration before initial database bootstrap; bootstrap/extension prerequisites run, then the runner migrates over verified TLS, then runtime deploys. **Existing DB:** take the approved backup, provision/mount TLS material, and **drain/scale to zero every N-1 runtime, worker, CLI maintenance process, and replica before TLS enforcement**. Enable server TLS, terminate any residual non-TLS PostgreSQL backend sessions, set `pg_hba.conf` to `hostssl` for all application/migrator CIDRs with no matching `host` rule, reload/restart as required, and prove the non-TLS session count is zero. Only then prove `verify-full` through the existing endpoint, run reconciliation/migration, and roll the non-owner TLS runtime. There is no plaintext transition interval.
+
+**Rotation/rollback:** stage a CA bundle containing old+new trust roots to runtime/migrator, validate a new server leaf with exact SANs, restart PostgreSQL and validate it, roll consumers, then remove the old root only after evidence. Credential rotation remains independent and never mounts migration material into Gateway. Before expiry, rollback restores the prior known-valid leaf/key and overlapping CA bundle, restarts PostgreSQL, enforces `hostssl`, terminates residual non-TLS sessions, and verifies `verify-full`; it never downgrades `sslmode`, restores a plaintext-only N-1 runtime after enforcement, or accepts plaintext. A pre-enforcement abort may restore the backed-up N-1 state only before `hostssl` is enabled and is recorded as an aborted—not activated—release. The runbook records expiry windows, secret versions, backup ID, drained-service/session evidence, activation actor, and validation result—not secret values.
+
+Required disposable tests cover standalone compose, federated/Swarm, and the two-gateway harness positives using verified TLS, plus for **both** gateway/database pairs: missing CA, wrong CA, wrong PostgreSQL SAN, wrong Gateway SAN, `sslmode` downgrade, missing/mispermissioned server or Gateway key, runtime-with-migrator-secret, cross-pair secret leakage, rendered secret-consumer/UID/GID/mode isolation, legacy plaintext drain/termination/`hostssl` enforcement, and readiness-before-migration negatives. PGlite local tests are explicitly classified as non-PostgreSQL and do not satisfy a PostgreSQL TLS test.
+
+## 6. Runtime verification and sanitized failures
+
+Before accepting traffic, runtime queries only parameterized/sanitized identity and privilege metadata on its already-open verified-TLS connection. It fails closed for owner/migrator identity or assumability; superuser/CREATEROLE/CREATEDB/BYPASSRLS; object/schema/database ownership; TEMPORARY; unexpected function execute; missing inherited capability/sequence/ledger grants; any non-exact search path; wrong schema/database target; bad TLS; or manifest/ledger mismatch. After KBN-100 it also checks every immutable grant/denial and relation presence.
+
+The runner performs reciprocal preflight under the same session/lock: dedicated migration DTO only, verified TLS, exact allowlisted target, migrator `session_user`, schema-owner `current_user`, exact trusted search path, and no unsafe attributes. It fails before DDL otherwise.
+
+Stable sanitized codes are `DATABASE_RUNTIME_URL_REQUIRED`, `DATABASE_MIGRATION_URL_REQUIRED`, `DATABASE_TLS_REQUIRED`, `DATABASE_TLS_VERIFICATION_FAILED`, `DATABASE_ROLE_UNSAFE`, `DATABASE_ROLE_GRANT_MISMATCH`, `DATABASE_SEARCH_PATH_UNSAFE`, `DATABASE_SCHEMA_MISMATCH`, `DATABASE_MIGRATION_RECONCILIATION_AMBIGUOUS`, `DATABASE_MIGRATION_LOCKED`, `DATABASE_MIGRATION_IDENTITY_UNSAFE`, `MIGRATE_TARGET_ATTESTATION_REQUIRED`, `MIGRATE_TARGET_ATTESTATION_INVALID`, `MIGRATE_TARGET_ATTESTATION_EXPIRED`, `MIGRATE_TARGET_ATTESTATION_REPLAYED`, and `MIGRATE_TARGET_BINDING_MISMATCH`. Logs/metrics may contain code, tier, manifest fingerprint, role class, and correlation ID only; never DSN, username, host, database name, SQL parameter, secret, or raw catalog result. External health exposes only unavailable/not-ready.
+
+## 7. Safe DAG, activation, and rollback authority
+
+Every KBN-101 card remains one PR with exclusive ownership. Cards `00`–`07` may merge only as **prepared, inactive capability**: no current owner-runtime deployment consumes their image/config, and no compatibility switch is exposed to a runtime operator. They must not retain `ALLOW_LEGACY_*`, runtime DDL, `DATABASE_URL` migration fallback, plaintext TLS, direct Drizzle, or test-only bypass flags. Current owner-runtime deployments remain on their known N-1 release until final activation.
+
+| Card                                                                    | Depends on  | Complete, disjoint file/glob manifest and required test/evidence paths                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ----------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KBN-101-00` platform bootstrap / IaC                                   | contract    | **Only:** `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, `infra/pg-bootstrap/tests/**`. It creates the extension-owner role/schema/extension interface and proves fresh, approved-owner, legacy-shadow, catalog/default-privilege, and direct-denial bootstrap cases. No renderer, runner, Compose, CI, or deployment path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `KBN-101-01` typed runtime config and verifier                          | 00          | **Only:** `packages/config/src/index.ts`, `packages/config/src/mosaic-config.ts`, `packages/config/src/mosaic-config.spec.ts`; `packages/db/src/client.ts`, `packages/db/src/defaults.ts`, `packages/db/src/connection-identity.ts`, `packages/db/src/client.spec.ts`, `packages/db/src/defaults.spec.ts`, `packages/db/src/connection-identity.spec.ts`; `apps/gateway/src/database/database.module.ts`, `apps/gateway/src/database/database.module.spec.ts`. It supplies runtime/migration/TLS DTO parsing plus runtime identity/search-path/readiness verification. No migrator, storage, installer, deploy, or CI path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `KBN-101-03` sole runner, manifest, and schema foundation               | 00,01       | **Only:** `.gitattributes`; `packages/db/package.json`; `packages/db/drizzle.config.ts`; `packages/db/src/cli.ts`, `packages/db/src/cli.spec.ts`, `packages/db/src/index.ts`, `packages/db/src/index.import-negative.spec.ts`, `packages/db/src/migrate.ts`, `packages/db/src/migrate.test.ts`, `packages/db/src/schema.ts`, `packages/db/src/schema.spec.ts`; `packages/db/src/migrator/**`; `packages/db/drizzle/*.sql`, `packages/db/drizzle/meta/*.json`; `docker/db-migrator.Dockerfile`, `docker/db-migrator.Dockerfile.spec.ts`; `packages/db/package-bin.spec.ts`. It alone publishes `"mosaic-db-migrator": "./dist/cli.js"`, verifies source/build/pack/discovery, and sets `ENTRYPOINT ["mosaic-db-migrator"]`; it exclusively owns `packages/db/src/migrator/target-attestation.dto.ts`, `target-attestation-signer.ts`, and their specs: fixed-key reference validation, JCS canonical payload, Ed25519 signing, producer TLS/identity/manifest binding, atomic artifact emission, and producer tests. It owns journal/manifest/ledger/lock/relocation/shadow tests. Shipped `0009` bytes stay unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `KBN-101-02` runtime DDL closure                                        | 01,03       | **Only:** `docker/init-db.sql`, `infra/pg-init/01-extensions.sql`; `packages/storage/src/adapters/postgres.ts`, `packages/storage/src/adapters/postgres.spec.ts`, `packages/storage/src/factory.ts`, `packages/storage/src/factory.spec.ts`, `packages/storage/src/types.ts`, `packages/storage/src/tier-detection.ts`, `packages/storage/src/tier-detection.spec.ts`, `packages/storage/src/cli.ts`, `packages/storage/src/cli.spec.ts`, `packages/storage/src/migrate-tier.ts`, `packages/storage/src/migrate-tier.spec.ts`, `packages/storage/src/migrate-tier.integration.test.ts`; `apps/gateway/src/main.ts`, `apps/gateway/src/__tests__/integration/federated-boot.pg-unreachable.integration.test.ts`, `apps/gateway/src/__tests__/integration/federated-boot.success.integration.test.ts`, `apps/gateway/src/__tests__/integration/federated-pgvector.integration.test.ts`; `packages/db/src/federation.integration.test.ts`; `packages/mosaic/src/commands/fleet-backlog.ts`, `packages/mosaic/src/commands/fleet-backlog.spec.ts`. It consumes the -03 runner and exclusively owns importer verification/interface in `packages/storage/src/{cli,migrate-tier}.ts` and the named unit/integration specs: paired URL/attestation options, file/fd/TOCTOU checks, signature/key/expiry/replay/secret/digest/binding validation, post-TLS zero-DML comparison, and DDL classifier. It closes runtime/retired-init DDL only and excludes every -03 signer/runner, index, migrate, and Drizzle-config asset, and every deployment/CI/doc path. |
+| `KBN-101-04` installer/wizard                                           | 01          | **Only:** `packages/mosaic/src/stages/gateway-config.ts`, `packages/mosaic/src/stages/gateway-config.spec.ts`, `packages/mosaic/src/stages/gateway-config-cors.spec.ts`, `packages/mosaic/src/stages/wizard-menu.spec.ts`, `packages/mosaic/src/wizard.ts`. It persists only non-secret references/injected-variable contracts; source inspection excludes `tools/install.sh`, which does not read/write the database DSN.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `KBN-101-05` renderer and deployment                                    | 00,03       | **Only:** `tools/db/render-postgres-secrets.ts`, `tools/db/render-postgres-secrets.spec.ts`; `apps/gateway/Dockerfile`, `apps/gateway/Dockerfile.spec.ts`; `docker-compose.yml`, `docker-compose.spec.ts`; `docker-compose.federated.yml`, `docker-compose.federated.spec.ts`; `deploy/portainer/federated-test.stack.yml`, `deploy/portainer/federated-test.stack.spec.ts`; `tools/federation-harness/docker-compose.two-gateways.yml`, `tools/federation-harness/docker-compose.two-gateways.spec.ts`. It consumes the -00 bootstrap interface and -03 immutable runner image, and exclusively renders/tests runner-only root-owned signing-key reference, importer-only public-key/key-ring, and controlled `0444` attestation artifact mount; it owns no bootstrap, runner, config, storage, or CI file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `KBN-101-07` operator/runbook/docs                                      | 02,03,04,05 | **Only:** `README.md`, `CLAUDE.md`, `docs/guides/admin-guide.md`, `docs/guides/dev-guide.md`, `docs/guides/deployment.md`, **`docs/guides/migrate-tier.md`**, `docs/guides/user-guide.md`, `docs/federation/SETUP.md`, `docs/federation/TASKS.md`, `docs/fleet/backlog-conventions.md`, `docs/PERFORMANCE.md`, `docs/design/storage-abstraction-middleware.md`, `docs/plans/2026-03-15-agent-platform-architecture.md`, `docs/runbooks/kbn-101-database-role-split.md`, `docs/reports/native-kanban-sot/kbn-101-operator-readiness-report.md`, `docs/native-kanban-sot/tests/kbn-101-operator-docs.spec.ts`. It exclusively owns the active migrate-tier operator route and documents the interfaces produced by -02/-03/-04/-05, including both file references, signing-key isolation, attestation bindings, rotation/replay, and no-connection/no-DML errors; it owns no source, storage, CLI, runner, or CI file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `KBN-101-06` CI classifier and command matrix                           | 02,03,05,07 | **Only:** `.woodpecker/ci.yml`, `tools/ci/kbn101-ddl-inventory.ts`, `tools/ci/kbn101-ddl-inventory.spec.ts`, `tools/ci/fixtures/kbn101-ddl-inventory.json`, `tools/ci/kbn101-entrypoint-matrix.ts`, `tools/ci/kbn101-entrypoint-matrix.spec.ts`. It invokes the already-produced bin/image/deployment/doc artifacts and edits no producer file. Its inventory test enforces manifest overlap, ownerless, duplicate-owner, path-existence, allowlist, active-route field completeness, finite operator-document inventory, normative-contract non-masking, unknown-command, and historical/status-only masking failures; its matrix invokes the -02 secure target route and verifies every declared attestation refusal before target connection/DDL and post-connect mismatch with zero DML.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `KBN-101-08` foundation certification and **atomic activation release** | 00…07       | **Only evidence:** `docs/reports/native-kanban-sot/kbn-101-foundation-activation-certificate.md`, `docs/reports/native-kanban-sot/kbn-101-foundation-activation-evidence.json`. It changes no implementation path. Independent review and terminal-green CI must verify prepared artifacts before Mosaic control plane/Jason authorizes backup → drain/scale-zero N-1 → TLS → roles → runner → verified readiness → rolling runtime; any red result aborts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `KBN-101-09` post-KBN-100 certification                                 | KBN-100,08  | **Only evidence:** `docs/reports/native-kanban-sot/kbn-101-immutable-role-certificate.md`, `docs/reports/native-kanban-sot/kbn-101-immutable-role-evidence.json`. It changes no implementation path and records real deployed runtime INSERT/SELECT plus UPDATE/DELETE-denial evidence and independent security/Ultron approval.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+
+The manifests above are the complete ownership universe for KBN-101 implementation paths; the KBN-101-06 inventory test fails on overlap, an ownerless in-scope path, or a nonexistent declared path. Cards `00`–`07` are prepared artifacts, not independently deployed releases: the immutable N-1 owner-runtime image stays live until KBN-101-08 control-plane atomic activation. No activation card edits a source-changing path, and no runtime bypass or broken deployed intermediate exists.
+
+**Authority:** Mosaic control plane/Jason is the sole activation and rollback authority. CI, Gateway, migrator, Coordinator, and Certifier cannot activate, waive a red result, or force release. Before an incompatible KBN-100 switch, the authority stops/scales runtime, uses the approved backup/restore or separately reviewed runner artifact, restores only a known TLS-compatible runtime with its runtime secret after `hostssl` enforcement, and verifies no plaintext sessions plus TLS/readiness. Migration URL is never injected into Gateway to enable rollback. KBN-100 starts only after KBN-101-08; KBN-105 starts only after KBN-101-09.
+
+**ASSUMPTION K101-A2:** every eligible production-like deployment can schedule a dedicated migration Job/one-shot command and an operator/IaC-controlled TLS bootstrap. A target that cannot do both is ineligible for KBN certification.
+
+## 8. Acceptance traceability
+
+| Requirement / acceptance criterion | Required implementation evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| K101-REQ-01 / AC-K101-01           | DTO/command matrix covers local/PGlite, standalone, federated, and both harness pairs; every finite classified §2 path rejects `DATABASE_URL`-only before connection/DDL; no runtime fallback/default; `--help`, argv, import-compile, and live-operator-route negatives pass. The active migrate-tier route proves runner-produced JCS/Ed25519 attestation, root-owned signing/private-key and importer-public-key isolation, atomic artifact, exact `--target-url-file /run/secrets/mosaic_migrate_target_url` plus `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`, secret-version/digest/TLS/CA/server/database/role/manifest/schema bindings, expiry/replay/rotation/TOCTOU checks, bounded non-DDL importer DML, and missing/wrong/stale/replayed/tampered/substituted/mismatched no-connection versus zero-DML refusal. |
+| K101-REQ-02 / AC-K101-02           | KBN-101-03 one-session fixed two-int lock, `--run`/`--verify` exit-code, contention/crash/readiness/unrelated-key tests; manifest-v1 canonical bytes/digest and all reconciliation states; Gateway/replica DDL impossibility.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| K101-REQ-03 / AC-K101-03           | KBN-101-00 bootstrap schema/extension-owner/default-privilege and direct-denial proof against actual PostgreSQL 17 + pgvector 0.8.2 control metadata (`trusted` absent/untrusted, `relocatable=true`); external-superuser `SET ROLE` create/update/`RESET ROLE` audit proof; `rolcanlogin=false`, `rolsuper=true`, zero members/no runtime credential proof; KBN-101-03 catalog relocation and future-Drizzle-only-`mosaic` proof plus approved-owner/shadow runner integration; `pg_namespace.nspowner`, `pg_extension.extowner`, owner-bearing member/schema/version, and runtime/migrator/schema-owner/importer/all-service-role catalog plus `SET ROLE`/ALTER/DROP/member-update denials; KBN-101-01/03 role, path, TEMP, ledger/default-grant, and pool-reset tests.                                                                                  |
+| K101-REQ-04 / AC-K101-04           | KBN-101-00 bootstrap-interface and KBN-101-05 renderer/deployment tests; immutable-image exact Job commands and runner-before-readiness order; fresh/existing verified-TLS Compose/Swarm/two-gateway positives; both-pair CA/SAN/downgrade/key-permission negatives; exact UID/GID/mode and runtime/migrator secret-consumer rendering/CI negatives.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| K101-REQ-05 / AC-K101-05           | KBN-101-09 after KBN-100: real deployed runtime INSERT/SELECT success and UPDATE/DELETE denial for each frozen relation, with RESTRICT retention evidence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| K101-REQ-06 / AC-K101-06           | KBN-101-00…08 prepared-card/no-intermediate-deploy evidence; one final activation authority record; N-1 drain/zero-plaintext-session/`hostssl`, backup/restore, CA overlap rotation, TLS-only rollback, Vault/redaction, and no-force-on-red evidence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| K101-REQ-07 / KBN sequence         | KBN-101-08 foundation certificate before KBN-100, KBN-101-09 real immutable-role certificate plus Ultron approval before KBN-105; KBN-100 rebases/restores Drizzle consistency and never bypasses the serial gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Delivery integrity                 | One-card/one-PR DAG, exact file ownership, docs/link/contract checks, independent author≠reviewer re-review on the pushed exact head, and terminal-green CI for implementation cards.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+
+## 9. Non-goals and residual authority
+
+KBN-101 planning does not create roles, certificates, Vault paths, migrations, deployment artifacts, or a deployed certificate. It does not replace KBN-100’s data migration, immutable retention, tenant constraints, or KBN-105 endpoint freeze. A PostgreSQL superuser/break-glass operator—including the deliberately isolated extension owner—remains outside application containment: `GRANT`/`REVOKE` cannot constrain that authority. Separate identity/non-login/zero-membership/external-control/audit controls, independent review, maintenance windows, backup/rollback evidence, and drills are mandatory.

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

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

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

@@ -0,0 +1,305 @@
+# Native Kanban/SOT — Remediated Shared Contract v1
+
+**Status:** CONTROL-PLANE rc.11 KBN-101 target-bound importer-attestation and complete operator-inventory remediation complete; awaiting independent exact-head re-review. Prior KCR-001–016 and rc.4 SI-001 decisions retained; KBN-101 foundation certification precedes KBN-100 and real immutable-operation certification precedes KBN-105
+**Version:** 1.0.0-rc.11
+**Date:** 2026-07-15
+**Change authority:** Mosaic control plane/Jason only
+**SI-001 amendment authority:** `web1:mosaic-100` control-plane decision under issue #753
+
+## Amendment record
+
+### 1.0.0-rc.11 — Target-bound importer attestation and exhaustive operator-route closure
+
+- **Target-bound proof:** trusted `mosaic-db-migrator --verify` now produces the atomic, credential-free `migrate-target.v1.json` JCS/Ed25519 artifact from a runner-only root-owned signing-key reference; the importer receives only pinned public verification keys and the artifact. Its signed v1 fields bind issued/expiry/nonce, exact secret version and SHA-256 of high-entropy target-file bytes, canonical TLS host/port/database, CA/SPKI, PostgreSQL system identifier/database OID, expected importer role, manifest/schema fingerprints, and producer invocation/build/image/correlation. No DSN, username, password, credential bytes, or signing key enters the artifact, importer, runtime, logs, or output.
+- **Fail-closed importer:** `mosaic storage migrate-tier` requires both `--target-url-file /run/secrets/mosaic_migrate_target_url` and `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. Before target connection it validates files, signature/key/expiry/replay, secret version/digest, TLS/CA/role/manifest bindings and opens/digests/connects from the same in-memory URL bytes. After verified TLS but before transaction/DML it matches server ID, database OID, `current_user`, CA/SPKI, and manifest/schema; failure distinguishes zero connection from connection/zero-DML and DDL remains impossible. Rotation overlap/revocation, atomic rename, replay cache, secret rotation invalidation, and wrong/substituted/stale/tampered/file-change tests are mandatory.
+- **Closed documentation surface:** KBN-101-06 inventories every current non-normative scanner hit, including `docs/guides/user-guide.md` and status-only `docs/federation/TASKS.md`; the latter is historical and cannot authorize DDL. The legacy `storage migrate` tier-copy syntax is unavailable. `storage migrate` is schema-wrapper delegation only; secure tier data copy is `migrate-tier`. Exact KBN PRD/contract/shared/task paths may be `normative-contract` scan class but are still scanned and cannot mask executable instructions. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
+- **Non-effect:** pgvector closure, manifest, lock, role graph, TLS, activation, and KBN-100/KBN-105 serial gates are unchanged.
+
+### 1.0.0-rc.10 — PostgreSQL-valid untrusted pgvector owner and active migrate-tier closure
+
+- **Valid extension authority:** PostgreSQL 17 + pgvector 0.8.2 `vector` is untrusted (`trusted` absent; `relocatable=true`), so `mosaic_extension_owner` is exactly `NOLOGIN SUPERUSER`, not `NOSUPERUSER`. It is dedicated solely to `mosaic_extensions`, `vector`, and owner-bearing extension members; `rolcanlogin=false`, `rolsuper=true`, zero members, no runtime credential/Vault secret, and no app-container delivery are catalog and deployment proof. An externally controlled audited bootstrap-superuser session alone `SET ROLE`s for extension CREATE/UPDATE/SET SCHEMA, then `RESET ROLE`; fresh and shadow paths do so, while in-place existing work requires exact pre-existing `extowner`.
+- **Explicit superuser exception:** `GRANT`/`REVOKE` cannot privilege-limit a superuser. The containment is dedicated identity, no login, no membership, external control plane, audit, independent review, backup/rollback, and maintenance window—not a false least-privilege claim. Runtime, migrator, schema owner, importer, and every service role cannot assume the role or alter/update/drop/change extension membership. Managed targets without this exact role are ineligible unless a versioned provider-owned extension-owner profile is independently approved.
+- **Active secure data-migration route:** `docs/guides/migrate-tier.md` is exclusively KBN-101-07, is active rather than historical, and specifies runner-prepared/verified PostgreSQL destination plus a dedicated non-DDL importer. KBN-101-02 freezes `--target-url-file /run/secrets/mosaic_migrate_target_url`, never credential argv; raw `--target-url`, `DATABASE_URL` fallback, runtime owner, missing/unsafe file, wrong mode, and DDL all fail before target connection/DDL. KBN-101-06 inventory/matrix records the route and exact secure fields, then tests its finite operator-document closure.
+- **Non-effect:** manifest, lock, `mosaic` application schema, TLS, activation, and KBN-100/KBN-105 serial gates remain unchanged. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
+
+### 1.0.0-rc.9 — KBN-101 extension-schema boundary, disjoint manifests, and scanner mechanics
+
+- **Extension schema owner:** `mosaic_extension_owner`, not `mosaic_schema_owner`, creates and owns `mosaic_extensions`, `vector`, and extension-member objects. The external bootstrap actor `SET ROLE`s for fresh creation or approved-owner relocation, then `RESET ROLE`s; rc.10 replaces the earlier membership wording with the PostgreSQL-valid zero-member superuser exception. Schema owner has only `USAGE` for legacy type resolution—never ownership, `CREATE`, `ALTER`, `DROP`, member change, or default-privilege authority. Runtime, migrator, and schema owner must fail catalog and direct DDL denials; shadow/resume/rollback repeat the owner/default-privilege proof.
+- **Exclusive delivery DAG:** KBN-101-00…09 now has a complete, nonoverlapping exact file/glob manifest with named tests/evidence. The runner mapping is exactly `"mosaic-db-migrator": "./dist/cli.js"` and image `ENTRYPOINT ["mosaic-db-migrator"]`; `packages/storage/src/{cli,migrate-tier}.ts` belongs only to -02, and -07 is documentation only. -08/-09 own evidence paths only. -00…07 are prepared artifacts; the immutable N-1 image remains live until -08 atomic activation, so no independently deployed intermediate can bypass runtime controls.
+- **Mechanical classifier:** -06 owns the exact scanner, inventory fixture, command-matrix harness, and CI wiring. Inventory records pin path/class/owner/disposition/allowed tokens/rationale/expiry/review revision; unknown, duplicate-owner, ownerless, missing-path, invalid allowlist, and historical-category masking fail. The architecture plan's operative direct `db:migrate` is replaced by sole-runner guidance rather than hidden under a historical category.
+- **Non-effect:** manifest v1, lock, `mosaic` application-schema ownership, TLS, activation, KBN-100/KBN-105 serial gates, and all earlier canon decisions remain unchanged. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
+
+### 1.0.0-rc.8 — KBN-101 finite authority, executable runner, and pgvector-owner remediation
+
+- **Finite authority closure:** KBN-101-06 classifies every current executable source/script/package bin, operator document, and deploy manifest by exact path; unclassified current hits fail. Byte-immutable historical SQL, PGlite-only routines, negative-test literals, vendored/generated artifacts, and clearly labeled historical reports are exact-path/category reviewed allowlists only. `packages/db/src/index.ts` loses its public `runMigrations` export with a direct-import/compile negative; `docs/fleet/backlog-conventions.md` and `docs/PERFORMANCE.md` lose first-use/direct-Drizzle/Gateway-startup migration instructions and carry runner/readiness route negatives. A token scan is only input to the classifier, never proof of authority.
+- **Executable exclusive cards:** KBN-101-03 alone publishes `mosaic-db-migrator` from `packages/db/package.json`/`src/cli.ts`, owns `docker/db-migrator.Dockerfile`, and keeps `{runner,config.dto,manifest,identity,tls}` private, with exact `--run|--verify|--help`, env-only input, stable exits, and command tests. KBN-101-00 alone owns `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, plus bootstrap tests. KBN-101-05 alone owns `tools/db/render-postgres-secrets.ts`, renderer tests, and Compose/Portainer/Swarm/two-gateway declarations, consuming the versioned bootstrap interface. No card overlaps renderer/bootstrap/deployment ownership.
+- **Extension-owner transition:** `mosaic_extension_owner` is a dedicated NOLOGIN role whose membership/credentials never reach services; the external bootstrap actor alone may `SET ROLE` during bootstrap. Fresh vector and member objects retain that owner. PostgreSQL has no supported extension-owner alteration: approved-owner existing extension relocation validates `pg_extension.extowner`, members/schema/version and uses tested `ALTER EXTENSION ... SET SCHEMA`; legacy runtime-owned extension fails closed to a controlled shadow database migration with backup, evidence, quiesce/final delta, atomic switch, and read-only rollback window. No catalog mutation, ownership adoption, or `DROP CASCADE` is permitted. Runtime/migrator/schema-owner extension ALTER/DROP/member-update denial is mandatory.
+- **Non-effect:** manifest v1, lock namespace, role/search-path, relocation/TLS/activation, KBN-100/KBN-105 serial gates, and all retained canon decisions are strengthened, not weakened. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
+
+### 1.0.0-rc.7 — KBN-101 complete current-path, relocation, and two-gateway remediation
+
+- **Finite current-path closure:** static inventory and the `DATABASE_URL`-only-before-connect/DDL denial matrix now explicitly include Gateway's former temporary-table pgvector test (runner-prepared persistent read/query-only fixture), `docker/init-db.sql` retirement, `migrate-tier.ts` runner/bootstrap-only guidance, and the active two-gateway harness. The harness is migrated, not retired: `postgres-a/b → mosaic-db-migrator-a/b → gateway-a/b`, each with isolated URL/CA material, verified readiness, SANs, and positive/negative TLS evidence.
+- **Executable relocation:** KBN-101-03 exclusively owns `schema.ts`, Drizzle snapshots/journal/generated relocation and exact tests. All future application declarations use exported `pgSchema('mosaic')`; immutable historical SQL runs only in trusted legacy `public`. `vector` is fixed in non-writable `mosaic_extensions`, with exact catalog relocatability/version eligibility, explicit type/operator qualification, catalog-class ordering, unknown-object fail-closed behavior, clean/current-public/partial/reverse rollback tests, and an N-1 release order.
+- **Bound deployment ownership:** `mosaicstack/stack` KBN-101-00/05 owns current Compose, Portainer, two-gateway, bootstrap renderer/templates, UID/GID declarations, and rendered validation. Gateway is fixed to `10001:10001`; PostgreSQL UID/GID is image-inspected and frozen only after digest pinning. Exact secret paths, atomic renderer behavior, Compose/Swarm targets/modes, Gateway/PostgreSQL leaf separation, and two-pair TLS failure evidence are required. Mosaic deployment control plane/Jason is the named activation authority; environment IaC/Vault supplies versioned input only.
+- **Correct traceability:** REQ-03 maps to role/schema/search-path, REQ-04 to TLS, REQ-05 to post-KBN-100 immutability, REQ-06 to rollout/rollback, and REQ-07 to the KBN-101 → KBN-100 → KBN-101 → KBN-105 sequence. No prior manifest/lock/role/DAG/activation decision is weakened.
+
+### 1.0.0-rc.6 — KBN-101 closed DDL/TLS/ledger activation remediation
+
+- **Choice:** `mosaic-db-migrator` is the sole application/CI/test PostgreSQL DDL control plane. Every legacy entrypoint is routed or denied, rejects `DATABASE_URL`-only before connection/DDL, and `db:push` is unavailable outside an allowlisted disposable developer target. The runner holds one `max:1` session with fixed `pg_try_advisory_lock(1297044289,1262636593)` across preflight through release.
+- **Exact ledger:** manifest v1 canonically serializes journal logical index/tag and SHA-256 of exact shipped migration bytes. It maps each observed ledger hash to one tuple; physical insertion order is non-normative, while missing/unknown/duplicate/ambiguous/corrupt/stale states fail closed. Shipped `0009` bytes remain unchanged; a missing/effects-absent `0009` runs normally, an applied-late hash maps normally, and partial/full effects with missing hash require backup restoration or separately reviewed repair—not manual adoption.
+- **TLS/search path:** operator/IaC owns CA and server leaf lifecycle, exact compose/Swarm secret mounts, server TLS activation, service-DNS SANs, verified-TLS readiness, transition, CA overlap rotation, and rollback. Runtime/migrator use `verify-full`; PGlite is not PostgreSQL TLS evidence. Application sessions use only `pg_catalog,mosaic`; no URL/config-derived identifier reaches SQL.
+- **Safe release:** cards 00–07 land prepared but inactive; owner-runtime deployments remain N-1. Mosaic control plane/Jason alone authorizes one atomic TLS/roles → runner → readiness → runtime activation or rollback. No runtime-operator compatibility switch, bypass, plaintext interval, or force-on-red exists; all temporary support is removed before KBN-101-08.
+- **Non-effect:** role graph, immutable certification after KBN-100, KBN-105 gate, rc.5’s preserved rc.4 SI-001 invariants, and all KCR-001–016 decisions remain unchanged. Exact detail is normative in [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
+
+### 1.0.0-rc.5 — KBN-101 role/connection split
+
+- **Choice:** PostgreSQL `standalone` and `federated` runtime uses `DATABASE_URL` only as a non-owner `mosaic_runtime` login; an explicit migration phase uses `DATABASE_MIGRATION_URL` only as `mosaic_migrator`, which `SET ROLE`s to non-login `mosaic_schema_owner` for DDL. Local PGlite remains an explicit embedded exception.
+- **No fallback / no startup DDL:** missing migration URL fails the migration phase; it never falls back to runtime URL/default/config. Gateway replicas do not run migrations. An advisory-locked migration phase verifies the exact ordered Drizzle ledger fingerprint before replicas may become ready.
+- **Privilege model:** non-login `mosaic_platform_database_owner` is outside application paths; `mosaic_schema_owner` owns only application/ledger schemas. `mosaic_runtime` has only `mosaic_runtime_capability`, owns no object/schema, cannot assume owner/migrator, has no TEMPORARY privilege, has only read access to the Drizzle ledger, and must fail startup if effective identity, unsafe attributes, authenticated TLS, search path, schema version, grants, or immutable relation privileges differ from the frozen contract. `task_events`, `artifacts`, `task_checkpoints`, `task_checkpoint_artifacts`, and `approval_decision_artifacts` grant runtime only INSERT/SELECT; KBN-100 retains RESTRICT/no-cascade semantics.
+- **Non-effect:** rc.4 SI-001 candidate-key/FK order and all KCR-001–016 tenancy, SOT, proposal-audit, approval, fence, recovery, no-cascade, endpoint, and wire invariants are unchanged. This amendment neither creates roles/secrets nor changes production deployment.
+- **Gate:** KBN-101’s role/schema-boundary foundation certificate, Vault/redaction/rotation, N-1/rollback, and independent security GO are mandatory before KBN-100. After KBN-100 creates the immutable relations, KBN-101 real deployed-role immutable-operation certification plus Ultron GO is mandatory before KBN-105; synthetic test-role success alone is insufficient. Exact implementation detail is normative in [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
+
+### 1.0.0-rc.4 — KBN010-SI-001 (preserved)
+
+- **Choice:** add the explicitly named, non-partial unique candidate key `missions_workspace_id_uidx` on `missions(workspace_id, id)` and retain `missions_workspace_project_id_uidx` on `(workspace_id, project_id, id)`.
+- **Rationale:** mission `id` remains globally unique, while the composite candidate key makes the frozen tenant-safe generic mission relations valid. `artifacts` and `approval_decisions` are polymorphic exactly-one-target records and do not consistently carry `project_id`; widening both children would unnecessarily broaden v1 and its target semantics.
+- **Exact effect:** `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk` continue to reference the exact ordered columns `missions(workspace_id, id)` with RESTRICT deletion, now backed by a matching candidate key.
+- **Non-effect:** no SOT, tenancy, project-congruence, proposal-audit, approval, fencing, immutability, no-cascade, API, or wire-version invariant changes. The `SuccessEnvelopeV1.contractVersion` remains `1.0.0`.
+- **Historical evidence boundary:** `KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` intentionally remains the immutable rc.3 blocker verdict that detected SI-001; this rc.4 record and the #753 scratchpad append are the authorized disposition. Rewriting the gate verdict is outside this amendment's exclusive scope.
+- **Gate:** this amendment resolves the DDL defect identified by KBN010-SI-001 but does not itself lift KBN-100; independent schema/SecReview remains required.
+
+## 1. Authority
+
+Concrete contracts are the four `contracts/*.v1.ts` files. PostgreSQL/current-main Drizzle is the sole writable SOT. In PostgreSQL standalone/federated deployments, KBN-101 rc.11 DDL/ledger/TLS/role/attestation separation is a precondition to schema implementation and certification. Public health, Valkey, files, exports, providers, browser state, and outage notes cannot authorize/reconstruct writes. Mechanical Coordinator is non-LLM with no scope/gate/certification/merge authority. Certifier is final independent gate with no merge authority. No feature lane starts until this canon merges and the KBN-010/KBN-105 prerequisites are satisfied.
+
+## 2. Health proof and exact failures
+
+`KanbanHealthResponseV1` is a discriminated union:
+
+| State                |  read | write | Capability                                          |
+| -------------------- | ----: | ----: | --------------------------------------------------- |
+| `healthy`            |  true |  true | reads; public state still cannot authorize mutation |
+| `read-only-degraded` |  true | false | reads only                                          |
+| `write-unavailable`  | false | false | diagnostics only                                    |
+
+Every response has `checkedAt`, `validUntil`, `policyRevision`; contradictory booleans fail validation.
+
+For a mutation, Gateway opens the PostgreSQL transaction, executes the live write probe on that transaction/connection, mints the internal branded `PostgresWriteHealthProofV1`, and revalidates time/policy/transaction identity immediately before mutation. Public REST/MCP/CLI DTOs never accept health/proof fields. Valkey/caller assertions cannot mint proof. Pure Coordinator takes `KanbanEvaluationContextV1`; persistence takes `InternalKanbanMutationContextV1` or probes internally.
+
+| Case                         |                        HTTP | Frozen result                                                       | Retry                |
+| ---------------------------- | --------------------------: | ------------------------------------------------------------------- | -------------------- |
+| degraded write               |                         503 | `KANBAN_WRITE_HEALTH_UNPROVEN`, `read-only-degraded`, `not_applied` | false                |
+| write unavailable            |                         503 | `KANBAN_WRITE_UNAVAILABLE`, `write-unavailable`, `not_applied`      | false                |
+| version conflict             |                         409 | `AGGREGATE_VERSION_CONFLICT`, actual version, `not_applied`         | false                |
+| timeout/unreachable          |             timeout/502/504 | `retryable_transport_error`, `unknown`                              | same idempotency key |
+| stale fence/session/approval | coordinator rejection union | `not_applied`                                                       | false                |
+
+Required negatives: contradictory state, expired/policy-mismatched/wrong-transaction proof, Valkey-only health, forged healthy, and exhaustive non-cross-mapping of 503 vs 502/504/timeout vs 409.
+
+## 3. Canonical schema invariants
+
+Complete declaration: `contracts/kanban-schema.v1.ts`.
+
+- Tables: tenant/identity (`workspaces`, members, teams/members, agents/sessions); planning (`projects`, `milestones`, current-milestone join, `missions`, mission-milestones, `tasks`, normalized tags, dependencies); orchestration (`task_assignments`, durable execution state, leases, checkpoints/evidence); governance (`change_proposals`, immutable artifacts/evidence, events, approvals, outbox, external links).
+- Task statuses: `backlog | ready | in_progress | blocked | in_review | done | cancelled`.
+- Assignment states everywhere: `awaiting_approval | policy_pre_authorized | approved | rejected | leased | released | expired | superseded`.
+- Specialist roles everywhere: `planning | enhance | coder | review | security-review | pr-monitor | certifier`.
+- Owner uses exactly-one user/team; assignment principal exactly-one user/team/agent; users require active membership; agent/session and all evidence are workspace-bound.
+- Task→mission/milestone/parent, mission→milestone, and project→current-milestone are project-congruent composite relations.
+- Mission `id` remains globally unique. The additional non-partial `missions_workspace_id_uidx` candidate key on `(workspace_id, id)` exists only to support the frozen workspace-safe polymorphic artifact and approval-decision mission relations; the project-congruent `(workspace_id, project_id, id)` key remains authoritative wherever `project_id` is present.
+- Dependency identity is workspace+predecessor+successor independent of type.
+- Approval evidence and checkpoint evidence are workspace-scoped joins to immutable artifacts, never JSON ID arrays.
+- Proposal audit links are composite relations: `(workspace_id, submitted_audit_event_id)` and `(workspace_id, accepted_command_audit_event_id)` reference `task_events(workspace_id, id)` with RESTRICT deletion.
+- Assignment is persisted with task/version, exact target/session, expiry/state/policy/proposer/reason. Approval relates to assignment. Lease acquisition accepts IDs, then reloads/locks and validates every relation.
+- `tasks.fencing_counter` is bigint; locked atomic increment/RETURNING creates a decimal-string lease token. Lease/checkpoint composites bind exact workspace+task+assignment/session+fence.
+- `task_execution_states` durably records retry/quarantine/exhaustion.
+- Tags are normalized; legacy `tasks.tags` remains through N-1. Archive is explicit actor/reason/time and does not change lifecycle.
+- Canonical parents use RESTRICT. Events/checkpoints/artifacts/evidence are INSERT/SELECT-only for application roles. Normal flow archives/cancels; purge is audited break-glass retention work.
+
+## 4. Outage proposal contract
+
+`change_proposals` stores workspace, active-member proposer, source-note digest, target/version, typed command/payload, idempotency, lifecycle, decision actor/reason/time, proposal version, and submit/accepted event IDs. Both event IDs are workspace-aware composite foreign keys to `task_events(workspace_id, id)`; a bare UUID is never sufficient.
+
+Submission preallocates the proposal ID. One transaction inserts `change_proposal.submitted` with the proposal workspace, `aggregate_type='change_proposal'`, `aggregate_id=<new proposal ID>`, `previous_version=NULL`, and `new_version=1`, then inserts the proposal referencing that event. Missing, foreign-workspace, wrong-type, or unrelated-proposal events abort the transaction.
+
+Submit/list/get/accept/reject are explicit Gateway commands. Pending/rejected proposals are inert: no scheduling, dependency/gate satisfaction, or direct target mutation. Acceptance locks proposal+target, obtains fresh transaction-local proof, verifies pending/expected version, invokes the normal command handler, and atomically stores the emitted normal-command event ID. That event must share the proposal workspace, match `target_aggregate_type` and `target_aggregate_id`, use `causation_id=submitted_audit_event_id`, and carry `payload.changeProposalId=<locked proposal ID>`. Missing, foreign-workspace, unrelated-target, unrelated-proposal, or unrelated-command events abort acceptance.
+
+## 5. Concrete current-main N-1 migration delta
+
+**Inspected:** `origin/main:packages/db/src/schema.ts` at `e72388b2cbfe400842fe940fa6cabf984ed43711` (2026-07-13). It has global teams/no workspace keys, legacy project/mission/task statuses, nullable task project/mission, `tasks.assignee/tags/due_date`, mission JSON/config, duplicated `mission_tasks.status`, legacy agent fields, and separate fleet `backlog` claims.
+
+Legacy columns remain declared in unified `schema.ts` for expand + full N-1/rollback window. Generation must not infer early drops.
+
+### 5.1 Ordered phases
+
+1. **Pre-expand:** N-1 patch stops `mission_tasks.status` as write source; inventory writers; backup/checksum.
+2. **Expand:** add enums/tables and nullable-first columns; retain legacy declarations/uniques; emit no v1-only status.
+3. **Backfill:** bootstrap workspace; bounded idempotent cursor/checksum batches; quarantine ambiguous rows.
+4. **Validate:** no null tenant, cross-project link, ambiguous owner; status/tag/date/config retention; then constraints/NOT NULL.
+5. **Compatibility:** N-1 reads legacy; same-DB transaction mirrors only unavoidable fields; never file/Valkey dual write.
+6. **Switch:** stop N-1 writers; Gateway sole command boundary; enable canonical statuses.
+7. **Contract release:** later release after rollback/N-1; remove compatibility/global uniques/legacy fields.
+
+### 5.2 Mission candidate-key and dependent-FK DDL order
+
+KBN-100 migration DDL must execute the SI-001 portion in this order:
+
+1. expand/backfill `missions.workspace_id` and `missions.project_id` while preserving the global `missions.id` primary key and the project-congruent `missions_workspace_project_id_uidx` key;
+2. prove duplicate-key feasibility on the production-shape dataset: `(workspace_id, id)` has no duplicate groups and global `id` uniqueness remains intact;
+3. create the non-partial unique index `missions_workspace_id_uidx` on exact ordered columns `(workspace_id, id)`;
+4. only after step 3, create/alter `artifacts` and add `artifacts_workspace_mission_fk` from `(workspace_id, mission_id)` to exact `missions(workspace_id, id)` with `ON DELETE RESTRICT`;
+5. only after step 3, create/alter `approval_decisions` and add `approval_decisions_workspace_mission_fk` from `(workspace_id, mission_id)` to exact `missions(workspace_id, id)` with `ON DELETE RESTRICT`;
+6. validate both constraints and prove a mission ID paired with a foreign workspace is rejected for each child.
+
+The candidate key is intentionally redundant with globally unique `missions.id`, but PostgreSQL requires a matching unique candidate key for the exact two-column FK target. It is additive and N-1-safe. Pre-switch rollback drops the two dependent FKs/tables before dropping this candidate key, preserves the global primary key and project-congruent key, and follows the existing freeze/reconciliation rule after the first canonical mutation.
+
+### 5.3 New audit/proposal DDL order
+
+KBN-100 migration DDL may begin only after KBN-101 foundation role/schema-boundary certification. It runs in the explicit migrator/owner phase—not Gateway startup—and its generated Drizzle declaration/snapshot/journal must be mutually consistent. It must execute in this order:
+
+1. create `task_events` and its unique `(workspace_id, id)` key;
+2. create `change_proposals` with nullable acceptance-event ID and required submission-event ID;
+3. add `change_proposals_workspace_submitted_event_fk` from `(workspace_id, submitted_audit_event_id)` to `task_events(workspace_id, id)` with `ON DELETE RESTRICT`;
+4. add `change_proposals_workspace_accepted_command_event_fk` from `(workspace_id, accepted_command_audit_event_id)` to the same composite key with `ON DELETE RESTRICT`;
+5. install application-role immutability privileges and same-transaction semantic validation before enabling proposal commands.
+
+The submission transaction inserts the event first using a preallocated proposal UUID, then the proposal. Acceptance inserts the normal command event before updating the locked proposal. Neither FK is omitted or replaced by a bare UUID/index check.
+
+### 5.4 Field map
+
+| Current                                        | Expand/backfill                                                                                                       | N-1 compatibility                                     | Switch/contract                                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| global `teams`, `team_members`                 | add workspace nullable; bootstrap; validate active owners                                                             | retain global slug/FKs                                | workspace composites; global unique contracts later                                |
+| `projects.status`                              | add `canonical_status`; map active/paused/completed/archived                                                          | mirror representable values; no `planning`            | canonical authority; legacy contracts later                                        |
+| project `owner_id/team_id/owner_type`          | add exact accountable user/team; deterministic map or quarantine                                                      | preserve old reads and compare drift                  | canonical exact-one; remove legacy after parity                                    |
+| current milestone                              | create milestones then join table (no circular DDL)                                                                   | absent to N-1                                         | join is authority                                                                  |
+| nullable `missions.project_id`                 | derive workspace/project; null/orphan exception, never guess                                                          | keep nullable legacy read                             | canonical required; validate/set NOT NULL later                                    |
+| mission relational candidate keys              | retain global `id` PK and project-congruent key; add non-partial `(workspace_id,id)` key before artifact/approval FKs | additive key is ignored safely by N-1 readers/writers | retain both composite keys; generic mission children use exact workspace+ID target |
+| mission `description`                          | add objective; preserve description; reviewed nonblank mapping                                                        | N-1 description                                       | objective authority; retain until signed review                                    |
+| `missions.status`                              | add canonical; planning→draft, active/paused/completed/failed same                                                    | no new-only statuses emitted                          | canonical authority                                                                |
+| mission `milestones` JSON                      | normalize with source digest; preserve malformed/original                                                             | N-1 reads JSON; no reverse sync                       | normalized authority; JSON removed after checksum sign-off                         |
+| mission config/metadata/phase/user             | retain all; map known typed policy only                                                                               | all remain declared                                   | remove only by signed consumer inventory                                           |
+| nullable `tasks.project_id`                    | derive explicit/mission project; orphan quarantine                                                                    | retain nullable read/write during compatibility       | canonical required; NOT NULL later                                                 |
+| `tasks.mission_id`                             | add project-congruent composite                                                                                       | old relation readable                                 | composite authority                                                                |
+| `tasks.status`                                 | canonical: not-started→backlog, in-progress→in_progress, others same                                                  | no ready/in_review emission                           | canonical authority                                                                |
+| `tasks.assignee`                               | deterministic active user/team/agent assignment; raw value preserved if ambiguous                                     | mirror text only if unambiguous                       | canonical owner/assignment; remove after no-loss sign-off                          |
+| `tasks.tags` JSON                              | normalize trim/case/dedupe with original digest                                                                       | transactionally mirror normalized rows                | normalized authority; JSON later removed                                           |
+| `tasks.due_date`                               | copy exactly to `due_at`                                                                                              | mirror                                                | due_at authority; legacy later                                                     |
+| task common fields                             | preserve metadata byte-for-byte; add criteria/rank/retry/archive/version/fence                                        | old reads valid                                       | new fields canonical                                                               |
+| `mission_tasks.status`                         | keep; prohibit as write source; linked status ignored; unlinked becomes task or reject                                | read-only compatibility value                         | membership uses task mission; status dropped after no readers                      |
+| mission-task notes/PR/user                     | map to metadata/artifact/event/link/attribution; preserve                                                             | read-only                                             | remove after parity                                                                |
+| `agents.status`                                | add workspace/lifecycle/runtime/roles; status remains presence                                                        | retain all legacy fields                              | lifecycle/roles authority; status may remain telemetry                             |
+| agent project/owner/prompt/tools/skills/config | preserve; validate tenant; derive typed capabilities without loss                                                     | N-1 reads                                             | removal only by separate inventory                                                 |
+| fleet `backlog`                                | map to designated-project tasks; edges; claimed rows quarantine                                                       | freeze claims before switch; read-only compare        | task/lease authority; retire after stabilization                                   |
+
+### 5.5 Required migration tests
+
+Empty DB; exact production-shape snapshot; crash/resume; rollback before switch; N-1 startup/read/write; workspace/member negatives; status-shadow/no premature new status; `mission_tasks.status` write prohibition; tags/assignee/date/mission JSON/config/description/agent checksum; project congruence/current-milestone order; backlog freeze/no dispatch; and proof legacy declarations persist until contract release.
+
+SI-001 adds frozen future executable evidence: empty and production-shape migrations create `missions_workspace_id_uidx` before either dependent FK; duplicate-key feasibility preflight returns no `(workspace_id,id)` duplicate groups without weakening global `id` uniqueness; N-1 startup/read/write behavior is unchanged; pre-switch rollback removes dependents before the candidate key; both exact FK column lists reconcile to the candidate key; and foreign-workspace mission references fail for both artifacts and approval decisions. TDD is not applicable to this design-only amendment; KBN-100 must implement these negative migration tests before runtime schema release.
+
+Proposal-specific negatives must attempt: missing submission event, foreign-workspace submission event, foreign-workspace acceptance event, same-workspace event for another proposal, event for another target aggregate, and unrelated normal-command event. Every attempt must fail atomically with no accepted proposal and no target mutation.
+
+## 6. Ownership and Coordinator split
+
+coder2 solely owns `packages/db/src/schema.ts`, `packages/db/drizzle/**`, journal/metadata, and migration tests. No other lane generates migrations. Expand is additive; no drop/rename/narrow; constraints validate before NOT NULL; compatibility is same-DB only; contract is later.
+
+KBN-200/coder4 owns pure `MechanicalCoordinatorDecisionEngineV1`: complete immutable snapshots in, deterministic eligibility/proposal/retry decisions out; no ID loading, SQL, Gateway, Valkey, proof, persistence, restart I/O, or LLM.
+
+KBN-210/coder3 owns `MechanicalCoordinatorServicePortV1`: ID loading, locks, fresh proof, assignment/approval persistence, atomic fencing, lease/checkpoint/outbox, Valkey wakes, durable retry/quarantine, and `recoverFromPostgres`. Cycle: load snapshots → pure decision → persist assignment → authoritative approval/policy → acquire by IDs/locks → increment fence → lease → ack/heartbeat/checkpoint → submit to review or durable retry/quarantine. No completion/certification/merge method exists.
+
+## 7. Exact Gateway/DTO freeze for KBN-105
+
+### 7.1 Common wire rules
+
+Base is `/api/v1/workspaces/:workspaceId`. Mutations require header `Idempotency-Key` (1–128 chars). Existing-aggregate mutations also require `If-Match-Version` (positive integer); create and privileged assignment-cycle requests are the only exceptions, while proposal submission carries `expectedTargetVersion` in its body. Body workspace fields are forbidden. Tenant denial follows one 404/403 policy without foreign existence detail.
+
+```ts
+interface SuccessEnvelopeV1<T> {
+  contractVersion: '1.0.0';
+  data: T;
+  aggregateRevision: string;
+  correlationId: string;
+}
+interface ListEnvelopeV1<T> extends SuccessEnvelopeV1<T[]> {
+  page: { cursor: string | null; nextCursor: string | null; limit: number };
+}
+```
+
+Errors are the exact health/transport/version unions in §2 plus validation/auth/not-found. Public DTOs never expose/accept internal write proof.
+
+### 7.2 Exact route registry
+
+| Method/path                                             | Request body/query                                                                                                                                                                                                             | Success data                                                         |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `GET /kanban-health`                                    | none                                                                                                                                                                                                                           | `KanbanHealthResponseV1`                                             |
+| `GET /projects`                                         | `status,ownerUserId,ownerTeamId,cursor,limit`                                                                                                                                                                                  | project list                                                         |
+| `POST /projects`                                        | `name,key,description,status,priority,ownerUserId XOR ownerTeamId,metadata`                                                                                                                                                    | project                                                              |
+| `GET /projects/:projectId`                              | none                                                                                                                                                                                                                           | project                                                              |
+| `PATCH /projects/:projectId`                            | editable create fields + expected header                                                                                                                                                                                       | project                                                              |
+| `POST /projects/:projectId/archive`                     | `reason`                                                                                                                                                                                                                       | project                                                              |
+| `GET /tasks`                                            | `projectId,missionId,milestoneId,status,priority,ownerUserId,ownerTeamId,specialistRole,tag,dueState,archived,cursor,limit`                                                                                                    | task summary list                                                    |
+| `POST /tasks`                                           | `projectId,missionId?,milestoneId?,parentTaskId?,title,description?,acceptanceCriteria[],status,priority,rank,ownerUserId XOR ownerTeamId,specialistRole?,dueAt?,notBeforeAt?,estimateMinutes?,retryPolicy?,tagIds[],metadata` | task detail                                                          |
+| `GET /tasks/:taskId`                                    | none                                                                                                                                                                                                                           | task detail including readiness/dependencies/assignment/lease/events |
+| `PATCH /tasks/:taskId`                                  | editable non-transition fields                                                                                                                                                                                                 | task detail                                                          |
+| `POST /tasks/:taskId/transition`                        | `toStatus,reason?`                                                                                                                                                                                                             | task detail                                                          |
+| `POST /tasks/:taskId/move`                              | `toStatus?,beforeTaskId?,afterTaskId?`                                                                                                                                                                                         | task detail with persisted rank                                      |
+| `POST /tasks/:taskId/archive`                           | `reason`                                                                                                                                                                                                                       | task detail                                                          |
+| `PUT /tasks/:taskId/tags`                               | `tagIds[]`                                                                                                                                                                                                                     | task detail                                                          |
+| `POST /tasks/:taskId/dependencies`                      | `predecessorTaskId,type`                                                                                                                                                                                                       | dependency                                                           |
+| `DELETE /tasks/:taskId/dependencies/:predecessorTaskId` | no body                                                                                                                                                                                                                        | deleted dependency ID                                                |
+| `GET /tasks/:taskId/events`                             | `cursor,limit`                                                                                                                                                                                                                 | event list                                                           |
+| `GET /tags`                                             | `query,cursor,limit`                                                                                                                                                                                                           | tag list                                                             |
+| `POST /tags`                                            | `name,color?`                                                                                                                                                                                                                  | tag                                                                  |
+| `GET /change-proposals`                                 | `state,targetType,targetId,cursor,limit`                                                                                                                                                                                       | proposal list                                                        |
+| `POST /change-proposals`                                | `sourceNoteDigest,targetType,targetId,expectedTargetVersion,commandType,commandPayload`                                                                                                                                        | inert proposal                                                       |
+| `GET /change-proposals/:proposalId`                     | none                                                                                                                                                                                                                           | proposal                                                             |
+| `POST /change-proposals/:proposalId/accept`             | `reason`                                                                                                                                                                                                                       | proposal + normal command result                                     |
+| `POST /change-proposals/:proposalId/reject`             | `reason`                                                                                                                                                                                                                       | proposal                                                             |
+| `GET /coordinator/eligibility`                          | `projectId?,missionId?,cursor,limit`                                                                                                                                                                                           | `EligibilityDecisionV1[]`                                            |
+| `POST /coordinator/assignment-cycles`                   | `limit`                                                                                                                                                                                                                        | assignment proposals; privileged internal                            |
+| `POST /coordinator/assignments/:assignmentId/approve`   | `decision,reason,policyRevision,artifactIds[]`                                                                                                                                                                                 | approval decision                                                    |
+| `POST /coordinator/leases/acquire`                      | `taskId,assignmentId,approvalDecisionId,targetSessionId,leaseTtlSeconds`                                                                                                                                                       | lease with decimal-string fence                                      |
+| `POST /coordinator/leases/:leaseId/ack`                 | `taskId,sessionId,fencingToken`                                                                                                                                                                                                | lease                                                                |
+| `POST /coordinator/leases/:leaseId/heartbeat`           | `taskId,sessionId,fencingToken,extendSeconds`                                                                                                                                                                                  | lease                                                                |
+| `POST /coordinator/leases/:leaseId/checkpoints`         | `taskId,sessionId,fencingToken,sequence,resumableSummary,artifactIds[],contextUsagePercent`                                                                                                                                    | checkpoint                                                           |
+| `POST /coordinator/leases/:leaseId/submit-review`       | `taskId,sessionId,fencingToken,artifactIds[],summary`                                                                                                                                                                          | task in `in_review`                                                  |
+
+All Coordinator mutations except human approval are service-identity-only. Generic task PATCH cannot perform claim/heartbeat/checkpoint/review/certification/completion shortcuts. Completion after certification uses a separately gated lifecycle command owned by the Portfolio/Sub-Orchestrator flow, not the Coordinator.
+
+### 7.3 DTO invariants
+
+Task summary/detail use exact schema vocabularies, owner union, `version: number`, `fencingCounter: string`, explicit `archivedAt/by/reason`, normalized tags, computed readiness, and separate assignment/lease. Assignment DTO includes one persisted ID, task/version, exact principal/agent/session, role, state, expiry, policy, proposer/reason. Lease/checkpoint DTOs serialize every fence as decimal string. Proposal DTO exposes no hidden write authority.
+
+### 7.4 MCP ownership and mapping
+
+coder3 exclusively owns:
+
+- `apps/gateway/src/mcp/mcp.dto.ts`
+- `mcp.controller.ts`
+- `mcp.service.ts`
+- `mcp.module.ts`
+- `mcp.tokens.ts`
+- `mcp.service.spec.ts`
+
+MCP tools are thin maps: `mosaic_projects_{list,get,create,update,archive}`, `mosaic_tasks_{list,get,create,update,transition,move,archive,set_tags,add_dependency,remove_dependency}`, and `mosaic_change_proposals_{list,get,submit,accept,reject}` to the exact routes above. coder4 owns CLI/projection clients only and must not edit Gateway MCP files.
+
+KBN-105 publishes route+DTO fixture digest before KBN-110/120/130. Every web/CLI/MCP call must match this registry and the generated client.
+
+## 8. Recovery contract and bounded delivery slice
+
+Runtime must invoke normative `validateRecoveryPostureV1`; JSON Schema alone is insufficient. It rejects unknown fields, PITR/WAL mismatch, RPO better than mechanism, unsafe storage, and weakened High-assurance. High-assurance is RPO 15m/RTO 4h, WAL ≤5m, PITR ≥35d, base ≤24h, restore test ≤30d, break-glass ≤90d, encrypted separate-failure-domain storage.
+
+KBN-115/coder2 owns `packages/config/src/recovery-posture.ts`, tests, and recovery runbook. It wires parser/refinement, override audit, mechanism assertions, restore test, and break-glass evidence. Any deployment manifest is separately enumerated and Mos-serialized. Recovery config has no SOT/gate/Coordinator authority fields.
+
+## 9. Integration, security, and hold
+
+Required release evidence includes KBN-101 foundation role/schema-boundary and post-KBN-100 real immutable-operation deployed-role certificates (not synthetic roles), empty/prod/partial/rollback/N-1 migration tests; cross-workspace and same-workspace wrong-project negatives; active-membership owners/principals; proposal inertness/normal acceptance; exact failure mapping; concurrent monotonic bigint fences; relational lease/checkpoint/evidence mismatch; immutability privileges/RESTRICT; recovery validation/mechanism evidence; endpoint registry alignment; accessible web journeys; author≠reviewer; mandatory SecReview; final Certifier pass/no merge authority.
+
+### 9.1 SI-001 amendment gate and #757 boundary
+
+- KBN-100 must provide the §5.2 candidate-key ordering, duplicate-feasibility, exact-FK reconciliation, empty/prod/N-1/rollback, and two-child foreign-workspace evidence before SI-001 can be certified closed.
+- All prior KCR-001–016 decisions and fixed SOT/tenant/authority, proposal-audit, approval, task-fencing, immutability, and no-cascade invariants remain unchanged.
+- Read-only PR #757 cross-check: its logical-agent connector lease/CAS fencing uses separate runtime tables/contracts and `lease_epoch`; rc.4 changes only the frozen `missions` candidate key. There is no shared table, index, FK, identity, fence, or authority semantic to consume or reconcile, and #757 remains owned by its existing lane.
+
+The build hold remains active until independent re-review reports GO for KCR-001–016 and the rc.4 SI-001 amendment. Mos alone releases waves and serializes integration roots.

docs/native-kanban-sot/TASKS.md

@@ -0,0 +1,278 @@
+# Native Kanban/SOT P0–P3 — Dependency-Ordered Build Slices
+
+**Status:** CANON INDEPENDENTLY APPROVED; PUBLICATION IN PROGRESS
+**Tracking:** [Mosaic Stack issue #751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
+**Execution:** USC web1 only; collision-free GPT coder2/3/4/5 lanes
+**Contract:** `SHARED-CONTRACT.md` + four `contracts/*.v1.ts` files
+**Implementation hold:** no feature slice starts until the canon PR is merged to `main` with terminal-green CI; after merge, each slice remains held until every declared KBN prerequisite is complete.
+
+> This publication file is not a runtime task authority. After cutover, repository `TASKS.md` is generated read-only and never imported.
+
+## Execution invariants
+
+- PostgreSQL is the sole writable SOT; current-main Drizzle is the persistence foundation.
+- Mutations require fresh internal PostgreSQL transaction-local write proof and fail closed otherwise.
+- Public health DTOs, Valkey, files, browser state, providers, and outage notes cannot authorize writes.
+- Outage notes return only through attributable `change_proposals`; proposal acceptance executes the normal command.
+- Mechanical Coordinator is non-LLM and cannot invent scope, waive gates, certify, or merge.
+- Certifier is final independent gate with no merge authority.
+- Workspace is the hard tenant. Project hierarchy is project-congruent. Assignment, approval, lease, fence, checkpoint, and evidence are relationally bound.
+- Recovery tiers change recovery posture only.
+
+## 1. Collision-free ownership
+
+| USC lane                                                | Exclusive ownership                                                                                                                                                                                                                                                                                              | Must not edit                                               |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| **coder2 — schema/recovery**                            | `packages/db/src/schema.ts`; `packages/db/drizzle/**`; DB tests; `packages/config/src/recovery-posture.ts`; `packages/config/src/recovery-posture.spec.ts`; `docs/runbooks/kanban-postgres-recovery.md`                                                                                                          | Gateway, Brain repositories, Coordinator, web, CLI/importer |
+| **coder3 — domain/Gateway/MCP server**                  | Kanban repositories under `packages/brain/src/`; Gateway workspace/project/mission/milestone/task/kanban/health/coord modules; **exact MCP files:** `apps/gateway/src/mcp/mcp.dto.ts`, `mcp.controller.ts`, `mcp.service.ts`, `mcp.module.ts`, `mcp.tokens.ts`, `mcp.service.spec.ts`; Gateway root wiring/tests | DB schema/migrations, `packages/coord`, web, CLI/importer   |
+| **coder4 — CLI → pure Coordinator → migration tooling** | In this one fixed lane order: KBN-120 (`packages/mosaic` CLI/projection) → KBN-200 (`packages/coord/src/mechanical/**`) → KBN-300/320 (`scripts/kanban-migration/**`)                                                                                                                                            | DB, Gateway/MCP server, web                                 |
+| **coder5 — web**                                        | `apps/web/src/app/(dashboard)/{tasks,projects}/**`; `apps/web/src/components/{tasks,projects}/**`; Kanban web API/types; later Coordinator/migration-review routes                                                                                                                                               | DB, Gateway, Coordinator, CLI/importer                      |
+| **Mos — publication/integration**                       | Contract amendments, exact endpoint registry publication, serialized root exports/manifests/lockfiles, integration gates                                                                                                                                                                                         | Active lane feature files                                   |
+
+Shared roots, package exports/manifests, lockfiles, and generated artifacts are integration-serialized. Contract changes stop affected lanes and require Mos approval.
+
+## 2. Parallelization legend
+
+- **SERIAL:** prerequisite must be complete and reviewed.
+- **PARALLEL-GROUP:** disjoint files and exact frozen contract permit concurrent work.
+- **LANE-SERIAL:** one lane's stated order cannot change.
+- **INTEGRATION-SERIAL:** component heads green first; semantic findings return to owner.
+
+## 3. Corrected dependency graph
+
+```text
+KBN-000 canon remediation
+  -> KBN-010 threat/auth/constraint-impact gate (MUST COMPLETE)
+      -> KBN-101 foundation role/schema-boundary certificate (SERIAL)
+          -> KBN-100 schema + concrete N-1 migration implementation
+              ├─ KBN-101 post-KBN-100 deployed-role immutable-operation certificate (SERIAL)
+              │    -> KBN-105 exact endpoint/DTO/error/registry freeze (SERIAL)
+              │        ├─ KBN-110 domain + Gateway + MCP server implementation
+              │        ├─ KBN-120 CLI/projection implementation [coder4 first]
+              │        └─ KBN-130 web MVP implementation
+              └─ KBN-115 recovery parser/mechanism slice [coder2 lane-serial]
+KBN-110 + KBN-120 + KBN-130 + KBN-115
+  -> KBN-140 P1 integration/SIT
+      -> KBN-200 pure decision engine [coder4 after KBN-120]
+          -> KBN-210 persistence/service adapter + approval/lease binding
+              -> KBN-220 Coordinator operations UI
+                  -> KBN-230 P2 concurrency/fault/gate integration
+KBN-230
+  -> KBN-300 importer dry-run/apply/verify [coder4 after KBN-200]
+      ├─ KBN-310 migration reviewer UI
+      └─ KBN-320 cutover/rollback tooling [coder4 after KBN-300]
+KBN-310 + KBN-320
+  -> KBN-330 rehearsal/reconciliation
+      -> KBN-340 owner-gated cutover/stabilization
+```
+
+No consumer implementation begins before KBN-105. No schema work begins before KBN-010 completes and the KBN-101 foundation role/schema-boundary certificate passes; the real immutable-operation certificate follows KBN-100 and blocks KBN-105. The coder4 order is always KBN-120 → KBN-200 → KBN-300 → KBN-320.
+
+## 4. P0 — Canon, threat gate, schema, and exact API freeze
+
+### KBN-000 — Remediate and publish canon
+
+- **Status:** COMPLETE — PR #752 squash-merged as `49e8a54`; issue #751 closed; post-merge pipeline #1798 terminal success.
+- **Owner:** Mosaic publication control plane.
+- **Mode:** SERIAL; completed.
+- **IN:** Resolve KCR-001–016 in requirements, schema, health, Coordinator, recovery, migration map, and slices; independent re-review.
+- **OUT:** Feature implementation.
+- **Depends on:** none.
+- **Contract surfaces:** all canon.
+- **Evidence:** strict TS; Prettier; per-finding traceability; independent author≠reviewer GO; Ultron GO; terminal-green CI.
+
+### KBN-010 — Threat, authorization, and constraint-impact gate
+
+- **Status:** IN PROGRESS — issue [#753](https://git.mosaicstack.dev/mosaicstack/stack/issues/753).
+- **Owner:** `kbn-coder3`; independent `secrev`.
+- **Mode:** SERIAL prerequisite of KBN-100.
+- **Exclusive files:** `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` and task scratchpad only.
+- **IN:** Cross-workspace owners/principals/evidence; active membership; stale/forged health; approval forgery; fence monotonicity; audit retention; proposal target/audit-event forgery; service tokens; DB/Valkey outage.
+- **OUT:** Runtime/schema edits.
+- **Depends on:** KBN-000 independent re-review GO.
+- **Contract surfaces:** schema constraints, health proof, exact errors, command-family authorization.
+- **Evidence:** signed constraint-impact matrix; no unresolved schema-impact finding; SecReview pass.
+
+### KBN-101 — PostgreSQL runtime/migration role split and deployed-role certification
+
+- **Status:** IN PROGRESS — issue [#771](https://git.mosaicstack.dev/mosaicstack/stack/issues/771); rc.11 closes the two exact-head re-review HIGH findings: trusted runner-produced target-bound Ed25519 importer attestation and complete finite operator-document disposition including the user guide. It awaits independent exact-head re-review; implementation remains held.
+- **Owner:** Mos integration control plane; independently reviewed by security/Ultron.
+- **Mode:** SERIAL foundation certificate blocks KBN-100; its post-KBN-100 real immutable-operation certificate blocks KBN-105.
+- **IN:** Exact `DATABASE_URL` non-owner runtime versus `DATABASE_MIGRATION_URL` owner/migrator connection contract; sole published `mosaic-db-migrator --run|--verify` PostgreSQL DDL path and all legacy/future entrypoint closure; active migrate-tier destination only after runner prepare/verify through exact `--target-url-file /run/secrets/mosaic_migrate_target_url` plus signed `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`, runner-only signing key/public-key isolation, target secret/TLS/CA/server/database/role/manifest/schema binding, expiry/replay/rotation/TOCTOU/no-DML controls, and dedicated non-DDL importer; finite exact-path scanner/allowlist/active-route review and every-path before-connect denial matrix; `DATABASE_TLS_CA_CERT_PATH` plus operator/IaC CA/server-key/cert lifecycle, exact service-DNS SANs, Vault/compose/Swarm mount modes, TLS server/bootstrap/rotation/rollback; PGlite exception; fixed two-int advisory lock; manifest-v1 logical-index/tag/exact-byte-SHA-256 ledger reconciliation including safe `0009`; fixed `mosaic` schema and exact `pg_catalog,mosaic` pooled session path; platform/schema/`NOLOGIN SUPERUSER` extension-owner/migrator/importer/runtime roles; approved-owner versus legacy-owner shadow pgvector transition; ownership, zero membership/no runtime secret, TEMP/ledger-read/default privilege and immutable grant proof; N-1 inactive prepared cards then atomic activation/rollback authority; Vault/redaction/observability/operator runbooks; one-card/one-PR implementation DAG.
+- **OUT:** Production mutation in this planning card; KBN-100 tables/data backfill; application API behavior; KBN-105 route/DTO freeze.
+- **Depends on:** KBN-010 completed.
+- **Contract surfaces:** [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md); `SHARED-CONTRACT.md` rc.11 amendment.
+- **Evidence:** foundation: exact `--help|--run|--verify`/exit/argv/import-negative plus DTO entrypoint negatives for every finite classified current DDL/static-bypass path (including `DATABASE_URL`-only, runner fixture, retired init, sanitized current operator guidance, both harness pairs, and `db:push` refusal); active migrate-tier paired URL-file/attestation-file, signing/public-key isolation, atomic JCS/Ed25519, secret-version/digest/TLS/CA/server/database/role/manifest/schema binding, expiry/replay/rotation/TOCTOU, zero-connection versus zero-DML, prepared-target/importer/no-DDL negatives; clean/pre-0009/skipped/applied-late/duplicate/unknown/missing/corrupt/stale/backup plus public-to-`mosaic`/partial/reverse runner proof; fixed-lock contention/crash/readiness/unrelated-key tests; runtime cannot invoke migrations/DDL/TEMP; actual pgvector 0.8.2 control metadata, fresh/approved-owner existing/legacy-owner shadow/partial-resume-rollback/N-1 pgvector evidence with `rolcanlogin=false`, `rolsuper=true`, zero members, external-superuser `SET ROLE`/`RESET ROLE` audit, `pg_extension.extowner`, owner-bearing member/schema/version and runtime/migrator/schema-owner/importer/all-service-role `SET ROLE`/ALTER/DROP/member-update denial; disposable standalone, federated/Swarm, and two-gateway verified-TLS positives plus both-pair CA/SAN/downgrade/key mode/UID-GID/URL-secret consumer-isolation and legacy-drain/`hostssl` zero-plaintext negatives; exclusive bootstrap/renderer/manifest ownership test; catalog relocation/vector-query/operator/Drizzle-only-`mosaic`, role/grant/search-path/pool-reset/identifier checks; N-1/atomic TLS-only rollback/no-force-on-red rehearsal; named Vault/bootstrap-control-plane/CA-overlap/redaction/operator evidence; independent author≠reviewer security GO. Post-KBN-100: real deployed non-owner INSERT/SELECT and UPDATE/DELETE denial for immutable event/artifact/evidence relations plus Ultron GO.
+
+### KBN-100 — Unified Drizzle schema and concrete N-1 migration
+
+- **Owner:** **coder2**.
+- **Mode:** SERIAL.
+- **Exclusive files:** `packages/db/src/schema.ts`, `packages/db/drizzle/**`, DB tests.
+- **IN:** All frozen tables/joins/enums; workspace/project-congruent constraints; owners/principals; tags/archive; change proposals with both workspace-aware task-event composite FKs and frozen event-before-proposal DDL order; assignment approvals; durable execution/quarantine; monotonic bigint fence; exact checkpoint/evidence joins; RESTRICT/immutability; concrete current-main expand/backfill/switch/contract map.
+- **OUT:** Repositories, Gateway, Coordinator behavior, UI, importer.
+- **Depends on:** **KBN-010 completed and KBN-101 foundation role/schema-boundary certificate PASS**. KBN-100 is blocked until both are terminal; it rebases on KBN-101 main, restores generated Drizzle declaration/snapshot/journal consistency, and confines procedural immutable-table grant/trigger/backfill work to its schema ownership. Its new relations are then subject to KBN-101 post-KBN-100 deployed-role certification.
+- **Contract surfaces:** `kanban-schema.v1.ts`; SHARED-CONTRACT current-main delta map.
+- **Evidence:** reviewed SQL; empty/prod-shape/partial-resume/rollback tests; N-1 app safety; legacy columns remain declared; workspace/project mismatch negatives; proposal event-FK missing/foreign-workspace tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; SecReview.
+
+### KBN-105 — Exact Gateway/MCP endpoint, DTO, and error freeze
+
+- **Owner:** Mos + coder3 contract author; independent endpoint-alignment reviewer.
+- **Mode:** SERIAL after KBN-100; prerequisite for KBN-110/120/130.
+- **Exclusive files:** canonical endpoint-registry/DTO contract docs; no implementation.
+- **IN:** Exact routes and methods from SHARED-CONTRACT §8; request/success/error fields; status codes; pagination/filter/revision envelopes; idempotency/expected-version headers/fields; proposal commands; health proof exclusion from public DTOs; MCP tool-to-route map.
+- **OUT:** Controller/service/client implementation.
+- **Depends on:** KBN-100 and KBN-101 post-KBN-100 deployed-role immutable-operation certification PASS.
+- **Contract surfaces:** health/error unions; schema IDs/statuses; Gateway DTO freeze.
+- **Evidence:** every FE/CLI/MCP call maps 1:1 to a route; 503/502-504/409 non-cross-map fixtures; contract digest published.
+
+### KBN-115 — Recovery posture parser, mechanisms, and evidence
+
+- **Owner:** **coder2**, lane-serial after KBN-100.
+- **Mode:** PARALLEL with KBN-110/120/130 after KBN-105.
+- **Exclusive files:** `packages/config/src/recovery-posture.ts`, `.spec.ts`, `docs/runbooks/kanban-postgres-recovery.md`; deployment-specific backup manifest changes are a separately enumerated Mos integration patch.
+- **IN:** Wire normative `validateRecoveryPostureV1`; override audit; backup/WAL/PITR mechanism assertions; off-cluster encryption/failure-domain checks; restore and break-glass evidence procedure.
+- **OUT:** SOT/gate/Coordinator policy knobs; DB business schema.
+- **Depends on:** KBN-100, KBN-105.
+- **Contract surfaces:** `recovery-posture.v1.ts` only.
+- **Evidence:** impossible-combination tests; High-assurance weakening tests; selected-tier mechanism verification; restore and break-glass evidence; SecReview.
+
+## 5. P1 — Thin native MVP
+
+### KBN-110 — Workspace-safe domain, Gateway, MCP server, and proposal commands
+
+- **Owner:** **coder3**.
+- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
+- **Exclusive files:** ownership map, including all exact MCP server files listed there.
+- **IN:** Workspace-safe repositories; project/task/dependency/tag/archive CRUD; transitions; exact owners; assignment/approval/link/artifact queries; submit/query/accept/reject change proposals; health endpoint; internal write-proof mint/revalidation; event/outbox atomicity; frozen DTOs/routes.
+- **OUT:** Scheduling algorithm, web, CLI, DB schema.
+- **Depends on:** KBN-100, KBN-105.
+- **Contract surfaces:** all four TypeScript contracts and exact registry.
+- **Evidence:** DTO/service/controller/integration tests; active-membership and no-oracle negatives; proposal cannot mutate directly; submission event is the new proposal's exact `change_proposal.submitted` event; acceptance links the executed normal command for the locked proposal and same workspace/target; missing, foreign-workspace, unrelated-proposal/target/command event negatives; exact failure mapping; endpoint registry; SecReview.
+
+### KBN-120 — CLI, MCP client mapping, and generated projection
+
+- **Owner:** **coder4**; first coder4 slice.
+- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
+- **Exclusive files:** `packages/mosaic/src/commands/{kanban,tasks,projects}.ts`; `packages/mosaic/src/projections/**`; tests. **No `apps/gateway/src/mcp/**` edits.\*\*
+- **IN:** Frozen query/mutation routes; proposal commands; compact context; generated `TASKS.md`; deliberate denial/transport/conflict handling.
+- **OUT:** Gateway/MCP server, file importer, raw SQL/Valkey, Coordinator.
+- **Depends on:** KBN-105; runtime integration later requires KBN-110.
+- **Evidence:** contract fixtures; same revision; no import parser; same idempotency key on transport retry; 503 never auto-retried.
+
+### KBN-130 — Writable Kanban/List and minimal Projects UI
+
+- **Owner:** **coder5**.
+- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
+- **Exclusive files:** web ownership map.
+- **IN:** Workspace context; projects; tasks; tags; explicit archive; detail; accessible move/reorder; filters; dependency/readiness; owner/assignment/lease; audit; proposal visibility; conflict/loading/error/reconnect.
+- **OUT:** Gateway/schema, Coordinator operations UI, migration UI.
+- **Depends on:** KBN-105; runtime integration later requires KBN-110.
+- **Evidence:** frozen contract mocks; real-Gateway journeys; keyboard/non-drag; tags/archive semantics; no-oracle tenant negatives; 503/transport/409 distinct UI.
+
+### KBN-140 — P1 integration and situational gate
+
+- **Owner:** Mos integration; independent reviewer/SecReview/Certifier.
+- **Mode:** INTEGRATION-SERIAL.
+- **IN:** KBN-110/120/130/115; unavoidable root exports only.
+- **OUT:** P2 behavior.
+- **Depends on:** KBN-110, KBN-120, KBN-130, KBN-115.
+- **Evidence:** clean migration; web/CLI/MCP/projection revision parity; forged/expired health negatives; change-proposal event-chain success plus missing/foreign/unrelated-event negatives; tag/archive; tenant negatives; endpoint registry; author-independent review; Certifier pass.
+
+## 6. P2 — Mechanical Coordinator
+
+### KBN-200 — Pure deterministic decision engine
+
+- **Owner:** **coder4**; second coder4 slice, strictly after KBN-120.
+- **Mode:** SERIAL in coder4 lane.
+- **Exclusive files:** `packages/coord/src/mechanical/**` and pure tests.
+- **IN:** `MechanicalCoordinatorDecisionEngineV1`; complete immutable snapshots; eligibility/explanation; fairness/order; capability matching; expiry/retry/quarantine decisions.
+- **OUT:** ID loading, PostgreSQL, Drizzle, Gateway, Valkey, health-proof minting, persistence, `recoverFromPostgres`, LLM calls.
+- **Depends on:** KBN-140 (or Mos may release after KBN-120 + frozen types if no P1 semantic risk remains).
+- **Evidence:** deterministic/property tests; snapshot completeness; no I/O/model imports; no authority methods.
+
+### KBN-210 — Coordinator persistence/service adapter and approval-bound leases
+
+- **Owner:** **coder3**.
+- **Mode:** SERIAL after KBN-200.
+- **Exclusive files:** Gateway `coord` and repositories.
+- **IN:** `MechanicalCoordinatorServicePortV1`; snapshot loading; proposal persistence; manual/versioned policy approval; acquire by IDs; reload+lock task/assignment/approval/session; fresh txn-local write proof; atomic task fence increment; lease/ack/heartbeat/checkpoint/submit; durable retry/quarantine; outbox/Valkey wake; restart recovery.
+- **OUT:** Pure algorithm, UI, DB schema.
+- **Depends on:** KBN-110, KBN-200.
+- **Evidence:** forged/stale approval rejection; target/session/version/expiry/policy checks; concurrent monotonic fences; same-workspace mismatch negatives; bigint precision; stale worker rejection; DB/Valkey faults; SecReview.
+
+### KBN-220 — Coordinator operations UI
+
+- **Owner:** **coder5**.
+- **Mode:** after KBN-210 exact DTO freeze.
+- **IN:** Roster; eligibility; persisted assignment state; approvals/overrides; exact lease/fence; durable retry/quarantine; role/gate/Certifier visibility.
+- **OUT:** Scheduling decisions, schema, merge control for Certifier.
+- **Depends on:** KBN-210.
+- **Evidence:** authorized journeys; reason required; stale refresh; no Certifier merge; endpoint alignment/accessibility.
+
+### KBN-230 — P2 concurrency/fault/gate integration
+
+- **Owner:** Mos integration; independent reviewer/SecReview/Certifier.
+- **Mode:** INTEGRATION-SERIAL.
+- **Depends on:** KBN-200, KBN-210, KBN-220.
+- **Evidence:** one lease; monotonic fences; exact relational mismatches rejected; expired proof; forged healthy; approval binding; restart; durable quarantine; outbox recovery; author≠reviewer; Certifier final/no merge.
+
+## 7. P3 — Shadow migration and cutover
+
+### KBN-300 — One-way importer dry-run/apply/verify
+
+- **Owner:** **coder4**; third coder4 slice.
+- **Mode:** after KBN-230.
+- **Exclusive files:** `scripts/kanban-migration/import/**`.
+- **IN:** Immutable jarvis-brain/Vikunja snapshots; deterministic mapping; source digest/lineage; Gateway writes; rejects; no dispatch.
+- **OUT:** Bidirectional sync, direct DB/file canonical writes, unrelated brain data.
+- **Depends on:** KBN-230.
+- **Evidence:** idempotency; counts/fields; malformed/foreign rejects; no dispatch; SecReview.
+
+### KBN-310 — Shadow reviewer UI
+
+- **Owner:** **coder5**.
+- **Mode:** PARALLEL-GROUP P3-A after KBN-300 report freeze.
+- **IN:** Read-only counts/diffs/rejects/lineage/sign-off.
+- **OUT:** Apply/cutover mutations.
+- **Depends on:** KBN-300.
+- **Evidence:** read-only and tenant tests; pagination/accessibility.
+
+### KBN-320 — Cutover/rollback tooling
+
+- **Owner:** **coder4**; fourth coder4 slice, after KBN-300.
+- **Mode:** PARALLEL-GROUP P3-A with KBN-310.
+- **Exclusive files:** `scripts/kanban-migration/cutover/**`.
+- **IN:** Freeze assertion; backup/checksum; final delta; client switch; legacy writer/credential shutdown; rollback delta; stabilization.
+- **OUT:** Destructive deletion, reverse sync, ungated production execution.
+- **Depends on:** KBN-300.
+- **Evidence:** fail-safe rehearsal; no dual writer; rollback authority; SecReview.
+
+### KBN-330 — Migration rehearsal/reconciliation
+
+- **Owner:** Mos + coder4 support + independent data reviewer.
+- **Mode:** INTEGRATION-SERIAL.
+- **Depends on:** KBN-310, KBN-320.
+- **Evidence:** signed exceptions; selected-tier restore; backlog hold; no legacy changes; Certifier readiness.
+
+### KBN-340 — Final cutover/stabilization
+
+- **Owner:** Mos/control plane; owner-gated operation.
+- **Mode:** SERIAL.
+- **Depends on:** KBN-330 PASS and Jason authorization.
+- **Evidence:** no legacy writer; scoped Gateway identities; no accidental dispatch; terminal green health/CI; Certifier evidence; owner retirement approval.
+
+## 8. Consistent USC wave schedule
+
+| Wave | coder2                                    | coder3                                                                               | coder4                         | coder5                         |
+| ---- | ----------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------ | ------------------------------ |
+| 0    | Wait                                      | **KBN-010**                                                                          | Wait                           | Wait                           |
+| 0.5  | Wait                                      | **KBN-101 foundation** Mos-controlled role/connection contract and certificate       | Wait                           | Wait                           |
+| 1    | **KBN-100** after KBN-101 foundation PASS | Review bounded schema/grant implementation                                           | Wait                           | Wait                           |
+| 1.5  | Certification support                     | **KBN-101 post-KBN-100 deployed-role immutable-operation certificate**, then KBN-105 | Wait                           | Wait                           |
+| 2    | **KBN-115** after KBN-100                 | **KBN-105** exact freeze, then KBN-110                                               | **KBN-120** only after KBN-105 | **KBN-130** only after KBN-105 |
+| 3    | Review support                            | Finish KBN-110                                                                       | **KBN-200 after KBN-120**      | Finish KBN-130                 |
+| 4    | —                                         | **KBN-210 after KBN-200**                                                            | Review/support                 | **KBN-220 after KBN-210 DTOs** |
+| 5    | —                                         | P2 remediation                                                                       | **KBN-300 then KBN-320**       | **KBN-310**                    |
+
+Mos alone releases slices and lifts the build hold after independent re-review GO.

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

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

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

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

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

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

docs/native-kanban-sot/tsconfig.json

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

docs/openapi-tess.yaml

@@ -124,7 +124,7 @@ paths:
         {
           summary: Submit Mos handoff,
           parameters: [{ $ref: '#/components/parameters/correlation' }],
-          requestBody: { $ref: '#/components/requestBodies/MosHandoff' },
+          requestBody: { $ref: '#/components/requestBodies/Handoff' },
           responses: { '200': { description: Receipt } },
         },
     }
@@ -261,7 +261,7 @@ components:
               },
           },
       }
-    MosHandoff:
+    Handoff:
       {
         required: true,
         content:

docs/plans/2026-03-15-agent-platform-architecture.md

@@ -1464,9 +1464,11 @@ Generate and apply:
 
 ```bash
 pnpm --filter @mosaicstack/db db:generate  # generates migration SQL
-pnpm --filter @mosaicstack/db db:migrate   # applies to PG
+mosaic-db-migrator --run                   # sole PostgreSQL migration runner
 ```
 
+> **KBN-101 supersession:** `pnpm --filter @mosaicstack/db db:migrate` is superseded and MUST NOT be used. The runner receives only deployment-injected migration credentials; it accepts no URL, SQL, schema, or role argv.
+
 Platform enforcement keys (seeded with `mutable = false` by gateway `PreferencesService.onModuleInit()`):
 
 | Key                       | Category | Reason                                    |

docs/reports/code-review/756-code-review.md

@@ -0,0 +1,27 @@
+# Independent Code Review — #756 Official Discord Channel Plugin
+
+**Verdict: APPROVE**
+
+## Scope reviewed
+
+Complete current uncommitted #756 delta: multi-binding trusted agent selection, privileged ingress-route validation, attachment validation/persistence/resume, egress route lifecycle and idempotency, concurrent gateway stream state, Discord lifecycle/thread/rate behavior, compatibility ingress, and tests.
+
+## Review result
+
+No blocking or change-request finding remains.
+
+- **Trusted multi-agent routing:** each binding requires a provisioned `agentConfigId`; the gateway resolves that config server-side, verifies its logical-agent name, and never accepts a Discord-controlled agent selection or applies generic routing to Discord ingress.
+- **Auth and route integrity:** allowlist, pairing, role, and canonical logical-agent/channel-or-thread conversation-route validation occur before gateway processing. Privileged approval/stop paths use the same binding and route validation.
+- **Attachments:** ingress rejects malformed, over-bounded, credential-bearing, fragment-bearing, or query-bearing URLs. Valid attachment metadata, including `sizeBytes`, persists and is reconstructed into resume history as explicitly untrusted context.
+- **Discord reliability:** the adapter supports degraded Socket.IO reconnect, parent/thread routing semantics, bounded pre-side-effect ingress rates, and terminal response-route cleanup. Egress validates route/message alignment, sends deterministic nonces, distinguishes permanent from transient errors, and uses bounded retries.
+- **Concurrent state:** per-client/conversation keys isolate listener, redaction, tool, and stream state for simultaneous threads sharing a Discord socket; disconnect cleanup covers all associated conversations.
+- **Harness neutrality:** contracts retain logical-agent/channel data only; no harness/provider identity leaks into adapter routes or message boundaries.
+
+## Verification performed
+
+- `git diff --check` — passed.
+- `pnpm --filter @mosaicstack/discord-plugin typecheck` — passed.
+- `pnpm --filter @mosaicstack/discord-plugin lint` — passed.
+- `pnpm --filter @mosaicstack/discord-plugin test` — passed: 44 tests; coverage 92.18% statements/lines, 86.55% branches, 100% functions (all ≥85% threshold).
+- `pnpm --filter @mosaicstack/gateway typecheck` — passed.
+- `cd apps/gateway && pnpm exec vitest run src/plugin/discord-ingress.security.spec.ts src/chat/chat.gateway-redaction.spec.ts src/__tests__/integration/tess-cross-surface.integration.test.ts` — passed: 32 tests.

docs/reports/documentation/756-discord-plugin-checklist.md

@@ -0,0 +1,36 @@
+# Documentation Completion Checklist — #756 Official Discord plugin
+
+## Required artifacts
+
+- [x] `docs/PRD.md` includes the #756 workstream, assumptions, and acceptance criteria.
+- [x] User workflow updated in `docs/tess/USER-GUIDE.md`.
+- [x] Administrator configuration and authorization policy updated in `docs/guides/admin-guide.md`.
+- [x] Developer/plugin authoring guidance updated in `docs/tess/PLUGIN-GUIDE.md`.
+- [x] Channel architecture updated in `docs/architecture/channel-protocol.md`.
+- [x] Package operations/development guide added at `plugins/discord/README.md`.
+- [x] `docs/SITEMAP.md` links the official channel plugin documentation.
+
+## API coverage
+
+- [x] No HTTP or WebSocket endpoint was added, removed, or changed.
+- [x] No OpenAPI update is needed.
+- [x] Shared TypeScript contracts are documented in architecture and plugin-authoring guides.
+- [x] Discord authentication, authorization, thread failure, and control-command behavior are documented.
+
+## Structural standards
+
+- [x] Working notes remain under `docs/scratchpads/`.
+- [x] Review and checklist artifacts remain under `docs/reports/`.
+- [x] No generated publishing output was added.
+- [x] Existing repository documentation structure was preserved; no unrelated root cleanup was attempted.
+
+## Review gate
+
+- [x] Independent documentation/contract review passes (shared-contract review plus final code review of the current documentation delta).
+- [x] Independent code review verifies documentation matches implementation (`docs/reports/code-review/756-code-review.md`: APPROVE).
+- [x] Independent security review verifies documented controls (`docs/reports/security/756-security-review.md`: APPROVE).
+
+## Publishing
+
+- [x] Canonical source remains in-repository.
+- [x] No external publishing action is in scope for this slice.

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

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

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

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

docs/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md

@@ -0,0 +1,109 @@
+# KBN-101 contract independent security/architecture review
+
+**Verdict: REQUEST CHANGES**
+
+## Review identity and scope
+
+- **Exact reviewed head:** `da742ca2da4a2ff466916c818fe275c4f7ffd384` (`docs(#771): record role-split review evidence`)
+- **Required comparison:** `origin/main...da742ca2da4a2ff466916c818fe275c4f7ffd384`
+- **Range:** `82ce3252df38a687c50485f8d048b53ca8db5989` is an ancestor of the reviewed head; the final head adds the scratchpad evidence commit and was reviewed.
+- **Changed docs:** `docs/PRD.md`, `docs/SITEMAP.md`, `docs/native-kanban-sot/{INDEX.md,KBN-101-DB-ROLE-SPLIT.md,SHARED-CONTRACT.md,TASKS.md}`, and `docs/scratchpads/771-kbn101-db-role-split.md` (300 additions / 25 deletions).
+- **Reviewed inputs:** issue #771; current DB/Gateway/storage/config/wizard/installer/compose/Portainer/CI sources; all current migration/DDL references; KBN-010, rc.4/rc.5 shared contract, requirements/canon, KBN-100 #769 branch context, and the final scratchpad.
+- **Repository/provider state:** not modified. The pre-existing `.mosaic/orchestrator/*` dirt was not touched.
+
+The role graph itself is sound in principle: a NOLOGIN platform database owner, separate NOLOGIN schema owner, NOINHERIT migrator which explicitly `SET ROLE`s, and runtime membership only in a capability role with `SET FALSE` does not create circular privilege or application-created login roles. The split of foundation certification before KBN-100 and immutable-operation certification after KBN-100 is also correctly ordered.
+
+## Findings
+
+### HIGH — DDL/migration control plane is not closed at every current entrypoint
+
+The contract requires an explicit, locked migration phase and forbids Gateway/runtime DDL (`KBN-101-DB-ROLE-SPLIT.md:34-39`), but its KBN-101-02 result merely says migration-capable commands use the migration DTO (`:109`). It does not prohibit or route every existing bypass through that one command.
+
+Current bypasses include:
+
+- `runMigrations()` falls back from an argument to `DATABASE_URL` and a hard-coded URL (`packages/db/src/migrate.ts:24-35`), while `drizzle.config.ts` likewise uses `DATABASE_URL` plus a default (`packages/db/drizzle.config.ts:3-9`).
+- Package scripts expose direct `drizzle-kit migrate` **and** `drizzle-kit push` (`packages/db/package.json:23-26`); `db:push` bypasses the planned journal/fingerprint/lock entirely.
+- `mosaic storage migrate --run` shells out to the direct `db:migrate` script (`packages/storage/src/cli.ts:413-452`).
+- The federated integration test can create types, tables, and indexes directly against `DATABASE_URL` and intentionally operates without a Drizzle ledger (`packages/db/src/federation.integration.test.ts:28-30,46-134`).
+
+**Failure mode:** a runtime or CI environment with only `DATABASE_URL`, or an operator invoking an existing command, can apply unverified DDL outside the lock, `SET ROLE` preflight, exact-ledger gate, and deployment sequencing. This breaks the requested fail-closed split even if Gateway startup is repaired.
+
+**Required remediation:** amend KBN-101-02/03/06 to enumerate these entrypoints and make the dedicated migrator runner the only PostgreSQL DDL path. Production-like `db:push` must be removed/blocked; `db:migrate`, `storage migrate --run`, and migration tests must invoke the same migration runner with `DATABASE_MIGRATION_URL`, lock, identity preflight, and ledger verification. Tests needing schema must consume a pre-migrated disposable database, or be explicitly run only by that migration phase. Add negative tests showing each command refuses `DATABASE_URL`-only execution and cannot reach DDL.
+
+### HIGH — TLS requirement has no deployable server/bootstrap contract
+
+The contract correctly requires a mounted CA and hostname-verified TLS (`KBN-101-DB-ROLE-SPLIT.md:25,28,93-95`). However KBN-101-05 promises only a “migration phase and secret binding boundary” (`:112`), not PostgreSQL server TLS, certificate issuance/SANs, CA distribution, startup ordering, or the fresh/existing-database bootstrap trust path.
+
+Current standalone and federated compose expose plain PostgreSQL with no server TLS configuration or CA mount (`docker-compose.yml:2-14`; `docker-compose.federated.yml:27-44`). The Portainer test stack passes a single plaintext in-network URL and uses the same database login for Gateway and database bootstrap (`deploy/portainer/federated-test.stack.yml:51-60,110-117`).
+
+**Failure mode:** enforcing the mandatory CA makes current local standalone/federated topologies unable to start; relaxing it to make bootstrap work silently violates K101-REQ-03. A first database cannot be safely migrated until the server certificate, its SAN for the actual service/DNS name, and trusted CA are provisioned, but this lifecycle is not owned or tested.
+
+**Required remediation:** add a concrete KBN-101-00/05 TLS bootstrap sub-contract: issuer/CA owner; server key/cert and SAN inputs; secure storage/mount permissions; `postgresql.conf`/container TLS enablement; migration and runtime CA mounts; hostname used by each compose/Swarm service; readiness only after TLS authentication; CA overlap rotation; and an existing-database transition. Require a disposable standalone and federated/Swarm test to prove verified TLS succeeds and missing CA, wrong CA, wrong SAN, and `sslmode` downgrade fail before readiness. Do not merge KBN-101-05 with an implicit plaintext exception.
+
+### HIGH — exact ledger fingerprint and historical 0009 repair are underspecified for existing databases
+
+The contract requires an “ordered complete set” and rejection of out-of-order rows (`KBN-101-DB-ROLE-SPLIT.md:36-38`), but does not define the canonical serialized tuple, ledger ordering source, or safe upgrade rule for a historical ledger. The current ledger stores only `id`, `hash`, and `created_at` (`packages/db/src/migrate.ts:70-82,105-107`). Its journal is demonstrably non-monotonic: `0008` has `when=1776822435828`, followed by `0009` at `1745280000000` (`packages/db/drizzle/meta/_journal.json:62-79`); the existing PostgreSQL runner documents that this causes skipping (`packages/db/src/migrate.ts:29-35`).
+
+**Failure mode:** an implementation can either reject a legitimate historical database after correcting 0009, or accept a reordered/duplicated ledger because no precise comparison rule exists. A count/hash-set implementation would fail to detect the condition that this contract explicitly calls unsafe; physical `id` order is not an adequate substitute after historical repair.
+
+**Required remediation:** freeze a versioned manifest algorithm before implementation: canonical record fields (at least journal index/tag, corrected logical order, migration content hash, and an explicit migration-manifest version), canonical byte serialization, SHA-256 input, and exact observed-ledger mapping. State whether physical ledger insertion order is normative; if not, compare hash-to-manifest tuples rather than timestamps. Add an idempotent migrator-only 0009 existing-database remediation/reconciliation procedure with backup/rollback evidence. Require clean, pre-0009, 0009-skipped, 0009-applied-late, duplicate, unknown, missing, corrupt-pair, and stale-replica cases. No manual ledger insertion is an acceptable production recovery path.
+
+### MEDIUM — advisory-lock namespace is collision-prone and lacks a fixed identifier contract
+
+The specified lock is `pg_try_advisory_lock(hashtext('mosaic-schema-migration-v1'))` (`KBN-101-DB-ROLE-SPLIT.md:34`). `hashtext` produces a 32-bit key. Session ownership/crash behavior is otherwise correctly stated (one session, same-session release, connection-close release), but an unrelated database user can accidentally collide or deliberately hold the key and force `DATABASE_MIGRATION_LOCKED`.
+
+**Failure mode:** avoidable migration denial of service in a shared PostgreSQL database. The current repository already uses separate `hashtext` advisory-lock names for migrate-tier, demonstrating the need for a documented namespace rather than a collision-prone implicit one.
+
+**Required remediation:** freeze a two-int advisory-lock namespace (fixed documented class/object values) or a documented 64-bit `hashtextextended` key with fixed seed; keep acquisition, migration, verification, and release on the single `max:1` migrator session. Add tests for concurrent migration, connection loss/crash release, readiness while the lock holder is active, and an unrelated lock-key non-interference case.
+
+### MEDIUM — identifier safety and `search_path` verification need executable constraints
+
+The contract rightly requires `pg_catalog, <mosaic_application_schema>` and rejects writable paths (`KBN-101-DB-ROLE-SPLIT.md:54,70-77`), but uses dynamic placeholders for database/schema and does not state how migration/bootstrap SQL will avoid identifier interpolation. Existing code has raw-SQL facilities (`packages/storage/src/migrate-tier.ts` uses `.unsafe`), so this is not merely theoretical.
+
+**Failure mode:** a future operator-configured database/schema value that reaches bootstrap or `SET search_path` through raw string construction can inject DDL, or a pooled connection can retain a mutable search path.
+
+**Required remediation:** require fixed allowlisted identifiers or server-side identifier quoting (`format('%I', ...)`) only; never interpolate URL/config values into SQL. Set and verify the trusted path per connection/session before any query (`SET LOCAL` inside transactions where applicable), forbid `public`/`$user` additions, and add injection-shaped identifier and pooled-connection reset negatives. Include this in KBN-101-00/01 tests.
+
+## Acceptance and threat traceability
+
+| Requirement / threat | Review result | Evidence or blocking finding |
+| --- | --- | --- |
+| K101-REQ-01 / AC-K101-01 split runtime/migration URLs | Partial | Role/DTO boundary is coherent; HIGH DDL-path finding requires all current commands to be closed. |
+| K101-REQ-02 / AC-K101-02 explicit migration/readiness | Blocked | HIGH ledger definition and HIGH DDL-bypass findings. |
+| K101-REQ-03 / AC-K101-03 least privilege, TLS, grants | Partial | Role model, default privileges, ledger read-only, TEMP/function checks are well specified (`KBN-101...:47-56,70-79`); HIGH TLS bootstrap and MEDIUM identifier constraints remain. |
+| K101-REQ-04 / AC-K101-04 immutable relations | Correctly deferred | KBN-101-09 after KBN-100 is the correct serial gate (`KBN-101...:58-66,115-118`); no synthetic-only certification claim found. |
+| K101-REQ-05 / AC-K101-05 N-1, secrets, rollback | Partial | No owner-runtime exception and rollback keeps migration URL out of Gateway (`:83-95`); deployable TLS and full command inventory are missing. |
+| K101-REQ-06 / AC-K101-07 KBN gates and DAG | Structurally sound | DAG is acyclic: 00→01/{03}; 02→06; 00/01/03→05; 00/04/05/06→07→08→KBN-100→09→KBN-105. KBN-100’s current branch contains docs-only baseline tracking, not schema implementation. |
+| T: runtime DDL / migration fallback | Blocked | HIGH finding 1. Current Gateway/storage, CLI, direct Drizzle scripts, and integration DDL require explicit closure. |
+| T: race/crash/readiness | Partial | Same-session nonblocking lock and replica-unready rules are present (`:34-38`); lock namespace remediation required. |
+| T: immutable evidence rewrite | Correctly staged | Explicit INSERT/SELECT-only matrix and RESTRICT retention are retained; proof is properly after table creation. |
+| T: secret leakage / TLS downgrade | Partial | Redaction and distinct Vault paths are specified (`:93-97`), but no server TLS/bootstrap implementation contract exists. |
+
+## Unresolved assumptions
+
+1. `standalone` and `federated` are the complete PostgreSQL production-like set (K101-A1).
+2. Each eligible deployment can execute a dedicated migration Job/one-shot phase (K101-A2).
+3. Vault path names are targets, not verified existing paths; deployment ownership remains to be established.
+4. PostgreSQL 17 is available for the selected membership and advisory-lock implementation.
+5. The required server-side TLS issuer/certificate lifecycle and Swarm/compose secret transport have not been decided; this is blocking, not a permissible implicit plaintext bootstrap.
+6. Historical databases containing the 0009 journal/ledger anomaly have no frozen reconciliation procedure.
+
+## Independent test and consistency evidence
+
+Read-only checks run in this review:
+
+| Check | Result |
+| --- | --- |
+| `git diff --check origin/main...da742ca2...` | PASS |
+| `pnpm exec prettier --check` on all seven changed docs | PASS |
+| `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` | PASS |
+| `docker compose -f docker-compose.yml config --quiet` (isolated test ports) | PASS |
+| `docker compose -f docker-compose.federated.yml --profile federated config --quiet` (isolated test ports) | PASS |
+| Static journal inspection | FAILS the required monotonic ordering premise: 0008 → 0009 `when` decreases; current runner documents skipping behavior. |
+| Static DDL-entrypoint inventory | Found direct Drizzle scripts, storage CLI shell-out, runtime extension/migration calls, fleet backlog migration, tier probe extension creation, and a direct-DLL federated integration test. |
+
+No live database, Vault, CI, deployment, issue, PR, or repository mutation was performed. The pass results validate documentation syntax/contract compilation and compose syntax only; they do **not** certify the proposed security behavior.
+
+## Conclusion
+
+Do not merge this frozen contract as implementation-ready until the HIGH findings are corrected and independently re-reviewed. The central role ownership/default-privilege design, immutable-table staging, and KBN-100/KBN-105 serial gating should be retained; they are not the reason for this REQUEST CHANGES verdict.

docs/reports/native-kanban-sot/ultron-final-go.md

@@ -0,0 +1,38 @@
+# #751 Native Kanban/SOT canonical publication — Ultron final gate
+
+**Verdict: GO** — zero BLOCKER/HIGH findings.
+
+## Scope / integrity
+
+- Reviewed `/home/hermes/agent-work/stack-kanban-canon` staged delta only: exactly 16 documentation/contract artifacts; no unstaged delta; `git diff --cached --check` passes.
+- This is a publication canon, not a runtime implementation. The explicit implementation hold prevents feature work until canon merge and prerequisite release (`docs/requirements/native-kanban-sot.md:8-9`; `docs/native-kanban-sot/TASKS.md:45-67`).
+
+## Acceptance mapping and findings
+
+| Requirement area                                             | Final evidence / result                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Sole PostgreSQL SOT, generated projections, outage proposals | Requirements D3/D4 and fixed invariants prohibit alternate writers and import (`docs/requirements/native-kanban-sot.md:22-23,32-44`). Health contract keeps public observation separate from branded transaction-local proof (`contracts/health-state.v1.ts:44-84`) and freezes 503/409/502/504 mappings (`:91-184`). Proposal table uses workspace-aware event FKs (`contracts/kanban-schema.v1.ts:847-908`); exact submission/acceptance transaction semantics are specified (`SHARED-CONTRACT.md:81-89`). PASS. |
+| Workspace tenancy, planning, assignments, evidence           | Workspace-composite task and proposal relations plus active-member rules are explicit (`SHARED-CONTRACT.md:40-48`; `kanban-schema.v1.ts:587-637,875-908`). Lease/checkpoint relations bind workspace/task/assignment/session/fence, with one active lease and bigint fencing (`:1062-1114`). PASS.                                                                                                                                                                                                                 |
+| Coordinator, gates, concurrency/recovery                     | Pure Coordinator has snapshot-only decision methods (`mechanical-coordinator.v1.ts:186-198`); persistence port owns locked ID validation and recovery (`:371-407`). Requirements forbid Coordinator scope/gate/certification/merge authority and Certifier merge authority (`requirements:39-40`; `MISSION-MANIFEST.md` authority table). Recovery validator rejects unknown fields, PITR/WAL/RPO/storage/high-assurance violations (`recovery-posture.v1.ts:193-369`). PASS.                                      |
+| Migration/N-1/API/task decomposition                         | N-1 expand/backfill/compatibility/switch/contract order and proposal DDL sequence are concrete (`SHARED-CONTRACT.md:69-115`). Frozen exact Gateway/DTO registry and non-overlapping lane ownership/prerequisites are present (`SHARED-CONTRACT.md:244-282`; `TASKS.md:45-67,81-259`). PASS.                                                                                                                                                                                                                        |
+| Documentation / seven owner decisions / evidence             | D1–D7 are all explicitly ratified (`requirements:20-26`); all 26 REQ sections contain acceptance criteria. Index/manifest/task graph link requirements, frozen contracts, ownership, and evidence. Relative-link audit passes. PASS.                                                                                                                                                                                                                                                                               |
+
+## Independent verification performed
+
+```text
+git diff --cached --check                                      PASS
+./node_modules/.bin/prettier --check <all publication paths>  PASS
+./node_modules/.bin/tsc --noEmit --strict <health/coordinator/recovery> PASS
+Python relative Markdown link audit                            PASS (0 errors)
+Python requirement acceptance audit                            PASS (26 requirements; 0 missing acceptance sections)
+Static staged scope/status check                               PASS (16 staged docs-only; no unstaged delta)
+```
+
+The full schema-contract strict type check cannot resolve `drizzle-orm` from this docs-only worktree; this is an environment dependency-resolution limitation, not a contract diagnostic. Independent external publication validation and final re-review record the strict all-four-contract check against the current Stack Drizzle toolchain as PASS.
+
+## Residual items
+
+- **LOW:** implementation must deliver the declared KBN-100/KBN-110/KBN-140 proposal-event-chain, tenant, failure-mapping, and SecReview evidence before P0/P1 release. This is a forward implementation obligation already frozen in the canon, not a publication defect.
+- **LOW:** selected infrastructure backup provider/recovery tier and migration/cutover thresholds remain owner-controlled implementation decisions, bounded by the normative recovery contract and change control.
+
+No source, staging, commit, provider, CI, or deployment state was mutated.

docs/reports/security/756-security-review.md

@@ -0,0 +1,37 @@
+# Security Review — Issue #756
+
+**Scope:** final current uncommitted Discord plugin, shared channel contract, gateway ingress, AgentService, and plugin registration delta  
+**Snapshot:** `plugins/discord/src/index.ts` SHA-256 `5ee6b6aa4e2ff349f137f76b918d02c1254e12066cb48b136048e57bef36fdb2`  
+**Verdict:** **APPROVE**
+
+## Final remediation verification
+
+| Area | Current evidence | Result |
+|---|---|---|
+| Attachment confidentiality and integrity | Ingress accepts bounded attachment metadata only when URL is HTTPS, query-free, fragment-free, and credential-free. Count, aggregate size, field length, MIME, and finite non-negative size validation apply before dispatch; `sizeBytes` is signed and retained. | Pass |
+| Trusted agent selection | Each binding names a required trusted `agentConfigId`; gateway resolves that config server-side and requires its configured name to equal the binding logical-agent ID. Client/provider input cannot select the agent for Discord ingress. | Pass |
+| Privileged operation routing | Gateway revalidates the binding and requires the signed conversation identity to match the configured logical agent before approve/stop actions. Paired admin identity and one-time approval checks remain enforced. | Pass |
+| Egress containment and delivery | Egress requires an aligned message/route, configured parent or exact observed thread target, and cleans response routes after completion, errors, typed-ingress failure, or bounded-map pressure. | Pass |
+| Side-effect limits | Per guild/authorized-parent/user rolling message and thread limits execute before thread creation or dispatch. | Pass |
+
+## Security controls reviewed
+
+- Default-deny guild, parent-channel, user, configured pairing, and role checks precede rate consumption and all side effects.
+- Gateway independently enforces Discord service authentication, HMAC integrity, allowlists, binding/role checks, attachment validation, and replay-ID rejection.
+- Thread authorization uses only the Discord thread parent; category parents cannot authorize ingress.
+- Agent-visible attachment references are explicitly labeled untrusted; binary content is not embedded. Persisted attachment name/URL values are redacted.
+- Egress uses deterministic nonces, bounded transient retry, typed terminal errors, and does not send to forged targets.
+- No secrets or message content were added to plugin logs.
+
+## Verification evidence
+
+| Command | Result |
+|---|---|
+| `pnpm --filter @mosaicstack/discord-plugin test` | PASS — 44 tests; v8 coverage: 92.18% statements/lines, 86.55% branches, 100% functions |
+| `pnpm --filter @mosaicstack/discord-plugin typecheck` | PASS |
+| `pnpm --filter @mosaicstack/types typecheck` | PASS |
+| `pnpm --filter @mosaicstack/gateway typecheck` | PASS |
+| `pnpm --filter @mosaicstack/gateway exec vitest run src/plugin/discord-ingress.security.spec.ts src/agent/__tests__/agent-service-ownership.test.ts` | PASS — 29 tests |
+| `git diff --check` | PASS |
+
+No unresolved critical, high, medium, or low security findings were identified in the reviewed final delta.

docs/requirements/native-kanban-sot.md

@@ -0,0 +1,368 @@
+# Native Kanban and Canonical Task SOT — Canonical Requirements
+
+**Status:** RATIFIED and independently approved for canonical publication under issue [#751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
+**Date:** 2026-07-14
+**Decision owner:** Jason
+**Publication owner:** web1 control plane (`mos-claude`; `mosaic-100` acting during Claude quota outage)
+**Implementation foundation:** current `mosaicstack/stack` main only
+**Implementation hold:** no feature implementation begins until this canon is squash-merged to `main` with terminal-green CI.
+
+## 1. Purpose
+
+Deliver Mosaic Stack's native project/task control plane and thin writable Kanban on one authoritative PostgreSQL model. This document formalizes the ratified source plan; it does not create a parallel design.
+
+Normative terms **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are binding as used here.
+
+## 2. Ratified decisions
+
+| #   | Ratified decision                          | Canonical result                                                                                                                                                                                                                                                                                       |
+| --- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| D1  | Foundation                                 | Extend current `mosaicstack/stack` main with its existing Drizzle/PostgreSQL, NestJS Gateway, Next.js, Better Auth, and Valkey/BullMQ conventions. No greenfield service and no Prisma revival.                                                                                                        |
+| D2  | Tenant boundary                            | `workspace_id` is the hard tenant boundary from the first migration. Teams are authorization groups inside a workspace, never tenant substitutes.                                                                                                                                                      |
+| D3  | Outage authority — Option A with amendment | PostgreSQL is the sole writable SOT and mutations fail closed whenever DB write-health cannot be proven. The amendment permits deployment-specific **recovery posture only**; it does not permit an alternate writer. Human outage notes are attributable post-recovery proposals, never shadow state. |
+| D4  | Generated files                            | `TASKS.md`, `mission.json`, and any file export are generated, read-only, non-authoritative, and never import sources. Generate on demand; commit only where repository review policy requires a snapshot.                                                                                             |
+| D5  | Status model                               | Task statuses are `backlog`, `ready`, `in_progress`, `blocked`, `in_review`, `done`, `cancelled`. Runtime readiness is orthogonal and computed.                                                                                                                                                        |
+| D6  | Coordinator approval                       | Hybrid: manual Project Sub-Orchestrator approval by default; automatic routing only under an explicit, approved, versioned low-risk policy.                                                                                                                                                            |
+| D7  | Initial migration scope                    | Project, mission, milestone, task, tags/archive, dependency, assignment, outage proposal, evidence/link, and orchestration state only. Calendar, email, GLPI cache, and personal-brain features remain out of scope.                                                                                   |
+
+## 3. Fixed invariants — every deployment
+
+These are not tier settings and cannot be weakened by deployment configuration.
+
+1. PostgreSQL is the **sole writable source of truth**.
+2. The implementation uses Drizzle on current stack main.
+3. Kanban and orchestration mutations **fail closed** unless DB write-health is positively proven `healthy`.
+4. No failed mutation is redirected to Markdown, JSON, browser storage, Valkey, queue payloads, scratchpads, or provider issues.
+5. `TASKS.md` and all file exports are generated, read-only, non-authoritative, and never parsed for import.
+6. Human notes created during an outage become attributable proposals only after recovery. They do not reserve work, change status, satisfy a gate, or establish ordering.
+7. Valkey is derived, expendable coordination infrastructure. PostgreSQL retains task truth, leases, fencing, audit, and the transactional outbox.
+8. The Mechanical Coordinator is non-LLM and deterministic. It may evaluate eligibility, dependencies, approval policy, leases, fencing, heartbeat, retry, expiry, and quarantine. It cannot invent scope, alter acceptance criteria, waive gates, certify, or merge.
+9. **Certifier** is the final independent quality-gate role. Certifier may pass, reject, or escalate with evidence; it has no merge authority.
+10. Every business and orchestration record is workspace-scoped; cross-workspace relationships are rejected.
+11. Every mutation is idempotent and expected-version checked where it changes an aggregate.
+12. Stale worker mutations are rejected by monotonically increasing fencing tokens.
+13. Audit events are append-only and attributable; authoritative state is reconstructable from PostgreSQL without Valkey or files.
+
+## 4. Configurable recovery posture only
+
+Deployment tiers configure durability and operational recovery targets. They never configure SOT authority, fail-open writes, or gate bypass.
+
+### 4.1 Tier defaults
+
+| Setting                     |                                    Lite |                                                      Standard |                                                          High-assurance |
+| --------------------------- | --------------------------------------: | ------------------------------------------------------------: | ----------------------------------------------------------------------: |
+| Target RPO                  |                                24 hours |                                                        1 hour |                                                          **15 minutes** |
+| Target RTO                  |                                24 hours |                                                       8 hours |                                                             **4 hours** |
+| Base backup cadence         |                                   Daily |                                                         Daily |                                                               **Daily** |
+| WAL archive cadence         |                                Disabled |                                              Every 15 minutes |                                                     **Every 5 minutes** |
+| PITR retention              |                       0 days / disabled |                                                       14 days |                                                             **35 days** |
+| Restore test frequency      |                               Quarterly |                                                     Quarterly |                                                             **Monthly** |
+| Break-glass drill frequency |                                Annually |                                                  Semiannually |                                                           **Quarterly** |
+| Off-cluster storage         | One encrypted off-cluster backup target | Encrypted off-cluster object storage, separate failure domain | **Encrypted off-cluster base backups and WAL, separate failure domain** |
+
+A deployment MAY override defaults only through the validated recovery-posture contract. An override MUST record actor, reason, effective time, and policy revision. A claimed RPO MUST be no smaller than the actual backup/WAL mechanism can support. Enabling PITR requires WAL archival and off-cluster storage.
+
+## 5. Functional requirements and acceptance criteria
+
+### REQ-SOT-001 — Sole writable PostgreSQL authority
+
+**Requirement:** All project, mission, milestone, task/tag/archive, dependency, assignment, execution/quarantine, lease, checkpoint, approval, outage proposal, event, link, artifact, and outbox mutations MUST commit through Gateway domain services into PostgreSQL.
+
+**Acceptance:**
+
+- Mutation journey tests show web, CLI, MCP, and agents invoke typed Gateway commands.
+- Static/process inventory finds no file, Valkey, browser, or provider issue writer acting as canonical state.
+- PostgreSQL state survives Valkey loss and reconstructs the same aggregate revisions.
+
+### REQ-SOT-002 — Fail-closed mutation health
+
+**Requirement:** A mutation MUST execute only while health state is `healthy`. `read-only-degraded` and `write-unavailable` MUST return the frozen deliberate-denial error contract and MUST NOT enqueue a hidden write.
+
+**Acceptance:**
+
+- Public health response is a discriminated union; contradictory state/proof combinations fail contract validation.
+- Mutation methods accept only a fresh internal PostgreSQL transaction-local write proof, never caller-asserted/public health state.
+- Negative tests reject expired proofs, policy-revision mismatch, Valkey-only liveness, and caller-forged `healthy`.
+- Fault tests force both degraded states and prove row counts, outbox, files, and Valkey remain unchanged.
+- Exact failure mapping proves authoritative 503 denial, retryable 502/504/timeout uncertainty, and 409 version conflict cannot cross-map.
+- Replaying the same idempotency key after recovery returns one canonical result.
+
+### REQ-SOT-003 — Generated projections
+
+**Requirement:** `TASKS.md`, `mission.json`, and other exports MUST contain a non-authoritative header, workspace/project IDs, generated time, and source revision. No production parser may mutate DB from an export.
+
+**Acceptance:**
+
+- Generated output matches the API snapshot revision.
+- Hand editing a projection fails CI validation or is overwritten by regeneration.
+- Repository search finds no import path from generated projections.
+
+### REQ-SOT-004 — Attributable outage proposals
+
+**Requirement:** Human outage notes MAY be captured outside the system but, after recovery, can enter Mosaic only through workspace-scoped `change_proposals` attributed to an authenticated active member. A proposal stores source-note digest, target aggregate/version, typed command/payload, idempotency, lifecycle, decision actor/reason/time, and audit links. It MUST NOT silently change canonical state.
+
+**Acceptance:**
+
+- `(workspace_id, submitted_audit_event_id)` and `(workspace_id, accepted_command_audit_event_id)` are composite foreign keys to `task_events(workspace_id, id)`; missing and foreign-workspace event IDs fail before commit.
+- Submission preallocates the proposal ID and atomically inserts `change_proposal.submitted` for that exact workspace/proposal with the new proposal referencing it.
+- Accept locks proposal and target, obtains fresh write proof, checks expected version, executes the normal typed command, and atomically links that command's event for the same workspace/target and proposal causation.
+- Negative tests reject missing submission events, foreign-workspace submission/acceptance events, and same-workspace events for an unrelated proposal, aggregate, target, or command.
+- Tests prove a pending/rejected proposal cannot claim/order work, satisfy a dependency/gate, or mutate any target directly.
+
+### REQ-TEN-001 — Workspace hard tenancy
+
+**Requirement:** Every canonical business/orchestration row MUST carry `workspace_id`. Workspace-aware constraints and authorization MUST prevent cross-tenant relationships and reads/writes.
+
+**Acceptance:**
+
+- API, repository, import, WebSocket, and Coordinator negative tests reject foreign-workspace IDs without existence oracles.
+- Project/task owners use exactly-one user/team references; assignment principals use exactly-one user/team/agent reference; agent/session targets are workspace-consistent.
+- User owners, principals, proposers, and decision actors require ACTIVE workspace membership in the authoritative transaction.
+- Dependency, project hierarchy, assignment, lease, checkpoint, approval-evidence, link, artifact, proposal target, and both proposal-audit-event composite relationships reject mixed workspaces.
+- Tenant context is derived from authenticated authority, never accepted blindly from request data.
+
+### REQ-ID-001 — Workspace identity and service scope
+
+**Requirement:** Users, teams, agents, and agent sessions MUST be bound to a workspace with explicit role/capability scope. Agents MUST NOT receive raw DB credentials.
+
+**Acceptance:**
+
+- Workspace membership and service-identity tests enforce command-family scope.
+- Revoked/disabled agents and ended sessions cannot claim, heartbeat, or submit.
+
+### REQ-PLAN-001 — Normalized planning hierarchy
+
+**Requirement:** Canonical planning entities are projects, milestones, missions, mission-milestone associations, and tasks. A task belongs to one required project and at most one mission/milestone/parent task.
+
+**Acceptance:**
+
+- CRUD tests preserve workspace, hierarchy, versions, and lifecycle constraints.
+- Mission membership does not duplicate task status.
+- Composite project-congruent constraints reject task→mission, task→milestone, task→parent, mission→milestone, and project→current-milestone mismatches.
+- Parent and association constraints reject cycles/orphans where applicable.
+
+### REQ-TASK-001 — Canonical task fields
+
+**Requirement:** Tasks MUST support title, description, structured acceptance criteria, canonical status, priority, fractional board rank, accountable owner, assigned specialist role, due/not-before dates, estimate, progress, explicit blocker, retry policy, normalized workspace tags, non-lifecycle archival (`archived_at/by/reason`), metadata, monotonic fencing counter, and optimistic version.
+
+**Acceptance:**
+
+- API and UI round-trip every field without silent loss.
+- Current `tasks.tags`, `assignee`, and `due_date` remain declared/preserved during N-1 and backfill to the canonical model without loss.
+- Archive hides work without changing its canonical lifecycle status and requires actor/reason/time.
+- Invalid status, rank, progress, date, owner, tag, archive, or retry data is rejected.
+- Concurrent expected-version updates produce a visible conflict.
+
+### REQ-TASK-002 — Fixed lifecycle and computed readiness
+
+**Requirement:** Human workflow status MUST use the seven ratified values. Dependency/schedule/policy/lease/retry conditions MUST be exposed as computed readiness, not hidden status rewrites.
+
+**Acceptance:**
+
+- A dependency becoming incomplete changes readiness but does not silently rewrite the Kanban column.
+- Readiness explanation identifies all active gates.
+- State-machine tests reject illegal transitions and require reasons for blocked/cancelled paths.
+
+### REQ-DEP-001 — Dependency DAG
+
+**Requirement:** Workspace-local directed dependencies MUST be unique and acyclic. A task is dependency-eligible only after every blocking predecessor is `done` and completion conditions pass.
+
+**Acceptance:**
+
+- `(workspace_id, predecessor_task_id, successor_task_id)` is unique independent of dependency type.
+- Cycle, duplicate, self-edge, and cross-workspace attempts fail before commit.
+- Property/concurrency tests prove all blocking predecessors are evaluated.
+- UI displays dependency and readiness errors accessibly.
+
+### REQ-ASN-001 — Assignment is not a lease
+
+**Requirement:** Assignment history and execution leases MUST be separate records. One persisted assignment identity freezes task version, exact target agent/session (or exactly-one non-agent principal), specialist role, expiry, state, policy revision, proposer, reason, and timestamps. Approval decisions relate to that assignment with workspace-aware constraints.
+
+**Acceptance:**
+
+- One assignment-state vocabulary is identical across schema, DTO, and engine.
+- Lease acquisition accepts IDs only, then reloads and locks assignment, approval, task, and target session to verify workspace, current task version, exact target, state, expiry, and policy revision.
+- Reassignment preserves history; assignment may exist without a lease; lease expiry does not erase ownership/evidence.
+
+### REQ-AUD-001 — Semantic audit and outbox
+
+**Requirement:** Mutating commands MUST append semantic `task_events` with actor, correlation, causation, idempotency key, and aggregate versions in the same transaction as state. Notifications MUST flow from a transactional outbox.
+
+**Acceptance:**
+
+- Atomicity tests prove state/event/outbox commit or roll back together.
+- Proposal submission and acceptance tests prove their workspace-bound event links identify the exact submission and executed normal command, not merely an existing event UUID.
+- Duplicate idempotency keys return the prior result without duplicate events.
+- `task_events`, checkpoints, immutable artifacts, and evidence joins are INSERT/SELECT-only for application roles; parent hard deletes are RESTRICTed.
+- Normal lifecycle uses archive/cancel, never hard delete; retention purge requires audited break-glass authority and evidence.
+- Valkey outage leaves outbox pending and later replayable.
+
+### REQ-API-001 — Typed Gateway command boundary
+
+**Requirement:** Gateway MUST expose workspace-safe project/task/dependency/assignment/link/artifact/change-proposal queries and explicit lifecycle commands. Generic patching MUST NOT bypass claim, heartbeat, review, certify, proposal acceptance, or completion invariants.
+
+**Acceptance:**
+
+- KBN-105 freezes exact route, request, success, denial, conflict, and transport-normalization DTOs before CLI/web implementation.
+- DTO validation, authorization, contract, and integration tests cover each command.
+- Exact MCP-owned Gateway files are coder3-owned; coder4 consumes only frozen Gateway contracts.
+- Endpoint registry aligns web, CLI, MCP, and generated client paths.
+- Direct SQL and raw Valkey writes are absent from clients.
+
+### REQ-UI-001 — Writable thin Kanban/List MVP
+
+**Requirement:** Existing Tasks and Projects surfaces MUST become a real-data writable MVP with one shared query contract.
+
+**Acceptance:**
+
+- Users can create/edit/cancel/archive tasks, open task detail, and move cards within/across columns.
+- Server validates transition and persists fractional board rank.
+- Refresh, reconnect, CLI, MCP, and generated projection show the same revision.
+
+### REQ-UI-002 — Tenant and work context
+
+**Requirement:** UI MUST show workspace context and support filters for project, mission, milestone, status, priority, owner/specialist, due state, and tags.
+
+**Acceptance:**
+
+- Context is visible on every mutation surface.
+- Filter tests cannot expose foreign-workspace data.
+- Empty/loading/error states are explicit.
+
+### REQ-UI-003 — Dependency, ownership, lease, and audit visibility
+
+**Requirement:** Task detail MUST separate accountable owner, specialist assignment, active session/lease expiry, dependencies/readiness, acceptance criteria, blocker, external links, and audit timeline.
+
+**Acceptance:**
+
+- Each concept renders from its canonical endpoint.
+- A lease is never displayed as ownership or completion.
+- Conflict and stale-reconnect states require refresh rather than silent overwrite.
+
+### REQ-UI-004 — Accessible interaction
+
+**Requirement:** Kanban MUST support keyboard-accessible moves, non-drag alternatives, responsive layout, and semantic status/error announcements.
+
+**Acceptance:**
+
+- Keyboard journey performs every card transition available by drag.
+- Automated accessibility checks and manual responsive checks pass.
+
+### REQ-COORD-001 — Non-LLM Mechanical Coordinator
+
+**Requirement:** Coordinator decisions MUST be deterministic from structured data and versioned policy. It MUST NOT invoke an LLM to interpret scope or acceptance criteria.
+
+**Acceptance:**
+
+- Pure decision engine receives complete immutable snapshots and performs no ID loading, SQL, Gateway, Valkey, or recovery I/O.
+- Persistence/service adapter owns ID loading, transaction-local write proof, locking, persistence, and `recoverFromPostgres`.
+- Same snapshot and policy revision produce the same eligibility/order explanation.
+- Dependency, schedule, durable retry/quarantine, approval, role, and capacity inputs are auditable.
+- Code/config inspection finds no model/provider dependency in the scheduling engine.
+
+### REQ-COORD-002 — Eligibility and approval routing
+
+**Requirement:** Only `ready` tasks under active project/mission, passed dependencies/schedule/retry/release policy, and without active lease may be proposed. Manual approval is default; auto-route requires an explicit approved policy revision.
+
+**Acceptance:**
+
+- Unapproved or gated tasks are never leased.
+- Every persisted assignment proposal includes task version, exact target agent/session, expiry, state, deterministic reasons, and policy revision.
+- Approval is relationally bound to the assignment identity and cannot be supplied as a forgeable proof-by-value DTO.
+- Override/reject/reassign requires an attributable reason.
+
+### REQ-COORD-003 — Atomic lease, heartbeat, fencing, and recovery
+
+**Requirement:** Lease acquisition MUST be atomic in PostgreSQL, permit at most one active lease per task, atomically increment the durable per-task fencing counter under task lock, use bigint-safe tokens, require timely acknowledgement/heartbeat, and reject stale workers. Lease and checkpoint relations MUST bind the exact workspace+task+assignment/session+fence.
+
+**Acceptance:**
+
+- Concurrent claim tests yield one winner and strictly increasing fencing tokens.
+- Lower/expired tokens and mismatched same-workspace task/assignment/lease/checkpoint IDs fail.
+- Token values round-trip as bigint/decimal strings without JavaScript precision loss.
+- Coordinator restart reconstructs lease/retry/quarantine state from PostgreSQL alone.
+
+### REQ-COORD-004 — Retry and quarantine
+
+**Requirement:** Missing acknowledgement, agent loss, or execution failure MUST produce a deterministic release, bounded backoff retry, or quarantine outcome according to retry policy. Ambiguous/non-idempotent work requires Sub-Orchestrator action.
+
+**Acceptance:**
+
+- Durable execution state records disposition, attempt/max, next eligibility, terminal reason, actor/policy, timestamps, and version.
+- Retry budget/backoff are bounded and tested.
+- Exhausted or non-idempotent failures quarantine with workspace-scoped artifact evidence.
+- One specialist-role vocabulary is enforced across schema, sessions, assignments, DTOs, and engine.
+- No task loops indefinitely or silently returns to ready.
+
+### REQ-GATE-001 — Role and authority chain
+
+**Requirement:** Canonical flow is User → Interaction → Portfolio Orchestrator → Project Sub-Orchestrator → Gateway → domain services → Mechanical Coordinator → specialists → Certifier.
+
+**Acceptance:**
+
+- Role bindings and approvals are queryable and audited.
+- Coordinator cannot create scope or waive gates.
+- Certifier cannot merge or close provider artifacts.
+
+### REQ-GATE-002 — Independent review and certification
+
+**Requirement:** Author and reviewer MUST differ. Auth, security, tenant, secrets, and data-integrity surfaces MUST receive mandatory SecReview. Certifier is the final quality gate after remediation.
+
+**Acceptance:**
+
+- Gate tests reject author self-review and missing required SecReview.
+- Certifier receives complete traceability/evidence and returns pass/reject/escalate.
+- A Certifier pass does not grant merge authority.
+
+### REQ-REC-001 — Recovery posture validation
+
+**Requirement:** A deployment MUST select a validated Lite, Standard, or High-assurance posture and MAY override only recovery knobs.
+
+**Acceptance:**
+
+- Runtime invokes normative `validateRecoveryPostureV1`, not shape-only JSON Schema validation.
+- Validator rejects PITR/WAL mismatch, impossible RPO, unknown fields, non-encrypted/non-separated storage, and weakened High-assurance values.
+- A bounded recovery/infra slice owns parser wiring, override audit, mechanism verification, restore test, and break-glass evidence.
+- High-assurance defaults equal RPO 15m/RTO 4h, encrypted off-cluster WAL every 5m, 35d PITR, daily base backup, monthly restore test, and quarterly break-glass.
+
+### REQ-MIG-001 — One-way shadow migration
+
+**Requirement:** Migration from jarvis-brain/Vikunja MUST use inventory, immutable source snapshots/checksums, one-way shadow import, read reconciliation, write freeze, final delta, cutover, and read-only stabilization. Dual writes are forbidden.
+
+**Acceptance:**
+
+- P0 publishes the current `origin/main` field-by-field expand/backfill/compatibility/switch/contract map before any schema lane starts.
+- Legacy columns remain in the unified Drizzle declaration for the entire expand/N-1 window.
+- Dry-run/apply/verify modes are idempotent and workspace-safe.
+- Import lineage preserves source system/key/file/checksum/batch and rejected-record reports.
+- Empty DB, production-shape, partial-resume, downgrade/rollback, status-shadow, workspace-backfill, and `mission_tasks.status` retirement tests pass.
+- Shadow records cannot auto-dispatch.
+
+### REQ-MIG-002 — Cutover and rollback safety
+
+**Requirement:** Cutover MUST disable legacy writers and switch all clients to Gateway. Before first DB mutation rollback may switch authority back; afterward rollback requires freeze, DB-delta export/reconciliation, and owner decision.
+
+**Acceptance:**
+
+- Process inventory proves no active jarvis-brain/Vikunja project/task writer.
+- Cutover rehearsal meets signed reconciliation thresholds.
+- No reverse and forward sync run concurrently.
+
+## 6. Explicit non-goals
+
+The P0–P3 canon does not authorize:
+
+- replacing Gitea issue/PR storage;
+- calendar, email, GLPI cache, CRM, billing, time tracking, or personal-brain migration;
+- arbitrary custom workflows/statuses/fields;
+- a writable offline/file/Valkey/browser fallback;
+- direct client database access;
+- LLM scheduling or autonomous scope invention;
+- Coordinator gate waiver, certification, merge, release, or provider issue closure;
+- Certifier merge authority;
+- full mission designer, portfolio analytics, critical-path UX, or advanced board customization in the thin MVP;
+- P4/P5 features unless separately released.
+
+## 7. Global release evidence
+
+P0–P3 may close only when requirements traceability maps every requirement above to automated and situational evidence, including cross-workspace denials, DB/Valkey fault injection, concurrent leases, stale fencing, generated-file immutability, UI conflict/reconnect behavior, migration reconciliation, independent review, mandatory SecReview, and final Certifier evidence.

docs/scratchpads/751-native-kanban-canon.md

@@ -0,0 +1,152 @@
+# Issue #751 — Native Kanban/SOT canonical publication
+
+## Objective
+
+Publish the owner-ratified P0–P3 requirements, mission manifest, task decomposition, and frozen shared contracts before feature implementation.
+
+## Authority and decisions
+
+- Owner: Jason
+- Plan owner/orchestrator: web1 control plane; takeover by mosaic-100 during Claude quota outage
+- Tracking: Mosaic Stack issue #751
+- Foundation: current Stack main + Drizzle/PostgreSQL
+- Fixed invariants: PostgreSQL sole writable SOT; writes fail closed; exports never import; outage notes become attributable proposals; mechanical Coordinator has no scope/gate/certify/merge authority; Certifier has no merge authority.
+- Recovery posture only is configurable through Lite, Standard, and High-assurance profiles.
+
+## Execution log
+
+- 2026-07-14: Existing planner-sol canon remediation reviewed from staging. KCR-001–016 claimed resolved; static checks passed.
+- 2026-07-14: Independent GPT/Terra re-review dispatched to rev1.
+- 2026-07-14: Re-review returned NO-GO: proposal audit-event IDs were not workspace-bound, leaving attribution forgeable; formatter evidence was not reproducible. Focused remediation round 2 routed to planner-sol.
+- 2026-07-14: Remediation bound proposal audit links to `task_events(workspace_id,id)`, froze same-transaction semantic validation and negative tests, and made formatter/type/static checks reproducible.
+- 2026-07-14: Independent rev1 re-review returned GO with KCR-001–016 closed and no new blocker. Canon copied into the issue #751 publication worktree; feature implementation remains held until merge.
+- 2026-07-14: Independent publication validation returned FAIL on formatting/trailing whitespace, stale staging wording, ignored review evidence, and missing worktree dependencies. Bounded publication remediation routed to planner-sol; no runtime source change authorized.
+- 2026-07-14: Publication remediation installed locked dependencies outside the repository cache, fixed formatting and wording, and preserved docs-only scope. Independent gaterun revalidation returned PASS across staged scope, formatting, lint, typecheck, strict contract compile, links, rollups, review artifacts, and fixed invariants.
+- 2026-07-14: Ultron final gate returned GO with zero BLOCKER/HIGH findings; residual LOW items remain explicit implementation obligations.
+- 2026-07-14: First commit attempt was correctly blocked by the lint-staged hook because docs contract `.ts` files were outside TypeScript project-service scope. Added a strict no-emit workstream `tsconfig.json` with exact Drizzle declaration paths; targeted contract TSC, contract ESLint, format, full lint/typecheck, strictness, and docs-only scope independently passed.
+
+## Verification evidence
+
+- Initial review: `docs/reports/native-kanban-sot/canon-initial-review-no-go.md`
+- Final GO: `docs/reports/native-kanban-sot/canon-final-rereview-go.md`
+- Ultron GO: `docs/reports/native-kanban-sot/ultron-final-go.md`
+- Pending: PR gates, squash merge, terminal-green CI, and issue closure.
+
+## Publication remediation session — planner-sol
+
+**Assignment:** Remediate only issue #751 publication blockers from `/home/hermes/agent-work/reviews/751-kanban-canon-publication-validation.md`; no source, package, lock, provider, CI, build, deploy, commit, or push action.
+
+**Plan:**
+
+1. Install the locked pnpm dependencies without modifying package metadata.
+2. Replace only stale publication/staging wording while retaining the canon-merge and KBN prerequisite implementation hold.
+3. Format all changed candidate Markdown and contract TypeScript; remove trailing whitespace.
+4. Run worktree `format:check`, `lint`, `typecheck`, strict no-emit contract compilation, tracked/untracked whitespace checks, and static invariants.
+5. Verify package/lock/source paths are unchanged and append exact evidence here.
+
+**Budget:** No explicit token cap; bounded docs-only remediation, no exploratory/runtime work.
+**TDD:** Not applicable—documentation/contract-publication formatting and wording only; strict/static validation is the primary gate.
+
+## Publication remediation results
+
+### Changes
+
+- `docs/native-kanban-sot/INDEX.md`: replaced staging/pending-GO wording with current publication and independent-GO wording; retained the merge hold and dependency-ordered KBN prerequisite hold.
+- `docs/native-kanban-sot/TASKS.md`: replaced “Mos using this staging set” with “Mos / publication control plane”; made the post-merge KBN prerequisite hold explicit.
+- Formatted all changed candidate Markdown and four contract TypeScript files with current-worktree Prettier 3.8.1.
+- Removed trailing whitespace from candidate Markdown, including both linked review reports.
+- Preserved both review reports and their links; they remain ignored by `.gitignore:11` for coordinator force-tracking.
+
+### Dependency installation
+
+The first target-worktree install attempt used the environment's default root-owned pnpm store and failed without changing package metadata:
+
+```text
+cd /home/hermes/agent-work/stack-kanban-canon && pnpm install --frozen-lockfile
+EACCES: permission denied, open '/root/.local/share/pnpm/store/v10/server/server.json'
+```
+
+Successful locked install using an authorized cache outside the repository:
+
+```bash
+cd /home/hermes/agent-work/stack-kanban-canon
+pnpm install --frozen-lockfile --store-dir /home/hermes/agent-work/pnpm-store
+```
+
+Result: PASS, 1,240 packages installed; lockfile resolution skipped as up to date. `node_modules` remains ignored. Tool versions: pnpm 10.6.2, Prettier 3.8.1, TypeScript 5.9.3, Drizzle ORM 0.45.1, Turbo 2.8.16.
+
+### Exact quality-gate results
+
+```text
+pnpm format:check
+PASS — All matched files use Prettier code style.
+
+pnpm lint
+PASS — 23 successful lint tasks.
+
+pnpm typecheck
+PASS — 42 successful tasks. Turbo invoked configured dependency build prerequisites as part of the repository's exact typecheck graph; no standalone build command was run.
+```
+
+Candidate formatting commands:
+
+```bash
+pnpm exec prettier --write <3 tracked rollups + 9 native-kanban artifacts + requirements + scratchpad>
+pnpm exec prettier --check <same files>
+pnpm exec prettier --ignore-path /dev/null --write \
+  docs/reports/native-kanban-sot/canon-initial-review-no-go.md \
+  docs/reports/native-kanban-sot/canon-final-rereview-go.md
+pnpm exec prettier --ignore-path /dev/null --check \
+  docs/reports/native-kanban-sot/canon-initial-review-no-go.md \
+  docs/reports/native-kanban-sot/canon-final-rereview-go.md
+```
+
+Result: PASS. The explicit `/dev/null` ignore path is required because `docs/reports/` is intentionally ignored pending coordinator force-tracking.
+
+Tracked and untracked whitespace checks:
+
+```text
+git diff --check
+PASS
+
+git diff --no-index --check /dev/null <each untracked/ignored candidate>
+PASS for all candidates
+```
+
+Strict contract compilation initially could not resolve pnpm-isolated `drizzle-orm` from the external docs directory. A temporary, removed dependency-context symlink made current-worktree resolution explicit:
+
+```bash
+LINK=docs/native-kanban-sot/node_modules
+ln -s ../../packages/db/node_modules "$LINK"
+trap 'unlink "$LINK"' EXIT
+pnpm exec tsc \
+  --noEmit \
+  --strict \
+  --skipLibCheck \
+  --target ES2022 \
+  --module NodeNext \
+  --moduleResolution NodeNext \
+  docs/native-kanban-sot/contracts/*.ts
+```
+
+Result: `strict-contract-noemit=PASS`; temporary link removed.
+
+Static result:
+
+```text
+proposal-audit-links=PASS
+kcr-invariant-regression=PASS
+publication-wording=PASS
+vocabulary-alignment=PASS
+```
+
+### Scope-integrity evidence
+
+Baseline and final hashes are identical:
+
+```text
+package.json   93a50eaefc7a0446a56234e427df03f6a2256f8da17c0bede17c22206928c8c0
+pnpm-lock.yaml 8b6448d51ac7797c8f782af52a080c0e38ab8bf364f32624f94e636bf5743229
+```
+
+`tracked-package-lock-source-unchanged=PASS`: every tracked/untracked nonignored change remains under `docs/`; no package, lock, application source, plugin source, configuration, CI trigger, standalone build/deploy, container, provider, commit, or push action occurred.

docs/scratchpads/753-kbn010-threat-gate.md

@@ -0,0 +1,101 @@
+# Issue #753 — KBN-010 threat, authorization, and constraint-impact gate
+
+## Objective
+
+Complete the mandatory threat/auth/constraint-impact analysis that gates KBN-100 schema implementation.
+
+## Scope
+
+- In: threat matrix, frozen-control mapping, schema/API/test impact inventory, security evidence plan.
+- Out: runtime, schema, migration, API, dependency, CI, deployment, and secret changes.
+- Canonical requirements: `docs/requirements/native-kanban-sot.md`.
+- Frozen contract: `docs/native-kanban-sot/SHARED-CONTRACT.md` and `contracts/*.v1.ts`.
+- Tracking: Mosaic Stack issue #753.
+
+## Plan
+
+1. Independently inspect current-main implementation and frozen canon.
+2. Enumerate tenant, identity, health-proof, approval, fencing, proposal, audit, token, and outage threats.
+3. Map every threat to required constraints, command behavior, negative tests, and owning future slice.
+4. Surface any unresolved schema impact as a blocker; do not silently amend the frozen contract.
+5. Run documentation/static validation and submit for independent SecReview.
+
+## Execution log
+
+- 2026-07-14: KBN-000 completed through PR #752 and post-merge pipeline #1798.
+- 2026-07-14: KBN-010 issue #753 created; task marked in progress; fresh GPT worker pending dispatch.
+
+## Verification evidence
+
+Pending worker validation, independent SecReview, Ultron gate, PR merge, post-merge CI, and issue closure.
+
+## 2026-07-14 worker analysis checkpoint
+
+- Inspected issue #753, canonical requirements, all frozen v1 contracts, and actual `origin/main` at `49e8a54` across DB schema, Better Auth scope, project/task/mission/team repositories/controllers, fleet backlog, and `TASKS.md` parsing/writing.
+- Confirmed the worker branch has no source/runtime/schema delta from `origin/main`; orchestrator-owned `.mosaic` state remains dirty and untouched.
+- Authored the threat, authorization, constraint-impact, negative-test, and requirements-traceability analysis in `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md`.
+- Gate decision: **BLOCKED** by `KBN010-SI-001`. `missionsV1` lacks a unique candidate key on `(workspace_id, id)`, while `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk` both reference that exact pair. PostgreSQL cannot create the frozen composite foreign keys as declared.
+- Decision: do not select or apply a schema fix. Contract authority must version either a `(workspace_id, id)` mission candidate key or project-congruent child keys, then obtain independent re-review before KBN-100.
+- Additional risks are controlled by frozen transaction/API behavior but require the exact future negative tests cataloged in the deliverable, especially active membership, service-token revocation, same-workspace semantic evidence checks, no-oracle behavior, and serialized parent/DAG cycle checks.
+- OpenBrain startup recall was attempted but unavailable because `/home/hermes/.config/mosaic/credentials.json` is absent; no project state was written to an alternate memory silo.
+- TDD: not applicable; this slice changes documentation/test-plan analysis only and implements no runtime behavior.
+
+## Validation log
+
+- `pnpm exec prettier --check docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md docs/scratchpads/753-kbn010-threat-gate.md` — PASS.
+- Changed-doc link validator — PASS (`relative_links=0`, one external issue link); `curl -fsSIL https://git.mosaicstack.dev/mosaicstack/stack/issues/753` — PASS.
+- The first inline link-validator invocation had a Python f-string syntax error; corrected once and rerun successfully without changing the deliverable.
+- `pnpm format:check` — PASS.
+- `pnpm lint` — PASS (23 tasks successful).
+- `pnpm typecheck` — PASS (42 tasks successful).
+- `pnpm exec tsc -p docs/native-kanban-sot/tsconfig.json --noEmit` — PASS.
+- Scoped diff review — PASS: authored delta is limited to the exclusive deliverable and this scratchpad; no runtime/schema/config/dependency/CI/deployment file is changed, and `docs/native-kanban-sot/TASKS.md` has no worker worktree delta from tracking commit `9b55de0`.
+- Independent SecReview remains pending and cannot return PASS until contract authority resolves `KBN010-SI-001`.
+- Final formatting/diff/test-ID completeness review — PASS (all catalog prefixes contiguous with no duplicate IDs).
+- Remaining: scoped commit, queue guard, and push.
+
+## 2026-07-14 KBN010-SI-001 contract-authority amendment
+
+- Authority: `web1:mosaic-100` directed the minimal rc.4 amendment under issue #753: add a non-partial unique candidate key on `missions(workspace_id, id)` while retaining global `missions.id` uniqueness and the project-congruent `(workspace_id, project_id, id)` key.
+- Rationale: artifacts and approval decisions are polymorphic exactly-one-target records and do not consistently carry `project_id`; widening both children would broaden frozen v1 semantics without improving tenant safety.
+- Plan: amend only the frozen schema contract and shared contract, freeze exact DDL ordering and future migration negatives, run scoped/full validation and independent review, then commit and push without opening/merging a PR or closing #753.
+- TDD: not applicable because this is a design-contract amendment with no runtime schema or migration implementation; rc.4 freezes future executable empty/prod/N-1/rollback/foreign-workspace and duplicate-key-feasibility tests.
+- Budget: no explicit cap supplied; use a 20K-equivalent soft working cap and one bounded worker lane.
+- Read-only #757 boundary: PR #757 adds separate logical-agent connector lease/CAS fencing (`logical_agent_connector_leases.lease_epoch`) in runtime schema and connector contracts. SI-001 changes only the frozen mission candidate key; it does not consume, alter, or reinterpret connector fencing, task fencing, lease authority, or #757 ownership.
+
+### Amendment verification evidence
+
+- Frozen schema: added exactly one non-partial `missions_workspace_id_uidx` on `(workspace_id, id)`; retained the global `id` primary key and `missions_workspace_project_id_uidx` on `(workspace_id, project_id, id)`.
+- FK reconciliation: targeted static checks prove the candidate key precedes both `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk`; each continues to reference exact ordered columns `(workspace_id, mission_id)` → `missions(workspace_id, id)` with RESTRICT deletion.
+- Shared contract: candidate version is `1.0.0-rc.4`; authority, rationale, exact effect/non-effect, candidate-before-FK DDL order, duplicate feasibility, empty/prod/N-1/rollback/foreign-workspace future tests, and unchanged KCR/SOT/tenant/proposal/fencing/no-cascade invariants are explicit.
+- Changed-file Prettier, contract ESLint, `pnpm exec tsc -p docs/native-kanban-sot/tsconfig.json`, and targeted SI-001 static checks — PASS.
+- Full `pnpm format:check && pnpm lint && pnpm typecheck` — PASS (23 lint tasks and 42 typecheck/build tasks).
+- Independent Codex security review — PASS, zero critical/high/medium/low findings; tenant isolation is preserved.
+- Independent Codex code review confirmed the candidate key repairs both FK targets and reported no blocker on the authorized delta. Its initial request to rewrite the historical KBN-010 verdict conflicts with the exclusive scope and was resolved by documenting the immutable-evidence boundary in rc.4; its remaining finding concerns pre-existing live `.mosaic` session files, which are untouched and excluded from this commit.
+- Scoped diff: only the two frozen contract files and this append-only scratchpad amendment are staged for delivery; no runtime schema, migration, task plan, gate verdict, provider artifact, or #757-owned file is included.
+
+## 2026-07-14 final rc.4 KBN-010 disposition
+
+- Control-plane direction authorized final disposition edits only to `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` and this append-only scratchpad; contract author `web1:kbn-contract` remained idle and undisturbed.
+- Exact reviewed contract object: commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`, tree `7ebab8fa530a7180036928cea9527f808548aa14`.
+- Corroborating review identities: full-index SHA-256 `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`; stable patch-id `058cf98026fcd1043703c866aee047c8bb144740`. A command-rendered patch digest varied by Git rendering command/options and is non-authoritative; commit+tree+exact file content are canonical.
+- Independent Homelab non-author schema/security review verdict: **APPROVE**. It confirmed the rc.4 `missions_workspace_id_uidx(workspace_id,id)` repairs both dependent FKs while retaining the global PK and project-congruent key; tenant, polymorphic exactly-one-target, RESTRICT/no-cascade, N-1/rollback semantics remain valid.
+- Read-only #757 cross-check: no shared table, index, FK, identity, fence, or authority collision with connector lease/CAS fencing.
+- Final KBN-010 gate decision: **PASS / GO** at rc.4 with `UNRESOLVED SCHEMA IMPACTS` equal to exact `none`. Historical SI-001 detection remains in the gate document as evidence that rc.3 was invalid.
+- No runtime schema/migration/API/config/dependency/CI/deployment implementation is claimed. KBN-100 must still implement candidate-before-dependent-FK ordering, duplicate feasibility, empty/prod/N-1/rollback evidence, exact FK reconciliation, and separate artifact/approval foreign-workspace negatives (N100-45..50).
+- TDD remains not applicable because this continuation changes only documentation/evidence disposition and no runtime behavior.
+- Remaining orchestrator-owned sequence: worker validation/commit/push → PR open/update → Ultron review → squash merge → terminal-green post-main CI → close #753 → release KBN-100. KBN-100 is not released earlier.
+
+### Final worker validation
+
+- Changed-doc Prettier and link checks — PASS; issue #753 external link returned successfully.
+- Static future-test catalog check — PASS: all prefixes are individually enumerated, contiguous, and duplicate-free; N100 now spans N100-01..50.
+- rc.4 disposition assertions — PASS: gate status PASS/GO, frozen target rc.4, exact `none` unresolved section, independent APPROVE, review identities, and N100-50 are present.
+- Review identity reproduction — PASS: commit tree `7ebab8fa530a7180036928cea9527f808548aa14`, full-index SHA-256 `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`, and stable patch-id `058cf98026fcd1043703c866aee047c8bb144740` match.
+- rc.4 frozen-contract static check — PASS: the candidate key is unique in the declaration and precedes both dependent FKs; frozen contract files remain byte-identical to commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`.
+- `pnpm exec tsc -p docs/native-kanban-sot/tsconfig.json --noEmit` — PASS.
+- `pnpm format:check` — PASS.
+- `pnpm lint` — PASS (23 tasks successful).
+- `pnpm typecheck` — PASS (42 tasks successful).
+- Scoped diff — PASS: only the gate document and this scratchpad are authored changes; contracts, TASKS, requirements, runtime/schema/migration/config/dependency/CI/deployment and #757-owned files are unchanged. Live `.mosaic` session state remains untouched and excluded.
+- Remaining worker steps: final formatting/scoped staging, commit `docs(#753): clear KBN-010 schema gate`, queue guard, push, and control-plane notification.

docs/scratchpads/755-mos-logical-identity-fencing.md

@@ -0,0 +1,148 @@
+# Issue #755 — Logical Mos identity and connector lease fencing
+
+- Task: `MOS-PORT-M1-001`
+- Branch: `feat/mos-logical-identity-fencing`
+- Base: `origin/main`
+- Started: 2026-07-14
+- Working budget: 38K tokens (task ledger estimate); one implementation lane, bounded to M1.
+
+## Objective
+
+Implement the first runtime-portability security boundary: normalized logical-agent identity plus a PostgreSQL-durable exclusive connector lease and server-validated fencing grants.
+
+## Scope
+
+- Normalized identity contract independent of harness/provider-native session IDs.
+- DB migration/schema/repository for one lease per tenant/logical-agent/binding.
+- CAS acquire/takeover, monotonic epoch, TTL, heartbeat, release, expiry handling.
+- Server-derived grants bound to tenant, logical agent, binding, connector, scopes, expiry, and lease epoch.
+- Reject and credential-safely audit stale, expired, forged, unauthorized, cross-tenant, and cross-binding grants before adapter side effects.
+- Runtime adapter boundary consumes normalized lease context.
+- Unit, migration, close/reopen, concurrency, abuse, and gateway integration tests.
+- Required developer/operations documentation for schema and security behavior.
+
+## Explicit exclusions
+
+No checkpoint/handoff payloads, exactly-once journal/receipts, concrete Claude/Pi/Codex harness adapter, channel cutover, or full cross-harness failover E2E.
+
+## Reconciliation baseline
+
+- Prospective remediation handoff: `web1:coder1`; PR [#757](https://git.mosaicstack.dev/mosaicstack/stack/pulls/757), issue [#755](https://git.mosaicstack.dev/mosaicstack/stack/issues/755).
+- Before rebase: `dff8ce4f79ef90370c29d925002118a708010091`; required base: `origin/main` at `2e2280070ae67288be45f41743cf67052a8ca5a6`; original branch base: `d0771835542deab048ad8e79f271e3abdb6151f7`.
+- Provider metadata: #757 is open, targets `main`, head is `feat/mos-logical-identity-fencing`, prior CI is green, and the provider reports it is not mergeable because of conflicts.
+- Affected delivery paths: `apps/gateway/src/agent/agent.module.ts`; connector-lease gateway repository/service and three focused tests; `packages/agent/src/connector-lease.ts` plus test/export; `packages/types/src/agent/connector-lease.dto.ts` plus test/export; `packages/db/src/schema.ts`, migration `0016_salty_morlocks.sql`, Drizzle snapshot/journal; `docs/PRD.md`, `docs/SITEMAP.md`, MOS architecture/operations pages, this scratchpad, and `docs/tess/TASKS.md`.
+- Read-only merge-tree inspection found only `docs/PRD.md` and `docs/SITEMAP.md` conflicts. Current-main #756 channel contracts, #758 roster-v2 structural compiler, and Native Kanban SOT use distinct contract domains; no substantive architecture collision was identified before mechanical reconciliation.
+- Reconciliation constraints: retain all current-main #752/#756/#758/KBN content; add only nonduplicative #755 references; do not alter semantics or conflate connector leases/grants with Kanban task leases/fences, local Fleet leases, auth sessions, ResetSession generations, or federation grants.
+
+## Plan (TDD RED → GREEN → REFACTOR)
+
+1. Map existing contracts, DB/migration conventions, gateway authorization/audit boundaries, and test infrastructure.
+2. Add failing contract/repository/concurrency/restart/abuse/gateway tests and capture RED evidence.
+3. Implement the smallest normalized contracts, schema/migration/repository, grant validator, audit sink, and gateway service/adapter boundary needed to pass.
+4. Refactor for clear invariants and credential-safe observability; rerun focused suites.
+5. Run package/repo typecheck, lint, format, and appropriate tests.
+6. Run independent code + security review, remediate, and re-review.
+7. Inspect the final diff for security/scope drift; commit; queue guard; push; open PR with `Refs #755` and exact verification; stop without merge/issue closure.
+
+## Constraints and safety notes
+
+- `docs/tess/TASKS.md` is orchestrator-only and will not be edited.
+- Existing dirty `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are launcher/orchestrator state and will not be staged or altered intentionally.
+- No client-supplied identity may confer authority.
+- No credential, token, or raw grant material may be persisted to audit/log output.
+- Existing authorization checks remain intact; fencing is an additional fail-closed layer.
+
+## Assumptions resolved from existing architecture
+
+- `ASSUMPTION:` M1 exposes no public lease endpoint. The gateway service is an internal policy surface with deny-all default policy because concrete connector activation/cutover is explicitly deferred.
+- `ASSUMPTION:` Fencing epochs use PostgreSQL `bigint` and cross-module decimal strings, preserving JSON portability without JavaScript number precision loss.
+- `ASSUMPTION:` Process-local grant provenance intentionally fails closed across restart; durable lease/epoch state survives and fresh grants require current policy + lease validation.
+
+## TDD evidence
+
+RED observed before implementation:
+
+- `corepack pnpm --filter @mosaicstack/types exec vitest run src/agent/connector-lease.dto.spec.ts` → failed to load missing `connector-lease.dto.js`.
+- `corepack pnpm --filter @mosaicstack/agent exec vitest run src/connector-lease.test.ts` → failed to load missing `connector-lease.js`.
+- Gateway focused tests failed before implementation because the new repository/service boundaries did not exist (workspace dependencies were then built before behavioral GREEN runs).
+
+GREEN to date:
+
+- Types contract: 6/6 passed.
+- Agent grant/fencing unit suite: 5/5 passed.
+- Gateway PGlite repository + policy/side-effect integration: 7/7 passed; 1 real-PostgreSQL test skipped when `DATABASE_URL` absent.
+- Real PostgreSQL focused run with configured `DATABASE_URL`: 1/1 passed (credential value not emitted in reports).
+
+## Documentation checklist
+
+- [x] `docs/PRD.md` contains current MOS-PORT M1 scope and acceptance criteria.
+- [x] Developer architecture: `docs/architecture/mos-runtime-portability-m1.md`.
+- [x] Admin/operations guidance: `docs/guides/mos-connector-lease-operations.md`.
+- [x] `docs/SITEMAP.md` links both pages.
+- [x] No user-guide change: M1 exposes no user-facing flow or channel cutover.
+- [x] No OpenAPI/endpoint-index change: M1 adds no HTTP endpoint.
+- [x] Migration/restart/rollback safety and credential-safe audit constraints documented.
+- [x] Canonical source remains in-repo; no external publishing action is in scope.
+- [x] Independent review confirms documentation matches implementation; implementation-specific findings were remediated.
+
+## Independent review and remediation
+
+Codex code/security review ran in multiple rounds. Findings and root-cause remediations:
+
+1. Policy could not inspect requested scope/TTL → policy subject now receives normalized requested scopes and explicit requested TTL.
+2. Unbounded authority lifetime → hard defaults cap leases at 5 minutes and grants at 30 seconds; overrides may only tighten; over-limit tests added.
+3. Cross-tenant denial could audit under submitted tenant → mismatch audit uses authenticated tenant plus sanitized `untrusted` target metadata; integration assertion added.
+4. Malformed forged grant could break the denial/audit path → runtime-safe shape validation with sanitized fallback audit; malformed-input test added.
+5. Gateway integration test depended on prior test state → denial test now seeds a unique binding itself; isolated `-t` run passed.
+6. Reviewer repeatedly identified launcher-generated `.mosaic/orchestrator/*` state; those files remain unstaged and excluded from the implementation commit.
+
+Latest independent security review: no critical/high/medium/low findings. Final commit-level code review remains to run after the intended diff is committed without launcher state.
+
+## Verification evidence
+
+- Focused contracts/fencing: types 6/6; agent 9/9.
+- Gateway focused PGlite repository/policy integration: 7/7; isolated denial test 1/1.
+- Real PostgreSQL close/reopen/CAS test: 1/1 with configured `DATABASE_URL`.
+- Root `corepack pnpm typecheck`: 42/42 Turbo tasks passed.
+- Root `corepack pnpm lint`: 23/23 Turbo tasks passed.
+- Root `corepack pnpm format:check`: all matched files passed.
+- Root `corepack pnpm test`: 42/42 Turbo tasks passed; gateway 616 passed / 12 environment-gated skipped; DB 19 passed / 7 environment-gated skipped; Mosaic 650 passed.
+
+## Known residual risks
+
+- Concrete connector policies and Claude/Pi/Codex adapters are intentionally deferred; production policy defaults deny-all.
+- Gateway pre-side-effect validation cannot make an external system exactly-once. Adapters must propagate/enforce the epoch at downstream effect boundaries; receipts/journaling are later #754 scope.
+- Migration rollback is additive-only; dropping lease/audit tables is intentionally manual to avoid destroying authority/audit evidence.
+
+## Commit-level review remediation
+
+- Commit-level Codex code review found one `should-fix`: heartbeat, release, and grant issuance authorized caller-supplied lease fields before canonical normalization.
+- TDD RED: the isolated gateway policy-boundary test showed mixed-case/padded logical agent, binding, connector, scope, and epoch values reaching policy unchanged.
+- Remediation: exported the coordinator's canonical lease normalizer and applied it at the gateway boundary before tenant/policy checks and coordinator dispatch for heartbeat, release, and grant issuance.
+- GREEN: isolated policy test 1/1; focused types 6/6, agent 9/9, gateway 8/8; root typecheck 42/42, lint 23/23, format check passed, and root tests 42/42 (gateway 617 passed / 12 environment-gated skipped).
+- Commit-level security review remained clean: no critical/high/medium/low findings.
+
+## Durable grant-expiry review remediation
+
+- Final commit review found a second `should-fix`: grant expiry was capped against submitted lease metadata after current-authority validation, rather than the durable lease row.
+- TDD RED: a crafted same-authority lease with a later submitted expiry produced a grant expiring after the durable row.
+- Remediation: grant authority fields and expiry now derive from the durable current lease; submitted scopes remain an additional narrowing constraint.
+- GREEN: focused agent fencing suite 10/10.
+
+## Current-main reconciliation (2026-07-14)
+
+- Rebased the existing PR branch from `dff8ce4f79ef90370c29d925002118a708010091` (old base `d0771835542deab048ad8e79f271e3abdb6151f7`) onto `origin/main` `2e2280070ae67288be45f41743cf67052a8ca5a6`; current uncommitted reconciliation head is `d190732a550918161b91d3eb54640f4ea0e2e499`.
+- Resolved only `docs/PRD.md` and `docs/SITEMAP.md`: preserved current-main #752 Native Kanban, #756 official-channel, and #758 FCM material; retained the nonduplicative #755 M1 workstream and placed its two documentation links in the existing Runtime-neutral Mos section. No #755 source semantics changed.
+- Compatibility review confirmed separate authority domains: connector lease/epoch/grant remains distinct from KBN task leases/fences, local Fleet roster lifecycle, auth sessions, ResetSession context, and federation grants. No channel cutover, adapter activation, checkpoint/exactly-once behavior, UI convergence, or #754 expansion was added.
+- Focused verification after building the required workspace dependencies: types contract 6/6; agent fencing/grant 10/10; gateway repository/PGlite and policy integration 8/8. The focused real-PostgreSQL test was skipped because `DATABASE_URL` was not configured; no credentials were inspected or emitted.
+- Generated schema check: `pnpm --filter @mosaicstack/db db:generate` reported no schema changes; migration `0016_salty_morlocks`, snapshot, and journal were unchanged by generation.
+- Full verification: `pnpm typecheck` 42/42; `pnpm lint` 23/23; `pnpm format:check` passed; `pnpm test` 42/42 (gateway 627 passed / 12 environment-gated skipped). Scoped diff check and local documentation-link scan passed.
+- Pending only: commit this reconciliation record, queue guard, force-with-lease push of the rebased existing branch, then fresh independent DB/code/security review and Ultron. Do not claim merge or issue closure.
+
+## Durable lifecycle-authority remediation (2026-07-14)
+
+- Independent review found that heartbeat and release authorized the submitted lease, allowing forged lifecycle scope data to influence policy before the durable row was consulted.
+- Remediation: lifecycle operations tenant-check the submitted lease, load the durable current lease, compare tenant, logical agent, binding, lease UUID, connector, epoch, and canonical ordered scopes, audit and deny any absent/mismatched authority, then run policy and coordinator lifecycle calls with the durable lease. Coordinator CAS/fencing checks remain unchanged.
+- Adversarial gateway integration coverage proves forged `tool.execute` scopes on a durable `runtime.send` lease deny before policy or mutation, preserve heartbeat/release state, and write a denial audit for both lifecycle actions; canonical heartbeat and release remain accepted.
+- Verification: focused types 6/6; agent 10/10; gateway PGlite integration/repository 9/9 with one `DATABASE_URL`-gated PostgreSQL test skipped; Drizzle check passed; root typecheck 42/42; lint 23/23; format check passed; root test 42/42 (gateway 628 passed / 12 environment-gated skipped).
+- Pending: commit, queue-guard, force-with-lease push, then independent DB/code/security rereview and CI. Do not merge or close #755.

docs/scratchpads/756-official-discord-plugin.md

@@ -0,0 +1,57 @@
+# Scratchpad — #756 Official Discord channel plugin
+
+- **Task / issue:** Official Discord channel plugin / #756
+- **Branch:** `feat/756-official-discord-plugin`
+- **Worktree:** `/home/hermes/agent-work/stack-discord-plugin`
+- **Base:** `origin/main` at `49e8a54105eddf41e8e0e44603ded616ee76044f`
+- **Objective:** Deliver harness-neutral Discord routing, native mention-to-thread behavior, untagged in-channel interaction, fail-closed channel/user authorization, and transport-neutral contracts for future official channel plugins.
+- **Collision boundary:** Do not modify orchestrator-to-Pi migration, logical-agent lease/fencing (#754/#755), runtime provider implementations, or orchestrator-owned `docs/TASKS.md`.
+- **Working budget:** 55K tokens for requirements, implementation, tests, documentation, independent review, and delivery. No user-specified hard cap. Reduce optional refactoring before reducing acceptance coverage.
+
+## Assumptions
+
+1. **ASSUMPTION:** Every configured Discord channel is intentionally agent-bound, so an authorized human's untagged message is agent input and receives an in-channel response. Rationale: this satisfies the requested no-tag behavior without activating the bot in arbitrary channels.
+2. **ASSUMPTION:** Mentioning the bot in a parent channel creates or reuses a public Discord thread; messages already in a thread remain in that thread without repeated mentions. Rationale: Discord does not support nested threads and the request describes tags as the thread-selection signal.
+3. **ASSUMPTION:** One bot process may host multiple configured channel-to-logical-agent bindings. Rationale: bindings are already configuration-owned and this avoids per-agent Discord credentials.
+4. **ASSUMPTION:** Static guild/channel/user allowlists and paired-user roles remain the administration surface for this slice. Rationale: dynamic admin UI is larger and can be added without changing adapter contracts.
+5. **ASSUMPTION:** The stable conversation handle contains logical agent plus Discord channel/thread identity and never a harness/provider identifier. Rationale: runtime re-enrollment and the active lease work can change Claude/Codex/Pi/OpenCode behind the same channel connection.
+6. **ASSUMPTION:** Canonical documentation remains in-repository for this slice; no external publishing is performed.
+
+## Plan
+
+1. Update `docs/PRD.md` before code with #756 scope, constraints, assumptions, and acceptance criteria.
+2. Add failing Discord behavior and authorization tests first.
+3. Add transport-neutral channel DTO/contracts in `@mosaicstack/types`.
+4. Implement mention-to-thread, untagged in-channel, existing-thread, stable conversation, and adapter health behavior without runtime-specific imports.
+5. Update admin/developer/channel protocol docs and documentation checklist.
+6. Run focused tests, typecheck, lint, formatting, full applicable baseline, and coverage.
+7. Run independent code and security review; remediate and re-review.
+8. Commit, queue-guard, push, open PR to `main`, wait for green CI, squash merge, verify merged CI, and close #756.
+
+## Progress
+
+- 2026-07-14: Loaded mission state (none active), global/project guidance, current `origin/main`, existing Discord/Tess/fleet connector architecture, issue #709 history, and active portability issues #754/#755.
+- 2026-07-14: Created issue #756 through the Mosaic wrapper.
+- 2026-07-14: Created isolated worktree/branch from current `origin/main`; the stale root checkout and unrelated QA artifacts remain untouched.
+
+## TDD decision
+
+Required and applied. This change modifies authorization-sensitive remote ingress and routing behavior. Failing permission and routing tests will be captured before implementation.
+
+## Risks / blockers
+
+- Active logical-agent lease work may later add stronger fencing fields. This slice must expose a clean, harness-neutral seam without duplicating that schema.
+- Discord thread creation is an external side effect. Unit tests use a typed fake; live credential smoke testing is out of scope and must not use committed secrets.
+- Repository-wide checks may expose unrelated baseline debt; changed-scope evidence and CI remain mandatory.
+
+## Verification evidence
+
+- `pnpm format:check` — passed.
+- `git diff --check` — passed.
+- `pnpm typecheck` — passed (42 Turbo tasks).
+- `pnpm lint` — passed (23 Turbo tasks).
+- `pnpm build` — passed (23 Turbo tasks).
+- `pnpm --filter @mosaicstack/discord-plugin test` — passed: 44 tests; V8 coverage 92.18% statements/lines, 86.55% branches, 100% functions (all configured thresholds ≥85%).
+- Focused gateway verification passed: Discord ingress/security, cross-surface, ownership, redaction/concurrency, and agent attachment tests.
+- `pnpm test` — changed-scope suites passed; repository baseline remains blocked by `apps/gateway/src/__tests__/cross-user-isolation.test.ts` requiring PostgreSQL at localhost port 5433 (`ECONNREFUSED`). The failure is unrelated to this change.
+- Independent code/security re-reviews requested after final remediation; reports are stored under ignored `docs/reports/` evidence paths.

docs/scratchpads/758-fcm-m1-002-shared-role-resolution.md

@@ -0,0 +1,148 @@
+# FCM-M1-002 — Shared role resolution
+
+- **Task:** `FCM-M1-002`
+- **Issue:** `mosaicstack/stack#758`
+- **Branch:** `feat/758-shared-role-resolution`
+- **Starting head:** `32e75c67b094de443d37fe7d5ff8d25cdfc8b39d`
+- **Role:** implementation worker; independent review and merge remain outside this worker
+
+## Objective
+
+Reuse the existing baseline-plus-`roles.local` persona resolver as the sole class authority for roster-v2 semantics, profile validation, provisioning, and launch/persona resolution. Add exact approved alias canonicalization, fail-closed semantic validation, immutable canonical-class authority contracts, required baseline roles, and operator documentation without implementing lifecycle, mutation, credentials, certificate workflow, or later FCM cards.
+
+## Budget
+
+- Soft budget: **25K tokens**.
+- Strategy: inspect once, implement in small TDD units, run focused suites before the full package gate, and avoid unrelated refactors or M1-003/M2/M4 scope.
+
+## Plan
+
+1. Map the existing persona resolver, roster-v2 compiler, profile/provision consumers, launch resolution, role library, and focused tests.
+2. Write denial/invariant tests first for aliases, canonicalization-before-override, unreadable roles, authority boundaries, policy mismatch, canonical provision output, and resolver parity.
+3. Run the focused suites and record the expected red evidence.
+4. Implement one shared canonical resolution and authority contract in/through `fleet-personas.ts`; delegate roster semantic validation and profile/provision paths to it.
+5. Add baseline `validator`, `team-leader`, and `interaction` role contracts plus `LIBRARY.md` entries while retaining `operator-interaction` compatibility.
+6. Add the required role reference, alias migration, customization guide, and roster-v2 semantic handoff documentation.
+7. Run focused tests, the full `@mosaicstack/mosaic` suite, typecheck, lint, Prettier, `git diff --check`, situational verification, independent code/security review, and remediation.
+8. Commit with the required co-author trailer, run the CI queue guard, push the existing branch, and create/update exactly one PR to `main` with `Refs #758`.
+
+## TDD evidence
+
+### Red
+
+After installing worktree-local dependencies and building `@mosaicstack/db`, the pre-implementation
+focused run collected the intended tests and failed as expected:
+
+```text
+2 test files failed; 32 tests failed; 32 tests passed
+```
+
+Expected failures named the missing `canonicalizeRoleClass`,
+`authorityForCanonicalClass`, and `validateRosterV2Semantics` APIs, absent requested/canonical typed
+output, and unresolved required canonical role contracts. An earlier run that failed before test
+collection on an unresolved `yaml` dependency was treated as environment setup, not TDD evidence.
+
+### Green
+
+Focused role-resolution and affected service fixtures:
+
+```text
+6 test files passed; 109 tests passed
+```
+
+The focused set covers personas, profiles, provision, launch persona contract, roster-v2 semantics,
+and the operator-interaction service fixture. The final profile tests also cover readable lead/floor
+compatibility and canonical collision denial.
+
+## Tests and gates
+
+- Focused suites: pass, **6 files / 109 tests**.
+- Full `@mosaicstack/mosaic` suite: pass, **50 files / 713 tests**. Workspace package build outputs
+  were prepared first because a clean worktree has no dependency `dist` entries.
+- `pnpm --filter @mosaicstack/mosaic typecheck`: pass.
+- `pnpm --filter @mosaicstack/mosaic lint`: pass.
+- Prettier check over every changed file: pass.
+- `git diff --check`: pass.
+- Runtime/file-boundary evidence: real role library, profile/provision filesystem integration,
+  launch-time synchronous contract injection, v1 roster parser round-trip, roster-v2 semantic
+  filesystem checks, and operator-interaction service fixtures all pass without live mutation.
+- Independent code review: **APPROVE**, no blocking or non-blocking findings; reviewed complete
+  tracked/untracked delta including the canonical collision guard. Residual: roster-v2 semantic
+  validation is an explicit async handoff with production caller wiring owned by later work.
+- Independent security review: **APPROVE**, no verified authority/security findings on the final
+  delta.
+
+### Post-PR fail-closed remediation
+
+Independent rereview found resolver fail-open edges that the original green PR head did not cover. The
+remediation remained uncommitted until every finding was reproduced red-first and the same reviewer
+approved the complete two-file delta.
+
+Final regression evidence:
+
+```text
+persona resolver: 47/47
+focused affected suites: 6 files / 138 tests
+root-container resolver suites: 86/86
+full canonical run: 42/42 Turbo tasks; Mosaic 50 files / 733 tests
+```
+
+DB migration, typecheck, lint, Prettier, and `git diff --check` also passed. Coverage now proves:
+
+- unreadable, unscannable, direct-dangling, ancestor-dangling, and literal `..` traversal override paths
+  fail closed across async, sync, listing, and status APIs;
+- genuinely missing override directories still permit baseline fallback;
+- cached missing scans are revalidated before fallback;
+- marker-defined identity and domain metadata are revalidated on the second read;
+- `LIBRARY.md` rows and incidental later markers cannot define, shadow, or advertise personas.
+
+Exact-head pipeline `1819` passed for rebased head `4d990eee…`, but the independent reviewer-of-record
+returned **REQUEST CHANGES** after reproducing three additional edge failures: a canonical filename could
+inherit protected authority despite a conflicting explicit first marker, cached `scanned` absence could
+miss an override created before baseline fallback, and inherited plain-object names such as `constructor`
+could corrupt alias/authority lookup. Merge remained held.
+
+Each failure was reproduced red-first in the persona suite (4 failing assertions), then remediated without
+expanding card scope. Explicit first markers now own identity and filename fallback applies only to
+markerless contracts; every second read rejects a newly introduced conflicting marker regardless of
+cached classification; cached async resolution re-scans the override layer immediately before every
+baseline fallback; alias and authority registries require own-property matches. Current uncommitted
+evidence is persona **52/52**, focused affected suites **6 files / 143 tests**, and full Mosaic package
+**50 files / 738 tests**, plus typecheck, lint, Prettier, and `git diff --check`. Independent
+finding-specific rereview **APPROVED** the complete uncommitted three-file remediation after direct
+adversarial reproduction of all three findings and the follow-up markerless TOCTOU. All post-commit
+exact-head gates remain required.
+
+## Risks and boundaries
+
+- **Security-sensitive authority:** authority must derive only from canonical class, never role prose, aliases, display names, or tool-policy text.
+- **Resolver divergence:** no second regex, registry, scanner, or prose parser may be introduced.
+- **Alias capture:** aliases must canonicalize before baseline/`roles.local` lookup so local files cannot redefine legacy aliases as separate authority.
+- **Readable persona requirement:** semantic success requires a resolved readable persona, not class-set membership.
+- **Scope control:** no roster mutation, lifecycle, lease issuance, certificate workflow/storage, credentials, remote reconciliation, provision-v2 conversion, or shipped-example disposition execution.
+- **Coordination:** `docs/TASKS.md` is read-only and remains orchestrator-owned.
+
+## Acceptance-evidence mapping
+
+| Requirement / criterion | Verification evidence |
+| --- | --- |
+| `FCM-REQ-02` shared semantic resolver | Async/sync resolver parity; roster-v2 delegates batched scans and resolution; profiles/provision and launch reuse `fleet-personas.ts`; no second scanner or class-marker regex added. |
+| `FCM-REQ-07` canonical classes and authority boundaries | Exact alias and non-alias tests; immutable authority invariant tests; all required canonical contracts resolve through the real role library. |
+| `AC-FCM-01` structural + semantic roster validation | Synchronous parser/normalizer tests remain intact; async semantic tests cover aliases, custom roles, unreadable/unresolved roles, `LIBRARY`-only rejection, and bidirectional protected policy mismatch. |
+| `AC-FCM-07` protected authority invariants | Denial tests prove merge-gate-only merge, validator certificate-only, orchestrator/team-leader/interaction limits, no implicit custom-role authority, and canonical tool-policy matching. |
+
+## Documentation
+
+- `docs/fleet/reference/role-classes.md`
+- `docs/fleet/migration/legacy-class-aliases.md`
+- `docs/fleet/how-to/customize-roles.md`
+- `docs/fleet/reference/roster-v2-fields.md` semantic handoff
+- Baseline role contracts and `LIBRARY.md` rows for `validator`, `team-leader`, and `interaction`
+
+## Residual risks
+
+- Provisioning remains intentionally v1 and does not emit `reports_to`; canonical topology is retained
+  in its typed seat/summary path only, matching the existing v1 parser boundary.
+- Alias support remains for compatibility; new configuration should emit canonical identities.
+- This card defines authority metadata and validation only. Enforcement workflows for leases,
+  certificates, lifecycle, and mutation remain owned by later FCM cards.

docs/scratchpads/758-fcm-m1-003-example-profile-dispositions.md

@@ -0,0 +1,37 @@
+# FCM-M1-003 — Executable example/profile/service-preset dispositions
+
+- **Task / issue:** FCM-M1-003 / #758
+- **Branch / base:** `test/758-example-profile-dispositions` from `origin/main` `a5e8e554012f27898e035d2882a8e47e1a02fe97`
+- **Objective:** Make every artifact in the M0 legacy disposition inventory executable evidence: it must validate canonically, be explicitly retained as a v1 fixture, or be retired with a replacement/deprecation link.
+- **Scope:** Validation and explicit version/retirement metadata only for shipped examples, profiles, and the operator-interaction service preset. Reuse the central resolver and existing v2 roster compiler.
+- **Out of scope:** Generated environment boundaries, CRUD, reconciliation/apply, migration, live fleet mutation, and `docs/TASKS.md`.
+- **Budget:** 20K card allocation; use focused package tests before full package validation.
+
+## Plan
+
+1. Inventory exact shipped artifacts and existing compiler/resolver/profile tests.
+2. Add failing behavior tests covering all listed artifacts and their documented disposition.
+3. Implement minimal declarative fixture/disposition validation; do not add a role/class resolver.
+4. Run focused and package quality gates; obtain independent code and security review.
+5. Commit, queue-guard, push, open one `main` PR with `Refs #758`.
+
+## Progress
+
+- Intake complete: verified no branch, worktree, or open PR for this card before creating this isolated worktree.
+- Requirements read: FCM PRD, FCM-M1-003 task row, M0 disposition inventory, delivery/QA/documentation guides.
+- TDD: RED recorded with `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` failing because the new module did not exist; GREEN recorded after the minimal guard implementation. The focused suite now has 4 passing tests, including undeclared-artifact and missing-explicit-v1-version denials.
+- Independent review: initial code review found the service policy path was hardcoded; remediation iterates declared `canonical-service-policy` artifacts. Exact-head code review approved and exact-head security review found no issues.
+
+## Risks / decisions
+
+- The M0 inventory permits unresolved legacy roles only when explicitly v1-versioned or retired. Do not infer aliases beyond the three approved by FCM-M1-002.
+- `docs/TASKS.md` is orchestrator-owned and will not be edited.
+
+## Verification evidence
+
+- Focused TDD guard: `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` — PASS (4 tests).
+- Full package suite: `pnpm --filter @mosaicstack/mosaic test` — PASS (51 files, 742 tests).
+- Static gates: `pnpm --filter @mosaicstack/mosaic typecheck`, `pnpm --filter @mosaicstack/mosaic lint`, and `pnpm format:check` — PASS.
+- Diff gate: `git diff --check` — PASS.
+- Exact-head reviews: `codex-code-review.sh --uncommitted` — APPROVE; `codex-security-review.sh --uncommitted` — no findings.
+- Delivery: committed as `9a9ad1a`, pushed after `ci-queue-wait.sh --purpose push`, and opened PR [#770](https://git.mosaicstack.dev/mosaicstack/stack/pulls/770) to `main` with `Refs #758`. `pr-ci-wait.sh -n 770` reported terminal-green Woodpecker pipeline [#1823](https://ci.mosaicstack.dev/repos/47/pipeline/1823/1).

docs/scratchpads/771-kbn101-db-role-split.md

@@ -0,0 +1,138 @@
+# Scratchpad — KBN-101 DB runtime/migration role split (#771)
+
+- **Branch:** `docs/771-kbn101-db-role-split`
+- **Base:** `main` `e9c4aa3`
+- **Scope:** planning/documentation only; authorized files are PRD, Native Kanban task/shared/index docs, sitemap, this scratchpad, and the new KBN-101 contract.
+- **Explicit exclusions:** source/runtime/config/deployment/secret/migration/compose/CI/lock/package/KBN-100 branch edits; no production mutation.
+
+## Objective
+
+Freeze an implementation-ready PostgreSQL role/connection split so the Gateway uses a non-owner runtime identity and only a dedicated migration phase uses an owner/migrator identity. Make real deployed-role certification—not synthetic role tests—a serial prerequisite of KBN-100 and KBN-105.
+
+## Intake and current-state evidence
+
+- Mission MVP is active; W3 Native Kanban/SOT is planning-complete. The task state shows KBN-010 as the predecessor and KBN-100 as the current schema slice.
+- Current branch started at `e9c4aa3`; `.mosaic/orchestrator/{mission.json,session.lock}` were already runtime-modified and remain untouched.
+- `packages/db/src/client.ts`, `migrate.ts`, and `drizzle.config.ts` resolve one `DATABASE_URL` (with default fallback). `packages/storage/src/adapters/postgres.ts` calls `runMigrations(this.url)`.
+- `apps/gateway/src/database/database.module.ts` calls `storageAdapter.migrate()` at startup for PostgreSQL; this is the owner-runtime defect to remove in KBN-101 implementation.
+- `packages/config/src/mosaic-config.ts`, installer wizard, local/federated compose, Portainer test stack, and `.woodpecker/ci.yml` currently expose one URL. PGlite has an existing explicit local migration path.
+- Current KBN contract requires immutable events/checkpoints/artifacts/evidence, `RESTRICT`, and KBN-100 generated Drizzle consistency. It did not establish a deployable runtime identity split.
+
+## Frozen decisions
+
+1. `DATABASE_URL` is the non-owner runtime URL; `DATABASE_MIGRATION_URL` is migration-only. Both are required in their respective PostgreSQL phases; PGlite is the explicit local exception; migration never falls back to runtime/default/config URL.
+2. PostgreSQL Gateway runtime never auto-runs migration/DDL. Dedicated migrator uses `pg_try_advisory_lock(hashtext('mosaic-schema-migration-v1'))`; replicas only check exact ordered Drizzle-ledger readiness and fail closed.
+3. Roles are non-login `mosaic_platform_database_owner`, non-login `mosaic_schema_owner`, login/noinherit `mosaic_migrator`, non-login `mosaic_runtime_capability`, and login/inherit `mosaic_runtime`. Runtime inherits only its capability role with SET/ADMIN denied, has no owner/migrator membership, no unsafe attributes/ownership/DDL authority, and an explicit trusted search path.
+4. Runtime gets mutable DML only as needed, but INSERT/SELECT only on `task_events`, `artifacts`, `task_checkpoints`, `task_checkpoint_artifacts`, and `approval_decision_artifacts`. KBN-100 still enforces RESTRICT/no-cascade.
+5. Startup verifies effective role/ownership/attributes/inherited capability/TEMP/function-execute/ledger grants/search path/immutable denials/schema fingerprint without DSN exposure. It also requires authenticated CA/hostname-verified TLS. Stable sanitized errors and redaction rules are required.
+6. N-1 retains single runtime URL only as a non-certified compatibility release; staged role provisioning/migration/runtime deployment then enforces the split. Rollback never injects migration URL into Gateway.
+7. Vault target paths, rotation, deployment injection, CI, installer, compose, Portainer, and observability are separate one-card/one-PR handoffs. The migration-only file manifest includes `packages/db/drizzle.config.ts`; KBN-101 repairs the known PostgreSQL runner/journal ordering defect and proves a clean database applies every hash once before its foundation certificate. No application migration creates roles/passwords or hardcodes credentials.
+8. KBN-101 foundation merges/certifies first. KBN-100 then rebases, restores Drizzle declaration/snapshot/journal consistency, and bounds procedural immutable-table grant/trigger/backfill work to its own slice. Because those immutable relations do not exist until KBN-100, KBN-101’s real deployed-role immutable-operation certificate follows KBN-100 and is the serial gate before KBN-105.
+
+## Assumptions
+
+- `standalone` and `federated` are all current PostgreSQL production-like modes; a future PostgreSQL tier inherits this contract unless versioned otherwise.
+- Deployment will support a dedicated migration Job/one-shot command. A target that cannot run it cannot receive production/federated KBN certification.
+- Canonical Vault target paths require deployment-owner verification before provisioning; the planning document does not claim they already exist.
+
+## Documentation produced
+
+- `docs/PRD.md`: bounded KBN-101 requirements and acceptance criteria.
+- `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md`: normative rc.5 implementation, threat, migration/rollback, evidence, and exact file DAG contract.
+- `docs/native-kanban-sot/SHARED-CONTRACT.md`: rc.5 amendment preserving rc.4.
+- `docs/native-kanban-sot/TASKS.md`: KBN-101 inserted before and blocks KBN-100; KBN-105 held.
+- Native Kanban index and root sitemap links.
+
+## Validation plan
+
+1. Prettier only for changed Markdown.
+2. Markdown link target/check checks scoped to modified docs.
+3. Strict contract check with `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` (the frozen TypeScript contracts remain unchanged).
+4. Diff allowlist proves only authorized documentation files changed, apart from pre-existing Mosaic runtime state.
+5. Independent documentation/security self-review: role escalation, fallback, startup DDL, schema readiness, grants/default privileges, immutable tables, secret leakage, deployment and KBN-100 boundaries.
+
+## Review corrections
+
+Independent Codex review found two blockers and security review found two medium defects; all were remediated in the frozen contract:
+
+1. Split the KBN-101 certificate into a foundation role/schema-boundary certificate (before KBN-100) and real immutable-operation certificate (after KBN-100, before KBN-105). This preserves the requested KBN-100 block without requiring evidence for tables not yet created.
+2. Removed the legacy owner-runtime exception. N-1 compatibility preserves variable/config shape only; the KBN-101 runtime refuses owner/migrator identity and current single-URL installs remain on their previous release until role cutover.
+3. Introduced `mosaic_platform_database_owner` as a separate non-login platform role. `mosaic_schema_owner` owns application/ledger schemas only, not the database and has no database CREATE/ALTER/extension authority.
+4. Replaced blocking `pg_advisory_lock` with `pg_try_advisory_lock` and the deterministic `DATABASE_MIGRATION_LOCKED` failure.
+5. Review also flagged active `.mosaic/orchestrator` state. It was pre-existing launcher state and remains unstaged/uncommitted.
+6. Second review added `packages/db/drizzle.config.ts` to the migration-only slice, mandates `DATABASE_MIGRATION_URL` with a missing-variable negative, grants runtime only `USAGE` plus `SELECT` on `drizzle.__drizzle_migrations`, and verifies/revokes its ledger writes.
+7. Security review added `DATABASE_TLS_CA_CERT_PATH` / `DatabaseTlsConfigDto` with authenticated TLS and hostname/CA verification in production-like modes, explicit database `TEMPORARY` revocation/catalog denial testing, and default-PUBLIC function EXECUTE revocation with SECURITY DEFINER prohibited by default.
+8. Final review corrected the runtime login to inherit only its capability role with SET/ADMIN denied, and moved the known hash-complete migration-runner/journal repair into KBN-101-03 before the foundation certificate.
+9. Final manifest review added all live runtime DDL paths (`packages/storage/src/tier-detection.ts`, Gateway startup, and `fleet-backlog`) to KBN-101-02, requiring read-only extension probes and no PostgreSQL runtime auto-migration. It also requires KBN-101-04 to stop persisting either DSN into generated `.env`/`mosaic.config.json`, using only Vault/deployment references and injected variables.
+10. Provisioning review separated the external privileged platform bootstrap actor from the NOCREATEDB database-owner role and added KBN-101-00. That IaC/bootstrap card owns fresh/existing database role/ownership/grant/Vault transition evidence and is a foundation-certificate dependency.
+
+## Results
+
+- `pnpm exec prettier --check` on every authorized Markdown file: PASS.
+- Markdown link and whitespace checker on all seven authorized Markdown files: PASS.
+- `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json`: PASS (frozen strict contracts unchanged).
+- Codex code review iterated through role inheritability, hash-complete migration ordering, all reachable runtime DDL entrypoints, installer DSN persistence, and platform-bootstrap ownership; each finding was incorporated into the final frozen contract/DAG. The last security review found no new KBN-101 vulnerability; its sole low finding is the pre-existing unstaged Mosaic session-lock metadata, which is excluded from this commit.
+- Commit: `82ce3252df38a687c50485f8d048b53ca8db5989` (`docs(#771): freeze database runtime role split`).
+- Pre-push queue guard: `ci-queue-wait.sh --purpose push -B main` returned `state=unknown` without failure. The push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`: PASS.
+- Pushed branch `docs/771-kbn101-db-role-split` at the exact commit above; no PR was opened, merged, or closed. `web1:mosaic-100` received the handoff with head, decisions, DAG, and validation.
+- Awaiting independent security/Ultron review.
+
+## 2026-07-15 — rc.6 exact-head remediation session
+
+- **Objective / correction:** Replace the prior planning-author handoff and close every finding in the [independent exact-head report](../reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) against `da742ca2da4a2ff466916c818fe275c4f7ffd384`. The report is a verbatim durable copy of the task-supplied review artifact; scope remains documentation-only, `.mosaic` is excluded, and source/config/compose/CI/deployment/secrets/migrations remain untouched.
+- **Finding 1 — closed DDL control plane:** rc.6 names `mosaic-db-migrator` as the sole application/CI/test PostgreSQL DDL runner, requires `DATABASE_MIGRATION_URL` before connection/DDL, inventories `runMigrations`, Drizzle config/scripts, `db:push`, storage CLI, adapter/Gateway startup, fleet-backlog, extension probes/bootstrap, direct federated integration DDL, CI, and future scripts, and specifies route/deny/test disposition for each. Tests use runner-prepared disposable PostgreSQL or invoke that runner; `db:push` is local-disposable-only and rejects production-like URLs.
+- **Finding 2 — deployable TLS:** rc.6 freezes distinct runtime/migrator URL and CA/server leaf Vault/compose/Swarm secret identifiers, `0400` key and `0600` URL/cert/CA mount requirements, actual compose/Swarm service-DNS SANs, PostgreSQL TLS settings, legacy-client drain/termination plus `hostssl` enforcement, verified-TLS readiness ordering, fresh/existing transition, CA-overlap rotation/TLS-only rollback, and standalone plus federated/Swarm positive and missing/wrong CA/SAN/downgrade negatives. PGlite is explicitly non-PostgreSQL evidence.
+- **Finding 3 — manifest/0009:** rc.6 defines manifest v1 canonical UTF-8 serialization and raw SQL-byte SHA-256, logical journal order, manifest ownership/grants, exact one-to-one observed hash tuple mapping, non-normative physical insertion order, safe original-0009 conditions, ambiguous-effect fail-closed recovery, and the full required reconciliation/backup test matrix. It preserves shipped 0009 bytes and forbids manual ledger adoption/insertion.
+- **Finding 4 — advisory lock:** replaced `hashtext` with fixed signed-int4-safe `(1297044289,1262636593)` (`MOSA`,`KBN1`), one `max:1` runner session, close-on-crash semantics, and contention/crash/readiness/unrelated-key evidence.
+- **Finding 5 — identifiers/search path:** selects `mosaic`, exact `pg_catalog,mosaic` per pooled connection and `SET LOCAL` transactions, plans audited public-object/extension/Drizzle relocation, forbids config-derived identifiers, limits bootstrap quoting to server-side `%I` on fixed allowlist, and requires injection/pool-reset negatives.
+- **Finding 6 — safe DAG:** cards 00–07 are inactive prepared capability while owner-runtime remains N-1; KBN-101-08 is the one atomic activation release after platform roles/TLS and compatible code. Mosaic control plane/Jason alone can activate/rollback; no force-on-red, runtime bypass, or temporary compatibility survives the gate. The approved role graph, post-KBN-100 immutable certification, and KBN-105 gate remain unchanged.
+- **Review remediation:** Codex review found the legacy plaintext cutover gap, missing URL-secret bindings, historical `public` migration incompatibility, non-reproducible checkout-byte hashing, CONNECT allowlisting regression, and undocumented direct-DDL operator instructions. rc.6 now requires drain/scale-to-zero, residual non-TLS session termination, `hostssl` with no `host` rule, zero plaintext-session proof, TLS-only post-enforcement rollback, distinct named runtime/migrator secret consumers, canonical Git-blob/LF manifest bytes, a runner-only owner-controlled legacy-public bootstrap followed by `mosaic` relocation, explicit CONNECT/TEMP revocation, and KBN-101-07 replacement of direct-DDL documentation. It also required the durable exact-head report link above. Pre-existing `.mosaic` runtime state remains excluded.
+- **Validation:** Prettier on all changed Markdown, repository Markdown link/whitespace check, and strict native-kanban contract TypeScript passed before final staging; the final staged diff excludes `.mosaic`. No source-code TDD applies because this is contract-only remediation.
+
+## 2026-07-15 — rc.7 residual remediation session
+
+- **Objective / correction:** Close every residual in the independent exact-head rc.6 re-review at `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview-45ba3d6.md` for `45ba3d6ad4d5383f457a303c05bc816144cfa48a`, without changing source, compose, CI, deployment, migration, or secret artifacts. Only the existing authorized planning/documentation paths are eligible; pre-existing `.mosaic` state remains excluded.
+- **Source-backed scope confirmed:** the active `federated-pgvector.integration.test.ts` executes `CREATE TEMP TABLE`; tracked `docker/init-db.sql` and `infra/pg-init/01-extensions.sql` both create `vector`; `migrate-tier.ts` advertises raw `CREATE EXTENSION`; and `tools/federation-harness/docker-compose.two-gateways.yml` is current plaintext two-PostgreSQL/two-Gateway topology. Current `schema.ts` has 36 default-schema `pgTable` declarations, 6 default `pgEnum` declarations, and an unqualified `vector` custom type; historical migrations contain `public` references.
+- **Plan:** (1) make the finite DDL/static-bypass inventory and `DATABASE_URL`-only denial matrix exact, including the runner-prepared persistent pgvector fixture and migrated two-gateway harness; (2) freeze executable `public`-to-`mosaic` and `mosaic_extensions` transition, Drizzle ownership, object-catalog classes/order, eligibility and rollback tests; (3) bind repository/control-plane ownership, UID/GID validation, exact artifact/mount rules, and both gateway TLS topology; (4) correct PRD acceptance mapping and cross-document rc.7 status; then run formatting, link/contract, source-path, diff, review, commit, queue guard, and push.
+- **Independent review closure:** initial Codex review found Gateway-key consumer wording, `CLAUDE.md` omission, final schema-owner set, and placeholder SANs; all are now explicit. Re-review found the legacy `0001` vector-type resolution problem and `docs/federation/SETUP.md` raw-DDL instruction; the legacy runner now uses only its fixed non-writable `pg_catalog,public,mosaic_extensions` history path, while runtime remains `pg_catalog,mosaic`, and the federation setup path is assigned to KBN-101-07/static inventory. Security review final verdict: no confident vulnerability. The review also repeated the pre-existing tracked `.mosaic` session-state concern; it remains deliberately unstaged/excluded by this task.
+- **Completion evidence:** changed Markdown is Prettier-formatted; local links and strict native-kanban TypeScript passed; source-path inventory confirmed all current referenced paths (the new `apps/gateway/Dockerfile` is explicitly a planned KBN-101-05 artifact); diff check and authorized-doc allowlist passed. No source-code TDD applies to this documentation-only remediation.
+
+## 2026-07-15 — rc.8 exact residual remediation session
+
+- **Objective / correction:** Close all three HIGH findings in the independent rc.7 exact-head re-review at `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview2-0778eba.md` for `0778eba2db3c2dfbaca3af352b12ba0389d3552b`. Scope remains documentation-only: no source, config, Compose, CI, deployment, secret, or migration artifact changed; pre-existing `.mosaic/orchestrator` state remains excluded.
+- **Finite authority closure:** KBN-101-06 now classifies exact current source/scripts/package bins, operator docs, and deploy manifests. `packages/db/src/index.ts` has explicit removal/compile-import negative ownership; `docs/fleet/backlog-conventions.md` and `docs/PERFORMANCE.md` now remove first-use/direct-Drizzle/Gateway-startup migration instructions and point to sole runner/readiness. Byte-immutable historical SQL, PGlite-only routines, negative-test literals, vendored/generated artifacts, and labeled historical reports are exact-path/category reviewed allowlists; unknown hits fail. The contract explicitly rejects relying on a naive token scan alone.
+- **Executable and exclusive handoff closure:** KBN-101-03 exclusively owns the published `mosaic-db-migrator` bin, `packages/db/src/cli.ts`, private migrator modules, `docker/db-migrator.Dockerfile`, exact `--run|--verify|--help`, environment/argv limits, sanitized exits, and command/order tests. KBN-101-00 exclusively owns `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, and bootstrap tests. KBN-101-05 exclusively owns `tools/db/render-postgres-secrets.ts`, its tests, and deployment declarations, consuming the versioned bootstrap interface without overlap.
+- **pgvector owner closure:** `mosaic_extension_owner` is dedicated NOLOGIN, available only to the external bootstrap actor during bootstrap; fresh vector/member ownership remains there. The contract records PostgreSQL's unsupported extension-owner transfer and forbids catalog mutation, ownership adoption, and `DROP CASCADE`. Approved-owner existing extensions use verified `ALTER EXTENSION ... SET SCHEMA`; legacy runtime-owned extensions fail closed to a controlled backup/shadow/runner/copy-evidence/quiesce/final-delta/atomic-switch/read-only-rollback migration. It requires `pg_extension.extowner`, member/schema/version, and runtime/migrator/schema-owner ALTER/DROP/member-update denial tests across clean, approved-owner, legacy shadow, partial/resume/rollback, and N-1.
+- **Cross-document state:** PRD, KBN contract, shared contract, task decomposition, index, sitemap, current operator docs, and this scratchpad are rc.8-consistent. The only intended next action is a fresh independent exact-head re-review after validation/push.
+- **Validation / review:** Prettier passed for all nine changed Markdown documents; local links passed (9 documents); `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` passed; source-path inventory passed (20 paths: 8 current, 12 explicitly planned); finite-authority requirement checklist and `git diff --check` passed. Manual documentation/security review checked the three requested paths, private-only runner boundary/exit contract, non-overlapping 00/03/05 ownership, extension-owner denial and shadow path, and `.mosaic` exclusion. No source-code TDD applies because this is contract-only remediation.
+- **Delivery evidence:** committed `1423c2ad02b5471eab006fb4c878808e5b29c387` as `docs(#771): close role split rc.8 residuals`. Push queue guard returned `state=unknown` without error; push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`, all PASS; branch push succeeded. This final evidence append is committed next, then the exact remote head is verified. The only intended next action is a fresh independent exact-head re-review.
+
+## 2026-07-15 — rc.9 final residual remediation session
+
+- **Objective / correction:** Close the three findings in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview3-9cf5d2f.md` against exact head `9cf5d2f6641b14082dc3294e2a84d1fb4ccc019d`: move `mosaic_extensions` schema ownership to `mosaic_extension_owner`; replace all broad/conflicting KBN-101 card ownership with a complete disjoint exact-path/test manifest; and classify the current architecture-plan `db:migrate` instruction with pinned scanner mechanics. Scope remains documentation-only; no source/config/Compose/CI/deployment/secret/migration artifact and no `.mosaic` path may be modified.
+- **Plan:** inspect current tracked source topology to name only existing paths; update the normative contract first and synchronize PRD/shared/task/index/sitemap/version language; run Prettier, changed-doc links, strict contract TypeScript, source/path and manifest-overlap checks, diff allowlist, independent documentation/security review; then stage docs only, commit, queue-guard, push, and verify exact remote SHA. No source-code TDD applies because this is contract-only remediation.
+- **Closure implemented:** rc.9 makes `mosaic_extension_owner` create and own `mosaic_extensions`, `vector`, and members; the external bootstrap actor alone temporarily `SET ROLE`s for fresh/approved-owner work, while schema owner has only `USAGE` for legacy type resolution and never temporary `CREATE`. Catalog/default-ACL plus direct DDL/member denials now cover runtime, migrator, and schema owner through fresh, relocation, shadow/resume, and rollback evidence.
+- **Delivery decomposition:** Replaced broad ownership with complete disjoint 00–09 manifests, exact tests/evidence, producer-before-consumer edges, and an explicit no-intermediate-deploy N-1 activation statement. `packages/storage/src/{cli,migrate-tier}.ts` belongs only to -02; the current tracked init artifacts are retired by -02 as direct-DLL closure; -03 owns all runner/index/migrate/config/schema assets and exact compiled-bin/image mapping; -07 owns docs only; -08/-09 own evidence only.
+- **Classifier closure:** -06 has exact scanner/inventory/matrix paths, canonical inventory fields, classes/dispositions, fixed token/rule set, exact allowlist categories/restrictions, and self-test requirements for unknown, duplicate-owner, ownerless, missing-path, and historical masking cases. The architecture plan now marks direct `db:migrate` superseded and uses `mosaic-db-migrator --run`.
+- **Validation:** Prettier check, strict native-kanban contract TypeScript, changed-document local-link resolution, `git diff --check`, and an automated manifest-overlap/owner/current-source-path check passed. Targeted documentation/security review verified role ownership/default privileges/search path/preflight/legacy/shadow/rollback consistency, disjoint manifests/DAG/activation, scanner mechanics, exact bin/entrypoint, and no `.mosaic` staging intent. No source-code TDD applies because this is documentation-only remediation.
+- **Next:** stage documentation only, commit, queue-guard, push, verify exact remote SHA, then wait for fresh exact-head review.
+- **Delivery evidence:** committed `8cbad2bcd9bc7507052f74f35670ef7c8e39e44e` as `docs(#771): close role split rc.9 residuals`; `ci-queue-wait.sh --purpose push -B main` returned `state=unknown` without error; push-hook `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` all passed; push succeeded and `origin/docs/771-kbn101-db-role-split` resolved to that exact SHA. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains modified but intentionally unstaged/excluded. The only next action is a fresh independent exact-head re-review.
+
+## 2026-07-15 — rc.10 Ultron NO-GO remediation intake
+
+- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-ultron-11f09a1.md` against exact head `11f09a15e43e72afda6a0374668996b4bda9e536`. Documentation only: preserve approved content; no source/config/Compose/CI/deploy/secret/migration edits and no `.mosaic` staging.
+- **Plan:** (1) replace the impossible `NOLOGIN NOSUPERUSER` extension owner with the exact non-login, zero-member `NOLOGIN SUPERUSER` external-control exception and document the non-delegable superuser residual; (2) require the audited external superuser session to `SET ROLE`/`RESET ROLE` for fresh, approved-owner, and shadow extension work, then prove catalog ownership and all service-role denial; (3) assign the active migrate-tier guide exclusively to KBN-101-07, add its active secure route to the -06 inventory/matrix/scanner schema, and freeze `--target-url-file /run/secrets/mosaic_migrate_target_url` plus pre-migrated target/dedicated non-DDL importer requirements; (4) synchronize PRD/shared/tasks/index/sitemap/guide and rc.10 status; (5) validate formatting, links, contracts, source paths, finite operator inventory, diff, review, commit, queue guard, push, and exact remote SHA.
+- **Target-image evidence before edits:** local `pgvector/pgvector:pg17` control file reports `default_version = '0.8.2'`, `relocatable = true`, and no `trusted`/`superuser` override (untrusted PostgreSQL extension). An isolated PostgreSQL 17 container proved a `NOLOGIN SUPERUSER` `mosaic_extension_owner` can create `mosaic_extensions` and `vector` under external-superuser `SET ROLE`, returns to the external session after `RESET ROLE`, has `rolcanlogin=false`, `rolsuper=true`, zero role members, exact extension/schema and owner-bearing-member ownership, and denies `SET ROLE`, `ALTER EXTENSION`, `DROP EXTENSION`, and schema ownership changes to runtime, migrator, schema owner, and data importer. Ownerless PostgreSQL catalog member classes (`pg_am`, `pg_cast`) were intentionally not misrepresented as ownable members.
+- **TDD decision:** skipped as not applicable: this is a documentation-only contract remediation. Future KBN-101-00/-02/-06 tests are specified as the situational evidence; no source/test artifact is permitted in this task.
+- **Final scope correction:** Per control-plane direction, remediation remains bounded to the two Ultron findings. The active guide is explicitly a non-operative KBN-101 contract until its owned implementation/activation lands; no additional design, source, CI, deployment, secret, or test artifact was added.
+- **Validation evidence:** target-image/container role proof PASS (pgvector `0.8.2`, `relocatable=true`, trusted absent/untrusted; external-superuser `SET ROLE`/`RESET ROLE`; exact extension/schema/owner-bearing-member ownership; zero membership and service-role denials). Changed-doc Prettier, strict native-kanban contract TypeScript, local-link resolver (8 docs), finite operator-doc inventory (one active KBN-101-07 route with no credential argv in executable blocks), source-path check (6 current paths), and `git diff --check` PASS. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains intentionally excluded.
+
+## 2026-07-15 — rc.11 exact-head re-review remediation intake
+
+- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview5-f60144e.md` against `f60144eb3eab6234ab01bda592052081c777897e`: target-bind the non-DDL tier importer with a runner-produced signed attestation, and disposition every current non-normative documentation scanner hit, including the active user-guide route and federation historical status. Documentation only; no source/config/Compose/CI/deployment/secret/migration edits and no `.mosaic` staging.
+- **Frozen decision:** `mosaic-db-migrator --verify` is trusted only after TLS/identity/manifest/schema verification and signs a credential-free JCS/Ed25519 v1 artifact from a runner-only fixed root-owned private-key file. The artifact binds secret version/exact URL-file digest, canonical TLS/CA/SPKI/server/database/importer/manifest/schema identity, issued/expiry/nonce, and producer build/correlation; importer gets pinned public key plus artifact only. It validates both files and all bindings before target connection, opens/digests/connects from one in-memory URL read, validates server identity before DML, and distinguishes zero connection from zero DML. Key overlap/revocation, secret-rotation invalidation, replay cache, atomic rename, and sanitized errors are mandatory.
+- **Ownership:** -03 owns producer/signing DTO/tests; -02 importer interface/verification tests; -05 key/artifact mounts/render tests; -06 inventory/matrix and non-masking scanner tests; -07 operator guide. The exact manifests remain disjoint.
+- **Operator correction:** `storage migrate` is schema-wrapper delegation only; legacy `--from hot --to cold` tier-copy guidance is unavailable. Secure tier copy is `migrate-tier` with `--target-url-file` plus `--target-attestation-file`. Federation M1 task language is status-only and adjacent KBN-101 text says it authorizes no current DDL.
+- **TDD decision:** skipped as not applicable: this bounded task changes documentation only. Future -02/-03/-05/-06 tests are specified as the required implementation evidence.
+- **Validation / review:** Prettier PASS on all 18 changed Markdown/root-doc files; `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; changed-doc local-link resolver PASS (71 links); full current docs scanner/disposition PASS (10 non-normative paths, 4 normative-contract paths; no unknown active command); legacy `storage migrate --from` and raw target-URL bypass scan PASS; attestation field/interface assertion PASS; exact source ownership/manifest-overlap assertion PASS; `git diff --check`, docs-only scope, and secret-leak scan PASS. Manual documentation/security review verified key isolation, JCS/detached signature, secret-file hash as non-secret evidence, verification ordering/TOCTOU/replay/rotation, no connection vs zero DML, non-masking scanner class, status-only federation history, and no regression to pgvector closure. No source-code TDD applies.
+- **Delivery evidence:** committed `6227f076c819bd124383851633b16d4ef9c88a98` as `docs(#771): bind tier importer to verified target`; staged scope was 18 documentation files only and excluded `.mosaic`. Pre-push queue guard returned `state=unknown` without failure. Push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`: PASS. Branch push succeeded. Verify the exact remote SHA after this final delivery-evidence append, then idle for independent exact-head re-review and Ultron reverify. `.mosaic/orchestrator/{mission.json,session.lock}` remains pre-existing and excluded.

docs/scratchpads/tess-m4-001-mos-coordination.md

@@ -18,12 +18,12 @@ Implement a transport-neutral coordination contract allowing a configured intera
 
 ## Design checkpoint — 2026-07-12
 
-Created `docs/tess/MOS-COORDINATION.md`. Mos approved the design and selected the native in-process `InMemoryMosCoordinationPort` for M4. Fleet/tmux remains a documented M5 adapter seam; no Mos-side consumer is built in this task.
+Created `docs/tess/MOS-COORDINATION.md`. Mos approved the design and selected the native in-process `InMemoryInteractionCoordinationPort` for M4. Fleet/tmux remains a documented M5 adapter seam; no Mos-side consumer is built in this task.
 
 ## Progress checkpoint — 2026-07-13
 
-- Implemented `MosCoordinationPort` with handoff/observe/result only, an authority-checking client, and deterministic native adapter in `@mosaicstack/coord`.
-- Implemented the gateway `MosCoordinationService`, deriving requester identity from trusted configuration and actor/tenant/correlation from authenticated context.
+- Implemented `InteractionCoordinationPort` with handoff/observe/result only, an authority-checking client, and deterministic native adapter in `@mosaicstack/coord`.
+- Implemented the gateway `InteractionCoordinationService`, deriving requester identity from trusted configuration and actor/tenant/correlation from authenticated context.
 - Added contract and gateway boundary tests for configurable identities, native round-trip, unconfigured requester, self-delegation, target drift, and cross-tenant observe/result denial before adapter invocation.
 - Did not modify `apps/gateway/src/commands/command-authorization.service.ts`.
 

docs/tess/ARCHITECTURE.md

@@ -54,7 +54,7 @@ Termination is fail-closed: a runtime approval verifier consumes a one-time, exa
 
 ### Mos Coordination Boundary
 
-`@mosaicstack/coord` exposes only the transport-neutral `MosCoordinationPort`
+`@mosaicstack/coord` exposes only the transport-neutral `InteractionCoordinationPort`
 verbs `handoff`, `observe`, and `result`. Gateway derives the actor, tenant,
 correlation, and interaction-agent identity from authenticated context plus
 trusted configuration; callers never provide an orchestration target. It

docs/tess/M5-MIGRATION-CUTOVER.md

@@ -6,7 +6,7 @@ This procedure is evidence-bound. It does not authorize a production cutover unt
 2. Query the normalized runtime capability surface, not a Hermes API directly. Confirm the session capabilities required for the operation are advertised.
 3. Query the transitional matrix through `RuntimeProviderService.transitionalCapabilityMatrix` (`apps/gateway/src/agent/runtime-provider-registry.service.ts`). Kanban, skills, memory, tools, and cron must remain `unsupported`; stop rather than route those operations through Hermes.
 4. Route new memory activity through the Mosaic operator-memory plugin path; there is no landed Hermes memory import.
-5. Use `MosCoordinationService` for orchestration handoff. Tess does not take Mos authority.
+5. Use `InteractionCoordinationService` (`apps/gateway/src/coord/interaction-coordination.service.ts`) for orchestration handoff. The interaction agent does not take configured orchestrator authority.
 6. Record the qualification evidence and only then update an external deployment/channel binding through its separately authorized operational process.
 
 No claim here authorizes bulk transcript copying, data-schema migration, or enabling an unsupported transitional capability.

docs/tess/M5-MIGRATION-INVENTORY.md

@@ -7,5 +7,5 @@ Hermes is a reference adapter, not a Mosaic core dependency. `packages/agent/src
 | sessions, hierarchy, streaming, send/attach/terminate | `HermesRuntimeProvider` plus `hermes-runtime-provider.test.ts`                                                                                                             | adapted                |
 | Kanban, skills, memory, tools, cron                   | normalized matrix in `HermesRuntimeProvider.transitionalCapabilityMatrix`; each is `unsupported` and `assertTransitionalCapability` denies before a transport call         | deferred / fail-closed |
 | operator memory                                       | `packages/memory/src/operator-memory-plugin.ts`, constructed by `apps/gateway/src/memory/memory.module.ts` and session-scoped by `apps/gateway/src/agent/agent.service.ts` | native Mosaic path     |
-| orchestration handoff                                 | `apps/gateway/src/coord/mos-coordination.service.ts` retains authenticated handoff/observe/result ownership checks                                                         | native Mosaic path     |
+| orchestration handoff                                 | `InteractionCoordinationService` in `apps/gateway/src/coord/interaction-coordination.service.ts` retains authenticated handoff/observe/result ownership checks             | native Mosaic path     |
 | transcripts, profiles, preferences                    | no Hermes importer/schema mapping landed                                                                                                                                   | no automatic migration |

docs/tess/M5-MIGRATION-ROLLBACK.md

@@ -6,5 +6,5 @@ Rollback is configuration/binding reversal, not a database rollback: no Hermes s
 2. Keep the gateway registration and core contracts unchanged unless a reviewed code rollback is required; `AgentRuntimeProviderRegistry` registration is explicit and non-replacing (`packages/agent/src/runtime-provider-registry.ts`).
 3. Do not replay an unsupported Kanban, skills, memory, tools, or cron operation. The transitional matrix is intentionally fail-closed.
 4. Preserve Mosaic audit, session, and operator-memory records under their normal scoped retention rules; do not copy them into Hermes as a rollback shortcut.
-5. For an in-flight coordination request, use the owned handoff observation/result flow in `MosCoordinationService`; do not create a second orchestrator path.
+5. For an in-flight coordination request, use the owned handoff observation/result flow in `InteractionCoordinationService` (`apps/gateway/src/coord/interaction-coordination.service.ts`); do not create a second orchestrator path.
 6. Capture the binding reversal, affected scope, correlation IDs, and reason in the approved operational record before retrying a cutover.

docs/tess/MOS-COORDINATION.md

@@ -20,29 +20,29 @@ interface CoordinationScope {
   readonly requesterAgentId: string; // trusted gateway/configuration data
 }
 
-interface MosHandoffRequest {
+interface HandoffRequest {
   readonly idempotencyKey: string;
   readonly summary: string;
   readonly context?: string;
   readonly missionId?: string;
 }
 
-interface MosHandoffReceipt {
+interface HandoffReceipt {
   readonly handoffId: string;
   readonly targetAgentId: string;
   readonly status: 'accepted' | 'queued';
   readonly correlationId: string;
 }
 
-interface MosHandoff {
+interface Handoff {
   readonly handoffId: string;
   readonly targetAgentId: string;
-  readonly request: MosHandoffRequest;
+  readonly request: HandoffRequest;
   readonly scope: CoordinationScope;
 }
 
-interface MosCoordinationPort {
-  handoff(handoff: MosHandoff): Promise<MosHandoffReceipt>;
+interface InteractionCoordinationPort {
+  handoff(handoff: Handoff): Promise<HandoffReceipt>;
   observe(handoffId: string, scope: CoordinationScope): Promise<CoordinationObservation>;
   result(handoffId: string, scope: CoordinationScope): Promise<CoordinationResult>;
 }
@@ -58,20 +58,20 @@ and the requester agent from trusted authentication/configuration only.
 
 ## Enforcement point
 
-`apps/gateway` owns a `MosCoordinationService` boundary that compares the
+`apps/gateway` owns an `InteractionCoordinationService` (`apps/gateway/src/coord/interaction-coordination.service.ts`) boundary that compares the
 trusted configured requester/target identities and rejects all of the following
 before calling a transport: unconfigured requester, self-delegation, target
 identity drift, cross-tenant observe/result lookup, and attempts to observe or
 receive a result for a handoff outside the originating tenant. The service exposes handoff, observe,
 and result only, and delegates delivery to an injected adapter.
 
-M4 ships a native in-process `InMemoryMosCoordinationPort` as the concrete,
+M4 ships a native in-process `InMemoryInteractionCoordinationPort` as the concrete,
 deterministic adapter. It preserves the immutable handoff ID, tenant, requester
 identity, and correlation ID while demonstrating the handoff → observe → result
 round trip. It is a queue/port adapter, not a Mos-side consumer.
 
 A future fleet/tmux adapter is a documented M5 deployment seam and must
-implement the same `MosCoordinationPort`; no channel client or interaction
+implement the same `InteractionCoordinationPort`; no channel client or interaction
 runtime calls a transport directly.
 
 ## Required tests

docs/tess/PLUGIN-GUIDE.md

@@ -1,3 +1,28 @@
 # Tess Plugin Authoring
 
 Plugins are replaceable adapters. Declare capabilities, derive scope from trusted context, preserve correlation IDs, redact before persistence/egress, and return unsupported operations as fail-closed results. Names and identities are configuration data, not literals in keys or defaults.
+
+## Official channel adapter contract
+
+Official Discord, Matrix, Slack, and future channel adapters share contracts exported from `@mosaicstack/types` under `channel/`:
+
+- `OfficialChannelAdapter` provides `name`, `start()`, `stop()`, and non-throwing connection `health()`.
+- `ChannelMessageDto` and `ChannelAttachmentDto` normalize transport data with JSON-safe metadata.
+- `ChannelBindingDto` and `ChannelAuthorizedPrincipalDto` normalize configuration-owned logical-agent binding and the already-allowlisted/paired external actor.
+- `ChannelIngressDto` carries operation, correlation, native message ID, authorized principal, normalized message, and stable route into `ChannelIngressPort`.
+- `ChannelConversationRouteDto` binds a configured channel to `logicalAgentId`, stable `conversationId`, authorization parent, and response target.
+- `ChannelEgressDto` and `ChannelEgressPort` separate where a response is delivered from the gateway's runtime/provider selection.
+
+`ChannelConversationRouteDto` deliberately has no harness, provider, model, process, or native runtime-session field. The gateway owns runtime selection, durable enrollment, authorization, audit, and lease/fencing. A channel adapter must not call Claude, Codex, Pi, OpenCode, tmux, or Matrix runtime providers directly. Discord currently preserves its signed Socket.IO compatibility ingress for established gateway authentication/replay/approval controls while normalizing the same ingress DTO; supplied direct ports are the future registration path.
+
+## Adapter requirements
+
+1. Resolve configuration-owned channel and logical-agent bindings before dispatch. A binding may carry a trusted gateway agent-config reference, but the stable route contains only the logical agent; gateway verifies the reference resolves to that agent before runtime selection.
+2. Apply channel-native allowlists and paired-user roles before any external side effect such as thread creation.
+3. Preserve native message ID, correlation ID, channel/thread address, attachments, and response target.
+4. Treat normal channel parents (for example Discord categories) separately from thread parents.
+5. Keep reconnect and conversation identity independent of the active runtime provider.
+6. Report sanitized connection/routing failures without message bodies or credentials.
+7. Pass the shared route/authorization contract suite plus adapter-specific translation tests.
+
+Discord establishes the first policy: authorized untagged messages respond in the configured channel; a mention creates a thread or reuses the thread already attached to that message; existing thread messages stay there. Runtime control commands remain on the current durable session. Matrix and Slack should translate native rooms/threads into the same route and response-target semantics rather than adding transport branches to gateway core.

docs/tess/TASKS.md

@@ -43,3 +43,4 @@
 | TESS-M5-002 | done | Complete migration inventory, cutover, rollback, retention and deprecation evidence | #711 | coder3 | docs/tess | feat/tess-migration-docs | TESS-M4-V | 18K | TESS-MIG-001. **Mos-DISPATCHED to coder3 2026-07-13** ("M4 complete; advancing to M5") — dispatched AHEAD of TESS-M4-V passing; the M4-V-status-vs-#710-CLOSED dependency reconciliation is pending Mos ruling (tracked, not orchestrator-decided). **DELIVERED as PR #742** — 4 new files docs/tess/M5-MIGRATION-{INVENTORY,CUTOVER,ROLLBACK,RETENTION-DEPRECATION}.md, base main b7b0f508, frozen head b5e9d0e528a50aae2e916cc7202bacc2e8db67dd. Docs-only; tracking-control trio (MISSION-MANIFEST/TASKS/VERIFICATION-MATRIX) UNTOUCHED; command-authz byte-identical a9f829e7; no live creds. **CI pipeline 1773 SUCCESS** (repo 47, refs/pull/742/head, commit==head). **Independent non-author ROR COMPLETE: reviewer VERIFIED APPROVE at exact head b5e9d0e528a50aae2e916cc7202bacc2e8db67dd (Gitea comment 17108)** — evidence claims verified to trace to landed Hermes adapter / capability matrix, gateway registry/reachability, operator-memory scope path, Mos coordination boundary; docs do NOT over-claim transcript/profile import, schema migration, unsupported-capability enablement, production cutover, or deprecation completion. Head independently verified UNMOVED at b5e9d0e528a5 post-ROR (live Gitea), base main, mergeable=true. **#742 MERGED by Mos → main 5789711e. Deliverable docs LANDED. GATE: TESS-M4-V/M5-V verification-gate reconciliation remains Mos-owned/pending (this row was dispatched ahead of M4-V passing).** |
 | TESS-M5-003 | done | 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. **DELIVERED as PR #746** (branch feat/tess-docs, base main, 7 docs-only files: docs/openapi-tess.yaml + docs/tess/{ADMIN,DEVELOPER,OPERATIONS,PLUGIN,USER}-GUIDE.md + M5-003-DOCUMENTATION-CHECKLIST.md). 4-round revise-loop (heads 470eb911→c9f69300→7aea94e2→25b9d642) converged: OpenAPI covers interaction routes + SSE /sessions/{sessionId}/stream + Mos coord (/api/coord/mos/handoff,/observe,/result) + memory preferences/insights/search; request-body schemas aligned to real DTOs (Send requires content+idempotencyKey, Stop requires approvalRef, Insight requires only content, MosHandoff body requires idempotencyKey+summary); checklist accurate. **CI pipeline 1786 SUCCESS** (repo 47, refs/pull/746/head, commit==head 25b9d642). **Independent non-author ROR COMPLETE: reviewer VERIFIED APPROVE at exact head 25b9d642b939014b3efd61826e7524cafc6ffc2e (Gitea comment 17170)** — docs-only, tracking-trio untouched, command-authz byte-identical a9f829e7, no false coverage claims. Head verified UNMOVED at 25b9d642 (live Gitea, not worker-reported), base main, mergeable=true. **#746 MERGED by Mos → main bc8016c8314ec3a4b6ebc2fec5d9f276fca3327a. Documentation gate LANDED.** GATE: TESS-M4-V/M5-V verification-gate reconciliation remains Mos-owned/pending. |
 | 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 |
+| MOS-PORT-M1-001 | in-progress | Implement logical Mos identity, PostgreSQL connector lease, monotonic fencing, server-bound execution grants, audit, migrations, concurrency/restart/abuse/integration tests | #755 | codex | packages/types, packages/agent, packages/db, apps/gateway | feat/mos-logical-identity-fencing | — | 38K | Requirements MOS-PORT-ID-001, MOS-PORT-LEASE-001, MOS-PORT-FENCE-001..002, MOS-PORT-OBS-001, MOS-PORT-ARCH-001. One Sol/Pi worker; TDD; PR-open STOP; worker must not edit this ledger. |

docs/tess/THREAT-MODEL.md

@@ -33,14 +33,18 @@ Trust boundaries: Discord→plugin, CLI→gateway, plugin→gateway service iden
 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
+## Closed Prerequisite Findings
 
-- 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.
+The original M1 findings below are closed by landed controls and retained for audit traceability.
 
-These are tracked as M1 security prerequisites and must pass independent security review before Tess ingress is enabled.
+| Former finding                              | Closed evidence                                                                                                                                                                                                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Command scope/role enforcement              | `apps/gateway/src/commands/command-authorization.service.ts` and its authorization tests enforce the server-side approval boundary.                                                                                |
+| Cross-owner session access                  | Gateway session ownership tests cover server-derived owner and tenant scope.                                                                                                                                       |
+| Caller-controlled MCP identity              | MCP tools derive actor and tenant from authenticated gateway context.                                                                                                                                              |
+| Missing Discord ingress allowlists          | `apps/gateway/src/plugin/plugin.module.ts` requires the guild, channel, and user allowlist environment values; `apps/gateway/src/plugin/discord-ingress.security.spec.ts` exercises denial and configured ingress. |
+| Missing redaction before persistence/egress | Gateway and log redaction coverage verifies sensitive content is classified before durable storage or channel delivery.                                                                                            |
+| In-memory-only restart safety               | `packages/agent/src/durable-session.test.ts` reconstructs durable identity, inbox/outbox, checkpoints, and handoffs after simulated restart.                                                                       |
+| Globally scoped session GC                  | `apps/gateway/src/gc/session-gc.service.spec.ts` verifies session-only collection and the absence of automatic global collection entry points.                                                                     |
+
+These controls remain subject to the runtime's independent review and release qualification gates.

docs/tess/USER-GUIDE.md

@@ -1,5 +1,13 @@
 # Tess User Guide
 
+## Discord conversations
+
+In a configured Tess/interaction channel, an authorized untagged message is sent to the bound logical agent and its response appears in the channel. Mention the bot when starting a separate topic: Mosaic reuses a thread already attached to that same Discord message, or creates a new thread for the message, and responds there. Continue in that thread without tagging the bot again. Messages from unconfigured channels or users without an authorized pairing are ignored without creating a thread.
+
+`/approve` and `/stop <approval>` operate on the current channel/thread session and do not open a new thread. The Discord connection is bound to the logical agent conversation, not Claude, Codex, Pi, OpenCode, or another harness; a runtime handoff behind Mosaic does not change where you continue the conversation.
+
+## CLI and HTTP interaction
+
 All HTTP interaction calls require authenticated session credentials and `X-Correlation-Id`. Use `GET /api/interaction/{agentName}/sessions?provider=...` to list only visible runtime sessions, then enroll with `POST .../sessions/{sessionId}/enroll` body `{providerId,runtimeSessionId}`. Attach uses `{mode:"read"}`; send uses `{content,idempotencyKey}`. Stop requires `{approvalRef}` and fails with 403 without the exact durable approval. Recovery only requeues interrupted durable work.
 
 Memory is user-scoped: preferences support list/get/upsert/delete; insights support list/get/create/delete; search body is `{query,limit?,maxDistance?}`. Mos work is handed off with `POST /api/coord/mos/handoff`; observe and result use the returned handoff ID.

docs/tess/qualification/2026-07-14-option2-runtime-portability.md

@@ -0,0 +1,238 @@
+# Tess / Option 2 runtime-portability qualification — 2026-07-14
+
+**Issue context:** #706–#711 and runtime-neutral Mos follow-up #754
+
+**Qualified revision:** `d0771835542d` (`origin/main` at review time)
+
+**Reviewer/runtime:** Independent Pi lane requested as `openai-codex/gpt-5.6-sol:high`
+
+**Runtime resolution note:** Mosaic warned that `gpt-5.6-sol` was not present in the provider model catalog and proceeded with it as a custom model ID. This warning was part of the original qualification log and is material provenance; downstream claims must not treat catalog recognition as verified.
+
+**Verdict:** REQUEST CHANGES
+
+**Evidence type:** Point-in-time qualification; later commits and PR #757 must be reviewed separately
+
+## Purpose and provenance
+
+This report preserves the complete independent qualification that was previously available only in `/tmp/tess-option2-qualification.log`. It distinguishes passing component tests from the missing operational proof required for identity-continuous Mos failover.
+
+No credential values, OAuth tokens, Discord tokens, device codes, or auth-file contents are included. Commands and results are retained so another environment can reproduce or challenge the findings.
+
+---
+
+# 1. Verdict
+
+## **REQUEST CHANGES**
+
+The current Option 2 implementation is a useful portability foundation, but it is **not qualified against AC-TESS-01..11** and is not equivalent to true same-Mos-identity failover.
+
+Primary blockers:
+
+1. **AC-TESS-01/02:** The required `mosaic tess` command does not exist; only `mosaic interaction` is registered (`packages/mosaic/src/commands/interaction.ts:60`). The cross-surface test proves CLI enrollment followed by Discord approval/stop, not bidirectional Discord/CLI chat streaming.
+2. **AC-TESS-04:** Fleet/tmux and Matrix providers are implemented as libraries but are not registered in the production gateway. `AgentModule` registers only Hermes (`apps/gateway/src/agent/agent.module.ts:34`).
+3. **Mos handoff is not operational or durable:** Production uses `InMemoryInteractionCoordinationPort` (`apps/gateway/src/coord/coord.module.ts:18`), with no Mos-side consumer. Restart loses handoff ownership, idempotency, activity, and results.
+4. **AC-TESS-06/10:** Restart tests are good local persistence tests, but no real connector/harness failover or exercised rollback exists. Rollback is documentation-only.
+5. **AC-TESS-08:** The parity suite validates a selected shared intersection using mocked transports. Matrix is not production-wired and tmux drops the runtime message idempotency key before delivery.
+6. **AC-TESS-09:** M5 qualification remains `not-started`; no live Discord, Matrix homeserver, tmux/Mos consumer, Claude Code/Pi/Codex failover, or deployment rollback was tested.
+7. **PR #750 mismatch:** Its description promises send-error coverage as HTTP 400, but both gateway and TUI test use HTTP 403 (`packages/mosaic/src/tui/gateway-api.interaction-errors.test.ts:25-34`).
+
+### AC disposition
+
+| AC  | Result            | Evidence                                                                        |
+| --- | ----------------- | ------------------------------------------------------------------------------- |
+| 01  | **Fail**          | No `mosaic tess`; no bidirectional same-session chat/stream E2E                 |
+| 02  | **Fail**          | Generic CLI exists, but fleet/Matrix providers are unreachable in production    |
+| 03  | Pass              | Pi profile/model/reasoning/effective-policy tests passed                        |
+| 04  | **Fail**          | No registered fleet provider or real Mos consumer                               |
+| 05  | Partial           | Hermes normalization/fail-closed matrix passes; live capability path is limited |
+| 06  | Partial           | PGlite restart/idempotency passes; no actual harness failover                   |
+| 07  | Partial           | Focused denial/replay tests pass; full M5 abuse qualification absent            |
+| 08  | Partial           | Mocked shared-intersection parity passes; Matrix not operationally wired        |
+| 09  | **Fail**          | Baselines/CI green, but required E2E/security/rollback qualification absent     |
+| 10  | **Fail**          | Inventory incomplete/inconsistent; rollback not exercised                       |
+| 11  | Pass/ledger stale | Documentation and sitemap exist; plugin/catalog ledger remains unresolved       |
+
+---
+
+# 2. Exact test commands and results
+
+Initial focused attempts failed before collection because this detached worktree had no dependencies:
+
+```bash
+pnpm --filter @mosaicstack/agent exec vitest run ...
+```
+
+Result: startup failure, `Cannot find module 'vitest/config'`.
+
+Setup used:
+
+```bash
+corepack pnpm --store-dir /home/jarvis/.local/share/pnpm/store/v10 \
+  install --frozen-lockfile --ignore-scripts
+```
+
+Result: PASS, 1,240 packages linked.
+
+```bash
+corepack pnpm turbo run build \
+  --filter='@mosaicstack/gateway^...' \
+  --filter='@mosaicstack/mosaic^...'
+```
+
+Result: **17/17 dependency builds successful**.
+
+### Focused suites
+
+```bash
+corepack pnpm --filter @mosaicstack/agent exec vitest run \
+  src/runtime-provider-parity.test.ts \
+  src/matrix-native-runtime-provider.test.ts \
+  src/tmux-fleet-runtime-provider.test.ts \
+  src/durable-session.test.ts \
+  src/hermes-runtime-provider.test.ts
+```
+
+Result: **5 files, 39/39 tests passed**.
+
+```bash
+corepack pnpm --filter @mosaicstack/gateway exec vitest run \
+  src/agent/durable-session.repository.test.ts \
+  src/__tests__/integration/tess-cross-surface.integration.test.ts \
+  src/plugin/discord-ingress.security.spec.ts \
+  src/coord/interaction-coordination.service.test.ts \
+  src/coord/interaction-coordination.routing.e2e.test.ts \
+  src/agent/hermes-runtime-reachability.e2e.test.ts
+```
+
+Result: **6 files, 36/36 tests passed**. PGlite close/reopen recovery passed in 504 ms.
+
+```bash
+corepack pnpm --filter @mosaicstack/mosaic exec vitest run \
+  src/fleet/matrix-native-runtime-transport.test.ts \
+  src/fleet/tess-service-profile.test.ts \
+  src/commands/interaction.test.ts \
+  src/tui/gateway-api.interaction-errors.test.ts
+```
+
+Result: **4 files, 15/15 tests passed**.
+
+```bash
+corepack pnpm --filter @mosaicstack/coord exec vitest run \
+  src/__tests__/interaction-coordination.test.ts
+```
+
+Result: **1 file, 7/7 tests passed**.
+
+```bash
+corepack pnpm --filter @mosaicstack/gateway exec vitest run \
+  src/agent/interaction.controller.test.ts \
+  src/commands/command-authorization.service.spec.ts \
+  src/agent/__tests__/runtime-provider-registry.service.test.ts
+```
+
+Result: **3 files, 27/27 tests passed**.
+
+Focused total: **124/124 tests passed** after dependency setup.
+
+### Baselines
+
+```bash
+TURBO_FORCE=true corepack pnpm typecheck
+```
+
+Result: **42/42 tasks successful**.
+
+```bash
+TURBO_FORCE=true corepack pnpm lint
+```
+
+Result: **23/23 tasks successful**.
+
+```bash
+corepack pnpm format:check
+```
+
+Result: **PASS — all files matched Prettier style**.
+
+```bash
+~/.config/mosaic/tools/woodpecker/pipeline-status.sh \
+  -r mosaicstack/stack -n 1796
+```
+
+Result: **SUCCESS** at `d0771835542d`; all test, build, sanitization, typecheck, lint, format, and publish steps green.
+
+No tracked files outside the pre-existing `.mosaic/orchestrator/*` launcher changes were modified.
+
+---
+
+# 3. Stale ledger inconsistencies
+
+1. `docs/tess/MISSION-MANIFEST.md` still says:
+   - current milestone M1;
+   - progress 0/5;
+   - M2/M3/M5 not started.
+2. `docs/tess/TASKS.md` says:
+   - M4-V failed;
+   - M4-W-001 and TESS-PLG-001 in progress;
+   - M5-V not started.
+3. Provider issue state conflicts:
+   - #707–#709 remain open although M1–M3 rows are recorded done/pass.
+   - #710 and #711 are closed although M4-V failed and M5-V is not started.
+4. M5 work was marked done despite depending on failed M4-V.
+5. TESS-M3-002 says `mosaic tess` is done, but only `mosaic interaction` exists.
+6. PR #750 removed stale service references from operational docs, but `docs/tess/TASKS.md` still contains `MosCoordinationService` in historical notes.
+7. `docs/tess/MIGRATION-INVENTORY.md` remains an “initial inventory” with several capabilities marked `adapt`; `M5-MIGRATION-INVENTORY.md` marks grouped capabilities deferred/fail-closed. Neither supplies the complete owner/evidence matrix AC-TESS-10 requires.
+8. TESS-M2-FUP-001 remains real: the unkeyed SHA-256 compatibility branch still exists at `durable-session.repository.ts:427-431`.
+9. TESS-PLG-001 claims catalog registration was folded into W-001, but production evidence shows provider registration in the gateway—not a completed `packages/mosaic` plugin catalog.
+
+---
+
+# 4. Gap to true same-Mos-identity failover
+
+Current code can relaunch the same roster name under another runtime and can rebind a durable interaction session to another provider/runtime ID. That is **replacement**, not identity-continuous failover.
+
+Missing pieces:
+
+- No canonical logical Mos identity independent of harness-native session IDs.
+- No exclusive connector lease or monotonic fencing epoch; session rebinding is effectively last-write-wins.
+- No stale-holder rejection preventing the old harness from continuing side effects.
+- No normalized Claude Code/Pi/Codex checkpoint/import/export adapters.
+- No durable Mos coordination transport or Mos consumer.
+- No canonical handoff containing mission/task refs, git state, causal sequence, pending operations, capability requirements, and acknowledgements.
+- No end-to-end receipt journal across connectors.
+- Matrix has deterministic transaction IDs, but tmux delivery discards `RuntimeMessage.idempotencyKey`.
+- No fault-injection test transferring Mos among Claude Code, Pi, and Codex and then rolling back.
+
+---
+
+# 5. Minimal follow-up issue decomposition
+
+| Order | Issue                                       | Minimum acceptance criteria                                                                                                                                                                                                                                          |
+| ----- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1     | **Logical identity and security fencing**   | Server-derived `{tenant, logicalAgentId, connectorId, harness, leaseEpoch, scopes, expiry}`; signed/fenced execution grant; stale/forged/cross-tenant grants denied and audited; no connector credential in handoffs                                                 |
+| 2     | **Durable connector lease**                 | PostgreSQL-backed exclusive lease with CAS, monotonic epoch, TTL/heartbeat, explicit takeover, and gateway rejection of stale holders; connectors for Claude Code, Pi, and Codex                                                                                     |
+| 3     | **Canonical handoff/checkpoint**            | Versioned, sealed schema containing canonical mission/task/git references, checkpoint digest, causal sequence, required capabilities, pending/ambiguous operation references, and source/destination acknowledgement; no raw secrets or mandatory harness transcript |
+| 4     | **Exactly-once connector journal**          | Durable operation IDs and receipts; idempotency propagated through every adapter; Matrix transaction mapping; tmux replaced or wrapped with receiver-side durable dedupe; ambiguous effects remain held for authorized reconciliation                                |
+| 5     | **Cross-harness failover and rollback E2E** | Real Mos identity moves Claude Code → Pi → Codex and back; inject crashes before/after lease transfer, handoff persistence, send, and acknowledgement; stale connector fenced; no duplicate side effects; canonical state preserved; rollback evidence published     |
+| 6     | **Generic gateway research ADR**            | Evaluate LiteLLM subscription OAuth and Bifrost concepts without adding either to core; include terms/security review, credential lifecycle, tenant mapping, budgets, failover semantics, and adapter-only prototype                                                 |
+
+## Generic gateway placement
+
+Allowed topology:
+
+```text
+Discord / CLI / web
+        ↓
+Mosaic Gateway: auth, tenant scope, policy, approvals, audit
+        ↓
+IProviderAdapter / AgentRuntimeProvider
+        ↓
+optional LiteLLM or Bifrost egress proxy
+        ↓
+upstream provider
+```
+
+- **LiteLLM ChatGPT subscription OAuth:** research-only, opt-in, behind an adapter. Subscription credentials require explicit terms, revocation, scope, token-storage, and audit review. They must never become Mosaic identity or core configuration.
+- **Bifrost:** virtual keys are downstream proxy credentials, not Mosaic principals. Budget and failover concepts may inform Mosaic routing, but tenant policy, authorization, and audit remain in Mosaic.
+- Neither product may introduce schemas into Mosaic core, receive direct calls from channels/agents, or bypass `IProviderAdapter`/`AgentRuntimeProvider`.
+- Mosaic should also correct its existing “all providers unhealthy → use one anyway” fallback behavior before adopting more automatic failover (`routing-engine.service.ts:204-212`).

eslint.config.mjs

@@ -28,6 +28,7 @@ export default tseslint.config(
             'apps/web/e2e/helpers/*.ts',
             'apps/web/playwright.config.ts',
             'apps/gateway/vitest.config.ts',
+            'plugins/discord/vitest.config.ts',
             'packages/db/vitest.config.ts',
             'packages/storage/vitest.config.ts',
             'packages/mosaic/vitest.config.ts',

packages/agent/src/connector-lease.test.ts

@@ -0,0 +1,261 @@
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  ConnectorExecutionContext,
+  ConnectorExecutionGrant,
+  ConnectorLease,
+  ConnectorLeaseAuditEvent,
+  ConnectorLeaseStore,
+  FencedConnectorAdapter,
+  LogicalAgentBinding,
+} from '@mosaicstack/types';
+import {
+  ConnectorLeaseCoordinator,
+  MAX_CONNECTOR_GRANT_TTL_MS,
+  MAX_CONNECTOR_LEASE_TTL_MS,
+} from './connector-lease.js';
+import type { ConnectorLeaseError } from './connector-lease.js';
+
+const identity = { tenantId: 'tenant-a', logicalAgentId: 'mos' } as const;
+const binding: LogicalAgentBinding = { identity, bindingId: 'operator-chat' };
+const activeLease: ConnectorLease = {
+  ...binding,
+  leaseId: '00000000-0000-4000-8000-000000000001',
+  connectorId: 'connector-a',
+  scopes: ['runtime.send', 'tool.execute'],
+  leaseEpoch: '3',
+  acquiredAt: '2026-07-14T17:00:00.000Z',
+  heartbeatAt: '2026-07-14T17:00:00.000Z',
+  expiresAt: '2026-07-14T17:10:00.000Z',
+};
+
+class FakeLeaseStore implements ConnectorLeaseStore {
+  lease: ConnectorLease | null = activeLease;
+  readonly audits: ConnectorLeaseAuditEvent[] = [];
+
+  async acquire(): Promise<ConnectorLease> {
+    if (!this.lease) throw new Error('fixture has no lease');
+    return this.lease;
+  }
+
+  async takeover(): Promise<ConnectorLease> {
+    if (!this.lease) throw new Error('fixture has no lease');
+    return this.lease;
+  }
+
+  async heartbeat(): Promise<ConnectorLease> {
+    if (!this.lease) throw new Error('fixture has no lease');
+    return this.lease;
+  }
+
+  async release(): Promise<void> {}
+
+  async findCurrent(): Promise<ConnectorLease | null> {
+    return this.lease;
+  }
+
+  async recordAudit(event: ConnectorLeaseAuditEvent): Promise<void> {
+    this.audits.push(event);
+  }
+}
+
+describe('ConnectorLeaseCoordinator fencing', (): void => {
+  it('validates a server-minted grant immediately before invoking an adapter side effect', async (): Promise<void> => {
+    const store = new FakeLeaseStore();
+    const coordinator = new ConnectorLeaseCoordinator(store, {
+      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
+    });
+    const grant = await coordinator.issueGrant({
+      lease: activeLease,
+      scopes: ['runtime.send'],
+      ttlMs: 30_000,
+      correlationId: 'correlation-1',
+    });
+    const execute = vi.fn(async (_input: string, context: ConnectorExecutionContext) => context);
+    const adapter: FencedConnectorAdapter<string, ConnectorExecutionContext> = { execute };
+
+    const context = await coordinator.executeGrant(grant, 'runtime.send', 'hello', adapter);
+
+    expect(execute).toHaveBeenCalledOnce();
+    expect(context).toMatchObject({
+      identity,
+      bindingId: 'operator-chat',
+      connectorId: 'connector-a',
+      leaseEpoch: '3',
+      scopes: ['runtime.send'],
+    });
+  });
+
+  it('caps grant expiry to the durable current lease instead of submitted metadata', async (): Promise<void> => {
+    const store = new FakeLeaseStore();
+    store.lease = { ...activeLease, expiresAt: '2026-07-14T17:01:05.000Z' };
+    const coordinator = new ConnectorLeaseCoordinator(store, {
+      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
+    });
+
+    const grant = await coordinator.issueGrant({
+      lease: { ...activeLease, expiresAt: '2026-07-14T18:00:00.000Z' },
+      scopes: ['runtime.send'],
+      ttlMs: 30_000,
+      correlationId: 'correlation-durable-expiry',
+    });
+
+    expect(grant.expiresAt).toBe('2026-07-14T17:01:05.000Z');
+  });
+
+  it.each([
+    ['forged clone', (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({ ...grant })],
+    [
+      'cross-tenant clone',
+      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
+        ...grant,
+        identity: { ...grant.identity, tenantId: 'tenant-b' },
+      }),
+    ],
+    [
+      'cross-agent clone',
+      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
+        ...grant,
+        identity: { ...grant.identity, logicalAgentId: 'other-agent' },
+      }),
+    ],
+    [
+      'cross-binding clone',
+      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
+        ...grant,
+        bindingId: 'other-binding',
+      }),
+    ],
+    [
+      'cross-connector clone',
+      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
+        ...grant,
+        connectorId: 'connector-b',
+      }),
+    ],
+  ])('denies and audits a %s before adapter invocation', async (_label, forge): Promise<void> => {
+    const store = new FakeLeaseStore();
+    const coordinator = new ConnectorLeaseCoordinator(store, {
+      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
+    });
+    const grant = await coordinator.issueGrant({
+      lease: activeLease,
+      scopes: ['runtime.send'],
+      ttlMs: 30_000,
+      correlationId: 'correlation-forged',
+    });
+    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
+
+    await expect(
+      coordinator.executeGrant(forge(grant), 'runtime.send', undefined, adapter),
+    ).rejects.toMatchObject({ code: 'forged_grant' } satisfies Partial<ConnectorLeaseError>);
+    expect(adapter.execute).not.toHaveBeenCalled();
+    expect(store.audits.at(-1)).toMatchObject({
+      event: 'reject',
+      outcome: 'denied',
+      reason: 'forged_grant',
+      correlationId: 'correlation-forged',
+    });
+  });
+
+  it('denies malformed forged grants with sanitized audit metadata', async (): Promise<void> => {
+    const store = new FakeLeaseStore();
+    const coordinator = new ConnectorLeaseCoordinator(store, {
+      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
+    });
+    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
+
+    await expect(
+      coordinator.executeGrant(
+        // @ts-expect-error Deliberately exercise malformed runtime input at the trust boundary.
+        {},
+        'runtime.send',
+        undefined,
+        adapter,
+      ),
+    ).rejects.toMatchObject({ code: 'forged_grant' } satisfies Partial<ConnectorLeaseError>);
+    expect(adapter.execute).not.toHaveBeenCalled();
+    expect(store.audits).toContainEqual(
+      expect.objectContaining({
+        identity: { tenantId: 'untrusted', logicalAgentId: 'untrusted' },
+        bindingId: 'untrusted',
+        connectorId: 'untrusted',
+        correlationId: 'untrusted',
+        reason: 'forged_grant',
+      }),
+    );
+  });
+
+  it('rejects lease and grant TTLs above server-side safety caps', async (): Promise<void> => {
+    const store = new FakeLeaseStore();
+    const coordinator = new ConnectorLeaseCoordinator(store, {
+      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
+    });
+    expect(
+      () =>
+        new ConnectorLeaseCoordinator(store, {
+          maxLeaseTtlMs: MAX_CONNECTOR_LEASE_TTL_MS + 1,
+        }),
+    ).toThrow(/no greater than/);
+
+    await expect(
+      coordinator.acquire({
+        identity,
+        bindingId: 'operator-chat',
+        connectorId: 'connector-a',
+        scopes: ['runtime.send'],
+        ttlMs: MAX_CONNECTOR_LEASE_TTL_MS + 1,
+        correlationId: 'correlation-ttl',
+      }),
+    ).rejects.toThrow(/no greater than/);
+    await expect(
+      coordinator.issueGrant({
+        lease: activeLease,
+        scopes: ['runtime.send'],
+        ttlMs: MAX_CONNECTOR_GRANT_TTL_MS + 1,
+        correlationId: 'correlation-ttl',
+      }),
+    ).rejects.toThrow(/no greater than/);
+  });
+
+  it('denies stale epoch, expired grant, and unauthorized scope before side effects', async (): Promise<void> => {
+    let now = new Date('2026-07-14T17:01:00.000Z');
+    const store = new FakeLeaseStore();
+    const coordinator = new ConnectorLeaseCoordinator(store, { now: (): Date => now });
+    const stale = await coordinator.issueGrant({
+      lease: activeLease,
+      scopes: ['runtime.send'],
+      ttlMs: 30_000,
+      correlationId: 'correlation-stale',
+    });
+    store.lease = { ...activeLease, leaseEpoch: '4', connectorId: 'connector-b' };
+    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
+
+    await expect(
+      coordinator.executeGrant(stale, 'runtime.send', undefined, adapter),
+    ).rejects.toMatchObject({ code: 'stale_epoch' } satisfies Partial<ConnectorLeaseError>);
+
+    store.lease = activeLease;
+    const expiring = await coordinator.issueGrant({
+      lease: activeLease,
+      scopes: ['runtime.send'],
+      ttlMs: 1_000,
+      correlationId: 'correlation-expired',
+    });
+    now = new Date('2026-07-14T17:01:02.000Z');
+    await expect(
+      coordinator.executeGrant(expiring, 'runtime.send', undefined, adapter),
+    ).rejects.toMatchObject({ code: 'grant_expired' } satisfies Partial<ConnectorLeaseError>);
+
+    now = new Date('2026-07-14T17:01:00.000Z');
+    const scoped = await coordinator.issueGrant({
+      lease: activeLease,
+      scopes: ['runtime.send'],
+      ttlMs: 30_000,
+      correlationId: 'correlation-scope',
+    });
+    await expect(
+      coordinator.executeGrant(scoped, 'tool.execute', undefined, adapter),
+    ).rejects.toMatchObject({ code: 'scope_denied' } satisfies Partial<ConnectorLeaseError>);
+    expect(adapter.execute).not.toHaveBeenCalled();
+  });
+});

packages/agent/src/connector-lease.ts

@@ -0,0 +1,381 @@
+import { randomUUID } from 'node:crypto';
+import {
+  normalizeConnectorId,
+  normalizeConnectorScope,
+  normalizeConnectorScopes,
+  normalizeCorrelationId,
+  normalizeLeaseEpoch,
+  normalizeLogicalAgentIdentity,
+  normalizeLogicalBindingId,
+  type AcquireConnectorLeaseInput,
+  type ConnectorExecutionContext,
+  type ConnectorExecutionGrant,
+  type ConnectorLease,
+  type ConnectorLeaseAuditEvent,
+  type ConnectorLeaseRejectReason,
+  type ConnectorLeaseStore,
+  type FencedConnectorAdapter,
+  type HeartbeatConnectorLeaseInput,
+  type IssueConnectorExecutionGrantInput,
+  type LogicalAgentBinding,
+  type ReleaseConnectorLeaseInput,
+  type TakeoverConnectorLeaseInput,
+} from '@mosaicstack/types';
+
+export const MAX_CONNECTOR_LEASE_TTL_MS = 5 * 60 * 1000;
+export const MAX_CONNECTOR_GRANT_TTL_MS = 30 * 1000;
+
+export interface ConnectorLeaseCoordinatorOptions {
+  readonly now?: () => Date;
+  readonly maxLeaseTtlMs?: number;
+  readonly maxGrantTtlMs?: number;
+}
+
+export class ConnectorLeaseError extends Error {
+  constructor(
+    readonly code: ConnectorLeaseRejectReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = ConnectorLeaseError.name;
+  }
+}
+
+/**
+ * Runtime-neutral lease coordinator. Durable CAS lives in the store adapter;
+ * grant provenance remains process-local so a restart fails closed and mints
+ * fresh grants from the durable current lease.
+ */
+export class ConnectorLeaseCoordinator {
+  private readonly issuedGrants = new WeakSet<object>();
+  private readonly now: () => Date;
+  private readonly maxLeaseTtlMs: number;
+  private readonly maxGrantTtlMs: number;
+
+  constructor(
+    private readonly store: ConnectorLeaseStore,
+    options: ConnectorLeaseCoordinatorOptions = {},
+  ) {
+    this.now = options.now ?? (() => new Date());
+    this.maxLeaseTtlMs = normalizeTtlLimit(
+      options.maxLeaseTtlMs ?? MAX_CONNECTOR_LEASE_TTL_MS,
+      MAX_CONNECTOR_LEASE_TTL_MS,
+      'lease',
+    );
+    this.maxGrantTtlMs = normalizeTtlLimit(
+      options.maxGrantTtlMs ?? MAX_CONNECTOR_GRANT_TTL_MS,
+      MAX_CONNECTOR_GRANT_TTL_MS,
+      'grant',
+    );
+  }
+
+  async acquire(input: AcquireConnectorLeaseInput): Promise<ConnectorLease> {
+    const command = normalizeAcquireInput(input, this.maxLeaseTtlMs);
+    const now = this.now();
+    return this.store.acquire({
+      ...command,
+      leaseId: randomUUID(),
+      now: now.toISOString(),
+      expiresAt: expiresAt(now, command.ttlMs),
+    });
+  }
+
+  async takeover(input: TakeoverConnectorLeaseInput): Promise<ConnectorLease> {
+    const command = normalizeAcquireInput(input, this.maxLeaseTtlMs);
+    const now = this.now();
+    return this.store.takeover({
+      ...command,
+      expectedEpoch: normalizeLeaseEpoch(input.expectedEpoch),
+      leaseId: randomUUID(),
+      now: now.toISOString(),
+      expiresAt: expiresAt(now, command.ttlMs),
+    });
+  }
+
+  async heartbeat(input: HeartbeatConnectorLeaseInput): Promise<ConnectorLease> {
+    const now = this.now();
+    const lease = normalizeConnectorLease(input.lease);
+    const ttlMs = normalizeTtl(input.ttlMs, this.maxLeaseTtlMs, 'lease');
+    return this.store.heartbeat({
+      lease,
+      ttlMs,
+      correlationId: normalizeCorrelationId(input.correlationId),
+      now: now.toISOString(),
+      expiresAt: expiresAt(now, ttlMs),
+    });
+  }
+
+  async release(input: ReleaseConnectorLeaseInput): Promise<void> {
+    await this.store.release({
+      lease: normalizeConnectorLease(input.lease),
+      correlationId: normalizeCorrelationId(input.correlationId),
+      now: this.now().toISOString(),
+    });
+  }
+
+  async current(binding: LogicalAgentBinding): Promise<ConnectorLease | null> {
+    return this.store.findCurrent(normalizeBinding(binding));
+  }
+
+  async issueGrant(input: IssueConnectorExecutionGrantInput): Promise<ConnectorExecutionGrant> {
+    const now = this.now();
+    const lease = normalizeConnectorLease(input.lease);
+    const scopes = normalizeConnectorScopes(input.scopes);
+    const correlationId = normalizeCorrelationId(input.correlationId);
+    const ttlMs = normalizeTtl(input.ttlMs, this.maxGrantTtlMs, 'grant');
+    const current = await this.store.findCurrent(lease);
+    await this.assertCurrentLease(current, lease, now, correlationId);
+    if (!current) throw new ConnectorLeaseError('lease_missing', 'Connector lease is unavailable');
+    if (!isScopeSubset(scopes, lease.scopes) || !isScopeSubset(scopes, current.scopes)) {
+      await this.reject(lease, correlationId, now, 'scope_denied');
+    }
+    const requestedExpiry = new Date(now.getTime() + ttlMs);
+    const leaseExpiry = new Date(current.expiresAt);
+    const grantExpiry = requestedExpiry < leaseExpiry ? requestedExpiry : leaseExpiry;
+    const grant: ConnectorExecutionGrant = Object.freeze({
+      identity: current.identity,
+      bindingId: current.bindingId,
+      leaseId: current.leaseId,
+      connectorId: current.connectorId,
+      scopes,
+      leaseEpoch: current.leaseEpoch,
+      issuedAt: now.toISOString(),
+      expiresAt: grantExpiry.toISOString(),
+      correlationId,
+    });
+    this.issuedGrants.add(grant);
+    return grant;
+  }
+
+  async executeGrant<TInput, TOutput>(
+    grant: ConnectorExecutionGrant,
+    requiredScope: string,
+    input: TInput,
+    adapter: FencedConnectorAdapter<TInput, TOutput>,
+  ): Promise<TOutput> {
+    const now = this.now();
+    const normalizedScope = normalizeConnectorScope(requiredScope);
+    if (!this.issuedGrants.has(grant)) {
+      await this.rejectForgedGrant(grant, now);
+    }
+    if (new Date(grant.expiresAt) <= now) {
+      await this.rejectGrant(grant, now, 'grant_expired');
+    }
+    const current = await this.store.findCurrent(normalizeBinding(grant));
+    await this.assertCurrentLease(current, grant, now, grant.correlationId);
+    if (!grant.scopes.includes(normalizedScope) || !current?.scopes.includes(normalizedScope)) {
+      await this.rejectGrant(grant, now, 'scope_denied');
+    }
+    if (!current) throw new ConnectorLeaseError('lease_missing', 'Connector lease is unavailable');
+    const context: ConnectorExecutionContext = Object.freeze({
+      identity: current.identity,
+      bindingId: current.bindingId,
+      leaseId: current.leaseId,
+      connectorId: current.connectorId,
+      scopes: Object.freeze([...grant.scopes]),
+      leaseEpoch: current.leaseEpoch,
+      correlationId: grant.correlationId,
+      grantExpiresAt: grant.expiresAt,
+    });
+    return adapter.execute(input, context);
+  }
+
+  private async assertCurrentLease(
+    current: ConnectorLease | null,
+    authority: ConnectorLease | ConnectorExecutionGrant,
+    now: Date,
+    correlationId: string,
+  ): Promise<void> {
+    if (!current) await this.reject(authority, correlationId, now, 'lease_missing');
+    if (!current) throw new ConnectorLeaseError('lease_missing', 'Connector lease is unavailable');
+    if (current.releasedAt) await this.reject(authority, correlationId, now, 'lease_released');
+    if (new Date(current.expiresAt) <= now) {
+      await this.store.recordAudit(auditEvent(current, correlationId, now, 'expiry', 'succeeded'));
+      await this.reject(authority, correlationId, now, 'lease_expired');
+    }
+    if (current.leaseEpoch !== authority.leaseEpoch) {
+      await this.reject(authority, correlationId, now, 'stale_epoch');
+    }
+    if (current.leaseId !== authority.leaseId || current.connectorId !== authority.connectorId) {
+      await this.reject(authority, correlationId, now, 'connector_mismatch');
+    }
+  }
+
+  private async rejectGrant(
+    grant: ConnectorExecutionGrant,
+    now: Date,
+    reason: ConnectorLeaseRejectReason,
+  ): Promise<never> {
+    return this.reject(grant, grant.correlationId, now, reason);
+  }
+
+  private async rejectForgedGrant(grant: unknown, now: Date): Promise<never> {
+    const event = safeForgedGrantAudit(grant, now);
+    await this.store.recordAudit(event);
+    throw new ConnectorLeaseError('forged_grant', safeReasonMessage('forged_grant'));
+  }
+
+  private async reject(
+    authority: LogicalAgentBinding & {
+      readonly connectorId: string;
+      readonly leaseId?: string;
+      readonly leaseEpoch?: string;
+    },
+    correlationId: string,
+    now: Date,
+    reason: ConnectorLeaseRejectReason,
+  ): Promise<never> {
+    await this.store.recordAudit(
+      auditEvent(authority, correlationId, now, 'reject', 'denied', reason),
+    );
+    throw new ConnectorLeaseError(reason, safeReasonMessage(reason));
+  }
+}
+
+function normalizeAcquireInput(
+  input: AcquireConnectorLeaseInput,
+  maxLeaseTtlMs: number,
+): AcquireConnectorLeaseInput {
+  return {
+    identity: normalizeLogicalAgentIdentity(input.identity),
+    bindingId: normalizeLogicalBindingId(input.bindingId),
+    connectorId: normalizeConnectorId(input.connectorId),
+    scopes: normalizeConnectorScopes(input.scopes),
+    ttlMs: normalizeTtl(input.ttlMs, maxLeaseTtlMs, 'lease'),
+    correlationId: normalizeCorrelationId(input.correlationId),
+  };
+}
+
+function normalizeBinding(input: LogicalAgentBinding): LogicalAgentBinding {
+  return {
+    identity: normalizeLogicalAgentIdentity(input.identity),
+    bindingId: normalizeLogicalBindingId(input.bindingId),
+  };
+}
+
+export function normalizeConnectorLease(lease: ConnectorLease): ConnectorLease {
+  const binding = normalizeBinding(lease);
+  return Object.freeze({
+    ...binding,
+    leaseId: lease.leaseId,
+    connectorId: normalizeConnectorId(lease.connectorId),
+    scopes: normalizeConnectorScopes(lease.scopes),
+    leaseEpoch: normalizeLeaseEpoch(lease.leaseEpoch),
+    acquiredAt: normalizeTimestamp(lease.acquiredAt, 'lease acquisition'),
+    heartbeatAt: normalizeTimestamp(lease.heartbeatAt, 'lease heartbeat'),
+    expiresAt: normalizeTimestamp(lease.expiresAt, 'lease expiry'),
+    ...(lease.releasedAt
+      ? { releasedAt: normalizeTimestamp(lease.releasedAt, 'lease release') }
+      : {}),
+  });
+}
+
+function normalizeTtl(ttlMs: number, maximum: number, kind: 'lease' | 'grant'): number {
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > maximum) {
+    throw new Error(
+      `Connector ${kind} TTL must be a positive safe integer no greater than ${maximum}ms`,
+    );
+  }
+  return ttlMs;
+}
+
+function normalizeTtlLimit(ttlMs: number, hardMaximum: number, kind: 'lease' | 'grant'): number {
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > hardMaximum) {
+    throw new Error(
+      `Maximum connector ${kind} TTL must be a positive safe integer no greater than ${hardMaximum}ms`,
+    );
+  }
+  return ttlMs;
+}
+
+function normalizeTimestamp(value: string, label: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error(`${label} timestamp is invalid`);
+  return date.toISOString();
+}
+
+function expiresAt(now: Date, ttlMs: number): string {
+  const expiry = new Date(now.getTime() + ttlMs);
+  if (Number.isNaN(expiry.getTime())) throw new Error('Connector lease TTL exceeds date range');
+  return expiry.toISOString();
+}
+
+function isScopeSubset(requested: readonly string[], allowed: readonly string[]): boolean {
+  return requested.every((scope) => allowed.includes(scope));
+}
+
+function auditEvent(
+  authority: LogicalAgentBinding & {
+    readonly connectorId: string;
+    readonly leaseId?: string;
+    readonly leaseEpoch?: string;
+  },
+  correlationId: string,
+  now: Date,
+  event: ConnectorLeaseAuditEvent['event'],
+  outcome: ConnectorLeaseAuditEvent['outcome'],
+  reason?: ConnectorLeaseRejectReason,
+): ConnectorLeaseAuditEvent {
+  return {
+    identity: authority.identity,
+    bindingId: authority.bindingId,
+    connectorId: authority.connectorId,
+    correlationId,
+    occurredAt: now.toISOString(),
+    event,
+    outcome,
+    ...(authority.leaseId ? { leaseId: authority.leaseId } : {}),
+    ...(authority.leaseEpoch ? { leaseEpoch: authority.leaseEpoch } : {}),
+    ...(reason ? { reason } : {}),
+  };
+}
+
+function safeForgedGrantAudit(grant: unknown, now: Date): ConnectorLeaseAuditEvent {
+  const fallback: ConnectorLeaseAuditEvent = {
+    identity: { tenantId: 'untrusted', logicalAgentId: 'untrusted' },
+    bindingId: 'untrusted',
+    connectorId: 'untrusted',
+    correlationId: 'untrusted',
+    occurredAt: now.toISOString(),
+    event: 'reject',
+    outcome: 'denied',
+    reason: 'forged_grant',
+  };
+  if (typeof grant !== 'object' || grant === null || !('identity' in grant)) return fallback;
+  const identity = grant.identity;
+  if (typeof identity !== 'object' || identity === null) return fallback;
+  if (!('tenantId' in identity) || !('logicalAgentId' in identity)) return fallback;
+  if (!('bindingId' in grant) || !('connectorId' in grant) || !('correlationId' in grant)) {
+    return fallback;
+  }
+  if (
+    typeof identity.tenantId !== 'string' ||
+    typeof identity.logicalAgentId !== 'string' ||
+    typeof grant.bindingId !== 'string' ||
+    typeof grant.connectorId !== 'string' ||
+    typeof grant.correlationId !== 'string'
+  ) {
+    return fallback;
+  }
+  try {
+    return {
+      identity: normalizeLogicalAgentIdentity({
+        tenantId: identity.tenantId,
+        logicalAgentId: identity.logicalAgentId,
+      }),
+      bindingId: normalizeLogicalBindingId(grant.bindingId),
+      connectorId: normalizeConnectorId(grant.connectorId),
+      correlationId: normalizeCorrelationId(grant.correlationId),
+      occurredAt: now.toISOString(),
+      event: 'reject',
+      outcome: 'denied',
+      reason: 'forged_grant',
+    };
+  } catch {
+    return fallback;
+  }
+}
+
+function safeReasonMessage(reason: ConnectorLeaseRejectReason): string {
+  return `Connector authority denied: ${reason}`;
+}

packages/agent/src/index.ts

@@ -5,3 +5,4 @@ export * from './tmux-fleet-runtime-provider.js';
 export * from './hermes-runtime-provider.js';
 export * from './matrix-native-runtime-provider.js';
 export * from './durable-session.js';
+export * from './connector-lease.js';

packages/db/drizzle/0016_salty_morlocks.sql

@@ -0,0 +1,36 @@
+CREATE TABLE "connector_lease_audit_log" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"tenant_id" text NOT NULL,
+	"logical_agent_id" text NOT NULL,
+	"binding_id" text NOT NULL,
+	"connector_id" text NOT NULL,
+	"lease_id" uuid,
+	"lease_epoch" bigint,
+	"event" text NOT NULL,
+	"outcome" text NOT NULL,
+	"reason" text,
+	"correlation_id" text NOT NULL,
+	"occurred_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "logical_agent_connector_leases" (
+	"lease_id" uuid PRIMARY KEY NOT NULL,
+	"tenant_id" text NOT NULL,
+	"logical_agent_id" text NOT NULL,
+	"binding_id" text NOT NULL,
+	"connector_id" text NOT NULL,
+	"scopes" jsonb NOT NULL,
+	"lease_epoch" bigint NOT NULL,
+	"acquired_at" timestamp with time zone NOT NULL,
+	"heartbeat_at" timestamp with time zone NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"released_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "connector_lease_audit_binding_occurred_idx" ON "connector_lease_audit_log" USING btree ("tenant_id","logical_agent_id","binding_id","occurred_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "connector_lease_audit_correlation_idx" ON "connector_lease_audit_log" USING btree ("correlation_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "logical_agent_connector_lease_binding_idx" ON "logical_agent_connector_leases" USING btree ("tenant_id","logical_agent_id","binding_id");--> statement-breakpoint
+CREATE INDEX "logical_agent_connector_lease_expiry_idx" ON "logical_agent_connector_leases" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "logical_agent_connector_lease_connector_idx" ON "logical_agent_connector_leases" USING btree ("connector_id");

packages/db/drizzle/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1783942610000,
       "tag": "0015_interaction_checkpoint_payload_digest",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1784050648841,
+      "tag": "0016_salty_morlocks",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -15,6 +15,7 @@ import {
   uniqueIndex,
   real,
   integer,
+  bigint,
   customType,
 } from 'drizzle-orm/pg-core';
 
@@ -487,6 +488,68 @@ export const agentLogs = pgTable(
   ],
 );
 
+// ─── Logical agent connector authority ──────────────────────────────────────
+// One durable row is the current authority for a tenant/logical-agent/binding.
+// Runtime-native session identifiers never enter these core tables.
+
+export const logicalAgentConnectorLeases = pgTable(
+  'logical_agent_connector_leases',
+  {
+    leaseId: uuid('lease_id').primaryKey(),
+    tenantId: text('tenant_id').notNull(),
+    logicalAgentId: text('logical_agent_id').notNull(),
+    bindingId: text('binding_id').notNull(),
+    connectorId: text('connector_id').notNull(),
+    scopes: jsonb('scopes').notNull().$type<string[]>(),
+    leaseEpoch: bigint('lease_epoch', { mode: 'bigint' }).notNull(),
+    acquiredAt: timestamp('acquired_at', { withTimezone: true }).notNull(),
+    heartbeatAt: timestamp('heartbeat_at', { withTimezone: true }).notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    releasedAt: timestamp('released_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('logical_agent_connector_lease_binding_idx').on(
+      t.tenantId,
+      t.logicalAgentId,
+      t.bindingId,
+    ),
+    index('logical_agent_connector_lease_expiry_idx').on(t.expiresAt),
+    index('logical_agent_connector_lease_connector_idx').on(t.connectorId),
+  ],
+);
+
+/** Append-only, credential-safe lease lifecycle and fencing denial metadata. */
+export const connectorLeaseAuditLog = pgTable(
+  'connector_lease_audit_log',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    tenantId: text('tenant_id').notNull(),
+    logicalAgentId: text('logical_agent_id').notNull(),
+    bindingId: text('binding_id').notNull(),
+    connectorId: text('connector_id').notNull(),
+    leaseId: uuid('lease_id'),
+    leaseEpoch: bigint('lease_epoch', { mode: 'bigint' }),
+    event: text('event', {
+      enum: ['acquire', 'renew', 'takeover', 'reject', 'release', 'expiry'],
+    }).notNull(),
+    outcome: text('outcome', { enum: ['succeeded', 'denied'] }).notNull(),
+    reason: text('reason'),
+    correlationId: text('correlation_id').notNull(),
+    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull(),
+  },
+  (t) => [
+    index('connector_lease_audit_binding_occurred_idx').on(
+      t.tenantId,
+      t.logicalAgentId,
+      t.bindingId,
+      t.occurredAt.desc(),
+    ),
+    index('connector_lease_audit_correlation_idx').on(t.correlationId),
+  ],
+);
+
 // ─── 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.

packages/mosaic/framework/fleet/roles/LIBRARY.md

@@ -12,19 +12,22 @@ on demand. Engineering personas have no explicit `domain:` marker (they are the
 implicit `engineering` domain); cross-domain personas carry a `domain:` key in
 their intro so tooling can group them.
 
-> This file is an index only — no code imports it. To add a persona, drop a new
-> `*.md` next to the others (mirroring the existing structure) and add a row here.
+> This file is an index, not an authority source. The fleet persona resolver reads
+> its rows for discovery compatibility, then requires a readable `*.md` contract;
+> authority is derived from canonical class metadata in code, never from this prose.
 
 ## engineering
 
 | Persona         | Purpose                                                                        |
 | --------------- | ------------------------------------------------------------------------------ |
 | orchestrator    | Always-on coordinator — runs the supervisor loop, dispatches ready work        |
+| team-leader     | Coordinates only orchestrator-leased capacity for one bounded project          |
 | board           | Multi-lens deliberation panel; owns the mission's direction, not its execution |
 | planner         | Turns ratified objectives into a phased FR plan wired into a `depends_on` DAG  |
 | decomposition   | Splits FRs into one-PR-each cards wired with `depends_on` edges                |
 | code            | Primary executor — one card, one branch, one PR to green CI                    |
 | review          | Correctness reviewer — judges an open PR on correctness, scope, and coverage   |
+| validator       | Independent final evidence certificate; never approves-to-land or merges       |
 | security-review | Second line of review — secrets, auth, and forbidden-path safety               |
 | site-tester     | Runtime verifier — runs the change and checks behavior vs. acceptance criteria |
 | documentation   | Prose maintainer — keeps human-facing docs and projections in sync             |
@@ -33,6 +36,7 @@ their intro so tooling can group them.
 | operator        | Escalation and control surface — owns exceptions and the fleet pause switch    |
 | session-review  | Post-task retrospective — turns finished work into improvement signals         |
 | enhancer        | Continuous-improvement loop — upgrades the fleet's tools, skills, and harness  |
+| interaction     | Operator request/status surface; routes orchestration and merge decisions      |
 
 ## executive
 

packages/mosaic/framework/fleet/roles/interaction.md

@@ -0,0 +1,16 @@
+# Interaction — fleet role definition
+
+The **interaction** role (`class: interaction`) is the operator-facing request and status surface for Mosaic.
+
+## Mandate
+
+1. Receive operator requests and present observable fleet or runtime status.
+2. Route orchestration requests to the orchestrator and merge decisions to the merge-gate.
+3. Report supported actions and their outcomes without claiming another role's authority.
+
+## Boundaries
+
+- Request/status only; it does not orchestrate, issue leases, approve-to-land, or merge.
+- It does not mutate roster configuration, role authority, or credentials.
+- A configured instance name such as Tess is display data, never a class or authority source.
+- `operator-interaction` remains a compatibility alias for this canonical class.

packages/mosaic/framework/fleet/roles/team-leader.md

@@ -0,0 +1,16 @@
+# Team leader — fleet role definition
+
+The **team-leader** (`class: team-leader`) coordinates a bounded project team using only capacity granted by an orchestrator-issued lease.
+
+## Mandate
+
+1. Direct the leased coder, reviewer, and validator capacity for the assigned project scope.
+2. Track delivery status and return results or blockers to the orchestrator.
+3. Stop using capacity when the lease or assignment ends.
+
+## Boundaries
+
+- Leased capacity only; this role does not issue or expand its own lease.
+- It cannot change fleet roster membership, role authority, fleet configuration, or credentials.
+- It cannot approve-to-land or merge.
+- It does not displace the orchestrator's topology and lease authority.

packages/mosaic/framework/fleet/roles/validator.md

@@ -0,0 +1,16 @@
+# Validator — fleet role definition
+
+The **validator** (`class: validator`) is the independent final evidence seat. It examines the accepted requirements, test evidence, review record, and candidate head and may issue a validation certificate for that exact evidence set.
+
+## Mandate
+
+1. Validate acceptance evidence independently from the implementation author.
+2. Issue or withhold a final validation certificate for the reviewed candidate.
+3. Report missing, stale, or contradictory evidence without altering it.
+
+## Boundaries
+
+- **Certificate only:** the validator does not approve-to-land or merge.
+- It does not replace correctness or security review.
+- It does not write product code, mutate the roster, issue leases, or access credentials.
+- A configured instance name such as Ultron is display data, never a class or authority source.

packages/mosaic/src/commands/fleet-personas.spec.ts

@@ -1,13 +1,18 @@
-import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { cp, mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import {
+  authorityForCanonicalClass,
+  canonicalizeRoleClass,
   extractClassesFromDir,
+  extractClassesFromDirSync,
   listPersonaClasses,
   personaStatus,
   resolvePersona,
+  resolvePersonaFrom,
+  resolvePersonaSync,
 } from './fleet-personas.js';
 import { loadProfiles, validateProfile, type FleetProfile } from './fleet-profiles.js';
 
@@ -54,13 +59,156 @@ afterEach(async () => {
   await rm(tmp, { recursive: true, force: true });
 });
 
+describe('FCM class canonicalization and authority', () => {
+  it.each([
+    ['implementer', 'code'],
+    ['reviewer', 'review'],
+    ['operator-interaction', 'interaction'],
+  ])('canonicalizes the approved alias %s to %s', (requested: string, canonical: string) => {
+    expect(canonicalizeRoleClass(requested)).toEqual({
+      requestedClass: requested,
+      canonicalClass: canonical,
+    });
+  });
+
+  it.each(['worker', 'analyst', 'canary', 'tess', 'ultron', 'constructor'])(
+    'does not infer an alias for %s',
+    (requested: string) => {
+      expect(canonicalizeRoleClass(requested)).toEqual({
+        requestedClass: requested,
+        canonicalClass: requested,
+      });
+    },
+  );
+
+  it('resolves inherited-property class names without granting protected authority', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'constructor.md'),
+      overridePersona('constructor', 'custom'),
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('constructor', { rolesDir, overrideDir });
+    expect(resolved).toMatchObject({
+      requestedClass: 'constructor',
+      canonicalClass: 'constructor',
+      klass: 'constructor',
+      layer: 'override',
+    });
+    expect(authorityForCanonicalClass('constructor')).toMatchObject({
+      mayMerge: false,
+      mayIssueValidationCertificate: false,
+      mayOrchestrate: false,
+    });
+  });
+
+  it('canonicalizes before override lookup and lets the canonical override win', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'implementer.md'),
+      overridePersona('implementer', 'legacy'),
+      'utf8',
+    );
+    await writeFile(
+      join(overrideDir, 'code.md'),
+      overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('implementer', { rolesDir, overrideDir });
+    expect(resolved).toMatchObject({
+      requestedClass: 'implementer',
+      canonicalClass: 'code',
+      klass: 'code',
+      layer: 'override',
+    });
+    expect(resolved?.content).toContain('CANONICAL-OVERRIDE');
+    expect(resolved?.content).not.toContain('legacy');
+  });
+
+  it('keeps sync and async resolution equivalent for aliases and canonical overrides', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'code.md'),
+      overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
+      'utf8',
+    );
+
+    const asyncResolution = await resolvePersona('implementer', { rolesDir, overrideDir });
+    const syncResolution = resolvePersonaSync('implementer', { rolesDir, overrideDir });
+    expect(syncResolution).toEqual(asyncResolution);
+  });
+
+  it('derives immutable protected authority only from the canonical class', () => {
+    expect(authorityForCanonicalClass('merge-gate')).toMatchObject({ mayMerge: true });
+    for (const klass of [
+      'validator',
+      'orchestrator',
+      'team-leader',
+      'interaction',
+      'code',
+      'custom-role',
+    ]) {
+      expect(authorityForCanonicalClass(klass).mayMerge).toBe(false);
+    }
+    expect(authorityForCanonicalClass('validator')).toMatchObject({
+      mayIssueValidationCertificate: true,
+      mayMerge: false,
+    });
+    expect(authorityForCanonicalClass('orchestrator')).toMatchObject({
+      mayOrchestrate: true,
+      mayIssueLeases: true,
+      mayMerge: false,
+    });
+    expect(authorityForCanonicalClass('team-leader')).toMatchObject({
+      leasedCapacityOnly: true,
+      mayMutateRoster: false,
+      mayAccessCredentials: false,
+      mayMerge: false,
+    });
+    expect(authorityForCanonicalClass('interaction')).toMatchObject({
+      requestStatusOnly: true,
+      mayOrchestrate: false,
+      mayMerge: false,
+    });
+    expect(Object.isFrozen(authorityForCanonicalClass('merge-gate'))).toBe(true);
+  });
+});
+
+describe('required FCM role library', () => {
+  it.each([
+    'code',
+    'review',
+    'validator',
+    'orchestrator',
+    'team-leader',
+    'enhancer',
+    'interaction',
+    'merge-gate',
+  ])('resolves %s through the real framework role library', async (klass: string) => {
+    const resolved = await resolvePersona(klass, {
+      rolesDir: realRolesDir,
+      overrideDir: join(tmp, 'none'),
+    });
+    expect(resolved).not.toBeNull();
+    expect(resolved?.canonicalClass).toBe(klass);
+    expect(resolved?.content.trim()).not.toBe('');
+  });
+});
+
 describe('extractClassesFromDir (shared extraction)', () => {
-  it('records class + domain from inline markers and degrades on missing dir', async () => {
+  it('records class + domain and distinguishes scanned from missing directories', async () => {
     const base = await extractClassesFromDir(rolesDir);
+    expect(base.scanState).toBe('scanned');
     expect(base.classes.has('ceo')).toBe(true);
     expect(base.byClass.get('ceo')?.domain).toBe('executive');
-    const missing = await extractClassesFromDir(join(tmp, 'nope'));
+
+    const missingDir = join(tmp, 'nope');
+    const missing = await extractClassesFromDir(missingDir);
+    expect(missing.scanState).toBe('missing');
     expect(missing.classes.size).toBe(0);
+    expect(extractClassesFromDirSync(missingDir).scanState).toBe('missing');
   });
 });
 
@@ -81,6 +229,287 @@ describe('resolvePersona — override wins', () => {
     expect(resolved?.content).toContain('BASELINE');
   });
 
+  it('does not let a LIBRARY-only row shadow a readable baseline persona', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'LIBRARY.md'),
+      '| Persona | Purpose |\n| --- | --- |\n| code | Index only |\n',
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('code', { rolesDir, overrideDir });
+    expect(resolved?.layer).toBe('baseline');
+    expect(resolved?.content).toContain('BASELINE');
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
+        ?.status,
+    ).toBe('baseline');
+  });
+
+  it('does not let an incidental later class marker shadow a readable baseline persona', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'mascot.md'),
+      '# mascot\n\n(`class: mascot`)\n\nSee also (`class: code`).\n',
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('code', { rolesDir, overrideDir });
+    expect(resolved?.layer).toBe('baseline');
+    expect(resolved?.content).toContain('BASELINE');
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('mascot')).toBe(true);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
+        ?.status,
+    ).toBe('baseline');
+  });
+
+  it('does not advertise an incidental-only class through listing or status APIs', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'mascot.md'),
+      '# mascot\n\n(`class: mascot`)\n\nSee also (`class: phantom`).\n',
+      'utf8',
+    );
+
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('phantom')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'phantom'),
+    ).toBe(false);
+  });
+
+  it('rejects a canonical filename whose explicit marker names another class', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(join(overrideDir, 'merge-gate.md'), overridePersona('mascot', 'fun'), 'utf8');
+    await writeFile(
+      join(rolesDir, 'merge-gate.md'),
+      baselinePersona('merge-gate', 'governance'),
+      'utf8',
+    );
+
+    expect(await resolvePersona('merge-gate', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('merge-gate', { rolesDir, overrideDir })).toBeNull();
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('merge-gate')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'merge-gate'),
+    ).toBe(false);
+  });
+
+  it('fails closed if a marker-defined override becomes unreadable after extraction', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const overrideFile = join(overrideDir, 'engineering.md');
+    await writeFile(overrideFile, overridePersona('code', 'engineering'), 'utf8');
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    await rm(overrideFile);
+    await mkdir(overrideFile);
+
+    expect(await resolvePersonaFrom('code', { rolesDir, overrideDir, base, over })).toBeNull();
+  });
+
+  it('fails closed if a marker-defined override changes identity after extraction', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const overrideFile = join(overrideDir, 'engineering.md');
+    await writeFile(overrideFile, overridePersona('code', 'engineering'), 'utf8');
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    await writeFile(overrideFile, overridePersona('mascot', 'fun'), 'utf8');
+
+    expect(await resolvePersonaFrom('code', { rolesDir, overrideDir, base, over })).toBeNull();
+
+    const classes = await listPersonaClasses({ rolesDir, overrideDir });
+    expect(classes.has('code')).toBe(true);
+    expect(classes.has('mascot')).toBe(true);
+    const status = new Map(
+      (await personaStatus({ rolesDir, overrideDir })).map((entry) => [entry.klass, entry]),
+    );
+    expect(status.get('code')?.status).toBe('baseline');
+    expect(status.get('mascot')?.status).toBe('custom');
+  });
+
+  it('fails closed if a markerless cached override gains a conflicting marker', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const overrideFile = join(overrideDir, 'merge-gate.md');
+    await writeFile(overrideFile, '# markerless merge gate\n', 'utf8');
+    await writeFile(
+      join(rolesDir, 'merge-gate.md'),
+      baselinePersona('merge-gate', 'governance'),
+      'utf8',
+    );
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    await writeFile(overrideFile, overridePersona('mascot', 'fun'), 'utf8');
+
+    expect(
+      await resolvePersonaFrom('merge-gate', { rolesDir, overrideDir, base, over }),
+    ).toBeNull();
+  });
+
+  it('fails closed asynchronously when the override directory cannot be scanned', async () => {
+    await writeFile(overrideDir, 'not a directory', 'utf8');
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('fails closed synchronously when the override directory cannot be scanned', async () => {
+    await writeFile(overrideDir, 'not a directory', 'utf8');
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('fails closed asynchronously and synchronously for a dangling override-directory symlink', async () => {
+    await symlink(join(tmp, 'missing-override-target'), overrideDir, 'dir');
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('fails closed asynchronously and synchronously when an override ancestor is a dangling symlink', async () => {
+    const danglingAncestor = join(tmp, 'dangling-ancestor');
+    await symlink(join(tmp, 'missing-ancestor-target'), danglingAncestor, 'dir');
+    overrideDir = join(danglingAncestor, 'nested', 'roles.local');
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('fails closed when dot-dot traversal crosses a dangling override ancestor', async () => {
+    const danglingAncestor = join(tmp, 'dangling-dotdot-ancestor');
+    await symlink(join(tmp, 'missing-dotdot-target'), danglingAncestor, 'dir');
+    overrideDir = `${danglingAncestor}/../roles.local`;
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('fails closed when relative dot-dot traversal crosses a dangling override ancestor', async () => {
+    const danglingAncestor = join(tmp, 'relative-dangling-ancestor');
+    await symlink(join(tmp, 'missing-relative-target'), danglingAncestor, 'dir');
+    overrideDir = `${relative(process.cwd(), danglingAncestor)}/../roles.local`;
+    expect(overrideDir.startsWith('/')).toBe(false);
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('revalidates a cached missing override before baseline fallback', async () => {
+    const cachedOverrideDir = join(tmp, 'mutable-ancestor', 'roles.local');
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(cachedOverrideDir),
+    ]);
+    expect(over.scanState).toBe('missing');
+    await symlink(join(tmp, 'missing-mutable-target'), join(tmp, 'mutable-ancestor'), 'dir');
+
+    expect(
+      await resolvePersonaFrom('code', {
+        rolesDir,
+        overrideDir: cachedOverrideDir,
+        base,
+        over,
+      }),
+    ).toBeNull();
+  });
+
+  it('revalidates a cached scanned override before baseline fallback', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    expect(over.scanState).toBe('scanned');
+    expect(over.classes.size).toBe(0);
+
+    await writeFile(join(overrideDir, 'engineering.md'), overridePersona('code', 'engineering'));
+
+    const resolved = await resolvePersonaFrom('code', {
+      rolesDir,
+      overrideDir,
+      base,
+      over,
+    });
+    expect(resolved?.layer).toBe('override');
+    expect(resolved?.file).toBe(join(overrideDir, 'engineering.md'));
+  });
+
+  it('falls back to baseline asynchronously and synchronously when override directory is missing', async () => {
+    const asyncResolution = await resolvePersona('code', { rolesDir, overrideDir });
+    const syncResolution = resolvePersonaSync('code', { rolesDir, overrideDir });
+    expect(asyncResolution?.layer).toBe('baseline');
+    expect(syncResolution?.layer).toBe('baseline');
+  });
+
+  it('fails closed asynchronously when the canonical override exists but is unreadable', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'code.md'));
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('does not advertise a shadowed baseline whose canonical override is unreadable', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'code.md'));
+
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'code'),
+    ).toBe(false);
+  });
+
+  it('does not advertise baseline personas when the override directory is unscannable', async () => {
+    await writeFile(overrideDir, 'not a directory', 'utf8');
+
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('does not advertise baseline personas through a dangling override-directory symlink', async () => {
+    await symlink(join(tmp, 'missing-override-target'), overrideDir, 'dir');
+
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('preserves baseline listings when the override directory is missing', async () => {
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
+        ?.status,
+    ).toBe('baseline');
+  });
+
+  it('does not advertise an unreadable custom override as a valid persona class or status', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'ghost.md'));
+
+    const extracted = await extractClassesFromDir(overrideDir);
+    expect(extracted.fileStems.has('ghost')).toBe(true);
+    expect(extracted.classes.has('ghost')).toBe(false);
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('ghost')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'ghost'),
+    ).toBe(false);
+  });
+
+  it('fails closed synchronously when the canonical override exists but is unreadable', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'code.md'));
+
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
   it('returns null for an unknown class', async () => {
     expect(await resolvePersona('does-not-exist', { rolesDir, overrideDir })).toBeNull();
   });

packages/mosaic/src/commands/fleet-personas.ts

@@ -25,10 +25,10 @@
  * can reference a customized or user-added persona.
  */
 
-import { readFileSync, readdirSync } from 'node:fs';
-import { readFile, readdir } from 'node:fs/promises';
+import { lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { lstat, readFile, readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
+import { basename, isAbsolute, join, sep } from 'node:path';
 import type { Command } from 'commander';
 
 function defaultMosaicHome(): string {
@@ -53,52 +53,136 @@ export function defaultOverrideDir(mosaicHome = defaultMosaicHome()): string {
 const CLASS_MARKER = /`?class:\s*\n?\s*([a-z][a-z0-9-]*)`?/g;
 /** Optional `domain: Y` marker that travels alongside the class in the prose. */
 const DOMAIN_MARKER = /`?domain:\s*\n?\s*([a-z][a-z0-9-]*)`?/;
-/** LIBRARY.md persona rows: the first table cell is the persona name. */
-const LIBRARY_ROW = /^\|\s*([a-z][a-z0-9-]*)\s*\|/gm;
 
 /** Where a resolved persona's definition came from. */
 export type PersonaLayer = 'baseline' | 'override';
 
+export const ROLE_CLASS_ALIASES = Object.freeze({
+  implementer: 'code',
+  reviewer: 'review',
+  'operator-interaction': 'interaction',
+} as const);
+
+export interface CanonicalRoleClass {
+  readonly requestedClass: string;
+  readonly canonicalClass: string;
+}
+
+/** Canonicalize only the three explicitly approved compatibility aliases. */
+export function canonicalizeRoleClass(requestedClass: string): CanonicalRoleClass {
+  const requested = requestedClass.trim();
+  const canonical = Object.hasOwn(ROLE_CLASS_ALIASES, requested)
+    ? ROLE_CLASS_ALIASES[requested as keyof typeof ROLE_CLASS_ALIASES]
+    : requested;
+  return Object.freeze({ requestedClass: requested, canonicalClass: canonical });
+}
+
+export interface RoleAuthority {
+  readonly mayMerge: boolean;
+  readonly mayIssueValidationCertificate: boolean;
+  readonly mayOrchestrate: boolean;
+  readonly mayManageTopology: boolean;
+  readonly mayIssueLeases: boolean;
+  readonly leasedCapacityOnly: boolean;
+  readonly requestStatusOnly: boolean;
+  readonly mayMutateRoster: boolean;
+  readonly mayMutateConfiguration: boolean;
+  readonly mayAccessCredentials: boolean;
+}
+
+const NO_PROTECTED_AUTHORITY: RoleAuthority = Object.freeze({
+  mayMerge: false,
+  mayIssueValidationCertificate: false,
+  mayOrchestrate: false,
+  mayManageTopology: false,
+  mayIssueLeases: false,
+  leasedCapacityOnly: false,
+  requestStatusOnly: false,
+  mayMutateRoster: false,
+  mayMutateConfiguration: false,
+  mayAccessCredentials: false,
+});
+
+/** Immutable authority contracts keyed only by canonical class identity. */
+export const ROLE_AUTHORITY_BY_CANONICAL_CLASS: Readonly<Record<string, RoleAuthority>> =
+  Object.freeze({
+    'merge-gate': Object.freeze({ ...NO_PROTECTED_AUTHORITY, mayMerge: true }),
+    validator: Object.freeze({
+      ...NO_PROTECTED_AUTHORITY,
+      mayIssueValidationCertificate: true,
+    }),
+    orchestrator: Object.freeze({
+      ...NO_PROTECTED_AUTHORITY,
+      mayOrchestrate: true,
+      mayManageTopology: true,
+      mayIssueLeases: true,
+    }),
+    'team-leader': Object.freeze({ ...NO_PROTECTED_AUTHORITY, leasedCapacityOnly: true }),
+    interaction: Object.freeze({ ...NO_PROTECTED_AUTHORITY, requestStatusOnly: true }),
+  });
+
+/** Return protected authority for an already-canonical class; custom classes get none. */
+export function authorityForCanonicalClass(canonicalClass: string): RoleAuthority {
+  return Object.hasOwn(ROLE_AUTHORITY_BY_CANONICAL_CLASS, canonicalClass)
+    ? ROLE_AUTHORITY_BY_CANONICAL_CLASS[canonicalClass]!
+    : NO_PROTECTED_AUTHORITY;
+}
+
 /** One discovered persona file (a single role contract on disk). */
 export interface PersonaFile {
   klass: string;
   /** The markdown file the class was found in. */
   file: string;
+  /** True when the first class marker, rather than filename, defined this mapping. */
+  markerDefined?: boolean;
   domain?: string;
 }
 
+export type DirScanState = 'scanned' | 'missing' | 'error';
+
 /** The set of persona classes a directory of role contracts defines. */
 export interface DirClasses {
-  /** Every class name the dir contributes (markers + filenames + LIBRARY rows). */
+  /** Whether the directory was scanned, absent, or present-but-unscannable. */
+  scanState: DirScanState;
+  /** Every readable class name the directory contributes by filename or first marker. */
   classes: Set<string>;
+  /** Filename stems present on disk, retained even when a markdown entry is unreadable. */
+  fileStems: Set<string>;
   /** For classes whose file carries a marker, the file + domain that defined it. */
   byClass: Map<string, PersonaFile>;
 }
 
 /**
- * Scan one directory of role contracts and extract the persona classes it
- * defines. THIS is the shared extraction both fleet-personas and fleet-profiles
- * rely on. Sources, unioned (each needed — see module doc):
- *   1. inline `class: X` markers in roles/*.md (primary; may wrap a newline),
- *   2. persona-name cells from LIBRARY.md index tables,
- *   3. the role filename stem (covers marker-less alias docs like planner).
+ * Scan one directory of role contracts and extract readable persona identities.
+ * Valid identities come only from a successfully read non-LIBRARY filename and
+ * that file's first `class:` marker. LIBRARY rows and later prose mentions are
+ * index/reference data, not independently readable role contracts.
  *
- * Missing dir / unreadable files degrade gracefully to whatever was found.
- * `byClass` records the defining file+domain for marker-bearing classes so the
- * resolver can map a class back to its file; filename-only and LIBRARY-only
- * classes still appear in `classes` for membership checks.
+ * Missing directories are distinguished from present-but-unscannable paths.
+ * `byClass` records the first marker-defined file+domain so the resolver can map
+ * a class back to its contract; marker-less readable files map by filename.
  */
 export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
-  const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
+  const acc: DirClasses = {
+    scanState: 'scanned',
+    classes: new Set<string>(),
+    fileStems: new Set<string>(),
+    byClass: new Map<string, PersonaFile>(),
+  };
   let entries: string[];
   try {
     entries = await readdir(dir);
-  } catch {
+  } catch (error) {
+    acc.scanState = await classifyScanFailure(dir, error);
     return acc;
   }
 
   for (const entry of entries) {
     if (!entry.endsWith('.md')) continue;
+    // Preserve entry presence separately from valid readable classes. Resolvers
+    // use it to fail closed on an explicit unreadable canonical override without
+    // advertising that override through class listing/status APIs.
+    if (entry !== 'LIBRARY.md') acc.fileStems.add(basename(entry, '.md'));
     let text: string;
     try {
       text = await readFile(join(dir, entry), 'utf8');
@@ -117,16 +201,25 @@ export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
  * cannot await. Missing dir / unreadable files degrade gracefully.
  */
 export function extractClassesFromDirSync(dir: string): DirClasses {
-  const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
+  const acc: DirClasses = {
+    scanState: 'scanned',
+    classes: new Set<string>(),
+    fileStems: new Set<string>(),
+    byClass: new Map<string, PersonaFile>(),
+  };
   let entries: string[];
   try {
     entries = readdirSync(dir);
-  } catch {
+  } catch (error) {
+    acc.scanState = classifyScanFailureSync(dir, error);
     return acc;
   }
 
   for (const entry of entries) {
     if (!entry.endsWith('.md')) continue;
+    // Keep sync extraction equivalent to the async scanner, including unreadable
+    // filename presence kept separate from valid readable classes.
+    if (entry !== 'LIBRARY.md') acc.fileStems.add(basename(entry, '.md'));
     let text: string;
     try {
       text = readFileSync(join(dir, entry), 'utf8');
@@ -138,6 +231,74 @@ export function extractClassesFromDirSync(dir: string): DirClasses {
   return acc;
 }
 
+async function classifyScanFailure(dir: string, error: unknown): Promise<DirScanState> {
+  if (!isMissingPathError(error)) return 'error';
+  return (await hasBrokenSymlinkInPath(dir)) ? 'error' : 'missing';
+}
+
+function classifyScanFailureSync(dir: string, error: unknown): DirScanState {
+  if (!isMissingPathError(error)) return 'error';
+  return hasBrokenSymlinkInPathSync(dir) ? 'error' : 'missing';
+}
+
+function traversalPrefixes(path: string): string[] {
+  const absolute = isAbsolute(path) ? path : `${process.cwd()}${sep}${path}`;
+  const parts = absolute.split(sep);
+  const prefixes: string[] = [];
+  let current: string = sep;
+  for (const part of parts) {
+    if (!part) continue;
+    current = current === sep ? `${sep}${part}` : `${current}${sep}${part}`;
+    prefixes.push(current);
+  }
+  return prefixes;
+}
+
+async function hasBrokenSymlinkInPath(path: string): Promise<boolean> {
+  for (const current of traversalPrefixes(path)) {
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink()) {
+        try {
+          await stat(current);
+        } catch {
+          return true;
+        }
+      }
+    } catch (error) {
+      if (!isMissingPathError(error)) return true;
+    }
+  }
+  return false;
+}
+
+function hasBrokenSymlinkInPathSync(path: string): boolean {
+  for (const current of traversalPrefixes(path)) {
+    try {
+      const entry = lstatSync(current);
+      if (entry.isSymbolicLink()) {
+        try {
+          statSync(current);
+        } catch {
+          return true;
+        }
+      }
+    } catch (error) {
+      if (!isMissingPathError(error)) return true;
+    }
+  }
+  return false;
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as { code?: unknown }).code === 'ENOENT'
+  );
+}
+
 /**
  * Apply the class-extraction rules for ONE role file's text into `acc`. Pure
  * over already-read content, so the async and sync directory scanners share a
@@ -146,33 +307,26 @@ export function extractClassesFromDirSync(dir: string): DirClasses {
  */
 function accumulateEntry(acc: DirClasses, dir: string, entry: string, text: string): void {
   const { classes, byClass } = acc;
-  if (entry === 'LIBRARY.md') {
-    for (const m of text.matchAll(LIBRARY_ROW)) {
-      const name = m[1];
-      if (name && name !== 'persona') classes.add(name);
-    }
-    return;
-  }
-  // The filename stem is itself a valid class (covers marker-less alias docs).
+  if (entry === 'LIBRARY.md') return;
+
+  // An explicit first marker owns identity. Filename identity is a fallback only
+  // for markerless compatibility contracts such as planner.md.
   const stem = basename(entry, '.md');
-  classes.add(stem);
   const domainMatch = DOMAIN_MARKER.exec(text);
   const domain = domainMatch?.[1];
-  let markedClassForFile: string | undefined;
-  for (const m of text.matchAll(CLASS_MARKER)) {
-    const klass = m[1];
-    if (!klass) continue;
-    classes.add(klass);
-    // Record the FIRST marker as the file's defining class (the prose names
-    // the persona's own class up top; later mentions reference siblings).
-    if (!markedClassForFile) {
-      markedClassForFile = klass;
-      byClass.set(klass, { klass, file: join(dir, entry), ...(domain ? { domain } : {}) });
-    }
-  }
-  // A marker-less file still maps its stem to itself (no domain known).
-  if (!markedClassForFile && !byClass.has(stem)) {
-    byClass.set(stem, { klass: stem, file: join(dir, entry) });
+  const firstMarker = text.matchAll(CLASS_MARKER).next().value as RegExpExecArray | undefined;
+  const markedClassForFile = firstMarker?.[1];
+  if (markedClassForFile) {
+    classes.add(markedClassForFile);
+    byClass.set(markedClassForFile, {
+      klass: markedClassForFile,
+      file: join(dir, entry),
+      markerDefined: true,
+      ...(domain ? { domain } : {}),
+    });
+  } else {
+    classes.add(stem);
+    if (!byClass.has(stem)) byClass.set(stem, { klass: stem, file: join(dir, entry) });
   }
 }
 
@@ -193,24 +347,19 @@ function resolveDirs(opts: PersonaDirs): { rolesDir: string; overrideDir: string
 }
 
 /**
- * UNION of baseline classes and override classes. Overrides may ADD entirely new
- * classes not present in the baseline, so callers (e.g. profile roster
- * validation) treat a user-added persona as a real class.
+ * Every class with an actually readable winning contract. Discovery applies the
+ * same override shadow/fail-closed semantics as resolution, so callers never
+ * advertise a class that cannot be used.
  */
 export async function listPersonaClasses(opts: PersonaDirs = {}): Promise<Set<string>> {
-  const { rolesDir, overrideDir } = resolveDirs(opts);
-  const [base, over] = await Promise.all([
-    extractClassesFromDir(rolesDir),
-    extractClassesFromDir(overrideDir),
-  ]);
-  const union = new Set<string>(base.classes);
-  for (const c of over.classes) union.add(c);
-  return union;
+  const { personas } = await collectUsablePersonas(opts);
+  return new Set(personas.keys());
 }
 
 export type PersonaStatus = 'baseline' | 'overridden' | 'custom';
 
-export interface PersonaResolution {
+export interface PersonaResolution extends CanonicalRoleClass {
+  /** Compatibility name for the canonical class. */
   klass: string;
   layer: PersonaLayer;
   /** The file the resolved persona was read from (override wins). */
@@ -219,6 +368,118 @@ export interface PersonaResolution {
   domain?: string;
 }
 
+async function readPersonaFromLayer(
+  requestedClass: string,
+  canonicalClass: string,
+  dir: string,
+  extracted: DirClasses,
+  layer: PersonaLayer,
+): Promise<PersonaResolution | null> {
+  const pf = extracted.byClass.get(canonicalClass);
+  if (!pf) {
+    if (!extracted.classes.has(canonicalClass)) return null;
+    const byName = join(dir, `${canonicalClass}.md`);
+    try {
+      const content = await readFile(byName, 'utf8');
+      const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+        | RegExpExecArray
+        | undefined;
+      if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+      const dm = DOMAIN_MARKER.exec(content);
+      return {
+        requestedClass,
+        canonicalClass,
+        klass: canonicalClass,
+        layer,
+        file: byName,
+        content,
+        ...(dm?.[1] ? { domain: dm[1] } : {}),
+      };
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const content = await readFile(pf.file, 'utf8');
+    const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+      | RegExpExecArray
+      | undefined;
+    if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+    const dm = DOMAIN_MARKER.exec(content);
+    return {
+      requestedClass,
+      canonicalClass,
+      klass: canonicalClass,
+      layer,
+      file: pf.file,
+      content,
+      ...(dm?.[1] ? { domain: dm[1] } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function overrideShadowsBaseline(over: DirClasses, canonicalClass: string): boolean {
+  return (
+    over.scanState === 'error' ||
+    over.fileStems.has(canonicalClass) ||
+    over.byClass.has(canonicalClass)
+  );
+}
+
+function readPersonaFromLayerSync(
+  requestedClass: string,
+  canonicalClass: string,
+  dir: string,
+  extracted: DirClasses,
+  layer: PersonaLayer,
+): PersonaResolution | null {
+  const pf = extracted.byClass.get(canonicalClass);
+  if (!pf) {
+    if (!extracted.classes.has(canonicalClass)) return null;
+    const byName = join(dir, `${canonicalClass}.md`);
+    try {
+      const content = readFileSync(byName, 'utf8');
+      const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+        | RegExpExecArray
+        | undefined;
+      if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+      const dm = DOMAIN_MARKER.exec(content);
+      return {
+        requestedClass,
+        canonicalClass,
+        klass: canonicalClass,
+        layer,
+        file: byName,
+        content,
+        ...(dm?.[1] ? { domain: dm[1] } : {}),
+      };
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const content = readFileSync(pf.file, 'utf8');
+    const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+      | RegExpExecArray
+      | undefined;
+    if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+    const dm = DOMAIN_MARKER.exec(content);
+    return {
+      requestedClass,
+      canonicalClass,
+      klass: canonicalClass,
+      layer,
+      file: pf.file,
+      content,
+      ...(dm?.[1] ? { domain: dm[1] } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Resolve a persona class to its winning definition: the override file if
  * roles.local/ defines that class, else the baseline. Match by inline `class:`
@@ -245,42 +506,32 @@ export async function resolvePersona(
  * is identical to {@link resolvePersona}: override layer wins, then baseline.
  */
 export async function resolvePersonaFrom(
-  klass: string,
+  requestedClass: string,
   layers: { rolesDir: string; overrideDir: string; base: DirClasses; over: DirClasses },
 ): Promise<PersonaResolution | null> {
+  const { requestedClass: requested, canonicalClass: klass } =
+    canonicalizeRoleClass(requestedClass);
   const { rolesDir, overrideDir, base, over } = layers;
 
-  const fromLayer = async (
-    dir: string,
-    extracted: DirClasses,
-    layer: PersonaLayer,
-  ): Promise<PersonaResolution | null> => {
-    // Prefer the marker-defined file; fall back to the filename stem.
-    let pf = extracted.byClass.get(klass);
-    if (!pf) {
-      const byName = join(dir, `${klass}.md`);
-      if (!extracted.classes.has(klass)) return null;
-      // Class known only via filename/LIBRARY: read the stem file if present.
-      try {
-        const content = await readFile(byName, 'utf8');
-        const dm = DOMAIN_MARKER.exec(content);
-        return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
-      } catch {
-        return null;
-      }
-    }
-    try {
-      const content = await readFile(pf.file, 'utf8');
-      return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
-    } catch {
-      return null;
-    }
-  };
+  const override = await readPersonaFromLayer(requested, klass, overrideDir, over, 'override');
+  if (override) return override;
+  // An observed explicit override that cannot resolve/read shadows the baseline.
+  if (overrideShadowsBaseline(over, klass)) return null;
 
-  return (
-    (await fromLayer(overrideDir, over, 'override')) ??
-    (await fromLayer(rolesDir, base, 'baseline'))
+  // Cached scans are only snapshots. Re-scan immediately before baseline fallback
+  // so a newly created canonical or marker-defined override cannot be skipped.
+  const currentOver = await extractClassesFromDir(overrideDir);
+  const currentOverride = await readPersonaFromLayer(
+    requested,
+    klass,
+    overrideDir,
+    currentOver,
+    'override',
   );
+  if (currentOverride) return currentOverride;
+  if (overrideShadowsBaseline(currentOver, klass)) return null;
+  if (currentOver.scanState === 'error') return null;
+  return readPersonaFromLayer(requested, klass, rolesDir, base, 'baseline');
 }
 
 /**
@@ -292,40 +543,55 @@ export async function resolvePersonaFrom(
  * one module so the launch-time and command-time resolutions never diverge.
  */
 export function resolvePersonaSync(
-  klass: string,
+  requestedClass: string,
   opts: PersonaDirs = {},
 ): PersonaResolution | null {
+  const { requestedClass: requested, canonicalClass: klass } =
+    canonicalizeRoleClass(requestedClass);
   const { rolesDir, overrideDir } = resolveDirs(opts);
   const base = extractClassesFromDirSync(rolesDir);
   const over = extractClassesFromDirSync(overrideDir);
 
-  const fromLayer = (
-    dir: string,
-    extracted: DirClasses,
-    layer: PersonaLayer,
-  ): PersonaResolution | null => {
-    // Prefer the marker-defined file; fall back to the filename stem.
-    const pf = extracted.byClass.get(klass);
-    if (!pf) {
-      if (!extracted.classes.has(klass)) return null;
-      const byName = join(dir, `${klass}.md`);
-      try {
-        const content = readFileSync(byName, 'utf8');
-        const dm = DOMAIN_MARKER.exec(content);
-        return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
-      } catch {
-        return null;
-      }
-    }
-    try {
-      const content = readFileSync(pf.file, 'utf8');
-      return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
-    } catch {
-      return null;
-    }
-  };
+  const override = readPersonaFromLayerSync(requested, klass, overrideDir, over, 'override');
+  if (override) return override;
+  if (overrideShadowsBaseline(over, klass)) return null;
+  return readPersonaFromLayerSync(requested, klass, rolesDir, base, 'baseline');
+}
 
-  return fromLayer(overrideDir, over, 'override') ?? fromLayer(rolesDir, base, 'baseline');
+interface UsablePersonaIndex {
+  personas: Map<string, PersonaResolution>;
+  readableBaseline: Set<string>;
+}
+
+async function collectUsablePersonas(opts: PersonaDirs): Promise<UsablePersonaIndex> {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+  if (over.scanState === 'error') {
+    return { personas: new Map(), readableBaseline: new Set() };
+  }
+
+  const candidates = new Set<string>([...base.classes, ...over.classes]);
+  const checked = await Promise.all(
+    [...candidates].map(async (requestedClass) => {
+      const { canonicalClass } = canonicalizeRoleClass(requestedClass);
+      const [persona, baseline] = await Promise.all([
+        resolvePersonaFrom(requestedClass, { rolesDir, overrideDir, base, over }),
+        readPersonaFromLayer(requestedClass, canonicalClass, rolesDir, base, 'baseline'),
+      ]);
+      return { requestedClass, persona, baseline };
+    }),
+  );
+
+  const personas = new Map<string, PersonaResolution>();
+  const readableBaseline = new Set<string>();
+  for (const { requestedClass, persona, baseline } of checked) {
+    if (persona) personas.set(requestedClass, persona);
+    if (baseline) readableBaseline.add(requestedClass);
+  }
+  return { personas, readableBaseline };
 }
 
 export interface PersonaStatusEntry {
@@ -342,24 +608,20 @@ export interface PersonaStatusEntry {
  * Domain is taken from the WINNING layer (override domain wins if present).
  */
 export async function personaStatus(opts: PersonaDirs = {}): Promise<PersonaStatusEntry[]> {
-  const { rolesDir, overrideDir } = resolveDirs(opts);
-  const [base, over] = await Promise.all([
-    extractClassesFromDir(rolesDir),
-    extractClassesFromDir(overrideDir),
-  ]);
-
-  const all = new Set<string>([...base.classes, ...over.classes]);
-  const domainOf = (extracted: DirClasses, klass: string): string | undefined =>
-    extracted.byClass.get(klass)?.domain;
-
-  const entries: PersonaStatusEntry[] = [];
-  for (const klass of all) {
-    const inBase = base.classes.has(klass);
-    const inOver = over.classes.has(klass);
-    const status: PersonaStatus = inOver ? (inBase ? 'overridden' : 'custom') : 'baseline';
-    const domain = (inOver ? domainOf(over, klass) : undefined) ?? domainOf(base, klass);
-    entries.push({ klass, status, ...(domain ? { domain } : {}) });
-  }
+  const { personas, readableBaseline } = await collectUsablePersonas(opts);
+  const entries = [...personas.entries()].map(([klass, persona]): PersonaStatusEntry => {
+    const status: PersonaStatus =
+      persona.layer === 'baseline'
+        ? 'baseline'
+        : readableBaseline.has(klass)
+          ? 'overridden'
+          : 'custom';
+    return {
+      klass,
+      status,
+      ...(persona.domain ? { domain: persona.domain } : {}),
+    };
+  });
   entries.sort((a, b) => a.klass.localeCompare(b.klass));
   return entries;
 }

packages/mosaic/src/commands/fleet-profiles.spec.ts

@@ -203,6 +203,91 @@ describe('loadProfiles with a temp override dir', () => {
     await rm(dir, { recursive: true, force: true });
   });
 
+  it('canonicalizes approved aliases across lead, floor, roster, and topology', async () => {
+    await writeFile(
+      join(dir, 'aliases.yaml'),
+      [
+        'id: aliases',
+        'title: Aliases',
+        'description: legacy class compatibility',
+        'lead: operator-interaction',
+        'floor: [operator-interaction]',
+        'roster:',
+        '  - class: operator-interaction',
+        '  - class: implementer',
+        '    reports_to: operator-interaction',
+        '  - class: reviewer',
+        '    reports_to: operator-interaction',
+        '',
+      ].join('\n'),
+    );
+
+    const profile = await loadProfile('aliases', {
+      profilesDir: dir,
+      rolesDir,
+      overrideDir: join(dir, 'roles.local'),
+    });
+    expect(profile.lead).toBe('interaction');
+    expect(profile.floor).toEqual(['interaction']);
+    expect(profile.roster).toEqual([
+      { class: 'interaction', multiplicity: 1 },
+      { class: 'code', reportsTo: 'interaction', multiplicity: 1 },
+      { class: 'review', reportsTo: 'interaction', multiplicity: 1 },
+    ]);
+  });
+
+  it('rejects roster entries that collapse to the same canonical class', async () => {
+    await writeFile(
+      join(dir, 'alias-collision.yaml'),
+      [
+        'id: alias-collision',
+        'title: Alias collision',
+        'description: ambiguous canonical topology',
+        'lead: orchestrator',
+        'floor: [orchestrator]',
+        'roster:',
+        '  - class: orchestrator',
+        '  - class: code',
+        '    reports_to: orchestrator',
+        '  - class: implementer',
+        '    reports_to: orchestrator',
+        '',
+      ].join('\n'),
+    );
+
+    await expect(
+      loadProfile('alias-collision', {
+        profilesDir: dir,
+        rolesDir,
+        overrideDir: join(dir, 'roles.local'),
+      }),
+    ).rejects.toThrow(/duplicate classes after canonicalization/);
+  });
+
+  it('allows a readable lead or floor persona that is not itself a roster seat', async () => {
+    await writeFile(
+      join(dir, 'external-topology.yaml'),
+      [
+        'id: external-topology',
+        'title: External topology',
+        'description: structural compatibility',
+        'lead: orchestrator',
+        'floor: [enhancer]',
+        'roster:',
+        '  - class: code',
+        '',
+      ].join('\n'),
+    );
+
+    const profile = await loadProfile('external-topology', {
+      profilesDir: dir,
+      rolesDir,
+      overrideDir: join(dir, 'roles.local'),
+    });
+    expect(profile.lead).toBe('orchestrator');
+    expect(profile.floor).toEqual(['enhancer']);
+  });
+
   it('throws when a profile references an unknown class (validated against real roles)', async () => {
     await writeFile(
       join(dir, 'bad.yaml'),

packages/mosaic/src/commands/fleet-profiles.ts

@@ -29,6 +29,7 @@ import {
   defaultOverrideDir,
   extractClassesFromDir,
   listPersonaClasses as listOverrideAwarePersonaClasses,
+  resolvePersonaFrom,
 } from './fleet-personas.js';
 
 function defaultMosaicHome(): string {
@@ -199,6 +200,61 @@ export function validateProfile(profile: FleetProfile, validClasses: Set<string>
   return problems;
 }
 
+export async function resolveProfilePersonas(
+  profile: FleetProfile,
+  rolesDir: string,
+  overrideDir: string,
+): Promise<FleetProfile> {
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+  const requestedClasses = new Set<string>([
+    profile.lead,
+    ...profile.floor,
+    ...profile.roster.flatMap((entry: ProfileRosterEntry): string[] =>
+      entry.reportsTo ? [entry.class, entry.reportsTo] : [entry.class],
+    ),
+  ]);
+  const canonicalByRequested = new Map<string, string>();
+  for (const requestedClass of requestedClasses) {
+    const resolved = await resolvePersonaFrom(requestedClass, {
+      rolesDir,
+      overrideDir,
+      base,
+      over,
+    });
+    if (!resolved || resolved.content.trim() === '') {
+      throw new Error(`persona class "${requestedClass}" does not resolve to a readable persona`);
+    }
+    canonicalByRequested.set(requestedClass, resolved.canonicalClass);
+  }
+  const canonical = (requestedClass: string): string =>
+    canonicalByRequested.get(requestedClass) ?? requestedClass;
+  const roster = profile.roster.map(
+    (entry: ProfileRosterEntry): ProfileRosterEntry => ({
+      class: canonical(entry.class),
+      multiplicity: entry.multiplicity,
+      ...(entry.reportsTo ? { reportsTo: canonical(entry.reportsTo) } : {}),
+    }),
+  );
+  const canonicalRosterClasses = roster.map((entry: ProfileRosterEntry): string => entry.class);
+  if (new Set(canonicalRosterClasses).size !== canonicalRosterClasses.length) {
+    throw new Error('profile roster contains duplicate classes after canonicalization');
+  }
+  const resolvedProfile: FleetProfile = {
+    ...profile,
+    lead: canonical(profile.lead),
+    floor: profile.floor.map(canonical),
+    roster,
+  };
+  const problems = validateProfile(resolvedProfile, new Set(canonicalByRequested.values()));
+  if (problems.length > 0) {
+    throw new Error(problems.join('\n  - '));
+  }
+  return resolvedProfile;
+}
+
 export interface LoadProfilesOptions {
   /** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
   profilesDir?: string;
@@ -237,10 +293,8 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
   }
   files.sort();
 
-  // Override-aware: a profile may reference a user-customized or user-ADDED
-  // persona living in the roles.local/ layer (H4), so validate against the
-  // baseline ⊕ override union, not the baseline alone.
-  const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
+  // Validation resolves each reference to an actually readable winning persona;
+  // LIBRARY membership alone is not semantic success.
   const profiles: FleetProfile[] = [];
   const seen = new Map<string, string>();
 
@@ -255,11 +309,14 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
     }
     seen.set(profile.id, file);
 
-    const problems = validateProfile(profile, validClasses);
-    if (problems.length > 0) {
-      throw new Error(`Profile ${file} is invalid:\n  - ${problems.join('\n  - ')}`);
+    let resolvedProfile: FleetProfile;
+    try {
+      resolvedProfile = await resolveProfilePersonas(profile, rolesDir, overrideDir);
+    } catch (error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`Profile ${file} is invalid:\n  - ${detail}`);
     }
-    profiles.push(profile);
+    profiles.push(resolvedProfile);
   }
   return profiles;
 }