test(fleet): make unreadable persona fixture deterministic

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.prettierignore

@@ -7,4 +7,3 @@ pnpm-lock.yaml
 .claude/
 docs/tess/TASKS.md
 docs/scratchpads/
-packages/mosaic/src/fleet/testdata/documentation-publication-v1/inline-migration-v1.json

.woodpecker/ci.yml

@@ -42,27 +42,6 @@ steps:
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
 
-  # Blocking gate (#791): a framework upgrade must never write or delete an
-  # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
-  # survives a keep-mode reseed byte-identical (with rsync present AND absent —
-  # keep mode is a single cp-based path that must not depend on rsync), and that a
-  # corrupt/empty/missing manifest aborts fail-closed leaving operator files
-  # untouched (B2/B3). The rollback gate proves a mid-sync failure is rolled back
-  # from the pre-update snapshot (B1). The durable-snapshot gate (#791 PR2) proves
-  # the retained, operator-scoped pre-update backup is taken before any mutation
-  # (0700/0600, secret never logged, retention-pruned) and that the post-sync
-  # verify net restores any operator file a manifest bug lets the sync touch. The
-  # migration matrix pins the v2→v3 contract-file semantics. Pure bash, no
-  # node_modules — runs early alongside sanitization.
-  upgrade-guard:
-    image: *node_image
-    commands:
-      - apk add --no-cache bash rsync
-      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh
-      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh
-      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh
-      - bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
-
   typecheck:
     image: *node_image
     commands:
@@ -71,7 +50,6 @@ steps:
     depends_on:
       - install
       - sanitization
-      - upgrade-guard
 
   # lint, format, and test are independent — run in parallel after typecheck
   lint:

CLAUDE.md

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

Dockerfile.ci

@@ -22,10 +22,10 @@
 FROM node:24-alpine
 
 # Native toolchain required to compile node-gyp deps on musl, plus the
-# postgresql-client used by the test step's pg_isready readiness probe. `bash`,
-# `git`, and `jq` are baked here too — framework shell tests and the shipped
-# Codex review wrappers require them without per-run installation in ci.yml.
-RUN apk add --no-cache python3 make g++ postgresql-client bash git jq
+# postgresql-client used by the test step's pg_isready readiness probe. `bash`
+# is baked here too — the sanitization step in ci.yml otherwise does a per-run
+# `apk add bash`.
+RUN apk add --no-cache python3 make g++ postgresql-client bash
 
 # Pin pnpm to the repo's packageManager version via corepack.
 RUN corepack enable && corepack prepare pnpm@10.6.2 --activate

README.md

@@ -97,10 +97,7 @@ mosaic config path           # Print config file path
 ```bash
 mosaic doctor                # Health audit — detect drift and missing files
 mosaic sync                  # Sync skills from canonical source
-mosaic skill list            # Audit Claude skill registrations and conflicts
-mosaic skill register <name> # Register one canonical skill with Claude Code
-mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
-mosaic update                # Update CLI/framework and auto-register canonical skills
+mosaic update                # Check for and install CLI updates
 mosaic wizard                # Full guided setup wizard
 mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
 mosaic coord init            # Initialize a new orchestration mission
@@ -160,12 +157,7 @@ mosaic storage status
 mosaic storage tier
 mosaic storage export
 mosaic storage import
-# Schema migration is unavailable in this release. The current storage wrapper shells
-# directly to `pnpm --filter @mosaicstack/db db:migrate`; it is legacy N-1,
-# uncertified, and MUST NOT be invoked pending KBN-101-02/-03/-06/-08 activation.
-# Future schema migration is non-operative: external bootstrap → TLS/roles → runner
-# --run → runner --verify → readiness. Tier copy uses only the separately held secure
-# migrate-tier route.
+mosaic storage migrate
 ```
 
 ### Telemetry
@@ -200,32 +192,29 @@ Consent state is persisted in config. Remote upload is a no-op until you run `mo
 git clone git@git.mosaicstack.dev:mosaicstack/stack.git
 cd stack
 
-# Install dependencies. The local tier uses in-process PGlite; leave DATABASE_URL unset.
+# Start infrastructure (Postgres, Valkey, Jaeger)
+docker compose up -d
+
+# Install dependencies
 pnpm install
 
-# Optional local queue service only. This does not start PostgreSQL.
-docker compose up -d valkey
+# Run migrations
+pnpm --filter @mosaicstack/db run db:migrate
 
-# The current Gateway/Web local process is held; see docs/guides/dev-guide.md.
-# Do not start it until KBN-101-02 makes inherited dotenv/DSN state fail closed.
+# Start all services in dev mode
+pnpm dev
 ```
 
-### Held future procedure
+### Infrastructure
 
-The checked-in Compose PostgreSQL service mounts legacy initialization SQL and is **not** a
-current PostgreSQL, standalone, or federated developer route. Do not start it with Compose,
-invoke initialization SQL, or treat the planned migrator as currently executable.
+Docker Compose provides:
 
-**Held future activation procedure — non-operative and no current command authority until KBN-101-00, KBN-101-03, and KBN-101-05
-land:** external bootstrap → TLS/roles → `mosaic-db-migrator --run` →
-`mosaic-db-migrator --verify` → Gateway/Compose readiness. The future deployment artifacts—not
-this README—will provide the reviewed commands and secret-consumer interface.
-
-For local data-layer work, PGlite needs no PostgreSQL service. The optional Compose command above
-starts only Valkey; OTEL Collector and Jaeger may likewise be started individually if needed,
-without starting PostgreSQL. A Gateway/Web local process is not currently a safe PGlite route:
-its unguarded dotenv loader may inherit a daemon PostgreSQL DSN. Do not use root `pnpm dev` or a
-Gateway start command until KBN-101-02 makes that state fail closed.
+| Service               | Port      | Purpose                |
+| --------------------- | --------- | ---------------------- |
+| PostgreSQL (pgvector) | 5433      | Primary database       |
+| Valkey                | 6380      | Task queue + caching   |
+| Jaeger                | 16686     | Distributed tracing UI |
+| OTEL Collector        | 4317/4318 | Telemetry ingestion    |
 
 ### Quality Gates
 
@@ -242,7 +231,7 @@ pnpm format                  # Prettier auto-fix
 Woodpecker CI runs on every push:
 
 - `pnpm install --frozen-lockfile`
-- **Legacy N-1 CI status only — active, uncertified, and non-authorizing as an operator route:** the checked-in job currently invokes `pnpm --filter @mosaicstack/db run db:migrate` with `DATABASE_URL` against an isolated disposable PostgreSQL CI database. It performs direct DDL in that CI database, is not approved ordinary behavior or an operator route, and remains a known exception pending KBN-101-06 removal/replacement by the certified runner-backed CI path.
+- Database migration against a fresh Postgres
 - `pnpm test` (Turbo-orchestrated across all packages)
 
 npm packages are published to the Gitea package registry on main merges.
@@ -352,8 +341,6 @@ bash tools/install.sh --yes             # Non-interactive, accept all defaults
 bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```
 
-The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
-
 ## Contributing
 
 ```bash

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

@@ -21,12 +21,6 @@ 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,
@@ -52,13 +46,6 @@ export function createGatewayRuntimeProviderRegistry(): AgentRuntimeProviderRegi
     SkillLoaderService,
     DurableSessionRepository,
     DurableSessionService,
-    ConnectorLeaseRepository,
-    DenyConnectorLeasePolicy,
-    {
-      provide: CONNECTOR_LEASE_POLICY,
-      useExisting: DenyConnectorLeasePolicy,
-    },
-    ConnectorLeaseService,
     {
       provide: AGENT_RUNTIME_PROVIDER_REGISTRY,
       useFactory: createGatewayRuntimeProviderRegistry,
@@ -91,7 +78,6 @@ export function createGatewayRuntimeProviderRegistry(): AgentRuntimeProviderRegi
     SkillLoaderService,
     DurableSessionService,
     RuntimeProviderService,
-    ConnectorLeaseService,
     AGENT_RUNTIME_PROVIDER_REGISTRY,
   ],
 })

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

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

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

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

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

@@ -1,285 +0,0 @@
-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];
-    })
-  );
-}

docs/PERFORMANCE.md

@@ -149,9 +149,15 @@ for any `<Image>` components added in the future.
 
 ---
 
-## Held future procedure
+## How to Apply
 
-This report is non-operative evidence, not a current runbook. Until **KBN-101-00, KBN-101-03, and KBN-101-05** land, do not execute a PostgreSQL runner from this checkout. The approved future procedure is exactly: external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness. Deployment will supply the reviewed runner, migration-only credentials, and TLS material; Gateway startup only verifies readiness.
+```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
+```
 
 ---
 

docs/PRD.md

@@ -79,29 +79,6 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 
 ---
 
-## Compaction Refresh Trust Lifecycle (M1, #827–#830)
-
-### Problem and objective
-
-Context compaction, session replacement, and same-PID runtime reloads can leave a previously VERIFIED runtime lease attached to stale directives. M1 must revoke that authority mechanically for Claude (including Claudex) and Pi without trusting caller-asserted identity or forking the external broker state machine.
-
-### Requirements
-
-1. `CR-REQ-01`: Claude `PreCompact` and `SessionStart` with matcher `compact`, plus Pi `session_before_compact` and the first post-`session_compact` `context`, SHALL independently revoke the active broker lease.
-2. `CR-REQ-02`: Runtime generation increases—including same-PID Pi reload/new/resume/fork and Claude resume/clear—SHALL monotonically replace the prior broker incarnation and inherit no VERIFIED lease.
-3. `CR-REQ-03`: A fired observer that cannot confirm broker revocation SHALL fail closed through lifecycle cancellation, a private local generation fence, and/or a runtime-local tool latch. The existing all-tools broker gate remains authoritative.
-4. `CR-REQ-04`: The lease TTL SHALL remain monotonic and capped at 300 seconds. If both observers are missed, within-TTL consequential actions remain allowed and after-TTL actions are denied. This named bounded residual stale window SHALL be documented without claiming a mutator-action bound inside the window.
-5. `CR-REQ-05`: Hook descendants SHALL use the broker-minted session and owner-only current-generation state inherited from register-before-exec. Caller-minted sessions and parallel lease state machines remain forbidden.
-
-### Acceptance criteria
-
-1. `AC-CR-01`: Real-socket tests prove each Claude observer revokes, Pi lifecycle tests prove both observer paths, and Claudex isolated settings preserve and install the mandatory hooks.
-2. `AC-CR-02`: A same-PID generation test proves the old generation is stale and the replacement generation is UNVERIFIED across reload/resume/fork-equivalent lifecycle events.
-3. `AC-CR-03`: RED-first T12b/T30 evidence explicitly reports dual-hook miss within TTL as **ALLOWED** and after TTL as **DENIED**.
-4. `AC-CR-04`: Attributable executable coverage is at least 85%, the full repository suite is green on deterministic main, and independent code/security review completes before merge.
-
----
-
 ## Fleet Declarative Configuration Management Workstream (FCM, #758)
 
 ### Problem and objective
@@ -148,105 +125,6 @@ are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
 
 ---
 
-## Exact Cross-Harness Fleet Communications Contract (#766)
-
-### Problem and objective
-
-Fleet runtime contracts currently combine exact peer rows with generic operational metavariables and
-independently parsed roster data. Non-Claude harnesses can mistake those metavariables for values to
-infer, producing incorrect host, session, socket, or helper targets. The objective is one
-roster-resolved communications contract that every supported harness receives unchanged.
-
-### Normative requirements
-
-1. `FCOM-REQ-01`: Fleet commands and runtime composition SHALL use one shared v1 roster structural
-   resolver. A second lenient communications parser is forbidden.
-2. `FCOM-REQ-02`: The composed contract SHALL render the local roster member's authoritative host,
-   exact agent/session name, resolved tmux socket, exact helper path, and deterministic communications
-   generation.
-3. `FCOM-REQ-03`: Every known peer SHALL have one exact executable command. Same-host commands SHALL
-   omit `-H`; cross-host commands SHALL use only that peer's explicit roster `ssh` target; the one
-   supported fleet-wide named socket SHALL use `-L` with its exact value. A per-agent socket declaration
-   must equal that fleet-wide value; unsupported independent sockets and missing cross-host SSH data SHALL
-   fail closed.
-4. `FCOM-REQ-04`: Operational fleet examples SHALL not contain unresolved host, session, socket, or
-   helper-path metavariables. Agents SHALL select an exact rendered peer row and SHALL NOT infer,
-   substitute, or fuzzy-match targeting values.
-5. `FCOM-REQ-05`: An unknown local member or requested peer SHALL fail closed with exact-name discovery
-   guidance. Runtime composition SHALL not silently omit a requested fleet member's communications
-   contract.
-6. `FCOM-REQ-06`: Claude Code, Codex, OpenCode, and Pi SHALL receive equivalent authoritative
-   communications data through the common runtime composer.
-7. `FCOM-REQ-07`: Tests SHALL prove the contract from framework-source `TOOLS.md`, through a fresh
-   installed `TOOLS.md`, to final runtime composition and helper executability. User-owned installed
-   `TOOLS.md` content SHALL remain preserved.
-8. `FCOM-REQ-08`: Stale installed or active composed context SHALL be reported with deterministic
-   generation/repair/relaunch guidance. Currency requires the expected source and installed contract
-   marker/version plus bounded byte equality. The supported current-version repair SHALL run independently
-   of package updates, preserve divergent `TOOLS.md` bytes in a digest-qualified no-clobber backup, restore
-   a regular executable helper without following symlinks, and be idempotent. Detection and reporting SHALL
-   NOT rewrite active context, restart a session, or mutate a live fleet.
-9. `FCOM-REQ-09`: The shared resolver SHALL preserve and strictly validate every schema-supported v1
-   connector kind (`tmux`, `discord`, and `matrix`) from YAML and JSON. Every accepted snake/camel alias
-   pair SHALL reject differing dual declarations and accept identical declarations. JSON roster fallback
-   SHALL occur only when `roster.yaml` is absent; all other YAML access failures SHALL fail closed.
-10. `FCOM-REQ-10`: The communications generation SHALL cover the complete canonical rendered semantic
-    contract, including identity, role/class, resolved host/socket/helper, peer metadata, and exact commands.
-    Installed helpers SHALL be validated with no-follow filesystem inspection as regular executable files.
-    Keep-mode reseed and relaunch discovery SHALL preserve and support both YAML and JSON rosters.
-
-### Acceptance criteria
-
-1. `AC-FCOM-01`: Contract fixtures contain no unresolved operational targeting metavariables; local
-   identity contains exact host/session/socket/helper values.
-2. `AC-FCOM-02`: Same-host, cross-host, named-socket, literal-default-socket, and missing-SSH tests prove
-   exact targeting and fail-closed behavior.
-3. `AC-FCOM-03`: Unknown identities and peers report known exact names plus an exact self-scoped
-   discovery command; no fuzzy session selection is emitted.
-4. `AC-FCOM-04`: Four-harness tests prove byte-equal authoritative communications sections.
-5. `AC-FCOM-05`: Source, fresh-install, preserved-custom-install, stale-installed, composed-generation,
-   helper executable, agent-send socket isolation, and exact-target tests pass.
-6. `AC-FCOM-06`: Documentation defines non-mutating stale-context detection and operator-authorized,
-   exact-agent relaunch; no implementation path performs automatic session mutation.
-7. `AC-FCOM-07`: YAML and JSON fixtures cover every connector kind; all snake/camel aliases cover
-   identical acceptance and conflicting rejection; non-`ENOENT` YAML failures do not fall back.
-8. `AC-FCOM-08`: Missing, directory, symlink, and non-executable installed helpers fail closed. Explicit
-   current-version repair proves partial-deletion recovery, digest-qualified backup collision safety,
-   symlink-target safety, and repeated-run idempotence.
-9. `AC-FCOM-09`: Markerless-equal and wrong-version source/installed contracts are stale, and a rendered
-   role/class change produces a different communications generation.
-
----
-
-## 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`, its fixed paired authenticated provider-version file `/run/secrets/mosaic-migrate-target-version`, plus `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. KBN-101-05 obtains URL key `url` and version only from the same successful Vault KV-v2 response at `secret-{env}/mosaic-stack/database/importer` (`data.metadata.version`), renders them as one immutable generation into separate consumer copies, and never infers a provider version from DSN bytes. The trusted runner verifies TLS/identity/manifest, reads its fixed importer URL/version copies only for binding through safe no-follow fd 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 URL/version/attestation/public-key files, signature/key/expiry/replay/authenticated provider version/digest/generation/bindings and the importer-only CA at exact `DATABASE_TLS_CA_CERT_PATH`; after verified TLS and before DML it validates server/database/role/CA/schema identity, with same-fd/in-memory-byte TOCTOU protection, rotation/revocation, a privileged producer-only-to-importer-only artifact handoff controller that verifies/copies/fsyncs/atomically renames/seals before importer start, consumer isolation/no logging-oracle, 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/importer URL, importer authenticated provider-version, DB-client CA, Gateway leaf, and PostgreSQL server key/certificate materials are provisioned before a production-like database starts. Importer and migrator have separate immutable URL/version copies at fixed `10002:10002`/`10003:10003` identities; runtime/unrelated containers receive neither importer material, attestation private key, or importer artifact. Runtime, migrator, and importer require their 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. Before inventory, ownership, or status masking, the semantic fixture fails README's exact former commented code-fence generic-wrapper form and the user guide's exact former executable generic-wrapper form; source-consistency proves current `packages/storage/src/cli.ts` directly `execSync`s `pnpm --filter @mosaicstack/db db:migrate` and no `mosaic-db-migrator` bin exists, so runner-delegation documentation fails. 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`, fixed paired provider-version file, and `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`; runner-only signing/private-key isolation; Vault KV-v2 same-response version provenance, separate immutable generation mounts, importer CA, JCS/Ed25519 signature/key rotation/revocation, atomic artifact, expiry/replay, safe-fd secret-version/digest, canonical TLS/CA/server/database/role/manifest/schema bindings, dedicated non-DDL importer, consumer isolation/no log-oracle, and exact no-connection versus zero-DML rejection for missing/wrong/stale/replayed/tampered/wrong-key/substituted/generation-mismatched inputs. The full current non-normative docs inventory—including user guide, federation historical task/MILESTONES status, and non-operative SETUP—has an exact safe disposition. Scanner semantic checks reject automatic first-boot/startup extension/schema/migration wording, Compose-up-before-runner, init-script authority, production `.env`/monorepo auto-load/`EnvironmentFile=`/credential-export-or-argv/restart-as-secret-activation routes, and every unqualified operator-document `mosaic-db-migrator --run|--verify` hit regardless of named/normative/status classification. The exact former README/dev/deployment Compose-first sequences, former SETUP wording, exact former MILESTONES wording `pgvector extension installed + verified on startup`, former architecture-plan/PERFORMANCE/backlog runner routes, and any unqualified runner fixture fail before inventory masking. Only one `Held future procedure` Markdown section—bounded through the next equal-or-higher heading—may contain the explicit non-operative/no-current-command-authority form that names KBN-101-00/-03/-05 and preserves external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness; every runner hit outside that section fails. The README assertion for the checked-in direct CI `pnpm --filter @mosaicstack/db run db:migrate` with `DATABASE_URL` passes only as active legacy N-1, uncertified, non-authorizing-as-an-operator-route status against an isolated disposable CI database pending KBN-101-06 removal—not as an ordinary operator or approved DDL-authority route. Only local PGlite data-layer work or non-PostgreSQL Compose is current (Gateway/Web local startup is held pending daemon/inherited/project-DSN rejection).
-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
@@ -406,37 +284,6 @@ Use TDD for remote-ingress routing and permission boundaries. Required evidence
 
 ---
 
-## 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
@@ -1204,10 +1051,10 @@ Telegram remote control channel.
 
 ### AC-10: Deployment
 
-- [ ] PGlite data-layer work uses no PostgreSQL; optional Compose services are selected individually and do not start PostgreSQL; Gateway/Web local start remains held until KBN-101-02 rejects daemon/inherited/project DSNs before connection or DDL
-- [ ] PostgreSQL/federated activation is unavailable until KBN-101-00/-03/-05 deliver external bootstrap, TLS/roles, runner `--run`, runner `--verify`, and Gateway/Compose readiness in that order
-- [ ] `mosaic` CLI installable and functional on bare metal after the reviewed KBN-101-05 secret-renderer/process-exec or `LoadCredential` interface exists
-- [ ] Local-only configuration documentation is distinct from production generation-pinned Vault-rendered consumer material
+- [ ] `docker compose up` starts full stack from clean state
+- [ ] `mosaic` CLI installable and functional on bare metal
+- [ ] Database migrations run automatically on first start
+- [ ] `.env.example` documents all required configuration
 
 ### AC-11: @mosaicstack/\* Packages
 

docs/SITEMAP.md

@@ -1,40 +1,5 @@
 # Documentation Sitemap
 
-## Compaction refresh lease broker
-
-- [Internal broker protocol](architecture/lease-broker-protocol.md) — kernel identity, ancestry and generation invariants, framed requests, responses, and persisted cycle bindings.
-- [Broker operations](guides/lease-broker-operations.md) — protected paths, startup, constrained recovery, fail-closed posture, distinct-principal deployment, and residual risk.
-- [Constrained recovery skill](../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md) — source-resident thin wrapper, receipt scope, C4 replay boundary, and T-C middle-drop disclosure.
-- [Lease-broker security notes](architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements.
-- [Whole mutator-class gate](architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary.
-- [Compaction revocation lifecycle](architecture/compaction-revocation.md) — Claude/Pi observer matrix, same-PID generation rollover, failure fencing, and the named bounded residual stale window.
-
-## CLI and skill management
-
-- [Skill registration user guide](guides/user-guide.md#claude-code-skill-registration) — register, unregister, list statuses, automatic install/update reconciliation, and Claude reload behavior.
-- [Skill bridge developer guide](guides/dev-guide.md#claude-code-skill-bridge) — path-validation, ownership, clobber-protection, install/update wiring, tests, and Pi/Codex scope notes.
-
-## Fleet configuration management
-
-- [Fleet configuration entry point](fleet/README.md) — desired-versus-observed decision tree and complete operator link map.
-- [Desired, derived, and observed state](fleet/concepts/desired-vs-observed-state.md) — roster authority, generation, ownership, and drift.
-- [Identity, class, and runtime](fleet/concepts/identity-class-runtime.md) — stable name, display alias, class, runtime, provider, and model separation.
-- [Role authority and leases](fleet/concepts/role-authority-and-leases.md) — validator/merge-gate separation and bounded lease authority.
-- [Generated launch chain](fleet/concepts/generated-env-launch-chain.md) — strict data parsing, precedence, and quarantine.
-- [Roster v2 structural contract](fleet/reference/roster-v2-fields.md) — schema, supported values, required fields, defaults, and constraints.
-- [Fleet CLI reference](fleet/reference/cli.md) — local desired-state commands, JSON/exit behavior, and gateway-catalog separation.
-- [Lifecycle transitions](fleet/reference/lifecycle-transitions.md) — create/apply/reboot/migration/rollback boundaries.
-- [Status and drift](fleet/reference/status-and-drift.md) — desired/managed/observed state and current/future classifications.
-- [Safe agent CRUD](fleet/how-to/create-update-delete-agent.md) — expected generation, dry-run, and partial-failure recovery.
-- [Local lifecycle operations](fleet/how-to/start-stop-restart.md) — persisted versus one-shot actions.
-- [Configurable interaction instance](fleet/how-to/configure-tess-interaction.md) and [validator instance](fleet/how-to/configure-ultron-validator.md) — generic identities and protected limits.
-- [Reconcile and recover](fleet/operations/reconcile-and-recover.md) — plan/apply lock and recovery behavior.
-- [Environment quarantine](fleet/operations/env-quarantine.md) — private evidence and value-free diagnostics.
-- [Systemd/tmux troubleshooting](fleet/operations/systemd-tmux-troubleshooting.md) — socket, holder, unmanaged-session, and lock decisions.
-- [Backup/restore boundary](fleet/operations/backup-restore.md) and [upgrade-assets hold](fleet/operations/upgrade-assets.md).
-- [v1-to-v2 migration preview](fleet/migration/v1-to-v2.md) and [executable artifact dispositions](fleet/migration/example-profile-disposition.md).
-- [FCM M5 closure evidence](reports/documentation/758-fleet-config-ia-closure.md) and [approved deferrals](reports/deferred/758-fleet-config-deferrals.md).
-
 ## Official channel plugins
 
 - [Channel protocol architecture](architecture/channel-protocol.md) — shared lifecycle, message, stable-route, authorization, and response-target contracts.
@@ -49,10 +14,7 @@
 - [Workstream index](native-kanban-sot/INDEX.md) — artifact map, lane partition, and delivery order.
 - [Mission manifest](native-kanban-sot/MISSION-MANIFEST.md) — scope, authority, invariants, and gate model.
 - [Task decomposition](native-kanban-sot/TASKS.md) — dependency-ordered implementation slices and ownership boundaries.
-- [KBN-101 database role split](native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md) — rc.16 direct-Drizzle storage-wrapper hold: legacy N-1/uncertified/non-operative pending -02/-03/-06/-08; exact README/user-guide wrapper forms fail before masking and source-consistency rejects runner-delegation copy; held bootstrap → TLS/roles → run → verify → readiness; plus prior attestation, pgvector owner, classifier, TLS, activation, and certification prerequisite.
-- [Federated tier data migration](guides/migrate-tier.md) — active KBN-101-07 operator route: runner-produced target attestation, dedicated non-DDL importer, and paired credential-/attestation-file references only.
 - [Frozen shared contract](native-kanban-sot/SHARED-CONTRACT.md) — schema, API, Coordinator, health, recovery, and migration contracts.
-- [KBN-101 exact-head security review](reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) — retained prior REQUEST CHANGES evidence for `da742ca`; rc.16 awaits independent exact-head re-review after closing the current generic storage-wrapper authority HIGH finding.
 - [Initial independent review](reports/native-kanban-sot/canon-initial-review-no-go.md) — KCR-001–016 findings that blocked the first draft.
 - [Final independent re-review](reports/native-kanban-sot/canon-final-rereview-go.md) — closure evidence and GO verdict.
 - [Ultron final gate](reports/native-kanban-sot/ultron-final-go.md) — final requirements, authority, schema, migration, recovery, and evidence review.
@@ -94,5 +56,3 @@
 - [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

@@ -52,20 +52,20 @@ Active workstream is **W1 — Federation v1**. Workers should:
 > 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 | done        | 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      | #768 squash `a5e8e55`; shared resolver and canonical authority/alias validation delivered                                                                                                                          |
-| FCM-M1-003 | done        | 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      | #770 squash `e9c4aa3`; shipped artifact disposition validation delivered                                                                                                                                           |
-| FCM-M2-001 | done        | 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      | #772 squash `191efae`; generated/local boundary and private quarantine delivered                                                                                                                                   |
-| FCM-M2-002 | done        | 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      | #773 squash `bc5e736`; generation-guarded atomic CRUD and recovery contracts delivered                                                                                                                             |
-| FCM-M3-001 | done        | 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      | #785 squash `4990905`; exact roster-owned systemd/tmux reconcile and lifecycle contracts delivered                                                                                                                 |
-| FCM-M3-002 | in-progress | 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      | Canonical v2 named-socket + legacy-v1 default-server boundaries; fake adapters/temp fixtures only                                                                                                                  |
-| FCM-M4-001 | done        | 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      | PR #788; final head `d63bb0206a1d312ab8352ec1d3ca3631146b0baa`; tree `4da210da9a71b035130d4160a4a2e691bdfde2da`; squash `9745bc3f29c26b021a478b7ad03cfb494f6c9de3`; descendant-main pipeline 1855 terminal success |
-| 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      | HOLD: never starts a previously stopped agent or kills an unproven unmanaged session; not authorized by FCM-M5-001                                                                                                 |
-| FCM-M5-001 | done        | 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      | #789 squash `627cf2bb`; exact-head RoR (head `a39bafb8`) and PR/main terminal-green CI 1907; accepted fleet documentation IA, how-to/operations/migration references, and link/example validation delivered        |
-| 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      | HOLD: final #758 gate; quality, independent code/security review, validator certificate, merge-gate approval, and green CI remain out of M5-001                                                                    |
+| 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
 

docs/architecture/compaction-revocation.md

@@ -1,59 +0,0 @@
-# Compaction observer revocation and runtime generations
-
-WI-3 connects Claude and Pi compaction/session lifecycle events to the existing authenticated lease-broker state machine. It does not add a second lease store or let runtime hooks assert identity. Each observer inherits the broker-minted session, resolves the current private runtime generation, and sends the existing `revoke_lease` action over the authenticated Unix socket.
-
-## Observer matrix
-
-| Runtime          | Lifecycle signal                                                 | Action                                                                                                                       |
-| ---------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Claude / Claudex | `PreCompact`                                                     | Revoke the current lease before compaction. A non-zero hook result blocks the lifecycle transition.                          |
-| Claude / Claudex | `SessionStart` with matcher `compact`                            | Revoke again after compacted context starts.                                                                                 |
-| Claude / Claudex | `SessionStart` with matcher `resume\|clear`                      | Atomically advance the private generation, then revoke the replacement incarnation.                                          |
-| Pi               | `session_before_compact`                                         | Revoke before compaction; return `{ cancel: true }` if revocation cannot be confirmed.                                       |
-| Pi               | `session_compact` then the first `context`                       | Arm and run an independent post-compaction revoke. A failed post observer blocks later tools locally until a retry succeeds. |
-| Pi               | `session_start` with reason `reload`, `new`, `resume`, or `fork` | Atomically advance the private generation, then revoke the replacement incarnation before reuse.                             |
-
-The first observer that reaches the broker deletes pending promotion tokens and makes the lease `UNVERIFIED`. The second compaction observer is deliberate redundancy, not a prerequisite for the first. Claudex receives the same mandatory hooks in its isolated `CLAUDE_CONFIG_DIR`; hook merging preserves unrelated isolated settings and rejects malformed or symlinked settings fail-closed.
-
-## Private generation authority
-
-`launch-runtime.py` still registers before `exec`, preserving the kernel-authenticated PID/starttime anchor. It now also creates `generation-<broker-session>.state` beside the broker socket. The file is owner-only mode `0600` under the broker's mode-`0700` directory. Hook descendants read that file instead of relying only on an immutable inherited environment value.
-
-Generation changes use an exclusive file lock, validate owner/type/mode/size, increment monotonically, truncate and write the complete new value, and `fsync` before contacting the broker. Therefore reload, new-session, resume, and fork events may retain the same PID/starttime while still becoming a new broker incarnation. The higher generation causes the broker to atomically discard prior tokens and lease authority; the replacement generation inherits no VERIFIED lease.
-
-If an observer fires while broker transport is unavailable, `revoke-lease.py` advances the private generation as a local fence before returning non-zero. Every later all-tools gate reads that higher value. When the broker is reachable again, authentication of that value performs the same old-generation revocation before authorization. Pi also keeps a process-local post-compaction/rollover failure latch that blocks tool calls. An unsafe or unreadable generation file itself makes both lifecycle revocation and tool authorization fail closed.
-
-## Threat contract and stopping boundary
-
-### BOUNDED RESIDUAL STALE WINDOW
-
-If **both** pre- and post-compaction observers are missed entirely, no revocation signal exists. During the remaining unexpired lease, **within-TTL consequential actions are allowed**. Their count and timing are **bounded by lease expiry, not by the mutator gate**. WI-3 makes no claim that it bounds mutator actions inside this stale interval. The broker's monotonic lease TTL is capped at 300 seconds; after expiry, the next consequential tool is denied with `LEASE_EXPIRED`.
-
-This is the named D2-v5 T-A residual. It is distinct from an observer that fires but cannot contact the broker: the latter creates a local generation fence and fails closed. It is also distinct from T-C total rot, where the lifecycle observers and the all-tools gate are both absent or replaced. Server-side branch protection, required CI, and independent review remain the irreducible backstop for T-C.
-
-| Condition                                                       | Result                                                                                                                |
-| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| Either compaction observer succeeds                             | Existing lease and pending promotion tokens are revoked immediately.                                                  |
-| Observer runs but broker confirmation fails                     | Lifecycle transition is denied where supported; local generation fence and runtime latch prevent inherited authority. |
-| Both observers are missed, lease unexpired                      | **ALLOWED** inside the bounded residual stale window. No within-window mutator bound is claimed.                      |
-| Both observers are missed, lease expired                        | **DENIED** by monotonic TTL expiry.                                                                                   |
-| Generation advances on reload/new/resume/fork                   | Prior incarnation revoked; replacement starts `UNVERIFIED`.                                                           |
-| Lifecycle observers and all-tools gate both fail or are removed | T-C total-hook-miss residual; protected-branch controls remain required.                                              |
-
-## T-C server-side branch-protection posture
-
-The required posture is that `main` is push-blocked and PR-only-merge is **MANDATORY**, regardless
-of client-gate state. The client-side gate narrows the exposure window only; it is not the T-C
-guarantee. The server-side protected-branch configuration is the irreducible guarantee for protected
-repository actions. Status-check enforcement and approval enforcement are **RECOMMENDED**.
-
-## Current-vs-required gap (recorded, not enacted)
-
-The current empirical configuration is recorded here without re-probing or mutating live branch
-protection. `enable_push=False` (push-block present), so the mandatory push-block/PR-only-merge core
-holds. `require_approvals=0` (approvals not enforced), `enable_status_check=False` (status checks not
-enforced), and `block_on_official_review=False` (official review not enforced). Those recommended
-merge-quality controls are the current gap; changing them is a separate, owner-gated operations
-decision and is not enacted by this documentation change.
-
-The permanent T12b/T30 acceptance case prints both required outcomes: dual-hook miss within TTL is **ALLOWED**, and the same lease after TTL is **DENIED**. Separate real-socket tests prove each Claude observer and same-PID generation rollover; Pi lifecycle tests exercise pre/post observers, all four replacement reasons, and local failure closure.

docs/architecture/lease-broker-protocol.md

@@ -1,35 +0,0 @@
-# Authenticated external lease broker protocol
-
-The compaction-refresh lease broker is a Linux-only, newline-framed JSON protocol over a Unix stream socket. It is runtime-neutral; M1 consumers are limited to Claude and Pi. This is an internal process boundary, not an HTTP API, so it is intentionally absent from OpenAPI.
-
-The broker, never the caller, obtains `(pid, uid, gid)` from kernel `SO_PEERCRED`. It correlates the PID with `/proc/<pid>/stat` field 22 (`starttime`) and mints `session_id` on `register_anchor`. Presence of `session_id` in that request is refused even when its value is `null` or empty. Later requests must originate from the anchor or a descendant. The broker walks parent PIDs to the `(pid,starttime)` anchor and then rereads every walked PID's starttime before accepting the chain.
-
-## Request and response boundary
-
-Each connection carries exactly one UTF-8 JSON object followed by one newline, capped at 64 KiB. The protocol deliberately uses EOF to prove that there is exactly one frame: immediately after writing the newline, the client **MUST half-close its write side** with `shutdown(SHUT_WR)` (or Node `socket.end()`) before awaiting the response. A client that writes a newline but leaves its write side open receives no successful response; the broker's one-second connection deadline fails closed. Malformed, unterminated, multiple (including a delayed second frame), or oversized frames fail closed. Responses are one JSON object and one newline. Success has `{"ok":true,...}`; refusal has `{"ok":false,"code":"TYPED_CODE"}`. Requests are:
-
-- `register_anchor`: `action`, non-negative `runtime_generation`; no `session_id` field.
-- `authenticate`: `action`, broker-minted `session_id`, non-negative `runtime_generation`.
-- `mint_token`: authenticated identity plus `binding` containing exactly `compaction_epoch`, `request_epoch`, `h_source`, `h_payload`, and `schema_version`.
-- `consume_token`: authenticated identity plus `token`.
-- `begin_verification`: authenticated identity, runtime (`claude` or `pi`), cycle `binding`, and a TTL no greater than 300 seconds. The broker revokes existing authority first, enters `PENDING_VERIFICATION`, and returns a single-use promotion token.
-- `begin_recovery`: the constrained recovery entrypoint. It rejects caller-provided receipt/challenge fields and delegates to the same `begin_verification` transition, but reports `PENDING_DELIVERY` and marks the volatile cycle as recovery-owned.
-- `complete_recovery`: authenticated identity only. It rejects caller-provided receipt/challenge fields, obtains the current recovery challenge only from broker state, and delegates to the same trusted-observer → evidence → consume → promote sequence. An observation failure revokes recovery authority; retry starts a fresh challenge.
-
-The daemon owns a second protected production observer socket (mode `0600`) unless a private `--test-observer-file` fixture is selected. That transport accepts only the exact `record_runtime_observation` schema after kernel `SO_PEERCRED` plus the existing anchor/ancestry authentication; it validates the pending runtime/generation before storing one finalized assistant entry for the in-process `RuntimeReceiptObserver`. It is **not** a broker request action. Claude sends its latest assistant entry from the Stop-hook transport; Pi sends only finalized `message_end` assistant content. The public broker socket continues to reject request-supplied `latest_assistant_message` in begin, observe, and complete paths.
-
-- `promote_lease`: authenticated identity plus the exact pending promotion token. The broker commits token consumption before making `VERIFIED` visible.
-- `revoke_lease`: authenticated observer signal; deletes pending tokens and makes the session `UNVERIFIED` immediately. WI-3 Claude/Pi hooks send this existing action; `runtime` and bounded `reason` fields are diagnostic input only and never identity authority.
-- `authorize_tool`: authenticated identity, runtime, and exact runtime-reported tool name. The broker returns an explicit allow/deny decision from the whole-class policy and current lease.
-
-A higher generation for the same anchor atomically replaces the stored incarnation and deletes all prior tokens and lease authority for that session. A lower generation is stale. Runtime descendants resolve the current generation from an owner-only, locked generation file created by the register-before-exec launcher; reload/new/resume/fork observers advance and `fsync` it before broker revocation. This supports generation replacement even when PID/starttime do not change. Tokens are 256-bit values from the operating-system cryptographic RNG and are single use. At most 256 pending tokens may be persisted; another mint fails with `TOKEN_CAPACITY` before mutation. Successful consumption deletes the token, while a replay still fails with `TOKEN_REPLAY`. Live v1 token records retain the existing `consumed: false` schema.
-
-VERIFIED leases are volatile and monotonic-time bounded: broker restart, generation change, explicit observer revocation, or expiry returns the session to `UNVERIFIED`. `begin_verification` always revokes before minting a new prerequisite. `begin_recovery` reuses that exact transition and mints a new challenge, so a normal-path receipt/challenge cannot be replayed through recovery. `promote_lease` is valid only from the matching pending cycle; persistence failure rolls token and lease state back, while post-rename durability uncertainty terminates the broker. The WI-1 token is the atomic promotion prerequisite substrate.
-
-## Receipt boundary and T-C residual (R1)
-
-Receipt evidence is a T-A delivery/liveness prerequisite only; it cannot replace the mechanical
-mutator gate as safety authority. The receipt detects an **ABSENT** or **PREFIX-TRUNCATED** terminal
-token. A **MIDDLE-DROP** that preserves the tail is a T-C contract violation that is **NOT receipt-detectable**. It is covered by server-side protected-branch controls, **NOT** by the receipt; no category-wide receipt-detection claim is made for that tail-preserving transformation.
-
-State replacement serializes and enforces the 4 MiB maximum before opening a temporary file, then uses a mode-`0600` temporary file, `fsync`, atomic rename, and parent-directory `fsync`. Every broker mutation snapshots the prior v1 state. A commit failure before rename restores that snapshot and leaves durable state unchanged. A failure after rename makes durability uncertain, so the store is poisoned without rolling memory back and the daemon terminates rather than serving with divergent state. Existing state is opened without following symlinks, must be a bounded regular file at mode `0600`, and is fully schema- and invariant-validated before use. Persisted tokens must be unconsumed, match their session's current generation, and remain within the 256-token cap. Session identity is uniquely keyed by `(anchor_pid,anchor_starttime)`; duplicate logical sessions for one anchor refuse startup. State integrity or mode failures refuse startup. The daemon does not log session IDs or tokens.

docs/architecture/lease-broker-security.md

@@ -1,26 +0,0 @@
-# WI-1 lease broker security notes
-
-- Trusted identity comes only from Linux `SO_PEERCRED` plus `/proc` starttime, never request identity fields.
-- Descendant authorization is anchored to `(pid,starttime)` and uses a complete second starttime pass to fail closed on disappearance or PID-reuse races.
-- Runtime generations are monotonic per anchor; a bump revokes prior-incarnation tokens before persistence commits. WI-3 stores the live generation in an owner-only locked file so same-PID Pi reload/new/resume/fork and Claude resume/clear transitions cannot inherit a VERIFIED lease.
-- Session IDs and cycle tokens use the OS cryptographic RNG. `Math.random` and model output are not token sources.
-- Framing and persistence failures fail closed. Sensitive tokens are not logged.
-- Built-in `0700`/`0600` filesystem modes provide same-principal hardening only, not socket authenticity against the same UID. WI-1 provides no distinct-principal isolation. That stronger deployment requires an external protected proxy, ACL, or service boundary, and the boundary must preserve authenticated client identity for the broker's `SO_PEERCRED` and ancestry authorization rather than substituting a shared proxy identity.
-- WI-2 whole-class authorization denies every consequential, unknown, and custom tool while UNVERIFIED; it does not inspect shell strings or trust wrapper selection. First-class Claude/Pi, both Claudex dispatch modes, PRDY, QA remediation, coord, orchestrator, and fleet starts converge on broker register-before-exec; Claudex additionally installs the mandatory all-tools hook inside its preserved isolated config and fails closed on unsafe settings.
-- The permanent `check-runtime-launches.py` suite/CI guard scans production source for direct literal, absolute-path, process-API, command-array, and dynamic Claude/Pi launches. It has no bypass allowlist: an unrecognized launch form fails CI until routed through the common boundary.
-- WI-2 promotion consumes a WI-1 cycle token before VERIFIED becomes visible. Observer revocation, runtime-generation replacement, broker restart, and monotonic TTL expiry remove authority.
-- WI-3 wires redundant Claude `PreCompact`/`SessionStart(compact)` and Pi `session_before_compact`/post-`session_compact` `context` observers to that same revoke action. If broker confirmation fails after an observer fires, the revoker advances the private generation as a local fence; subsequent authorization revokes the stale broker incarnation before any consequential allow.
-- Dual observer absence while a lease remains live is the named **bounded residual stale window**: consequential tools remain allowed until monotonic expiry, with no claimed within-window action bound. After expiry they are denied. Total observer-plus-gate absence remains T-C.
-- Receipt observation, payload construction, and constrained recovery implementation remain later surfaces. A receipt can become a promotion prerequisite but is never the safety mechanism.
-
-## Named residual: promote-lease-lost-ACK (WI-3 D2-v5)
-
-A valid `promote_lease` can leave a session `VERIFIED` in the broker while the client never learns of it. This is a named, bounded D2-v5 T-A residual — an **authority-observability divergence, not an authority divergence, not an ALLOW-risk, and not a retry double-apply**. It is disclosed here, not laundered.
-
-**Window — where it can occur.** The broker commits token consumption and durable `VERIFIED` state _before_ the success reply becomes visible (see the promotion order in `lease-broker-protocol.md`). The residual is confined to the interval after that commit+fsync when the broker→client reply or peer-ACK is lost — for example an extreme-contention send failure or peer disconnect after `handle()` has already mutated and persisted state (the #838 fail-closed transport path). The lease mutation is already durable broker-side; only the acknowledgement to the client is lost. No uncommitted or partially-applied state is involved: the commit either happened (and is authoritative) or it did not (and no lease exists).
-
-**Fail-safe direction — the client can only under-claim.** Broker intent is the ceiling; client authority is always ≤ broker intent, never more. Client-side authority-belief is granted only by a _received_ acknowledgement; a lost acknowledgement conveys nothing, so the client cannot conclude "verified" and continues to treat itself as `UNVERIFIED` (it re-verifies or recovers). If the client retries `promote_lease` with the same token, the token is already consumed and the broker rejects the retry (`PROMOTION_TOKEN_MISMATCH` / `INVALID_LEASE_TRANSITION`); there is no double-apply. The committed `VERIFIED` state the broker holds is authority the lease _legitimately earned_ from a real promotion — the broker authorizing consequential tools under it is correct, not inflation. Divergence is therefore strictly toward _less_ client authority than the broker granted; it never produces authority the broker did not grant.
-
-**Bound — TTL plus the observer/gen-bump revoke backstop, self-healing.** The orphaned `VERIFIED` lease is indistinguishable to the broker from any other legitimately verified lease, so the identical D2-v5 revocation backstops dispose of it: any compaction observer (`PreCompact` / `SessionStart(compact)` for Claude; `session_before_compact` / post-`session_compact` `context` for Pi), any same-PID runtime-generation bump (reload/new/resume/fork), broker restart, or monotonic-time expiry returns the session to `UNVERIFIED`. Monotonic TTL expiry (capped at 300 seconds) is **unconditional** — it requires no observer at all — so the maximum exposure of the orphaned lease is one TTL, ≤ 300 s, after which the next consequential tool is denied with `LEASE_EXPIRED`. Any observer that fires shortens the window further. The residual self-heals: "≥1 observer fires OR expiry ⇒ revoke" catches the lost-ACK lease on the same terms as every other stale lease. As with the dual-observer-miss stale window, WI-3 makes no claim that the mutator gate bounds actions inside the residual interval; the interval is bounded by TTL and the revoke backstop, and the server-side branch-protection / required-CI / independent-review line remains the irreducible backstop for protected-repository mutations.
-
-Coordinator security review must rerun the real socket/peercred and mutator-gate acceptance suites on an unrestricted Linux runner and obtain the mandated independent Opus-SECREV review before integration.

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

@@ -1,49 +0,0 @@
-# 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/architecture/mutator-class-gate.md

@@ -1,72 +0,0 @@
-# Whole mutator-class lease gate
-
-WI-2 adds the framework-native authorization boundary for Claude (including the supported Claudex overlay) and Pi. Every runtime-reported tool name reaches the lease broker before execution. The gate classifies capabilities by the whole tool class; it never parses a Bash command to decide whether that particular string looks read-only.
-
-## Default-deny policy
-
-While a session is not VERIFIED, only these exact classes are allowed:
-
-- Claude: `Read`, `Grep`, `Glob`, `Ls`, `Find`
-- Pi: `read`, `grep`, `find`, `ls`
-- Both runtimes: the fixed `mosaic_context_recover` primitive
-
-Every other built-in, unknown tool, and custom/MCP tool is consequential by default and is denied. This includes Claude `Bash`, `Edit`, `Write`, and `NotebookEdit`, plus Pi `bash`, `edit`, and `write`. A compromised model therefore cannot bypass Mosaic wrappers by selecting raw `git`, `curl`, `kubectl`, provider, deployment, or filesystem commands inside a generic mutator—the generic mutator itself is blocked before its input executes.
-
-## Broker-owned transition order
-
-The authenticated broker is the sole lease writer:
-
-1. `begin_verification` revokes existing authority and pending tokens first, then records `PENDING_VERIFICATION` and mints one WI-1 single-use promotion token bound to the exact cycle.
-2. `promote_lease` accepts only that session/generation/binding/token combination.
-3. Token consumption commits before the volatile lease becomes VERIFIED. Promotion is last and cannot be reached directly from UNVERIFIED.
-4. `revoke_lease`, a runtime-generation increase, broker restart, or monotonic expiry removes mutator authority.
-
-The initial TTL is capped at the ratified 300-second maximum. A caller may request a shorter positive TTL but cannot lengthen the maximum. WI-3 installs the [compaction observer and generation lifecycle](compaction-revocation.md). Dual compaction-hook miss within an unexpired lease remains the ratified bounded T-A residual: consequential tools are allowed until expiry, with no claimed within-window action bound; once either observer revokes or TTL expires, the next consequential tool is denied.
-
-A receipt is only a future promotion prerequisite. It is not an obedience, residency, or safety proof and never replaces this mechanical gate.
-
-## Runtime adapters
-
-`launch-runtime.py` registers itself with the broker and then `exec`s Claude or Pi so PID/starttime remain the authenticated parent anchor. It exports the broker-minted session ID and an owner-only generation-file reference to descendants; lifecycle hooks advance that file for same-PID replacement generations.
-
-- Claude installs `mutator-gate.py` as an all-tools (`.*`) `PreToolUse` hook.
-- `mosaic claudex` and `mosaic yolo claudex` preserve their isolated `CLAUDE_CONFIG_DIR`, merge the mandatory hook into that isolated `settings.json`, and use the same register-before-exec launcher. Malformed or symlinked isolated settings deny launch.
-- Pi invokes the same executable from its `tool_call` handler.
-
-The executable submits the runtime's actual tool name to `authorize_tool`. Missing identity, malformed input/reply, timeout, broker unavailability, or denial exits with status 2 and blocks fail-closed.
-
-## Runtime-launch choke-point and permanent guard
-
-Every repository-owned Claude/Pi launch entry converges on `launch-runtime.py`, either directly or through `mosaic` → `execLeaseGatedRuntime`. PRDY init/update and QA remediation invoke the wrapper directly so their existing prompts, dangerous-permission behavior, working directory, and environment survive without skipping broker registration. The raw Claude `--dangerously-skip-permissions` primitive is owned only by `launch-runtime.py`; callers request semantic `--dangerous` mode, and the wrapper validates Claude before injecting the primitive. `@mosaicstack/coord` rewrites direct Claude commands to `mosaic claude` and rejects unknown custom Claude launchers.
-
-`check-runtime-launches.py` is the permanent completeness guard. It scans production shell, TypeScript/JavaScript, Python, and data launch definitions under `packages/`, `apps/`, `plugins/`, and `tools/`; direct literal, absolute-path, process-API, dynamic, command-substitution, `eval`, and variable-execution runtime launches fail. Shell comments are stripped with quote awareness, wrapper prefixes are tokenized with `shlex`, and only an invocation in command position with `--runtime` before the command separator is gated. Literal and tracked-variable command tokens use one terminal resolver after any nesting of `exec`, `command`, `nohup`, or `env` plus assignments. A direct command always wins over an inert marker on the same line. Independently, the raw dangerous primitive anywhere outside the choke-point is RED.
-
-The command parser is a best-effort CI defense, not a complete shell interpreter. Alias/function redefinition, sourced commands, generated scripts, and encoded pipelines are intentionally residual rather than an invitation to chase an unbounded shell language. Two runtime controls backstop that residual surface: primitive ownership rejects a dangerous launch even when command identity is alias-indirected, and Claude's global `.*` `PreToolUse` hook invokes the broker gate for non-dangerous launches. Without `MOSAIC_LEASE_SESSION_ID`, representative read, mutator, and custom/MCP tools all fail closed with `GATE_UNAVAILABLE`. Hook absence or replacement remains in the documented T-C boundary.
-
-### Parser stopping criterion
-
-- **A — realistic parser matrix:** comments, inert strings/assignments, heredocs, continuations, chained commands, command substitution, `eval`, bare tracked variables, and quoted/unquoted tracked variables behind `exec`, `command`, `nohup`, or `env` are permanent RED regressions. Prefix-variable forms are covered in both multiline and same-line assignment shapes.
-- **B — residual backstops:** a dangerous alias-indirected launch is RED solely through primitive anchoring; a parser-missed non-dangerous alias launch is paired with an acceptance test proving the global all-tools hook denies every representative tool class as `GATE_UNAVAILABLE` without a lease.
-- **C — independent fresh review:** the parser class is considered complete only when reviewers find no new non-overlapping realistic evasion on the exact head. A and B are repository evidence; C is supplied by the fresh review round.
-
-All three layers are load-bearing and complementary. The guard is mandatory in `@mosaicstack/mosaic`'s test script, so root CI fails on a future realistic bypass. Real-socket tests separately prove PRDY init/update and QA receive broker sessions and deny an unverified mutator.
-
-The live inventory is emitted by:
-
-```bash
-python3 packages/mosaic/framework/tools/lease-broker/check-runtime-launches.py --root . --json
-```
-
-| Production launch family                               | Gated entries |
-| ------------------------------------------------------ | ------------: |
-| `@mosaicstack/coord` default/configured Claude command |             2 |
-| Fleet runtime start                                    |             1 |
-| QA remediation + generated QA command                  |             2 |
-| Orchestrator command construction/session launches     |             3 |
-| PRDY init/update                                       |             2 |
-| Mosaic Claude/Pi/Claudex adapter and wrapper boundary  |             4 |
-| **Total**                                              |   **14 / 14** |
-
-## Assurance boundary
-
-This closes T-A after an observer fires or lease expiry and T-B for in-runtime tool calls. Hook/extension absence, a runtime executing outside the gated launcher, ptrace/same-UID broker replacement, and other fully rotted behavior remain T-C. Server-side branch protection and required PR review/CI remain the irreducible line for protected repository mutations.

docs/compaction-refresh/probes/p5_receipt_replay.py

@@ -1,228 +0,0 @@
-#!/usr/bin/env python3
-"""P5 Gate0 replay probe; BUILT ONLY, execution is Mos-gated.
-
-Run only under fresh-executor authorization:
-  python3 -I -S -B docs/compaction-refresh/probes/p5_receipt_replay.py
-
-Each of the default three isolated runs launches the shipped lease-broker daemon
-in a distinct private temporary directory.  This driver never changes broker
-state directly and does not replace the promote gate: every transition is sent
-over the daemon's real Unix socket.  It proves the shipped order is
-PENDING_DELIVERY -> observe/evidence commit -> consume -> VERIFIED and that a
-consumed challenge cannot be replayed or reopen/renew its lease.
-"""
-
-from __future__ import annotations
-
-import argparse
-import base64
-import importlib.util
-import json
-import os
-import shutil
-import socket
-import subprocess
-import sys
-import tempfile
-import time
-from pathlib import Path
-
-
-HERE = Path(__file__).resolve().parent
-REPOSITORY = HERE.parents[2]
-TOOLS = REPOSITORY / "packages/mosaic/framework/tools/lease-broker"
-DAEMON = TOOLS / "daemon.py"
-FRAGMENTS = TOOLS / "normative_fragments.py"
-
-
-def load_shipped_fragments():
-    if not FRAGMENTS.is_file():
-        raise RuntimeError(f"shipped normative construction missing: {FRAGMENTS}")
-    spec = importlib.util.spec_from_file_location("p5_shipped_normative_fragments", FRAGMENTS)
-    if spec is None or spec.loader is None:
-        raise RuntimeError("unable to load shipped normative construction")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def request(socket_path: Path, value: dict[str, object]) -> dict[str, object]:
-    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
-        connection.settimeout(3.0)
-        connection.connect(str(socket_path))
-        connection.sendall((json.dumps(value, separators=(",", ":")) + "\n").encode())
-        connection.shutdown(socket.SHUT_WR)
-        response = bytearray()
-        while True:
-            chunk = connection.recv(4096)
-            if not chunk:
-                break
-            response.extend(chunk)
-    if not response.endswith(b"\n") or response.count(b"\n") != 1:
-        raise AssertionError(f"unframed broker reply: {bytes(response)!r}")
-    parsed = json.loads(response[:-1])
-    if not isinstance(parsed, dict):
-        raise AssertionError(f"non-object broker reply: {parsed!r}")
-    return parsed
-
-
-def wait_ready(process: subprocess.Popen[str], socket_path: Path) -> None:
-    deadline = time.monotonic() + 5.0
-    while time.monotonic() < deadline:
-        if socket_path.exists():
-            return
-        if process.poll() is not None:
-            output = process.stdout.read() if process.stdout is not None else ""
-            raise RuntimeError(f"shipped daemon exited before READY: {output}")
-        time.sleep(0.02)
-    raise TimeoutError("shipped daemon did not create private probe socket")
-
-
-def expect_refused(reply: dict[str, object], code: str) -> None:
-    if reply != {"ok": False, "code": code}:
-        raise AssertionError(f"expected refusal {code}, got {reply!r}")
-
-
-def run_once(index: int) -> str:
-    fragments = load_shipped_fragments()
-    root = Path(tempfile.mkdtemp(prefix=f"mosaic-p5-replay-{index}-"))
-    os.chmod(root, 0o700)
-    socket_path = root / "broker.sock"
-    state_path = root / "state.json"
-    observer_path = root / "test-observer.json"
-    process = subprocess.Popen(
-        [
-            sys.executable, "-I", "-S", "-B", str(DAEMON), "--socket", str(socket_path),
-            "--state", str(state_path), "--test-observer-file", str(observer_path),
-        ],
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-    )
-    try:
-        wait_ready(process, socket_path)
-        registered = request(socket_path, {"action": "register_anchor", "runtime_generation": 1})
-        if registered.get("ok") is not True or not isinstance(registered.get("session_id"), str):
-            raise AssertionError(f"registration failed: {registered!r}")
-        session_id = registered["session_id"]
-        construction = fragments.build_payload(
-            manifest_version=1,
-            generator_version="p5-replay-probe",
-            fragments=[
-                fragments.NormativeFragment(
-                    "authority/probe",
-                    b"P5 shipped transition driver\n",
-                    "63537df1a6cb0d80195a96757ab11d629e5b5e1f23be167218b84cb195b1c1d6",
-                ),
-            ],
-        )
-        if construction.injectionDecision != "ACCEPTED" or not construction.promotion:
-            raise AssertionError("shipped normative construction refused P5 fixture")
-        binding = {
-            "compaction_epoch": index,
-            "request_epoch": index + 100,
-            "h_source": construction.h_source,
-            "h_payload": construction.h_payload,
-            "schema_version": 1,
-        }
-        construction_request = {
-            "manifest_version": 1,
-            "generator_version": "p5-replay-probe",
-            "fragments": [{
-                "source_id": "authority/probe",
-                "content_base64": base64.b64encode(b"P5 shipped transition driver\n").decode("ascii"),
-                "expected_sha256": "63537df1a6cb0d80195a96757ab11d629e5b5e1f23be167218b84cb195b1c1d6",
-            }],
-        }
-        pending = request(socket_path, {
-            "action": "begin_verification",
-            "session_id": session_id,
-            "runtime_generation": 1,
-            "runtime": "pi",
-            "binding": binding,
-            "construction": construction_request,
-        })
-        if pending.get("ok") is not True or pending.get("state") != "PENDING_VERIFICATION":
-            raise AssertionError(f"shipped pending-delivery transition failed: {pending!r}")
-        challenge = pending.get("receipt_challenge")
-        receipt = pending.get("receipt")
-        if not isinstance(challenge, str) or not isinstance(receipt, str):
-            raise AssertionError(f"shipped broker did not mint a receipt challenge: {pending!r}")
-
-        # Promotion before observation/evidence/consumption is forbidden.
-        expect_refused(request(socket_path, {
-            "action": "promote_lease",
-            "session_id": session_id,
-            "runtime_generation": 1,
-            "receipt_challenge": challenge,
-        }), "INVALID_LEASE_TRANSITION")
-
-        observer_path.write_text(json.dumps({
-            "session_id": session_id,
-            "runtime_generation": 1,
-            "latest_assistant_message": receipt,
-        }), encoding="utf-8")
-        os.chmod(observer_path, 0o600)
-        observed = request(socket_path, {
-            "action": "observe_receipt",
-            "session_id": session_id,
-            "runtime_generation": 1,
-            "receipt_challenge": challenge,
-        })
-        if observed.get("ok") is not True or observed.get("state") != "PENDING_PROMOTION":
-            raise AssertionError(f"shipped evidence transition failed: {observed!r}")
-        durable = json.loads(state_path.read_text(encoding="utf-8"))
-        evidence = durable["tokens"][challenge].get("evidence")
-        if not isinstance(evidence, dict) or not isinstance(evidence.get("h_latest_assistant"), str):
-            raise AssertionError("shipped receipt evidence was not committed before consume/promote")
-
-        promoted = request(socket_path, {
-            "action": "promote_lease",
-            "session_id": session_id,
-            "runtime_generation": 1,
-            "receipt_challenge": challenge,
-        })
-        if promoted.get("ok") is not True or promoted.get("state") != "VERIFIED":
-            raise AssertionError(f"shipped consume-before-promote transition failed: {promoted!r}")
-
-        # T25/T28: the actual consumed challenge, re-presented through the
-        # shipped daemon, can neither be observed again nor re-promote/reopen.
-        expect_refused(request(socket_path, {
-            "action": "observe_receipt",
-            "session_id": session_id,
-            "runtime_generation": 1,
-            "receipt_challenge": challenge,
-        }), "RECEIPT_REPLAY")
-        expect_refused(request(socket_path, {
-            "action": "promote_lease",
-            "session_id": session_id,
-            "runtime_generation": 1,
-            "receipt_challenge": challenge,
-        }), "RECEIPT_REPLAY")
-        return challenge
-    finally:
-        if process.poll() is None:
-            process.terminate()
-            try:
-                process.wait(timeout=3.0)
-            except subprocess.TimeoutExpired:
-                process.kill()
-                process.wait()
-        shutil.rmtree(root, ignore_errors=True)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--runs", type=int, default=3)
-    arguments = parser.parse_args()
-    if arguments.runs != 3:
-        raise SystemExit("P5 requires exactly three isolated runs")
-    challenges = [run_once(index) for index in range(arguments.runs)]
-    if len(set(challenges)) != arguments.runs:
-        raise AssertionError("separate shipped cycles did not mint unique challenges")
-    print("P5 receipt replay probe PASS: 3 isolated shipped-daemon runs")
-
-
-if __name__ == "__main__":
-    main()

docs/compaction-refresh/probes/p6_constrained_recovery.py

@@ -1,255 +0,0 @@
-#!/usr/bin/env python3
-"""P6 constrained-recovery probe; BUILT ONLY and Mos-gated.
-
-DO NOT self-fire. Under Mos authorization only:
-  python3 -I -S -B docs/compaction-refresh/probes/p6_constrained_recovery.py
-
-The default three isolated runs launch the shipped daemon plus its production
-observer transport on private sockets. The driver invokes the shipped recovery
-command and adapter gate identity; it never resets broker state, mocks promote,
-or taps a live model-output stream.
-"""
-
-from __future__ import annotations
-
-import argparse
-import base64
-import hashlib
-import importlib.util
-import json
-import os
-import shutil
-import socket
-import subprocess
-import sys
-import tempfile
-import time
-from pathlib import Path
-
-
-HERE = Path(__file__).resolve().parent
-REPOSITORY = HERE.parents[2]
-TOOLS = REPOSITORY / "packages/mosaic/framework/tools/lease-broker"
-DAEMON = TOOLS / "daemon.py"
-GATE = TOOLS / "mutator-gate.py"
-RECOVERY_COMMAND = TOOLS / "recover-context.py"
-OBSERVER_CLIENT = TOOLS / "receipt-observer-client.py"
-FRAGMENTS = TOOLS / "normative_fragments.py"
-CLAUDE_SETTINGS = REPOSITORY / "packages/mosaic/framework/runtime/claude/settings.json"
-PI_EXTENSION = REPOSITORY / "packages/mosaic/framework/runtime/pi/mosaic-extension.ts"
-
-
-def load_shipped_fragments():
-    spec = importlib.util.spec_from_file_location("p6_shipped_fragments", FRAGMENTS)
-    if spec is None or spec.loader is None:
-        raise RuntimeError("shipped normative construction unavailable")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def request(socket_path: Path, value: dict[str, object]) -> dict[str, object]:
-    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
-        connection.settimeout(3.0)
-        connection.connect(str(socket_path))
-        connection.sendall((json.dumps(value, separators=(",", ":")) + "\n").encode())
-        connection.shutdown(socket.SHUT_WR)
-        response = bytearray()
-        while True:
-            chunk = connection.recv(4096)
-            if not chunk:
-                break
-            response.extend(chunk)
-    if not response.endswith(b"\n") or response.count(b"\n") != 1:
-        raise AssertionError(f"unframed broker reply: {bytes(response)!r}")
-    reply = json.loads(response[:-1])
-    if not isinstance(reply, dict):
-        raise AssertionError("broker reply is not an object")
-    return reply
-
-
-def wait_ready(process: subprocess.Popen[str], socket_path: Path) -> None:
-    deadline = time.monotonic() + 5.0
-    while time.monotonic() < deadline:
-        if socket_path.exists():
-            return
-        if process.poll() is not None:
-            output = process.stdout.read() if process.stdout is not None else ""
-            raise RuntimeError(f"shipped daemon exited before READY: {output}")
-        time.sleep(0.02)
-    raise TimeoutError("shipped daemon did not create private probe socket")
-
-
-def run_json(command: list[str], environment: dict[str, str], input_value: object | None = None) -> dict[str, object]:
-    completed = subprocess.run(
-        command,
-        input=None if input_value is None else json.dumps(input_value),
-        text=True,
-        capture_output=True,
-        env=environment,
-        check=False,
-    )
-    if not completed.stdout.endswith("\n"):
-        raise AssertionError(f"command omitted framed result: {completed.stderr!r}")
-    reply = json.loads(completed.stdout)
-    if not isinstance(reply, dict):
-        raise AssertionError("command result is not an object")
-    return reply
-
-
-def gate_recovery(runtime: str, phase: str, environment: dict[str, str]) -> None:
-    command = [sys.executable, "-I", "-S", "-B", str(GATE), "--runtime", runtime]
-    if runtime == "claude":
-        command.extend(["--recovery-command", str(RECOVERY_COMMAND)])
-        recovery_invocation = (
-            f"python3 {RECOVERY_COMMAND} begin --construction /tmp/p6.json "
-            "--compaction-epoch 1 --request-epoch 1"
-            if phase == "begin"
-            else f"python3 {RECOVERY_COMMAND} complete"
-        )
-        value = {"tool_name": "Bash", "tool_input": {"command": recovery_invocation}}
-    else:
-        value = {"tool_name": "mosaic_context_recover"}
-    completed = subprocess.run(command, input=json.dumps(value), text=True, capture_output=True, env=environment, check=False)
-    if completed.returncode != 0:
-        raise AssertionError(f"{runtime} recovery invocation remained gated: {completed.stderr!r}")
-
-
-def record_production_observation(runtime: str, message: str, root: Path, environment: dict[str, str]) -> None:
-    command = [sys.executable, "-I", "-S", "-B", str(OBSERVER_CLIENT), "--runtime", runtime]
-    if runtime == "claude":
-        transcript = root / "claude-transcript.jsonl"
-        transcript.write_text(json.dumps({"message": {"role": "assistant", "content": message}}) + "\n", encoding="utf-8")
-        payload = {"transcript_path": str(transcript)}
-        command.append("--latest-entry")
-    else:
-        payload = {"latest_assistant_message": message}
-    completed = subprocess.run(command, input=json.dumps(payload), text=True, capture_output=True, env=environment, check=False)
-    if completed.returncode != 0:
-        raise AssertionError(f"{runtime} production observer transport refused: {completed.stderr!r}")
-
-
-def run_once(index: int, runtime: str) -> None:
-    # Parity guard: drive the shipped command and the repaired adapter/observer
-    # bytes, not a shadow receipt or promotion implementation.
-    recovery_source = RECOVERY_COMMAND.read_text(encoding="utf-8")
-    if '"action": "begin_recovery"' not in recovery_source or '"action": "complete_recovery"' not in recovery_source:
-        raise AssertionError("P6 parity guard: recovery command no longer drives shipped broker entrypoints")
-    gate_source = GATE.read_text(encoding="utf-8")
-    if "--recovery-command" not in CLAUDE_SETTINGS.read_text(encoding="utf-8"):
-        raise AssertionError("P6 parity guard: Claude recovery mapping is missing")
-    if "_SHELL_ACTIVE" not in gate_source or "argv[1] != str(recovery_command)" not in gate_source:
-        raise AssertionError("P6 parity guard: Claude mapping is not literal-only")
-    if "const RECOVERY_TOOL = 'mosaic_context_recover'" not in PI_EXTENSION.read_text(encoding="utf-8"):
-        raise AssertionError("P6 parity guard: Pi recovery tool mapping is missing")
-
-    fragments = load_shipped_fragments()
-    root = Path(tempfile.mkdtemp(prefix=f"mosaic-p6-recovery-{index}-"))
-    os.chmod(root, 0o700)
-    socket_path = root / "broker.sock"
-    observer_socket = root / "observer.sock"
-    state_path = root / "state.json"
-    construction_path = root / "construction.json"
-    content = b"P6 constrained recovery fixture\n"
-    construction = {
-        "manifest_version": 1,
-        "generator_version": "p6-constrained-recovery",
-        "fragments": [{
-            "source_id": "authority/p6",
-            "content_base64": base64.b64encode(content).decode("ascii"),
-            "expected_sha256": hashlib.sha256(content).hexdigest(),
-        }],
-    }
-    construction_path.write_text(json.dumps(construction), encoding="utf-8")
-    os.chmod(construction_path, 0o600)
-    process = subprocess.Popen(
-        [sys.executable, "-I", "-S", "-B", str(DAEMON), "--socket", str(socket_path),
-         "--state", str(state_path), "--observer-socket", str(observer_socket)],
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-    )
-    try:
-        wait_ready(process, socket_path)
-        registered = request(socket_path, {"action": "register_anchor", "runtime_generation": 1})
-        session_id = registered.get("session_id")
-        if registered.get("ok") is not True or not isinstance(session_id, str):
-            raise AssertionError(f"broker anchor registration failed: {registered!r}")
-        built = fragments.build_payload_from_wire(construction)
-        normal = request(socket_path, {
-            "action": "begin_verification", "session_id": session_id, "runtime_generation": 1,
-            "runtime": runtime, "construction": construction,
-            "binding": {"compaction_epoch": index, "request_epoch": index + 100,
-                        "h_source": built.h_source, "h_payload": built.h_payload, "schema_version": 1},
-        })
-        normal_challenge = normal.get("receipt_challenge")
-        normal_receipt = normal.get("receipt")
-        if not isinstance(normal_challenge, str) or not isinstance(normal_receipt, str):
-            raise AssertionError("normal path did not mint a receipt challenge")
-        environment = {
-            **os.environ,
-            "MOSAIC_LEASE_BROKER_SOCKET": str(socket_path),
-            "MOSAIC_RECEIPT_OBSERVER_SOCKET": str(observer_socket),
-            "MOSAIC_LEASE_SESSION_ID": session_id,
-            "MOSAIC_RUNTIME_GENERATION": "1",
-            "MOSAIC_LEASE_RUNTIME": runtime,
-        }
-        gate_recovery(runtime, "begin", environment)
-        recovery = run_json([
-            sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "begin", "--construction", str(construction_path),
-            "--compaction-epoch", str(index + 10), "--request-epoch", str(index + 110),
-        ], environment)
-        challenge = recovery.get("receipt_challenge")
-        receipt = recovery.get("receipt")
-        if recovery.get("state") != "PENDING_DELIVERY" or not isinstance(challenge, str) or not isinstance(receipt, str):
-            raise AssertionError(f"recovery command did not drive pending delivery: {recovery!r}")
-        if challenge == normal_challenge:
-            raise AssertionError("recovery reused a normal-path challenge")
-
-        # C4: production observer content is still exact-current-cycle only.
-        record_production_observation(runtime, normal_receipt, root, environment)
-        refused = run_json([sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "complete"], environment)
-        if refused.get("ok") is not False or refused.get("code") != "RECEIPT_MISMATCH":
-            raise AssertionError(f"normal-path receipt replay was not refused: {refused!r}")
-
-        gate_recovery(runtime, "begin", environment)
-        recovery = run_json([
-            sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "begin", "--construction", str(construction_path),
-            "--compaction-epoch", str(index + 20), "--request-epoch", str(index + 120),
-        ], environment)
-        receipt = recovery.get("receipt")
-        if recovery.get("state") != "PENDING_DELIVERY" or not isinstance(receipt, str):
-            raise AssertionError(f"fresh recovery retry did not pend: {recovery!r}")
-        record_production_observation(runtime, receipt, root, environment)
-        gate_recovery(runtime, "complete", environment)
-        promoted = run_json([sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "complete"], environment)
-        if promoted.get("ok") is not True or promoted.get("state") != "VERIFIED":
-            raise AssertionError(f"recovery consume-before-promote failed: {promoted!r}")
-        replay = run_json([sys.executable, "-I", "-S", "-B", str(RECOVERY_COMMAND), "complete"], environment)
-        if replay.get("ok") is not False or replay.get("code") != "INVALID_LEASE_TRANSITION":
-            raise AssertionError(f"consumed recovery challenge re-promoted: {replay!r}")
-    finally:
-        if process.poll() is None:
-            process.terminate()
-            try:
-                process.wait(timeout=3.0)
-            except subprocess.TimeoutExpired:
-                process.kill()
-                process.wait()
-        shutil.rmtree(root, ignore_errors=True)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--runs", type=int, default=3)
-    arguments = parser.parse_args()
-    if arguments.runs != 3:
-        raise SystemExit("P6 requires exactly three isolated runs")
-    for index, runtime in enumerate(("pi", "claude", "pi")):
-        run_once(index, runtime)
-    print("P6 constrained recovery probe PASS: 3 isolated shipped recovery-command runs")
-
-
-if __name__ == "__main__":
-    main()

docs/design/791-upgrade-config-protection.md

@@ -1,290 +0,0 @@
-# Design — #791: Framework upgrades must not destroy operator-owned config under `~/.config/mosaic`
-
-- **Issue:** mosaicstack/stack#791
-- **Branch:** `feat/791-upgrade-config-protection` (off `origin/main` `9745bc3f`)
-- **Author:** ms-791 worker lane
-- **Status:** Phase 1 — DESIGN, awaiting MS-LEAD confirmation before implementation
-- **Ratified scope (Mos-approved, not re-litigated):** deliver **(b) strict ownership separation [PRIMARY]** + **(a) transactional pre-update snapshot [safety net]** + **(d) regeneration-from-SSOT [recovery]**. **(c) periodic backup timer is DEFERRED** — noted as future work only.
-
----
-
-## 1. Current updater behavior + exact wipe mechanism (evidence)
-
-### 1.1 What runs on `mosaic update`
-
-`mosaic update` re-seeds the framework by invoking the **bash installer** in sync-only, keep mode:
-
-- `packages/mosaic/src/runtime/update-checker.ts:509` `buildReseedCommand()` returns
-  `bash <frameworkRoot>/install.sh` with env `MOSAIC_SYNC_ONLY=1`, `MOSAIC_INSTALL_MODE=keep`,
-  `MOSAIC_HOME=<mosaicHome>`.
-- The same `install.sh` is the direct/`tools/install.sh` upgrade path and the framework-vN migration path.
-
-So the destructive surface is **`packages/mosaic/framework/install.sh`**.
-
-### 1.2 The wipe
-
-`sync_framework()` (`install.sh:177`) performs, in `keep` mode:
-
-```
-rsync -a --delete --exclude .git --exclude .framework-version --exclude '*.pre-constitution.bak' \
-      [--exclude "/$path" for each PRESERVE_PATHS entry] SOURCE_DIR/ TARGET_DIR/
-```
-
-- `install.sh:199` — `rsync -a --delete`. **`--delete` prunes every path in `~/.config/mosaic`
-  that is NOT present in the shipped framework source**, unless excluded.
-- `install.sh:47` — `PRESERVE_PATHS` is the **only** thing standing between `--delete` and operator
-  data. It is a _denylist of exclusions_:
-  ```
-  PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md"
-    "memory" "sources" "credentials" "fleet/roster.yaml" "fleet/roster.json" "fleet/agents"
-    "fleet/run" "fleet/backlog" "fleet/roles.local")
-  ```
-- The cp-fallback (no rsync) is equally destructive: `install.sh:223`
-  `find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ... -exec rm -rf {} +` then re-copies source, restoring
-  only PRESERVE_PATHS globs.
-
-**Root-cause model:** _"Everything under `~/.config/mosaic` is framework-owned and pruneable UNLESS
-explicitly preserved."_ Any operator path the list forgets is destroyed on the next upgrade.
-
-### 1.3 The exact operator paths wiped
-
-Cross-referencing the issue's operator-owned list against `PRESERVE_PATHS`:
-
-| Operator path (issue #791)                                        | In PRESERVE_PATHS?                      | Fate on `mosaic update` |
-| ----------------------------------------------------------------- | --------------------------------------- | ----------------------- |
-| `agents/*.conf` (per-agent runtime)                               | **NO**                                  | **WIPED**               |
-| `policy/*.md` (operator overlays)                                 | **NO**                                  | **WIPED**               |
-| `*.local.md` (SOUL/USER/STANDARDS)                                | **NO**                                  | **WIPED**               |
-| harvester / SOP artifacts + timers                                | **NO**                                  | **WIPED**               |
-| `tools/_lib/credentials.json`                                     | **NO** (`credentials/` dir ≠ this path) | **WIPED**               |
-| `fleet/agents/*.env`                                              | yes (`fleet/agents`, added by #631)     | survives                |
-| `memory/`, `fleet/roster.*`, `fleet/backlog`, `fleet/roles.local` | yes                                     | survives                |
-
-The `fleet/agents`, `memory`, `fleet/backlog` entries were **retro-added after prior incidents**
-(#631). This whack-a-mole is the structural signature of a denylist.
-
-**Stale-comment evidence:** `update-checker.ts:492` claims the reseed preserves
-"`SOUL/USER/*.local/credentials`" — but `PRESERVE_PATHS` contains **no `*.local` entry**. The code
-documents protection it does not deliver.
-
-### 1.4 Second code path (TS) — already non-destructive, but drifted
-
-`FileConfigAdapter.syncFramework()` (`packages/mosaic/src/config/file-adapter.ts:157`) →
-`syncDirectory()` (`packages/mosaic/src/platform/file-ops.ts:66`) is a **copy-overlay**: it copies
-source over target and skips preserved paths, but **never deletes** target paths absent from source
-(`file-ops.ts:77-109`). It is used by the wizard/init flow, not `mosaic update`.
-
-Two problems remain:
-
-1. Its `preservePaths` (`file-adapter.ts:164-185`) has **already diverged** from `install.sh` — it is
-   **missing `fleet/backlog` and `fleet/roles.local`**. Two hand-maintained denylists, drifted. This
-   is direct evidence for a single shared SSOT manifest.
-2. Even non-destructive, it will happily _overwrite_ an operator file that collides with a
-   framework-shipped path unless that path is on its (incomplete) preserve list.
-
-### 1.5 Existing snapshot is inadequate for rollback
-
-`make_snapshot()`/`restore_snapshot()` (`install.sh:76-87`) copy `TARGET_DIR` to `mktemp -d` under
-`/tmp`, restore **only on `ERR/INT/TERM` trap**, and are **deleted on success** (`cleanup_snapshot`,
-`install.sh:345`). Consequences: ephemeral `/tmp`, no retention, no post-success rollback, and **no
-`mosaic restore`**. It is crash-safety only, not the transactional safety net #791 requires.
-
----
-
-## 2. Fix (b) — Strict ownership separation [PRIMARY / root cause]
-
-### 2.1 Ownership model (invert to allow-list)
-
-Replace _"framework-owned unless preserved"_ with _"operator-owned unless framework-owned"_, resolved
-**per target path** with operator carve-outs winning inside shared framework subtrees.
-
-Two declared lists, one SSOT data file shipped in the framework
-(`framework/framework-manifest.json`), consumed by **both** bash and TS:
-
-- **`framework` globs** — paths the updater is entitled to create / overwrite / prune. Authored to
-  match exactly what the framework ships in `packages/mosaic/framework/` (e.g. `CONSTITUTION.md`,
-  `AGENTS.md`, `STANDARDS.md`, `TOOLS.md`, `guides/**`, `constitution/**`, `templates/**`, `tools/**`,
-  `skills/**`, `mcp/**`, `defaults/**`, `fleet/examples/**`, `fleet/roles/**`, `fleet/profiles/**`,
-  `fleet/roster.schema.json`).
-- **`operatorReserved` globs** — NEVER written or pruned, even nested inside a `framework` subtree;
-  these **win** over `framework` (deny-wins / most-specific-wins). At minimum:
-  `agents/**`, `policy/**`, `memory/**`, `sources/**`, `credentials/**`, `*.local.md`,
-  `tools/_lib/credentials.json`, `fleet/roster.yaml`, `fleet/roster.json`, `fleet/agents/**`,
-  `fleet/run/**`, `fleet/backlog/**`, `fleet/roles.local/**`, plus operator harvester/SOP artifacts.
-
-### 2.2 Ownership resolution for a target path `P`
-
-1. `P` matches `operatorReserved` → **operator-owned**: updater MUST NOT write, MUST NOT delete.
-2. else `P` matches `framework` → **framework-owned**: may overwrite; may prune **only if absent from
-   the current SOURCE** (a genuinely retired framework file).
-3. else (matches neither) → **UNKNOWN ⇒ operator-owned by default (fail-safe)**: never delete.
-
-Rule 3 is the actual root-cause fix: an operator path the manifest authors forget is still protected,
-because _unknown defaults to operator_. A denylist can never provide this guarantee.
-
-### 2.3 Sync mechanism change (the mechanically-critical part)
-
-`--delete` cannot express "prune only framework-owned" without re-enumerating every operator path
-(the denylist trap). So:
-
-1. **Drop `--delete` from the bulk sync.** Copy `SOURCE → TARGET` non-destructively (writes/overwrites
-   all framework files; deletes nothing). rsync without `--delete`, or the existing overlay copy.
-2. **Explicit manifest-scoped prune pass.** Iterate the **`framework` manifest** (not the whole tree);
-   for each framework path present in `TARGET` but **absent in `SOURCE`**, delete it — after
-   re-checking it does not match `operatorReserved`. Because the prune iterates only declared
-   framework globs, operator/unknown paths are **structurally unreachable** by deletion.
-
-This is implemented in both bash `sync_framework()` and TS `syncFramework()` from the shared manifest.
-A pure **prune-planner** function (TS) computes the delete-set from
-`(manifest, sourceListing, targetListing)` so the invariant is unit-testable in isolation.
-`PRESERVE_PATHS` becomes redundant (kept as a defense-in-depth alias mapping to `operatorReserved`, or
-removed) — either way the two lists stop drifting because they read one file.
-
-### 2.4 HARD GATE test — "upgrade touches no path outside the manifest"
-
-Filesystem-observation test in the existing `test-install-migration.sh` harness pattern (mktemp
-`MOSAIC_HOME`, `MOSAIC_SYNC_ONLY=1`), plus TS specs:
-
-1. Seed a throwaway `TARGET` with a realistic operator mix — one sentinel per operator class:
-   `agents/x.conf`, `policy/p.md`, `SOUL.local.md`, `memory/m.md`,
-   `tools/_lib/credentials.json` (with a secret value), `fleet/agents/a.env`, `fleet/roster.yaml`,
-   `harvester/sop.md`, **and a deliberately-unanticipated `unknown-operator-dir/x`**.
-2. Record hash+mtime of every sentinel.
-3. Run the upgrade from a `SOURCE` containing none of those operator paths.
-4. **Assert:** every sentinel exists, byte-identical, **mtime unchanged** (not even rewritten). The
-   `unknown-operator-dir` surviving proves the fail-safe default — a denylist could not pass this case.
-5. **Positive controls:** framework files WERE updated; a retired framework file WAS pruned.
-6. **Property test** (TS prune-planner): for fuzzed operator paths, `deleteSet ⊆ {matches framework ∧
-in target ∧ not in source}` and `deleteSet ∩ operatorReserved = ∅`.
-
----
-
-## 3. Fix (a) — Transactional pre-update snapshot [safety net]
-
-- **Destination:** `${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-ts>/`.
-  **Outside `~/.config/mosaic`** (so no future sync can sweep it) and outside any repo.
-- **Perms:** dir `0700`, files `0600` — enforced with `umask 077` around the copy **and** explicit
-  `chmod`. Never world-readable.
-- **Scope:** the operator-owned surface (`operatorReserved` paths that exist) — bounded; does not copy
-  the framework tree.
-- **Timing:** taken before ANY mutation in the upgrade flow.
-- **Post-sync verify + selective restore:** after sync, diff the operator surface against the snapshot;
-  since (b) should never touch operator paths, any diff means a manifest bug — restore the affected
-  paths from the snapshot and warn loudly. This is precisely (a) catching a miss in (b).
-- **Retention:** keep N most-recent (default 5; `MOSAIC_BACKUP_RETENTION` override); prune older.
-- **`mosaic restore`:** `--list` (default, dry-run) enumerates snapshots by timestamp;
-  `--from <ts>` restores that snapshot over the operator surface, confirmation-gated. Reports
-  counts/paths only.
-- **Secret-safety:** snapshot copy and restore never emit file **contents**; only paths/counts.
-  Tests assert `0700/0600` and that no secret value appears in stdout/stderr.
-
----
-
-## 4. Fix (d) — Regeneration-from-SSOT [recovery]
-
-The incident's live blast radius: `fleet/agents/*.env` (systemd `EnvironmentFile` sources) gone →
-`mosaic-agent@<name>` boots **unit defaults** on restart (because `EnvironmentFile=-...` is
-absent-tolerant) → **silent identity/runtime/workdir downgrade**.
-
-The SSOT for those `.env` files is the roster. The reconciler **already** separates a
-`regenerate-projections-from-roster` projection phase from lifecycle
-(`packages/mosaic/src/fleet/fleet-reconciler.ts:93,234`; env rendering in
-`generated-env-boundary.ts:149-264`).
-
-**`mosaic fleet regen`** is therefore a **thin recovery-framed wrapper over the existing projection
-phase** — it does NOT reimplement fleet logic and does NOT preempt in-flight FCM cards (M4/M5):
-
-- Regenerates derivable config (per-agent `*.env.generated`, unit files) from roster SSOT.
-- **Preview-first:** dry-run default; `--write` to apply. Idempotent.
-- **Never restarts agents** (the recovery order forbids restart-before-verify).
-- Prints the runbook's next step (verify `EnvironmentFile` resolves, THEN restart).
-
-Alternatively documentable as `install.sh --relink` per the issue; `mosaic fleet regen` is preferred
-because it reuses the merged reconciler plumbing.
-
----
-
-## 5. Secret-safety approach (secrev surface)
-
-- Snapshots/backups: `0700`/`0600`, outside any repo, never world-readable. (§3)
-- No secret **value** ever emitted to logs/stdout/stderr by snapshot, restore, sync, or regen —
-  paths/counts only. Adversarial test: a secret value placed in `tools/_lib/credentials.json` must
-  never appear in installer or command output.
-- `tools/_lib/credentials.json` is an explicit `operatorReserved` carve-out inside the framework-owned
-  `tools/**` subtree — it is never overwritten or pruned.
-- The HARD GATE test doubles as a secret-safety test (asserts the credentials sentinel is untouched).
-
----
-
-## 6. Test plan (TDD, tests-first, ≥85% on new code, co-located `*.spec.ts`)
-
-1. **Manifest SSOT parity** — bash and TS resolve identical framework/operator sets from the one file;
-   a test fails if either path hard-codes a divergent list.
-2. **Manifest completeness** — every path shipped in `framework/` is covered by a `framework` glob (so
-   a new shipped file cannot silently fall outside the manifest and become un-prunable/undeclared).
-3. **HARD GATE** — upgrade touches nothing outside the manifest, incl. the unanticipated-path case
-   (§2.4).
-4. **Prune-planner** unit + property tests (§2.4.6).
-5. **Snapshot** — perms `0700/0600`, correct destination, retention prune, secret value absent from
-   output.
-6. **Restore** — `--list` / `--from` round-trip restores operator surface byte-exact; confirmation
-   gate; no secret leakage.
-7. **Regen** — roster→env projection deterministic + idempotent; dry-run makes no writes; `--write`
-   restores `*.env`; **never** issues a lifecycle/restart call.
-8. **Cross-path regression** — TS `syncFramework` and bash `install.sh` agree on a shared fixture
-   (closes the current #631-style drift).
-
-Gates before every push: `pnpm typecheck && pnpm lint && pnpm format:check` + mosaic package tests
-green. Never `--no-verify`.
-
----
-
-## 7. web1 recovery runbook (operator-agnostic; web1 specifics live in the issue as evidence only)
-
-For a currently-wiped fleet EnvironmentFile state — **do NOT service-restart while
-`fleet/agents/*.env` is absent** (a restart boots unit defaults and silently downgrades identity):
-
-1. **Regenerate:** `mosaic fleet regen --write` — rebuild `~/.config/mosaic/fleet/agents/*.env` from
-   roster SSOT.
-2. **Verify each unit resolves to the intended runtime/workdir** _before_ any restart:
-   `systemctl --user show mosaic-agent@<name> -p EnvironmentFile` and confirm the generated env exists
-   and carries the intended `MOSAIC_AGENT_*` runtime/workdir values.
-3. **Only then** `systemctl --user restart mosaic-agent@<name>`, one unit at a time.
-
-If config (not just fleet env) was lost, `mosaic restore --list` → `mosaic restore --from <ts>` before
-step 1.
-
----
-
-## 8. Proposed PR split (reviewable; DAG-ordered)
-
-| PR  | Scope                                                                                                                                                    | Depends | Review focus               |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------- |
-| PR1 | **PRIMARY** — shared `framework-manifest.json` + ownership resolver + non-deleting sync + scoped prune (bash + TS) + **HARD GATE** + prune-planner tests | —       | correctness (root fix)     |
-| PR2 | **Safety net** — pre-update snapshot (`~/.local/state`, 0700/0600, retention) + post-sync verify/restore + `mosaic restore`                              | PR1     | **secrev** (backup/secret) |
-| PR3 | **Recovery** — `mosaic fleet regen` (projection-only, preview-first, no restart) + docs (upgrade-safety + recovery runbook)                              | PR1     | correctness + docs         |
-
-Rationale: PR1 closes the failure class on its own; if PR2/PR3 slip, the class stays fixed. Each PR is
-one reviewable unit with its own tests ≥85%. Independent review (author≠reviewer) on all; **secrev** on
-PR2 (and PR1's secret-sentinel assertions).
-
-## 9. Deferred (noted per scope)
-
-**(c) periodic backup timer** — a systemd user timer snapshotting operator dirs on a cadence
-(defense-in-depth for non-upgrade losses). Explicitly **out of scope now**; future phase.
-
-## 10. Constraints honored
-
-- **Framework-PR firewall:** manifest + logic are operator-agnostic; no SOUL/USER/operator specifics
-  in framework code; web1 details are issue evidence only.
-- **Capacity-fill:** must not preempt M5-001 or #790; `fleet regen` reuses merged FCM-M3 plumbing and
-  does not overlap FCM-M4/M5 migration cards.
-- **Delivery gates:** TDD tests-first, ≥85% new-code coverage, trunk-based squash PRs, independent
-  review + secrev, completion = merged PR + descendant-main green + #791 closed.
-
----
-
-**Requesting MS-LEAD confirmation of:** (1) the manifest allow-list + non-deleting-sync + scoped-prune
-approach as the (b) root-cause fix; (2) snapshot destination/retention + `mosaic restore` UX;
-(3) `mosaic fleet regen` as a projection-only wrapper; (4) the 3-PR split. Implementation begins only
-on your confirmation.

docs/design/storage-abstraction-middleware.md

@@ -70,10 +70,6 @@ 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/MILESTONES.md

@@ -54,7 +54,7 @@ Every milestone adds tests to these layers. A milestone cannot be claimed comple
 - Add `"tier": "federated"` to `mosaic.config.json` schema and validators
 - Docker Compose `federated` profile (`docker-compose.federated.yml`) adds: Postgres+pgvector (5433), Valkey (6380), dedicated volumes
 - Tier detector in gateway bootstrap: reads config, asserts required services reachable, refuses to start otherwise
-- **Historical/status only:** the prior startup-provisioning statement is superseded. Runtime/startup extension provisioning is forbidden. PostgreSQL activation remains non-operative with no current command authority until KBN-101-00, KBN-101-03, and KBN-101-05 land; this record authorizes no current DDL, Compose/init, or startup path.
+- `pgvector` extension installed + verified on startup
 - Migration logic: safe upgrade path from `local`/`standalone` → `federated` (data export/import script, one-way)
 - `mosaic doctor` reports tier + service health
 - Gateway continues to serve as a normal standalone instance (no federation yet)

docs/federation/SETUP.md

@@ -1,74 +1,280 @@
 # Federated Tier Setup Guide
 
-> **KBN-101 N-1 hold:** This page is **non-operative** and grants no current command
-> authority until KBN-101-00, KBN-101-03, and KBN-101-05 land and KBN-101-08 activates a
-> reviewed release. It does not authorize a deployment operation, initialization artifacts,
-> implicit extension/schema/migration creation, raw `CREATE`, direct database initialization, or
-> a Gateway against an unverified database. The prior direct-start wording is retired; its
-> regression fixture is owned by KBN-101-06.
+## What is the federated tier?
 
-## Held future procedure
+The federated tier is designed for multi-user and multi-host deployments. It consists of PostgreSQL 17 with pgvector extension (for embeddings and RAG), Valkey for distributed task queueing and caching, and a shared configuration across multiple Mosaic gateway instances. Use this tier when running Mosaic in production or when scaling beyond a single-host deployment.
 
-This section is non-operative and grants no current command authority until KBN-101-00, KBN-101-03, and KBN-101-05 land.
+## Prerequisites
 
-The deployment control plane—not an operator shell or deployment lifecycle hook—performs this
-exact held future sequence after activation authorization: external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness.
+- Docker and Docker Compose installed
+- Ports 5433 (PostgreSQL) and 6380 (Valkey) available on your host (or adjust environment variables)
+- At least 2 GB free disk space for data volumes
 
-1. External bootstrap provisions the approved database/extension prerequisites.
-2. TLS/roles are installed through the generation-pinned renderer.
-3. The dedicated one-shot runner executes `mosaic-db-migrator --run`.
-4. The same runner executes `mosaic-db-migrator --verify`, including readiness and the
-   importer-target attestation where that route is enabled.
-5. Only after successful verification may Gateway reach its independent verified-TLS Gateway
-   readiness gate.
+## Start the federated stack
 
-No step may be reordered, skipped, replaced by a raw SQL command, or delegated to an initialization
-hook.
-A missing extension, schema, migration, role, secret generation, or readiness proof is a failed
-control-plane precondition; it is not an instruction to start Compose, retry startup, or create
-anything directly.
+Run the federated overlay:
 
-## N-1 status and required disposition
+```bash
+docker compose -f docker-compose.federated.yml --profile federated up -d
+```
 
-The current branch retains historical federation artifacts, but they are not a deployable
-procedure. `docs/federation/TASKS.md` records their shipped status only. KBN-101-02 retires
-runtime/init DDL; KBN-101-05 owns the renderer/deployment handoff; KBN-101-06 verifies the
-finite scanner and command matrix; and KBN-101-07 owns this operator route. A path named in an
-inventory, a historical-status label, or a normative requirement cannot suppress the semantic
-checks above.
+This starts PostgreSQL 17 with pgvector and Valkey 8. The pgvector extension is created automatically on first boot.
 
-Until the activation certificate names an exact release, use no database startup or recovery
-command from this document. For the produced importer interface, see
-[the federated tier migration contract](../guides/migrate-tier.md); it is likewise non-operative
-until activation.
+Verify the services are running:
 
-## Federation and Step-CA reference
+```bash
+docker compose -f docker-compose.federated.yml ps
+```
 
-Federation uses PostgreSQL 17 with pgvector, Valkey, and a shared configuration across multiple
-Gateway instances. Step-CA issues federation peer X.509 certificates whose custom OIDs carry a
-grant and subject identity. The following facts are reference material only; provisioning and
-secret delivery remain deployment-control-plane work under the activation sequence.
+Expected output shows `postgres-federated` and `valkey-federated` both healthy.
 
-| OID                 | Name                     | Description           |
-| ------------------- | ------------------------ | --------------------- |
-| 1.3.6.1.4.1.99999.1 | `mosaic_grant_id`        | Federation grant UUID |
-| 1.3.6.1.4.1.99999.2 | `mosaic_subject_user_id` | Subject user UUID     |
+## Configure mosaic for federated tier
 
-The internal arc `1.3.6.1.4.1.99999` is development-only. Before an externally reachable
-production deployment, register an IANA Private Enterprise Number and version the assignments.
-Each value is DER-encoded as an ASN.1 UTF8String containing the UUID.
+Create or update your `mosaic.config.json`:
 
-The future activated Gateway requires `STEP_CA_URL`, `STEP_CA_PROVISIONER_PASSWORD`,
-`STEP_CA_PROVISIONER_KEY_JSON`, `STEP_CA_ROOT_CERT_PATH`, and `BETTER_AUTH_SECRET` through the
-reviewed secret mechanism. These names do not authorize shell exports, copied credential files,
-or an ad hoc service start.
+```json
+{
+  "tier": "federated",
+  "database": "postgresql://mosaic:mosaic@localhost:5433/mosaic",
+  "queue": "redis://localhost:6380"
+}
+```
 
-## Failure disposition
+If you're using environment variables instead:
 
-- A TLS, CA, SAN, role, runner, or readiness failure is a control-plane incident. Preserve only
-  sanitized evidence and follow the approved rollback/repair record.
-- A pgvector/extension failure is a failed external-bootstrap or runner precondition. Do not use
-  direct extension SQL, init artifacts, or a startup retry as remediation.
-- A port, container, or Valkey problem does not permit bypassing the activation sequence.
-- Federation peer-key rotation remains deferred until its separately approved migration plan;
-  do not rotate `BETTER_AUTH_SECRET` without that plan.
+```bash
+export DATABASE_URL="postgresql://mosaic:mosaic@localhost:5433/mosaic"
+export REDIS_URL="redis://localhost:6380"
+```
+
+## Verify health
+
+Run the health check:
+
+```bash
+mosaic gateway doctor
+```
+
+Expected output (green):
+
+```
+Tier: federated  Config: mosaic.config.json
+  ✓ postgres         localhost:5433       (42ms)
+  ✓ valkey           localhost:6380       (8ms)
+  ✓ pgvector         (embedded)           (15ms)
+```
+
+For JSON output (useful in CI/automation):
+
+```bash
+mosaic gateway doctor --json
+```
+
+## Step 2: Step-CA Bootstrap
+
+Step-CA is a certificate authority that issues X.509 certificates for federation peers. In Mosaic federation, it signs peer certificates with custom OIDs that embed grant and user identities, enforcing authorization at the certificate level.
+
+### Prerequisites for Step-CA
+
+Before starting the CA, you must set up the dev password:
+
+```bash
+cp infra/step-ca/dev-password.example infra/step-ca/dev-password
+# Edit dev-password and set your CA password (minimum 16 characters)
+```
+
+The password is required for the CA to boot and derive the provisioner key used by the gateway.
+
+### Start the Step-CA service
+
+Add the step-ca service to your federated stack:
+
+```bash
+docker compose -f docker-compose.federated.yml --profile federated up -d step-ca
+```
+
+On first boot, the init script (`infra/step-ca/init.sh`) runs automatically. It:
+
+- Generates the CA root key and certificate in the Docker volume
+- Creates the `mosaic-fed` JWK provisioner
+- Applies the X.509 template from `infra/step-ca/templates/federation.tpl`
+
+The volume is persistent, so subsequent boots reuse the existing CA keys.
+
+Verify the CA is healthy:
+
+```bash
+curl https://localhost:9000/health --cacert /tmp/step-ca-root.crt
+```
+
+(If the root cert file doesn't exist yet, see the extraction steps below.)
+
+### Extract credentials for the gateway
+
+The gateway requires two credentials from the running CA:
+
+**1. Provisioner key (for `STEP_CA_PROVISIONER_KEY_JSON`)**
+
+```bash
+docker exec $(docker ps -qf name=step-ca) cat /home/step/secrets/mosaic-fed.json > /tmp/step-ca-provisioner.json
+```
+
+This JSON file contains the JWK public and private keys for the `mosaic-fed` provisioner. Store it securely and pass its contents to the gateway via the `STEP_CA_PROVISIONER_KEY_JSON` environment variable.
+
+**2. Root certificate (for `STEP_CA_ROOT_CERT_PATH`)**
+
+```bash
+docker cp $(docker ps -qf name=step-ca):/home/step/certs/root_ca.crt /tmp/step-ca-root.crt
+```
+
+This PEM file is the CA's root certificate, used to verify peer certificates issued by step-ca. Pass its path to the gateway via `STEP_CA_ROOT_CERT_PATH`.
+
+### Custom OID Registry
+
+Federation certificates include custom OIDs in the certificate extension. These encode authorization metadata:
+
+| OID                 | Name                   | Description           |
+| ------------------- | ---------------------- | --------------------- |
+| 1.3.6.1.4.1.99999.1 | mosaic_grant_id        | Federation grant UUID |
+| 1.3.6.1.4.1.99999.2 | mosaic_subject_user_id | Subject user UUID     |
+
+These OIDs are verified by the gateway after the CSR is signed, ensuring the certificate was issued with the correct grant and user context.
+
+### Environment Variables
+
+Configure the gateway with the following environment variables before startup:
+
+| Variable                       | Required | Description                                                                                               |
+| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------- |
+| `STEP_CA_URL`                  | Yes      | Base URL of the step-ca instance, e.g. `https://step-ca:9000` (use `https://localhost:9000` in local dev) |
+| `STEP_CA_PROVISIONER_KEY_JSON` | Yes      | JSON-encoded JWK from `/home/step/secrets/mosaic-fed.json`                                                |
+| `STEP_CA_ROOT_CERT_PATH`       | Yes      | Absolute path to the root CA certificate (e.g. `/tmp/step-ca-root.crt`)                                   |
+| `BETTER_AUTH_SECRET`           | Yes      | Secret used to seal peer private keys at rest; already required for M1                                    |
+
+Example environment setup:
+
+```bash
+export STEP_CA_URL="https://localhost:9000"
+export STEP_CA_PROVISIONER_KEY_JSON="$(cat /tmp/step-ca-provisioner.json)"
+export STEP_CA_ROOT_CERT_PATH="/tmp/step-ca-root.crt"
+export BETTER_AUTH_SECRET="<your-secret>"
+```
+
+## Troubleshooting
+
+### Port conflicts
+
+**Symptom:** `bind: address already in use`
+
+**Fix:** Stop the base dev stack first:
+
+```bash
+docker compose down
+docker compose -f docker-compose.federated.yml --profile federated up -d
+```
+
+Or change the host port with an environment variable:
+
+```bash
+PG_FEDERATED_HOST_PORT=5434 VALKEY_FEDERATED_HOST_PORT=6381 \
+  docker compose -f docker-compose.federated.yml --profile federated up -d
+```
+
+### pgvector extension error
+
+**Symptom:** `ERROR: could not open extension control file`
+
+**Fix:** pgvector is created at first boot. Check logs:
+
+```bash
+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;"
+```
+
+### Valkey connection refused
+
+**Symptom:** `Error: connect ECONNREFUSED 127.0.0.1:6380`
+
+**Fix:** Check service health:
+
+```bash
+docker compose -f docker-compose.federated.yml logs valkey-federated
+```
+
+If Valkey is running, verify your firewall allows 6380. On macOS, Docker Desktop may require binding to `host.docker.internal` instead of `localhost`.
+
+## Key rotation (deferred)
+
+Federation peer private keys (`federation_peers.client_key_pem`) are sealed at rest using AES-256-GCM with a key derived from `BETTER_AUTH_SECRET` via SHA-256. If `BETTER_AUTH_SECRET` is rotated, all sealed `client_key_pem` values in the database become unreadable and must be re-sealed with the new key before rotation completes.
+
+The full key rotation procedure (decrypt all rows with old key, re-encrypt with new key, atomically swap the secret) is out of scope for M2. Operators must not rotate `BETTER_AUTH_SECRET` without a migration plan for all sealed federation peer keys.
+
+## OID Assignments — Mosaic Internal OID Arc
+
+Mosaic uses the private enterprise arc `1.3.6.1.4.1.99999` for custom X.509
+certificate extensions in federation grant certificates.
+
+**IMPORTANT:** This is a development/internal OID arc. Before deploying to a
+production environment accessible by external parties, register a proper IANA
+Private Enterprise Number (PEN) at <https://pen.iana.org/pen/PenApplication.page>
+and update these assignments accordingly.
+
+### Assigned OIDs
+
+| OID                   | Symbolic name                     | Description                                               |
+| --------------------- | --------------------------------- | --------------------------------------------------------- |
+| `1.3.6.1.4.1.99999.1` | `mosaic.federation.grantId`       | UUID of the `federation_grants` row authorising this cert |
+| `1.3.6.1.4.1.99999.2` | `mosaic.federation.subjectUserId` | UUID of the local user on whose behalf the cert is issued |
+
+### Encoding
+
+Each extension value is DER-encoded as an ASN.1 **UTF8String**:
+
+```
+Tag    0x0C        (UTF8String)
+Length 0x24        (36 decimal — fixed length of a UUID string)
+Value  <36 ASCII bytes of the UUID>
+```
+
+The step-ca X.509 template at `infra/step-ca/templates/federation.tpl`
+produces this encoding via the Go template expression:
+
+```
+{{ printf "\x0c\x24%s" .Token.mosaic_grant_id | b64enc }}
+```
+
+The resulting base64 value is passed as the `value` field of the extension
+object in the template JSON.
+
+### CA Environment Variables
+
+The `CaService` (`apps/gateway/src/federation/ca.service.ts`) requires the
+following environment variables at gateway startup:
+
+| Variable                       | Required | Description                                                          |
+| ------------------------------ | -------- | -------------------------------------------------------------------- |
+| `STEP_CA_URL`                  | Yes      | Base URL of the step-ca instance, e.g. `https://step-ca:9000`        |
+| `STEP_CA_PROVISIONER_PASSWORD` | Yes      | JWK provisioner password for the `mosaic-fed` provisioner            |
+| `STEP_CA_PROVISIONER_KEY_JSON` | Yes      | JSON-encoded JWK (public + private) for the `mosaic-fed` provisioner |
+| `STEP_CA_ROOT_CERT_PATH`       | Yes      | Absolute path to the step-ca root CA certificate PEM file            |
+
+Set these variables in your environment or secret manager before starting
+the gateway. In the federated Docker Compose stack they are expected to be
+injected via Docker secrets and environment variable overrides.
+
+### Fail-loud contract
+
+The CA service (and the X.509 template) are designed to fail loudly if the
+custom OIDs cannot be embedded:
+
+- The template produces a malformed extension value (zero-length UTF8String
+  body) when the JWT claims `mosaic_grant_id` or `mosaic_subject_user_id` are
+  absent. step-ca rejects the CSR rather than issuing a cert without the OIDs.
+- `CaService.issueCert()` throws a `CaServiceError` on every error path with
+  a human-readable `remediation` string. It never silently returns a cert that
+  may be missing the required extensions.

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   | Historical shipped-status record: authored a federated Compose overlay with PostgreSQL/pgvector, Valkey, volumes, and healthchecks. It is not a current startup, init, extension, schema, or migration procedure.  | #460  | sonnet | feat/federation-m1-compose         | FED-M1-01  | 5K       | Shipped in PR #471 status only. KBN-101-02 retires its init authority; KBN-101-05 replaces deployment rendering; KBN-101-07 SETUP is non-operative until activation.                                                                                  |
-| 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.                                                                                                                                            |
+| 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.                                       |
 
 **M1 total estimate:** ~74K tokens (over-budget vs 20K PRD estimate — explanation below)
 

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

@@ -5,17 +5,28 @@
 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 M5 closure report and linked deferral evidence.
+recorded in the M0 task/PR.
 
 ## M0 baseline acceptance
 
-- [x] `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.
-- [x] `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.
-- [x] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and observed state, including stopped-state preservation through migration, apply, and reboot.
-- [x] `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.
-- [x] `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.
-- [x] `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.
-- [x] `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` classifies every current shipped fleet example, profile, and service preset before M1 implementation starts.
+- [ ] `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
 
@@ -61,18 +72,15 @@ recorded in the M5 closure report and linked deferral evidence.
 
 ## Cross-cutting evidence gates
 
-- [x] Every retained or migrated YAML/JSON example, profile, and service preset validates through the same declared executable production parser/resolver path recorded by the disposition inventory; versioned v1 fixtures are not forced through the v2 compiler.
-- [x] Every retired example/profile/service preset has a replacement link and deprecation note; no unresolved legacy class or tool-policy alias remains silently shipped.
-- [x] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded Tess/Ultron identity.
-- [x] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed mosaic agent catalog.
-- [x] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of legacy sensitive keys are never printed.
-- [x] M5 documentation validation verifies required IA paths, local file and heading-fragment links, the canonical roster through the production compiler/resolver, and fenced/canonical-example safety checks.
-- [ ] FCM-M5-001 does not deterministically assert owner/evidence/deferral metadata for every checklist row. Closure and deferral reports provide human-reviewable evidence only; broader assertion coverage remains unclaimed.
-
-## Held downstream gates
-
-These unchecked items are intentionally outside FCM-M5-001 and are not authorized by this checklist:
-
-- [ ] FCM-M4-002 executes and evidences live cutover, canary, stopped-state preservation, and rollback.
-- [ ] FCM-M5-002 completes independent exact-head review and issues the validator certificate.
-- [ ] The exact PR head reaches terminal-green CI after independent review.
+- [ ] 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/FLEET-LAUNCH.md

@@ -1,81 +1,114 @@
 # Fleet Launch Runbook
 
-The local fleet roster is the sole writable desired-state authority for membership and launch policy.
-Generated environment files are rebuildable projections, not an operator-editable command surface.
+How every Mosaic fleet agent — workers **and** the orchestrator — is launched, and how to
+configure each one. The guiding principle: **one roster-driven launcher**. There is no bespoke
+per-agent launch script; the roster plus per-agent `.env` files are the single source of launch
+config.
 
-## Launch chain
+## The launch chain
 
-| Layer               | Responsibility                                                                                                                  |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
-| Projection writer   | Renders deterministic fleet/agents/<name>.env.generated from the roster.                                                        |
-| Optional local data | Reads a strict, data-only fleet/agents/<name>.env.local; it cannot shadow generated keys.                                       |
-| systemd             | Starts the launcher with env -i and fixed bootstrap data. It does not preload either environment file.                          |
-| session launcher    | Validates generated and local data before it queries, creates, or stops an exact tmux session.                                  |
-| runtime launch      | Derives the fixed mosaic yolo <runtime> argument array from validated roster data, then seeds the runtime contract.             |
+| Layer            | File                                              | Responsibility                                                                                                                                              |
+| ---------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| systemd unit     | `mosaic-agent@<role>.service`                     | One templated unit per role; `ExecStart` runs the session launcher with the instance name `%i`. Defaults `MOSAIC_AGENT_RUNTIME=pi`, `MOSAIC_AGENT_NAME=%i`. |
+| session launcher | `tools/fleet/start-agent-session.sh <role>`       | Builds the launch command, opens the tmux pane, wires the heartbeat.                                                                                        |
+| launch command   | `mosaic yolo <runtime>` (or a per-agent override) | Replaces the pane's foreground process with the runtime, fully seeded.                                                                                      |
+| seeding          | `mosaic`'s `composeContract()`                    | Injects the Constitution/USER/TOOLS/runtime contract, `*.local` overlays, **and** the Fleet-Comms cheat-sheet — all via `--append-system-prompt`.           |
 
-The launcher never `source`s or `eval`s an environment file and never accepts an environment-supplied
-command. `MOSAIC_AGENT_COMMAND`, command/channel overrides, unknown keys, generated-key shadowing,
-secret-like key names, duplicate keys, comments, quoted/export syntax, and unsafe values are rejected.
+Per-agent overrides live in `fleet/agents/<role>.env`, generated from `roster.yaml` by
+`generateAgentEnv` (`packages/mosaic/src/commands/fleet.ts`) and consumed by the launcher.
 
-## Generated and local files
+## Worker launch path (default)
 
-<name>.env.generated is complete, deterministic, and written only by Mosaic. Its ordered keys are:
+1. `roster.yaml` carries each agent's `runtime` and optional `model_hint`.
+2. `generateAgentEnv` emits `fleet/agents/<role>.env` with `MOSAIC_AGENT_NAME`,
+   `MOSAIC_AGENT_RUNTIME`, and `MOSAIC_AGENT_MODEL`.
+3. `start-agent-session.sh` has no `MOSAIC_AGENT_COMMAND` set, so it falls through to the default
+   (line ~44):
+   ```sh
+   MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}"
+   ```
+4. The launcher bakes `MOSAIC_AGENT_NAME` into the pane command (line ~118), so `composeContract`
+   can inject the Fleet-Comms cheat-sheet for that role.
 
-```dotenv
-MOSAIC_AGENT_NAME=<roster name>
-MOSAIC_AGENT_CLASS=<roster class>
-MOSAIC_AGENT_RUNTIME=<roster runtime>
-MOSAIC_AGENT_MODEL=<roster model hint>
-MOSAIC_AGENT_REASONING=<roster reasoning>
-MOSAIC_AGENT_TOOL_POLICY=<roster tool policy>
-MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
-MOSAIC_TMUX_SOCKET=<roster socket or empty>
+That is the whole worker path: roster → `.env` → `mosaic yolo <runtime>` → seeded pane.
+
+## Orchestrator fold (PATH A — ships today)
+
+The orchestrator is **just another roster agent** launched through the canonical path — not a
+snowflake script.
+
+| Piece              | Value                               |
+| ------------------ | ----------------------------------- |
+| host-side launcher | `orchestrator-launch.sh`            |
+| systemd unit       | `mosaic-fleet-orchestrator.service` |
+| tmux session       | `orchestrator` (role-named)         |
+
+Set its launch command via `fleet/agents/orchestrator.env`:
+
+```sh
+MOSAIC_AGENT_COMMAND='mosaic yolo claude --channels plugin:discord@<channel>'
 ```
 
-The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. mosaic fleet add
-rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
-The legacy dogfood stub remains an observability-only canary on its separate `mosaic-factory` socket;
-it has no generated-launch adapter and cannot be added through this path.
+When `MOSAIC_AGENT_COMMAND` is set, `start-agent-session.sh`'s `if [ -z "$MOSAIC_AGENT_COMMAND" ]`
+guard (line ~41) is false, so the line-44 default — **including its hardcoded `yolo`** — is skipped
+entirely. The override fully controls the runtime and flags. Routing through `mosaic yolo claude`
+(rather than a raw `claude` invocation) is what gives the orchestrator the same full
+`composeContract` seeding + Fleet-Comms cheat-sheet as every worker, with `--channels` and any
+other flags passed straight through to the `claude` binary.
 
-<name>.env.local is optional and may contain only non-secret machine data:
+## Launch gotchas
 
-- `MOSAIC_RUNTIME_BIN`
-- `MOSAIC_HEARTBEAT_RUN_DIR`
-- `MOSAIC_HEARTBEAT_INTERVAL`
-- `MOSAIC_CLAUDE_JSON`
-- `CLAUDE_CONFIG_DIR`
+1. **Flag conflict.** `mosaic yolo claude` already injects `--dangerously-skip-permissions`. Do
+   **not** also pass `--permission-mode bypassPermissions` — the `claude` binary would receive both.
+   Use `mosaic yolo claude …` alone (yolo covers the unattended posture), **or** non-yolo
+   `mosaic claude --permission-mode bypassPermissions …`. Never mix the two.
+2. **`MOSAIC_AGENT_NAME` must reach the pane.** The launcher bakes it from the instance name, and
+   `composeContract` gates the Fleet-Comms block on it (`launch.ts`, in `composeContract`) — **and**
+   the role must be a member of `roster.yaml`, or the block resolves empty.
+3. **`launchRuntime` guards.** `mosaic yolo claude` runs `checkSoul` / `checkRuntime` /
+   `checkSequentialThinking`. The host needs `SOUL.md` and the sequential-thinking MCP, or the
+   launch aborts (a raw `claude` invocation skipped these checks). Dry-run the composed command in a
+   throwaway tmux session before swapping a live launcher.
 
-Paths must be safe absolute paths and the heartbeat interval must be a positive integer. Projection,
-local, and quarantine files must be private regular files; the managed directories must be real,
-private, non-symlink paths. Violations fail closed before tmux interaction.
+## Why per-agent `.env` survives upgrades (#632)
 
-## Legacy input and diagnostics
+`install.sh` `PRESERVE_PATHS` includes `fleet/*.yaml`, `fleet/agents`, and `fleet/run`, so
+`mosaic update`'s framework re-seed **preserves** your roster and per-agent `.env` overrides
+(glob-aware `cp` fallback; matching TS parity in `file-adapter.ts`). Before #632, an auto re-seed
+could wipe them — which is exactly why PATH A's `.env` override is safe to rely on now.
 
-A legacy <name>.env is input only during projection generation. Roster-owned keys are regenerated;
-valid allowed local data can move to `.env.local`; invalid legacy input is privately retained at
-<name>.env.quarantine. Neither legacy nor quarantine files are launch authority.
+## Inspecting the comms wiring
 
-Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command
-text, credentials, or other values.
+- `mosaic fleet comms-block <role>` prints the Fleet-Comms cheat-sheet a given role receives at
+  launch — its `[host:session]` identity, the exact `agent-send.sh` command for each peer, and the
+  FLIP / `--verify` conventions. `--host <h>` previews a cross-host view. An unknown role or missing
+  roster **fails loud** (stderr + non-zero exit), so a typo is never a silent no-op.
+- Versus `mosaic compose-contract <runtime>`: that emits the **whole** system prompt and reads the
+  role from `MOSAIC_AGENT_NAME` (a full-prompt smoke test). `comms-block` is the targeted,
+  explicit-arg, comms-only view — e.g. `mosaic fleet comms-block coder0-0` to preview a peer.
 
-## Launch and stop behavior
+## North Star / future direction
 
-The launcher obtains the agent's socket only from the validated generated projection. It creates or
-checks the exact =<agent-name> tmux target; it never uses an ambient socket or fuzzy session match.
-The same strict parser runs before exact-stop behavior. A fresh native Pi heartbeat remains authoritative;
-the shell sidecar only provides fallback state when the native marker is stale or absent.
+**Vision:** a webUI lets the user edit each agent's launch config — switch **harness**
+(claude / pi / codex / opencode), toggle **yolo**, pick a **model**, set a **command/channels**
+override — with no terminal.
 
-mosaic agent comms-block <exact-member> can inspect that exact roster member's resolved Fleet-Comms
-block. It is a read-only inspection tool and fails loudly for an unknown exact member or missing roster.
-On Linux, the installed roster, TOOLS contract, and executable helper are opened through a held
-descriptor chain rooted at `/`; every managed path component uses no-follow traversal, and content plus
-execute validation stay bound to the same opened file. Systems without Linux `/proc/self/fd` support
-fail closed rather than falling back to pathname revalidation.
+**Continuity — this is not a new launch path.** It is a data-model + UI-binding layer over the
+existing roster-driven launcher. Field-by-field status today:
 
-## Current M2 boundary
+| Launch-config field      | Roster-native today? | Mechanism / gap                                                                                                                                          |
+| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **harness** (`runtime`)  | ✅ end-to-end        | `roster.runtime` → `generateAgentEnv` emits `MOSAIC_AGENT_RUNTIME` → launcher line 44. UI just writes the field.                                         |
+| **model** (`model_hint`) | ✅ end-to-end        | `roster.model_hint` → `MOSAIC_AGENT_MODEL` → launcher line 44 `--model`. UI just writes the field.                                                       |
+| **yolo**                 | ❌ new               | Launcher line 44 **hardcodes** `mosaic yolo`. A non-yolo toggle needs a roster `yolo` field → emit `MOSAIC_AGENT_YOLO` → make line 44 conditional.       |
+| **command / channels**   | ❌ new               | `MOSAIC_AGENT_COMMAND` is **consumed** (launcher line ~12) but `generateAgentEnv` does not emit it. Needs a roster `command`/`channels` field → emitted. |
 
-FCM-M2-001 supplies generated/local parsing, validation, projection, quarantine, and launch-boundary
-evidence only. It does not authorize roster CRUD expansion, reconciliation, lifecycle changes, remote
-or connector mutation, site canaries, or migration. M3 must establish the local reconcile/lifecycle
-path; M4 separately provides migration preview, canary, and rollback gates.
+**The arc:**
+
+- **A** — `.env` `MOSAIC_AGENT_COMMAND` hatch: manual, ships now, kept safe across upgrades by #632.
+- **B** — roster-native launch-config: harness + model are already there; add the **yolo** toggle
+  (line-44 conditional) and **command/channels** emission to complete the data model.
+- **webUI** — binds dropdowns/toggles directly to those four roster fields.
+
+PATH A's `.env` override is the **manual form** of exactly what PATH B makes roster-native and the
+webUI edits — one continuous arc, not three separate features. PATH B is tracked as #636.

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

@@ -7,14 +7,13 @@ The v2 compiler may not silently accept an unresolved class. Before M1 exits, ev
 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).
+parallel resolver.
 
 ## Examples
 
 | Shipped file                                         | Current class evidence                                              | M0 disposition decision                                                                              | Required M1/M4 evidence                                              |
 | ---------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `framework/fleet/examples/coding.yaml`               | `orchestrator`, `enhancer`, `implementer`, `reviewer`               | Migrate: implementer → code, reviewer → review; retain orchestration/enhancer intent                 | v2 fixture validates; role aliases and authority matrix tested       |
+| `framework/fleet/examples/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     |
@@ -34,14 +33,14 @@ parallel resolver. The current executable implementation and per-artifact outcom
 
 ## 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. |
+| 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.
+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

docs/fleet/NORTH_STAR.md

@@ -33,7 +33,7 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
 - **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
 - **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
 - **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
-- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives mosaic update: baseline reseed never clobbers user overrides.
+- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives `mosaic update`: baseline reseed never clobbers user overrides.
 
 ## Workstreams
 

docs/fleet/NORTH_STAR.yaml

@@ -97,7 +97,7 @@ success_criteria:
   - id: AC-NS-7
     text: >-
       A user-customized persona (edited or added via the orchestrator) survives
-      mosaic update: baseline reseed never clobbers user overrides.
+      `mosaic update`: baseline reseed never clobbers user overrides.
 
 workstreams:
   - id: A

docs/fleet/PRD-fleet-suite.md

@@ -8,7 +8,7 @@
 ## Mission
 
 Turn the proven fleet primitives into a **user-installable, AI-free-configurable fleet product**:
-a user runs mosaic fleet init, answers a few questions (general / coding / research / hybrid),
+a user runs `mosaic fleet init`, answers a few questions (general / coding / research / hybrid),
 gets a recommended set of agents plus one always-on orchestrator wired for chat-ops, and can
 operate, mutate, re-create, and observe the fleet — over tmux today and Matrix tomorrow — from
 CLI/TUI and (designed-for) the webUI.
@@ -21,25 +21,25 @@ functional, we use the fleet itself to continue the work.
 
 ### A. Configure-without-AI CLI
 
-| ID  | Requirement                                                                                                 |
-| --- | ----------------------------------------------------------------------------------------------------------- |
-| R1  | mosaic fleet command set is functional end-to-end (init/install/start/stop/status/ps/verify + agent verbs). |
-| R2  | mosaic fleet init is an interactive, **AI-free** CLI wizard.                                                |
-| R3  | Init asks the **configuration type**: `general`, `coding`, `research`, `hybrid`, … (extensible).            |
-| R4  | Based on the answer, the fleet is populated with a **recommended set of agents** (a preset).                |
-| R5  | **Exactly one main orchestrator agent** is always configured, regardless of type.                           |
-| R10 | A set of **recommended configurations (presets)** ships for easy duplication.                               |
-| R8  | User can **re-create** the fleet when config needs change (idempotent re-init / reconfigure).               |
-| R17 | Fleet controls are **simple and intuitive**.                                                                |
+| ID  | Requirement                                                                                                   |
+| --- | ------------------------------------------------------------------------------------------------------------- |
+| R1  | `mosaic fleet` command set is functional end-to-end (init/install/start/stop/status/ps/verify + agent verbs). |
+| R2  | `mosaic fleet init` is an interactive, **AI-free** CLI wizard.                                                |
+| R3  | Init asks the **configuration type**: `general`, `coding`, `research`, `hybrid`, … (extensible).              |
+| R4  | Based on the answer, the fleet is populated with a **recommended set of agents** (a preset).                  |
+| R5  | **Exactly one main orchestrator agent** is always configured, regardless of type.                             |
+| R10 | A set of **recommended configurations (presets)** ships for easy duplication.                                 |
+| R8  | User can **re-create** the fleet when config needs change (idempotent re-init / reconfigure).                 |
+| R17 | Fleet controls are **simple and intuitive**.                                                                  |
 
 ### B. Comms & orchestrator chat-ops
 
-| ID  | Requirement                                                                                                                   |
-| --- | ----------------------------------------------------------------------------------------------------------------------------- |
-| R6  | Init can wire the orchestrator to a chat connector — **Telegram / Discord / Matrix / Slack** — for command + comms.           |
-| R7  | Designed with the end-goal of **Matrix comms on a locally-controlled server**.                                                |
-| R16 | Fleet supports **tmux AND Matrix** comms, **user-configurable** at init or any time. Not all users want Matrix.               |
-| R19 | **"Mos" orchestrator on Discord** (chan 1517622518662434996 / srv 1112631390438166618) on `w-jarvis` — the first live target. |
+| ID  | Requirement                                                                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------------- |
+| R6  | Init can wire the orchestrator to a chat connector — **Telegram / Discord / Matrix / Slack** — for command + comms.               |
+| R7  | Designed with the end-goal of **Matrix comms on a locally-controlled server**.                                                    |
+| R16 | Fleet supports **tmux AND Matrix** comms, **user-configurable** at init or any time. Not all users want Matrix.                   |
+| R19 | **"Mos" orchestrator on Discord** (`chan 1517622518662434996` / `srv 1112631390438166618`) on `w-jarvis` — the first live target. |
 
 ### C. Runtime, health, lifecycle
 
@@ -64,46 +64,46 @@ functional, we use the fleet itself to continue the work.
 - **Orchestrator agent:** always present; carries the chat connector config (connector type + target IDs) so it can be commanded over chat. tmux is the substrate; the connector bridges chat ↔ the orchestrator session.
 - **Comms layers (R16):** (1) **tmux** inter-agent (`agent-send`, proven) — default, always available. (2) **chat connector** for human↔orchestrator (Discord now; Matrix the strategic target). (3) **Matrix** as the locally-controlled cross-agent bus (future). Connector is pluggable + reconfigurable.
 - **Heartbeat (R15):** runtime-agnostic launcher sidecar already covers pi/claude/codex (#584). Refine per-runtime (native HB) with the **custom Pi harness** (R14) + a Claude path.
-- **Updates (R13):** mosaic update (CLI) + a fleet-aware harness-update step that refreshes pi/claude/codex and re-launches agents safely (drain → update → relaunch via the durable launcher).
-- **webUI (R18):** the fleet exposes machine-readable state (fleet ps --json already carries tenant/host/heartbeat/managed) + control verbs (start/stop/watch/send); webUI consumes these (control plane rides federation per north star). Ensure a stable JSON contract + a terminate/attach(butt-in) path.
+- **Updates (R13):** `mosaic update` (CLI) + a fleet-aware harness-update step that refreshes pi/claude/codex and re-launches agents safely (drain → update → relaunch via the durable launcher).
+- **webUI (R18):** the fleet exposes machine-readable state (`fleet ps --json` already carries tenant/host/heartbeat/managed) + control verbs (start/stop/watch/send); webUI consumes these (control plane rides federation per north star). Ensure a stable JSON contract + a terminate/attach(butt-in) path.
 
 ## Phases (incremental, each shippable)
 
-| Phase                             | Deliverable                                                                                                                       | Notes                                 |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| **F1 Presets + init wizard**      | preset rosters (general/coding/research/hybrid) + always-orchestrator + AI-free fleet init selecting a preset; re-init idempotent | R1–R5, R8, R10, R17                   |
-| **F2 Connector + Mos-on-Discord** | orchestrator chat-connector config (Discord first) + **Mos live on Discord 1517…/1112…** on w-jarvis                              | R6, R19, partial R16                  |
-| **F3 Heartbeat + harness**        | HB confirmed for claude + pi/gpt; **custom Pi harness** (tool usage, native HB, model self-report); graceful harness updates      | R13, R14, R15                         |
-| **F4 Matrix + comms toggle**      | Matrix connector (local server) + user toggle tmux/Matrix at init/anytime                                                         | R7, R16                               |
-| **F5 Orchestrator-mutable fleet** | orchestrator can add/remove agents at runtime                                                                                     | R9                                    |
-| **F6 webUI hooks**                | stable JSON contract + terminate/attach surface for webUI view/monitor/terminate/butt-in                                          | R18                                   |
-| **F7 Test + docs**                | install+test on w-jarvis AND dragon-lin; user docs (install/configure/use)                                                        | R11, R12 (runs alongside every phase) |
+| Phase                             | Deliverable                                                                                                                         | Notes                                 |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| **F1 Presets + init wizard**      | preset rosters (general/coding/research/hybrid) + always-orchestrator + AI-free `fleet init` selecting a preset; re-init idempotent | R1–R5, R8, R10, R17                   |
+| **F2 Connector + Mos-on-Discord** | orchestrator chat-connector config (Discord first) + **Mos live on Discord `1517…`/`1112…`** on w-jarvis                            | R6, R19, partial R16                  |
+| **F3 Heartbeat + harness**        | HB confirmed for claude + pi/gpt; **custom Pi harness** (tool usage, native HB, model self-report); graceful harness updates        | R13, R14, R15                         |
+| **F4 Matrix + comms toggle**      | Matrix connector (local server) + user toggle tmux/Matrix at init/anytime                                                           | R7, R16                               |
+| **F5 Orchestrator-mutable fleet** | orchestrator can add/remove agents at runtime                                                                                       | R9                                    |
+| **F6 webUI hooks**                | stable JSON contract + terminate/attach surface for webUI view/monitor/terminate/butt-in                                            | R18                                   |
+| **F7 Test + docs**                | install+test on w-jarvis AND dragon-lin; user docs (install/configure/use)                                                          | R11, R12 (runs alongside every phase) |
 
 ## Work division (proposed — confirm with dragon-lin)
 
 - **Jarvis @ w-jarvis (Lead):** F1 presets+wizard, F2 connector+Mos-on-Discord, F5 mutability, F6 webUI hooks; merge authority + dual-engine reviews; co-testing on w-jarvis.
-- **coder @ dragon-lin:** F3 custom Pi harness + harness-update flow (pi/codex-savvy); plus its in-flight constitution P4–P6 (P4 installer rework underpins fleet init/updates — coordinate the install path). Co-testing on dragon-lin (R11).
+- **coder @ dragon-lin:** F3 custom Pi harness + harness-update flow (pi/codex-savvy); plus its in-flight constitution P4–P6 (P4 installer rework underpins `fleet init`/updates — coordinate the install path). Co-testing on dragon-lin (R11).
 - **Shared:** F4 Matrix (whoever has bandwidth); F7 testing/docs continuous.
 
 ## Immediate target: Mos on Discord (F2 first slice)
 
-The discord plugin is available (~/.claude.json). Path: configure the **orchestrator** as a durable
+The discord plugin is available (`~/.claude.json`). Path: configure the **orchestrator** as a durable
 fleet session running Claude Code with the discord plugin bridged to channel `1517622518662434996`
 (server `1112631390438166618`) on w-jarvis, with the existing Discord Bridge Protocol (ack within
 ~3s, reply via `mcp__discord__reply`, no `AskUserQuestion`). Heartbeat via the launcher sidecar.
 
 ## Success criteria
 
-- A non-AI user can mosaic fleet init, pick a type, and get a working fleet + orchestrator.
-- **Mos answers in Discord 1517…** on w-jarvis.
-- Fleet runs + is observable (fleet ps) on **both** w-jarvis and dragon-lin.
+- A non-AI user can `mosaic fleet init`, pick a type, and get a working fleet + orchestrator.
+- **Mos answers in Discord `1517…`** on w-jarvis.
+- Fleet runs + is observable (`fleet ps`) on **both** w-jarvis and dragon-lin.
 - Harness updates handled gracefully; HB healthy for claude + pi/gpt agents.
 - Docs let a new operator install/configure/use the fleet.
 - Re-init + orchestrator mutation work.
 
 ## Assumptions (veto-able)
 
-- `ASSUMPTION:` presets ship as example rosters under the framework (fleet/examples/\*.yaml), selected by `init`.
+- `ASSUMPTION:` presets ship as example rosters under the framework (`fleet/examples/*.yaml`), selected by `init`.
 - `ASSUMPTION:` chat connectors are pluggable; Discord first (target exists), Matrix is the strategic default later.
 - `ASSUMPTION:` "Mos" = a Claude Code orchestrator session with the discord plugin (reuses the documented Discord Bridge Protocol).
 - `ASSUMPTION:` per north star, runtimes default to Codex/pi-on-Codex for workers; the orchestrator "Mos" runs Claude Code (in Claude Code, which is allowed).

docs/fleet/PRD.md

@@ -10,8 +10,8 @@
 The durable tmux fleet runs on the isolated `mosaic-fleet` socket. That isolation
 (which protects the operator's default tmux) makes the fleet **invisible** to default
 tooling, and truth is split across three planes no single command joins — systemd
-(systemctl --user), tmux (-L mosaic-fleet), and the process tree (`pstree`).
-agent tail (`capture-pane`) returns **blank for full-screen TUIs**, and agent send
+(`systemctl --user`), tmux (`-L mosaic-fleet`), and the process tree (`pstree`).
+`agent tail` (`capture-pane`) returns **blank for full-screen TUIs**, and `agent send`
 confirms only keystroke injection, not acceptance. Net: the operator has near-zero
 observability and no safe way to watch a session.
 
@@ -32,22 +32,22 @@ observability and no safe way to watch a session.
 
 ## Functional requirements
 
-| ID   | Requirement                                                                                                                                                                                                                                                                                                  |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FR-1 | mosaic fleet ps [--json] prints one row per roster agent joining: name · tenant · host · runtime · systemd(active/enabled) · pane(alive/dead) · pid · idle · **last-heartbeat age** · **drift** flag (roster runtime ≠ actual pane command) · **boot-enable** warning (active but `UnitFileState=disabled`). |
-| FR-2 | **Heartbeat protocol v1** (see below); `dogfood-agent.py` implements the responder. fleet ps issues probes (or reads last-seen) and reports health per FR-1.                                                                                                                                                 |
-| FR-3 | mosaic agent watch <name> opens a **read-only** view of the pane (grouped session or tmux attach -r) that cannot send keystrokes and does not shrink the agent's window.                                                                                                                                     |
-| FR-4 | mosaic agent attach <name> remains the **explicit** interactive-takeover path (separate verb, documented as the only one that can type).                                                                                                                                                                     |
-| FR-5 | mosaic agent send <name> --verify confirms the message was **accepted** (not left as an unsubmitted draft) and returns non-zero if delivery cannot be verified.                                                                                                                                              |
-| FR-6 | All structured output (`--json`) includes `tenant_id` and `host` fields.                                                                                                                                                                                                                                     |
+| ID   | Requirement                                                                                                                                                                                                                                                                                                    |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR-1 | `mosaic fleet ps [--json]` prints one row per roster agent joining: name · tenant · host · runtime · systemd(active/enabled) · pane(alive/dead) · pid · idle · **last-heartbeat age** · **drift** flag (roster runtime ≠ actual pane command) · **boot-enable** warning (active but `UnitFileState=disabled`). |
+| FR-2 | **Heartbeat protocol v1** (see below); `dogfood-agent.py` implements the responder. `fleet ps` issues probes (or reads last-seen) and reports health per FR-1.                                                                                                                                                 |
+| FR-3 | `mosaic agent watch <name>` opens a **read-only** view of the pane (grouped session or `tmux attach -r`) that cannot send keystrokes and does not shrink the agent's window.                                                                                                                                   |
+| FR-4 | `mosaic agent attach <name>` remains the **explicit** interactive-takeover path (separate verb, documented as the only one that can type).                                                                                                                                                                     |
+| FR-5 | `mosaic agent send <name> --verify` confirms the message was **accepted** (not left as an unsubmitted draft) and returns non-zero if delivery cannot be verified.                                                                                                                                              |
+| FR-6 | All structured output (`--json`) includes `tenant_id` and `host` fields.                                                                                                                                                                                                                                       |
 
 ## Heartbeat protocol v1
 
-- **Probe:** operator/fleet ps writes a sentinel line to the agent's input or a
-  well-known per-agent heartbeat file path ~/.config/mosaic/fleet/run/<agent>.hb.
-- **Response:** the runtime updates <agent>.hb with ts=<iso8601> pid=<pid> status=<ok|busy>
+- **Probe:** operator/`fleet ps` writes a sentinel line to the agent's input or a
+  well-known per-agent heartbeat file path `~/.config/mosaic/fleet/run/<agent>.hb`.
+- **Response:** the runtime updates `<agent>.hb` with `ts=<iso8601> pid=<pid> status=<ok|busy>`
   on a fixed interval (default 15s) and on demand when probed.
-- **Health rule:** `healthy` if now - ts <= 3 × interval; else `stale`; missing file = `unknown`.
+- **Health rule:** `healthy` if `now - ts <= 3 × interval`; else `stale`; missing file = `unknown`.
 - **Contract:** every runtime (dogfood stub now; claude/codex/pi/opencode in Phase 3)
   MUST emit the heartbeat. The protocol is file-based so it works for headless stubs and
   full-screen TUIs alike (no `capture-pane` dependency).
@@ -56,15 +56,15 @@ observability and no safe way to watch a session.
 
 ## Acceptance criteria
 
-- mosaic fleet ps shows all 5 live sessions on `mosaic-fleet` with correct
+- `mosaic fleet ps` shows all 5 live sessions on `mosaic-fleet` with correct
   pane/pid/idle and flags the dogfood **drift** (`canary-pi` runtime=pi but pane runs
   `dogfood-agent.py`) and the **boot-enable** gap (active but disabled).
 - Killing one agent's pane flips its row to dead/stale within one `interval`.
-- agent watch shows live output and provably cannot type into the pane; detaching
+- `agent watch` shows live output and provably cannot type into the pane; detaching
   leaves the agent's window size unchanged.
-- agent send --verify returns success on an accepting pane and non-zero on a wedged/draft pane.
-- Quality gates green: pnpm typecheck, pnpm lint, pnpm format:check, plus
-  pnpm --filter @mosaicstack/mosaic test.
+- `agent send --verify` returns success on an accepting pane and non-zero on a wedged/draft pane.
+- Quality gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, plus
+  `pnpm --filter @mosaicstack/mosaic test`.
 - Independent review passed; dogfood evidence captured against the live fleet.
 
 ## Test plan
@@ -72,18 +72,18 @@ observability and no safe way to watch a session.
 - Unit/CLI specs in `packages/mosaic/src/commands/fleet.spec.ts` (and a new
   `fleet-ps`/`watch`/`send-verify` spec) using the injected `CommandRunner` to assert
   exact tmux/systemd command construction and JSON shape (tenant+host present).
-- Situational: run against the live `mosaic-fleet` fleet; capture fleet ps output,
-  a kill-and-detect cycle, a read-only `watch`, and a send --verify pass/fail pair.
+- Situational: run against the live `mosaic-fleet` fleet; capture `fleet ps` output,
+  a kill-and-detect cycle, a read-only `watch`, and a `send --verify` pass/fail pair.
 
 ## Known limitations
 
-- **Verify heuristic is best-effort:** agent send --verify uses a > -prefix draft
+- **Verify heuristic is best-effort:** `agent send --verify` uses a `>` -prefix draft
   heuristic that is specific to pi/claude TUIs. Draft detection for codex and opencode
   TUIs is best-effort only; those runtimes may not use the same input-line indicator.
 - **Pane-change check is the best Phase-2 signal; verify now polls up to a bounded
-  timeout:** agent send --verify captures a BEFORE snapshot, sends the message, then
+  timeout:** `agent send --verify` captures a BEFORE snapshot, sends the message, then
   polls `capture-pane` every ~400 ms up to a configurable total timeout (default ~6 s,
-  controlled by --verify-timeout <ms>). On each poll it runs classifySendResult: if
+  controlled by `--verify-timeout <ms>`). On each poll it runs classifySendResult: if
   the pane shows 'accepted' or 'draft' the loop exits immediately; while the result is
   'unverifiable' (no pane change yet) it keeps polling. After the timeout with no
   definitive result, it fails closed: exit 1 with "no pane change after send". This
@@ -92,15 +92,15 @@ observability and no safe way to watch a session.
   requires a runtime acknowledgement (Phase-3 heartbeat-ack); the bounded pane-change
   poll is the best signal available against an opaque TUI for Phase-2.
 - **Blank AFTER capture fails closed:** Full-screen TUIs (claude, codex, opencode, pi)
-  render blank for tmux capture-pane. When the AFTER snapshot is empty, send --verify
+  render blank for `tmux capture-pane`. When the AFTER snapshot is empty, `send --verify`
   returns non-zero with an "unverifiable" message rather than silently succeeding. This
   is an intentional fail-closed design (FR-5).
-- **agent watch uses a grouped viewer session:** tmux attach -r directly against the
-  agent session lets the viewer terminal shrink the agent's window. agent watch instead
-  creates a throwaway grouped session (tmux new-session -d -t '=<agent>' -s
-  '<agent>-watch-<pid>'), attaches read-only to that session, and kills it on detach.
+- **`agent watch` uses a grouped viewer session:** `tmux attach -r` directly against the
+  agent session lets the viewer terminal shrink the agent's window. `agent watch` instead
+  creates a throwaway grouped session (`tmux new-session -d -t '=<agent>' -s
+'<agent>-watch-<pid>'`), attaches read-only to that session, and kills it on detach.
   The grouped session shares the agent's windows but has independent sizing, so the
-  agent's window is never affected. tmux attach is still interactive and requires
+  agent's window is never affected. `tmux attach` is still interactive and requires
   inherited stdio; the `interactiveRunner` handles TTY passthrough.
 
 ## Surfaces & parity (MVP-X1)

docs/fleet/README.md

@@ -1,63 +0,0 @@
-# Fleet Configuration Management
-
-This book documents the local roster-v2 desired-state control plane delivered under issue #758. The normative requirements are the [FCM section of the repository PRD](../PRD.md#fleet-declarative-configuration-management-workstream-fcm-758), not the older fleet-suite or observability planning pages.
-
-## Authority boundary
-
-<MOSAIC_HOME>/fleet/roster.yaml is the sole writable desired-state authority for local fleet membership, launch policy, and persisted lifecycle. Generated environment files, systemd enablement, tmux sessions, heartbeat files, and status output are derived or observed. Rebuild projections from the roster; never edit them as desired state.
-
-This control plane is local tmux/systemd only. Remote/SSH entries and connectors are inventory, not reconciliation targets. Arbitrary commands, channels, secret references, gateway catalog convergence, and UI configuration storage are outside this workstream. `mos-comms` is temporary transport glue, not permanent fleet architecture.
-
-## Choose the right workflow
-
-1. **Need to inspect intent?** Read the roster and use mosaic fleet get; see [desired versus observed state](concepts/desired-vs-observed-state.md).
-2. **Need to inspect reality?** Use `status` or `doctor`; use `verify` for a strict non-zero drift/ownership gate. These commands do not repair anything.
-3. **Need to change membership or persisted policy?** Use generation-guarded `plan`, `create`, `update`, or `delete`; see [safe CRUD](how-to/create-update-delete-agent.md).
-4. **Need a one-time runtime action?** Use `start`, `stop`, or `restart`. These do not change persisted desired state.
-5. **Need convergence?** Review apply --dry-run, resolve blockers, then use `apply` with the same current generation; see [reconcile and recover](operations/reconcile-and-recover.md).
-6. **Need v1 migration evidence?** Use preview only. Cutover, canary, and rollback remain held for FCM-M4-002.
-7. **Need the gateway-backed agent catalog?** That is the separate mosaic agent surface, not local fleet desired state.
-
-## Concepts
-
-- [Desired versus observed state](concepts/desired-vs-observed-state.md)
-- [Identity, class, runtime, provider, and model](concepts/identity-class-runtime.md)
-- [Role authority and leases](concepts/role-authority-and-leases.md)
-- [Generated environment launch chain](concepts/generated-env-launch-chain.md)
-
-## Operator how-to
-
-- [Create, inspect, update, and delete](how-to/create-update-delete-agent.md)
-- [Start, stop, restart, and reconcile](how-to/start-stop-restart.md)
-- [Configure an interaction instance](how-to/configure-tess-interaction.md)
-- [Configure a validator instance](how-to/configure-ultron-validator.md)
-- [Customize roles](how-to/customize-roles.md)
-
-## Operations and recovery
-
-- [Reconcile and recover](operations/reconcile-and-recover.md)
-- [Environment quarantine](operations/env-quarantine.md)
-- [Systemd/tmux troubleshooting](operations/systemd-tmux-troubleshooting.md)
-- [Backup and restore boundary](operations/backup-restore.md)
-- [Upgrade and asset-drift hold](operations/upgrade-assets.md)
-
-## Reference and migration
-
-- [Roster v2 fields](reference/roster-v2-fields.md) · [executable JSON Schema](reference/roster-v2.schema.json) · [validated example](examples/roster-v2.yaml)
-- [CLI and exit codes](reference/cli.md)
-- [Role classes](reference/role-classes.md)
-- [Lifecycle transitions](reference/lifecycle-transitions.md)
-- [Status and drift](reference/status-and-drift.md)
-- [Generated environment boundary](reference/generated-env-boundary.md)
-- [v1-to-v2 preview](migration/v1-to-v2.md)
-- [Example/profile dispositions](migration/example-profile-disposition.md)
-- [Legacy class aliases](migration/legacy-class-aliases.md)
-
-## Acceptance evidence and holds
-
-- [M0/M5 IA checklist](FLEET-CONFIG-DOCS-IA-CHECKLIST.md)
-- [Legacy example/profile inventory](LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md)
-- [M5 closure evidence](../reports/documentation/758-fleet-config-ia-closure.md)
-- [Approved-existing deferrals and live-action holds](../reports/deferred/758-fleet-config-deferrals.md)
-
-The canonical publishing source remains this repository. This card does not publish externally, run a migration, operate a live fleet, or close parent issue #758.

docs/fleet/TASKS.md

@@ -7,21 +7,21 @@
 > Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/north-star.md](./north-star.md)
 > Status: `not-started` | `in-progress` | `done` | `blocked` | `failed`
 
-| id            | status      | description                                                                                                      | depends_on            | agent       | pr  | notes                                                                                                                       |
-| ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
-| FLEET-OBS-000 | done        | Plan: north-star + Phase-2 PRD + workstream scaffolding                                                          | —                     | lead        | —   | persisted 2026-06-20 on `feat/fleet-observability`                                                                          |
-| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                      | FLEET-OBS-000         | lead        | —   | file-based ~/.config/mosaic/fleet/run/<agent>.hb; spec in PRD                                                               |
-| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                              | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc mosaic yolo fleet agent (dogfood)                                                                      |
-| FLEET-OBS-003 | done        | mosaic fleet ps — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
-| FLEET-OBS-004 | done        | mosaic agent watch <name> — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | attach -r; verb wired                                                                                                       |
-| FLEET-OBS-005 | done        | mosaic agent send --verify — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
-| FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                     | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
-| FLEET-OBS-007 | not-started | Framework doc: fleet observability guide + verbs                                                                 | FLEET-OBS-003,004,005 | lead        | —   | `docs/guides/` or `framework/tools/.../README`                                                                              |
-| FLEET-OBS-008 | not-started | Independent review + dogfood verification on live fleet                                                          | FLEET-OBS-002..007    | reviewer    | —   | author ≠ reviewer; capture evidence in scratchpad                                                                           |
-| FLEET-OBS-009 | not-started | Open PR → green CI (queue guard) → squash-merge → close `fleet-observability-1`                                  | FLEET-OBS-008         | lead        | —   | trunk merge; no direct push to main                                                                                         |
+| id            | status      | description                                                                                                        | depends_on            | agent       | pr  | notes                                                                                                                       |
+| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
+| FLEET-OBS-000 | done        | Plan: north-star + Phase-2 PRD + workstream scaffolding                                                            | —                     | lead        | —   | persisted 2026-06-20 on `feat/fleet-observability`                                                                          |
+| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                        | FLEET-OBS-000         | lead        | —   | file-based `~/.config/mosaic/fleet/run/<agent>.hb`; spec in PRD                                                             |
+| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                                | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc `mosaic yolo` fleet agent (dogfood)                                                                    |
+| FLEET-OBS-003 | done        | `mosaic fleet ps` — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
+| FLEET-OBS-004 | done        | `mosaic agent watch <name>` — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | `attach -r`; verb wired                                                                                                     |
+| FLEET-OBS-005 | done        | `mosaic agent send --verify` — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
+| FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                       | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
+| FLEET-OBS-007 | not-started | Framework doc: fleet observability guide + verbs                                                                   | FLEET-OBS-003,004,005 | lead        | —   | `docs/guides/` or `framework/tools/.../README`                                                                              |
+| FLEET-OBS-008 | not-started | Independent review + dogfood verification on live fleet                                                            | FLEET-OBS-002..007    | reviewer    | —   | author ≠ reviewer; capture evidence in scratchpad                                                                           |
+| FLEET-OBS-009 | not-started | Open PR → green CI (queue guard) → squash-merge → close `fleet-observability-1`                                    | FLEET-OBS-008         | lead        | —   | trunk merge; no direct push to main                                                                                         |
 
 ## Proposed MVP rollup row (for the MVP orchestrator — not written by this workstream)
 
-```text-table
+```
 | W-FLEET | in-progress | Fleet (agent-session execution layer) | Phase 2/5 | docs/fleet/TASKS.md | observability dogfooded on live stub fleet; control plane rides federation (W1) |
 ```

docs/fleet/backlog-conventions.md

@@ -2,10 +2,10 @@
 
 The **backlog** is Mosaic's native backlog-of-record for fleet work. It is built
 end-to-end on Mosaic's own storage layer (`@mosaicstack/db`, drizzle/Postgres)
-and surfaced as mosaic fleet backlog <sub> --json.
+and surfaced as `mosaic fleet backlog <sub> --json`.
 
 > **Mosaic-native, no Hermes.** This backlog REPLACES the former Hermes adapter.
-> There is **no** runtime dependency on Hermes, hermes kanban, or ~/.hermes
+> There is **no** runtime dependency on Hermes, `hermes kanban`, or `~/.hermes`
 > anywhere in this feature. Anything previously delegated to Hermes is recreated
 > here on Mosaic's own Postgres storage layer.
 
@@ -14,23 +14,24 @@ 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` 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                                   |
+| 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` |
 
 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.
 
-For embedded PGlite only, the local backlog routine may prepare its local schema on first use. **Current operator behavior is PGlite-only.** The PostgreSQL path is held until KBN-101 activation; no current PostgreSQL CLI route, runner, or first-use migration is available or authorized. A future activated PostgreSQL runtime may connect only after its separately certified readiness gate.
+The schema (`backlog` table) is created automatically on first CLI use:
+`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
 
 ### Update safety
 
-The embedded PGlite store lives under ~/.config/mosaic/fleet/backlog, which is
+The embedded PGlite store lives under `~/.config/mosaic/fleet/backlog`, which is
 listed in `PRESERVE_PATHS` in `packages/mosaic/framework/install.sh`. This means
-mosaic update (which runs the framework sync with rsync --delete) will **not**
+`mosaic update` (which runs the framework sync with `rsync --delete`) will **not**
 wipe the operator's backlog — same protection as the roster, per-agent env, and
 heartbeat run dir.
 
@@ -46,10 +47,10 @@ A card is one row in the `backlog` table:
 | `phase`             | text (nullable)     | Board/phase grouping (see below).                             |
 | `priority`          | int (default 0)     | **Higher = sooner.** Claim picks the max-priority ready card. |
 | `status`            | enum                | `ready` \| `claimed` \| `blocked` \| `done`.                  |
-| `depends_on`        | jsonb string[]      | DAG edges — ids of cards this one depends on.                 |
+| `depends_on`        | jsonb `string[]`    | DAG edges — ids of cards this one depends on.                 |
 | `claim_owner`       | text (nullable)     | Owner token of the active claim.                              |
 | `claim_ttl_seconds` | int (nullable)      | TTL of the active claim.                                      |
-| `claimed_at`        | timestamptz (null)  | When the claim was taken. claimed_at + ttl = expiry.          |
+| `claimed_at`        | timestamptz (null)  | When the claim was taken. `claimed_at + ttl` = expiry.        |
 | `attempts`          | int (default 0)     | Incremented each time the card is claimed.                    |
 | `idempotency_key`   | text (unique, null) | Dedups `create`; NULLs are distinct in Postgres.              |
 | `acceptance`        | jsonb (nullable)    | Acceptance criteria (array of strings or object).             |
@@ -65,12 +66,12 @@ would add ceremony without benefit.
 ### Board / phase convention
 
 `phase` is a free-form grouping string used as the board column / milestone label
-(e.g. `M1`, `fleet`, `infra`). list --phase <phase> filters to one board lane.
+(e.g. `M1`, `fleet`, `infra`). `list --phase <phase>` filters to one board lane.
 `priority` orders cards **within** the ready pool regardless of phase.
 
 ## Status lifecycle
 
-```text-diagram
+```
             create
               │
               ▼
@@ -87,49 +88,51 @@ would add ceremony without benefit.
 - **blocked** — explicitly parked; never auto-claimed.
 - **done** — completed; satisfies dependents.
 
-## Atomic claim (FOR UPDATE SKIP LOCKED) + TTL
+## Atomic claim (`FOR UPDATE SKIP LOCKED`) + TTL
 
 `claim` is atomic. Inside a single transaction it locks candidate `ready` rows
-with SELECT ... FOR UPDATE SKIP LOCKED (via the drizzle `sql` operator), picks
+with `SELECT ... FOR UPDATE SKIP LOCKED` (via the drizzle `sql` operator), picks
 the highest-priority deps-satisfied card, and flips it to `claimed`. Because a row
 already locked by a concurrent claimer is **skipped**, two claimers can **never**
 both win the same card — the loser falls through to the next candidate or gets
 `null`. (Proven by the concurrency tests in `packages/db/src/backlog.spec.ts`.)
 
 - **Deps gate:** a card is only claimable when every id in `depends_on` is `done`.
-- **TTL:** claim --ttl <sec> (default **900s**) records `claim_ttl_seconds`.
-- **reclaim:** releases claims whose claimed_at + ttl is in the past (expired)
-  back to `ready`, clearing the claim fields. reclaim --id <id> force-releases a
+- **TTL:** `claim --ttl <sec>` (default **900s**) records `claim_ttl_seconds`.
+- **reclaim:** releases claims whose `claimed_at + ttl` is in the past (expired)
+  back to `ready`, clearing the claim fields. `reclaim --id <id>` force-releases a
   specific card regardless of expiry. This is how a crashed worker's card returns
   to the pool.
 
-## CLI — mosaic fleet backlog <sub> --json
+## CLI — `mosaic fleet backlog <sub> --json`
 
 All subcommands support `--json`.
 
-| Subcommand                                                                                  | Purpose                                                                                   |
-| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key] | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
-| list [--status --phase --ready-only]                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
-| claim --owner [--ttl <sec> --id <id>]                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
-| reclaim [--id <id>]                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
-| link --from --to                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
-| `stats`                                                                                     | Counts by status, oldest-ready age, expired-claim count.                                  |
-| block --id                                                                                  | Set a card to `blocked`.                                                                  |
-| complete --id                                                                               | Set a card to `done` (releases any claim).                                                |
+| Subcommand                                                                                    | Purpose                                                                                   |
+| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key]` | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
+| `list [--status --phase --ready-only]`                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
+| `claim --owner [--ttl <sec> --id <id>]`                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
+| `reclaim [--id <id>]`                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
+| `link --from --to`                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
+| `stats`                                                                                       | Counts by status, oldest-ready age, expired-claim count.                                  |
+| `block --id`                                                                                  | Set a card to `blocked`.                                                                  |
+| `complete --id`                                                                               | Set a card to `done` (releases any claim).                                                |
 
 ### Example
 
-Seed two cards; the second depends on the first. Because A2 is gated on A1, claim returns A1 first. Finish A1, then list A2 as ready. Recover stalled work.
-
-```fleet-command
+```sh
+# Seed two cards, the second depends on the first.
 mosaic fleet backlog create --id A1 --title "schema" --priority 5
 mosaic fleet backlog create --id A2 --title "service" --depends-on A1 --priority 9
 
+# A2 is gated on A1, so claim returns A1 first.
 mosaic fleet backlog claim --owner worker-1 --ttl 600 --json
 
+# Finish A1; now A2 is ready.
 mosaic fleet backlog complete --id A1
 mosaic fleet backlog list --ready-only --json
 
+# Recover stalled work.
 mosaic fleet backlog reclaim --json
 ```

docs/fleet/concepts/desired-vs-observed-state.md

@@ -1,42 +0,0 @@
-# Desired, Derived, and Observed Fleet State
-
-## One writable authority
-
-The canonical local v2 roster at <MOSAIC_HOME>/fleet/roster.yaml is desired state. Membership, stable identity, class, runtime/provider/model selection, launch policy, enablement, and persisted `running`/`stopped` intent are written only through generation-guarded roster mutations.
-
-Derived projections are reproducible consequences of that authority:
-
-- <name>.env.generated;
-- exact roster-named tmux sessions on the configured socket after reconciliation;
-- systemd service targets managed by installation/reconciliation.
-
-Current systemd unit enablement is not yet lifecycle-conformant at boot: installation can enable every
-agent unit, and the launcher projection does not carry `enabled` or `desired_state`. Therefore reboot
-preservation for stopped/disabled agents remains an FCM-M3-002 acceptance hold, not a guaranteed
-projection behavior.
-
-Observed evidence available to current roster-v2 status commands includes systemd active state, tmux
-presence, holder ownership, and unmanaged sessions. Heartbeat files are observational in the wider fleet,
-but roster-v2 `status`, `doctor`, and `verify` do not currently read them. Observation never writes back
-to the roster.
-
-## Generation and ownership
-
-`generation` is a positive integer concurrency fence. A mutating request must provide the current value. Successful changed CRUD increments it exactly once; stale or concurrent writers fail before mutation. Apply/reconcile rereads the canonical roster under a private exclusive lock and uses only that generation and content for effects.
-
-Ownership is exact, never fuzzy. Reconciliation is limited to roster names, the configured socket, the exact holder session, a private installation identity, and private managed paths. An ownership mismatch, unmanaged session, unsafe path, stale generation, or ambiguous lock fails closed.
-
-## Drift decisions
-
-| Observation                              | Interpretation           | Safe response                                                          |
-| ---------------------------------------- | ------------------------ | ---------------------------------------------------------------------- |
-| Generated file differs or is missing     | Derived projection drift | Review apply --dry-run; regenerate from the roster.                    |
-| Desired `running`, exact session missing | `missing-session`        | Diagnose ownership/runtime, then reconcile if safe.                    |
-| Desired `stopped`, exact session present | `unexpected-session`     | Inspect; reconciliation may stop only the proven roster target.        |
-| Disabled agent running                   | `disabled-running`       | Inspect; disabled state wins during explicit safe reconciliation.      |
-| Unknown session on the configured socket | Unmanaged state          | Report only. Do not adopt, rename, or kill it.                         |
-| Heartbeat stale in the wider fleet       | Liveness evidence        | Diagnose separately; current roster-v2 status does not read heartbeat. |
-
-`status` and `doctor` classify. `verify` is also observational but exits non-zero when ownership, drift, or unmanaged-state checks fail. `plan`/apply --dry-run validates proposed projection and lifecycle work without mutation. `apply` and `reconcile` converge only after all preconditions pass.
-
-A partial projection failure does not roll the roster back. Treat the committed roster as authority and regenerate. A lifecycle failure after projection completion preserves both roster and projections for inspection. Sensitive legacy values are never printed; diagnostics are bounded to stable codes, key names where applicable, and hashes.

docs/fleet/concepts/generated-env-launch-chain.md

@@ -1,23 +0,0 @@
-# Generated Environment Launch Chain
-
-The launcher consumes validated data, not shell configuration.
-
-1. Read and validate the canonical roster.
-2. Render deterministic <name>.env.generated data from that roster.
-3. Parse optional <name>.env.local through a strict allowlist.
-4. Reject generated-key shadowing, unknown or sensitive-looking keys, unsafe paths/values, duplicates, malformed lines, shell syntax, and command overrides.
-5. Derive the runtime command from validated runtime/model/reasoning data.
-6. Target only the exact configured tmux socket and roster session after ownership checks.
-
-## File precedence and ownership
-
-| File              | Owner                    | Use                                                                         |
-| ----------------- | ------------------------ | --------------------------------------------------------------------------- |
-| `.env.generated`  | Mosaic projection writer | Complete deterministic roster projection. Rebuild; do not edit.             |
-| `.env.local`      | Operator                 | Optional, private, strict machine-local data. Cannot shadow generated keys. |
-| `.env`            | Legacy input             | One-time migration input only; never launch authority.                      |
-| `.env.quarantine` | Private quarantine       | Retained unsafe legacy evidence; never loaded by the launcher.              |
-
-Neither systemd nor the launcher sources these files. No `eval`, shell expansion, arbitrary `MOSAIC_AGENT_COMMAND`, channel, or secret-reference compatibility path exists. Safe legacy generated keys are regenerated, allowed local keys are relocated, and unsafe material is quarantined.
-
-Diagnostics never expose the rejected value, credential material, or command text. They are bounded to stable rule code, key name where safe, and SHA-256 content identity. See [generated environment reference](../reference/generated-env-boundary.md) and [quarantine operations](../operations/env-quarantine.md).

docs/fleet/concepts/identity-class-runtime.md

@@ -1,20 +0,0 @@
-# Fleet Identity, Class, and Runtime
-
-Each roster field has one job. Do not use names or model strings as authority shortcuts.
-
-| Concern                 | Field                         | Contract                                                                                     |
-| ----------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
-| Stable machine identity | agents[].name                 | Unique, immutable mutation target and exact service/session name.                            |
-| Display identity        | agents[].alias                | Human-facing label only; may be changed and grants no authority.                             |
-| Behavioral contract     | agents[].class                | Resolves through the shared baseline plus `roles.local` persona library.                     |
-| Tool boundary           | agents[].tool_policy          | Must match protected canonical classes; cannot independently grant authority.                |
-| Harness                 | agents[].runtime              | One of `claude`, `codex`, `opencode`, or `pi`, declared in `runtimes`.                       |
-| Backend selection       | agents[].provider and `model` | Explicit non-empty data; capability validity is not inferred from the display name or class. |
-| Effort                  | agents[].reasoning            | `low`, `medium`, or `high`.                                                                  |
-| Local placement         | `working_directory`           | Explicit safe local work path; not remote placement authority.                               |
-
-Tess and Ultron are conventional instance/display names only. They are not products, required machine identities, role aliases, or authority-bearing classes. A configurable interaction instance uses class: interaction; a configurable validation instance uses class: validator. Any stable name and alias satisfying the structural contract may be used.
-
-Class aliases are deliberately narrow: implementer → code, reviewer → review, and operator-interaction → interaction. No runtime, provider, model, persona prose, or instance name changes this mapping. See [role classes](../reference/role-classes.md) and the [validated generic example](../examples/roster-v2.yaml).
-
-Roster v2 is local-only. It contains no host/SSH placement, connector, channel, secret-reference, arbitrary-command, per-agent socket, or gateway mapping fields. Those concerns require separate requirements and threat models.

docs/fleet/concepts/role-authority-and-leases.md

@@ -1,22 +0,0 @@
-# Fleet Role Authority and Leases
-
-Role content describes behavior; protected authority is immutable code metadata derived only from the canonical class.
-
-## Required workstream classes
-
-`code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction` are required FCM classes. `merge-gate` is additionally protected because it remains the sole approve-to-land and merge authority.
-
-| Class                                        | Authority                                         | Boundary                                                                               |
-| -------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `merge-gate`                                 | Approve-to-land and merge                         | Sole merge authority.                                                                  |
-| `validator`                                  | Issue independent validation evidence/certificate | Never approves landing or merges.                                                      |
-| `orchestrator`                               | Orchestrate topology and issue bounded leases     | Does not gain merge authority.                                                         |
-| `team-leader`                                | Use explicitly leased capacity                    | Cannot issue leases or mutate roster, credentials, topology authority, or merge state. |
-| `interaction`                                | Receive requests and report status                | Cannot orchestrate, issue leases, mutate configuration, or merge.                      |
-| `code`, `review`, `enhancer`, custom classes | No protected authority by default                 | Persona prose cannot grant protected powers.                                           |
-
-A lease is capacity authorization from an orchestrator, not ownership. It must identify a bounded task or period and does not alter the leased agent's roster identity, role contract, credentials, authority, or persisted lifecycle. Expiry/revocation returns capacity; it does not rewrite the roster.
-
-Semantic validation rejects protected class/tool-policy mismatch in either direction. An instance named Ultron with class: validator remains validation-only. An instance named Tess with class: interaction remains request/status-only. Renaming either instance changes no authority.
-
-For resolver layering and safe customization, see [role classes](../reference/role-classes.md) and [customize roles](../how-to/customize-roles.md).

docs/fleet/examples/roster-v2.yaml

@@ -1,61 +0,0 @@
-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: code-example
-    alias: Code Example
-    class: code
-    runtime: pi
-    provider: example-provider
-    model: example-model
-    reasoning: medium
-    tool_policy: code
-    working_directory: ~/src
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: false
-  - name: interaction-example
-    alias: Interaction Example
-    class: interaction
-    runtime: pi
-    provider: example-provider
-    model: example-model
-    reasoning: low
-    tool_policy: interaction
-    working_directory: ~/src
-    persistent_persona: true
-    reset_between_tasks: false
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: false
-  - name: validator-example
-    alias: Validator Example
-    class: validator
-    runtime: pi
-    provider: example-provider
-    model: example-model
-    reasoning: high
-    tool_policy: validator
-    working_directory: ~/src
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: false

docs/fleet/f4-matrix-connector.md

@@ -15,7 +15,7 @@ core.
 
 Connectors implement one small, uniform interface (`src/fleet/connectors/types.ts`):
 
-```typescript
+```ts
 interface OrchestratorConnector {
   readonly kind: 'tmux' | 'discord' | 'matrix';
   send(message: OutboundMessage): Promise<SendResult>; // orchestrator → human
@@ -25,11 +25,11 @@ interface OrchestratorConnector {
 ```
 
 - **send / subscribe / health** — the only surface fleet core depends on. `SendResult` is the
-  ack half; health() is the liveness half.
+  ack half; `health()` is the liveness half.
 - **Thread-aware by metadata** — `OutboundMessage.threadId` / `InboundMessage.threadId` are
   optional, so thread-capable connectors (Matrix rooms/threads, the future first-party Mosaic
   Discord plugin) fit **without an interface change**.
-- **Registry** (`registry.ts`) — implementations register a factory by kind; createConnector(config)
+- **Registry** (`registry.ts`) — implementations register a factory by kind; `createConnector(config)`
   resolves one from roster config. Phase 1 ships the registry + `resolveConnectorKind` (defaults
   `tmux` when a roster declares no connector — **back-compat**); the factories land in Phase 2.
 
@@ -39,7 +39,7 @@ A roster may carry an optional `connector` block (`roster.schema.json`); absent
 
 ```yaml
 connector:
-  kind: matrix
+  kind: matrix # tmux | discord | matrix
   matrix:
     homeserver_url: https://matrix.example.internal
     user_id: '@mos:example.internal'
@@ -55,12 +55,12 @@ reject a token committed to a shipped file anyway.
 The connector speaks the **Matrix client-server API** directly over HTTPS (`fetch` — no SDK needed
 for MVP), so it is **homeserver-agnostic**:
 
-| Op          | Matrix CS-API                                                           |
-| ----------- | ----------------------------------------------------------------------- |
-| `send`      | PUT /\_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}      |
-| `subscribe` | GET /\_matrix/client/v3/sync (long-poll, `since` token) → room timeline |
-| `health`    | GET /\_matrix/client/versions (reachable) + …/account/whoami (authed)   |
-| threads     | `m.thread` relations ↔ `threadId`                                       |
+| Op          | Matrix CS-API                                                            |
+| ----------- | ------------------------------------------------------------------------ |
+| `send`      | `PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}`      |
+| `subscribe` | `GET /_matrix/client/v3/sync` (long-poll, `since` token) → room timeline |
+| `health`    | `GET /_matrix/client/versions` (reachable) + `…/account/whoami` (authed) |
+| threads     | `m.thread` relations ↔ `threadId`                                        |
 
 ## Local homeserver (infra, not connector code)
 
@@ -79,7 +79,7 @@ homeserver choice is a **deployment** concern (a Phase-2 deploy guide), not conn
 | ----- | --------------------------------------------------------------------------------------- | ------- |
 | **1** | Connector interface + types, registry + kind resolution, roster `connector` schema, doc | ✅ yes  |
 | 2     | Matrix CS-API client (fetch-based send/sync/health) + registered factory + tests        | follow  |
-| 2     | fleet init / `configure` connector-selection UX; roster parse wires the block           | follow  |
+| 2     | `fleet init` / `configure` connector-selection UX; roster parse wires the block         | follow  |
 | 2     | systemd launch wiring so the orchestrator starts on the chosen connector                | follow  |
 | 3     | Conduit deploy guide; first-party Mosaic Discord (threads) registers as a connector     | follow  |
 

docs/fleet/how-to/configure-tess-interaction.md

@@ -1,21 +0,0 @@
-# Configure an Interaction Instance
-
-An interaction instance is a configurable local roster member with canonical class: interaction and matching tool_policy: interaction. “Tess” may be used as a display alias, but neither that alias nor the stable name is required or authority-bearing.
-
-Use the [validated generic roster](../examples/roster-v2.yaml) as the safe shape. Choose a unique stable `name`, any descriptive `alias`, a supported declared runtime, explicit provider/model/reasoning, and a safe work directory. Start with:
-
-```yaml
-name: interaction-example
-alias: Interaction Example
-class: interaction
-tool_policy: interaction
-lifecycle:
-  enabled: true
-  desired_state: stopped
-```
-
-Plan the complete agent payload with the current roster generation, then create it without `--persisted-start`. Creation defaults to enabled/stopped and performs no runtime action. Review the resulting roster and projection plan before any later lifecycle decision.
-
-The interaction class is request/status only. It cannot orchestrate, issue leases, mutate the roster/configuration, grant credentials, certify validation, approve landing, or merge. Connector and channel configuration are outside roster v2; do not add connector, channel, secret, command, remote-host, or gateway fields.
-
-See [safe CRUD](create-update-delete-agent.md), [identity separation](../concepts/identity-class-runtime.md), and [role authority](../concepts/role-authority-and-leases.md).

docs/fleet/how-to/configure-ultron-validator.md

@@ -1,21 +0,0 @@
-# Configure a Validator Instance
-
-A validator instance is a configurable local roster member with canonical class: validator and matching tool_policy: validator. “Ultron” may be used as a display alias, but it is not a required identity, class alias, product name, or source of authority.
-
-Use the [validated generic roster](../examples/roster-v2.yaml) as the safe shape. Choose a unique stable name and explicit supported runtime/provider/model/reasoning values. Start stopped:
-
-```yaml
-name: validator-example
-alias: Validator Example
-class: validator
-tool_policy: validator
-lifecycle:
-  enabled: true
-  desired_state: stopped
-```
-
-Plan the full payload with the current generation and create without `--persisted-start`. Creation writes desired state and projections only; it does not launch a validator.
-
-`validator` may issue independent validation evidence or a certificate. It has no approve-to-land or merge authority. `merge-gate` remains the sole protected merge authority, and changing the validator's name, alias, persona prose, runtime, provider, model, or tool-policy text cannot elevate it.
-
-Certificate consumption and final release evidence remain FCM-M5-002 gates. This page does not create a certificate or authorize merge. See [safe CRUD](create-update-delete-agent.md) and [role authority](../concepts/role-authority-and-leases.md).

docs/fleet/how-to/create-update-delete-agent.md

@@ -1,74 +0,0 @@
-# Create, Inspect, Update, and Delete a Local Fleet Agent
-
-Use the local roster-v2 control plane only. These commands change desired state and derived environment projections; they never start, stop, reconcile, inspect, or otherwise act on systemd, tmux, sessions, or runtimes.
-
-## Read and plan first
-
-```fleet-synopsis
-mosaic fleet get <name>
-mosaic fleet plan create --expected-generation <n> --agent '<json>'
-mosaic fleet plan update <name> --expected-generation <n> --agent '<json>'
-mosaic fleet plan delete <name> --expected-generation <n>
-```
-
-plan create takes the name from `--agent`. plan update and plan delete require the target name immediately after the operation. A plan is deterministic and side-effect free: it validates the complete proposed roster and projection targets without changing files. Use `--dry-run` on `create`, `update`, or `delete` for the same no-write result.
-
-Every successful command prints JSON. `get` returns { "generation", "agent" }; mutation results contain `plan`, `applied`, `authoritativeRoster`, and `projections`.
-
-## Create safely
-
-```fleet-command
-mosaic fleet create --expected-generation 7 --agent '{
-  "name":"coder0",
-  "alias":"Coder 0",
-  "className":"code",
-  "runtime":"pi",
-  "provider":"openai",
-  "model":"gpt-5.6-sol",
-  "reasoning":"high",
-  "toolPolicy":"code",
-  "workingDirectory":"/srv/mosaic",
-  "persistentPersona":false,
-  "resetBetweenTasks":true,
-  "launch":{"yolo":true}
-}'
-```
-
-Create defaults to enabled: true and desired_state: stopped. It does not start a process. Add `--persisted-start` only to persist desired_state: running; that still does not start a runtime in this M2 command. The JSON payload is an allowlist of the roster-v2 fields shown above plus `launch.yolo`; command, channel, secret-reference, and other unknown keys are rejected rather than ignored. The JSON error exposes only a stable code, never the rejected value.
-
-## Update and delete safely
-
-```fleet-synopsis
-mosaic fleet update <name> --expected-generation <n> --agent '<complete JSON agent payload>'
-mosaic fleet delete <name> --expected-generation <n>
-```
-
-Updates require a complete agent JSON payload and preserve the stable name. Delete removes only the exact roster-owned `coder0.env.generated` projection. It retains `coder0.env.local`, legacy `coder0.env`, `coder0.env.quarantine`, and every unrelated projection. A delete dry-run leaves all of those files byte-identical.
-
-## Handle generation conflicts
-
-Every mutation requires the current authoritative `--expected-generation`. A stale value returns JSON error.code: "stale-generation" with a non-zero exit. Reload with mosaic fleet get <name> or reread the roster, plan again using the returned generation, then retry. A concurrent mutation returns `concurrent-mutation`; do not force or bypass the lock.
-
-## Interpret partial failures
-
-The roster is authoritative and is written before derived projections. A late projection I/O failure returns non-zero with redacted, actionable JSON:
-
-```json
-{
-  "applied": false,
-  "authoritativeRoster": "committed",
-  "projections": "incomplete",
-  "recovery": {
-    "code": "projection-apply-failed",
-    "action": "regenerate-projections-from-roster"
-  }
-}
-```
-
-This is not a rollback and not a no-op: reload the roster because its generation and membership were committed, regenerate projections from that roster, then plan a new mutation. Recovery output never contains environment values, credentials, or command text.
-
-## Exit and boundary behavior
-
-Handled validation errors and partial projection failures exit non-zero. `plan`/`--dry-run` and normal mutation JSON make the state explicit; scripts should use both the exit code and `authoritativeRoster`/`projections`, not `applied` alone.
-
-The commands operate only on <mosaic-home>/fleet/roster.yaml, the local roster desired-state authority. They do not accept arbitrary commands, channels, secrets, remote/connector actions, migration/canary actions, or runtime lifecycle operations.

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

@@ -2,8 +2,8 @@
 
 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.
+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.
@@ -34,11 +34,11 @@ A custom class remains supported when a readable contract exists for the exact i
 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.
+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.
+contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.
 
 ## Validation and authority boundaries
 

docs/fleet/how-to/start-stop-restart.md

@@ -1,23 +0,0 @@
-# Safely Reconcile and Control a Local Fleet Agent
-
-Use the canonical local roster-v2 command surface:
-
-```fleet-synopsis
-mosaic fleet apply --expected-generation <n> --dry-run
-mosaic fleet apply --expected-generation <n>
-mosaic fleet reconcile --expected-generation <n>
-mosaic fleet start <name> --expected-generation <n>
-mosaic fleet stop <name> --expected-generation <n>
-mosaic fleet restart <name> --expected-generation <n>
-mosaic fleet status [<name>]
-mosaic fleet verify
-mosaic fleet doctor
-```
-
-Start with `--dry-run`. It validates roster semantics, deterministic projections, private managed paths, exact holder ownership, and named-socket state without changing files or lifecycle state. Explicit `apply` and `reconcile` rebuild derived projections and enforce persisted roster state: enabled `running` agents may start, while stopped or disabled agents are not started. This guarantee does not extend to reboot/service activation yet; boot preservation remains an FCM-M3-002 hold.
-
-`start`, `stop`, and `restart` are explicit one-shot exact-service actions. They do not persist a lifecycle change. `update` preserves the agent's existing lifecycle, and no delivered operation changes durable lifecycle after creation.
-
-Every command prints JSON. Observation commands report drift without mutation; `verify` exits non-zero on ownership mismatch, unmanaged sessions, or drift. A failed apply that wrote some derived projections reports projections: "incomplete" with bounded recovery to regenerate from the roster. A lifecycle failure after projections reports incomplete lifecycle work; it is never represented as a rollback or no-op.
-
-These commands are local only. Remote/SSH/connector entries are inventory/validation-only. Commands do not accept arbitrary runtime commands, channels, secrets, generated-file desired state, or arbitrary tmux sockets.

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

@@ -1,69 +0,0 @@
-# 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.             |
-
-## M4 migration-preview evidence
-
-FCM-M4-001 layers an executable migration posture over the same 13-entry M1 inventory without
-changing the retained artifact classification:
-
-- every `v1-fixture` is previewed only with explicit class and lifecycle evidence;
-- every `canonical-profile` remains validated by the shared baseline-plus-`roles.local` resolver;
-- the canonical service policy remains generic and uses only the approved tool-policy alias.
-
-`validateShippedFleetMigrationDispositions` first runs the existing executable M1 guard, then requires
-explicit decisions and lifecycle observations and executes `previewV1ToV2Migration` for every shipped
-v1 fixture. `collectShippedFleetMigrationDispositions` derives the 13-entry posture directly from
-`SHIPPED_FLEET_ARTIFACT_DISPOSITIONS`, so additions or removals continue to fail the M1 guard rather
-than creating a second artifact list. None of these dispositions claims a cutover, canary, or
-rollback; those gates belong to FCM-M4-002. See [v1-to-v2 preview](./v1-to-v2.md).
-
-## Running the guard
-
-```fleet-command
-pnpm --filter @mosaicstack/mosaic test -- v1-v2-migration.spec.ts \
-  -t "validates all 13 shipped artifacts and executes ready previews for every v1 fixture"
-```
-
-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/v1-to-v2.md

@@ -1,86 +0,0 @@
-# Previewing a Fleet Roster v1-to-v2 Migration
-
-**Issue:** #758 · **Card:** FCM-M4-001 · **Effect boundary:** preview only
-
-mosaic fleet migrate-v1 preview inventories a v1 roster and emits a canonical v2 candidate plus
-recovery evidence. It does not write a roster, apply environment projections, invoke systemd or
-`tmux`, contact connectors or remote hosts, launch an agent, run a canary, or execute rollback.
-FCM-M4-002 owns reversible cutover and rollback.
-
-## Inputs
-
-```fleet-command
-mosaic fleet migrate-v1 preview \
-  --source roster-v1.yaml \
-  --decisions migration-decisions.json \
-  --observations reviewed-observations.json
-```
-
-The command emits one JSON object and exits nonzero when the preview is blocked, including when any of
-`--source`, `--decisions`, or `--observations` is omitted, passed without a path value, or passed an empty
-path value. These request-shape failures are reported before any input file is read. Decision and
-observation JSON is validated fail-closed: unknown fields, malformed values, and records for non-local
-agents are rejected. Decisions must supply a positive v2 `generation`, a reviewed `fleetHost` whenever
-v1 agents include `host` or `ssh`, explicit `defaultRuntime`, and per-local-agent provider, model,
-reasoning, enabled state, and launch policy. The v1 source remains authoritative for socket semantics:
-a supported declared socket field, including an explicit empty value for the default tmux server, is
-preserved; if both supported root aliases are absent, the production v1 default is the literal empty socket.
-A matching `socketName` decision is accepted and an incompatible decision blocks, but a decision never
-supplies or repairs a missing source socket. If v1 omitted `tool_policy`, decisions must supply an
-explicit replacement; it is never derived from `class`. `model_hint` is never split or treated as
-authority.
-
-Observations are separate reviewed evidence keyed by local agent name:
-
-```json
-{
-  "coder0": { "systemd": "inactive", "tmux": "missing" }
-}
-```
-
-Only `active` plus `present` maps to `running`; only `inactive` plus `missing` maps to `stopped`.
-Missing, extra, unknown, or contradictory evidence blocks output. An observed-running agent cannot
-be marked disabled. Observed-stopped agents always remain stopped.
-
-## Field disposition
-
-| v1 field                                                                 | v2 disposition                                                                                                                                                                                                                                                                                                                |
-| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`, `transport`, `tmux`, `defaults`, `runtimes`                   | Inventoried and structurally compiled; omitted runtimes retain v1 built-in defaults, while each explicitly declared runtime without a reset field follows the production v1 `/clear` fallback; present-empty holder/work-directory/reset values block                                                                         |
-| agent `name`, `alias`, `runtime`, working directory, persona/reset flags | Copied or explicitly defaulted only when absent; present-empty alias/work-directory values block for explicit disposition. Canonical ~/~/... values stay unchanged in roster evidence and traversal-free forms expand only at the shared production environment-projection boundary before unchanged absolute-path validation |
-| `provider`, `model_hint`, `reasoning_level`                              | Explicit provider/model/reasoning decisions; no model-hint inference                                                                                                                                                                                                                                                          |
-| `class`, `tool_policy`                                                   | Only approved aliases canonicalize automatically; other classes require explicit preserve/replace disposition and shared-resolver validation                                                                                                                                                                                  |
-| `kickstart_template`                                                     | No v2 field; explicit inventory-only disposition required                                                                                                                                                                                                                                                                     |
-| agent `host`, `ssh`                                                      | host != fleetHost is demonstrably remote and inventory-only; host == fleetHost stays local; SSH targets with or without an explicit user must agree with `host`; ssh-only, missing fleet-host evidence, or contradictory targets block                                                                                        |
-| agent `socket`                                                           | Same-host candidate only when it matches the canonical fleet socket; conflicts block for explicit future disposition                                                                                                                                                                                                          |
-| root `connector`                                                         | Inventory-only; never contacted or reconciled                                                                                                                                                                                                                                                                                 |
-| unknown fields or snake/camel synonym collisions                         | Inventoried and block readiness                                                                                                                                                                                                                                                                                               |
-| `.env.generated`                                                         | Rebuild from canonical roster data                                                                                                                                                                                                                                                                                            |
-| no legacy `.env`                                                         | `absent`; no legacy action required                                                                                                                                                                                                                                                                                           |
-| legacy `.env` containing generated keys only                             | `regenerate-only`; replace later from canonical roster data                                                                                                                                                                                                                                                                   |
-| legacy `.env` containing strict local keys                               | `relocate-local`; preserve those keys in `.env.local` during a later reviewed cutover                                                                                                                                                                                                                                         |
-| legacy `.env` containing forbidden/unsafe/sensitive/malformed keys       | `quarantine`; private input only, with diagnostics limited to code, key, and SHA-256                                                                                                                                                                                                                                          |
-
-The only automatic aliases are implementer → code, reviewer → review, and
-operator-interaction → interaction. Similar or domain-specific names are never inferred. Automatic
-classes do not accept competing disposition records. Semantic validation delegates to the existing
-baseline-plus-`roles.local` resolver after the candidate is compiled by the existing v2 compiler.
-
-## Evidence and recovery boundary
-
-Ready output includes source and candidate SHA-256 identities, value-free field inventory, excluded
-remote/connector entries, explicit environment dispositions with sanitized diagnostics, and the lifecycle
-evidence used for each local candidate. Canonical lifecycle and remote-exclusion evidence ordering compares
-Unicode code points directly and does not depend on source-agent order or process locale. Source field
-inventory remains position-addressed evidence of the exact input. Recovery is marked non-executable and
-assigns the executable gate to FCM-M4-002.
-
-Before any later cutover, preserve these artifacts:
-
-1. authoritative v1 roster backup;
-2. agent environment backup, including `.env.local` and private quarantine inputs;
-3. reviewed lifecycle observations;
-4. canonical candidate v2 roster and its SHA-256.
-
-See [backup and restore](../operations/backup-restore.md). Preview output is migration-readiness
-evidence, not proof that migration, canary, or rollback occurred.

docs/fleet/north-star.md

@@ -44,9 +44,9 @@ The Fleet inherits — does not re-invent — the MVP's hard requirements:
 | MVP req                       | What it means for the Fleet                                                                                             |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
 | MVP-X1 three-surface parity   | fleet observability/control reachable via **CLI + TUI + webUI** (CLI first; webUI is required for parity, not optional) |
-| MVP-X2 multi-tenant isolation | one tenant = one **Linux uid** (own systemd --user, socket, ~/.config/mosaic); no cross-tenant leakage                  |
+| MVP-X2 multi-tenant isolation | one tenant = one **Linux uid** (own `systemd --user`, socket, `~/.config/mosaic`); no cross-tenant leakage              |
 | MVP-X3 auth (BetterAuth/SSO)  | operator→fleet and cross-host views are auth-gated through the platform's existing auth                                 |
-| MVP-X4 quality gates          | pnpm typecheck/`lint`/`format:check` green before any push                                                              |
+| MVP-X4 quality gates          | `pnpm typecheck`/`lint`/`format:check` green before any push                                                            |
 | MVP-X5 federated topology     | cross-host fleet visibility rides the **federation** boundary (W1), not a bespoke broker                                |
 | MVP-X6 OTEL tracing           | heartbeats, sends, and lifecycle events emit spans; `traceparent` crosses the federation boundary                       |
 | MVP-X7 trunk merge            | branch from `main`, squash-merge via PR, never push to `main`                                                           |
@@ -55,20 +55,20 @@ The Fleet inherits — does not re-invent — the MVP's hard requirements:
 
 One **definition** is the source of truth; the **session** is how it runs.
 
-| Layer                            | Owner                                                                                   | Phase-2 reality                                        | Destination                                                                                                                         |
-| -------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| **Definition + identity + auth** | gateway / `mosaic-as` (scoped tokens, #541)                                             | `roster.yaml` (tenant-tagged)                          | one definition; mosaic agent --new materializes it                                                                                  |
-| **Tenancy boundary**             | **Linux uid per tenant** (linger, own systemd --user, own socket, own ~/.config/mosaic) | one tenant: `jarvis` = tenant zero                     | uid-per-tenant; federation aggregates across hosts                                                                                  |
-| **Runtime**                      | per-tenant tmux session on isolated socket                                              | dogfood stub sessions (live now on `mosaic-factory`)   | claude/codex/pi/opencode TUIs                                                                                                       |
-| **Liveness**                     | **heartbeat protocol** every runtime answers                                            | protocol defined + dogfood stub answers it             | all runtimes answer; "healthy" ≠ "pane alive"                                                                                       |
-| **Observation**                  | read-only `watch` (native tmux) + `pipe-pane` stream                                    | CLI `watch`/`ps`; explicit opt-in `attach` for control | + auth-gated webUI streams                                                                                                          |
-| **Control plane**                | **federation** across hosts × tenants                                                   | records already carry `tenant_id` + `host`             | federated gateways expose fleet state; webUI in Phase 5                                                                             |
-| **Central register**             | Postgres `fleet` schema (gateway instance); access via gateway API only                 | _none in PoC_ (files + `roster.yaml`)                  | agents, missions, tasks, heartbeats, spend — single network-accessible SSOT; docs = generated projections                           |
-| **Budget / spend governance**    | **per-tenant budget policy** ingested by the orchestrator + routing layer               | none today (spend is unmetered)                        | usage-vs-limit feedback ingested; spend auto-paced to the limit window; per-provider/per-account/concurrency/API-$ budgets enforced |
+| Layer                            | Owner                                                                                       | Phase-2 reality                                        | Destination                                                                                                                         |
+| -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Definition + identity + auth** | gateway / `mosaic-as` (scoped tokens, #541)                                                 | `roster.yaml` (tenant-tagged)                          | one definition; `mosaic agent --new` materializes it                                                                                |
+| **Tenancy boundary**             | **Linux uid per tenant** (linger, own `systemd --user`, own socket, own `~/.config/mosaic`) | one tenant: `jarvis` = tenant zero                     | uid-per-tenant; federation aggregates across hosts                                                                                  |
+| **Runtime**                      | per-tenant tmux session on isolated socket                                                  | dogfood stub sessions (live now on `mosaic-factory`)   | claude/codex/pi/opencode TUIs                                                                                                       |
+| **Liveness**                     | **heartbeat protocol** every runtime answers                                                | protocol defined + dogfood stub answers it             | all runtimes answer; "healthy" ≠ "pane alive"                                                                                       |
+| **Observation**                  | read-only `watch` (native tmux) + `pipe-pane` stream                                        | CLI `watch`/`ps`; explicit opt-in `attach` for control | + auth-gated webUI streams                                                                                                          |
+| **Control plane**                | **federation** across hosts × tenants                                                       | records already carry `tenant_id` + `host`             | federated gateways expose fleet state; webUI in Phase 5                                                                             |
+| **Central register**             | Postgres `fleet` schema (gateway instance); access via gateway API only                     | _none in PoC_ (files + `roster.yaml`)                  | agents, missions, tasks, heartbeats, spend — single network-accessible SSOT; docs = generated projections                           |
+| **Budget / spend governance**    | **per-tenant budget policy** ingested by the orchestrator + routing layer                   | none today (spend is unmetered)                        | usage-vs-limit feedback ingested; spend auto-paced to the limit window; per-provider/per-account/concurrency/API-$ budgets enforced |
 
 > **PoC socket hygiene:** the PoC fleet runs on the **default tmux socket** (no `-L`).
 > The named production-isolation socket is **`mosaic-fleet`** (matches the product brand);
-> an absent roster `socket_name` means the default socket everywhere (spawn, fleet ps,
+> an absent roster `socket_name` means the default socket everywhere (spawn, `fleet ps`,
 > onboarding cheat-sheet). The legacy dogfood canary still runs on the old `mosaic-factory`
 > socket pending migration.
 
@@ -177,22 +177,22 @@ routing flow**, **concurrency** (the spend multiplier), and **hard API-token $-l
 are enforced at the orchestrator + routing boundary, not inside individual workers (a worker never
 decides its own budget — see delegation discipline).
 
-**Budget CLI UX (#558):** mosaic budget set --reset-at sets the window reset; reset-datetimes
+**Budget CLI UX (#558):** `mosaic budget set --reset-at` sets the window reset; reset-datetimes
 carry **confidence tags** (`user` / `provider` / `estimated` / `unknown`); and **urgency/criticality
 is a dispatch-gate modifier** — high-urgency work may override even-spread pacing **within
 authorization**. (Also feeds the budgeting workstream, not only this doc.)
 
 ## Observation model
 
-| Verb                              | Behavior                                                                                           |
-| --------------------------------- | -------------------------------------------------------------------------------------------------- |
-| mosaic fleet ps                   | one table joining systemd + tmux + process + idle + last-heartbeat, with drift + boot-enable flags |
-| mosaic agent watch <name>         | **read-only** join (grouped session / `-r`), no resize tyranny, no keystrokes                      |
-| mosaic agent attach <name>        | explicit interactive takeover (the only path that can type)                                        |
-| mosaic agent send <name> --verify | confirms message **accepted**, not merely keystroke-injected                                       |
+| Verb                                | Behavior                                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `mosaic fleet ps`                   | one table joining systemd + tmux + process + idle + last-heartbeat, with drift + boot-enable flags |
+| `mosaic agent watch <name>`         | **read-only** join (grouped session / `-r`), no resize tyranny, no keystrokes                      |
+| `mosaic agent attach <name>`        | explicit interactive takeover (the only path that can type)                                        |
+| `mosaic agent send <name> --verify` | confirms message **accepted**, not merely keystroke-injected                                       |
 
 > Why the current PoC blocks observation: sessions live on the isolated `mosaic-factory`
-> socket (invisible to default tmux ls), the only sanctioned read is `capture-pane`
+> socket (invisible to default `tmux ls`), the only sanctioned read is `capture-pane`
 > (blank for full-screen TUIs), and `attach` is read-write + resizes the session. The
 > verbs above restore "join and observe" safely.
 
@@ -214,7 +214,7 @@ compromised pane cannot corrupt or exfiltrate the register.
 | Layer                  | Responsibility                                                                                                | Implementation                                                                                                                                                                                            |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Register**           | Source of truth: agents, missions, tasks, heartbeats, spend                                                   | Postgres `fleet` schema — existing stack instance (`@mosaicstack/db`)                                                                                                                                     |
-| **Access**             | Typed, auth-gated API                                                                                         | Gateway fleet/\* routes                                                                                                                                                                                   |
+| **Access**             | Typed, auth-gated API                                                                                         | Gateway `fleet/*` routes                                                                                                                                                                                  |
 | **Dispatcher**         | Brief classification, BOD review, planning/coding/review/test/deploy sequencing + gates → fleet task dispatch | **forge pipeline engine** (`runPipeline`/`resumePipeline`, brief classifier, BOD) **+ thin `forge-exec` adapter → `agent-send.sh`**; NOT a new daemon — forge is reused, only stage→agent dispatch is new |
 | **Orchestrator (Mos)** | Goals, missions, judgment, user/PA interface                                                                  | Context-light; sets intent → re-engages only for decisions                                                                                                                                                |
 
@@ -236,7 +236,7 @@ role implementation.
 
 `docs/TASKS.md` and `MISSION-MANIFEST.md` are **generated projections** of the DB,
 not hand-maintained. The dispatcher (or a scheduled job) renders Markdown from
-fleet.\* tables and commits the output. DB is authoritative; docs are for human
+`fleet.*` tables and commits the output. DB is authoritative; docs are for human
 reference.
 
 ### Spend
@@ -266,13 +266,13 @@ re-evaluate if isolation or write-volume demands it.
 
 ## Phased roadmap
 
-| Phase                  | Outcome                                                                                                                                                                                                | Status  |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
-| 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                                                                                 | ✅ done |
-| **2 — Observability**  | fleet ps (host+tenant aware join), heartbeat protocol + dogfood stub answers it, agent watch (read-only), agent send --verify receipts                                                                 | ▶ now   |
-| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)                                                              | planned |
-| 4 — Unified definition | one agent schema in gateway; mosaic agent --new → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
-| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**            | planned |
+| Phase                  | Outcome                                                                                                                                                                                                  | Status  |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                                                                                   | ✅ done |
+| **2 — Observability**  | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts                                                             | ▶ now   |
+| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)                                                                | planned |
+| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
+| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**              | planned |
 
 ## Decisions of record (2026-06-20, with Jason)
 
@@ -285,9 +285,9 @@ re-evaluate if isolation or write-volume demands it.
 - Delivery: **CLI-first now**, dogfood against the live stub fleet; webUI deferred to Phase 5.
 - Runtimes: fleet agents default to **Codex / pi-on-Codex**; **Claude is reserved for Claude
   Code only** (avoid alternate-harness API pricing). Validated durable recipe:
-  mosaic yolo pi --model openai-codex/gpt-5.5:high. Durable detached launch requires the
+  `mosaic yolo pi --model openai-codex/gpt-5.5:high`. Durable detached launch requires the
   runtime-bin on PATH (baked into the pane command) + boot-survival (`enable` + linger),
-  which fleet init should automate.
+  which `fleet init` should automate.
 
 ## Decisions of record (2026-06-22, with Jason)
 
@@ -304,18 +304,19 @@ re-evaluate if isolation or write-volume demands it.
 - **Session context cap = 200k tokens (GLOBAL to all Claude sessions):** Claude Code sessions are
   capped at a **max 200k-token context window**. Long-running sessions extended toward 1M tokens
   have proven **worse in practice** (degraded steering, off-plan divergence); 200k is the standard.
-  **Enforcement split:** the _window_ lives in **~/.claude/settings.json** (host-global) as
-  "autoCompactWindow": 200000 + "autoCompactEnabled": true; the _1M-disable_ lives in **launch
+  **Enforcement split:** the _window_ lives in **`~/.claude/settings.json`** (host-global) as
+  `"autoCompactWindow": 200000` + `"autoCompactEnabled": true`; the _1M-disable_ lives in **launch
   ENV** (`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, plus `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`) wherever
-  a [1m] model can be selected (`mos-claude.service` + the fleet Claude launcher), so every Claude
+  a `[1m]` model can be selected (`mos-claude.service` + the fleet Claude launcher), so every Claude
   agent is capped at spawn. (settings = window; env = 1M-disable.)
 - **Worker context bound (#8):** workers are kept context-bounded via the **ephemeral-per-lane
   lifecycle + native compaction**, not via the 200k knob. The explicit `autoCompactWindow` 200k knob
   **stays Claude-specific** — the _principle_ (bounded context) extends to workers, the _knob_ does not.
 - **Orchestrator delegation discipline:** the orchestrator **delegates all delivery work** to
-  subagents / workflows / ultracode / coder agents and confines its own context to the personal-assistant
-  lane. Keeping delivery out of the orchestrator's window keeps its context unpolluted and measurably
-  reduces off-plan divergence. The orchestrator coordinates and decides; it does not implement.
+  subagents / workflows / ultracode / coder agents and confines its own context to \*\*orchestration
+  - the personal-assistant lane\*\*. Keeping delivery out of the orchestrator's window keeps its
+    context unpolluted and measurably reduces off-plan divergence. The orchestrator coordinates and
+    decides; it does not implement.
 - **Budget governance is fleet doctrine:** token/API-dollar budgeting is a first-class fleet concern
   (see "Budget & token governance"). OAuth-sub usage-vs-limit feedback is ingested per account, spend
   is **auto-paced EVEN-SPREAD over remaining time** (rapid/overspend only on explicit authorization),
@@ -343,7 +344,7 @@ re-evaluate if isolation or write-volume demands it.
 ### Control plane & central register
 
 - **Store:** Postgres (existing stack instance, dedicated `fleet` schema via `@mosaicstack/db`). SQLite rejected: (1) it is a local file — structurally incompatible with a multi-host fleet; (2) concurrent multi-agent writes caused repeated corruption in Hermes. "SQLite + access service" rejected as reinventing a DB server badly; "LLM agent gating DB access" rejected as slow, expensive, and a single point of failure.
-- **Access:** gateway API only (`apps/gateway`, fleet/\* routes). No raw DB credentials in any agent/dispatcher pane — directly mitigates the tmux attack-surface concern.
+- **Access:** gateway API only (`apps/gateway`, `fleet/*` routes). No raw DB credentials in any agent/dispatcher pane — directly mitigates the tmux attack-surface concern.
 - **Dispatcher = forge (reuse, not a new build):** the dispatcher IS `@mosaicstack/forge`'s pipeline engine (`runPipeline`/`resumePipeline` + brief classifier + BOD persona loader), a fully-implemented software-factory pipeline (brief → BOD review → 3 planning stages → coding → review/remediation → testing → deploy). We do **not** design/build a new dispatcher and do **not** re-implement sequencing, gate logic, or brief classification. The only new fleet-owned piece is a thin **`forge-exec` TaskExecutor adapter** (suggested package `packages/forge-exec`) mapping a `ForgeTask` → `agent-send.sh` dispatch to a named fleet agent — forge's single missing piece. It is tracked as a Gitea issue and built **post-PoC** (not now).
 - **Register backs forge:** the Postgres `fleet` register is genuinely new (neither forge nor the fleet has cross-project state). It BACKS forge's pipeline state (durable `resumePipeline`, cross-host) plus cross-project missions/tasks/Kanban.
 - **'board' role = forge BOD:** the north-star role-library 'board' role IS forge's Board-of-Directors — reused, not reinvented.
@@ -356,9 +357,9 @@ re-evaluate if isolation or write-volume demands it.
 
 - **Per-agent model switch (operator-configurable, NOT a global lock):** model selection is
   **per-agent**, never a host-global pin. Claude sessions MUST NOT be locked to a single model in
-  ~/.claude/settings.json; each agent chooses its model independently. The plumbing already exists —
-  roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends --model <hint> to that
-  agent's harness (claude or pi); settable today via mosaic fleet add|edit <agent> --model <hint>.
+  `~/.claude/settings.json`; each agent chooses its model independently. The plumbing already exists —
+  roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends `--model <hint>` to that
+  agent's harness (claude or pi); settable today via `mosaic fleet add|edit <agent> --model <hint>`.
   **North-star target:** surface this as a **per-agent model switch in the webUI** (with CLI/TUI parity
   per MVP-X1) — read the roster, expose a per-agent model dropdown, write `model_hint` back, and restart
   that one agent to apply. Unset = inherit the harness default. This **composes with** the budget
@@ -384,7 +385,7 @@ re-evaluate if isolation or write-volume demands it.
   self-hosted homeserver (Conduit default, Synapse alt). Matrix is named here as the strategic
   future transport — peer to tmux/Discord, not superseded by them.
 - **tmux fleet attack-surface hardening.** Many always-on tmux sessions are an attack surface;
-  tmux send-keys / socket access could enable malicious action against agents directly.
+  `tmux send-keys` / socket access could enable malicious action against agents directly.
   Mitigations to build toward: socket ownership/perms, per-tenant socket isolation (already an
   invariant), authenticated `agent-send`, and an audit of who can write to any pane. **Post-MVP
   unless a P0 surfaces.** The control-plane register reinforces this (gateway-API access = no raw
@@ -417,9 +418,9 @@ re-evaluate if isolation or write-volume demands it.
 
 ---
 
-> **Release procedure (drift re-capture, 2026-06-22):** mosaic update only propagates new fleet
+> **Release procedure (drift re-capture, 2026-06-22):** `mosaic update` only propagates new fleet
 > commands when the **CLI version is bumped** — without a version bump, fleet command changes never
-> reach installed hosts. The release/version-bump procedure (bump → publish → mosaic update
+> reach installed hosts. The release/version-bump procedure (bump → publish → `mosaic update`
 > [→ `--relaunch`]) must be documented so fleet changes actually land. (Also feeds the budgeting
 > workstream.)
 >

docs/fleet/operations/backup-restore.md

@@ -1,40 +0,0 @@
-# Fleet Configuration Backup and Restore Boundary
-
-**Issue:** #758 · **Card:** FCM-M4-001
-
-This page defines evidence that must exist before a roster v1-to-v2 cutover. FCM-M4-001 lists these
-prerequisites in non-executable recovery evidence but does not validate that backups exist and performs
-no backup, migration, canary, or restore. FCM-M4-002 owns the executable reversible canary and rollback
-gates.
-
-## Preserve before cutover
-
-- The authoritative v1 roster, byte-for-byte, with a SHA-256 identity.
-- Existing per-agent legacy `.env`, strict `.env.local`, and quarantine files under private
-  permissions.
-- Reviewed per-local-agent systemd and exact-socket tmux observations.
-- The canonical v2 candidate and its SHA-256 identity.
-- Inventory-only remote agents and connector configuration as evidence, not local control-plane input.
-
-`.env.generated` is a rebuildable projection and is not restored as authority. It must be regenerated
-from the selected authoritative roster. `.env.local` is operator-owned strict data and must not be
-overwritten or absorbed into generated output. Quarantined source remains private evidence; public
-diagnostics expose only rule code, key name, and SHA-256.
-
-## Restore requirements
-
-A later rollback implementation must restore the authoritative roster and operator-owned environment
-files, regenerate managed projections, and preserve each reviewed pre-cutover stopped/running state.
-It must never start an agent observed stopped and must never reconcile an inventory-only remote or
-connector entry.
-
-The preview evidence deliberately records:
-
-- executable: false;
-- required backup artifacts;
-- source and candidate identities;
-- lifecycle observations and resulting desired states;
-- environment relocation/quarantine dispositions;
-- FCM-M4-002 as the executable rollback gate owner.
-
-Do not interpret a ready preview as a completed backup, migration, canary, or rollback.

docs/fleet/operations/env-quarantine.md

@@ -1,20 +0,0 @@
-# Environment Quarantine Operations
-
-Legacy <name>.env is input evidence, never current launch authority. Projection preparation classifies it deterministically:
-
-- generated roster keys → discard and regenerate;
-- allowed strict local keys → relocate to private `.env.local`;
-- malformed, duplicate, unknown, sensitive-looking, shell-bearing, unsafe, or command-override entries → move the legacy input to private `.env.quarantine`.
-
-## Safe response
-
-1. Stop and read the stable error code and reported key name/hash. Do not request or paste the value.
-2. Confirm the canonical roster contains the intended non-sensitive desired state.
-3. If the key is an allowed local machine-data field, place only its validated data form in `.env.local` under private permissions.
-4. Remove unsupported intent rather than translating it into commands, channels, secret references, or unknown MOSAIC*AGENT*\* keys.
-5. Regenerate `.env.generated` from the roster and rerun a dry-run/verification gate.
-6. Retain quarantine evidence privately until the operator's normal retention process permits removal.
-
-The launcher never reads quarantine. Public/JSON diagnostics expose stable code, key name where safe, and SHA-256 only—never a legacy sensitive value, credential, rejected command, or full line. Quarantine does not prove remediation, backup, migration, or rollback.
-
-See [generated launch chain](../concepts/generated-env-launch-chain.md), [generated environment boundary](../reference/generated-env-boundary.md), and [migration field disposition](../migration/v1-to-v2.md#field-disposition).

docs/fleet/operations/reconcile-and-recover.md

@@ -1,28 +0,0 @@
-# Reconcile and Recover a Local Fleet
-
-## Safe sequence
-
-1. Read mosaic fleet doctor and mosaic fleet status.
-2. Run mosaic fleet apply --expected-generation <n> --dry-run.
-3. Resolve stale generation, ownership mismatch, unsafe path, projection validation, or unmanaged-session findings before applying.
-4. Run mosaic fleet apply --expected-generation <n> only after the plan is understood.
-
-This is per-generation convergence, not a rolling canary. Executable canary cutover/rollback remains held for FCM-M4-002; rolling local release evidence remains FCM-M5-002. Do not approximate either with repeated live apply commands.
-
-The reconciler uses the exact roster tmux socket, exact holder session, private installation holder identity, and the complete expected global environment. For mutations it acquires its exclusive lock before rereading the canonical roster and fencing its generation; only that under-lock roster drives validation, planning, projections, and lifecycle effects. Before effects, its exclusive lock proves real private `MOSAIC_HOME` and `fleet` ancestors, uses a private `0600` lock leaf, and binds cleanup to the created file identity and ownership token. A fake holder, contaminated global environment, missing identity, unsafe lock path, or unmanaged session fails closed. It does not adopt, kill, or rename any unproven session. A crash can leave a stale lock for explicit operator inspection; reconciliation deliberately does not guess ownership or remove it.
-
-## Partial results
-
-The roster is never changed by reconciliation. If derived projection application partially fails, JSON reports:
-
-```json
-{
-  "applied": false,
-  "authoritativeRoster": "unchanged",
-  "projections": "incomplete",
-  "lifecycle": "not-applied",
-  "recovery": { "code": "projection-apply-failed", "action": "regenerate-projections-from-roster" }
-}
-```
-
-If projections completed but lifecycle work failed, JSON reports projections: "complete", lifecycle: "incomplete", and the bounded action `rerun-after-inspecting-owned-resources`. If lock cleanup cannot be proven after an effect result, it adds cleanup: { "code": "lock-cleanup-failed", "action": "inspect-lock-before-retry" } without changing the known projection, lifecycle, or primary recovery truth. Inspect the retained lock before retrying; no rollback, release, or stale-lock removal is implied. Results do not include environment values, secrets, or privileged command content.

docs/fleet/operations/systemd-tmux-troubleshooting.md

@@ -1,24 +0,0 @@
-# Systemd and tmux Troubleshooting
-
-Start with read-only mosaic fleet status, `doctor`, and `verify`. Do not manually adopt, rename, terminate, or recreate sessions while ownership is ambiguous.
-
-## Decision table
-
-| Finding                         | Meaning                                              | Safe next step                                                                        |
-| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| Empty roster `tmux.socket_name` | Literal default tmux server                          | Do not substitute the named `mosaic-fleet` socket. Use roster-derived commands only.  |
-| Non-empty socket                | Exact named socket                                   | Never target another socket or infer a per-agent socket.                              |
-| holder: missing                 | Required exact holder absent                         | Inspect installation/projection readiness; do not create an unproven holder manually. |
-| `ownership-mismatch`            | Holder identity or global environment differs        | Stop. Verify private install identity and managed paths before retry.                 |
-| `missing-session`               | Desired-running roster agent lacks exact session     | Check service/runtime preconditions; review apply dry-run.                            |
-| `unexpected-session`            | Desired-stopped roster agent still has exact session | Confirm ownership; only reconciler may target the exact proven roster member.         |
-| `disabled-running`              | Disabled roster member is observed running           | Inspect and reconcile only after ownership proof.                                     |
-| `unmanagedSessions`             | Unknown session exists on configured named socket    | Report and investigate separately. Reconciler will not kill or adopt it.              |
-| stale/concurrent generation     | Desired state changed since plan                     | Reload roster/generation and recompute the plan.                                      |
-| stale or ambiguous lock         | Prior writer/cleanup cannot be proven                | Inspect ownership; do not blindly remove the lock.                                    |
-| projection failure              | Derived files incomplete                             | Keep roster as authority and regenerate projections.                                  |
-| lifecycle failure               | Projections complete, runtime convergence incomplete | Inspect the exact owned resource, then rerun with current generation.                 |
-
-Systemd state, tmux state, heartbeat, and generated files are observations/projections, not alternate desired state. Explicit apply/reconcile honors stopped/disabled intent, but current unit enablement and launcher projections do not yet prove lifecycle-safe reboot; inspect unit enablement before reboot and treat stopped/disabled boot preservation as an FCM-M3-002 hold. Current roster-v2 status commands also do not read heartbeat files. Executable gates do not provide site cutover/rollback or package asset-revision repair.
-
-Errors and troubleshooting output never print legacy sensitive values, credential contents, or privileged command text. Use stable codes, key names/hashes, exact roster identities, and bounded recovery actions. See [status and drift](../reference/status-and-drift.md) and [reconcile and recover](reconcile-and-recover.md).

docs/fleet/operations/upgrade-assets.md

@@ -1,18 +0,0 @@
-# Upgrade and Installed-Asset Drift
-
-Fleet source assets and installed assets can differ after an update, but FCM-M5-001 does not add a trustworthy source-versus-installed revision detector or refresh command. Do not infer freshness from checkout presence, timestamps, generated environment files, running sessions, or a ready migration preview.
-
-## Current safe boundary
-
-- The canonical roster remains authority and must survive package/framework refresh.
-- Generated projections are rebuilt from that roster after the installed contract is independently verified.
-- Operator `roles.local`, `.env.local`, and private quarantine evidence are not generated assets and must not be overwritten.
-- Baseline roles, schemas, examples, service presets, launcher helpers, and systemd templates must move as one reviewed release set.
-- Remote/connector inventory and `mos-comms` are not promoted into permanent architecture by an update.
-- No update may start an agent persisted stopped, adopt an unmanaged session, or bypass generation/ownership checks.
-
-## Explicit hold
-
-FCM-M5-002 owns deterministic asset-drift checks, safe package/update refresh evidence, rolling local canary, independent validation certificate, and release evidence. Until that card lands, this page is an operational hold rather than an executable procedure: use the repository/release review path, preserve backups, and do not claim source/installed parity without exact revision evidence from the future validator.
-
-See [approved deferrals](../../reports/deferred/758-fleet-config-deferrals.md) and [backup/restore boundary](backup-restore.md).

docs/fleet/reference/agent-mutations.md

@@ -1,43 +0,0 @@
-# Local Fleet Agent Mutations
-
-FCM-M2-002 provides local roster-v2 create, get, update, delete, and plan operations. They only change desired state and derived environment projections. They never start, stop, inspect, reconcile, or otherwise act on runtimes, systemd units, tmux sessions, or heartbeats.
-
-## CLI contract
-
-The commands operate only on the canonical <mosaic-home>/fleet/roster.yaml v2 authority and print one JSON object to stdout. `--agent` is a JSON object with the roster agent fields expressed as `className`, `toolPolicy`, `workingDirectory`, `persistentPersona`, `resetBetweenTasks`, and launch: { "yolo": boolean }.
-
-```fleet-synopsis
-mosaic fleet get <name>
-mosaic fleet plan <create|update|delete> [<name>] --expected-generation <n> [--agent '<json>'] [--persisted-start]
-mosaic fleet create --expected-generation <n> --agent '<json>' [--dry-run] [--persisted-start]
-mosaic fleet update <name> --expected-generation <n> --agent '<json>' [--dry-run]
-mosaic fleet delete <name> --expected-generation <n> [--dry-run]
-```
-
-`get` returns the authoritative generation and the selected agent. plan create derives its name from `--agent`; plan update <name> and plan delete <name> require the target name. `--agent` accepts only the documented roster-v2 request fields and `launch.yolo`; unknown keys such as commands, channels, or secret references are rejected. Rejection diagnostics return only the stable `invalid-request` code and never echo a rejected value. `plan` and `--dry-run` validate the complete proposed roster and projections but write neither the roster nor projections. `--persisted-start` is available only for a create request: it records desired_state: running, but does not start a process. Without it, create records enabled: true and desired_state: stopped. Handled failures return JSON with `error.code` and exit non-zero; unclassified validation/projection failures use the redacted `mutation-failed` code.
-
-## Generation, validation, and idempotency
-
-Each create, update, or delete request includes `expectedGeneration`. A request whose expected value differs from the authoritative roster generation fails with `stale-generation`; reload and retry with a newly computed plan. A private mutation lock rejects concurrent writers with `concurrent-mutation`.
-
-`planFleetAgentMutation` is deterministic and side-effect free. `executeFleetAgentMutation` validates the complete proposed roster through the existing structural and shared persona resolver, prepares generated/local/quarantine projections, and writes the roster authority atomically before applying derived projections. Equivalent create retries and delete requests for an already-absent agent are idempotent no-ops.
-
-Delete removes only the exact <name>.env.generated projection for the removed roster entry. Operator-owned <name>.env.local, legacy <name>.env, quarantine records, and unrelated projections remain untouched. An already-absent generated projection is treated as stale derived state, not as a failed mutation.
-
-## Result and recovery
-
-Mutation results are JSON-safe objects with `applied`, `authoritativeRoster`, `projections`, `plan`, and—only if a derived projection write fails after the authoritative roster write—a recovery object. `applied` is true only when every roster and derived-projection write completed. The explicit state fields prevent a partial result from being mistaken for a rollback or a no-op:
-
-```json
-{
-  "applied": false,
-  "authoritativeRoster": "committed",
-  "projections": "incomplete",
-  "recovery": {
-    "code": "projection-apply-failed",
-    "action": "regenerate-projections-from-roster"
-  }
-}
-```
-
-Dry-runs and idempotent no-ops report authoritativeRoster: "unchanged" and projections: "not-applied"; a complete mutation reports "committed" and "complete". Recovery output identifies the authoritative roster path and regeneration action only. It never contains generated/local/quarantine values, credentials, or command text. A recovery result exits non-zero because the authoritative roster was persisted but derived projections require regeneration. Regenerate projections from the roster before attempting another mutation.

docs/fleet/reference/cli.md

@@ -1,46 +0,0 @@
-# Fleet Control-Plane CLI
-
-The local desired-state surface is mosaic fleet. It is distinct from the gateway-backed mosaic agent catalog and from legacy compatibility commands that act on roster v1.
-
-## Roster-v2 desired-state commands
-
-| Command                                                    | Effect                                         | Generation | Output                     |
-| ---------------------------------------------------------- | ---------------------------------------------- | ---------- | -------------------------- |
-| mosaic fleet get <name>                                    | Read one authoritative agent                   | no         | One JSON object            |
-| mosaic fleet plan <create\|update\|delete> ...             | Validate proposed CRUD and projections         | required   | One JSON object; no writes |
-| mosaic fleet create ... [--dry-run] [--persisted-start]    | Add desired state; default enabled/stopped     | required   | One JSON object            |
-| mosaic fleet update <name> ... [--dry-run]                 | Replace mutable agent fields                   | required   | One JSON object            |
-| mosaic fleet delete <name> ... [--dry-run]                 | Remove roster member/generated projection      | required   | One JSON object            |
-| mosaic fleet apply ... [--dry-run]                         | Plan or converge projections/lifecycle         | required   | One JSON object            |
-| mosaic fleet reconcile ... [--dry-run]                     | Alias of the same convergence contract         | required   | One JSON object            |
-| mosaic fleet start\|stop\|restart [<name>] ... [--dry-run] | Exact one-shot lifecycle action                | required   | One JSON object            |
-| mosaic fleet status [<name>]                               | Observe desired/managed/runtime state          | no         | One JSON object            |
-| mosaic fleet verify                                        | Strict observational drift/ownership gate      | no         | One JSON object            |
-| mosaic fleet doctor                                        | Classify local drift and recovery context      | no         | One JSON object            |
-| mosaic fleet migrate-v1 preview ...                        | Non-mutating field-complete migration evidence | no         | One JSON object            |
-
-CRUD syntax and full payload shape are documented in [agent mutations](agent-mutations.md). Reconciliation syntax:
-
-```fleet-synopsis
-mosaic fleet apply --expected-generation <n>
-mosaic fleet reconcile --expected-generation <n>
-mosaic fleet start [<name>] --expected-generation <n> [--dry-run]
-mosaic fleet stop [<name>] --expected-generation <n> [--dry-run]
-mosaic fleet restart [<name>] --expected-generation <n> [--dry-run]
-mosaic fleet status [<name>]
-mosaic fleet verify
-mosaic fleet doctor
-mosaic fleet migrate-v1 preview --source <path> --decisions <path> --observations <path>
-```
-
-`get` is the read/show operation for one v2 agent. Full roster parsing and semantic validation occur on every v2 mutation/reconcile path; there is no separate mutable “config store.” The executable JSON Schema and validated example provide offline structural evidence. The PRD requires an explicit programmatic mosaic fleet validate operation, but the current CLI does not expose one; do not substitute another command or claim that requirement is delivered. This remains an implementation gap for #758.
-
-## JSON and exit behavior
-
-Roster-v2 CRUD and reconciler precondition failures emit { "error": { "code": "..." } } and exit non-zero. Migration preview has its own result envelope: a non-ready preview emits { "status": "blocked", "blockers": [...] } and exits non-zero rather than using the CRUD/reconciler error object. Use both exit status and command-specific state fields. A partial reconciliation result distinguishes `authoritativeRoster`, `projections`, `lifecycle`, `recovery`, and optional `cleanup`; it never claims automatic rollback. `verify` exits non-zero for drift, ownership failure, or unmanaged sessions. Sensitive legacy values, credentials, and rejected command text are never printed.
-
-## Compatibility and scope
-
-Roster-v1 initialization, provisioning, profiles/personas, and historical fleet add/remove remain compatibility surfaces, not roster-v2 CRUD aliases. New v2 automation should use the table above. migrate-v1 preview writes nothing and has no cutover, canary, or rollback option.
-
-mosaic agent is a separate catalog/transport surface; it does not own <MOSAIC_HOME>/fleet/roster.yaml desired state. Remote/SSH reconciliation, connector mutation, arbitrary commands/channels, secret references, and gateway convergence are rejected or outside scope.

docs/fleet/reference/generated-env-boundary.md

@@ -1,96 +0,0 @@
-# Fleet Generated Environment Boundary
-
-**Card:** FCM-M2-001 · **Issue:** #758 · **Status:** merged contract
-
-The local fleet roster is the desired-state authority. A launch reads a deterministic,
-roster-derived generated projection and an optional strictly data-only local file; neither file is
-a second roster or a command configuration surface.
-
-## Paths and ownership
-
-For agent <name> under <MOSAIC_HOME>/fleet/agents/:
-
-| Path                  | Owner                    | Purpose                                                                                                                      |
-| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| <name>.env.generated  | Mosaic projection writer | Complete deterministic launch data rendered from the authoritative roster.                                                   |
-| <name>.env.local      | Operator                 | Optional, constrained local machine data. It cannot shadow generated keys.                                                   |
-| <name>.env            | Legacy input only        | Read once during projection generation, then regenerated/relocated or privately quarantined. It is never a launch authority. |
-| <name>.env.quarantine | Mosaic quarantine        | Mode-`0600` private record of forbidden legacy input; it is never read by the launcher.                                      |
-
-The systemd templates do not load either environment file. They invoke Bash with a fixed, cleared
-bootstrap environment; the launcher reads and validates `.env.generated` and `.env.local` itself before
-it queries, creates, or stops an exact tmux session. It does not `source`, `eval`, or execute an
-environment-supplied command. Exact stop derives its socket from the same validated generated projection,
-not from systemd or ambient environment data.
-
-All projection, local, and quarantine files must be regular files with no group or world permissions.
-The agent environment directory must also be a real, non-symlink private directory; it is validated
-before either environment file is read or tmux is queried. Unsafe paths, symlinks, or permissions fail
-closed. Diagnostics identify only a rule code, key name, and SHA-256 content hash; they never print
-values, credential material, or command text.
-
-## Allowed data
-
-`.env.generated` is complete and ordered exactly as follows:
-
-```dotenv
-MOSAIC_AGENT_NAME=<roster name>
-MOSAIC_AGENT_CLASS=<roster class>
-MOSAIC_AGENT_RUNTIME=<roster runtime>
-MOSAIC_AGENT_MODEL=<roster model hint>
-MOSAIC_AGENT_REASONING=<roster reasoning>
-MOSAIC_AGENT_TOOL_POLICY=<roster tool policy>
-MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
-MOSAIC_TMUX_SOCKET=<roster socket or empty>
-```
-
-The generated launch contract supports only `claude`, `codex`, `opencode`, and `pi`. fleet add
-uses that same runtime authority and rejects any other runtime before it writes the roster or changes
-projection, local, or quarantine files. The legacy dogfood stub on its separate `mosaic-factory`
-socket remains an observability canary; it has no generated-launch adapter and cannot be added through
-this projection path.
-
-`.env.local` may contain only these non-secret data keys:
-
-- `MOSAIC_RUNTIME_BIN`
-- `MOSAIC_HEARTBEAT_RUN_DIR`
-- `MOSAIC_HEARTBEAT_INTERVAL`
-- `MOSAIC_CLAUDE_JSON`
-- `CLAUDE_CONFIG_DIR`
-
-Local paths must be safe absolute paths and the interval must be a positive integer. Comments,
-quoted/export syntax, duplicate keys, unknown keys, generated-key shadowing, sensitive key names,
-and `MOSAIC_AGENT_COMMAND` are rejected. The launcher derives the only executable command from the
-validated runtime, model, and reasoning data; no arbitrary command compatibility path exists. When a
-Pi runtime writes a fresh <name>.hb.native marker, its native heartbeat remains authoritative; the
-shell sidecar resumes its `status=ok` fallback only after that marker is stale or absent.
-
-## Legacy disposition
-
-During projection generation, legacy roster-derived keys are regenerated from the roster. A valid
-allowed local value is relocated to `.env.local`; forbidden, malformed, duplicate, sensitive, and
-unknown legacy entries cause the legacy file to be moved to `.env.quarantine` and are represented by
-sanitized diagnostics. This is deterministic and idempotent after the legacy file has been consumed.
-
-## USC interface packet
-
-This card does not add a USC site file, write a USC roster, or run a site canary. The following is the
-consolidated downstream interface packet. Status is deliberately separated from checkout presence: no
-product release version has been evidenced for this interface set.
-
-| Interface               | Canonical public path and version                                                                                                               | Tracker/release status                                                                                    | Downstream limit                                                                              |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| M1 structural compiler  | `parseRosterV2` in `packages/mosaic/src/fleet/roster-v2.ts`; schema `docs/fleet/reference/roster-v2.schema.json`; roster version: 2             | FCM-M1-001 is recorded done, merged as #764 (`aa5b43b`); no released product version is asserted here.    | Parse YAML/JSON and canonicalize a supplied v2 site roster without writes.                    |
-| M1 semantic resolver    | `validateRosterV2Semantics` in `packages/mosaic/src/fleet/roster-v2.ts`; baseline `framework/fleet/roles/` plus `roles.local/`                  | FCM-M1-002 merged as #768 (`a5e8e55`); no released product version is asserted here.                      | Reuse the shared resolver only; no parallel role resolver or lifecycle action.                |
-| M1 disposition evidence | `packages/mosaic/src/fleet/example-profile-dispositions.ts`; `docs/fleet/migration/example-profile-disposition.md`; retained fixture version: 1 | FCM-M1-003 merged as #770 (`e9c4aa3`); checkout evidence remains validation, not migration authorization. | Inspect fixture/profile/service disposition evidence only; it is not migration authorization. |
-| M2 generated boundary   | `packages/mosaic/src/fleet/generated-env-boundary.ts`; generated projection contract in this document                                           | FCM-M2-001 merged as #772 (`191efae`); no released product version is asserted here.                      | Render/write a roster-derived projection; local input is never authority.                     |
-
-The canonical source remains <MOSAIC_HOME>/fleet/roster.yaml for the current local fleet path.
-Generated environment data is a rebuildable projection, not an operator-editable source of membership,
-runtime policy, or lifecycle state.
-
-**Corrected downstream gates:** M2 supplies only parse/validation/projection evidence and does not
-permit a USC site canary, reconciliation, or lifecycle mutation. M3 must first define and validate the
-canonical local reconcile/lifecycle path. M4 then supplies preview/migration and its separate
-canary/rollback gates; only after those M3 and M4 gates may a site migration or canary be considered.
-This card authorizes none of those actions.

docs/fleet/reference/lifecycle-transitions.md

@@ -1,21 +0,0 @@
-# Local Fleet Lifecycle Transitions
-
-Roster-v2 `lifecycle.enabled` and `lifecycle.desired_state` are the only persisted lifecycle authority. Systemd, tmux, generated environment, and heartbeat state are derived or observed.
-
-| Event                     | Desired-state write                                                        | Runtime effect                                                                              | Safety boundary                                                                                                                                             |
-| ------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fleet create              | Adds enabled/stopped by default; `--persisted-start` records running       | None                                                                                        | Generation-guarded; validates full roster/projections.                                                                                                      |
-| fleet update              | Preserves the existing enabled/desired state; updates other mutable fields | None                                                                                        | Generation-guarded; stable name and lifecycle are immutable on this path.                                                                                   |
-| fleet delete              | Removes exact roster member                                                | None                                                                                        | Removes only generated projection; retains local/quarantine evidence.                                                                                       |
-| fleet apply / `reconcile` | Never                                                                      | Rebuilds projections; starts only enabled/running; stops disabled or stopped roster members | Current generation, private lock/paths, semantic validity, holder ownership, no unmanaged named-socket sessions.                                            |
-| fleet start <name>        | Never                                                                      | One-shot exact service start                                                                | Exact enabled roster name and proven ownership.                                                                                                             |
-| fleet stop <name>         | Never                                                                      | One-shot exact service stop                                                                 | Exact roster name and proven ownership.                                                                                                                     |
-| fleet restart <name>      | Never                                                                      | One-shot exact service restart                                                              | Exact enabled roster name and proven ownership.                                                                                                             |
-| Reboot/service activation | Never                                                                      | Current installation may activate enabled units without honoring roster lifecycle           | **Held for FCM-M3-002:** boot preservation for stopped/disabled agents is not yet proven; inspect/disable units rather than assuming lifecycle-safe reboot. |
-| v1 migration preview      | Never                                                                      | None                                                                                        | Observed active+present maps running; inactive+missing maps stopped; ambiguity blocks.                                                                      |
-| Cutover/canary            | Held for FCM-M4-002                                                        | Not implemented by preview                                                                  | Must preserve every observed stopped state.                                                                                                                 |
-| Rollback                  | Held for FCM-M4-002                                                        | Not implemented                                                                             | Must restore selected authority/projections without surprise starts or unmanaged targeting.                                                                 |
-
-Explicit apply/reconcile never starts a stopped roster agent. Direct lifecycle commands are explicit one-shot actions and do not persist intent. The current update operation preserves `existing.lifecycle`; there is no delivered generation-guarded CRUD operation for changing durable lifecycle after creation. Reboot preservation for stopped/disabled agents is not yet guaranteed because current enabled units and launcher projections do not carry the persisted lifecycle fence; that acceptance evidence remains FCM-M3-002.
-
-Missing/stale generation, concurrent writer, unsafe path, ownership mismatch, unmanaged session, unsupported runtime, invalid projection, and lifecycle precondition failures return stable redacted JSON and non-zero status. No command targets fuzzy names, arbitrary sockets/commands/channels/secrets, or generated files as authority. Legacy sensitive values are never printed.

docs/fleet/reference/role-classes.md

@@ -16,7 +16,7 @@ Only these legacy class aliases are recognized:
 
 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.
+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

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

@@ -50,38 +50,36 @@ agents:
 
 ## Root fields
 
-| Field        | Required | Default | Constraint            | Meaning                                                                                           |
-| ------------ | -------- | ------- | --------------------- | ------------------------------------------------------------------------------------------------- |
-| `version`    | yes      | none    | integer constant `2`  | Identifies this contract. Version `1` stays on the compatibility path pending explicit migration. |
-| `generation` | yes      | none    | positive safe integer | Desired-state generation and mutation/reconcile concurrency fence.                                |
-| `transport`  | yes      | none    | constant `tmux`       | M1–M5 support local tmux only.                                                                    |
-| `tmux`       | yes      | none    | strict object         | Explicit local socket and holder-session configuration.                                           |
-| `defaults`   | yes      | none    | strict object         | Default work directory and one supported local runtime.                                           |
-| `runtimes`   | yes      | none    | non-empty object      | Declared local runtime reset policy map.                                                          |
-| `agents`     | yes      | none    | non-empty array       | Local fleet entries. Duplicate stable names are rejected.                                         |
+| 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
 
-All nested fields in the v2 schema are required and have no implicit default. CRUD `create` is the only higher-level convenience: it records lifecycle.enabled: true and desired_state: stopped unless `--persisted-start` explicitly records running. That convenience still performs no runtime action.
-
-| Path                                               | Required | Constraint                                                                                                   |
-| -------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
-| `tmux.socket_name`                                 | yes      | [A-Za-z0-9_.-]\*; empty string means the literal default tmux server, while a non-empty value names a socket |
-| `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                                         |
+| 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
 
@@ -99,12 +97,12 @@ Semantic validation:
   `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
+  `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.
+`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).
@@ -114,7 +112,7 @@ lifecycle mutation.
 
 ## Fail-closed boundary
 
-Every object is additionalProperties: false. The compiler rejects unknown, missing, malformed,
+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

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

@@ -24,7 +24,7 @@
       "properties": {
         "socket_name": {
           "type": "string",
-          "pattern": "^[A-Za-z0-9_.-]*$"
+          "pattern": "^[A-Za-z0-9_.-]+$"
         },
         "holder_session": {
           "type": "string",

docs/fleet/reference/status-and-drift.md

@@ -1,25 +0,0 @@
-# Local Fleet Status and Drift
-
-mosaic fleet status [<name>], `verify`, and `doctor` are observational roster-v2 commands. They emit one JSON result and do not write projections, mutate desired state, operate lifecycle, or change tmux.
-
-## State dimensions
-
-- **Desired:** roster membership, generation, enabled flag, and persisted running/stopped target.
-- **Managed/derived:** generated environment and expected exact service/session topology.
-- **Observed by current roster-v2 commands:** systemd active state, tmux presence, exact holder ownership, and unmanaged sessions.
-
-Implemented drift classifications include:
-
-- `missing-session`: enabled/desired-running agent lacks its exact session;
-- `unexpected-session`: desired-stopped agent has its exact session;
-- `disabled-running`: disabled roster agent has its exact session;
-- `unmanagedSessions`: named-socket sessions that are neither exact holder nor roster agent;
-- `holder`: `owned`, `missing`, or `ownership-mismatch` after private identity and global environment checks.
-
-Generated projection failures/staleness are surfaced by plan/apply preparation and bounded recovery fields rather than adopted as configuration. Heartbeat remains wider-fleet observational evidence, never desired state, but the current roster-v2 `status`, `doctor`, and `verify` commands do not read heartbeat files. A provable removed-agent projection may be treated as stale derived state during deletion, but general projection-orphan classification and installed source-versus-asset revision mismatch remain FCM-M4-002/M5-002 holds; current commands must not claim those future checks.
-
-## Command behavior
-
-`status` and `doctor` classify rather than adopt, destroy, or repair. `verify` is observational too, but exits non-zero if ownership cannot be proven, unmanaged sessions exist, or drift is present. Reconciliation fails closed under those conditions and never kills or adopts an unmanaged session.
-
-Doctor/error output uses stable codes and bounded recovery context. Migration, quarantine, lifecycle, status, and troubleshooting output never prints a legacy sensitive value, credential, or privileged command text.

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`       | Runtime-only PostgreSQL connection injected from the dedicated deployment secret; no default or inline DSN. |
+| 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` |
 
 ### Gateway
 

docs/guides/deployment.md

@@ -1,67 +1,384 @@
 # Deployment Guide
 
-> **Status: non-operative for PostgreSQL, federated, and bare-metal production.** The checked-in
-> Compose PostgreSQL service mounts legacy initialization SQL and the KBN-101 bootstrap, runner,
-> secret-renderer, and process-exec interfaces do not exist yet. This page does not authorize a
-> production deployment, database initialization, manual DDL, secret provisioning, or service
-> activation.
+This guide covers deploying Mosaic in two modes: **Docker Compose** (recommended for quick setup) and **bare-metal** (production, full control).
 
-## Current safe local route
+---
 
-Use PGlite only for current in-process data-layer work; it requires no PostgreSQL. A Gateway/Web
-local process is held because its unguarded dotenv loader can inherit a daemon PostgreSQL DSN and
-reach runtime DDL. If a local queue service is useful, start only Valkey:
+## Prerequisites
+
+| Dependency       | Minimum version | Notes                                          |
+| ---------------- | --------------- | ---------------------------------------------- |
+| Node.js          | 22 LTS          | Required for ESM + `--experimental-vm-modules` |
+| pnpm             | 9               | `npm install -g pnpm`                          |
+| PostgreSQL       | 17              | Must have the `pgvector` extension             |
+| Valkey           | 8               | Redis-compatible; Redis 7+ also works          |
+| Docker + Compose | v2              | For the Docker Compose path only               |
+
+---
+
+## Docker Compose Deployment (Quick Start)
+
+The `docker-compose.yml` at the repository root starts PostgreSQL 17 (with pgvector), Valkey 8, an OpenTelemetry Collector, and Jaeger.
+
+### 1. Clone and configure
 
 ```bash
-docker compose up -d valkey
+git clone <repo-url> mosaic
+cd mosaic
+cp .env.example .env
 ```
 
-This command intentionally does not start PostgreSQL. Do not run a broad Compose start, use its
-PostgreSQL initialization mount, infer that current Compose is a production/federated route, or
-start Gateway/Web until KBN-101-02 supplies fail-closed local-tier/DSN isolation.
+Edit `.env`. The minimum required change is:
 
-## Held future procedure
+```dotenv
+BETTER_AUTH_SECRET=<output of: openssl rand -base64 32>
+```
 
-PostgreSQL local, federated, Compose, and bare-metal production activation are held until these
-artifacts land and pass their independent gates:
+### 2. Start infrastructure services
 
-1. **KBN-101-00** external privileged bootstrap artifact;
-2. **KBN-101-03** sole `mosaic-db-migrator` runner and verified-readiness artifact; and
-3. **KBN-101-05** Vault/secret-renderer-backed deployment and consumer-isolation artifact.
+```bash
+docker compose up -d
+```
 
-The required future order is external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness.
+Services and their ports:
 
-This is a held, non-operative future activation specification with no current command authority. Do not invoke the named
-runner, start PostgreSQL, or substitute a Compose/init/manual-SQL route until the owned artifacts
-are implemented and reviewed.
+| Service               | Default port             |
+| --------------------- | ------------------------ |
+| PostgreSQL            | `localhost:5433`         |
+| Valkey                | `localhost:6380`         |
+| OTEL Collector (HTTP) | `localhost:4318`         |
+| OTEL Collector (gRPC) | `localhost:4317`         |
+| Jaeger UI             | `http://localhost:16686` |
 
-## Future production secret and unit boundary (schematic only)
+Override host ports via `PG_HOST_PORT` and `VALKEY_HOST_PORT` in `.env` if the defaults conflict.
 
-No current bare-metal production unit or command is published. KBN-101-05 must supply a reviewed,
-generation-pinned Vault renderer and a process-exec or systemd `LoadCredential` interface before
-production units can exist. The interface must preserve these exact consumer boundaries:
+### 3. Install dependencies
 
-| Consumer          | May receive                                                                                  | Must never receive                                                                            |
-| ----------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Gateway/runtime   | Its own runtime URL and DB client CA at process exec                                         | Migrator URL, importer URL/version, attestation material, signing key, PostgreSQL private key |
-| One-shot migrator | Its own migration URL, DB client CA, and runner-only signing capability                      | Runtime URL, importer consumer copy, Gateway/private PostgreSQL keys                          |
-| Data importer     | Its own immutable URL/version copies, importer CA, pinned public key, and sealed attestation | Runtime/migrator URLs, signing key, shared writable mount                                     |
-| PostgreSQL        | Its own server certificate/key and only its approved server material                         | Application, migrator, importer, or Gateway secrets                                           |
+```bash
+pnpm install
+```
 
-A future unit specification is non-executable until KBN-101-05 supplies it. It must obtain
-credentials through the renderer’s Vault generation and process-exec/`LoadCredential` boundary;
-it must not place credentials in a production environment file, a monorepo auto-load path, a shell
-export, command arguments, logs, or a manual secret-activation lifecycle instruction. Rotation and
-process replacement semantics must be delivered by the reviewed renderer/interface with generation,
-consumer-isolation, mode/owner, and no-mixed-generation evidence—not improvised in this guide.
+### 4. Initialize the database
 
-## Readiness and troubleshooting status
+```bash
+pnpm --filter @mosaicstack/db db:migrate
+```
 
-Until the future procedure is implemented, do not diagnose PostgreSQL with ad hoc SQL, connection
-strings, or initialization scripts. The future sanitized runner-verification readiness artifact is
-the required PostgreSQL readiness authority after its bootstrap/TLS prerequisites pass.
-For local PGlite development, diagnose application behavior without introducing a PostgreSQL
-connection.
+### 5. Build all packages
 
-Non-database local services may be inspected with their ordinary local health/log tools. Those
-checks do not certify PostgreSQL, federated deployment, or production readiness.
+```bash
+pnpm build
+```
+
+### 6. Start the gateway
+
+```bash
+pnpm --filter @mosaicstack/gateway dev
+```
+
+Or for production (after build):
+
+```bash
+node apps/gateway/dist/main.js
+```
+
+### 7. Start the web app
+
+```bash
+# Development
+pnpm --filter @mosaicstack/web dev
+
+# Production (after build)
+pnpm --filter @mosaicstack/web start
+```
+
+The web app runs on port `3000` by default.
+
+---
+
+## Bare-Metal Deployment
+
+Use this path when you want to manage PostgreSQL and Valkey yourself (e.g., existing infrastructure, managed cloud databases).
+
+### Step 1 — Install system dependencies
+
+```bash
+# Node.js 22 via nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+nvm install 22
+nvm use 22
+
+# pnpm
+npm install -g pnpm
+
+# PostgreSQL 17 with pgvector (Debian/Ubuntu example)
+sudo apt-get install -y postgresql-17 postgresql-17-pgvector
+
+# Valkey
+# Follow https://valkey.io/download/ for your distribution
+```
+
+### Step 2 — Create 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;
+```
+
+### 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
+```
+
+### Step 4 — Install dependencies and build
+
+```bash
+pnpm install
+pnpm build
+```
+
+### Step 5 — Run database migrations
+
+```bash
+pnpm --filter @mosaicstack/db db:migrate
+```
+
+### Step 6 — Start the gateway
+
+```bash
+node apps/gateway/dist/main.js
+```
+
+The gateway reads `.env` from the monorepo root automatically (via `dotenv` in `main.ts`).
+
+### Step 7 — Start the web app
+
+```bash
+# Next.js standalone output
+node apps/web/.next/standalone/server.js
+```
+
+The standalone build is self-contained; it does not require `node_modules` to be present at runtime.
+
+### Step 8 — Configure a reverse proxy
+
+#### Nginx example
+
+```nginx
+# /etc/nginx/sites-available/mosaic
+
+# Gateway API
+server {
+    listen 443 ssl;
+    server_name your-domain.example.com;
+
+    ssl_certificate     /etc/ssl/certs/your-domain.crt;
+    ssl_certificate_key /etc/ssl/private/your-domain.key;
+
+    # WebSocket support (for chat.gateway.ts / Socket.IO)
+    location /socket.io/ {
+        proxy_pass http://127.0.0.1:14242;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # REST + auth
+    location / {
+        proxy_pass http://127.0.0.1:14242;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+
+# Web app (optional — serve on a subdomain or a separate server block)
+server {
+    listen 443 ssl;
+    server_name app.your-domain.example.com;
+
+    ssl_certificate     /etc/ssl/certs/your-domain.crt;
+    ssl_certificate_key /etc/ssl/private/your-domain.key;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+#### Caddy example
+
+```caddyfile
+# /etc/caddy/Caddyfile
+
+your-domain.example.com {
+    reverse_proxy /socket.io/* localhost:14242 {
+        header_up Upgrade {http.upgrade}
+        header_up Connection {http.connection}
+    }
+    reverse_proxy localhost:14242
+}
+
+app.your-domain.example.com {
+    reverse_proxy localhost:3000
+}
+```
+
+---
+
+## Production Considerations
+
+### systemd Services
+
+Create a service unit for each process.
+
+**Gateway** — `/etc/systemd/system/mosaic-gateway.service`:
+
+```ini
+[Unit]
+Description=Mosaic Gateway
+After=network.target postgresql.service
+
+[Service]
+Type=simple
+User=mosaic
+WorkingDirectory=/opt/mosaic
+EnvironmentFile=/opt/mosaic/.env
+ExecStart=/usr/bin/node apps/gateway/dist/main.js
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Web app** — `/etc/systemd/system/mosaic-web.service`:
+
+```ini
+[Unit]
+Description=Mosaic Web App
+After=network.target mosaic-gateway.service
+
+[Service]
+Type=simple
+User=mosaic
+WorkingDirectory=/opt/mosaic/apps/web
+EnvironmentFile=/opt/mosaic/.env
+ExecStart=/usr/bin/node .next/standalone/server.js
+Environment=PORT=3000
+Environment=HOSTNAME=127.0.0.1
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now mosaic-gateway mosaic-web
+```
+
+### Log Management
+
+Gateway and web app logs go to systemd journal by default. View with:
+
+```bash
+journalctl -u mosaic-gateway -f
+journalctl -u mosaic-web -f
+```
+
+Rotate logs by configuring `journald` in `/etc/systemd/journald.conf`:
+
+```ini
+SystemMaxUse=500M
+MaxRetentionSec=30day
+```
+
+### Security Checklist
+
+- Set `BETTER_AUTH_SECRET` to a cryptographically random value (`openssl rand -base64 32`).
+- Restrict `GATEWAY_CORS_ORIGIN` to your exact frontend origin — do not use `*`.
+- Run services as a dedicated non-root system user (e.g., `mosaic`).
+- Firewall: only expose ports 80/443 externally; keep 14242 and 3000 bound to `127.0.0.1`.
+- Set `AGENT_FILE_SANDBOX_DIR` to a directory outside the application root to prevent agent tools from accessing source code.
+- If using `AGENT_USER_TOOLS`, enumerate only the tools non-admin users need.
+
+---
+
+## Troubleshooting
+
+### Gateway fails to start — "BETTER_AUTH_SECRET is required"
+
+`BETTER_AUTH_SECRET` is missing or empty. Set it in `.env` and restart.
+
+### `DATABASE_URL` 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;
+```
+
+### Valkey / Redis connection refused
+
+Check the URL in `VALKEY_URL`. The Docker Compose default is port `6380`.
+
+```bash
+redis-cli -u "$VALKEY_URL" ping
+```
+
+### WebSocket connections fail in production
+
+Ensure your reverse proxy forwards the `Upgrade` and `Connection` headers. See the Nginx/Caddy examples above.
+
+### Ollama models not appearing
+
+Set `OLLAMA_BASE_URL` to the URL where Ollama is running (e.g., `http://localhost:11434`) and set `OLLAMA_MODELS` to a comma-separated list of model IDs you have pulled.
+
+```bash
+ollama pull llama3.2
+```
+
+### OTEL traces not appearing in Jaeger
+
+Verify the collector is reachable at `OTEL_EXPORTER_OTLP_ENDPOINT`. With Docker Compose the default is `http://localhost:4318`. Check `docker compose ps` and `docker compose logs otel-collector`.
+
+### Summarization / embedding features not working
+
+These features require `OPENAI_API_KEY` to be set, or you must point `SUMMARIZATION_API_URL` / `EMBEDDING_API_URL` to an OpenAI-compatible endpoint (e.g., a local Ollama instance with an embeddings model).

docs/guides/dev-guide.md

@@ -8,9 +8,8 @@
 4. [Adding New Agent Tools](#adding-new-agent-tools)
 5. [Adding New MCP Tools](#adding-new-mcp-tools)
 6. [Database Schema and Migrations](#database-schema-and-migrations)
-7. [Claude Code Skill Bridge](#claude-code-skill-bridge)
-8. [API Endpoint Reference](#api-endpoint-reference)
-9. [Local Fleet Canary](./fleet-local-canary.md)
+7. [API Endpoint Reference](#api-endpoint-reference)
+8. [Local Fleet Canary](./fleet-local-canary.md)
 
 ---
 
@@ -40,7 +39,7 @@ mosaic-mono-v1/
 │   ├── queue/            # Valkey-backed task queue
 │   └── types/            # Shared TypeScript types
 ├── docker/               # Dockerfile(s) for containerized deployment
-├── infra/                # Infrastructure configuration (for example, OTEL collector)
+├── infra/                # Infra config (OTEL collector, pg-init scripts)
 ├── docker-compose.yml    # Local services (Postgres, Valkey, OTEL, Jaeger)
 └── CLAUDE.md             # Project conventions for AI coding agents
 ```
@@ -87,54 +86,71 @@ cd mosaic-mono-v1
 pnpm install
 ```
 
-### 2. Use the local PGlite tier
-
-The supported local tier is in-process PGlite and requires no PostgreSQL service. Leave
-`DATABASE_URL` unset for this route. Its default local configuration uses PGlite and performs no
-external database probe.
-
-If a local queue service is useful, start only that non-PostgreSQL service:
+### 2. Start Infrastructure Services
 
 ```bash
-docker compose up -d valkey
+docker compose up -d
 ```
 
-Do not use the current Compose PostgreSQL service: it mounts legacy `infra/pg-init` SQL and is
-not qualified for KBN-101. Start OTEL Collector or Jaeger individually only when needed and
-without starting PostgreSQL.
+This starts:
 
-### 3. Gateway/Web local process (held)
+| Service                  | Port           | Description          |
+| ------------------------ | -------------- | -------------------- |
+| PostgreSQL 17 + pgvector | `5433` (host)  | Primary database     |
+| Valkey 8                 | `6380` (host)  | Queue and cache      |
+| OpenTelemetry Collector  | `4317`, `4318` | OTEL gRPC and HTTP   |
+| Jaeger                   | `16686`        | Distributed trace UI |
 
-Do not start the current Gateway or web process as a local PGlite route. Gateway first loads the
-daemon configuration and then project environment files without a tier guard; a pre-existing
-`DATABASE_URL` can select PostgreSQL, where current startup still reaches runtime DDL/migrations.
-Creating a root `.env` that omits `DATABASE_URL` does not make this safe, so neither a local
-credential file nor a web environment file is a current developer procedure.
+### 3. Configure Environment
 
-PGlite remains the supported in-process data-layer implementation, and the optional Valkey command
-above remains safe because it does not start PostgreSQL. A safe Gateway/Web local procedure is held
-until KBN-101-02 rejects a daemon, inherited, root, or app-local PostgreSQL DSN and any non-local
-tier before connection or DDL; KBN-101-05 then supplies the production renderer/Vault process-exec
-or `LoadCredential` boundary.
+Create a `.env` file in the monorepo root:
 
-### Held future procedure
+```env
+# Database (matches docker-compose defaults)
+DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
 
-PostgreSQL local and federated deployment are held until KBN-101-00 (external bootstrap),
-KBN-101-03 (runner), and KBN-101-05 (renderer-backed deployment) land. The following is the
-**held, non-operative future activation order with no current command authority**:
+# Auth (required — generate a random 32+ char string)
+BETTER_AUTH_SECRET=change-me-to-a-random-secret
 
-external bootstrap → TLS/roles → `mosaic-db-migrator --run` →
-`mosaic-db-migrator --verify` → Gateway/Compose readiness.
+# Gateway
+GATEWAY_PORT=14242
+GATEWAY_CORS_ORIGIN=http://localhost:3000
 
-Neither current Compose nor this development guide authorizes PostgreSQL initialization SQL,
-manual DDL, or a pre-runner start.
+# Web
+NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
 
-### 5. Gateway/Web start (held)
+# Optional: Ollama
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODELS=llama3.2
+```
 
-No Gateway/Web start command is currently authorized for the local PGlite route. Do not use root
-`pnpm dev` as a workaround: it additionally starts configured integrations and cannot establish the
-required local-tier/DSN isolation. Resume this section only after KBN-101-02 provides its
-fail-closed local-startup evidence.
+The gateway loads `.env` from the monorepo root via `dotenv` at startup
+(`apps/gateway/src/main.ts`).
+
+### 4. Push the Database Schema
+
+```bash
+pnpm --filter @mosaicstack/db db:push
+```
+
+This applies the Drizzle schema directly to the database (development only; use
+migrations in production).
+
+### 5. Start the Gateway
+
+```bash
+pnpm --filter @mosaicstack/gateway exec tsx src/main.ts
+```
+
+The gateway starts on port `14242` by default.
+
+### 6. Start the Web App
+
+```bash
+pnpm --filter @mosaicstack/web dev
+```
+
+The web app starts on port `3000` by default.
 
 ---
 
@@ -284,13 +300,26 @@ Implement a standard MCP server that exposes tools via the streamable HTTP
 transport or SSE transport. The server must accept connections at a `/mcp`
 endpoint.
 
-### 2. Gateway MCP configuration (held)
+### 2. Configure `MCP_SERVERS`
 
-Do not configure MCP endpoint credentials, write them to a local environment file, or restart the
-Gateway from this guide. Gateway/Web startup is held until KBN-101-02 supplies fail-closed
-local-tier/DSN isolation and KBN-101-05 supplies the renderer/Vault process-exec or
-`LoadCredential` secret-consumer interface. The future authenticated MCP route requires verified
-HTTPS and certificate validation; plaintext bearer-token examples are forbidden.
+In your `.env`:
+
+```env
+MCP_SERVERS='[{"name":"my-server","url":"http://localhost:3001/mcp"}]'
+```
+
+With authentication:
+
+```env
+MCP_SERVERS='[{"name":"secure-server","url":"http://my-server/mcp","headers":{"Authorization":"Bearer token"}}]'
+```
+
+### 3. Restart the Gateway
+
+On startup, `McpClientService` (`apps/gateway/src/mcp-client/mcp-client.service.ts`)
+connects to each configured server, calls `tools/list`, and bridges the results
+to Pi SDK `ToolDefinition` format. These tools become available in all new agent
+sessions.
 
 ### Tool Naming
 
@@ -326,65 +355,45 @@ The schema lives in a single file:
 
 The `insights` table uses a `vector(1536)` column (pgvector) for semantic search.
 
-### PostgreSQL schema work (held)
+### Development: Push Schema
 
-Do not prepare or run a PostgreSQL target from this branch. The sole runner, bootstrap, and
-renderer are future KBN-101 artifacts, not current commands. When KBN-101-00/-03/-05 land, the
-owned activation documentation will require external bootstrap → TLS/roles → runner `--run` →
-runner `--verify` → Gateway/Compose readiness.
+Apply schema changes directly to the dev database (no migration files created):
 
-### Generating migration artifacts
+```bash
+pnpm --filter @mosaicstack/db db:push
+```
 
-`pnpm --filter @mosaicstack/db db:generate` is an offline artifact-generation command. It does
-not authorize connecting to or initializing PostgreSQL. A future reviewed PostgreSQL procedure
-will determine when its output is applied.
+### Generating Migrations
+
+For production-safe, versioned changes:
+
+```bash
+pnpm --filter @mosaicstack/db db:generate
+```
+
+This creates a new SQL migration file in `packages/db/drizzle/`.
+
+### Running Migrations
+
+```bash
+pnpm --filter @mosaicstack/db db:migrate
+```
 
 ### Drizzle Config
 
-Config is at `packages/db/drizzle.config.ts`. The schema file path and output directory are
-defined there.
+Config is at `packages/db/drizzle.config.ts`. The schema file path and output
+directory are defined there.
 
 ### Adding a New Table
 
 1. Add the table definition to `packages/db/src/schema.ts`.
 2. Export it from `packages/db/src/index.ts`.
-3. Generate the offline artifact with `pnpm --filter @mosaicstack/db db:generate`.
-4. Do not apply it to PostgreSQL until the future KBN-101 activation artifacts and their owned
-   procedure are available. Direct schema push is not a production-like workflow.
+3. Run `pnpm --filter @mosaicstack/db db:push` (dev) or
+   `pnpm --filter @mosaicstack/db db:generate && pnpm --filter @mosaicstack/db db:migrate`
+   (production).
 
 ---
 
-## Claude Code Skill Bridge
-
-The framework's canonical skill root is `~/.config/mosaic/skills/`; Claude Code
-requires registrations under `~/.claude/skills/`. The implementation in
-`packages/mosaic/src/commands/skill.ts` owns only direct-child symlinks whose
-resolved target remains inside the canonical root.
-
-Security invariants:
-
-1. Validate the user-supplied name before filesystem access against
-   `[A-Za-z0-9][A-Za-z0-9._-]*`. Separators, control characters, whitespace,
-   `..`, absolute paths, and leading `-` are invalid; filesystem-derived invalid
-   names are escaped before terminal output.
-2. Never replace a real file, directory, foreign symlink, or live misdirected
-   symlink in the Claude skill directory.
-3. Repair a dangling link only when its lexical target is inside the canonical
-   Mosaic skills root.
-4. Unregister only a symlink pointing inside that root.
-5. Enumerate canonical directories at runtime; never hardcode framework skill
-   names.
-
-`finalizeStage` reconciles after wizard/framework synchronization, and
-`runFrameworkReseed` reconciles after the sync-only `mosaic update` path. A
-foreign conflict is reported but does not prevent unrelated canonical skills
-from registering. Filesystem tests use injected temporary roots in
-`skill.spec.ts`, `finalize-skills.spec.ts`, and `update-checker.reseed.spec.ts`.
-
-M1 intentionally manages Claude Code only. Pi's Mosaic launcher can discover the
-canonical root directly. Codex still relies on the existing full skill-sync
-linker and needs separate parity analysis before this lifecycle API is extended.
-
 ## API Endpoint Reference
 
 All endpoints are served by the gateway at `http://localhost:14242` by default.

docs/guides/fleet-local-canary.md

@@ -98,39 +98,6 @@ Expected results:
   that means the unit ran, not that an agent pane is live. Treat tmux
   `has-session`, `list-panes`, process tree, and logs as the liveness evidence.
 
-## Recovery — rebuild generated env projections
-
-Each agent's `~/.config/mosaic/fleet/agents/<name>.env.generated` is a
-deterministic projection of `roster.yaml` (the SSOT) that the launcher
-(`start-agent-session.sh`) sources at start. If an upgrade or a manual mistake
-wipes or diverges those projections, rebuild them from the roster with
-`mosaic fleet regen` — do NOT restart the affected unit first.
-
-```bash
-mosaic fleet regen            # dry-run (default): show create/rebuild plan per agent
-mosaic fleet regen --json     # same plan, machine-readable
-mosaic fleet regen --write    # rebuild fleet/agents/<name>.env.generated on disk
-```
-
-`regen` is projection-only and **never restarts an agent** — it has no path to
-systemd lifecycle. It is dry-run by default, deterministic/idempotent, uses the
-same roster→env mapping as `mosaic fleet reconcile`, and emits paths and counts
-only (never the projected `KEY=value` body). After `--write`, verify each unit
-resolves the intended values before restarting one unit at a time. The unit sets
-no `EnvironmentFile=` — `start-agent-session.sh` sources `.env.generated` itself —
-so verify the generated file directly and the launcher path, not a nonexistent
-`EnvironmentFile` property:
-
-```bash
-test -f ~/.config/mosaic/fleet/agents/<name>.env.generated
-systemctl --user cat mosaic-agent@<name> | grep ExecStart
-systemctl --user restart mosaic-agent@<name>
-```
-
-Full recovery runbook and the three-layer #791 protection model (manifest
-ownership → pre-update snapshot/restore → regen): see
-[Upgrade Safety & Recovery](./upgrade-safety-and-recovery.md).
-
 ## Release Preflight
 
 Run this checklist before cutting or dogfooding a fleet release:

docs/guides/lease-broker-operations.md

@@ -1,44 +0,0 @@
-# Lease broker operations
-
-Place the socket and state file in a dedicated directory with mode `0700`. Start the packaged daemon with:
-
-```bash
-python3 "$MOSAIC_HOME/tools/lease-broker/daemon.py" \
-  --socket /run/user/1000/mosaic-lease/broker.sock \
-  --state /run/user/1000/mosaic-lease/state.json
-```
-
-The broker refuses an existing parent directory whose mode is not exactly `0700`, an existing state file not at `0600`, corrupt/incompatible state, or an already-existing socket path. After bind it sets the socket to `0600`. It never silently unlinks a pre-existing socket. On normal termination it unlinks only the socket inode it created, so it does not remove a replacement path.
-
-Before launching Claude, Claudex, or Pi, export the socket path; `mosaic` then runs the runtime through the packaged register-and-exec wrapper:
-
-```bash
-export MOSAIC_LEASE_BROKER_SOCKET=/run/user/1000/mosaic-lease/broker.sock
-mosaic claude # or: mosaic claudex, mosaic yolo claudex, mosaic pi
-```
-
-The wrapper obtains a broker-minted session ID, creates a private `generation-<session>.state` file beside the socket, and `exec`s the runtime without changing its PID/starttime anchor. The all-tools Claude `PreToolUse` hook and Pi `tool_call` handler inherit that identity and read the current generation from the file. Claudex retains its isolated proxy environment and config directory; Mosaic merges the mandatory all-tools and compaction-lifecycle hooks into that isolated `settings.json` before invoking the same wrapper. PRDY init/update, QA remediation, coord, orchestrator, and fleet launchers also converge on this boundary. Broker registration failure, unsafe isolated settings, unsafe generation state, or missing identity denies launch/tool execution fail-closed; broker timeout/unavailability and malformed replies also block tools.
-
-Claude `PreCompact` and `SessionStart(compact)` hooks and Pi pre-/post-compaction handlers invoke `revoke-lease.py`. Pi `session_start` reload/new/resume/fork and Claude resume/clear advance the locked generation before revocation, so a replacement session inherits no lease even when PID/starttime stay unchanged. Do not invoke the revoker manually as a way to restore authority; it only removes authority. If a lifecycle hook reports failure, stop consequential work and repair broker/generation-state availability before re-verification.
-
-Run the permanent launch inventory locally with:
-
-```bash
-python3 packages/mosaic/framework/tools/lease-broker/check-runtime-launches.py --root .
-```
-
-The same check runs in the Mosaic package test suite and therefore in root CI. Any direct Claude/Pi binary launch must be replaced with `launch-runtime.py`, `execLeaseGatedRuntime`, or the gated `mosaic` runtime command; do not add static allowlist exceptions.
-
-Clients must complete the request boundary before waiting for a reply. After sending the single JSON object and its terminating newline, the client **MUST half-close the socket's write side** (`shutdown(SHUT_WR)` in POSIX clients; `socket.end()` in Node) and only then await the response. Merely calling `write()` and waiting is invalid: the broker waits for EOF to enforce the exact-one-frame contract and fails closed at its one-second deadline. Do not replace `end()` with `write()` in client helpers. A delayed second frame remains malformed and is rejected.
-
-`mosaic_context_recover` is the only unverified mutator class. Its durable `mosaic-context-refresh` skill is a thin wrapper over `tools/lease-broker/recover-context.py`: `begin` has the broker rebuild the validated `B_payload`/`H_payload`, revoke first, and mint a new `PENDING_DELIVERY` receipt challenge; `complete` accepts neither receipt text nor a challenge argument. Claude maps only the exact direct recovery executable/validated arguments to this exempt tool identity; ordinary `Bash` remains gated. Pi exposes only the `mosaic_context_recover` custom tool; ordinary `bash` and all other tools remain gated. A normal-path receipt cannot be replayed through recovery because each retry begins a distinct recovery cycle and recovery completion cannot receive caller-presented evidence.
-
-Production daemon startup creates a separate private observer socket unless a test-only `--test-observer-file` fixture is selected. Claude's Stop hook sends its exact latest assistant entry and Pi's `message_end` handler sends only finalized assistant content to that authenticated transport; the broker public socket never accepts message text. This is byte-build and private out-of-process harness wiring only: do not activate it against a live daemon, live socket, systemd service, tmux session, or model-output stream outside the controlled integration procedure.
-
-Receipt honesty is load-bearing: absent, malformed, prefix-truncated, and observable adapter-mutated terminal receipts do not promote. A tail-only case is non-promoting only where the concrete terminal payload is malformed or observably incomplete. A tail-preserving middle drop is **not receipt-detectable**; it is the disclosed T-C injection-contract residual deferred to WI-7 server-side evidence. The receipt remains a T-A delivery/liveness prerequisite, never a safety, obedience, or residency proof. The framework skill is source-resident and bridge-projected on install/upgrade; do not hand-create a live runtime symlink.
-
-After a runtime exits, its `generation-<session>.state` file may be removed only after verifying that no process for that broker-minted session remains; stale files carry no lease authority but should be retained during incident analysis. After a broker crash, preserve the protected state file and restart only after verifying that no broker owns the socket. Restart intentionally clears all volatile VERIFIED leases. A leftover socket requires an operator to verify the owning service is stopped and remove that exact socket deliberately. Corrupt, oversized, symlinked, or non-regular state fails closed; do not overwrite it. Preserve it for incident review and establish new state only through an explicit operational decision, which invalidates prior sessions and tokens.
-
-## Security posture
-
-Directory `0700` plus socket/state `0600` is built-in same-principal hardening only: it excludes other UIDs but does **not** stop the same UID from unlinking and counterfeiting the socket. It therefore does not close T-C same-UID replacement. WI-1 does not provide a distinct-principal boundary. A stronger distinct-principal deployment requires an external protected proxy, ACL, or service boundary that clients cannot unlink or rebind and that preserves the authenticated client identity required by the broker's `SO_PEERCRED` and ancestry checks. Server-side branch protection remains the irreducible backstop.

docs/guides/migrate-tier.md

@@ -1,98 +1,147 @@
 # Migrating to the Federated Tier
 
-> **KBN-101-07 ownership:** This active documentation is a **non-operative KBN-101
-> contract** with no current command authority until KBN-101-00, KBN-101-02, KBN-101-03, KBN-101-05, and KBN-101-06 land and
-> KBN-101-08 activates an exact reviewed release. The commands below describe the produced interface only. Do not run them on the
-> current branch or replace them with direct PostgreSQL, raw SQL, legacy storage migration, or
-> credential-on-argv procedures.
+Step-by-step guide to migrate from `local` (PGlite) or `standalone` (PostgreSQL without pgvector) to `federated` (PostgreSQL 17 + pgvector + Valkey).
 
-## Held future procedure
+## When to migrate
 
-This section is non-operative and grants no current command authority until KBN-101-00, KBN-101-03, and KBN-101-05 land.
+Migrate to federated tier when:
 
-The deployment control plane executes the complete held future procedure, in order: external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness. The
-runner is the only attestation producer after its verified TLS, identity, manifest, and schema
-checks. A data importer is never a schema bootstrap, extension installer, repair command, or DDL
-consumer.
+- 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
 
-## Target material contract
+## Prerequisites
 
-KBN-101-05 obtains the target URL from Vault KV-v2
-`secret-{env}/mosaic-stack/database/importer`, key `url`, and reads its authenticated version from
-the same successful response `data.metadata.version`. A hash or DSN byte sequence is not a
-provider version. The renderer treats URL bytes and provider version as one generation, writes a
-temporary generation directory with fsync plus atomic rename, and creates separate immutable
-consumer mounts. Swarm uses distinct versioned secret/config references. A deployment cannot mix
-generations.
+- 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)
 
-| Consumer                                      | Permitted material                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Migrator-attestation producer (`10003:10003`) | Its own migration URL/CA; read-only `/run/secrets/mosaic-migrate-target-url` and `/run/secrets/mosaic-migrate-target-version`, each `0400`, solely to bind; producer-only attestation output at `/run/mosaic-attestations-producer/migrate-target.v1.json`; root-wrapper-only signing key. It never connects with, uses, exports, logs, or forwards the importer URL/version.                                                                                                            |
-| Privileged deployment handoff controller      | After runner success and before importer creation, it receives only root-owned non-secret expected provider-version/URL-SHA-256/generation descriptor and pinned public verifier key—not URL bytes or private key. It safe-opens/verifies descriptor and producer artifact, copies exact bytes to a new importer-only mount with fsync/atomic rename, sets `10002:10002` `0400`, seals it read-only, and refuses importer start on any partial/wrong-generation/wrong-owner/mode result. |
-| Importer (`10002:10002`)                      | Its own immutable `0400` copies at the same URL/version paths; CA at exact `DATABASE_TLS_CA_CERT_PATH=/run/secrets/mosaic-db-ca.crt`; pinned Ed25519 public key; read-only `/run/mosaic-attestations/migrate-target.v1.json` supplied only by the sealed handoff.                                                                                                                                                                                                                        |
-| Gateway/runtime/unrelated container           | No importer URL/version, importer artifact, attestation private key, or unrelated CA mount.                                                                                                                                                                                                                                                                                                                                                                                              |
+## Dry-run first
 
-The migrator and importer safe-open URL, provider-version, attestation, and public-key files only
-with `O_RDONLY|O_CLOEXEC|O_NOFOLLOW`; they validate from the opened fd that the file is regular,
-has its expected owner/mode and link count one. The migrator digests only that URL fd for binding,
-then zeroizes/closes it. The importer reads URL bytes once into protected memory, validates the
-signed binding and exact CA before connecting from those same bytes, then zeroizes/closes every
-fd. It neither logs nor exposes a URL/version/attestation/key oracle.
-
-## Produced command interface
-
-After activation and only after approved target preparation, the future interface is:
+Always run a dry-run to validate the migration:
 
 ```bash
-# Deployment control plane has already completed the held runner procedure above.
 mosaic storage migrate-tier --to federated \
-  --target-url-file /run/secrets/mosaic-migrate-target-url \
-  --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \
+  --target-url postgresql://mosaic:mosaic@localhost:5433/mosaic \
   --dry-run
 ```
 
-The provider-version file is fixed deployment material, not argv. This connecting dry-run consumes its nonce; before an actual copy, the deployment control plane must provide fresh runner verification and a new sealed handoff. The runner uses its migration
-identity; the importer connects only as non-DDL `mosaic_data_importer` and only after all
-pre-connect validation. After verified TLS and before DML it compares PostgreSQL system ID,
-database OID, `current_user`, CA/SPKI, and manifest/schema fingerprints to the artifact.
+Expected output (partial example):
 
-## Required refusals and evidence
+```
+[migrate-tier] Analyzing source tier: pglite
+[migrate-tier] Analyzing target tier: federated
+[migrate-tier] Precondition: target is empty ✓
+  users: 5 rows
+  teams: 2 rows
+  conversations: 12 rows
+  messages: 187 rows
+  ... (all tables listed)
+[migrate-tier] NOTE: Source tier has no pgvector support. insights.embedding will be NULL on all migrated rows.
+[migrate-tier] DRY-RUN COMPLETE (no data written). 206 total rows would be migrated.
+```
 
-KBN-101-02/-03/-05/-06 must prove, with stable sanitized errors, that no target connection occurs
-for missing/unsafe URL/version/attestation/public-key files; symlink, hardlink, owner, mode, or
-TOCTOU violations; mixed URL/version generations; missing/wrong CA mount; stale/replayed/tampered
-or revoked-key artifacts; provider rotation/revocation; wrong TLS/server/database/role/manifest
-binding; raw `--target-url`; `DATABASE_URL` fallback; runtime/owner identity; consumer leakage;
-or any DDL attempt. Post-connect identity mismatch closes with zero DML/DDL. Tests also prove no
-forwarding, child environment, logging, or error oracle leaks URL/version/key/artifact contents.
+Review the output. If it shows an error (e.g., target not empty), address it before proceeding.
 
-The attestation is credential-free JCS with detached Ed25519 signature and binds issued/expiry,
-nonce, authenticated provider version, exact URL-fd SHA-256, TLS host/port/database, CA/SPKI,
-PostgreSQL system ID/database OID, importer role, manifest/schema, and producer identity. Provider
-version rotation invalidates an old artifact and requires a fresh rendered generation plus runner
-verification.
+## Run the migration
 
-## Actual copy after dry-run
-
-After reviewed dry-run, obtain the required fresh verification/attestation generation, then use:
+When ready, run without `--dry-run`:
 
 ```bash
-# Deployment control plane has supplied fresh runner verification and attestation.
 mosaic storage migrate-tier --to federated \
-  --target-url-file /run/secrets/mosaic-migrate-target-url \
-  --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \
+  --target-url postgresql://mosaic:mosaic@localhost:5433/mosaic \
   --yes
 ```
 
-The dry-run artifact is terminally replayed and must be rejected; `--yes` bypasses no file,
-generation, signature, TLS, identity, or DDL control.
+The `--yes` flag skips the confirmation prompt (required in non-TTY environments like CI).
 
-## Data boundary and recovery
+The command will:
 
-The importer has only an allowlisted mutable-table DML registry. It has no grant for immutable KBN
-relations, schemas, roles, memberships, extensions, catalogs, or the Drizzle ledger. Source PGlite
-uses its explicit local directory and does not make a PostgreSQL URL fallback valid.
+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)
 
-A failed or ambiguous migration is a control-plane incident: preserve sanitized evidence, retain
-the approved backup/rollback state, and retry only after independent review. Never inspect,
-unlock, repair, or initialize the target with ad hoc SQL or copied credentials.
+## What gets migrated
+
+All persistent, user-bound data is migrated in dependency order:
+
+- **users, teams, team_members** — user and team ownership
+- **accounts** — OAuth provider tokens (durable credentials)
+- **projects, agents, missions, tasks** — all project and agent definitions
+- **conversations, messages** — all chat history
+- **preferences, insights, agent_logs** — preferences and observability
+- **provider_credentials** — stored API keys and secrets
+- **tickets, events, skills, routing_rules, appreciations** — auxiliary records
+
+Full order is defined in code (`MIGRATION_ORDER` in `packages/storage/src/migrate-tier.ts`).
+
+## What gets skipped and why
+
+Three tables are intentionally not migrated:
+
+| Table             | Reason                                                                                          |
+| ----------------- | ----------------------------------------------------------------------------------------------- |
+| **sessions**      | TTL'd auth sessions from the old environment; they will fail JWT verification on the new target |
+| **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.
+
+## Idempotency and concurrency
+
+The migration is **idempotent**:
+
+- 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;"
+```
+
+## Rollback
+
+There is no in-place rollback. If the migration fails:
+
+1. Restore the target database from a pre-migration backup
+2. Investigate the failure logs
+3. Rerun the migration
+
+Always test migrations in a staging environment first.

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

@@ -1,43 +0,0 @@
-# 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/upgrade-safety-and-recovery.md

@@ -1,147 +0,0 @@
-# Upgrade Safety & Recovery
-
-How Mosaic protects operator-owned configuration under `~/.config/mosaic` across
-framework upgrades, and how to recover if a projection is ever lost.
-
-A framework upgrade runs `install.sh` in keep-mode (`MOSAIC_INSTALL_MODE=keep`,
-`MOSAIC_SYNC_ONLY=1`) to refresh framework-owned files in place. The incident
-this hardening addresses: an upgrade that silently overwrites or deletes a file
-the operator owns — credentials, personas, a roster, or a generated agent env —
-with no snapshot to fall back to.
-
-Protection is layered. Each layer is independent; a later layer catches what an
-earlier one misses.
-
-## Layer 1 — Manifest-owned sync (prevention)
-
-The single source of truth for ownership is
-[`framework-manifest.txt`](../../packages/mosaic/framework/framework-manifest.txt).
-Both the bash installer and the TypeScript sync path resolve every path against
-this one file (parity is enforced by test), so they can never drift.
-
-- Ownership is **allow-list, deny-wins**: a path is framework-owned only if a
-  `[framework]` glob matches and no `[operator]` carve-out overrides it.
-- **Unknown paths default to operator** (fail-safe): a file the manifest never
-  anticipated is treated as operator-owned and is never pruned.
-- Keep-mode does a non-deleting copy plus an explicit, manifest-scoped prune that
-  only ever iterates framework globs — operator and unknown paths are
-  structurally unreachable by the prune.
-
-Result: a correct upgrade cannot touch operator config at all.
-
-## Layer 2 — Durable pre-update snapshot + verify net (safety + rollback)
-
-Before **any** mutation, the installer snapshots the operator-owned surface that
-exists into:
-
-```
-${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-timestamp>/
-```
-
-- `0700` directories / `0600` files (`umask 077`, scoped and restored),
-  outside `~/.config/mosaic` and outside any repo.
-- **Fail-open**: a snapshot failure warns but never aborts the upgrade it
-  protects.
-- Retention is `MOSAIC_BACKUP_RETENTION` snapshots (default 5).
-
-After the sync, a **verify net** compares each snapshot file against its target
-and restores (with a loud warning) any operator file the upgrade diverged or
-removed — a divergence means a manifest bug slipped through Layer 1.
-
-Inspect and restore snapshots with the CLI:
-
-```bash
-mosaic restore --list                 # dry-run: enumerate snapshots by timestamp
-mosaic restore --from <UTC-timestamp> # restore the operator surface from one snapshot
-mosaic restore --from <ts> --dry-run  # preview a specific restore without writing
-```
-
-`mosaic restore` reports **counts and relative paths only** — it never emits file
-contents, so a secret in `tools/_lib/credentials.json` is never echoed. Restores
-are confirmation-gated (`--yes` or `MOSAIC_ASSUME_YES`) and write each leaf
-atomically with `O_NOFOLLOW` (a symlink swapped in after the snapshot fails
-closed rather than following out of the managed tree).
-
-## Layer 3 — Regeneration from roster SSOT (recovery)
-
-Some operator files are **derived** and do not need a byte-for-byte snapshot to
-recover — they can be rebuilt from their source of truth. The fleet's per-agent
-generated env projections are the prime case:
-
-- `~/.config/mosaic/fleet/agents/<name>.env.generated` is a deterministic
-  projection of `~/.config/mosaic/fleet/roster.yaml`.
-- The launcher (`start-agent-session.sh`, invoked by
-  `mosaic-agent@<name>.service`) sources that generated projection to establish
-  each agent's identity, runtime, model, and working directory. If it is missing
-  or wrong, the agent cannot launch with its intended identity.
-
-`mosaic fleet regen` rebuilds those projections from the roster SSOT:
-
-```bash
-mosaic fleet regen            # dry-run (default): show what would be rebuilt
-mosaic fleet regen --json     # same, machine-readable
-mosaic fleet regen --write    # rebuild the projections on disk
-```
-
-- **Dry-run by default.** Nothing is written until you pass `--write`.
-- **Deterministic and idempotent** — the projection is a pure function of the
-  roster, so repeated `--write` runs produce byte-identical files.
-- **Projection-only. It never restarts an agent.** Recovery order forbids
-  restart-before-verify; `regen` has no path to systemd lifecycle at all.
-- **It rebuilds only `<name>.env.generated`** — it never writes, relocates, or
-  deletes the operator-owned `.env` / `.env.local` surface.
-- It **validates the roster the same way `reconcile` does** (persona resolution
-  and protected-class tool-policy match), so a hand-edited or corrupt roster is
-  rejected rather than projected, and a `--write` takes the shared reconcile
-  lock so it cannot race a concurrent reconcile.
-- Output is **paths and counts only** — the rendered `KEY=value` body is never
-  echoed.
-
-`regen` uses the exact same roster→env mapping as `mosaic fleet reconcile`, so a
-recovered projection matches what a normal reconcile would have written.
-
-## Recovery runbook — wiped `fleet/agents/*.env.generated`
-
-If an upgrade (or a manual mistake) has left an agent without its generated
-projection, **do not restart the unit first** — a launch against a missing
-projection fails closed, and any stale state must be corrected before restart,
-not after.
-
-1. **Prefer a snapshot restore if one exists** (byte-exact operator state):
-
-   ```bash
-   mosaic restore --list
-   mosaic restore --from <UTC-timestamp>
-   ```
-
-2. **Otherwise regenerate the derived projections from the roster SSOT:**
-
-   ```bash
-   mosaic fleet regen            # confirm the plan (create vs rebuild per agent)
-   mosaic fleet regen --write    # rebuild fleet/agents/<name>.env.generated
-   ```
-
-3. **Verify each unit will resolve the intended runtime/workdir _before_ any
-   restart.** The unit sets **no** `EnvironmentFile=` — it launches from a minimal
-   environment and `start-agent-session.sh` sources `.env.generated` itself, so
-   verify the generated file directly and confirm the launcher path:
-
-   ```bash
-   # Confirm fleet/agents/<name>.env.generated exists and carries the intended
-   # MOSAIC_AGENT_* values (name, runtime, model, workdir, socket).
-   test -f ~/.config/mosaic/fleet/agents/<name>.env.generated
-   # Confirm the unit launches the session script that reads it.
-   systemctl --user cat mosaic-agent@<name> | grep ExecStart
-   ```
-
-4. **Only then restart, one unit at a time:**
-
-   ```bash
-   systemctl --user restart mosaic-agent@<name>
-   ```
-
-## See also
-
-- Design: [`docs/design/791-upgrade-config-protection.md`](../design/791-upgrade-config-protection.md)
-- Fleet operations: [`docs/guides/fleet-local-canary.md`](./fleet-local-canary.md)
-- Ownership SSOT: [`packages/mosaic/framework/framework-manifest.txt`](../../packages/mosaic/framework/framework-manifest.txt)

docs/guides/user-guide.md

@@ -183,8 +183,6 @@ non-interactive use:
 --no-auto-launch    # Skip auto-launch of wizard after install
 ```
 
-Unrecognized flags or positional arguments fail before installation starts and print the supported-option usage.
-
 Or if installed globally:
 
 ```bash
@@ -309,39 +307,6 @@ mosaic quality-rails
 
 ---
 
-### Claude Code Skill Registration
-
-Mosaic stores canonical skills under `~/.config/mosaic/skills/`. Claude Code scans
-`~/.claude/skills/`, so Mosaic maintains one symlink per skill between those
-directories.
-
-```bash
-mosaic skill list
-mosaic skill register <name>
-mosaic skill unregister <name>
-```
-
-- `register` is idempotent and repairs a dangling Mosaic-owned link. Names use
-  the safe grammar `[A-Za-z0-9][A-Za-z0-9._-]*`; files, directories, foreign
-  symlinks, path traversal, absolute paths, and names beginning with `-` are
-  refused.
-- `unregister` is idempotent when no entry exists. It removes only symlinks that
-  point inside `~/.config/mosaic/skills/`; foreign entries are never removed.
-- `list` reports `registered`, `unregistered`, `dangling`, `foreign`,
-  `foreign-dangling`, or `misdirected` for each canonical or Claude entry.
-
-Install, wizard finalization, and `mosaic update` framework re-seeding reconcile
-every canonical skill automatically. A skill directory added after initial
-setup therefore receives its Claude bridge without a per-skill code change or
-manual `ln -s`. If Claude Code is already running, use `/reload-skills` or start
-a new session after registration so its in-process skill registry rescans.
-
-This command group is Claude-only in M1. Pi can consume Mosaic's canonical skill
-root through its Mosaic launcher configuration and does not need this Claude
-bridge. Codex has a separate link path managed by the legacy full skill-sync
-script; equivalent lifecycle management remains follow-up scope and is not
-changed here.
-
 ## Sub-package Commands
 
 Each Mosaic sub-package exposes its full API surface through the `mosaic` CLI.
@@ -557,14 +522,8 @@ mosaic storage export --bucket agent-artifacts --output ./artifacts.tar.gz
 # Import data into storage
 mosaic storage import --bucket agent-artifacts --input ./artifacts.tar.gz
 
-# Schema migration is unavailable in this release. The current storage wrapper shells
-# directly to `pnpm --filter @mosaicstack/db db:migrate`; it is legacy N-1,
-# uncertified, and MUST NOT be invoked pending KBN-101-02/-03/-06/-08 activation.
-# Future schema migration is non-operative: external bootstrap → TLS/roles → runner
-# --run → runner --verify → readiness.
-
-# Tier copy uses only the separately held secure migrate-tier route. Never use a legacy
-# --from/--to storage-migrate command or pass a credential on argv.
+# Migrate data between tiers
+mosaic storage migrate --from hot --to cold --older-than 30d
 ```
 
 ---

docs/native-kanban-sot/INDEX.md

@@ -1,28 +1,26 @@
 # Native Kanban/SOT Canon
 
-**Status:** KCR-001–016 independently cleared; KBN-101 rc.16 current generic storage-wrapper authority remediation awaits independent exact-head re-review under issue [#771](https://git.mosaicstack.dev/mosaicstack/stack/issues/771)
+**Status:** KCR-001–016 independently cleared; canonical publication is in progress under issue [#751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
 **Date:** 2026-07-14
 **Implementation hold:** no feature implementation starts until this canon is squash-merged to `main` with terminal-green CI; after merge, every slice remains held until its KBN prerequisite graph is satisfied.
 
 ## Artifacts
 
-| Artifact                                                                                                       | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Canonical requirements](../requirements/native-kanban-sot.md)                                                 | Canonical P0–P3 requirements, all seven ratified decisions, fixed invariants, thin MVP, recovery tiers, non-goals, and per-requirement acceptance criteria                                                                                                                                                                                                                                                                                                                                                                                  |
-| [`MISSION-MANIFEST.md`](./MISSION-MANIFEST.md)                                                                 | Mission/authority boundaries, exact role chain, gate model, mandatory SecReview triggers, Certifier final/no-merge rule, and collision-free slice ownership                                                                                                                                                                                                                                                                                                                                                                                 |
-| [`TASKS.md`](./TASKS.md)                                                                                       | Dependency-ordered, bounded P0–P3 slices with IN/OUT scope, dependencies, shared contracts, file ownership, evidence, and USC coder2/3/4/5 parallelization                                                                                                                                                                                                                                                                                                                                                                                  |
-| [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md)                                                       | rc.16 direct-Drizzle current storage-wrapper hold: legacy N-1/uncertified/non-operative pending -02/-03/-06/-08; exact README commented/user-guide executable forms fail before masking and source-consistency rejects runner-delegation copy; held future bootstrap → TLS/roles → run → verify → readiness; plus prior production boundary, pgvector owner, attestation, inventory, manifests, DDL classifier, TLS/bootstrap, 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.16 awaits independent exact-head re-review after closing the current generic storage-wrapper authority HIGH finding                                                                                                                                                                                                                                                                                                                                      |
-| [Initial independent review](../reports/native-kanban-sot/canon-initial-review-no-go.md)                       | KCR-001–016 findings that blocked the first draft                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| [Final independent re-review](../reports/native-kanban-sot/canon-final-rereview-go.md)                         | Closure 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                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Artifact                                                                                 | Purpose                                                                                                                                                                                               |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Canonical requirements](../requirements/native-kanban-sot.md)                           | Canonical P0–P3 requirements, all seven ratified decisions, fixed invariants, thin MVP, recovery tiers, non-goals, and per-requirement acceptance criteria                                            |
+| [`MISSION-MANIFEST.md`](./MISSION-MANIFEST.md)                                           | Mission/authority boundaries, exact role chain, gate model, mandatory SecReview triggers, Certifier final/no-merge rule, and collision-free slice ownership                                           |
+| [`TASKS.md`](./TASKS.md)                                                                 | Dependency-ordered, bounded P0–P3 slices with IN/OUT scope, dependencies, shared contracts, file ownership, evidence, and USC coder2/3/4/5 parallelization                                            |
+| [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)                                             | Remediated v1 integration contract: proof authority, exact failures/routes/DTOs/MCP ownership, concrete current-main field migration map, relational invariants, Coordinator split, recovery delivery |
+| [`contracts/kanban-schema.v1.ts`](./contracts/kanban-schema.v1.ts)                       | Drizzle target declarations including exact owner/principal membership, project congruence, tags/archive, proposals, persisted assignments, monotonic fences, durable retry, immutable evidence/audit |
+| [`contracts/mechanical-coordinator.v1.ts`](./contracts/mechanical-coordinator.v1.ts)     | Pure snapshot decision engine separated from persistence/service adapter; ID-bound approvals, bigint-safe fences, durable retry/quarantine, artifact-backed checkpoints, exact failures               |
+| [`contracts/health-state.v1.ts`](./contracts/health-state.v1.ts)                         | Discriminated public health, separate branded transaction-local write proof, and non-overlapping denial/transport/version-conflict mappings                                                           |
+| [`contracts/recovery-posture.v1.ts`](./contracts/recovery-posture.v1.ts)                 | Provider-neutral shape schema plus normative runtime refinement, cross-field constraints, and Lite/Standard/High-assurance defaults                                                                   |
+| [`tsconfig.json`](./tsconfig.json)                                                       | Strict no-emit project scope for linting and compiling the four frozen TypeScript contracts against the current Stack Drizzle declarations                                                            |
+| [`DOCUMENTATION-CHECKLIST.md`](./DOCUMENTATION-CHECKLIST.md)                             | Publication documentation gate and implementation-slice deferrals                                                                                                                                     |
+| [Initial independent review](../reports/native-kanban-sot/canon-initial-review-no-go.md) | KCR-001–016 findings that blocked the first draft                                                                                                                                                     |
+| [Final independent re-review](../reports/native-kanban-sot/canon-final-rereview-go.md)   | Closure matrix, reproducible validation evidence, and GO verdict                                                                                                                                      |
+| [Ultron final gate](../reports/native-kanban-sot/ultron-final-go.md)                     | Final requirements, authority, schema, migration, recovery, decomposition, and evidence review GO                                                                                                     |
 
 ## Recommended USC lane partition
 
@@ -34,7 +32,7 @@
 | **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.
+The safe order is KBN-010 → KBN-100 → KBN-105, then coder3 Gateway/MCP server, coder4 CLI/projection, coder5 web, and coder2 recovery can proceed on disjoint files. coder4 then runs pure Coordinator → importer → cutover tooling serially. No two active slices edit the same files.
 
 ## Recovery defaults
 

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

@@ -1,95 +1,14 @@
 # Native Kanban/SOT — Remediated Shared Contract v1
 
-**Status:** CONTROL-PLANE rc.16 KBN-101 current generic storage-wrapper authority 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.16
-**Date:** 2026-07-15
+**Status:** CONTROL-PLANE SI-001 AMENDMENT AUTHORIZED; prior KCR-001–016 independent-review GO retained; rc.4 requires independent schema/SecReview before KBN-100
+**Version:** 1.0.0-rc.4
+**Date:** 2026-07-14
 **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.16 — Current generic storage-wrapper authority closure
-
-- **Current-source truth:** `packages/storage/src/cli.ts` currently shells `storage migrate --run` directly to `pnpm --filter @mosaicstack/db db:migrate` through `execSync`; no `mosaic-db-migrator` executable exists. README and user-guide command guidance therefore remove that command and any runner-delegation claim. The current wrapper is legacy N-1, uncertified, non-operative, and MUST NOT be invoked pending KBN-101-02/-03/-06/-08 activation.
-- **Future-only boundary:** future schema migration remains non-operative and follows external bootstrap → TLS/roles → runner `--run` → runner `--verify` → readiness; tier copy uses only the separately held secure migrate-tier route.
-- **Unmaskable semantic/source-consistency evidence:** before inventory, ownership, or status masking, -06 fails the exact former README commented code-fence generic-wrapper form and exact user-guide executable generic-wrapper form. Its source-consistency test proves the direct-Drizzle `execSync` target and absent runner bin, so any documentation describing current wrapper delegation to the runner fails.
-- **Non-effect:** prior runner, legacy-CI, Compose, production-secret, attestation, pgvector, manifest, lock, TLS, activation, and serial-gate closures remain unchanged.
-
-### 1.0.0-rc.15 — Held runner and legacy-CI authority closure
-
-- **Held runner only:** Current operator documents cannot advertise `mosaic-db-migrator --run|--verify` as executable. The sole passing future form is one `Held future procedure` Markdown section, bounded through its next equal-or-higher heading, that explicitly says non-operative/no-current-command-authority, names KBN-101-00/-03/-05, and preserves external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness. Any runner hit outside that section fails before inventory/ownership/status masking.
-- **PGlite/current-CI boundary:** Fleet backlog current behavior is PGlite-only; PostgreSQL CLI/runner authority remains held until activation. README classifies the checked-in direct `db:migrate` CI job as active legacy N-1, uncertified, non-authorizing as an operator route, and pending KBN-101-06 removal; it is a known direct-DDL exception against an isolated disposable CI database, not approved ordinary behavior. The -06 fixture asserts every required status term and rejects ordinary-authority presentation.
-- **Non-effect:** prior Compose, production-secret, attestation, pgvector, manifest, lock, TLS, activation, and serial-gate closures remain unchanged.
-
-### 1.0.0-rc.14 — Current Compose and production-secret route closure
-
-- **Current developer boundary:** `README.md` and `docs/guides/dev-guide.md` permit only in-process PGlite data-layer work and explicitly selected non-PostgreSQL Compose services. Gateway/Web local start is held because the current unguarded loader can inherit a daemon/project PostgreSQL DSN and reach runtime DDL; KBN-101-02 must reject it before connection. The current PostgreSQL Compose mount is legacy/unqualified; PostgreSQL and federated activation are held until KBN-101-00/-03/-05 and then follow external bootstrap → TLS/roles → runner `--run` → `--verify` → Gateway/Compose readiness.
-- **Production boundary:** `docs/guides/deployment.md` is non-operative until the KBN-101-05 renderer-backed process-exec or `LoadCredential` interface exists. It contains no active production environment-file, monorepo auto-load, credential export/argv, or secret-activation lifecycle route; future units must preserve generation-pinned Vault consumer isolation.
-- **Unmaskable semantic negatives:** -06 fails the exact former README/dev/deployment Compose-first sequences and every production `.env`, `EnvironmentFile=`, credential export/argv, or restart-as-secret-activation fixture before owned/status/normative classification. The held PGlite/non-PostgreSQL route and future ordered activation are the only passing fixtures.
-
-### 1.0.0-rc.13 — Federation-MILESTONES indirect-startup closure
-
-- **Complete operator inventory:** `docs/federation/MILESTONES.md` is exclusively KBN-101-07 and an exact KBN-101-06 `operator-document` `status-only` record. Its former `pgvector extension installed + verified on startup` wording is superseded and forbidden; it authorizes no current DDL, Compose/init, or runtime/startup path.
-- **Unmaskable semantic negative:** before inventory disposition, the scanner fixture proves that exact former wording fails. The only passing status-only sequence is external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway readiness.
-
-### 1.0.0-rc.12 — Deployable importer generation and indirect-DDL-route closure
-
-- **Authenticated generation:** KBN-101-05 owns one canonical Vault KV-v2 importer record, `secret-{env}/mosaic-stack/database/importer` key `url`, with its version taken only from the same successful `data.metadata.version` response. Value plus provider version are one generation, never inferred from DSN bytes. The renderer creates separate immutable `0400` URL/version copies for migrator `10003:10003` binding-only access and importer `10002:10002` access; it uses fsync/atomic generation replacement for Compose and distinct versioned secret/config references for Swarm, so deployment cannot mix generations.
-- **Bounded consumers:** importer alone receives its URL/version, CA at `DATABASE_TLS_CA_CERT_PATH`, pinned public key, and read-only attestation; migrator receives its own migration URL/CA, the URL/version only for no-connect/no-export binding, attestation output, and the root-wrapper-only private key. Safe fd open/fstat/digest/zeroize/close semantics, a privileged producer-only-to-importer-only attestation handoff controller (verify, exact-byte copy, fsync/atomic rename, `10002:10002` `0400` seal, then importer start), no shared writable file, no logging/oracle, provider rotation/revocation, CA/mount, consumer-isolation, and symlink/hardlink/owner/mode/TOCTOU negatives are mandatory.
-- **Indirect-DDL closure:** `docs/federation/SETUP.md` is non-operative until KBN-101 activation and documents only external bootstrap → TLS/roles → runner `--run` → `--verify` → Gateway readiness. The -06 scanner performs unsuppressible semantic checks for automatic first-boot/startup extension/schema/migration language, Compose-up-before-runner, and init-script authority; the former SETUP wording fails and the remediated sequence passes.
-
-### 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)
+### 1.0.0-rc.4 — KBN010-SI-001
 
 - **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.
@@ -100,7 +19,7 @@
 
 ## 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.13 DDL/ledger/TLS/role/attestation/generation 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.
+Concrete contracts are the four `contracts/*.v1.ts` files. PostgreSQL/current-main Drizzle is the sole writable SOT. Public health, Valkey, files, exports, providers, browser state, and outage notes cannot authorize/reconstruct writes. Mechanical Coordinator is non-LLM with no scope/gate/certification/merge authority. Certifier is final independent gate with no merge authority. No feature lane starts until this canon merges and the KBN-010/KBN-105 prerequisites are satisfied.
 
 ## 2. Health proof and exact failures
 
@@ -185,7 +104,7 @@ The candidate key is intentionally redundant with globally unique `missions.id`,
 
 ### 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:
+KBN-100 migration DDL must execute in this order:
 
 1. create `task_events` and its unique `(workspace_id, id)` key;
 2. create `change_proposals` with nullable acceptance-event ID and required submission-event ID;
@@ -324,7 +243,7 @@ KBN-115/coder2 owns `packages/config/src/recovery-posture.ts`, tests, and recove
 
 ## 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.
+Required release evidence includes empty/prod/partial/rollback/N-1 migration tests; cross-workspace and same-workspace wrong-project negatives; active-membership owners/principals; proposal inertness/normal acceptance; exact failure mapping; concurrent monotonic bigint fences; relational lease/checkpoint/evidence mismatch; immutability privileges/RESTRICT; recovery validation/mechanism evidence; endpoint registry alignment; accessible web journeys; author≠reviewer; mandatory SecReview; final Certifier pass/no merge authority.
 
 ### 9.1 SI-001 amendment gate and #757 boundary
 

docs/native-kanban-sot/TASKS.md

@@ -43,14 +43,12 @@ Shared roots, package exports/manifests, lockfiles, and generated artifacts are
 ```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-100 schema + concrete N-1 migration implementation
+          ├─ KBN-105 exact endpoint/DTO/error/registry freeze (SERIAL)
+          │    ├─ KBN-110 domain + Gateway + MCP server implementation
+          │    ├─ KBN-120 CLI/projection implementation [coder4 first]
+          │    └─ KBN-130 web MVP implementation
+          └─ KBN-115 recovery parser/mechanism slice [coder2 lane-serial]
 KBN-110 + KBN-120 + KBN-130 + KBN-115
   -> KBN-140 P1 integration/SIT
       -> KBN-200 pure decision engine [coder4 after KBN-120]
@@ -66,7 +64,7 @@ KBN-310 + KBN-320
       -> 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.
+No consumer implementation begins before KBN-105. No schema work begins before KBN-010 completes. The coder4 order is always KBN-120 → KBN-200 → KBN-300 → KBN-320.
 
 ## 4. P0 — Canon, threat gate, schema, and exact API freeze
 
@@ -93,17 +91,6 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 - **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.16 closes HIGH-1 current generic storage-wrapper authority: README/user-guide remove `storage migrate --run` guidance and false runner delegation; current source is direct-Drizzle, legacy N-1, uncertified, non-operative, and forbidden pending -02/-03/-06/-08 activation. The -06 fixture fails both exact former forms before inventory/status masking and source-consistency rejects current direct-Drizzle wrapper as runner delegation. 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`, paired authenticated provider-version file, and signed `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`; runner-only signing key/public-key isolation; canonical Vault KV-v2 target URL/version, generation-pinned renderer, importer CA/public-key/attestation plus privileged sealed producer-to-importer handoff, safe-fd/consumer-isolation/no-log-oracle, TLS/server/database/role/manifest/schema binding, expiry/replay/provider-rotation/TOCTOU/no-DML controls, and dedicated non-DDL importer; finite exact-path scanner/allowlist/active-route review plus unsuppressible automatic-startup/init/Compose-before-runner semantic negatives 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.15 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/version/attestation files, signing/public-key isolation, canonical Vault KV-v2 authenticated version, generation-pinned renderer, importer CA, safe fd/TOCTOU/consumer-isolation/no-log-oracle, atomic JCS/Ed25519, digest/TLS/server/database/role/manifest/schema binding, expiry/replay/provider rotation/revocation, 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**.
@@ -111,7 +98,7 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 - **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.
+- **Depends on:** **KBN-010 completed**.
 - **Contract surfaces:** `kanban-schema.v1.ts`; SHARED-CONTRACT current-main delta map.
 - **Evidence:** reviewed SQL; empty/prod-shape/partial-resume/rollback tests; N-1 app safety; legacy columns remain declared; workspace/project mismatch negatives; proposal event-FK missing/foreign-workspace tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; SecReview.
 
@@ -122,7 +109,7 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 - **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.
+- **Depends on:** KBN-100.
 - **Contract surfaces:** health/error unions; schema IDs/statuses; Gateway DTO freeze.
 - **Evidence:** every FE/CLI/MCP call maps 1:1 to a route; 503/502-504/409 non-cross-map fixtures; contract digest published.
 
@@ -264,15 +251,13 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 
 ## 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**                    |
+| Wave | coder2                    | coder3                                 | coder4                         | coder5                         |
+| ---- | ------------------------- | -------------------------------------- | ------------------------------ | ------------------------------ |
+| 0    | Wait                      | **KBN-010**                            | Wait                           | Wait                           |
+| 1    | **KBN-100**               | Review constraint implementation       | Wait                           | Wait                           |
+| 2    | **KBN-115** after KBN-100 | **KBN-105** exact freeze, then KBN-110 | **KBN-120** only after KBN-105 | **KBN-130** only after KBN-105 |
+| 3    | Review support            | Finish KBN-110                         | **KBN-200 after KBN-120**      | Finish KBN-130                 |
+| 4    | —                         | **KBN-210 after KBN-200**              | Review/support                 | **KBN-220 after KBN-210 DTOs** |
+| 5    | —                         | P2 remediation                         | **KBN-300 then KBN-320**       | **KBN-310**                    |
 
 Mos alone releases slices and lifts the build hold after independent re-review GO.

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

@@ -1460,11 +1460,12 @@ Add to `packages/db/src/schema.ts` in the `preferences` table definition:
 mutable: boolean('mutable').notNull().default(true),
 ```
 
-### Held future procedure
+Generate and apply:
 
-This historical architecture plan grants **no current command authority**. PostgreSQL execution is non-operative until **KBN-101-00, KBN-101-03, and KBN-101-05** land; do not invoke a PostgreSQL runner from this checkout. After those cards land, the approved future procedure is exactly: external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness. Offline migration artifact generation belongs to its owning implementation card and does not activate PostgreSQL execution.
-
-> **KBN-101 supersession:** `pnpm --filter @mosaicstack/db db:migrate` is superseded and MUST NOT be used. The future runner receives only deployment-injected migration credentials; it accepts no URL, SQL, schema, or role argv.
+```bash
+pnpm --filter @mosaicstack/db db:generate  # generates migration SQL
+pnpm --filter @mosaicstack/db db:migrate   # applies to PG
+```
 
 Platform enforcement keys (seeded with `mutable = false` by gateway `PreferencesService.onModuleInit()`):
 

docs/plans/2026-03-15-wave2-tui-layout-navigation.md

@@ -946,11 +946,13 @@ pnpm --filter @mosaicstack/types typecheck
 
 Expected: All PASS
 
-**Step 2: Manual smoke test (held)**
+**Step 2: Manual smoke test**
 
-This historical TUI smoke test is unavailable until KBN-101-02 supplies a fail-closed Gateway local
-startup route. Do not start current Compose PostgreSQL or infer a local Gateway from PGlite support.
-A future reviewed test must use the correct Mosaic CLI package and an independently verified Gateway.
+```bash
+cd /home/jwoltje/src/mosaic-mono-v1-worktrees/tui-improvements
+docker compose up -d
+pnpm --filter @mosaicstack/cli exec tsx src/cli.ts tui
+```
 
 Verify:
 

docs/reports/compaction-refresh/830-documentation-checklist.md

@@ -1,34 +0,0 @@
-# #830 Documentation Completion Checklist
-
-## Required artifacts
-
-- [x] `docs/PRD.md` contains the M1 compaction-refresh trust-lifecycle requirements and acceptance criteria.
-- [x] Operator behavior and recovery are documented in `docs/guides/lease-broker-operations.md`.
-- [x] Developer architecture and protocol behavior are documented in `docs/architecture/compaction-revocation.md`, `lease-broker-protocol.md`, and `mutator-class-gate.md`.
-- [x] Security boundaries and residuals are documented in `docs/architecture/lease-broker-security.md` and `compaction-revocation.md`.
-- [x] `docs/SITEMAP.md` links the new architecture page.
-- [x] User-guide changes are not applicable: observers are mandatory internal runtime controls with no end-user workflow.
-- [x] OpenAPI/endpoint changes are not applicable: the broker remains an internal Unix-socket protocol, not a public HTTP API.
-
-## Contract coverage
-
-- [x] Claude and Claudex lifecycle signals, matchers, commands, and fail-closed behavior are documented.
-- [x] Pi pre-/post-compaction signals and session replacement reasons are documented.
-- [x] Private generation-file ownership, monotonic update, same-PID replacement, and failure fencing are documented.
-- [x] `revoke_lease` input purpose, broker response state, and denial behavior are documented.
-- [x] T12b/T30 explicitly names the bounded residual stale window and reports within-TTL **ALLOWED** / after-TTL **DENIED**.
-- [x] Documentation explicitly disclaims a within-window mutator-action bound.
-- [x] T-A, T-C, same-principal, and protected-branch boundaries are retained.
-
-## Structure and review
-
-- [x] New architecture content is under `docs/architecture/`.
-- [x] This report is under `docs/reports/compaction-refresh/`.
-- [x] Session evidence is under `docs/scratchpads/`.
-- [x] Documentation changes are in the same logical change set as code and tests.
-- [ ] Independent exact-head code and Opus security reviews pending coordinator sequencing after the deterministic-main rebase gate.
-
-## Publishing
-
-- [x] Canonical documentation remains in-repository.
-- [x] No external publishing target is required for this internal M1 control.

docs/reports/deferred/758-fleet-config-deferrals.md

@@ -1,54 +0,0 @@
-# FCM-M5-001 Fleet Documentation Deferrals and Holds
-
-**Issue:** #758 · **Branch:** `docs/758-fleet-config-operator-docs`
-
-These are accepted existing DAG boundaries, not omissions silently claimed as delivered.
-
-## FCM-M3-002 hold
-
-- Boot/reboot preservation for roster members persisted stopped or disabled.
-- Current installation may enable all agent units, while the launcher projection does not yet carry
-  `lifecycle.enabled` or `desired_state`; documentation therefore does not claim lifecycle-safe reboot.
-- Heartbeat/liveness integration into roster-v2 `status`, `doctor`, and `verify`; current observations
-  cover systemd active state, tmux sessions, holder ownership, and unmanaged sessions only.
-
-## FCM-M4-002 hold
-
-- Executable v1-to-v2 cutover, reversible canary, and rollback.
-- Stale-projection/orphan migration classification and current-host managed/unmanaged fixture coverage.
-- Any live migration, lifecycle, systemd/tmux/session, or rollback action.
-
-M5 docs describe prerequisites and the preview boundary only. A ready preview is not migration or rollback evidence.
-
-## Explicit validate-operation gap
-
-- `FCM-REQ-03` requires a documented programmatic `mosaic fleet validate` operation.
-- The current CLI does not expose that operation. Existing mutation/reconcile validation and the
-  documentation example test are not a replacement for the missing command.
-- FCM-M5-001 documents this implementation gap without inventing syntax, JSON, exit behavior, or an
-  owning implementation card. Parent #758 must remain open until the requirement is implemented and
-  evidenced or the PRD/DAG is explicitly revised through the authoritative process.
-
-## FCM-M5-002 hold
-
-- Deterministic source-versus-installed asset revision detection and safe refresh implementation.
-- Rolling local canary, independent validator certificate, final release evidence, merge-gate approval, and parent #758 closure.
-
-`operations/upgrade-assets.md` is therefore a fail-closed hold, not an invented procedure.
-
-## Compatibility interpretation
-
-The M0 cross-cutting row requiring every retained/migrated artifact to validate through the executable contract is satisfied by each artifact's declared executable disposition, not by forcing versioned v1 fixtures through the v2 parser:
-
-- retained examples are explicit `version: 1` fixtures validated by the production v1 parser;
-- canonical profiles validate through the shared baseline plus `roles.local` resolver;
-- the service preset validates through its production service-policy reader;
-- migration candidates validate through the production v2 compiler and shared semantic resolver.
-
-The executable disposition inventory rejects undeclared additions/removals and prevents silent legacy drift.
-
-## Repository-wide documentation structure
-
-The accepted #758 IA is the domain book under `docs/fleet/`. Creating global `USER-GUIDE`, `ADMIN-GUIDE`, or `DEVELOPER-GUIDE` books and cleaning unrelated pre-existing `docs/` root files are outside this bounded card. The repository sitemap links the fleet book. No HTTP/API/auth contract changed, so OpenAPI and endpoint-index updates are not applicable.
-
-Canonical documentation remains in-repository; no external publishing or generated publishing output is in scope. Parent issue #758 stays open through M5.

docs/reports/documentation/758-fleet-config-ia-closure.md

@@ -1,44 +0,0 @@
-# FCM-M5-001 Fleet Documentation IA Closure Evidence
-
-**Issue:** #758 · **Task:** FCM-M5-001
-
-## Artifact map
-
-- Fleet entry point and desired/observed decision tree: `docs/fleet/README.md`.
-- Concepts: `docs/fleet/concepts/` covers authority/projections, identity separation, role authority/leases, and the generated launch chain.
-- Operator workflows: `docs/fleet/how-to/` covers CRUD, lifecycle, interaction and validator instances, and role overrides.
-- Operations: `docs/fleet/operations/` covers reconciliation/recovery, quarantine, systemd/tmux troubleshooting, backup/restore boundaries, and upgrade-asset holds.
-- References: executable schema, complete field/default/constraint reference, CLI/JSON/exit behavior, lifecycle/status/drift, role authority, and generated environment boundary under `docs/fleet/reference/`.
-- Migration: preview field map, lifecycle preservation, backup/recovery prerequisites, aliases, and executable artifact dispositions under `docs/fleet/migration/`.
-- Navigation: `docs/SITEMAP.md` and the fleet entry point.
-
-## Acceptance mapping
-
-| Checklist area                                   | Evidence                                                                                                                                                                                                             |
-| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Roster authority and fail-closed legacy handling | Root PRD FCM-REQ-01/05/08; desired/observed and quarantine pages.                                                                                                                                                    |
-| Classes and authority                            | Root PRD FCM-REQ-07; role authority concept/reference; configurable interaction/validator how-tos.                                                                                                                   |
-| Lifecycle                                        | Root PRD FCM-REQ-04; lifecycle transition table and operator lifecycle how-to.                                                                                                                                       |
-| Local-only generated launch boundary             | Root PRD FCM-REQ-05/09; generated launch concept/reference.                                                                                                                                                          |
-| Complete DAG and artifact inventory              | `docs/TASKS.md`; M0 inventory; executable disposition tests.                                                                                                                                                         |
-| IA pages                                         | Every path named by the M0 checklist exists and is linked from `docs/fleet/README.md`.                                                                                                                               |
-| Examples                                         | `docs/fleet/examples/roster-v2.yaml` validates through production v2 compiler/shared resolver; shipped artifact dispositions validate through declared production readers.                                           |
-| Links                                            | Deterministic local Markdown link test covers the entire fleet book and sitemap, including local heading-fragment resolution.                                                                                      |
-| Sensitive/example safety                         | Validator scans backtick- and tilde-fenced fleet-book examples plus the canonical roster for sensitive-looking keys, common credential formats (including Anthropic, OpenAI project, and Stripe restricted keys), path-qualified privileged commands, package-manager/root commands, arbitrary command override, and hardcoded Tess/Ultron identities; findings report only file/block and violation kind, never matched values. |
-| Holds                                            | `docs/reports/deferred/758-fleet-config-deferrals.md` records M3-002, M4-002, M5-002, compatibility, and repository-structure boundaries.                                                                            |
-
-## Documentation completion checklist
-
-- [x] Root PRD exists and remains the #758 requirements authority.
-- [ ] The accepted project-specific fleet book is indexed, but it is not complete against `FCM-REQ-03`: the required explicit programmatic `mosaic fleet validate` operation is not implemented. The CLI reference and deferral report record this gap without inventing behavior.
-- [x] Sitemap links the fleet entry point and operator-critical pages.
-- [x] No HTTP/API/auth contract changed; OpenAPI/endpoint rows are not applicable.
-- [x] Working evidence remains under `docs/scratchpads/`; closure and deferral evidence remains under `docs/reports/`.
-- [x] Canonical source remains in-repository; no external publishing action is in scope.
-- [ ] Independent exact-head documentation review, PR CI, and FCM-M5-002 release certificate remain post-PR gates and are not claimed here.
-
-## Live-action boundary
-
-No migration, canary, rollback, deployment, systemd/tmux/session operation, generated projection, or product mutation was performed. `roster.yaml` remains the sole writable desired-state authority. `mos-comms` remains temporary. Parent issue #758 remains open.
-
-Validation command results and exact commit/tree evidence are recorded in the task scratchpad and PR body after execution.

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

@@ -1,109 +0,0 @@
-# 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/scratchpads/755-mos-logical-identity-fencing.md

@@ -1,148 +0,0 @@
-# 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/758-fcm-m1-002-shared-role-resolution.md

@@ -72,46 +72,6 @@ compatibility and canonical collision denial.
 - 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
 

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

@@ -1,37 +0,0 @@
-# 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/758-fcm-m2-002-fleet-agent-crud.md

@@ -1,46 +0,0 @@
-# FCM-M2-002 — Generation-Guarded Fleet Agent CRUD
-
-- **Task / issue:** FCM-M2-002 / #758
-- **Branch / base:** `feat/758-fleet-agent-crud` from `origin/main` `191efaefeb5c0c6bb218c1292d12ce8e73ace12b`
-- **Budget:** 30K card allocation; no deployment or live-fleet actions.
-
-## Objective
-
-Provide local roster-owned create, get, update, and delete mutations with a generation precondition, deterministic dry-run plan, complete-state structural/semantic/projection validation before writes, atomic roster persistence, and redacted recovery output on a late projection failure.
-
-## Scope and exclusions
-
-- Roster v2 is the sole desired-state authority. Reuse `parseRosterV2`, `renderRosterV2Yaml`, `validateRosterV2Semantics`, and the generated-environment boundary.
-- Fresh create defaults to `enabled: true` and `desired_state: stopped`; this card never starts a runtime.
-- Excluded: reconcile/apply; lifecycle/session/systemd/tmux actions; migration/canary; remote/connector/gateway mutation; arbitrary commands/channels/secrets; generated files as authority; `docs/TASKS.md` and orchestration ledger changes.
-
-## Red-first plan
-
-1. Add failing tests for dry-run non-mutation, stale generation, concurrent writer locking, stopped default create, equivalent idempotency, complete proposed-state semantic/boundary validation, atomic roster write, and injected late projection failure with redacted recovery details.
-2. Implement only a roster-v2 CRUD service and file adapter; no legacy `fleet add/remove` behavior expansion.
-3. Add operator/reference docs for JSON outcomes, generation retries, recovery, and no-runtime-action boundary.
-
-## Progress
-
-- Preflight: clean exact base and no duplicate PR confirmed.
-- Intake read: FCM PRD/AC-FCM-03, task row, launch and generated-env boundaries, roster v2/resolver contracts, legacy fleet command behavior, delivery/QA/TypeScript/security/documentation guidance.
-- TDD: RED observed for the missing CRUD module. GREEN: focused suite passes 7 tests covering stopped-default create, stale generation, idempotency, dry-run non-mutation, concurrent lock denial, exact stale/absent generated-projection delete cleanup, and redacted late-projection recovery.
-- REVIEW-1 remediation: RED observed for absent CLI create/get/update/delete/plan wiring. Added roster-v2-only JSON commands, including safe `get`, read-only planning/dry-run, explicit persisted-start recording (never runtime start), stable handled error codes, and focused CLI coverage.
-- REVIEW-2 remediation: RED observed for missing direct fleet-control-plane registration and ambiguous partial late-I/O result. The public surface is now direct `mosaic fleet {create,get,update,delete,plan}` (not root gateway `mosaic agent`); a late filesystem projection failure returns non-zero redacted JSON with `authoritativeRoster: committed` and `projections: incomplete`, proving no rollback/no-op claim.
-- REVIEW-3 remediation: RED observed for unnamed update/delete plans and deleted-agent quarantine conflict. `plan <operation> [name]` now requires target names only for update/delete; delete validates/removes only exact generated state while retaining local/legacy/quarantine/unrelated files. Actual CLI/filesystem tests cover create/update/delete plans, plan validation/non-mutation, retained artifacts/dry-run bytes, unsafe permission/symlink rejection, and post-roster delete recovery. Added the required operator how-to.
-- REVIEW-4 remediation: RED observed that actual Commander create accepted and silently dropped disallowed `command`, `channel`, and `secretRef` keys. The `--agent` object and nested `launch` now use strict own-property allowlists; non-plain/prototype-sensitive shapes and unknown keys fail `invalid-request` before resolver, roster, or projection mutation. Actual Commander plan/create/update tests cover top-level command/channel/secretRef/constructor/prototype/`__proto__` shapes and nested launch unknown fields, byte-identical retained artifacts, non-zero exit, and diagnostics that never echo rejected values. Docs state the same boundary.
-
-## Risks / assumptions
-
-- **ASSUMPTION:** M2 mutations operate exclusively on the existing v2 roster contract because generation/lifecycle fields are v2-only; legacy v1 add/remove commands remain unchanged compatibility paths.
-- A multi-file roster/projection write cannot be one filesystem rename. The roster is authoritative; a post-roster projection failure returns a redacted recovery plan naming only safe paths/actions, never environment values.
-
-## Verification evidence
-
-- `pnpm --filter @mosaicstack/mosaic test -- fleet-agent-crud-command.spec.ts fleet-agent-crud.spec.ts generated-env-boundary.spec.ts` — PASS (48 tests after REVIEW-4 remediation).
-- `pnpm --filter @mosaicstack/mosaic test` — PASS (54 files, 794 tests after REVIEW-4 remediation).
-- `pnpm --filter @mosaicstack/mosaic lint` — PASS.
-- `pnpm --filter @mosaicstack/mosaic typecheck` — PASS.
-- `pnpm format:check` and `git diff --check` — PASS.
-- Root `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, and `git diff --check` — PASS after REVIEW-4 remediation; full package test is 54 files / 794 tests.
-- REVIEW-4 remediation focused checks are green; fresh full-delta independent review is required before author-green. No commit, push, or PR opened.

docs/scratchpads/758-fcm-m3-001-local-reconciler.md

@@ -1,39 +0,0 @@
-# FCM-M3-001 — Local roster-owned reconciliation and lifecycle
-
-- **Task / issue:** FCM-M3-001 / #758
-- **Branch / base:** `feat/758-local-reconciler` from `origin/main` `bc5e73629e92c56a80fa6a769ebad17c0177f504`
-- **Base tree:** `1b9ebe4fa1a90734b6f81118e120bae5290cd350`
-- **Scope:** source, isolated fake-adapter tests, and card documentation only. No live fleet/systemd/tmux action.
-
-## Objective
-
-Provide local roster-v2 `apply`/`reconcile` and lifecycle/status contracts. The roster remains desired-state authority; projections and runtime observations are derived state.
-
-## Red-first evidence
-
-The initial focused reconciler test failed because `fleet-reconciler.ts` did not exist. The initial new-worktree test invocation also exposed absent dependencies; `pnpm install --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store` restored local workspace dependencies without changing source.
-
-## Design
-
-- A new `fleet-reconciler.ts` accepts only typed roster-v2 input plus injected command and projection adapters.
-- It targets only exact `mosaic-agent@<roster-name>.service` units and the exact configured tmux socket/session.
-- It classifies unowned/unmanaged state and fails mutation closed rather than adopting or killing it.
-- It validates the private install-derived holder identity and complete expected tmux global environment before mutating lifecycle state.
-- REVIEW-1 remediation: RED review evidence found service-level apply could omit generation and had no mutation lock. Every non-observational command now requires an expected generation; a private exclusive roster-adjacent lock is acquired before effects and released on success or partial failure. Tests cover missing/stale values, concurrent denial, no effects, release, and lock-free observation.
-- REVIEW-2 remediation: lock acquisition now validates private real `MOSAIC_HOME`/`fleet` ancestors, rejects symlink or unsafe leaves, distinguishes `EEXIST` concurrency from other I/O, and binds release to the created inode plus random ownership token. A replacement lock is retained and reported, not unlinked. A crash may leave a stale lock for inspection; no stale-lock break is claimed.
-- REVIEW-3 remediation: a lock cleanup failure now adds bounded `cleanup` diagnostics to a known successful or partial effect result without replacing its projection/lifecycle/recovery truth. Cleanup is not claimed as complete, and the retained lock requires inspection before retry.
-- REVIEW-4 remediation: command JSON with an additive cleanup diagnostic now exits non-zero even where known effects completed; clean effect and observational JSON remain zero-exit.
-- REVIEW-5 remediation: mutating operations acquire the private lock before rereading canonical `roster.yaml`; the fenced reread, not a caller snapshot, supplies generation validation, plan, projection, and lifecycle authority.
-- `apply` starts only enabled agents whose persisted desired state is `running`; stopped/default agents are never started by reconciliation.
-- Observational commands produce JSON classification only. Partial projection or lifecycle effects report explicit recovery without values.
-
-## Boundaries
-
-Excluded: live host actions, remote/SSH/connector lifecycle mutation, migrations, canaries, deployment, gateway changes, arbitrary command/channel/secret inputs, `docs/TASKS.md`, and orchestration ledgers.
-
-## Verification
-
-- Focused reconciler/Commander/CRUD/fleet tests: 4 files / 229 tests passed.
-- Full `@mosaicstack/mosaic` suite: 56 files / 820 tests passed after REVIEW-5 canonical roster fencing remediation.
-- Package and root typecheck/lint, root format check, and `git diff --check`: passed.
-- Isolated launcher and systemd template harnesses passed; they use fixtures only. No live fleet, systemd, tmux, session, remote, connector, or runtime action occurred.

docs/scratchpads/758-fcm-m3-002-reconciler-lifecycle-gates.md

@@ -1,84 +0,0 @@
-# FCM-M3-002 — Reconciler lifecycle acceptance gates
-
-- **Task / issue:** FCM-M3-002 / mosaicstack/stack#758
-- **Branch:** `test/758-reconciler-lifecycle-gates`
-- **Required starting head:** `499090508ef1d768660e4d54e7934cbcf13cb1cd`
-- **Required starting tree:** `2f1bb7fed48291f3f7ba8b21c2b52491aa14fe2b`
-- **Scope:** isolated acceptance coverage and card-required evidence/tracking only; no live fleet, systemd, tmux, session, site, migration, canary, deployment, runtime, connector, or remote action.
-- **Budget:** use the task estimate of 25K as the working cap; keep the delta to one coherent acceptance suite plus required task/scratchpad evidence. No production change unless a failing reproducer proves an in-scope defect.
-
-## Intake evidence
-
-- Clean exact local branch/head/tree verified before editing.
-- `origin/test/758-reconciler-lifecycle-gates` fetched and verified at the same required head.
-- The Mosaic PR wrapper reported no open pull requests, so no open-PR branch collision exists.
-- Parent issue #758 is open and remains intentionally open through M5.
-- Requirements loaded from `docs/PRD.md` FCM requirements and `AC-FCM-05`, `docs/TASKS.md` FCM DAG, the M3 rows in `docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md`, and the FCM-M3-001 implementation scratchpad.
-
-## Objective
-
-Add broad, behavior-oriented acceptance evidence around the shipped local reconciler contracts. Exercise only injected fake systemd/tmux adapters and temporary filesystem fixtures. Prove exact ownership/targeting, persisted stopped-state safety, truthful partial-failure recovery, rollback behavior, and stable command JSON/exit outcomes without touching live services or sessions.
-
-## Acceptance mapping and evidence
-
-| FCM-M3-002 acceptance concern | Delivered isolated evidence |
-| --- | --- |
-| Systemd/tmux lifecycle | `fleet-reconciler.acceptance.spec.ts` drives apply, reconcile, stop, restart, status, and recovery reconcile through one stateful injected fake host. The fake models exact systemd effects and tmux session observations; no host commands run. |
-| Drift | Canonical roster-v2 YAML drives the Commander `fleet status` boundary and classifies `missing-session`, `unexpected-session`, and `disabled-running`, including combined drift, while asserting observation emits no lifecycle mutation. |
-| Exact default/named socket targeting | Canonical v2 requires an explicit non-empty named socket; the parser rejects missing/empty values and the Commander acceptance path asserts exact `-L mosaic-fleet` targeting. A separate canonical legacy-v1 roster loader plus runtime-transport path proves a socket-less compatibility roster targets the literal tmux default server with no `-L`. No unreachable empty-socket v2 fixture is used. |
-| Unmanaged-session classification | Stateful fixtures report sorted `coder0-shadow`/`unmanaged` sessions, then prove an exact roster stop leaves both sessions and the near-collision service intact. |
-| Crash/partial failure | Injected restart failure is applied after the fake effect to model crash/partial truth: result is `lifecycle: incomplete`, the roster is unchanged, and observed runtime may be active. |
-| Rollback/recovery semantics | M3 has no rollback command and explicitly does not claim automatic rollback. The acceptance workflow proves the bounded recovery contract: inspect, then exact reconcile restores the persisted stopped target without a start or fuzzy effect. M4 migration/canary rollback remains outside this card. |
-| Stopped-state preservation | Stateful apply and reconcile both stop an initially running observed agent whose persisted target is stopped; failed explicit restart leaves desired state stopped; recovery reconcile restores stopped state. No start call is emitted. |
-| Zero fuzzy destructive targeting | Near-collision `coder0-shadow` service/session plus `unmanaged` session remain untouched. The recorded destructive calls contain only exact `mosaic-agent@coder0.service`; no tmux kill action is emitted. |
-| Stable JSON/exit behavior | Temporary canonical roster fixture invokes the CLI boundary and asserts exactly one JSON line, exact partial-result shape, and exit code 1. Existing focused command specs continue to cover clean zero-exit and stable error JSON. |
-| Redacted truthful recovery | Fake stderr includes `PASSWORD=acceptance-secret`; exact CLI JSON contains only bounded recovery metadata and excludes the key, value, and raw diagnostic. |
-
-## Plan
-
-1. Inventory existing reconciler and command specs against the table above; avoid duplicating narrow assertions already present.
-2. Add one acceptance-level spec using only fake/injected adapters and temporary files.
-3. If a real defect is exposed, preserve the failing reproducer and make only the smallest FCM-M3-002-required fix; otherwise leave production unchanged.
-4. Reconcile `docs/TASKS.md` only for delivered M1/M2/M3-001 truth and mark FCM-M3-002 in progress.
-5. Run focused tests, full `@mosaicstack/mosaic` tests, package/root typecheck and lint, Prettier/format and diff checks, plus adversarial fake-runner cases.
-6. Record exact evidence and leave the tree uncommitted for independent synthetic-tree review.
-
-## TDD decision
-
-This card adds acceptance coverage to already-delivered behavior. Test-first applies to any product defect discovered: retain a failing reproducer before an in-scope fix. If the shipped behavior already satisfies the acceptance contract, no production code will be changed and the acceptance suite itself is the deliverable.
-
-## Progress
-
-- Intake and immutable baseline verification complete.
-- Existing coverage inventory confirmed strong unit coverage but no stateful cross-command lifecycle acceptance harness.
-- Added `packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts`: one injected stateful fake systemd/tmux host, temporary canonical v2 and legacy-v1 roster fixtures, and seven acceptance tests.
-- Production source is unchanged; no product defect requiring an FCM-M3-002 fix was found.
-- `docs/TASKS.md` reconciles only merged M1/M2/M3-001 truth and marks FCM-M3-002 in progress.
-
-## Verification evidence
-
-All commands ran from `/home/jarvis/src/mosaic-stack-local-reconciler` and passed unless explicitly noted.
-
-- `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/fleet-reconciler.acceptance.spec.ts` — final remediation run: 1 file, 7 tests passed; canonical v2 named-socket parsing/Commander status, missing/empty v2 rejection, and canonical legacy-v1 default-server runtime targeting are distinct reachable cases.
-- Focused reconciler/roster/transport command covering acceptance, reconciler, command, CRUD, v2 parser, and runtime transport specs — 8 files, 304 tests passed.
-- `pnpm --filter @mosaicstack/mosaic test` — final remediation run: 57 files, 827 tests passed.
-- `pnpm --filter @mosaicstack/mosaic typecheck` — passed.
-- `pnpm --filter @mosaicstack/mosaic lint` — passed.
-- `pnpm typecheck` — 42/42 Turbo tasks successful.
-- `pnpm lint` — 23/23 Turbo tasks successful.
-- `pnpm exec prettier --check docs/TASKS.md docs/scratchpads/758-fcm-m3-002-reconciler-lifecycle-gates.md packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts` — passed.
-- `pnpm format:check` — all matched files use Prettier style.
-- `git diff --check` — passed with no output.
-- Initial scoped Prettier check found style drift in the new spec and tracking table; `pnpm exec prettier --write ...` remediated it before all final gates above.
-- No live fleet, systemctl, tmux, process, site, migration, canary, deploy, runtime, connector, or remote command was invoked.
-
-## Review boundary
-
-This is an author handoff. No self-review is represented as reviewer-of-record. The uncommitted synthetic tree is intended for independent review.
-
-## Risks / blockers
-
-- M3 truthfully reports incomplete lifecycle effects and bounded recovery; it does not implement or claim an automatic rollback command. This suite proves stopped-state restoration by the documented exact recovery reconcile. M4 retains migration/canary rollback ownership.
-- The fake host models only the public systemd/tmux runner contract and temporary roster filesystem boundary. This is intentional under the no-live-effects hold.
-- Parent issue closure, commit, push, PR, merge, deployment, and branch cleanup remain explicit holds.
-- No residual implementation blocker.

docs/scratchpads/758-fcm-m4-001-v1-v2-migrator.md

@@ -1,80 +0,0 @@
-# FCM-M4-001 — v1-to-v2 inventory, preview, and migrator
-
-- **Task / issue:** FCM-M4-001 / mosaicstack/stack#758
-- **Branch / base:** `feat/758-v1-v2-migrator` from `origin/main` `c1aecfabe97a5dc81a72f44910cd4e626f41863f`
-- **Base tree:** `46cdfbcdc1d1ff9c7b8b2b9cf3841086590bf774`
-- **Scope:** field-complete inventory, non-mutating preview, canonical v2 migration output, and migration/recovery disposition evidence. All effects use injected fakes or temporary fixtures.
-- **Budget:** 35K task estimate is the hard working cap. Keep one card/one PR and prefer focused reuse of the v2 compiler, shared role resolver, generated-env boundary, M1 executable disposition inventory, and reconciler observations.
-
-## Objective
-
-Implement preview-first v1 migration that never infers unresolved classes or lifecycle, preserves observed running/stopped state, quarantines forbidden legacy environment inputs with key-name/SHA-256-only diagnostics, inventories remote/connector/schema-only entries without reconciling them, covers every M1-classified shipped artifact, and emits deterministic recovery disposition evidence for the later M4-002 canary/rollback gate.
-
-## Acceptance mapping
-
-1. Field-by-field v1 inventory and no-mutation preview.
-2. Canonical output compiled by `roster-v2.ts` and semantically validated by the existing baseline-plus-`roles.local` resolver.
-3. Only approved deterministic aliases; every other noncanonical class requires an explicit disposition.
-4. Observed stopped/running maps explicitly to persisted lifecycle; stopped observations never produce running targets.
-5. Generated env is regenerated; strict local data is relocated; forbidden keys are quarantine inputs reported only by key name and SHA-256.
-6. Remote/connector/schema-only entries are inventory-only and excluded from local reconciliation output.
-7. Every shipped M1 example/profile/service preset has executable migration disposition evidence.
-8. Deterministic migration/recovery evidence records source, output, exclusions, quarantine, and restore prerequisites without executing a canary or rollback.
-
-## Boundaries
-
-Out of scope: FCM-M4-002 executable canary/rollback and host fixture, #766 communications, #636 commands/channels, live fleet/systemd/tmux/session/migration/deploy/connector/remote/gateway effects, `docs/TASKS.md`, parent issue mutation, commit, push, and PR operations.
-
-## TDD plan
-
-Migration rules and redaction are critical data-mutation/security logic, so tests are written red-first for inventory completeness, explicit class disposition, observed-state preservation, quarantine redaction, inventory-only remote/schema entries, compiler/resolver reuse, artifact coverage, and recovery evidence. Production code follows only after the focused tests fail for the missing behavior.
-
-## Plan
-
-1. Map existing v1 loader, v2 compiler/resolver, env quarantine, reconciler observation, and M1 disposition guard.
-2. Add behavior-oriented failing migration tests with temporary fixtures and injected observation/filesystem adapters only.
-3. Implement the narrow migration module and CLI boundary without a second resolver or live command runner.
-4. Add scoped M4 migration/recovery documentation and executable shipped-artifact evidence.
-5. Run focused tests, full package tests, package/root typecheck and lint, formatting, diff checks, and adversarial redaction/no-effect verification.
-6. Run independent code/security review, remediate findings, reconstruct the synthetic tree using a temporary index, and stop uncommitted.
-
-## Progress
-
-- Collision checks passed: no local/remote branch, worktree, target path, or open PR owned `feat/758-v1-v2-migrator`.
-- Dedicated worktree created at the exact green `origin/main` base.
-- Required global/repository guides and FCM requirements/evidence loaded.
-- No matching migration skill exists under the configured skill directories; no unrelated skill loaded.
-- Added a preview-only CLI and migration module that compile with the existing v2 parser/renderer and validate through the shared persona resolver.
-- Added value-free raw-v1 inventory, strict unknown-field/synonym/duplicate detection, inventory-only remote and connector handling, and explicit class/tool-policy decisions.
-- Added separate reviewed lifecycle observations with only unambiguous running/stopped mappings.
-- Added sanitized, non-mutating environment preflight and recovery evidence explicitly marked non-executable.
-- Added executable disposition evidence derived from the exact 13-entry M1 inventory and operator documentation.
-- Tightened untrusted decisions/observations to reject unknown keys, invalid types/enums, extra local records, and competing automatic-alias dispositions.
-- Remediated independent review findings: v1 runtime/reset defaults are preserved, `~` workdirs expand only at env preflight, malformed/required agent fields fail closed before remote exclusion, and all seven shipped v1 fixtures now execute real previews with explicit evidence.
-- Remediated socket and locality authority blockers: socket-only agents stay local; `host == fleetHost` stays local; only `host != fleetHost` is inventory-only; ssh-only, missing reviewed fleet-host identity, and contradictory host/ssh targets block explicitly without lifecycle omission.
-- Remediated final exact-tree blockers: a declared v1 root socket cannot be overridden; matching/conflicting socket decisions retain reviewed running evidence; canonical ordering uses a shared locale-independent Unicode code-point comparator; migration evidence preserves all four legacy environment dispositions; backup documentation no longer claims validation that M4-001 does not perform.
-- Remediated immutable-review socket-presence blocker: both `socket_name` and `socketName` are field-presence-aware, so explicit empty/default-server declarations remain authoritative and incompatible named decisions block rather than replacing them.
-- Remediated the replacement-tree blockers: the shared v2 compiler and reconciler accept an explicit empty socket as literal default-server identity; present-empty holder session, default/agent work directory, runtime reset command, and alias values block rather than defaulting; missing preview inputs emit one stable blocked JSON object with non-zero status. Snake/camel aliases and whitespace-only input have adversarial coverage.
-- Remediated the subsequent authority blockers: each present-empty CLI path emits exactly one stable blocked JSON object with exit 1 before file reads, and reconciler `start`/`restart` or desired-state `apply`/`reconcile` fail closed before fixed `mosaic-fleet` systemd services can act on a default-server roster.
-- Remediated committed-head review blockers: explicitly declared empty runtime objects use the production v1 `/clear` reset fallback while omitted `pi` retains `/new`; lifecycle observations are sorted by canonical agent name; and bare CLI path flags reach preview validation, emit one stable blocked JSON object with exit 1, and perform zero reads. Built production-CLI subprocess tests cover all three bare flags.
-- Remediated late-audit blockers: the documented M4 guard invokes the 13-artifact validator and all seven v1 previews; canonical `~`/`~/...` workdirs remain unchanged in migration evidence and traversal-free forms expand at the shared production projection boundary while ordinary relative and home-relative traversal paths remain rejected; remote inventory and exclusion evidence sort canonically; and every default-server lifecycle-mutating reconciler path fails before observation, projection preparation/application, or fixed-unit effects. Explicit regressions preserve `plan`, `status`, `doctor`, and `verify` as observational default-server commands.
-- Remediated exact-tree traversal review: `~/../escape` and `~/src/../../escape` remain unexpanded and fail the unchanged shared `unsafe-path` validation. Both the shared generated-environment boundary and the production v1 environment caller have red-first regressions, preventing earlier caller normalization from bypassing the boundary.
-
-## Verification evidence
-
-- Focused migration/compiler/environment/reconciler/CLI: 8 files, 372 tests passed.
-- Documented 13-artifact guard: 1 matching test passed and executed all seven v1 previews.
-- Full `@mosaicstack/mosaic`: 59 files, 902 tests passed.
-- Workspace build: 23 tasks passed.
-- Root typecheck: 42 tasks passed.
-- Root lint: 23 tasks passed.
-- Root format check and `git diff --check`: passed.
-- Built production CLI: canonical `~/src` remains in ready roster/YAML evidence; generated projection preflight succeeds with no blockers; a bare path flag emits one blocked JSON object, exit 1, and no stderr.
-- Independent high-effort late-audit review: no blocker remained in the four assigned repair surfaces; separate exact-tree security audits found no qualifying newly introduced vulnerability.
-- Exact temporary-index synthetic tree includes every tracked changed path; immutable SHA and duplicate reconstruction are recorded in the final handoff.
-
-## Risks / blockers
-
-- M4-001 emits rollback prerequisites/evidence only; executable rollback/canary and the managed/unmanaged host fixture remain owned by M4-002.
-- Remote/connector entries remain inventory-only; later federation or connector reconciliation requires separately reviewed work.
-- Existing environment data is only preflighted. Cutover backup, quarantine write, legacy removal, and generated projection application remain later reviewed effects.

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

@@ -1,183 +0,0 @@
-# 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.
-
-## 2026-07-15 — rc.12 bounded deployable-importer/SETUP remediation plan
-
-- **Objective / scope:** Close the two HIGH findings in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview6-65663d4.md` against exact head `65663d4f72f2ace5148bce9aeba04b5a8d5beee9`. Documentation/tracking only; preserve every earlier closure; do not modify source, deployment, Compose, CI, migration, Vault, or `.mosaic` artifacts.
-- **Plan:** (1) make KBN-101-05 own canonical KV-v2 importer URL/version provenance, separate immutable generation-pinned renderer consumers, importer CA/public-key/attestation mounts, fixed importer/migrator identities, safe-fd lifecycle, isolation/rotation/TOCTOU/error evidence, and -02/-03/-06 handoffs; (2) convert `docs/federation/SETUP.md` to a non-operative N-1 reference with only the required external-bootstrap → TLS/roles → runner `--run` → `--verify` → Gateway-readiness sequence; (3) broaden scanner grammar plus path-specific semantic negatives so indirect first-boot/startup/init/Compose authority cannot be masked by a named, normative, or status record; (4) synchronize PRD/shared/tasks/index/sitemap/federation task state and this scratchpad; (5) run formatting, links, strict contracts, complete-doc scanner/semantic assertions, diff/operator inventory, material/manifest overlap, review, docs-only stage, commit, queue guard, push, and exact remote-SHA verification.
-- **TDD decision:** skipped because this bounded change is documentation-only; the affected -02/-03/-05/-06 implementation tests and scanner semantic fixtures are specified as mandatory future evidence.
-- **Review correction:** independent Codex review found the initial `10003` producer → immutable `10002` importer artifact handoff impossible. rc.12 now specifies the required privileged deployment handoff controller: after runner success it safe-opens/verifies producer artifact plus generation, exact-byte copies/fsyncs/atomically renames to a distinct `10002:10002` `0400` importer mount, seals it read-only, and starts no importer on partial/wrong-generation/owner/mode failure. It receives only a root-owned non-secret expected-version/URL-digest/generation descriptor plus public verifier key, never URL bytes/private key; producer/importer share no writable file or mount. Dry-run nonce consumption now requires fresh `--verify` and artifact before `--yes`; the active-route schema requires `targetCredentialVersionFile`. Pre-existing `.mosaic` state is confirmed excluded from staging.
-- **Validation result:** changed-doc Prettier and `git diff --check` PASS; strict `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; contract/SETUP material and non-operative semantic assertions PASS. Pending final docs-only stage, commit, queue guard, push, and remote-head verification.
-
-## 2026-07-15 — rc.13 MILESTONES semantic-scan remediation intake
-
-- **Objective / scope:** Close only HIGH-1 from `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview7-7365dcf.md` against `7365dcf15c09262a46132b9c011769ad98243641`. Documentation/tracking only: assign `docs/federation/MILESTONES.md` exclusively to KBN-101-07 and its exact former startup-extension wording to the KBN-101-06 semantic fixture/inventory; replace the wording with a non-operative historical/status disposition. No source, deployment, Compose, CI, Vault, migration, provider, or `.mosaic` artifact is authorized.
-- **Frozen remediation:** runtime/startup extension provisioning is superseded and forbidden. The sole eligible sequence is external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway readiness. The MILESTONES record authorizes no current DDL, Compose/init, or startup path. The scanner must prove the exact former wording fails before any inventory/status-only mask and rerun its full current-doc operator/deploy-manifest scan outside reports/scratchpads.
-- **Plan:** update only MILESTONES plus the exact KBN-101 contract/inventory/manifests and necessary PRD/shared/task/index/sitemap/version/status references; run full lexical+semantic scan, Prettier, links, strict contract TypeScript, diff and manifest-overlap checks; stage docs only (excluding pre-existing `.mosaic`), commit, queue-guard, push, and verify the exact remote SHA. No source-code TDD applies because this bounded task changes documentation only.
-- **Remediation result (pre-commit):** `MILESTONES.md` now makes runtime/startup extension provisioning superseded and forbidden, with only external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `--verify` → Gateway readiness; it authorizes no current DDL/Compose/init/startup path. The KBN-101-07 manifest/inventory is exclusive and KBN-101-06 documents the exact former wording as a semantic negative that fails before inventory masking. Full current-doc scan outside reports/scratchpads: 103 Markdown files, 10 lexical-hit paths classified, 2 owned Compose-before-runner references, and zero ownerless indirect/literal routes. Prettier, strict native-kanban TypeScript, local links (64/0), diff check, and 95-path manifest-overlap reconstruction (0 overlaps; MILESTONES only -07) passed. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains excluded.
-- **Delivery checkpoint:** committed remediation as `237bac81c93dc4305470cea23a67e4ced730bd61` (`docs(#771): close MILESTONES startup authority`). Push queue guard returned `state=unknown` without failure; the push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`, all PASS; the remote branch resolved to that exact SHA. This final evidence append is committed next, then the exact remote head is verified and the branch waits for independent exact-head rereview/Ultron reverify. `.mosaic` remains unstaged.
-
-## 2026-07-15 — rc.13 current-document safety remediation intake
-
-- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview8-aeacc70.md` against exact head `aeacc702353740aad0f2f086974cc0670e360d1d`. This is documentation/tracking only. Preserve all prior gates; do not edit source, Compose, deployment artifacts, CI, migrations, Vault data, reports, or `.mosaic`.
-- **Source-backed decision:** Current `docker-compose.yml` mounts `infra/pg-init` into PostgreSQL init and that SQL creates `vector`; it cannot be used as a current PostgreSQL start route before KBN-101 bootstrap/runner artifacts exist. The checked-in configuration declares a supported `local` PGlite tier (`DEFAULT_LOCAL_CONFIG` and `tier-detection` both establish in-process PGlite with no external service probe), so docs may retain a local/PGlite route and start only non-PostgreSQL Compose services such as `valkey`.
-- **Plan:** (1) replace the README and dev-guide Compose-first PostgreSQL instructions with a PGlite/no-PostgreSQL developer path and an explicit held PostgreSQL/federated future activation sequence; (2) replace the deployment quick-start and bare-metal production procedure with non-operative status, no production `.env`/automatic dotenv/`EnvironmentFile`/credential export-or-argv/restart guidance, and only a non-executable future renderer/Vault generation-pinned process-exec or `LoadCredential` schematic; (3) expand KBN-101-06/-07 semantic fixture/disposition language to fail the exact former README/dev/deployment Compose-first sequences and production credential routes before ownership/status masking; (4) synchronize PRD/shared/tasks/index/sitemap/status/version and this scratchpad; (5) run formatting, links, strict contract TypeScript, full current-doc lexical+semantic scan outside reports/scratchpads, manifest-overlap, review, docs-only stage, commit, queue guard, push, and exact remote-SHA verification.
-- **TDD decision:** no source or fixture implementation may be changed in this documentation-only remediation. The -06 future fixture requirements are frozen as acceptance evidence; validation here is static semantic inventory plus documentation quality gates.
-- **Correction from independent review:** The initial local-Gateway PGlite wording was unsafe. `apps/gateway/src/main.ts` loads daemon/root/app-local environment files before tier selection; an inherited daemon `DATABASE_URL` can select PostgreSQL, whose current startup reaches extension creation and migrations. No source is authorized in this docs-only task. The remediation therefore holds Gateway/Web local startup, preserves only PGlite data-layer plus selected non-PostgreSQL Compose work, and assigns KBN-101-02 the fail-closed daemon/inherited/root/app-local DSN and non-local-tier rejection before connection/DDL, with a regression proof. The future renderer boundary remains KBN-101-05.
-- **Remediation evidence:** Removed active PostgreSQL Compose-first and production credential guidance from README, CLAUDE, dev/deployment, and the residual historical TUI/MCP routes; local documentation now permits only PGlite data-layer/non-PostgreSQL Valkey work while Gateway/Web startup is explicitly held. KBN-101-06/-07 now freeze exact former README/dev/deployment Compose sequences plus production credential patterns as pre-classification semantic negatives. Independent review surfaced the current daemon/root/app dotenv loader as an unsafe source boundary; no source is authorized here, so the docs hold that startup and assign fail-closed removal/regression proof to KBN-101-02.
-- **Validation:** Prettier PASS (12 changed docs); local-link resolver PASS (71 links); `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; full README/CLAUDE/docs inventory PASS (104 documents, 0 active non-normative Compose/init/production-credential violations); manifest reconstruction PASS (10 cards, 95 declared path tokens, 0 overlaps); `git diff --check` PASS. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains intentionally unstaged.
-- **Final route correction:** Held the residual MCP environment/restart and historical TUI smoke-test routes after review showed they could bypass the Gateway local-start hold; no bearer-token-over-HTTP or Gateway restart route remains in this remediation scope.
-- **Delivery:** committed `7cc156b777189ee89448e4d569a8b3f69560a240` (`docs(#771): hold unsafe database startup routes`) and `d8f935c20ade835aa3ec03fe5d6961885d8b5f0b` (`docs(#771): record final route correction`). Push queue guard returned `state=unknown` without failure; both pushes completed and the remote matched `d8f935c` before this final delivery-evidence append. `.mosaic/orchestrator/{mission.json,session.lock}` remains pre-existing and unstaged. Await a fresh independent exact-head re-review/Ultron verification.
-
-## 2026-07-15 — rc.15 exact one-finding runner/legacy-CI remediation intake
-
-- **Objective / scope:** Close only HIGH-1 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview9-be0ebfd.md` against `be0ebfdc6a2b32a0ab6989117ebbb12f43854d71`. Documentation/tracking only: no source, Compose, CI, deployment, migration, Vault, reports, or `.mosaic` edit.
-- **Plan:** Replace imperative current runner routes in the architecture plan and PERFORMANCE with one explicit non-operative future procedure; make fleet backlog current behavior PGlite-only and PostgreSQL held; classify README's checked-in direct CI `db:migrate` as legacy N-1/uncertified/non-authorizing pending KBN-101-06 removal; then extend the future KBN-101-06 lexical/semantic inventory contract so unqualified runner/current-CI authority fails before masking while only the complete named held procedure passes. Synchronize required contract/PRD/shared/task/index/sitemap state, run full docs scan and document gates, stage docs only, commit, queue-guard, push, and verify remote SHA.
-- **TDD decision:** not applicable: the user authorizes documentation only and the named -06 fixture/inventory files do not yet exist; the contract records their required future implementation evidence.
-- **Remediation / review closure:** Architecture, PERFORMANCE, federation SETUP/MILESTONES, deployment/dev/migrate-tier, and README now use one Markdown-bounded `Held future procedure` form where needed: non-operative/no-current-command-authority; KBN-101-00/-03/-05; external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness. Any runner hit outside that section is a -06 semantic failure. Fleet backlog current behavior is PGlite-only. README accurately records the checked-in direct CI migration as an active, isolated-disposable-database, uncertified legacy N-1 DDL exception that is non-authorizing as an operator route and pending -06 removal; it no longer falsely claims the current CI role lacks DDL capability. Independent Codex review found and this pass closed the readiness-endpoint, standalone-verify, CI-factuality, and scanner-boundary findings. Its only residual finding concerns pre-existing tracked `.mosaic/orchestrator` runtime state, which is explicitly excluded and unstaged by task scope; security review found no vulnerability.
-- **Validation:** changed-doc Prettier PASS; `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; changed-doc local links 72/0; `git diff --check` PASS; full README/CLAUDE/docs lexical+semantic scan outside reports/scratchpads PASS (106 Markdown documents; 7 operator documents with runner tokens; zero unqualified future-runner/current-CI authority routes); KBN-101 manifest check PASS (10 dependency-ordered cards; -07 docs/-06 fixtures disjoint); docs-only allowlist PASS (16 docs, pre-existing `.mosaic` excluded).
-- **Delivery evidence:** committed `d857463a8a4658e34a77177737860cf82cc26ac6` (`docs(#771): hold unimplemented runner routes`). Pre-push queue guard returned `state=unknown` without failure; the push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`, all PASS. Push succeeded and `origin/docs/771-kbn101-db-role-split` matched `d857463a8a4658e34a77177737860cf82cc26ac6`. This evidence append is committed and pushed next; `.mosaic/orchestrator/{mission.json,session.lock}` stays pre-existing, unstaged, and excluded. Await exact-head independent re-review/Ultron reverify.
-
-## 2026-07-15 — rc.16 exact one-finding generic-wrapper remediation intake
-
-- **Objective / scope:** Close only HIGH-1 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview10-18e253c.md` against exact head `18e253c8790bdbb5bc30a06c116472213b83b22f`. Documentation/tracking only: no source, Compose, CI, deployment, migration, Vault, report, or `.mosaic` change.
-- **Source-backed correction:** `packages/storage/src/cli.ts` currently labels `storage migrate` a thin wrapper for `pnpm --filter @mosaicstack/db db:migrate` and executes that direct Drizzle command with `execSync`; no `mosaic-db-migrator` executable exists. Therefore the README commented form and user-guide executable form must not describe runner delegation or provide current command authority.
-- **Plan:** Remove the current wrapper command from README/user-guide command guidance; record it as legacy N-1, uncertified, non-operative, and forbidden pending KBN-101-02/-03/-06/-08 activation. Retain only the held future ordered bootstrap → TLS/roles → runner `--run` → `--verify` → readiness sequence and the separately held secure migrate-tier route. Extend KBN-101-06's future semantic fixture/matrix with both exact former forms (including the README commented code-fence form), requiring their failure before inventory/status masking and a source-consistency assertion that direct Drizzle wrapper source cannot be described as runner delegation. Synchronize status/version references only where required, then run document gates, stage docs only, commit, queue-guard, push, and verify the remote SHA.
-- **TDD decision:** not applicable: this bounded task changes documentation only; the required future -06 semantic/source-consistency fixtures are specified as implementation acceptance evidence.
-- **Remediation / validation:** README and user-guide remove the generic wrapper from command guidance and state the direct-Drizzle current-source truth, legacy-N-1/uncertified/non-operative MUST-NOT-INVOKE boundary, named -02/-03/-06/-08 activation cards, future external-bootstrap → TLS/roles → runner `--run` → `--verify` → readiness sequence, and separately held secure migrate-tier route. The KBN-101 rc.16 contract records both exact former forms (README commented code fence and user-guide executable code fence), requires failure before inventory/ownership/status masking, and requires the direct-Drizzle/no-runner-bin source-consistency proof. Prettier passed on all nine changed Markdown documents; changed-doc local links passed (72/0); strict native-kanban contract TypeScript and `git diff --check` passed; full README/CLAUDE/docs scan outside reports/scratchpads passed (106 documents, zero non-normative executable generic-wrapper or false runner-delegation route); and manifest validation passed (10 cards, 90 exact tokens, zero overlaps). Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains excluded.

docs/scratchpads/791-upgrade-config-protection.md

@@ -1,529 +0,0 @@
-# Scratchpad — #791 Upgrade config protection (ms-791 worker lane)
-
-**Lane:** web1:ms-791 → reports to MS-LEAD (web1:mosaic-100). Do NOT contact Jason/Mos directly.
-**Worktree:** `/home/hermes/agent-work/stack-agents-dir-791`, branch `feat/791-upgrade-config-protection`
-off `origin/main` `9745bc3f` (verified exact head).
-
-## Mission prompt (verbatim intent)
-Protect operator-owned config under `~/.config/mosaic` from framework-upgrade wipes. Ratified
-combination (Mos-approved, do NOT re-litigate): (b) strict ownership separation [PRIMARY] + (a)
-transactional pre-update snapshot [safety net] + (d) regeneration-from-SSOT [recovery]. (c) periodic
-timer DEFERRED. HARD GATE: unit test that an upgrade run touches NO path outside the manifest.
-Design-first: write design doc, send to MS-LEAD, WAIT for confirmation before impl.
-
-## Session 1 (2026-07-16) — Phase 1 design
-
-### Evidence gathered (wipe mechanism, file/line)
-- `mosaic update` → `update-checker.ts:509` `buildReseedCommand` → `bash install.sh`
-  (`MOSAIC_SYNC_ONLY=1`, `MOSAIC_INSTALL_MODE=keep`).
-- Wipe = `packages/mosaic/framework/install.sh:199` `rsync -a --delete` + `PRESERVE_PATHS` denylist
-  (`install.sh:47`). cp-fallback `install.sh:223` `find ... -exec rm -rf`.
-- Denylist gaps → WIPED: `agents/*.conf`, `policy/*.md`, `*.local.md`, harvester/SOP,
-  `tools/_lib/credentials.json`.
-- Stale comment `update-checker.ts:492` claims `*.local` preserved — PRESERVE_PATHS has no such entry.
-- TS path `file-adapter.ts:157` → `file-ops.ts:66` `syncDirectory` = non-destructive copy-overlay, BUT
-  its preserve list (`file-adapter.ts:164`) already DRIFTED from install.sh (missing `fleet/backlog`,
-  `fleet/roles.local`). Evidence for single shared manifest SSOT.
-- Existing snapshot (`install.sh:76`) = /tmp, crash-trap only, deleted on success → inadequate; no
-  `mosaic restore`.
-- `fleet-reconciler.ts:93,234` already has `regenerate-projections-from-roster` phase separate from
-  lifecycle → `mosaic fleet regen` = thin projection-only wrapper (no restart), no FCM-M4/M5 preemption.
-
-### Design decisions
-- **(b)** Invert to allow-list: shared `framework/framework-manifest.json` (framework globs +
-  operatorReserved carve-outs); resolve per-path, deny-wins; **UNKNOWN ⇒ operator (fail-safe)**.
-  Mechanism: drop `--delete`; non-deleting bulk copy + explicit manifest-scoped prune pass (iterate
-  framework globs only → operator/unknown structurally unreachable). Pure prune-planner fn for tests.
-- **(a)** Snapshot to `~/.local/state/mosaic/backups/pre-update-<ts>/` 0700/0600, retention N=5,
-  post-sync verify+restore, `mosaic restore --list/--from`. No secret values in output.
-- **(d)** `mosaic fleet regen` projection-only, preview-first, never restart.
-- HARD GATE test includes a deliberately-unanticipated operator path to prove fail-safe default.
-- **PR split:** PR1 manifest+guard (root fix, ships alone) → PR2 snapshot/restore (secrev) → PR3
-  regen+docs. PR2/PR3 depend on PR1.
-
-### Status
-Design doc written: `docs/design/791-upgrade-config-protection.md`. Sent to MS-LEAD.
-
-## Session 1 (cont.) — MS-LEAD CONFIRMED → Phase 2 GO
-All 4 asks approved. Binding conditions:
-- TDD tests-first, red-first proof per PR; ≥85% new-code; co-located `*.spec.ts`; never `--no-verify`.
-- HARD GATE test (§2.4, unanticipated sentinel survives byte-identical + mtime unchanged) = MERGE-BLOCKING for PR1.
-- Manifest-completeness test (§6.2) required.
-- Bash+TS read ONE shared `framework-manifest.json`; parity test (§6.1) required (closes #631 drift class).
-- UNKNOWN⇒operator (rule 3) non-negotiable. Keep prune-planner PURE.
-- `fleet regen`: NEVER restart; dry-run default, `--write` to apply; "never issues restart" test mandatory.
-- Independent review every PR; PR2 dedicated secrev.
-- One PR at a time through DAG. Report PR1 exact head + red→green evidence for review commission.
-
-### Now: implementing PR1 (manifest + resolver + non-deleting sync + scoped prune + guard tests).
-
-## Session 2 (2026-07-16) — PR1 built, tests-first, red→green proven
-
-Deviation noted to MS-LEAD in PR: manifest is `framework-manifest.txt` (line-oriented), NOT `.json`.
-Rationale: keep the bash installer free of a python3/jq dependency. The "ONE shared file, parity-
-tested" requirement is honored — `manifest-parity.spec.ts` drives the bash resolver as a subprocess
-and asserts byte-identical ownership vs the TS resolver over 34 probe paths spanning every class.
-
-### PR1 artifacts
-- SSOT: `packages/mosaic/framework/framework-manifest.txt` ([framework]/[operator], deny-wins, fail-safe).
-- TS resolver: `src/framework/manifest.ts` (pure: parse/matchGlob/resolveOwnership/frameworkSubtreeRoots/
-  planPrune) + `manifest.spec.ts` (18 tests incl. planPrune property test + §6.2 completeness).
-- Bash resolver: `framework/tools/_lib/manifest.sh` (compiled globs → fork-free `manifest_is_framework`;
-  CLI `resolve|subtree-roots|classify`). Sourced by install.sh.
-- HARD GATE (§2.4): `framework/tools/quality/scripts/test-upgrade-manifest-guard.sh` — keep-mode reseed,
-  10 operator sentinels (incl. unanticipated `unknown-operator-dir/x`, `harvester/sop.md`,
-  `fleet/my-fleet.yaml`) survive byte-identical + mtime-unchanged; retired framework file pruned;
-  secret value absent from output. RED=31 fail (orig install.sh) → GREEN=48 pass (fixed).
-- install.sh: keep mode now manifest-driven (`sync_framework_keep`, no `--delete`); overwrite unchanged.
-  PRESERVE_PATHS denylist deleted.
-- TS sync: `file-ops.syncDirectory` gains `isOperatorOwned` guard; `file-adapter.syncFramework` derives
-  it from `loadManifest` — hardcoded (drifted) preservePaths deleted. Fixture uses the REAL manifest.
-- Parity: `manifest-parity.spec.ts` (§6.1) — bash↔TS agree on 34 paths + subtree roots.
-- Migration matrix `test-install-migration.sh`: F6 flipped — `my-fleet.yaml` now MUST survive (fail-safe).
-- CI: new merge-blocking `upgrade-guard` step (`.woodpecker/ci.yml`) runs both bash suites (adds rsync).
-- update-checker.ts reseed comment corrected to the manifest model.
-
-### Gates (all green)
-- `pnpm typecheck` ✓ · `pnpm lint` ✓ · `pnpm format:check` ✓
-- Full mosaic vitest: 1062 passed (cli-smoke needs `pnpm build` first — build-artifact dep, not this change).
-- HARD GATE 48/48 · migration 21/21 · parity 3/3 · manifest 18/18 · file-adapter 8/8.
-
-### PR opened + reported (2026-07-16)
-- **PR #802** http://git.mosaicstack.dev/mosaicstack/stack/pulls/802 — base `main`@`9745bc3f`,
-  head `34e55d4a` (commit `feat(mosaic): manifest-owned upgrade guard…`). 15 files, +1160/-142.
-- Reported PR head + red→green evidence to MS-LEAD (web1:mosaic-100); queued (lead busy).
-  Standing by for the independent-review commission at head `34e55d4a`.
-- **TWO items flagged to MS-LEAD for decision (awaiting reply):**
-  1. Deviation `.txt` vs `.json` — confirm accept (parity-tested) or convert to `.json`+jq.
-  2. `pr-create -i 791` appended `Fixes #791` → would auto-close the tracking issue on PR1 merge
-     while PR2/PR3 remain. Recommended edit to `Part of #791`; awaiting go-ahead to patch PR body.
-- DO NOT start PR2/PR3 until PR1 merges (DAG; one PR at a time).
-
-### MS-LEAD ruling → #797 ledger-survival sentinel folded into PR1 (2026-07-16)
-MS-LEAD ruled both my decisions: (1) `.txt` format ACCEPTED (parity must be strict/merge-blocking incl.
-format edge cases + negative probe); (2) trailer `Fixes #791`→`Part of #791` APPROVED (patched PR #802
-body via Gitea API — tracking issue no longer auto-closes on PR1 merge). Plus Mos-ELEVATED merge-blocker
-(spec `~/agent-work/planning/epic-796/791-ledger-survival-sentinel-SPEC.md`): #797 Runtime Session Ledger
-must survive upgrade. Two coupled deliverables landed in PR1:
-- (i) Carve-out: `fleet/run/**` was ALREADY an explicit `[operator]` entry — glob matches the spec's
-  pinned `fleet/run/**` EXACTLY, so NO divergence to route back to planner-opus. Strengthened its comment
-  to name the ledger (`fleet/run/sessions/` events.ndjson + ledger.json) so it is unmistakably load-bearing.
-- (ii) HARD-GATE sentinel: seeded populated ledger (events.ndjson 3 events + ledger.json node+edge+gen,
-  0600 under 0700) into test-upgrade-manifest-guard.sh sentinels; asserts byte-identical + mtime-unchanged
-  + dir-perms unchanged. Negative control (retired framework file IS pruned) relabeled explicitly.
-  HARD GATE now 58/58 (was 48).
-- Decision-1 parity hardening: format-edge fixtures (comments/blanks/whitespace, duplicate+overlapping
-  globs deny-wins, section/glob-ordering independence) + explicit UNKNOWN→operator negative probe, driven
-  through BOTH resolvers via MANIFEST_FILE override. Parity 7/7 (was 3).
-- RED-FIRST honesty note: the bash ledger sentinel stays GREEN even against the pre-fix installer (the
-  ledger was incidentally safe from the rsync --delete bug; overall pre-fix run 30/58 as expected). The
-  carve-out's TRUE load-bearing value (deny-wins if framework ownership ever broadens to `fleet/**`) is
-  isolated by a dedicated resolver-seam red→green in manifest.spec.ts: WITHOUT `fleet/run/**` operator
-  entry + hypothetical `fleet/**` framework → ledger resolves framework and planPrune DELETES it (RED);
-  WITH the carve-out → deny-wins → operator, unprunable (GREEN). manifest.spec.ts 21/21 (was 18).
-- Gates all green: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1069 passed · HARD GATE 58/58
-  · migration 21/21. Committing FORWARD on the branch (NOT rebasing 34e55d4a out from under review).
-
-### MS-LEAD REQUEST CHANGES @ 0a5e703a → B1/B2/B3 fixed red-first (2026-07-16)
-MS-LEAD returned REQUEST CHANGES (routed merge-blockers satisfied; 2 CRITICAL reliability defects from
-the commissioned independent review). Fixed forward on the branch, red-first:
-- **B1 (CRITICAL) — dead ERR trap.** install.sh had `set -euo pipefail` (no `-E`), so the
-  `trap restore_snapshot ERR` never fired for a failure inside sync_framework_keep() (function body) —
-  a mid-sync abort left a half-written target with NO rollback. Fix: `set -Eeuo pipefail` (errtrace) +
-  disarm the trap at the top of restore_snapshot() to prevent re-entrancy. New gate
-  `test-upgrade-rollback.sh`: injects a mid-sync `cp` EACCES (read-only divergent framework file);
-  Part A asserts the shipped installer rolls back (restore message fires AND target byte-identical to
-  pre-upgrade); Part B control strips `-E` and asserts the rollback message does NOT fire (dead trap) —
-  self-verifying red→green. 7/7.
-- **B2/B3 (CRITICAL) — empty/unreadable/malformed manifest divergence.** Pre-fix: TS `parseManifest('')`
-  returned `{framework:[],operator:[]}` (NO throw) → silent no-op "Installation complete"; bash aborted
-  fragilely (the `_manifest_compile` `"${MANIFEST_OPERATOR[@]:-}"` artifact returned 1 with no message)
-  AND the CLI dispatch swallowed manifest_load's rc (no `|| exit`) so `resolve` exited 0 resolving
-  everything operator. Fix (fail-loud + identical both langs):
-  * TS `parseManifest`: throw on zero framework entries; `loadManifest`: wrap read error →
-    "Cannot read framework manifest …".
-  * bash `manifest_load`: explicit unreadable guard (`[[ ! -r ]]`) + zero-`[framework]` guard, both loud
-    stderr + return 1; `_manifest_compile` gets explicit `return 0` (kills the empty-array artifact);
-    CLI dispatch `manifest_load … || exit 1`.
-  * `finalize.ts`: wrap syncFramework → `spin.stop('Framework sync aborted …')` + rethrow (never falls
-    through to "Installation complete").
-  Tests: manifest.spec.ts +5 fail-closed (empty/comment-only/operator-only/empty-section/missing);
-  manifest-parity.spec.ts +7 failure-mode parity (both reject empty/comment-only/operator-only/
-  empty-section/entry-before-header/unknown-header/missing — TS throws, bash CLI exits non-zero+stderr);
-  HARD GATE +4 end-to-end fail-closed matrices (empty/operator-only/malformed/missing → abort non-zero,
-  manifest error surfaced, every operator sentinel byte-identical). RED proven by reverting
-  manifest.ts+manifest.sh to HEAD → 12 new tests fail; restore → 40/40 green.
-- **Non-blocking addressed.** MEDIUM install.sh:222 find-empty now warns on a real failure instead of
-  blanket `|| true`. LOW: corrected the "both destructive paths rsync vs cp" overstatement in the HARD
-  GATE header + cp-fallback comment + ci.yml (keep mode is a single cp-based path; the rsync-present vs
-  -absent runs prove rsync-independence). `.pre-constitution.bak` triage: single-shot backup is
-  intentional (reconcile_framework_files backs up once), no change.
-- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1081 passed (was 1069, +12) · HARD GATE
-  118/118 (was 58) · rollback 7/7 (new) · migration 21/21. No --no-verify. Rollback test wired into
-  ci.yml upgrade-guard. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
-
-### Codex round 2 (pre-push self-review) → blockers A/B + should-fix C fixed red-first (2026-07-16)
-Before committing round 1 I re-ran codex on the change set; it surfaced two fresh reliability defects
-and one messaging defect on the SAME rollback/manifest path. Fixed forward, red-first:
-- **Blocker-A (CRITICAL) — signal trap resumed instead of terminating.** A bash INT/TERM handler that
-  merely `restore_snapshot` (returns) does NOT terminate the script — execution RESUMES past the
-  interrupt, cleans the snapshot and reports success, leaving a partial post-interrupt update. Fix:
-  `trap 'restore_snapshot; exit 1' ERR INT TERM` so both the errtrace (ERR) and signal (INT/TERM) paths
-  exit non-zero. Rollback test Part C: a `cp` shim that `kill -TERM $PPID` mid-sync then succeeds (so
-  set -e never fires and only the signal path governs) → asserts abort non-zero + restore fires + does
-  NOT print "file phase complete"; control strips `exit 1` and asserts the buggy resume-to-success.
-- **Blocker-B (CRITICAL) — degenerate `[framework]` section resolved everything operator.** A manifest
-  whose framework entries are all empty / bare-dot (`/`, `./`, `.`, `..`) passed the non-empty guard yet
-  yielded zero usable globs → nothing is framework → a keep-mode sync silently no-ops (bash resolved
-  `operator`, exit 0). Fix (both langs, parity): reject when no entry has a char other than `/`/`.` —
-  TS `isUsableFrameworkGlob` = `/[^/.]/.test(normalizeRel(glob))`, throws `ManifestError`; bash mirror
-  loops `[[ "$(_manifest_norm "$_g")" =~ [^/.] ]]`, loud stderr + return 1. Tests: manifest.spec.ts
-  `it.each(['/','./','.','..','/\n./'])` throw; parity +3 `expectBothReject` (root-slash/dot-slash/
-  bare-dot). RED: reverting the guard makes `[framework]\n/` resolve `operator` exit 0.
-- **Should-fix-C — misleading abort message.** finalize.ts printed one generic "may be partially
-  applied" for every sync failure. A `ManifestError` is a PRE-sync validation abort (manifest is
-  validated before any copy) → nothing was written; conflating it with a mid-copy failure misdirects
-  recovery. Fix: introduce `ManifestError` (exported from manifest.ts, thrown by every fail-closed
-  parse/load path), and classify in finalize.ts — ManifestError → "no files were changed"; any other →
-  "may be partially applied". New co-located `finalize-sync-abort.spec.ts` (3 tests) asserts both
-  branches re-throw the original error + the correct message, and that config writes are never reached.
-  RED proven by collapsing the classification → the ManifestError test fails.
-- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 (was 1081, +3 finalize-abort;
-  manifest specs already counted) · HARD GATE 193/193 · rollback 14/14 · migration 21/21.
-
-### Codex round 3 (pre-push self-review) → blockers D1/D2 fixed red-first (2026-07-16)
-Re-ran codex again; it found two more rollback-path gaps `set -E` cannot catch. Fixed forward, red-first:
-- **Blocker-D1 (CRITICAL) — `find` scan failures swallowed by process substitution.** Both the overlay
-  copy and the scoped prune consumed `< <(find … -print0)`. Bash does NOT propagate the producer's exit
-  status to the `while`, so an EACCES/I/O failure mid-scan truncates the file list yet leaves the loop
-  exiting 0 → a partial upgrade commits and reports success; the ERR/restore trap never fires. Fix:
-  `_scan_or_die` runs `find … -print0 > "$tmp"` to completion, checks its status, and returns non-zero
-  (→ ERR trap → restore) on failure; both loops now read from the checked temp file. Rollback test
-  Part D: a `find` shim that fails every `-print0` scan → shipped installer aborts non-zero + restores +
-  emits "Could not enumerate framework files" + target byte-identical; control neuters the `# D1-GUARD`
-  `return 1` → find failure swallowed, upgrade wrongly reports "file phase complete", no rollback.
-- **Blocker-D2 (CRITICAL) — silent `set -e` exit on a failed target reset.** restore_snapshot did a bare
-  `rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"` (trap disarmed, under set -e). If `rm`/`mkdir` fails —
-  possibly after `rm` deleted part of the target — the script exits immediately, skipping the cp AND the
-  recovery pointer, leaving a half-removed target and an orphaned snapshot the operator can't locate.
-  Fix: `if ! rm -rf … || ! mkdir -p …; then fail "Snapshot restore could not reset … preserved at:
-  $SNAPSHOT_DIR — copy it back …"; return 1; fi` (tested like the cp -a check; snapshot NOT deleted).
-  Rollback test Part E: cp-poison triggers restore + an `rm` shim fails `rm -rf <TARGET>` → shipped
-  emits the recovery pointer, the named snapshot dir survives, secret value never leaked; control deletes
-  the recovery line → operator gets no pointer. RED: reverting D1+D2 → 7 shipped/control assertions fail.
-- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 · HARD GATE 193/193 ·
-  rollback 28/28 (was 14, +14 for D1/D2 with controls) · migration 21/21. shellcheck clean on new lines.
-  No --no-verify. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
-
-## Session 3 (2026-07-16) — PR1 MERGED, starting PR2 (durable snapshot + restore + secrev)
-PR1 (#802) squash-merged → main `32a0ffba`; issue #791 stays open (3-PR DAG umbrella). Independent Opus
-adversarial/security review APPROVED at head `af627e75` (Gitea RoR cmt 17892); lead ran rollback 28/28 +
-HARD GATE 193/193 green; CI #1877 green. PR2 UNBLOCKED.
-
-PR2 branch: `feat/791-pr2-snapshot-restore` off `origin/main` 32a0ffba. Same treatment applies:
-tests-first red-first, independent review + durable Gitea Reviewer-of-Record comment BEFORE MS-LEAD runs
-the queue guard/merge. Report PR2 number + exact head when ready. PR body: `Part of #791` (NOT Fixes).
-
-### PR2 scope (ratified §3/§5 of design doc, Mos-approved — do NOT re-litigate)
-- **(a) Durable pre-update snapshot** to `${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-ts>/`
-  — OUTSIDE ~/.config/mosaic and any repo. Perms dir 0700 / files 0600 (umask 077 + explicit chmod).
-  Scope = operator-owned surface that EXISTS (operatorReserved paths), not the framework tree. Taken
-  BEFORE any mutation. Retention N=5 (`MOSAIC_BACKUP_RETENTION`), prune older.
-- **Post-sync verify + selective restore**: diff operator surface vs snapshot; (b) should never touch
-  operator paths, so ANY diff = manifest bug → restore affected paths + warn loudly. (a) catches a (b) miss.
-- **`mosaic restore`** (TS CLI): `--list` (default, dry-run) enumerates snapshots by ts; `--from <ts>`
-  restores over operator surface, confirmation-gated. Counts/paths only.
-- **Secret-safety (secrev)**: snapshot/restore NEVER emit file contents; only paths/counts. Tests assert
-  0700/0600 AND that a secret value seeded in tools/_lib/credentials.json never appears in any output.
-
-### PR2 implementation status (2026-07-16, ready-for-review)
-All three tasks implemented, red-first proven, unit-green:
-- **Task #10 — durable snapshot (install.sh)**: `backup_root()`/`enumerate_operator_files()`/
-  `prune_durable_snapshots()`/`make_durable_snapshot()` wired into keep-mode main() after `manifest_load`,
-  before any mutation. umask 077 + explicit chmod 700/600. UTC ts, collision suffix. FAIL-OPEN (a backup
-  failure never aborts the upgrade it protects). Retention `MOSAIC_BACKUP_RETENTION` (default 5), in-place
-  `sort -r -o` prune (no `mv` — stays inside the rsync-absent coreutils whitelist).
-- **Task #11 — post-sync verify net (install.sh)**: `verify_operator_surface()` runs after sync (trap
-  disarmed), `cmp -s` each snapshot file vs target; restores any diverged/missing operator file + warns
-  loudly (a divergence = manifest bug). VERIFY-NET wired before `cleanup_snapshot`.
-- **Task #12 — `mosaic restore` (TS)**: `src/commands/restore.ts` + co-located spec (19 tests).
-  `--list` default (dry-run enumerate), `--from <ts>` confirmation-gated restore, `--dry-run`, `--yes`/
-  `MOSAIC_ASSUME_YES`. Injectable `confirm` for testability (proceed/decline/env-bypass covered). Restored
-  files forced 0600. Registered in `cli.ts`. Path convention mirrors install.sh `backup_root()`.
-- **CI**: `.woodpecker/ci.yml` upgrade-guard runs the new `test-upgrade-durable-snapshot.sh` gate.
-- **Gates green**: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1241 (+5) ·
-  durable-snapshot 26/26 · manifest-guard 193/193 · rollback 28/28 · migration 21/21.
-  Est. new-code coverage ≈93% (only the interactive readline default + process.exit-on-error uncovered).
-- Regression fixed: PR2's `date`/`sort`/`mv` broke the rsync-absent manifest-guard PATH whitelist →
-  made date/sort fail-open, replaced `mv` with in-place `sort -o`, added `date sort` to the test whitelist
-  + isolated `XDG_STATE_HOME`. All 193 manifest-guard assertions green under restricted PATH.
-- Codex code-review + security-review (secrev) run on the uncommitted diff before commit.
-
-### PR2 review round 1 — findings + remediations (2026-07-16, pre-PR)
-Codex code-review returned **request-changes** (1 blocker + 3 should-fix); Codex security-review returned
-**high** (1 high + 1 medium). Deduped to 5 distinct defects, ALL legitimate, ALL fixed FORWARD, each with
-a red-first regression test whose control neuters exactly the guard under test:
-
-- **A · BLOCKER — verify net undid the legacy bin/ migration (install.sh).** On a pre-v2 install `bin/**`
-  is operator-classified, so the durable snapshot captured it; `run_migrations()` deletes bin/ on purpose,
-  but `verify_operator_surface()` then saw it "missing" and healed it back — the migration would be silently
-  undone forever once the version stamps. **Fix:** `MIGRATION_REMOVED_PATHS[]` recorded by run_migrations
-  (`bin`,`rails`) + `is_migration_removed()` skip in the verify loop (`# MIGRATION-SKIP-GUARD`).
-  **Test:** Part 6 — v1 fixture with bin/; shipped keeps it removed + stamps v3; control (guard stripped)
-  wrongly restores bin/tool.sh.
-- **B · HIGH (CWE-59) — restore/verify wrote secrets THROUGH a symlink (install.sh + restore.ts).** An
-  attacker swapping an operator path (e.g. tools/_lib/credentials.json) for a symlink after the snapshot
-  would make `cp`/`copyFileSync` write the snapshot's secret out through the link. **Fix (bash):** refuse a
-  symlinked ancestor (`has_symlinked_parent`), drop a symlinked leaf before restore
-  (`# SYMLINK-LEAF-GUARD`). **Fix (TS):** reuse audited `secure-file.ts` — `assertCanonicalContainment`
-  + `ensureManagedDirectory` on every dst, open the leaf `O_NOFOLLOW|O_CREAT|O_TRUNC` 0600 (ELOOP =
-  fail-closed). **Tests:** Part 7 (shipped leaves external exfil target untouched, restores a real 0600
-  file; control leaks the secret through the link) + restore.spec symlinked-leaf/ancestor cases (red-first).
-- **C · MEDIUM/should-fix (CWE-22) — `--from` traversal escaped the backup root (restore.ts).**
-  `join(root, from)` accepted `../poison`. **Fix:** validate the selector against
-  `^\d{8}T\d{6}Z(?:-\d+)?$`, build exactly `join(root,'pre-update-'+ts)`, `lstat` (reject symlinked snap
-  dir). **Test:** restore.spec `it.each` of 6 malformed selectors + `--from ../poison` fail-closed (red-first).
-- **D · should-fix — verify `mkdir -p` unguarded under set -e (install.sh).** A parent replaced by a
-  regular file aborted the installer before the recovery pointer printed. **Fix:** guard `mkdir -p`, warn
-  + `continue` on failure (keeps healing remaining files).
-- **E · should-fix — snapshot `umask 077` leaked process-global (install.sh).** Later sync copies/dirs
-  inherited 0600/0700. **Fix:** save `old_umask`, restore on EVERY return path (`# UMASK-RESTORE-NORMAL`).
-  **Test:** Part 8 — synced framework file is 0644 while the secret backup stays 0600; control (restore
-  stripped) makes the synced file 0600.
-
-**Full gate suite re-run after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic
-vitest **1252** · restore.spec **30** · durable-snapshot **41** · manifest-guard 193 · rollback 28 ·
-migration 21. shellcheck clean on all new lines; new test markers mirror the existing `# VERIFY-NET`
-anchor convention. NOTE: codex self-review does NOT satisfy the independent-review gate — an independent
-(author≠reviewer) review + durable Gitea Reviewer-of-Record comment is still required before MS-LEAD merges.
-
-## Session 4 (2026-07-16) — PR2 MERGED, PR3 built (fleet regen — recovery layer)
-PR2 (#811) squash-merged → main `31607a4a`; issue #791 stays open (final PR of the 3-PR DAG). Independent
-exact-head RoR at `d12c5f78` APPROVE (Gitea cmt 17904); #1882 green; busybox-portable Part 7 control fix
-verified in-Alpine. PR3 UNBLOCKED.
-
-PR3 branch: `feat/791-pr3-fleet-regen` off `origin/main` 31607a4. Same discipline: tests-first red-first,
-independent review + durable Gitea RoR BEFORE MS-LEAD runs the queue guard/merge. PR body `Part of #791`.
-
-### PR3 scope (ratified §4/§7 of design doc) — `mosaic fleet regen`
-Projection-only recovery command: rebuilds each `fleet/agents/<name>.env.generated` from `roster.yaml`
-(SSOT). Dry-run default; `--write` applies; `--json` machine output. Structural guarantee: NO code path to
-systemd lifecycle — **never restarts an agent**. Single-SSOT: reuses `projectRosterV2AgentGeneratedEnv`
-(extracted, shared with the reconciler apply path) so regen and reconcile cannot drift. Secrev: paths +
-counts only, never the rendered KEY=value body.
-
-New files: `commands/fleet-regen-command.ts` (+ `.spec.ts`), guide `docs/guides/upgrade-safety-and-recovery.md`
-(three-layer model: PR1 manifest ownership → PR2 snapshot/restore → PR3 regen; do-NOT-restart-before-verify
-runbook), regen reference added to `docs/guides/fleet-local-canary.md`. Wired in `commands/fleet.ts`.
-
-### Independent review (3 reviewers: subagent code-reviewer + codex code-review + codex security) → 4 fixes, red-first
-- **A · BLOCKER (codex) — regen mutated/deleted legacy operator env.** `applyPreparedAgentEnvironmentProjection`
-  also writes `.env.local`/`.env.quarantine` and unlinks legacy `.env`. Violated projection-only contract.
-  **Fix:** NEW generated-only boundary primitives `prepareGeneratedAgentEnvironmentProjection` +
-  `applyPreparedGeneratedAgentEnvironmentProjection` (write ONLY `<name>.env.generated`). regen now has no
-  code path that touches `.env`/`.env.local`/`.env.quarantine`. **Test:** projection-only leaves legacy `.env`
-  verbatim, no local/quarantine fabricated.
-- **B · should-fix (codex + subagent + security) — partial write on mid-loop failure.** Interleaved
-  prepare/apply left earlier agents written when a later agent failed prepare. **Fix:** PREPARE ALL agents
-  before writing ANY (mirrors reconciler `defaultPrepareProjections`). **Test:** 2nd agent's projection
-  pre-seeded 0644 → prepare rejects → coder0 NOT written, exit 1.
-- **C · subagent — semantic-validation bypass.** Default readRoster skipped `validateRosterV2Semantics`, so
-  a tampered protected-class `tool_policy` would be silently projected. **Fix:** default readRoster now runs
-  `validateRosterV2Semantics` (persona resolution + protected-class match), rolesDir/overrideDir defaults
-  mirroring the reconciler. **Test:** merge-gate agent w/ tool_policy=code → fails closed, no write.
-- **D · MEDIUM (codex security, CWE-362) — concurrent-reconcile race.** regen `--write` wrote without the
-  reconcile lock. **Fix:** `--write` acquires `acquirePrivateReconcileLock(mosaicHome)` for the whole
-  read-prepare-apply sequence, released in `finally`; dry-run stays lock-free. **Test:** pre-held lock →
-  regen fails closed, no write.
-
-**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1265**
-(regen spec 13, incl. 4 new red-first regressions). NOTE: codex self-review does NOT satisfy the
-independent-review gate — an independent (author≠reviewer) review + durable Gitea RoR is still required
-before MS-LEAD merges. STOP at PR-open for MS-LEAD's exact-head review; do NOT self-merge.
-
-## Session 5 — PR3 review round 2 (finding L + M1/M2/M3), red-first fixes
-
-Second review pass on the lock-cleanup plumbing surfaced one round-1 residual (L) and three round-2
-findings (M1 blocker, M2/M3 should-fix). All fixed red-first (RED proven per-finding, then GREEN).
-
-- **L · should-fix (codex r1) — mutation-lock release swallowed unlink failures.** regen's
-  `acquirePrivateRosterMutationLock` release copied CRUD's `unlink().catch(()=>{})`, hiding a stale
-  `roster.yaml.mutation.lock`. **Fix:** its release PROPAGATES the unlink fault (finding-J stale-lock
-  warning then fires for this lock too). **Test:** acquire real lock, `rm` it, assert `release()` rejects.
-- **M1 · BLOCKER (codex r2) — replacement-lock race.** The propagating release from L did an
-  UNCONDITIONAL `unlink(lockPath)` without proving ownership. If the lock is cleared + re-created by
-  another writer mid-op, regen deletes the STRANGER's live lock → a third writer enters → mutual
-  exclusion defeated. **Fix (reuse, not reimplement):** generalized the reconciler's ownership-proving
-  lock body into shared `acquirePrivateManagedRosterLock(mosaicHome, lockLeaf, busyMessage, openLock)`;
-  `acquirePrivateReconcileLock` delegates to it (behavior-identical: same leaf/codes/messages), and a NEW
-  hardened `acquirePrivateRosterMutationLock` (now in fleet-reconciler.ts, leaf `roster.yaml.mutation.lock`)
-  records dev/ino + ownership token and RE-PROVES ownership (`assertLockOwnership`) before unlinking —
-  fails closed as `lock-cleanup-failed` if replaced. Removed the crud-based export; reverted
-  `acquireMutationLock` (fleet-agent-crud.ts) to its original inline empty-file/swallowing-release form
-  (CRUD behavior intentionally unchanged). Compatibility: CRUD empty-file `wx` and regen tokened `wx`
-  contend on the same path but never co-own (wx winner owns; loser → concurrent-mutation), so the token
-  is only ever read back by the same regen invocation. **Test:** acquire, `rm`+recreate lock (new inode),
-  assert `release()` rejects AND the replacement survives (not unlinked).
-- **M2 · should-fix (codex r2) — acquire-unwind fault dropped.** The acquire-failure catch discarded
-  `releaseFleetLocks`' return (a possible fault on the already-held first lock). **Fix:** capture and
-  augment — `const releaseFault = await releaseFleetLocks(releases); throw augmentWithLockCleanupFault(error, releaseFault);`
-  (symmetric to finding J). **Test:** mutation lock acquires w/ faulting release + reconcile acquire
-  throws → thrown error mentions stale/lock, nothing written.
-- **M3 · should-fix (codex r2 + subagent REQUEST-CHANGES) — cleanup warning named only reconcile lock.**
-  Finding L made the mutation-lock release fault reachable, so the `cleanup` marker can originate from
-  EITHER lock. **Fix:** `formatFleetRegenReport`'s WARNING now names BOTH `roster.yaml.mutation.lock` and
-  `roster.yaml.reconcile.lock`, matching `augmentWithLockCleanupFault`. **Test:** fault the mutation-lock
-  release specifically → report names both lock files.
-
-**Refactor note (no cycle):** neither fleet-reconciler nor fleet-agent-crud imports the other; regen
-imports lock acquirers from fleet-reconciler and the projection mapping from fleet-reconciler. The two
-reconcile-lock reviewers reconciled: independent reviewer validated acquire-time empty-file compatibility
-(preserved), codex flagged RELEASE-time replacement race (closed by ownership proof) — non-contradictory.
-
-**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1275**
-(regen spec 23, incl. 7 red-first lock regressions E/F/G/K/L/M1/M2/M3). RED proven per-finding by
-temporary revert before re-applying each fix. Independent (author≠reviewer) review of M1/M2/M3 + codex
-code/security re-run in flight. STOP at PR-open for MS-LEAD's exact-head review + durable Gitea RoR; do
-NOT self-merge; #791 umbrella stays OPEN; PR body `Part of #791`.
-
-### Round 3 review (after M1/M2/M3) — independent review PASS + codex residual-TOCTOU disposition
-Three reviewers on the post-M1/M2/M3 head:
-- **Independent (subagent, author≠reviewer) — PASS.** Verified M1/M2/M3 all correctly fixed; "never
-  restarts" is STRUCTURAL (runner never referenced in executable code); no secrets; no deadlock (only
-  regen holds both locks); tests meaningful (assert inode preservation + exact lock-file names). Raised:
-  - **should-fix #1 (fixed, red-first):** generalizing the lock helper left `assertSafeLockLeafIfPresent`/
-    `assertLockOwnership` hardcoding "reconciliation lock" in thrown messages → a MUTATION-lock fault
-    misreported as the reconcile lock, undercutting M3's accurate-diagnosis goal. **Fix:** thread
-    `lockLabel = fleet/<leaf>` through both helpers + the generic lock-io messages, so every fault names
-    the actual lock file. Red-first: strengthened the M1 test to assert `/roster\.yaml\.mutation\.lock/`
-    (RED: got "reconciliation lock"; GREEN after). Also resolves nit #3 (generic-message drift).
-  - **nit #2 (fixed):** `FleetRegenResult.cleanup` JSDoc still said "the shared reconcile lock"; now names
-    both locks (regen holds both).
-  - **nit #4 (fixed):** removed the redundant duplicate `assertLockOwnership` call before unlink
-    (pre-existing in merged main; harmless but dead — dropped since the fn was already being touched).
-- **Codex security — clean (risk: none).** Validates roster semantics, constrains env values, no shell
-  eval, no secret output, generated-only writes, serialized against both locks.
-- **Codex code — request-changes, 1 "blocker": residual check-then-unlink TOCTOU.** Between the final
-  `assertLockOwnership` and the path-based `unlink`, an external actor could vacate our inode and a new
-  writer grab the path, so the unlink deletes the stranger's lock. **Disposition: documented known
-  limitation, NOT fixed in PR3.** Rationale: (1) byte-identical to the MERGED, shipped reconcile-lock
-  release on origin/main (fleet-reconciler.ts L654-659) — not introduced here; (2) UNREACHABLE within the
-  `wx` writer protocol — no Mosaic writer removes a lock it doesn't own (wx fails EEXIST while our inode
-  exists), so only external interference can vacate our inode in the sub-instruction window; (3) the
-  ownership guard DOES close the reachable case (stale-lock reaper/operator cleared our lock + another
-  writer took it BEFORE release began → fail closed, don't delete stranger's lock); (4) the true atomic
-  fix — fd-held advisory lock (flock/lockf) adopted by ALL fleet writers (CRUD + reconcile + regen) — is
-  a cross-cutting mechanism change touching merged CRUD + reconciler, out of scope for a projection-only
-  recovery PR. Documented honestly in the acquirer doc + M1 test comment. **The binding independent
-  review did NOT treat this as a blocker.** Recommendation to MS-LEAD: proceed to PR-open + spin a
-  SEPARATE follow-up issue for the fd-advisory-lock migration; MS-LEAD adjudicates scope at exact-head
-  review (merge authority).
-
-**Gates after round-3 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1275** (regen spec 23). Fresh codex code re-run in flight to confirm no NEW issues from the label fix.
-
----
-
-## Session 6 — Round 4/5 convergence (stranded-lock robustness)
-
-**Two independent reviewers converged on the SAME should-fix** on the init-failure cleanup path,
-strengthening confidence it was real:
-
-- **Codex code-review-5 — 0 blockers, 1 should-fix.** "Stat failure after lock creation strands the new
-  lock." When `handle.stat()` ITSELF fails right after the `wx` create (transient EIO/EBADF), `created`
-  is `undefined`, so `removeOwnedLockLeafBestEffort` had `if (!created) return;` → no cleanup → the
-  just-created `roster.yaml.mutation.lock`/`reconcile.lock` is stranded, permanently blocking future
-  regen + CRUD. (Notably NO blocker, and the TOCTOU is no longer flagged in code-review as of r5.)
-- **Independent delta reviewer (author≠reviewer, pr-review-toolkit) — no blockers, same should-fix.**
-  Independently flagged the identical `!created` gap; validated FIX 1 (label threading — no call site
-  missed, codes unchanged, no test depended on old text) and FIX 2 (dev/ino-guarded cleanup, best-effort,
-  happy-path release reuses captured dev/ino) as correct. Suggested an unconditional best-effort unlink
-  in the `!created` branch; I took the **safer** variant below.
-- **Codex security-review-5 — 0 crit / 0 high / 1 medium.** The single medium is the SAME residual
-  check-then-unlink TOCTOU already dispositioned in round 3 (its own remediation = "migrate every writer
-  to an fd-held advisory lock" = the follow-up issue). No new security finding. No secrets.
-
-**Fix (red-first, safer than an unconditional unlink):** thread the persisted random `token` into
-`removeOwnedLockLeafBestEffort`. Two independent ownership proofs now: primary dev/ino (unchanged), and a
-**fallback** when the post-create stat failed — read the leaf and unlink ONLY if its content equals our
-`randomUUID()` token. Only OUR lock carries that token, so a CRUD (empty) or differently-tokened
-replacement is never deleted. `tokenPersisted` guards passing the token (only after `writeFile` lands).
-Doubly-degenerate case (stat fails AND token write never landed) leaves the lock in place rather than
-risk deleting a stranger's file — requires two independent fs faults on a just-created fd; documented.
-
-- **Red-first proof:** new test `does not strand the lock file when the post-create stat itself fails`
-  injects a real `wx` create + a Proxy handle whose `stat()` rejects (writeFile/close succeed), asserts
-  `exists(lockPath) === false`. RED before fix (`expected true to be false` — lock stranded); GREEN after.
-- **Also fixed (delta nit #3):** `fleet-regen-command.ts` `acquireRosterMutationLock` JSDoc said "CRUD's
-  private lock"; the default is the reconciler's hardened ownership-proving acquirer for the same
-  `fleet/roster.yaml.mutation.lock` path. Corrected.
-- **PR-description note (delta nit #2):** FIX 1 also collapsed a pre-existing duplicate back-to-back
-  `assertLockOwnership` call in the release closure (identical args, no intervening logic) into one — a
-  no-op simplification of merged code, not a behavior change. Called out so a future reader doesn't
-  wonder if the duplicate had a purpose.
-
-**Gates after round-4 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1277** (regen spec now 25: +1 stat-failure stranded-lock regression). Residual TOCTOU still deferred to
-the fd-advisory-lock follow-up issue; MS-LEAD adjudicates scope at exact-head review (merge authority).
-
----
-
-## Session 6 — Round 6 (persona-root wiring)
-
-**Codex code-review-6 — 0 blockers, 1 should-fix (NEW, distinct from the lock work).** "Forward
-configured persona directories to regen." `registerFleetRegenCommand` was registered at
-`fleet.ts:2069` with only `{ runner, mosaicHome }`, discarding `deps.reconcileDeps.rolesDir` /
-`overrideDir`. The regen command ALREADY has those seams (validates roster semantics via
-`validateRosterV2Semantics({ rolesDir, overrideDir })`, defaulting to `<mosaicHome>/fleet/roles{,.local}`),
-but the top-level wiring never forwarded the configured roots. **Impact:** in a deployment with custom
-persona roots, `fleet reconcile` (which honors the overrides) would ACCEPT a roster while `fleet regen`
-REJECTS the same roster (persona resolution against the wrong default dir) — blocking the recovery
-command and violating the documented "resolves personas the SAME way reconcile does" contract.
-
-**Fix (red-first):** forward `rolesDir`/`overrideDir` from `deps.reconcileDeps` into
-`registerFleetRegenCommand` at `fleet.ts:2069`. Red-first test `forwards configured persona roots
-(rolesDir/overrideDir) from reconcileDeps into regen`: seeds personas ONLY under a custom root, leaves
-the default `<home>/fleet/roles` empty, registers with `reconcileDeps: { rolesDir, overrideDir }`, and
-requires `fleet regen` to SUCCEED. RED before fix (`expected 1 not to be 1` — regen validated against the
-empty default and exited 1); GREEN after.
-
-**Codex security-review-6 — 0 crit / 0 high / 1 medium.** Same residual check-then-unlink TOCTOU, now
-noted at BOTH the release closure and the init-cleanup path; remediation = fd-held advisory lock across
-all writers = the SAME deferred follow-up item. No new security finding, no secrets.
-
-**Independent confirmation review of the token-fallback fix (Session 6/round 4) — PASS, no findings.**
-All 7 verification points confirmed; reviewer mechanically reverted `removeOwnedLockLeafBestEffort` to
-the pre-fix `if (!created) return;` and re-ran the new test → RED (`expected true to be false`),
-confirming the test genuinely pins the fix; restored after. No lint/type issues; doc-comment accurate.
-
-**Gates after round-6 fix (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1278** (regen spec now 26: +1 persona-root wiring regression).
-
----
-
-## Session 6 — Round 7 convergence (review CLOSED for PR-open)
-
-- **Codex code-review-7 — 0 blockers, 1 should-fix = the residual TOCTOU** (previously a "blocker" in r3,
-  dropped in r4/r5, now re-surfaced as a should-fix). **Codex security-review-7 — 0 crit / 0 high /
-  1 medium = the SAME residual TOCTOU.** Codex has CONVERGED: the only remaining finding across both
-  streams is that one race, whose own remediation is "fd-held advisory lock shared by all fleet writers"
-  = the deferred follow-up. No new distinct finding; the wiring fix introduced nothing.
-- **Independent confirmation review of the persona-root wiring fix — PASS, no findings.** Reviewer
-  mechanically reverted the two forwarded lines → RED (`Roster v2 agent "coder0" class "code" does not
-  resolve to a readable persona` → exit 1), restored → GREEN (26 regen + 204 fleet tests). Confirmed the
-  optional-chaining fallback preserves default-deployment behavior and no type/lint issue.
-
-**Review disposition for PR-open:** ALL actionable findings fixed red-first across rounds 3–6 (label
-threading, stranded-lock on init failure, stat-failure strand, persona-root wiring). The residual
-check-then-unlink TOCTOU is the ONLY open item and is DEFERRED to a follow-up issue (fd-advisory-lock
-migration across CRUD + reconcile + regen) — byte-identical to merged origin/main's reconcile-lock
-release, unreachable within the `wx` writer protocol (no Mosaic writer removes a lock it doesn't own;
-only external `rm`/a stale-lock reaper can vacate the inode mid-release), and its true fix is a
-cross-cutting mechanism change out of scope for a projection-only recovery PR. Two independent human-agent
-reviews (author≠reviewer) treated it as non-blocking. MS-LEAD adjudicates scope at exact-head review
-(merge authority); recommendation = proceed to PR-open + spin the follow-up issue.
-
-**Final gates (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1278**
-(regen spec 26). No secret values in any snapshot/projection/report output (counts + paths only). Regen
-NEVER issues a lifecycle/restart call (load-bearing recordingRunner gate). STOP at PR-open for MS-LEAD's
-exact-head review + durable Reviewer-of-Record before any merge; do NOT self-merge.

docs/scratchpads/804-install-unknown-flags.md

@@ -1,86 +0,0 @@
-# Issue #804 — fail closed on unknown installer arguments
-
-## Objective
-
-Implement Part 1 of Gitea issue #804 only: `tools/install.sh` must reject every unrecognized flag or argument with an actionable STDERR error and nonzero exit before installation starts.
-
-## Scope and constraints
-
-- Preserve all currently recognized options and behavior, including `-y` and `--ref <branch>`.
-- No positional arguments are currently accepted by the parser.
-- Do not add `--next`, `MOSAIC_NEXT`, prerelease routing, or any Part 2 behavior.
-- TDD is mandatory: add and observe a failing process-level regression test before changing `tools/install.sh`.
-- Worker lifecycle ends after branch push, PR creation, and coordinator notification; do not merge or close #804.
-- Existing launcher-owned changes in `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are out of scope and must not be committed.
-
-## Requirements and acceptance criteria
-
-- Unknown input names the offending argument on STDERR.
-- STDERR includes a short installer usage hint.
-- Exit status is nonzero.
-- The installer does not invoke npm or otherwise proceed into installation.
-- Existing recognized flags remain unchanged.
-
-## Plan
-
-1. Add a process-level Vitest regression using the installer test location under `packages/mosaic/src/commands/`.
-2. Run the focused test and record the expected RED failure.
-3. Commit the RED test as `test(#804): ...`.
-4. Replace the parser catch-all with a fail-closed STDERR error and usage hint.
-5. Update concise installer-facing documentation without introducing prerelease behavior.
-6. Run focused tests, shell syntax validation, package tests, lint, typecheck, and format checks.
-7. Run independent review tooling and remediate findings.
-8. Commit as `fix(#804): ...`, queue-guard, push, open a PR containing `Closes #804.`, notify the coordinator, and exit.
-
-## Budget
-
-- No explicit token cap supplied.
-- Working estimate: 8K tokens; narrow two-file behavior/test change plus concise docs and delivery gates.
-
-## Progress
-
-- 2026-07-17: Loaded mission state, issue #804, delivery/QA/documentation rails, and relevant TDD/Vitest/pnpm/Gitea skills.
-- 2026-07-17: Confirmed the parser has no legitimate positional arguments and currently drops all unmatched input via `*) shift ;;`.
-- 2026-07-17: Installed locked workspace dependencies with a worktree-local pnpm store; no lockfile changes.
-- 2026-07-17: Added the process-level unknown-argument regression with an isolated `$HOME` and npm shim.
-- 2026-07-17: Replaced the silent catch-all with STDERR error + usage output and exit 2 before preflight or installation.
-- 2026-07-17: Initial Codex code review found an unknown option could still be consumed as the `--ref` value. Added a second RED reproducer, then rejected option-shaped/missing `--ref` values without changing valid `--ref <branch>` behavior. The review's launcher-state note is handled by excluding both `.mosaic/orchestrator/` files from commits.
-- 2026-07-17: Updated README, user guide, and packaged framework README with the fail-closed argument contract. No API, auth, admin, sitemap/navigation, or publishing surface changed.
-
-## Verification
-
-- RED: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts` — expected failure: installer exited `0` instead of nonzero at the exit-status assertion; confirms the test reproduces the silent-drop defect before production changes.
-- Remediation RED: the added `--cli --ref --bogus` case exited `0`, proving `--ref` could swallow an unknown option before the guard was added.
-- GREEN: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts src/commands/install-heading.spec.ts` — 2 files, 3 tests passed.
-- Situational process check: unknown positional input exited 2, named the input on STDERR, printed usage, and did not call the npm shim.
-- `bash -n tools/install.sh` — passed.
-- Bare `--ref` process check — exited 2 with `Missing value for --ref` and usage.
-- `pnpm --filter @mosaicstack/mosaic test` — 69 files, 1,287 tests passed; framework shell checks passed. The first attempt lacked generated `dist/cli.js`; `pnpm --filter @mosaicstack/mosaic build` restored the required test precondition and the full rerun passed.
-- `pnpm lint` — 23/23 tasks passed.
-- `pnpm typecheck` — 42/42 tasks passed.
-- `pnpm format:check` — passed.
-- Codex code re-review against `origin/main` — `approve`, 0 blockers/should-fix/suggestions.
-- Codex security re-review against `origin/main` — risk `none`, 0 findings.
-
-## Acceptance evidence
-
-| Criterion | Evidence |
-| --- | --- |
-| Unknown input is named on STDERR | Process-level Vitest assertions for `--bogus`, including after `--ref` |
-| Short usage hint is printed on STDERR | Vitest usage regex + manual process output |
-| Exit is nonzero | Vitest status assertions and manual exit 2 |
-| Installation does not proceed | Isolated npm shim marker remains absent |
-| Recognized behavior is preserved | Parser cases are unchanged except validation of malformed `--ref`; full Mosaic package suite passed |
-| Part 2 is excluded | No `--next`, `MOSAIC_NEXT`, dist-tag, or prerelease routing changes |
-
-## Documentation checklist
-
-- Current canonical `docs/PRD.md` remains unchanged; issue #804 and the coordinator brief supply this bounded defect's acceptance contract.
-- Updated installer behavior in root README, user guide, and packaged framework README in the same logical change set.
-- API/OpenAPI, auth/permissions, admin operations, developer architecture, sitemap/navigation, and external publishing are not affected.
-- Scratchpad remains under `docs/scratchpads/`; no root-hygiene changes.
-
-## Risks and blockers
-
-- Part 2 remains owner-gated under #805 and is intentionally excluded.
-- No implementation blocker remains. Independent coordinator RoR, CI, merge, and issue closure remain pending after worker handoff.

docs/scratchpads/807-glpi-partial-content.md

@@ -1,64 +0,0 @@
-# Issue #807 — GLPI list wrappers accept HTTP 206
-
-- **Branch:** `fix/807-glpi-206`
-- **Task:** Gitea issue #807
-- **Role:** Author-only worker reporting to `mosaic-100`; no self-review or merge
-- **Started:** 2026-07-16
-
-## Objective
-
-Fix the shipped GLPI ticket, computer, and user list wrappers so ranged responses with HTTP 206 Partial Content render successfully while genuine HTTP failures remain non-zero errors.
-
-## Scope
-
-- Modify only the three affected list wrappers and a focused shell regression test.
-- Do not touch `session-init.sh`, `ticket-create.sh`, or `docs/TASKS.md`.
-- Add task-local delivery evidence here as required by the mission protocol.
-
-## Plan
-
-1. Add a deterministic shell harness that copies each wrapper beside stubbed `session-init.sh`, credentials, and `curl` boundaries.
-2. Prove RED against the current 200-only gates: 206 must fail before the implementation change.
-3. Update all three status gates to accept exactly 200 or 206.
-4. Prove GREEN for 206 rendering and genuine 401/500 failures, then run repository quality gates.
-5. Commit with co-author attribution, run the push queue guard, push, and open a PR for independent review and merge by the team lead.
-
-## Budget
-
-- No explicit token cap supplied.
-- Soft estimate: 8K tokens; narrow single-worker execution with no exploratory scope.
-
-## Progress
-
-- [x] Mission, task, PRD, QA, documentation, and code-review guidance loaded.
-- [x] RED regression evidence captured: `test-list-http-status.sh` exited 1; all three wrappers rejected 206 while retaining 401 failures.
-- [x] Implementation complete.
-- [x] Relevant tests and repository gates green.
-- [ ] Commit pushed and PR opened.
-
-## Tests and evidence
-
-- RED (before source fix): `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → exit 1; ticket/computer/user 206 assertions failed, all 401 assertions passed.
-- GREEN: `bash -n packages/mosaic/framework/tools/glpi/{ticket-list.sh,computer-list.sh,user-list.sh,test-list-http-status.sh}` → pass.
-- GREEN: `shellcheck packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → pass.
-- GREEN: `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → 6 assertions pass (206 renders and 401 errors for all three wrappers).
-- GREEN: `pnpm typecheck` → 42/42 tasks pass.
-- GREEN: `pnpm lint` → 23/23 tasks pass.
-- GREEN: `pnpm format:check` → all matched files pass.
-- Setup note: initial gate attempts could not start because the fresh worktree lacked dependencies; `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` restored the locked workspace dependencies without lockfile changes.
-
-## Acceptance criteria mapping
-
-| Criterion | Evidence |
-| --- | --- |
-| HTTP 206 succeeds and renders each ranged list | Focused test's three 206 render assertions pass |
-| Genuine HTTP failures remain non-zero with existing diagnostics | Focused test's three HTTP 401 assertions pass |
-| Only affected list wrappers change | Diff contains the three status predicates plus focused test/evidence; session and create wrappers untouched |
-
-## Documentation decision
-
-No operator/API documentation change is needed: this restores documented list behavior for a healthy GLPI response without changing command syntax, output, configuration, or public contracts. This task scratchpad records delivery evidence.
-
-## Risks / blockers
-
-- Existing dirty `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are runtime-owned and will not be edited or committed.

docs/scratchpads/808-agent-send-sender-identity.md

@@ -1,37 +0,0 @@
-# Issue #808 — agent-send sender identity
-
-## Objective
-
-Fix cross-socket `agent-send.sh` preambles so replies route to the real sender rather than a destination-socket holder session.
-
-## Scope and acceptance criteria
-
-- Prefer exported `MOSAIC_AGENT_NAME` as the authoritative sender session name.
-- If it is unset, query the sender's local/default tmux socket for `#S` without destination `-L` arguments.
-- Preserve `?` when sender identity cannot be determined.
-- Do not alter destination socket dispatch.
-- Add red-first regressions for all three identity paths.
-
-## Plan
-
-1. Extend `agent-send.test.sh` with deterministic fake-tmux coverage.
-2. Run the test against the unpatched implementation and record RED evidence.
-3. Apply the minimal sender lookup fix only.
-4. Run the focused suite and repository quality gates.
-5. Commit, queue-guard, push, and open an author-only PR for independent review.
-
-## Constraints and risks
-
-- Worker lane is author-only: no self-review or merge.
-- `docs/TASKS.md` and mission state are orchestrator-owned and will not be modified.
-- Pre-existing runtime changes under `.mosaic/orchestrator/` are excluded from this work.
-- Budget: no explicit token cap; keep changes limited to the shell tool, sibling regression test, and this scratchpad.
-
-## Evidence
-
-- RED: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` failed on the unpatched implementation with `PASS=12 FAIL=3`; it selected `destination-holder` instead of both `MOSAIC_AGENT_NAME=authoritative-agent` and local session `local-agent`. The genuinely unavailable sender case already exercised and preserved `?`.
-- GREEN: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed with `PASS=15 FAIL=0`; coverage includes env authority, local/default tmux fallback across a destination `-L`, explicit rejection of the destination holder, and `?` fallback.
-- Syntax: `bash -n packages/mosaic/framework/tools/tmux/agent-send.sh packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed.
-- Quality gates: `pnpm typecheck` (42/42 tasks), `pnpm lint` (23/23 tasks), and `pnpm format:check` all passed after installing the frozen lockfile dependencies. The first install attempt failed because pnpm's configured store pointed at `/root`; retrying with the existing user-owned store (`--store-dir /home/hermes/.local/share/pnpm/store`) succeeded without changing tracked dependency files.
-- Documentation: no public API or operator workflow changed; the source comment, regression-test contract, and this implementation record cover the internal bug fix.
-- Independent review: intentionally pending for the reviewer assigned by `mosaic-100`; this author-only lane will not self-review or merge.

docs/scratchpads/824-mosaic-skill-cli.md

@@ -1,112 +0,0 @@
-# Issue #824 — Mosaic skill CLI and Claude bridge auto-sync
-
-## Objective
-
-Deliver `mosaic skill register|unregister|list` plus install/upgrade reconciliation of every canonical `~/.config/mosaic/skills/*` entry into `~/.claude/skills/`, without clobbering runtime-owned files or directories.
-
-## Scope and constraints
-
-- Issue: mosaicstack/stack#824
-- Branch: `feat/824-mosaic-skill-cli`
-- M1 runtime: Claude Code only.
-- Pi/Codex parity is documentation-only; no non-Claude bridge implementation.
-- Do not author the downstream `mosaic-context-refresh` skill.
-- Workers do not modify `docs/TASKS.md`, merge, close #824, or touch `main`.
-- TDD is mandatory and red-first; filesystem tests use temporary directories only.
-- Budget: no explicit token cap supplied; use a focused single-worker implementation with no new dependencies.
-
-## Requirements mapping
-
-1. Register creates the canonical Claude symlink and is idempotent.
-2. Names are untrusted: reject empty/escaping/absolute/separator/`..`/leading-dash names before filesystem mutation, with clear CLI stderr and nonzero status.
-3. Register repairs only Mosaic-owned dangling symlinks and refuses foreign files, directories, and symlinks.
-4. Unregister removes only symlinks pointing inside the canonical Mosaic skills root and is idempotent when absent.
-5. List reports registered, dangling, foreign, and canonical-but-unregistered skills.
-6. Install and upgrade generically reconcile all canonical skills after framework sync/re-seed, continuing past foreign conflicts without clobbering them.
-7. User/developer documentation describes commands, status meanings, security boundaries, and Claude-only M1 scope.
-
-## Plan
-
-1. Add co-located failing Vitest coverage for all filesystem behaviors and auto-sync.
-2. Run the focused spec and record the expected RED failure.
-3. Commit the red contract as `test(#824): ...`.
-4. Implement the skill bridge and Commander command registration.
-5. Wire reconciliation into wizard finalize and `mosaic update` re-seed, preserving non-clobber behavior.
-6. Update canonical docs and sitemap if navigation changes.
-7. Run focused tests, package tests, typecheck, lint, and formatting.
-8. Commit implementation/docs as `feat(#824): ...`, queue-guard, push, open PR with `Closes #824.`, fire completion event, and notify the coordinator.
-
-## Progress
-
-- 2026-07-17: Loaded mission/delivery/TDD/documentation rails, issue #824, active mission state, and relevant installer/update paths.
-- 2026-07-17: Confirmed `mosaic update` invokes `framework/install.sh` with `MOSAIC_SYNC_ONLY=1`; that path exits before existing post-install skill linking, leaving newly present canonical skills unregistered.
-- 2026-07-17: Coordinator addendum classified the user-supplied skill name and runtime symlink target as a path-traversal/symlink-injection surface. Expanded the initial red contract to reject traversal before mutation, preserve every foreign entry, and unregister Mosaic-owned links only.
-- 2026-07-17: Implemented the Commander command group and secure generic bridge; wired wizard finalize and successful framework re-seed reconciliation; updated user/developer/installed/root docs and sitemap.
-- 2026-07-17: Focused, package-wide, repository baseline, temp-home situational, and independent review gates completed. Ready for scoped feature commit, queue guard, push, and PR handoff.
-
-## Tests and evidence
-
-### TDD evidence
-
-- RED environment attempt: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/skill.spec.ts` initially could not locate Vitest because this fresh worktree had no dependencies.
-- Dependency setup: `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` succeeded. The explicit store was required because machine pnpm config incorrectly resolves the default store under `/root`.
-- RED behavior: focused Vitest failed with `Failed to load url ./skill.js ... Does the file exist?`, proving the bridge API was absent.
-- RED integration: finalize/update specs failed because no Claude links or `skillSync` result existed.
-- RED symlink injection: symlinked Claude/canonical root tests failed because the initial implementation followed ancestor links.
-- GREEN after review remediation: `skill.spec.ts` 36/36, `finalize-skills.spec.ts` 6/6, and `update-checker.reseed.spec.ts` 30/30.
-
-### Baseline gates
-
-- `pnpm --filter '@mosaicstack/mosaic...' run build` — pass (fresh-worktree dependency outputs built).
-- `pnpm --filter @mosaicstack/mosaic run typecheck` — pass.
-- `pnpm --filter @mosaicstack/mosaic run lint` — pass.
-- `pnpm --filter @mosaicstack/mosaic test` — pass: 69 files, 1,325 Vitest tests plus framework shell suite.
-- `pnpm typecheck` — pass: 42/42 Turbo tasks.
-- `pnpm lint` — pass: 23/23 Turbo tasks.
-- `pnpm format:check` — pass.
-
-### Situational evidence
-
-A built-CLI temp-home smoke test (no real `~/.claude` or Mosaic config touched) proved:
-
-- register creates the exact link and a second run reports `already registered`;
-- list reports registered and unregistered canonical skills;
-- `../../etc` exits 1 with `Invalid skill name` and creates no escaped path;
-- unregister removes the managed link and a second run reports `already unregistered`;
-- a fake successful framework re-seed generically registered both `added-after-setup` and `second-skill` from runtime directory enumeration.
-
-### Review evidence
-
-- Initial uncommitted Codex code/security review described name validation/clobber protection as strong; its only finding was the harness-owned, unrelated `.mosaic/orchestrator/session.lock`, which is excluded from all commits and the PR.
-- Exact branch review then identified two remediations: preserve successful framework re-seed status when bridge-wide reconciliation fails, and reject/escape control-character names to prevent terminal/log injection.
-- Both findings were reproduced red-first and remediated. A subsequent exact review identified one finalize failure-isolation blocker; a root-wide bridge error now warns and allows wizard doctor/summary/next-steps completion, with a red-first regression.
-- All remediations passed the full package and repository gates. Final exact-head review is rerun after amending the feature commit.
-
-### Acceptance mapping
-
-| Acceptance criterion | Evidence |
-| --- | --- |
-| register/unregister/list, idempotent | `skill.spec.ts` and built-CLI temp-home smoke |
-| traversal/symlink-injection protection | invalid-name matrix, foreign file/dir/link tests, symlinked-root tests |
-| list flags dangling and foreign entries | deterministic list status test |
-| install and upgrade auto-sync every canonical directory | finalize + framework re-seed integration specs; two-skill built-module smoke |
-| newly added skill becomes discoverable without manual link | `added-after-setup` auto-sync creates exact Claude link; Claude can rescan with `/reload-skills` or a new session |
-| Pi/Codex parity captured as scope note | user guide, developer guide, installed framework README |
-| documentation gate | root README, user guide, developer guide, framework README, sitemap |
-
-## Risks
-
-- Symlink replacement uses `lstat` semantics so dangling links are detectable without following them.
-- Link ownership is determined lexically against the canonical skills root, and existing symlink ancestors in either managed root are rejected before mutation.
-- Auto-sync continues across per-skill conflicts while never deleting real files/directories or foreign symlinks.
-- Claude Code discovers filesystem skills at session launch/reload boundaries; bridge creation makes a later `/reload-skills` or new session able to discover the skill, but cannot mutate an already-cached in-process registry by itself.
-- Pi does not need this Claude bridge because its Mosaic launcher can consume the canonical root. Codex lifecycle parity remains explicitly deferred.
-- No deployment surface is affected.
-
-## PR #826 review remediation
-
-- 2026-07-17: Exact-head RoR requested changes for two ownership bugs: installer pruning deleted foreign-name links under `MOSAIC_HOME` outside canonical skills, and unregister deleted a same-root link targeting a different skill. It also requested trailing-dot rejection and executable coverage support.
-- RED evidence: focused regression run failed 4 tests: register/unregister accepted `safe.`, misdirected unregister did not throw, and the install linker deleted the foreign-name link.
-- GREEN evidence: `skill.spec.ts` passes 43/43, including live and dangling foreign-name links in a temp HOME/MOSAIC_HOME and the misdirected unregister invariant.
-- Coverage: `vitest run src/commands/skill.spec.ts --coverage` passes configured 85% thresholds for `skill.ts`: 91.05% statements/lines, 86.27% branches, 95.23% functions.
-- Full gates: package build passed; package tests passed 69 files / 1,332 tests plus framework shell suite; repository typecheck 42/42, lint 23/23, and format check passed.

docs/scratchpads/828-lease-broker.md

@@ -1,86 +0,0 @@
-# WI-1 Scratchpad — Authenticated external lease broker
-
-- **Issue:** Gitea #828
-- **Milestone:** 188 — Compaction-Refresh Mechanism (M1: Claude + Pi)
-- **Branch:** `feat/828-lease-broker`
-- **Starting HEAD:** `d801d6c4c8a984d6a95033c49714210018d3d9a8`
-- **Session role:** Orchestrator coordinating implementation; Mos retains merge authority.
-
-## Objective
-
-Implement the ratified WI-1 product lease broker under `packages/mosaic/`: Linux `SO_PEERCRED` identity, broker-minted logical session IDs, `(pid,starttime)` launcher anchors with per-hop `/proc` starttime revalidation, sibling-substitution rejection, same-PID runtime-generation revocation, crypto-RNG single-use token persistence, and protected Unix-socket posture.
-
-## Authority verification
-
-Verified before code on session start; all exact SHA-256 values matched:
-
-- BUILD-BRIEF: `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b`
-- SPEC-v5: `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433`
-- Ratification: `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67`
-- P6 planner ruling: `b7bbb6ea6e8d9a5c3366993642ab4e4f65b961af04936dcac20bfbcdcbaf1a09`
-- WI-0 Gate0 evidence: `5d418306fcc597fd514e500bee40d1509f0bf467e46ee13fc5c280ed8274759d`
-
-## Locked constraints
-
-- Build against the ratified design; do not re-derive it.
-- Product code only in `packages/mosaic`; Gate0 Python probes are reference prototypes and are not shipped.
-- Caller-supplied/asserted `session_id` is refused.
-- Tokens use the operating-system CSPRNG via Python `secrets`; never `Math.random` or model output.
-- Socket parent directory mode `0700`, socket mode `0600` minimum; document distinct-principal deployment as the stronger T-C-closing posture.
-- Red-first TDD for six named cases; new-code coverage >=85%.
-- No merge. PR must say `closes #828`; exact 40-character head handed to Mos for Opus-SECREV and independent review.
-
-## Plan
-
-1. Load security/testing/docs guidance and inspect existing `packages/mosaic` architecture.
-2. Write the six required tests first and capture RED evidence.
-3. Implement minimal broker modules and CLI/runtime integration necessary for product use.
-4. Run focused tests with coverage, package gates, then full repository gates/suite.
-5. Run author-side review/remediation, commit `closes #828`, queue guard, push, and open PR through Mosaic wrappers.
-6. Send PR number + exact head SHA to `web1:mosaic-100`; stop without merging.
-
-## Risks / boundaries
-
-- Same-UID counterfeit socket replacement remains the disclosed T-C residual unless broker runs under a distinct principal; filesystem modes alone are minimum hardening, not a complete authenticity proof.
-- `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` were already modified at session start and must not be included in this PR.
-- Repository Woodpecker pipelines exist; CI is the canonical build path. No manual image build/deploy is in scope.
-
-## Progress / evidence
-
-- 2026-07-18 session start: mandatory mission files and orchestration guides loaded.
-- STEP 0: all four authority hashes matched; artifacts read in full.
-- Branch/HEAD confirmed; issue #828 open; Gate0 evidence hash confirmed.
-- Initial RED: focused Vitest acceptance suite failed 11/11 because the product daemon did not exist; the expected missing-product failure was observed before implementation.
-- Review-remediation RED: partial/zero-progress state writes, nested corrupt state, symlink state, canonical starttime, and duplicate-anchor generation behavior failed before their fixes. Real socket RED/GREEN runs were executed by the unrestricted parent harness because the delegated worker sandbox denies `AF_UNIX.bind()`.
-- Product implementation added at `packages/mosaic/framework/tools/lease-broker/daemon.py`; Gate0 probe scripts were read as references but not copied or shipped.
-- Independent Codex code review round 1 found 2 blockers + 1 should-fix (connection stall/crash, partial writes, packet-dependent framing); all were remediated with tests.
-- Independent Codex code review round 2 found 2 blockers + 1 relevant should-fix (half-close contract ambiguity, incomplete persisted-state validation, symlink/non-regular state); all were remediated with tests and documentation. Pre-existing `.mosaic/*` session dirt remains excluded from the PR.
-- Unrestricted focused situational suite: `35/35` GREEN.
-- New Python product module coverage: `90%` (`356` statements, `36` missed), above the user-required 85%.
-- Root typecheck: `42/42` Turbo tasks GREEN.
-- Root lint: `23/23` Turbo tasks GREEN.
-- Root format check: GREEN.
-- Package build + suite: `71/71` files and `1,369/1,369` tests GREEN, including framework shell tests.
-- Full root suite: `43/43` Turbo tasks GREEN after the oversized-frame production race fix.
-- Focused acceptance suite: `35/35` GREEN in three consecutive unrestricted runs; exact-head instrumented run also `35/35` GREEN.
-- Exact-head Python product coverage: `90%` (`365` statements, `37` missed), above the required 85%.
-- Review-triggered oversized-frame race was fixed in production by bounded drain-to-EOF; tests were not changed.
-- Commits banked in red/green cadence: `d61c5441` (RED contract), `deb11df7` (GREEN implementation/docs), `57770e34` (oversized-frame production fix).
-- Final-review blocker remediated: added a 256-token pending-state cap, deletion on consume/generation revocation, pre-open serialized-size enforcement, and request-wide in-memory rollback for every broker mutation/commit failure while retaining the v1 live-token schema.
-- Distinct-principal docs now state built-in `0700`/`0600` is same-principal only; WI-1 does not provide the external identity-preserving proxy/ACL/service boundary needed for the stronger deployment.
-- Exact Python unit suite: `8/8` GREEN. Unrestricted focused acceptance: `35/35` GREEN.
-- Exact-head package build/suite: `71/71` files and `1,369/1,369` tests GREEN.
-- Exact-head Python product coverage: `90%` (`376` statements, `36` missed), above required 85%.
-- Root typecheck: `42/42` GREEN. Root lint: `23/23` GREEN. Root format check and `git diff --check`: GREEN.
-- Final exact-head rereview found two persistence blockers: post-rename directory-fsync uncertainty and acceptance of impossible persisted token records. RED was captured as three invariant failures plus one missing fail-stop error; commits `a94b1220` (RED) and `d05465e5` (GREEN) remediate both without weakening tests.
-- Post-remediation evidence: Python unit suite `10/10`, focused real-socket acceptance `35/35`, full root suite `43/43` Turbo tasks, broker coverage `90%` (`395` statements, `38` missed), lint `23/23`, typecheck `42/42`, format check and `git diff --check` GREEN.
-- Independent Codex review of remediation commit `d05465e54736c4966294c4af8fbd6a4ad8fe81aa`: APPROVE, confidence `0.94`, zero findings. Reviewer sandbox could not allocate temp directories; unrestricted parent test evidence above is canonical.
-
-- Remediation session: terra review comment `18072` reproduced a SERIAL-ACCEPT DoS; scope is RED regressions plus bounded concurrent connection handling on PR #836, preserving all existing broker security properties.
-- RED evidence against reviewed daemon: four silent peers delayed registration `3920 ms` beyond the `1500 ms` bound; 16 silent peers were not reaped within `2500 ms`. The first bounded implementation then exposed slot exhaustion by rejecting the valid queued caller with `EPIPE`; admission was corrected to wait for a reclaimed bounded slot. GREEN evidence: queued-peer test `211 ms`; strengthened cap/reap/reclaim test `1118 ms`; complete real-socket acceptance `37/37` and Python persistence suite `10/10`.
-
-## Coordinator handoff requirements
-
-1. Mandatory Opus-SECREV on the exact PR head; no GPT/terra substitute.
-2. Independent exact-head code review and exact-head RoR before Mos-authorized merge.
-3. Mos retains merge authority; this WI author stops after PR + full 40-character head handoff.

docs/scratchpads/829-mutator-gate.md

@@ -1,130 +0,0 @@
-# WI-2 Scratchpad — Whole mutator-class gate
-
-- **Issue:** Gitea #829
-- **Branch:** `feat/829-mutator-gate`
-- **Base HEAD:** `8ec67a1126adb0dcd4c3a2bf5525f3e239c0b201`
-- **Role:** sol author/build lane only; terra code review and Opus security review are coordinator-owned.
-
-## Mission prompt
-
-Implement BUILD-BRIEF Deliverable 2 as a framework-native whole mutator-class gate under `packages/mosaic/`, building against the merged WI-1 lease broker. No consequential mutator may succeed while UNVERIFIED after a compaction observer fires or after TTL. Carry the T-B compromised-tool acceptance criteria. Enforce revoke-first and promote-last structurally. A receipt is only a promotion prerequisite; the mutator-class gate remains the safety mechanism. M1 is Claude + Pi only.
-
-## Authority verification
-
-Verified exact SHA-256 before design/code:
-
-- BUILD-BRIEF: `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b`
-- SPEC-v5: `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433`
-- Ratification: `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67`
-- sol final red-team: `3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa`
-
-Carried authority chain also verified/read for the locked T-B gate contract: SPEC-v4 `a5e9c261…`, v4 sol `1e76ee59…`, SPEC-v3 `e0830ba0…`, v3 sol `9f321ade…`.
-
-## Plan
-
-1. RED real-socket acceptance tests for default-deny whole classes, T-B raw-tool bypass, observer/TTL revocation, and structural revoke-first/promote-last.
-2. Extend the merged WI-1 broker as the sole lease authority; authenticate every transition through existing peercred/ancestry/session logic and consume WI-1 single-use cycle tokens atomically before promotion.
-3. Add one broker-backed runtime gate executable and wire it across all Claude `PreToolUse` tools and Pi `tool_call`; unknown/custom tools deny by default.
-4. Add proportional protocol/security/operations documentation and requirements-to-evidence mapping.
-5. Run focused coverage, package/full suites, lint/typecheck/format, then queue-guard, push, open an unmerged PR with `closes #829`, and hand off the exact head.
-
-## Risks and bounds
-
-- Receipt parsing/builders and compaction observers are later WIs; WI-2 exposes the promotion prerequisite boundary but does not treat a receipt as safety authority.
-- Broker restart intentionally loses volatile VERIFIED leases and therefore restarts UNVERIFIED; persistent WI-1 identity/token state remains unchanged.
-- The gate is whole-class and does not parse shell command strings. T-C extension/hook absence and same-UID broker replacement remain outside the client guarantee and server branch protection remains the backstop.
-- Initial lease TTL is capped at ratified 300 seconds; callers may only shorten it.
-- Working budget assumption: 35K tokens; reduce documentation/refactor breadth before touching locked scope if pressure rises.
-
-## Progress and verification
-
-- RED #1: all 5 initial real-socket contract tests failed on WI-1 with `UNKNOWN_ACTION` or missing adapter behavior.
-- RED #2: register-before-exec runtime test failed because `launch-runtime.py` did not exist.
-- GREEN: broker-owned volatile lease state, 300-second maximum monotonic TTL, WI-1 token-backed promotion, all-tools runtime gate, Claude/Pi wiring, and register-before-exec launcher delivered without changing WI-1 peercred/ancestry authority.
-- Focused broker + gate acceptance: `43/43` GREEN.
-- Instrumented Python coverage: `88%` total — daemon `89%`, register/exec launcher `86%`, runtime gate `86%`.
-- Full repository suite: `43/43` Turbo tasks GREEN; `@mosaicstack/mosaic` `72/72` files and `1,377/1,377` tests GREEN.
-- Root typecheck: `42/42`; lint: `23/23`; format check and `git diff --check`: GREEN.
-- No author self-review was run. Exact-head terra CODE and Opus SECREV remain coordinator-owned gates.
-
-## Acceptance mapping
-
-| Acceptance criterion | Evidence |
-| --- | --- |
-| No consequential mutator succeeds while UNVERIFIED after observer revoke or TTL | `observer revocation and monotonic TTL expiry deny the next mutator` real-socket acceptance test |
-| T-B compromised-tool bypass is covered by the whole gate | `T-B raw and custom mutator tools are default-denied without shell parsing` across Claude/Pi built-ins, raw Bash class, MCP/custom/unknown tools |
-| Revoke-first / promote-last is structural | `revoke-first and promote-last structurally bracket mutator authority`; direct promotion rejected, pending remains denied, token consumption commits before VERIFIED |
-| Consume WI-1 auth/lease substrate | All transitions and decisions traverse merged peercred/ancestry authentication; promotion consumes the exact WI-1 CSPRNG cycle token |
-| M1 Claude + Pi | Claude `.*` PreToolUse and Pi `tool_call` invoke the same broker gate; register-before-exec test proves broker-minted parent identity reaches runtime descendants |
-
-## Locked discipline
-
-- Re-verify and read the four authority artifacts before design or code.
-- RED-first tests must cover unverified mutation refusal, T-B compromised-tool refusal, and revoke-first/promote-last ordering.
-- Consume WI-1 VERIFIED-lease state; do not re-derive kernel identity, ancestry, sessions, or token authentication.
-- Minimum 85% new-code coverage; full suite, lint, typecheck, and format checks green.
-- Build only: no self-review and no merge. Open a PR containing `closes #829`, report its exact 40-character head, then exit.
-
-## Remediation — terra CODE comment 18091
-
-- Coordinator correction: terra returned REQUEST CHANGES at head `77b137ccc04b5be035cac5ca21bbbf3df8b94f97`; Opus SECREV was GO and CI green, but no evidence transfers to the remediated head.
-- BLOCKER 1 verified: first-class Claude/Pi route through `execLeaseGatedRuntime`, while the supported Claudex path preserves isolation but directly invokes `claude`; it therefore registers no anchor, injects no lease session, and the isolated config has no guaranteed all-tools gate hook.
-- BLOCKER 2 accepted: prior 88% was aggregate evidence. Remediation must produce independently measured branch coverage of at least 85% for each new executable (`launch-runtime.py`, `mutator-gate.py`, and daemon delta evidence), including successful exec-boundary collection and validation/error branches.
-- Remediation discipline: RED tests first; preserve the reviewed-good broker lock/state-transition ordering; update PR #837 on the same branch; no self-review or merge.
-
-### Remediation evidence
-
-- RED commit `046896c6`: both `mosaic claudex` and `mosaic yolo claudex` behavioral probes exited 1 because the direct path supplied neither a broker session nor the isolated all-tools hook; branch-focused Python tests failed on the absent injectable boundaries. Fresh WI-2 daemon-delta instrumentation also failed the ≥85% branch gate at 75%.
-- GREEN: Claudex now exposes only `execLeaseGated`, passes the preserved isolated proxy environment through the shared register-before-exec wrapper, and merges the exact `.*` mutator hook into isolated `settings.json` with mode `0600`. Missing broker/identity, malformed or symlinked settings, and an unverified consequential tool all fail closed. The broker transition/lock implementation was not changed.
-- Behavioral regression: normal and YOLO Claudex both receive a 64-hex broker session, retain their mode-specific arguments, observe the exact all-tools hook, and receive status 2 for unverified `Bash`.
-- Independent branch coverage: `launch-runtime.py` 16/18 = **89%** (statements 98%); `mutator-gate.py` 21/22 = **95%** (statements 99%); `daemon.py` WI-2 delta 35/40 = **88%** (whole-file branch 80%, statements 90%).
-- Fresh focused real-socket coverage run: WI-1 + WI-2 acceptance `46/46`; persistence `10/10`; branch unit suite `10/10`.
-- Fresh full repository suite: `43/43` Turbo tasks; `@mosaicstack/mosaic` `72/72` files and `1,381/1,381` tests.
-- Fresh root gates: typecheck `42/42`; lint `23/23`; format and `git diff --check` GREEN.
-- PR #837 remains open and unmerged. Terra CODE and Opus SECREV must both rerun from zero on the exact remediated head before coordinator-owned merge authorization.
-
-## Remediation round 3 — terra CODE comment 18099 + binding upgrade
-
-- Locked-good surfaces: Claudex gating and B2 per-executable coverage are verified; do not regress them. Broker state-transition/lock ordering remains untouched.
-- Mechanical repository sweep found direct executing Claude entries in PRDY init, PRDY update, QA remediation, and `@mosaicstack/coord` task launch. It also found a direct Claude command rendered into the QA report template and documentation examples. Existing Mosaic CLI Claude/Pi/Claudex, orchestrator session-run, and fleet starts already reach the gated boundary.
-- Elevated hard requirements: ship a permanent suite/CI guard that scans production source and fails on any direct Claude/Pi launch; route every executing entry through one common gated wrapper; add real-broker RED/GREEN tests for PRDY init/update and QA; preserve each environment and denial behavior; independently measure all new executable coverage at ≥85%.
-- Round-3 plan: first commit RED behavioral and scanner-contract tests; then add one framework `launch-runtime.sh` choke-point over `launch-runtime.py`, make Mosaic CLI and shell launchers use it, make coord route through `mosaic`, and wire the permanent guard into package tests. Update all discovered operator-facing direct-launch examples so the scanner inventory remains complete.
-
-### Round-3 outcome
-
-- RED commit `7f3418fa`: PRDY init, PRDY update, and QA remediation all reached the fake Claude binary without a broker session even when the configured socket did not exist; the permanent-guard contract initially failed because its executable was absent, then failed against the five discovered direct entries (four executing plus the QA command template).
-- Choke-point decision: a new shell layer was unnecessary. Every executing repository entry now converges directly or through `mosaic`/`execLeaseGatedRuntime` on the existing single `launch-runtime.py` register-then-exec wrapper. PRDY and QA preserve their working directories, prompts, flags, logging pipe, and environment. Coord rewrites direct Claude commands to `mosaic claude` and rejects unknown custom Claude launchers fail-closed.
-- Permanent guard: `packages/mosaic/framework/tools/lease-broker/check-runtime-launches.py`, invoked by `packages/mosaic/package.json` `test:framework-shell` and therefore root `pnpm test`/CI. It scans production code under `packages/`, `apps/`, `plugins/`, and `tools/` and rejects literal, absolute-path, process-API, command-array, and dynamic Claude/Pi launch forms. Synthetic bypass tests are permanent at `runtime_launch_guard_unittest.py`.
-- Mechanical inventory: **14 gated / 14 total** — coord 2, fleet 1, QA 2, orchestrator 3, PRDY 2, Mosaic Claude/Pi/Claudex adapter/boundary 4. No verification-layer fallback or follow-up issue is needed because the single code-level wrapper was achieved.
-- Real-socket behavioral evidence: PRDY init, PRDY update, and QA remediation each fail before runtime execution when the broker is absent; with the broker present they receive a broker-minted 64-hex session and the unverified `Bash` authorization exits 2. Claudex normal/YOLO and the broker state machine remain GREEN.
-- Fresh branch coverage: `launch-runtime.py` **18/18 = 100%**; `mutator-gate.py` **22/22 = 100%**; permanent guard **36/38 = 95%**; `daemon.py` WI-2 delta **35/40 = 87.5%**. All attributable executable statement coverage is at least 98%.
-- Fresh focused suites: broker + mutator real-socket acceptance `49/49`; persistence `10/10`; launcher/gate branch suite `13/13`; permanent guard suite `7/7`; coord `19/19`.
-- Fresh full repository suite: `43/43` Turbo tasks; `@mosaicstack/mosaic` `72/72` files and `1,384/1,384` tests. Root typecheck `42/42`, lint `23/23`, format, and diff checks GREEN.
-- PR #837 remains open and unmerged. Terra CODE and Opus SECREV must both rerun from zero on the exact round-3 head before coordinator-owned merge authorization.
-
-## Remediation round 4 — terra CODE comment 18104
-
-- Locked-good surfaces: the 14/14 launch inventory, single `launch-runtime.py` choke-point, real-socket launcher behavior, coverage, Claudex gating, and broker state machine must not change.
-- Reproduced RIDER E exactly at head `1792b7934dda7eff64a207b8b0edb9c460d4164b`: a temporary production file containing `exec claude --dangerously-skip-permissions "terra-r3" # launch-runtime.py` made the guard exit 0 and report `1 gated/1 total`.
-- Root cause: classification searched the unparsed physical line, and the broad gated regex treated any `launch-runtime.py` substring—including comments and inert arguments—as an invocation before the direct-launch finding was evaluated.
-- Round-4 plan: add permanent RED cases for the exact comment evasion plus string-argument, echo, and unrelated-variable marker evasions; tokenize/strip comments by launcher syntax; recognize only command-position wrapper invocations with `--runtime` and the gated command separator; retain 14/14 real inventory; rerun guard coverage and all gates fresh.
-- Mos Rider A/B decision: adopt **both** defenses. Command-position parsing remains necessary because a normal `claude -p` launch is consequential even without the dangerous flag. The primitive-location invariant is more mechanically robust for dangerous mode because it does not need to recognize a wrapper marker at all. Move the sole raw `--dangerously-skip-permissions` literal into `launch-runtime.py`; any occurrence in another production file is independently RED.
-- Rider-A RED matrix adds heredoc body, backslash continuation, non-first `;`/`&&`/pipe commands, command substitution, `eval`, and variable-execution indirection in addition to the six marker/comment evasions. Before the augmented implementation, primitive ownership, command substitution, `eval`, variable execution, and the preserved 14-site inventory all fail.
-- Round-4 GREEN uses both defenses. Quote-aware comment stripping removes shell/Python `#` and JS/TS line/block comments; shell command prefixes are segmented with `shlex`; validated wrappers require `launch-runtime.py` in command position, `--runtime`, and the `--` command separator; multiline TypeScript wrapper calls are validated as complete invocations. Direct command syntax wins over markers, while tracked runtime assignments plus `eval`/variable execution, command substitution, chained commands, heredocs, continuations, and `env`/`command`/`nohup` prefixes are rejected.
-- Primitive ownership is independently load-bearing: `launch-runtime.py` is the sole production owner of the raw Claude dangerous flag. Mosaic, Claudex, and PRDY request semantic `--dangerous`; the wrapper validates Claude and injects the primitive immediately before register/exec. This preserves actual YOLO argv behavior while making any raw primitive elsewhere fail without relying on wrapper-name recognition.
-- Permanent guard suite now has 10 tests and 31 direct-launch forms, including 18 new round-4 marker/comment/indirection/prefix evasions plus harmless-marker and multiline-wrapper controls. Terra's exact add-ungated source is exercised through the CLI effectiveness test. Repository inventory remains exactly **14 gated / 14 total**.
-- Fresh round-4 coverage: guard **97%** branch-aware aggregate (241 statements, 110 branches); `launch-runtime.py` **100%**; `mutator-gate.py` **100%**. The daemon is byte-unchanged from the round-3 head whose WI-2 delta is **87.5%**.
-- Fresh round-4 gates: real-socket acceptance **49/49**; persistence **10/10**; launcher/gate **14/14**; guard **10/10**; coord **19/19**; Mosaic **1384/1384**; root **43/43**; typecheck **42/42**; lint **23/23**; format and diff checks green.
-
-## Remediation round 5 — terra 18116 + Opus 18114
-
-- Both independent gates converged on one guard-only completeness gap at round-4 head `1eb77c17f3147d4fa9944f77f1826243135b9cc0`; all round-4 primitive anchoring, command-position parsing, 14/14 inventory, broker ordering, and coverage remain locked-good.
-- Reproduced exactly: a temporary production source containing `launcher=claude` followed by `exec "$launcher" -p x` exits 0 with `0 gated / 0 total`. The literal command resolver skips prefixes but cannot resolve a tracked variable; the variable resolver handles only bare/eval references and cannot skip prefixes.
-- Round-5 plan: add 10 permanent RED forms (quoted/unquoted `exec`, `command`, `nohup`, and `env` with assignment, each multiline and same-line), then unify shell command-position resolution so literal and tracked-variable terminal tokens traverse the same prefix parser. Retain an independent variable-reference backstop, the 14/14 inventory, and every round-4 regression.
-- Mos stopping-criterion augment: command parsing is explicitly best-effort rather than a complete shell interpreter. Add B1 proving a parser-exotic alias launch with the raw dangerous flag is still RED by primitive anchoring, and B2 proving a parser-missed non-dangerous alias launch reaches the global `.*` hook and fails closed with `GATE_UNAVAILABLE` when no lease session exists. Document A (realistic parser matrix) + B (robust residual backstops); fresh reviewers supply criterion C (no new non-overlapping finding).
-- RED commit `91a4a983`: all 10 prefix×variable cases failed as expected before the fix—quoted/unquoted `exec`, `command`, `nohup`, and `env A=1`, each in multiline and same-line assignment shapes.
-- GREEN structural resolution: `shell_command_tokens()` now owns command-position prefix skipping for both literal and variable callers, including nested `exec`/`command`/`nohup`/`env` ordering. `runtime_variables` is threaded into `is_shell_direct_invocation()` and the same terminal-token resolver backs `executes_runtime_variable()`; exact `$v` and `${v}` references are resolved after `shlex` removes quoting. Same-line runtime assignment delimiters include shell operators.
-- Residual backstops: B1 proves alias-indirected dangerous mode is classified `dangerous-primitive` even though the parser does not resolve the alias. B2 proves a non-dangerous alias residual remains parser-missed, then verifies the shipped global `.*` Claude hook and status-2 `GATE_UNAVAILABLE` denial for representative read, mutator, and custom/MCP tools without a lease session.
-- Stopping-criterion evidence A+B is committed in tests and architecture docs; C remains the fresh exact-head terra/Opus determination. Repository inventory remains exactly **14 gated / 14 total**.
-- Fresh round-5 coverage: permanent guard remains **97%** branch-aware aggregate (251 statements, 112 branches). Locked-good launcher and mutator-gate executables remain unchanged at their round-4 **100% / 100%** evidence.
-- Fresh round-5 gates: real-socket acceptance **50/50**; persistence **10/10**; launcher/gate **14/14**; guard **12/12**; coord **19/19**; Mosaic **1385/1385**; root **43/43**; typecheck **42/42**; lint **23/23**; format and diff checks green.

docs/scratchpads/830-compaction-revoke.md

@@ -1,95 +0,0 @@
-# WI-3 Scratchpad — Compaction revocation and runtime-generation rollover
-
-- **Issue:** Gitea #830
-- **Branch:** `feat/830-compaction-revoke`
-- **Base HEAD:** `abd2791f59b3f06f46dd08e55298ced72f6aa7c2`
-- **Role:** sol author/build lane only; terra CODE and Opus SECREV are coordinator-owned.
-
-## Mission prompt
-
-Implement BUILD-BRIEF Deliverable 3.3 and D4 on merged WI-1/WI-2 under `packages/mosaic/`. Claude `PreCompact` and `SessionStart(matcher=compact)` plus Pi `session_before_compact`/`context` equivalents must revoke the active lease through the existing broker state machine. Any `runtime_generation` bump—including same-PID reload/resume/fork—must auto-revoke the prior incarnation so the new generation inherits no prior lease. M1 is Claude + Pi only.
-
-Honor amended D2-v5 exactly: hard fail-closure when at least one observer fires or after lease expiry; both observers missing within TTL is an explicitly named bounded residual stale window (maximum 300 seconds, soak-tighten only), with no claim that the mutator gate bounds actions inside that window; total gate-hook miss is T-C. T12b/T30 must report both the within-TTL ALLOWED outcome and after-TTL DENIED outcome.
-
-## Session start verification
-
-- Worktree is clean on `feat/830-compaction-revoke` at exact required base `abd2791f59b3f06f46dd08e55298ced72f6aa7c2`; `origin/main` is the same SHA and includes merged WI-2 atop WI-1.
-- Authority SHA-256 verified:
-  - BUILD-BRIEF: `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b`
-  - SPEC-v5: `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433`
-  - Ratification: `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67`
-  - sol red-team: `3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa`
-- WI-0 evidence pack SHA-256 `5d418306fcc597fd514e500bee40d1509f0bf467e46ee13fc5c280ed8274759d` read directly. Probe P3 is **PASS**: real Pi retained the same PID/starttime through reload/fork/new/resume while generations advanced and a prior VERIFIED generation was revoked.
-- P6 planner-return ruling SHA-256 `b7bbb6ea6e8d9a5c3366993642ab4e4f65b961af04936dcac20bfbcdcbaf1a09` read directly: feature WI admission is GO with the exact-delivery empirical compatibility fact and disclosed T-C middle-drop residual; no receipt redesign.
-
-## Plan and budget
-
-1. RED real-socket acceptance for T12b/T30, each Claude observer, same-PID generation rollover, Claude/Claudex hook wiring, and Pi lifecycle wiring.
-2. Add one broker client executable for observer revocation plus a private monotonic generation-file helper shared by launcher, gate, and revoker.
-3. Wire Claude `PreCompact`, `SessionStart(compact)`, and resume/clear generation rollover; merge equivalent mandatory hooks into isolated Claudex settings.
-4. Wire Pi pre/post compaction observers and reload/new/resume/fork generation rollover with local fail-closed tool blocking if lifecycle revocation fails.
-5. Document the D2-v5 bounded stale window without claiming the mutator gate bounds within-TTL actions; update protocol/security/operations/sitemap/checklist.
-6. Run focused real tests, independently measured executable coverage ≥85%, full repository gates, commit/push, open an unmerged `closes #830` PR, and hand off for terra CODE + mandatory Opus SECREV.
-
-Working estimate: **35K tokens**. No explicit hard cap was supplied; reduce refactor breadth before touching locked broker authority/state-machine semantics.
-
-## RED evidence
-
-- New T12b/T30 test already reports the inherited primitive honestly: within-TTL **ALLOWED**, after-TTL **DENIED**. The complete AC remains RED because the mandatory threat-contract document is absent.
-- Focused real-socket suite is RED with 7 expected failures: missing revoker executable (both Claude observers + generation bump), missing Claude/Pi wiring, missing isolated Claudex observers, and missing D2-v5 disclosure.
-- Branch-focused Python suite is RED on the wished generation initializer/resolver interfaces and missing `lease_generation.py` / `revoke-lease.py`.
-- Pi lifecycle suite is RED because the wished standalone `lease-lifecycle.ts` observer/generation module does not exist.
-
-## Locked discipline
-
-- RED-first T12b/T30 and observer/generation tests; test commit precedes implementation.
-- Reuse broker `revoke_lease`; do not fork identity, lease, or transition authority.
-- Preserve revoke-first/promote-last and WI-1/WI-2 reviewed state machine.
-- ≥85% attributable executable coverage with real tests.
-- No author self-review, no merge, no `--no-verify`.
-
-## Local implementation complete (push held)
-
-Implemented on the WI-3 base `abd2791f59b3f06f46dd08e55298ced72f6aa7c2` without changing the reviewed broker state machine:
-
-- Added `revoke-lease.py`, which authenticates through the existing broker session/generation and invokes `revoke_lease`. A fired observer that cannot confirm broker revocation advances the private generation as a local fence before returning non-zero.
-- Added `lease_generation.py`: owner/type/mode/size validation, no-follow opens, exclusive bump lock, monotonic `int64` generation, write-all + `fsync`, and fail-closed exhaustion/corruption handling.
-- `launch-runtime.py` creates `generation-<broker-session>.state` mode `0600` beside the socket before `exec`; `mutator-gate.py` resolves that current file value on every tool check.
-- Claude settings and isolated Claudex settings now preserve/install `PreCompact`, `SessionStart(compact)`, and resume/clear rollover hooks in addition to the global all-tools gate.
-- Pi now registers tested `session_before_compact`, `session_compact`→first `context`, and `session_start(reload|new|resume|fork)` handlers. Failed pre-compact revocation cancels compaction; failed post-compact/rollover revocation latches local all-tool denial.
-- Added PRD requirements, architecture/security/protocol/operations updates, sitemap entry, and the ignored-by-default documentation checklist (force-add required at commit).
-
-### Acceptance and coverage evidence
-
-- Focused acceptance: `19/19`; T12b/T30 prints within-TTL **ALLOWED** and after-TTL **DENIED**.
-- Pi lifecycle: `8/8`, with **100% statements/branches/functions/lines** attributable coverage.
-- New Python generation/revoker: `24/24`, **99% branch-aware aggregate coverage** (`lease_generation.py` 98%, `revoke-lease.py` 100%).
-- Mosaic package: `1399/1399`; framework shell Python `24/24`, launch guard `12/12`, permanent launch inventory `14 gated/14 total`.
-- Existing lease-broker real-socket acceptance: `37/37` within the package run.
-- Full repository: `43/43` Turbo tasks green; gateway `628 passed / 12 skipped`; Mosaic `1399/1399`.
-- Root typecheck: `42/42`; lint: `23/23`; format and `git diff --check` green.
-- Initial direct package test without first building the package reproduced the known missing-`dist/cli.js` harness condition; the canonical root Turbo test (which schedules `@mosaicstack/mosaic#build`) and explicit package build+test are green. No test was weakened.
-
-### Review evidence
-
-- Codex uncommitted code review: **APPROVE**, confidence `0.88`, zero findings. Its read-only sandbox could not rerun Vitest, but the author-side focused and full suites above were green.
-- Codex uncommitted security review: risk **none**, confidence `0.91`, zero findings.
-- Coordinator-mandated fresh exact-head terra CODE and Opus SECREV remain pending after rebase/push clearance; these local reviews do not replace that final gate.
-
-### Hold and residuals
-
-- **DO NOT PUSH OR OPEN A PR YET.** Coordinator requires flake-fix #838 to land, then WI-3 must rebase onto deterministic-green `main` before push.
-- Merge remains gated on #838, #827 Probe 3, and combined GO.
-- Named residual retained verbatim: when both observers are entirely missed, within-TTL consequential actions remain allowed; only lease expiry denies after the bounded stale window. No within-window mutator-action bound is claimed.
-
-## Deterministic-main rebase evidence
-
-- Fetched and confirmed `origin/main` at `8dfcf1903e385f977121069f798f476eb671fffc` (`#838` bounded broker deadlines, empty-read fail-closure, and de-flaked acceptance client).
-- Linear rebase completed. The only content conflict was `packages/mosaic/src/mutator-gate/runtime_tools_unittest.py`; resolution retained #838's `subprocess`/`threading` deadline regressions and WI-3's `stat` generation-state coverage. No authority/state-machine choice was ambiguous.
-- `packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts` auto-merged on top of #838's shared `requestBrokerReply` helper. No inline socket/`JSON.parse` client was resurrected.
-- Verified WI-3 has zero diff from `origin/main` for #838-owned `daemon.py`, `broker-test-client.ts`, `lease-broker.acceptance.spec.ts`, `vitest.config.ts`, and `packages/mosaic/package.json`; bounded deadlines and the de-flaked harness are preserved byte-for-byte.
-- Required verbose acceptance command: **2 files / 56 tests green**. T12b/T30 still prints within-TTL **ALLOWED** and after-TTL **DENIED**.
-- Full Mosaic package after explicit build: **74 files / 1408 tests green**; deadline unit `2/2`, runtime tools `25/25`, launch guard `12/12`, inventory `14/14`.
-- Full repository: **43/43 Turbo tasks green**. Root typecheck `42/42`, lint `23/23`, format and diff checks green.
-- Attributable coverage remains Python **99%** branch-aware and Pi lifecycle **100%** statements/branches/functions/lines.
-- Push and PR remain held pending combined GO and all WI-3 merge gates. The coordinator-owned promote-lease-lost-ACK SPEC amendment/backstop is acknowledged as a future merge prerequisite and was not retro-expanded into this core rebase/build.

docs/scratchpads/832-receipt-challenge-protocol.md

@@ -1,13 +0,0 @@
-# #832 Receipt-challenge protocol — build scratchpad
-
-- **Objective:** Deliver WI-5 receipt-challenge protocol ACs T25, T26, T28, and T29 only.
-- **Authority:** BUILD-BRIEF, SPEC-v5, ratification, and red-team hashes verified in STEP-0.
-- **Base:** `e522b22fa4492861b0fcd4a956a8795c54eb9bfe` (`origin/main`).
-- **Constraints:** Byte-build only: no live broker/socket/systemd/tmux mutation. No PR, self-review, or probe fire. T27/T30 are out of scope.
-- **Plan:**
-  1. Add red-first deterministic T26/T29 in-build tests that call shipped normative construction and broker path.
-  2. Add an unexecuted, isolated P5 out-of-process replay harness that drives the shipped daemon and asserts consume-before-promote for T25/T28.
-  3. Implement the broker-minted receipt challenge and exact receipt observation/consume/promote path.
-  4. Run unit, framework-shell, compile, lint, and type checks; push after the required queue guard; report to `mosaic-100`.
-- **Risks:** The standalone harness must drive the real daemon without a divergent fixture. If that is impossible, stop and flag Mos.
-- **Evidence:** Initial RED recorded in `/home/hermes/agent-work/reviews/832-wi5-red-receipt-challenge.log`; initial green checks passed. Remediation RED recorded in `/home/hermes/agent-work/reviews/832-wi5-remediation-red.log` before observer/payload implementation; remediation green passed. Remediation-2 RED recorded in `/home/hermes/agent-work/reviews/832-wi5-remediation2-red.log`: each rejected begin restored prior VERIFIED authority. Remediation-2 GREEN: receipt unittest (5: all `INVALID_CONSTRUCTION`, `PAYLOAD_CONSTRUCTION_REFUSED`, and `PAYLOAD_BINDING_MISMATCH` cases preserve UNVERIFIED and deny the next mutator), normative-fragments unittest (5), state-store regression (10), full mutator-gate acceptance (20, including the real begin → observer → consume → promote path), `py_compile`, Mosaic package lint/typecheck, and targeted Prettier check. The P5 harness remains unfired. Coverage tooling remains unavailable (`python3 -m coverage`: module not installed). Push pending.