fix(#1051): track canonical estate registry

Co-authored-by: be-coder-08 <[email protected]>

.woodpecker/publish.yml

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

README.md

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

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

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

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

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

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

@@ -72,13 +72,13 @@ const mockChatGateway = {
   broadcastSessionInfo: vi.fn(),
 };
 
-function buildService(redis: typeof mockRedis | null = mockRedis): CommandExecutorService {
+function buildService(): CommandExecutorService {
   return new CommandExecutorService(
     mockRegistry as never,
     mockAgentService as never,
     mockSystemOverride as never,
     mockSessionGC as never,
-    redis as never,
+    mockRedis as never,
     mockBrain as never,
     null,
     mockChatGateway as never,
@@ -131,22 +131,6 @@ describe('CommandExecutorService — P8-012 commands', () => {
     expect(ttl).toBe(300);
   });
 
-  it('/provider login remains available without Redis on the local tier', async () => {
-    const localService = buildService(null);
-    const payload: SlashCommandPayload = {
-      command: 'provider',
-      args: 'login anthropic',
-      conversationId,
-    };
-
-    const result = await localService.execute(payload, userScope);
-
-    expect(result.success).toBe(true);
-    expect(result.message).not.toContain('token=');
-    expect(result.data).toEqual({ provider: 'anthropic' });
-    expect(mockRedis.set).not.toHaveBeenCalled();
-  });
-
   // /provider with no args — returns usage
   it('/provider with no args returns usage message', async () => {
     const payload: SlashCommandPayload = { command: 'provider', conversationId };

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

@@ -23,10 +23,7 @@ export class CommandExecutorService {
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(SystemOverrideService) private readonly systemOverride: SystemOverrideService,
     @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
-    // On Local tier COMMANDS_REDIS is null — provider login caching is skipped.
-    @Optional()
-    @Inject(COMMANDS_REDIS)
-    private readonly redis: QueueHandle['redis'] | null,
+    @Inject(COMMANDS_REDIS) private readonly redis: QueueHandle['redis'],
     @Inject(BRAIN) private readonly brain: Brain,
     @Optional()
     @Inject(forwardRef(() => ReloadService))
@@ -446,16 +443,14 @@ export class CommandExecutorService {
           byte.toString(16).padStart(2, '0'),
         ).join('');
         const key = `mosaic:auth:poll:${tokenHash}`;
-        if (this.redis) {
-          // Persist only a short-lived token digest. The raw token is delivered only by
-          // the authenticated dashboard flow, never in chat output or command metadata.
-          await this.redis.set(
-            key,
-            JSON.stringify({ status: 'pending', provider: providerName, userId }),
-            'EX',
-            300,
-          );
-        }
+        // Persist only a short-lived token digest. The raw token is delivered only by
+        // the authenticated dashboard flow, never in chat output or command metadata.
+        await this.redis.set(
+          key,
+          JSON.stringify({ status: 'pending', provider: providerName, userId }),
+          'EX',
+          300,
+        );
         return {
           command: 'provider',
           success: true,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { Inject, Injectable, Optional } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
 import type { QueueHandle } from '@mosaicstack/queue';
 import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
@@ -21,10 +21,7 @@ function escapeRedisGlobLiteral(value: string): string {
 @Injectable()
 export class SessionGCService {
   constructor(
-    // Local tier has no Redis; lifecycle cleanup still demotes this session's logs.
-    @Optional()
-    @Inject(REDIS)
-    private readonly redis: QueueHandle['redis'] | null,
+    @Inject(REDIS) private readonly redis: QueueHandle['redis'],
     @Inject(LOG_SERVICE) private readonly logService: LogService,
   ) {}
 
@@ -32,10 +29,8 @@ export class SessionGCService {
    * Scan Valkey for all keys matching a pattern using SCAN (non-blocking).
    * KEYS is avoided because it blocks the Valkey event loop for the full scan
    * duration, which can cause latency spikes under production key volumes.
-   * Returns an empty population on the Local tier where Redis is disabled.
    */
   private async scanKeys(pattern: string): Promise<string[]> {
-    if (!this.redis) return [];
     const collected: string[] = [];
     let cursor = '0';
     do {
@@ -52,14 +47,12 @@ export class SessionGCService {
   async collect(sessionId: string): Promise<GCResult> {
     const result: GCResult = { sessionId, cleaned: {} };
 
-    // 1. Valkey: delete all session-scoped keys (skipped on Local tier).
-    if (this.redis) {
-      const pattern = `mosaic:session:${escapeRedisGlobLiteral(sessionId)}:*`;
-      const valkeyKeys = await this.scanKeys(pattern);
-      if (valkeyKeys.length > 0) {
-        await this.redis.del(...valkeyKeys);
-        result.cleaned.valkeyKeys = valkeyKeys.length;
-      }
+    // 1. Valkey: delete all session-scoped keys
+    const pattern = `mosaic:session:${escapeRedisGlobLiteral(sessionId)}:*`;
+    const valkeyKeys = await this.scanKeys(pattern);
+    if (valkeyKeys.length > 0) {
+      await this.redis.del(...valkeyKeys);
+      result.cleaned.valkeyKeys = valkeyKeys.length;
     }
 
     // 2. PG: demote hot-tier agent logs for this session only.

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

@@ -18,7 +18,7 @@ import type { MosaicJobData } from '../queue/queue.service.js';
 @Injectable()
 export class CronService implements OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(CronService.name);
-  private readonly registeredWorkers: Array<Worker<MosaicJobData>> = [];
+  private readonly registeredWorkers: Worker<MosaicJobData>[] = [];
 
   constructor(
     @Inject(SummarizationService) private readonly summarization: SummarizationService,
@@ -26,12 +26,6 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
   ) {}
 
   async onModuleInit(): Promise<void> {
-    // Local tier deliberately has no BullMQ consumers or repeatable jobs.
-    if (!this.queueService.isEnabled()) {
-      this.logger.log('CronService: BullMQ disabled on local tier — no jobs will be scheduled');
-      return;
-    }
-
     const summarizationSchedule = process.env['SUMMARIZATION_CRON'] ?? '0 */6 * * *'; // every 6 hours
     const tierManagementSchedule = process.env['TIER_MANAGEMENT_CRON'] ?? '0 3 * * *'; // daily at 3am
 
@@ -45,7 +39,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const summarizationWorker = this.queueService.registerWorker(QUEUE_SUMMARIZATION, async () => {
       await this.summarization.runSummarization();
     });
-    if (summarizationWorker) this.registeredWorkers.push(summarizationWorker);
+    this.registeredWorkers.push(summarizationWorker);
 
     // M6-005: Tier management repeatable job
     await this.queueService.addRepeatableJob(
@@ -57,7 +51,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const tierWorker = this.queueService.registerWorker(QUEUE_TIER_MANAGEMENT, async () => {
       await this.summarization.runTierManagement();
     });
-    if (tierWorker) this.registeredWorkers.push(tierWorker);
+    this.registeredWorkers.push(tierWorker);
 
     // Retire any repeatable global GC schedule created by older deployments.
     // Session cleanup is now triggered only by an authorized session lifecycle operation.

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

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

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

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

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

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

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

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

docs/PRD.md

@@ -79,6 +79,49 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 
 ---
 
+## Per-estate durable agent working memory (#1051)
+
+### Problem and objective
+
+Agent and lane continuity currently accumulates as plain local files with no repository backing. The installer must make a private, per-estate `mosaic-brain` clone at `~/.mosaic` reproducible without authorizing cross-estate access or introducing an independent credential path.
+
+### Normative requirements
+
+1. `MB-REQ-01` (R1): Ensure the target estate's existing `mosaic-brain` can be cloned to `~/.mosaic`; repository creation and live access granting remain broker-mediated.
+2. `MB-REQ-02` (R2/Q1): Derive estate and brain target from the configured target git host through the credential broker's estate registry. A second `brain_repo` authority and host-machine inference are forbidden; an unknown host fails closed with a named diagnosis.
+3. `MB-REQ-03` (R3): Seat access is granted only through `mosaic cred`; callers must never resolve or read a token independently. Live grant verification is gated on MC-CRED-01 implementation.
+4. `MB-REQ-04` (R4): The eventual live postcondition requires `~/.mosaic` to be a `main`-branch git repo with the expected remote and a seat-owned read/write round-trip. This live validation is gated on MC-CRED-01 implementation and cannot be replaced by a clone exit code.
+5. `MB-REQ-05` (R5): The out-of-estate refusal control covers both Git and API resolver axes. Axis disagreement is `indeterminate` failure, never permission; contract tests bind to the broker's four terminal classes and stable reason codes.
+6. `MB-REQ-06` (R6): The brain skeleton excludes `*.token`, `*.key`, `*.pem`, `.env`, and `credentials.json`; credentials remain broker-owned and no error path may print secret material. Arbitrary legacy content is never auto-published from a heuristic denylist: an approved content scanner must bind approval to the exact source snapshot, otherwise the item is retained and reported.
+7. `MB-REQ-07` (R7): Detect existing local lane directories and seat state files, publish approved snapshots into the durable layout without overwrite or deletion, and explicitly report every detected item that cannot be migrated. Automatic source deletion is parked until command-scoped identity propagation and the required clean audit; retained sources are always reported. Lane findings are append-only; `board/` has a named single writer; writes push immediately rather than on a timer.
+8. `MB-REQ-08` (R8): `mosaic doctor` reports missing clone, wrong remote, incomplete write-access evidence, and uncommitted local state. `--fix` repairs the first three only through the approved installer/broker path; it never hand-rolls credential resolution.
+9. `MB-REQ-09`: Retention is ownership-first and archive-only. Every retained artifact requires a named durable owner; absent or non-durable ownership leaves the gate open and blocking. Age and size never authorize deletion.
+10. `MB-REQ-10`: Brain provisioning occupies canonical installer P7 only after the applicable P5 credential postcondition commits; canonical phase numbers are unchanged.
+
+### Current delivery slice
+
+In scope now: estate derivation, secret exclusion, non-destructive migration, doctor reporting/repair orchestration, and red-first tests over all four credential-contract terminal classes. Live grant and live read/write round-trip evidence remain explicitly gated on the working MC-CRED-01 broker and must not be mocked or replaced by independent token lookup.
+
+### Acceptance criteria
+
+1. `AC-MB-01`: Contract tests observe RED before implementation and then distinguish `ok/0`, `refused/10`, `error/20`, and `indeterminate/30`, preserving v1.5 diagnoses including refused `provider-identity-mismatch`/`credential-rejected` and indeterminate `identity-not-measured`/`provider-unavailable`. A scope-forbidden `/user` result with confirmed in-scope repository capability is never represented as a dead credential. `identity-not-found` remains reserved for a future visibility-authorized inventory operation and is not an expected `validate` result.
+2. `AC-MB-02`: Estate resolution uses the configured target git host and one registry; unknown, mismatched, and host-machine-derived inputs fail closed.
+3. `AC-MB-03`: A clean fixture contains the required layout and exact secret exclusions; filename-, content-, binary-, and size-based secret controls remain outside Git without their values appearing in output. Without an approved scanner, even benign legacy content is retained and reported rather than auto-published.
+4. `AC-MB-04`: Migration publishes approved lane-durable and seat-state snapshots into collision-safe archive/ledger paths, retains and reports every source, never overwrites an existing finding, and never deletes by age/size.
+5. `AC-MB-05`: Doctor detects all four R8 defect classes; `--fix` repairs eligible classes through the approved P7/broker seam and leaves unresolved credential-dependent states visible.
+6. `AC-MB-06`: Git-axis and API-axis refusal must both be authoritative `refused` outcomes with matching stable reason codes; any disagreement yields `indeterminate`.
+7. `AC-MB-07`: Independent code review and security review pass at the exact head, and HOMELAB Woodpecker instance `mosaic` is terminal green before integration.
+8. `AC-MB-08`: After reviewed merge to `main`, report only **believed-fixed, pending jarvis validation**; issue #1051 remains open until W-jarvis validates the installed result.
+
+### Constraints and risks
+
+- MC-CRED-01 contract v1.5 is the caller boundary; no independent credential/token lookup is permitted. Identity is established from governed mint-time binding and provider evidence when measurable, never a credential filename. Runtime validation does not widen a least-privilege token merely to make `/user` observable.
+- C1 owns installer phase sequencing. This slice consumes P5/P7 ordering without renumbering or duplicating the phase machine.
+- Lane content is findings, so last-writer-wins is data loss. Append-only names and explicit collision handling are mandatory.
+- A created-but-empty brain beside unbacked local doctrine fails the objective; migration is a primary acceptance gate.
+
+---
+
 ## Compaction Refresh Trust Lifecycle (M1, #827–#830)
 
 ### Problem and objective

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

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

docs/guides/dev-guide.md

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

docs/guides/user-guide.md

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

docs/scratchpads/1051-mosaic-brain-installer.md

@@ -0,0 +1,115 @@
+# #1051 — per-estate mosaic-brain installer
+
+Last updated: 2026-08-05
+
+## Objective
+
+Codify estate-derived, repository-backed `~/.mosaic` support with secret exclusions, non-destructive migration, doctor diagnostics/fixes, and credential-contract terminal-class handling. Live broker grants and live read/write round-trips remain gated on MC-CRED-01.
+
+## Sources and bindings
+
+- Provider issue: HOMELAB `git.mosaicstack.dev`, `GET /api/v1/repos/mosaicstack/stack/issues/1051`, `application/json;charset=utf-8`.
+- Issue requirements: R1–R8 read directly on 2026-08-05.
+- MC-CRED caller contract: v1.5, SHA-256 `4cecba3386b37431d4a075205c6dfe43555c7673922fed61b84f43cac1a6ae92` at the 2026-08-05 re-derivation. Earlier moving bindings were v1.5 `710d22d61a93a4b9c70fc55506a023a675a110417fa7a6e72dc051c0d9fe8237`, v1.4 `27f20158561ae8292f3bfc926b5e97f398de93db6a1cf65fcc215d08811d39af`/`d12ad4595b7aef078e392988a07ab5cb00244440775c9c733dc825746d7ac67b`, and v1.3 `8cfa4853d2b0b0e8cc9e792fa8411310e16d7704c06e0af9d9a57155131d8086`.
+- Fleet doctrine: SHA-256 `026b43322e0551ef15b646a9f30d3a6aef58c662a810b732be2a03b1ecf7d36e` at intake.
+- Intake base was HOMELAB provider `next` = `4df478cdd150fdf8d52ea109f02ade5d85017acd`; `main` = `5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc`. On 2026-08-05 `mos-claude` ruled that L0 trunk-based gate 15 requires all three lanes to retarget to `main`; `next` remains a non-merging integration branch. Never weaken or patch `pr-merge.sh`.
+
+## Scope
+
+### In now
+
+- R2/Q1 target-host estate derivation using one registry.
+- R5 both-axis refusal parity and disagreement failure.
+- R6 exact secret exclusions and no secret-bearing diagnostics.
+- R7 detection plus non-destructive, collision-safe migration/reporting.
+- R8 doctor checks and approved-seam fix orchestration.
+- Red-first tests over all four contract terminal classes and stable reason codes.
+
+### Gated / excluded
+
+- R3 live grant: waits for working MC-CRED-01.
+- R4 live seat-owned read/write round-trip: waits for working MC-CRED-01.
+- No independent token lookup, grant helper, or shared-credential fallback.
+- No phase renumbering; C1 owns the phase machine and provides the P5→P7 seam.
+- No age/size reaping or deletion.
+
+## Owner authority ruling and resolver seam
+
+- Binding addendum: `/home/hermes/agent-work/tl-mosaic/CHARTER-MB-BRAIN-01-ADDENDUM.md`; re-read after compaction.
+- HOMELAB durable lane-archive owner and user-namespace brain owner are the human provider account selected by local estate policy (operator ruling: `jason.woltje`) with a required GLPI queue as the standing remediation process. The brain target is therefore `<policy-owner>/mosaic-brain` on the estate host, not `<installer-source-org>/mosaic-brain`. Framework source remains operator-agnostic: the actual login and queue are local policy, not hardcoded open-source context.
+- Provider lookup is anonymous because the ruled owner is public. It requires exact allowlisted login plus a same-invocation public known-good control, private 404 control, and generated absent 404 control. It sends no Authorization header and never widens token scope.
+- Provider `active` is deliberately ignored: non-admin reads return false for demonstrably active accounts. Resolvability + exact login + public visibility are the gate.
+- Private and absent principals both return anonymous 404. The fail-closed reason is `owner-not-resolvable`, never owner-not-found.
+- Caller `owner` strings and `validated=true` are ignored. Migration consumes only an injected source-of-truth resolver result. Owner grammar is NFKC-stable, ASCII allowlisted, exact-policy matched, and mission-seat class is excluded.
+
+## Plan
+
+1. Pre-register acceptance tests and observe each requirement RED for its own missing behavior.
+2. Commit the red tests before implementation.
+3. Implement a narrow brain provisioning/doctor helper that consumes broker JSON outcomes and the shared estate registry without credential resolution.
+4. Implement safe migration and exact brain skeleton/ignore policy.
+5. Integrate the helper into C1's P7 seam and `mosaic doctor` after C1 lands/rebase.
+6. Run focused, package, installer, lint, typecheck, format, and situational security tests.
+7. Run independent code and security reviews in parallel; remediate and re-review.
+8. Push after HOMELAB queue guard, open the reviewed PR to `main`, and preserve merge order C1 → MC-CRED → MB-BRAIN. Do not modify the merge guard; `next` is non-merging integration only.
+9. Re-take CI measurement at the rebased exact head; do not rework code solely because base evidence moved.
+
+## Acceptance interpretation registered before results
+
+- `ok/0`: complete authoritative evidence only.
+- `refused/10`: complete authoritative denial only.
+- `error/20`: local contract/control failure; never reinterpret as denial.
+- `indeterminate/30`: incomplete/disagreeing evidence; fail closed, never resolve permissively.
+- Both Git and API axes must return authoritative `refused` with the same stable reason code for R5. Any axis disagreement is `indeterminate`. A provider `/user` login mismatch is first-class `provider-identity-mismatch`; credential filenames never establish principal identity.
+- Migration publication requires the durable object to contain the approved snapshot and no overwrite. Automatic path-based source deletion is parked; every source is retained and reported.
+- Secret exclusion is tested through exact ignore rules, nested secret-shaped paths, bounded UTF-8 content controls, and an approved-scanner gate bound to the exact source snapshot. Without an approved scanner, even benign content is retained and reported rather than committed.
+
+## Budget
+
+No explicit token ceiling was supplied. Working cap: 55K tokens for implementation/review and 3 focused remediation attempts per failure class. Reduce optional refactoring and documentation breadth before touching required acceptance scope.
+
+## Risks
+
+- C1 and MC-CRED branches have not merged into `main`; integration edits must wait for their exact interfaces or be confined to stable contract seams.
+- A broker runtime test before MC-CRED lands would either fail for an irrelevant reason or pressure a hand-rolled workaround; contract fixtures are allowed, live capability claims are not.
+- Migration can lose data through overwrite, cross-device move failure, or partial copy. Implementation must stage, verify resulting bytes, and retain/report source on incomplete transfer.
+- `~/.mosaic` is a git repo, while current working state may live under multiple local roots; detection must be explicit and cannot treat age/size as ownership.
+
+## Progress / evidence
+
+- [x] Charter receipt accepted by `tl-mosaic`.
+- [x] Issue #1051 R1–R8 read directly from provider.
+- [x] Contract re-derived through v1.3, moving v1.4, and v1.5 before R5 integration. v1.5 separates in-scope repository capability from `/user` identity measurement: 401 is `credential-rejected`/refused, 403/404 may become `identity-not-measured` only after in-scope capability succeeds, and 200 login mismatch is refused. `identity-not-found` is not reachable from `validate`.
+- [x] C1 P5→P7 seam receipt read; no brain implementation is in C1.
+- [x] RED acceptance set committed at `cf11c6c86abae073d8b02b4014cd5447ba67f12a`; author and committer read back as `be-coder-07` and branch reachability was independently verified by `tl-mosaic`.
+- [x] Moving-contract REDs observed independently for v1.4 mismatch, R8 prerequisite ordering, owner resolver seam/allowlist, tracked skeleton/no-follow behavior, runtime observation/publication, and provider owner resolution.
+- [x] Focused implementation includes secure migration, v1.5 write-differential/subject binding, production Git+API refusal parity, provider-backed durable owner resolution that ignores non-admin `active`, required GLPI standing-process policy, P7 provision orchestration, an internal installer command, and installed `mosaic doctor` wiring. Latest focused result: 97/97 (secure config 4, store 45, runtime 19, owner resolver 16, provision 5, provision command 3, installed doctor 5).
+- [x] MC-CRED added the required canonical reverse registry seam `ParsedCredentialEstateRegistry.resolveByHost()`; the 32-line permissive shim was removed. After exact-head CI proved the cross-PR source dependency was absent, the provider-fetched canonical registry implementation, DTO dependencies, and registry tests were tracked byte-for-byte on this branch so a fresh checkout validates the real seam rather than a stub. A later rebase onto merged MC-CRED should recognize those identical files as upstream.
+- [x] Identity gotcha measured: inline `MOSAIC_GIT_IDENTITY=be-coder-07` controls credential resolution but does not override `user.name`/`user.email` inherited from the linked worktree common-dir config (`coder-mos1`). The first local P7 RED commit was immediately amended before push with command-scoped `GIT_AUTHOR_*` + `GIT_COMMITTER_*`; resulting author and committer both read back as `be-coder-07`. Every subsequent authoring command must carry both identity sets and be verified.
+- [x] R6 migration reports filename- or content-secret-shaped files without copying them; arbitrary legacy content requires an approved scanner bound to the exact source snapshot, and production currently retains/reports when no approved scanner is configured. `.gitignore` is canonical allowlisted content only: an existing noncanonical regular file fails closed and is never merged into publication. Symlinked `.gitignore`, layout directories, and nested migration destinations fail closed; a dirty checkout blocks provisioning before skeleton publication. The brain root is principal-owned mode `0700` before clone and after clone, all memory-bearing layout directories are mode `0700` even under umask `0022`, and doctor reports owner-accessible roots as hard unsafe findings.
+- [x] Provider owner lookup uses manual redirect handling, a five-second abort signal, strict JSON content type/shape, and an incrementally enforced 256 KiB response ceiling.
+- [x] Security-critical owner policy/registry reads have direct controls for principal UID ownership, file/ancestor permissions, and descriptor-safe regular-file reads.
+- [x] Automatic source deletion is parked per the shared-Git-identity governance ruling; remotely reachable snapshots still leave and report every source.
+- [x] Multi-host push-on-write uses an isolated temporary Git index populated from approved in-memory blobs rather than pathname re-reads, verifies each committed blob ID, the exact changed-path allowlist, and both author/committer trailers before push, then reconciles only approved paths into the real checkout index. Real-repository controls prove a clean checkout remains clean, a concurrent non-fast-forward fetch/rebase/push remains clean and preserves both findings, destination-path substitution cannot change committed bytes, and unrelated pre-staged secret-shaped content remains staged but never enters the published commit.
+- [x] Doctor Git observations preserve three states: `clean`, `dirty`, and `unmeasurable`; failed remote, branch, or status measurements emit hard `brain-git-state-indeterminate` findings rather than mismatch or ready. The boolean-literal guard sweep covered all MB-BRAIN production files in the 20-file PR population: its only remaining `=== false` guard is the non-nullable `isAbsolute()` predicate; no nullable boolean measurement guards remain.
+- [x] Author-run Review 10 and focused 88/88 evidence were declared void when blocker fixes changed the head; neither is an independent gate pass.
+- [ ] Installer shell P7 invocation after C1 + MC-CRED integration; production command is registered but the C1 shell has not yet called it.
+- [ ] Implementation green on merged dependency base.
+- [ ] Independent code review.
+- [ ] Independent security review.
+- [ ] HOMELAB CI terminal green at exact head.
+- [ ] Reviewed PR retargeted to `main` after C1 and MC-CRED; `next` remains non-merging integration only.
+
+## Exact-head CI dependency remediation
+
+- Pipeline `#2222` at `a50b5a6b` ran the sole pull-request-eligible workflow (`ci`, 1/3 defined workflows) and failed `typecheck` with two `TS2307` errors before lint, format, or tests could execute.
+- History establishes that the imports are intentional: commit `2451c2f` introduced both consumers, while the contemporaneous registry-seam report explicitly called the local 32-line implementation a disposable scaffold and required MC-CRED's canonical parser. This was a deliberate cross-PR dependency, not a wrong import or forgotten shim add.
+- RED-first root typecheck reproduced the two missing-module errors. The fix tracks the provider-fetched MC-CRED registry, its two DTO dependencies, its unit test, and the result DTO dependency. Three DTO files remain byte-identical to `fbff4ffa`; author review found that the canonical parser accepted a trailing-slash origin which MB-BRAIN consumers concatenate into double-slash URLs, so the parser and test are intentionally hardened here pending propagation to MC-CRED.
+- R7 removed the tracked registry module and root typecheck returned RED with three missing-module errors (the two production consumers plus the registry unit test); restoring the same SHA-256 returned typecheck to 45/45 tasks.
+- With the suppressing typecheck failure removed, lint ran 25/25 tasks and formatting passed. Full tests actually ran: 1,607/1,614 passed; the seven failures are the four pre-registered P7 integration tests intentionally held for C1/MC-CRED integration plus the three previously disclosed ambient update-banner CLI smoke failures. No test was weakened. Build ran 25/25 tasks.
+- Author review's trailing-slash finding was reproduced RED (`https://git.example.invalid/` accepted), then fixed by requiring the configured source to equal `URL.origin`; the control reran GREEN. Security review reported risk `none` with zero findings; final code re-review remains required after remediation.
+- This is a second instance of the `#1068` suppression class: an early integrity failure prevented every downstream stage carrying behavioral evidence from running while the workflow's aggregate failure looked like a completed check. Workflow reordering remains `#1068` scope and is not changed here.
+
+## Completion language
+
+After reviewed merge to `main`, only: **believed-fixed, pending jarvis validation**. Issue #1051 remains open until W-jarvis validates the installed result.

docs/scratchpads/462-fed-m3-06-get-verb.md

@@ -1,38 +0,0 @@
-# Scratchpad — FED-M3-06 get verb
-
-## Objective
-
-Implement `POST /api/federation/v1/get/:resource/:id` for M3 inbound federation reads.
-
-## Scope
-
-- `apps/gateway/src/federation/server/verbs/get.controller.ts`
-- `apps/gateway/src/federation/server/verbs/get-query.service.ts`
-- Unit coverage for controller pipeline + query service RBAC guardrails
-- Register controller/service in `FederationModule`
-
-## Plan
-
-1. Mirror the list verb pipeline: `FederationAuthGuard` → `FederationScopeService` → read-only query service.
-2. Return one `_source: "local"` tagged item on success.
-3. Return federation error envelopes:
-   - `404 not_found` when the resource id does not exist.
-   - `403 scope_violation` when the row exists but falls outside native RBAC/scope intersection.
-   - `400 invalid_request` for malformed ids/scope requests.
-4. Keep read audit persistence deferred to M4; no body or response persistence in M3.
-
-## Verification Evidence
-
-- Rebased onto `origin/main` at `86e106fcc9a1dfa3a18f7846bb477be128794aad` after M3-05 merged; resolved `FederationModule` by registering both list and get verb controllers/services.
-- Review-change coverage added for comment 15971:
-  - get note access now requires subject ownership AND authorized mission intersection.
-  - missing federation context returns structured `401 unauthorized` envelope.
-  - unsupported get resources fail closed with structured denial.
-  - PGlite regressions cover cross-user note exclusion and subject-note unauthorized-mission exclusion.
-- `pnpm --filter @mosaicstack/gateway test -- src/federation/server/verbs/__tests__/get.controller.spec.ts src/federation/server/verbs/__tests__/get-query.service.spec.ts` — pass (2 files / 17 tests; re-run after review changes).
-- `pnpm --filter @mosaicstack/gateway build` — pass (re-run after review changes).
-- `pnpm build` — pass (23 successful tasks before review changes).
-- `pnpm typecheck` — pass (41 successful tasks; re-run after review changes).
-- `pnpm lint` — pass (23 successful tasks; re-run after review changes).
-- `pnpm format:check` — pass (re-run after review changes).
-- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings after review changes.

docs/scratchpads/B1-next-durable-publish-design.md

@@ -1,82 +0,0 @@
-# B1 / @next Durable Publish Pipeline — Design
-
-## Objective
-
-Make `next` a durable integration line that publishes the artifacts required by downstream federation boot tests without manual builds.
-
-Every merge to `next` publishes:
-
-1. **npm prerelease packages** to the Gitea npm registry with dist-tag `next`.
-2. **Gateway container image** tagged only as `gateway:sha-<short>`.
-
-The existing stable release behavior remains isolated to `main` / tags.
-
-## Registry verification
-
-Target registry: `https://git.mosaicstack.dev/api/packages/mosaicstack/npm/`.
-
-Pre-implementation checks:
-
-- `npm view @mosaicstack/mosaic dist-tags --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/ --json` returned a dist-tags object (`latest: 0.0.48`).
-- `npm view @mosaicstack/mosaic@latest version --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/` resolved `0.0.48`.
-- `@next` currently returns 404 because no `next` dist-tag exists yet; this is expected before the first next prerelease publish.
-
-Pipeline design includes a post-publish verification that `npm view @mosaicstack/mosaic@next version` resolves to the exact CI-computed prerelease version. If Gitea fails to honor the `next` dist-tag, the pipeline fails closed.
-
-## Version scheme
-
-The prerelease version is computed at publish time only; no `package.json` version changes are committed.
-
-For each non-private `@mosaicstack/*` package:
-
-```text
-<target-stable>-next.<CI_PIPELINE_NUMBER>
-```
-
-Where:
-
-- `CI_PIPELINE_NUMBER` is Woodpecker's monotonic pipeline number.
-- `target-stable` is the package's current committed stable version with the patch component incremented.
-  - Example: `@mosaicstack/mosaic` `0.0.48` publishes as `0.0.49-next.1626`.
-  - Example: `@mosaicstack/gateway` `0.0.6` publishes as `0.0.7-next.1626`.
-
-Rationale:
-
-- npm semver sorts `0.0.49-next.1627` above `0.0.49-next.1626`.
-- The prerelease does not overtake the future stable `0.0.49`.
-- The monotonic pipeline number avoids conflicts across repeated `next` merges.
-
-## Branch and tag guardrails
-
-| Pipeline path         | Branch/event                   | Publishes                                               | Forbidden              |
-| --------------------- | ------------------------------ | ------------------------------------------------------- | ---------------------- |
-| stable npm publish    | `main` push/manual or tag      | package versions already committed in package manifests | `@next` dist-tag       |
-| next npm publish      | `next` push/manual only        | CI-computed prereleases with `--tag next`               | `latest` dist-tag      |
-| gateway image         | `main` push/manual or tag      | `sha-<short>` + `latest` on main + tag on tag events    | next prerelease npm    |
-| gateway image         | `next` push/manual only        | `sha-<short>` only                                      | `latest`               |
-| appservice/web images | `main` push/manual or tag only | existing stable image behavior                          | next image publication |
-
-The pipeline has explicit branch checks inside the publish commands as a second fail-closed layer beyond Woodpecker `when` clauses.
-
-## Implementation plan
-
-1. Widen `.woodpecker/publish.yml` top-level `when` to include `next` so the publish pipeline runs on next merges.
-2. Keep existing `publish-npm` on `main` / tags only.
-3. Add `publish-next-npm` for `next` push/manual only:
-   - configure Gitea npm auth from existing `gitea_token` secret as `NPM_TOKEN`;
-   - preflight registry dist-tag metadata;
-   - compute prerelease versions in CI by temporarily editing package manifests in the workspace;
-   - run `pnpm publish ... --tag next` against non-private `@mosaicstack/*` packages;
-   - verify `@mosaicstack/mosaic@next` resolves to the computed version.
-4. Split image `when` anchors:
-   - `image_build_when` includes `next` and is used by `build-gateway`;
-   - `main_image_build_when` keeps appservice/web on main/tags only.
-5. Keep gateway next image destinations to `sha-<short>` only; no `latest` on next.
-
-## Risk controls
-
-- Auth/registry failures are fatal.
-- No manual image build/push path is introduced.
-- No production `latest` tags are touched from `next`.
-- No `@latest` npm dist-tags are touched from `next`.
-- All changes live in CI config and docs; no runtime source behavior changes.

docs/scratchpads/B2-skills-sync-path.md

@@ -1,34 +0,0 @@
-# B2 — Fresh-install skills sync path
-
-## Problem
-
-Greenfield wizard on `next` reported:
-
-```text
-Skills sync script not found at ~/.config/mosaic/bin/mosaic-sync-skills
-Skills: install failed
-```
-
-## Diagnosis
-
-The framework install migration removed the legacy `~/.config/mosaic/bin/` directory and now installs framework helper scripts under:
-
-```text
-~/.config/mosaic/tools/_scripts/
-```
-
-`packages/mosaic/src/stages/finalize.ts` still resolved wizard helper scripts from `mosaicHome/bin`, so wizard-selected skills failed even though `mosaic-sync-skills` was present in the current framework layout.
-
-## Fix
-
-- Resolve framework helper scripts through `tools/_scripts/<name>` first.
-- Keep a legacy `bin/<name>` fallback for pre-migration installs.
-- Point missing-script warnings at the current `tools/_scripts` layout.
-- Update the finalize skills test fixture to model the fresh framework layout.
-- Update framework README examples from legacy `bin/` helper paths to `tools/_scripts/`.
-
-## Verification
-
-- Unit: `pnpm --filter @mosaicstack/mosaic test -- finalize-skills`
-- Gates: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm build`
-- Fresh path: ran `packages/mosaic/framework/install.sh` with a temp `MOSAIC_HOME` and `MOSAIC_SYNC_ONLY=1`; verified `tools/_scripts/mosaic-sync-skills` exists, legacy `bin/mosaic-sync-skills` does not, and the script installs a selected fake `lint` skill into Mosaic + Pi runtime skill directories.

docs/scratchpads/B3-wizard-gateway-health-order.md

@@ -1,36 +0,0 @@
-# B3 — Wizard completion ordering
-
-## Problem
-
-The wizard printed the success summary / `Mosaic is ready.` during `finalizeStage`, before the gateway configuration stage had completed its daemon health check. If the gateway health gate later failed, the user could see a success claim followed by a gateway failure.
-
-## Diagnosis
-
-`finalizeStage` handled both mutation work and terminal success messaging. Wizard paths then ran `gatewayConfigStage` and `gatewayBootstrapStage` afterward:
-
-1. finalize writes config, links runtime assets, syncs skills, runs doctor;
-2. finalize prints `Installation Summary` + `Mosaic is ready.`;
-3. gateway config starts/waits for daemon health;
-4. gateway bootstrap runs.
-
-The summary needed to be deferred until after the gateway readiness gates.
-
-## Fix
-
-- `finalizeStage` now returns a `showSummary()` callback and supports `deferSummary`.
-- Wizard/quick-start paths call finalize with `deferSummary: true`.
-- `showSummary()` is called only after gateway config reports ready and bootstrap completes, or immediately when the caller explicitly skips gateway setup.
-- If gateway health/config reports not ready, the wizard returns/aborts without printing the success summary.
-- Folded in adjacent runtime install hint fix for Pi: `curl -fsSL https://pi.dev/install.sh | sh`.
-
-## Verification
-
-- Added unified-wizard coverage for summary-after-health and no-summary-on-health-failure.
-- Targeted: `pnpm --filter @mosaicstack/mosaic test -- unified-wizard finalize-skills`
-- `pnpm format:check`
-- `pnpm typecheck`
-- `pnpm lint`
-- `pnpm build`
-- `pnpm test`
-- Codex code review: approve.
-- Codex security review: one low finding on the requested Pi `curl | sh` install hint; no security finding in the wizard completion-ordering change.

docs/scratchpads/B4-wizard-step-dedup.md

@@ -1,36 +0,0 @@
-# B4 — Wizard step deduplication
-
-## Problem
-
-Greenfield wizard testing showed completed wizard steps could be executed again after the menu marked them `[done]`. In practice this made the Providers/API-key flow and Skills flow appear twice in one wizard run.
-
-There was a second related API-key duplication path: when the Providers step was completed with no key, `gatewayConfigStage` still prompted for `ANTHROPIC_API_KEY` during Finish because it only skipped the gateway API-key prompt when `providerKey` was non-empty.
-
-## Diagnosis
-
-- `runMenuLoop` labeled completed sections with `[done]`, but still dispatched the selected step again if the user selected that row.
-- Quick Start ran Providers and Skills but did not mark those sections complete in `completedSections`.
-- `runFinishPath`/`quickStartPath` defaulted `providerType` to `none` for gateway config, which made it impossible for `gatewayConfigStage` to distinguish:
-  - provider step completed and user intentionally skipped the key, vs.
-  - provider step was never run.
-
-## Fix
-
-- Added a shared menu section key helper and a completed-step guard in `runMenuLoop`.
-- Completed menu steps now log a skip message instead of re-running their stage.
-- Quick Start marks Providers and Skills complete after running them.
-- Finish/Quick Start now pass `state.providerType` as-is to gateway config instead of defaulting to `none`.
-- `gatewayConfigStage` treats `providerType: 'none'` as an explicit completed provider setup with no key and skips the second gateway API-key prompt.
-
-## Verification
-
-- Added unified wizard regression coverage asserting repeated Providers/Skills menu selections only execute each stage once.
-- Added gateway config coverage asserting `providerType: 'none'` does not prompt for a gateway API key and writes no API key env var.
-- Targeted: `pnpm --filter @mosaicstack/mosaic test -- unified-wizard gateway-config`
-- `pnpm format:check`
-- `pnpm typecheck`
-- `pnpm lint`
-- `pnpm build`
-- `pnpm test`
-- Codex code review: approve.
-- Codex security review: no findings.

docs/scratchpads/FED-M3-10-integration-tests.md

@@ -1,60 +0,0 @@
-# FED-M3-10 — Federation M3 Integration Tests
-
-## Objective
-
-Add single-gateway gateway integration tests for M3 acceptance #6 and #7.
-
-## Branch / base
-
-- Branch: `feat/federation-m3-integration`
-- Base: `origin/next` (`838701bd` after M3-06/#683 merge)
-- PR base when unblocked: `next`
-
-## Scope
-
-- Real PostgreSQL via `@mosaicstack/db`.
-- Mocked TLS context / Fastify request shim for `FederationAuthGuard`.
-- Direct controller calls using the real M3 route contract: `POST /api/federation/v1/list/:resource` with body `{ limit?, cursor? }`.
-- Gated by `FEDERATED_INTEGRATION=1`.
-- No federation harness dependency.
-
-## Fixture notes
-
-Aligned with the B2 seed design vocabulary:
-
-- `tasks` visibility uses personal `projects` + `missions` chain.
-- `notes` are `mission_tasks.notes`; the integration suite asserts subject-only note visibility on an authorized mission.
-- Seed includes a second user and unauthorized team/project tasks to prove exclusion from the max-row-cap list result.
-- Grants/peers are direct DB fixtures; cert auth still runs through `FederationAuthGuard` using real X.509 certs generated by existing test helpers.
-
-## Current implementation
-
-Added `apps/gateway/src/__tests__/integration/federation-m3-list.integration.test.ts` covering:
-
-1. M3 #6 — cert missing Mosaic OIDs returns 401 federation `unauthorized` envelope.
-2. M3 #6 — valid cert whose grant row is `revoked` returns 403 federation `forbidden` envelope.
-3. M3 #7 — active grant with `max_rows_per_query: 2` caps `list tasks`, returns `_truncated` + `nextCursor`, source-tags rows, and excludes other-user / unauthorized-team tasks.
-4. Cross-user notes invariant — subject can list their own `mission_tasks.notes` row while another user's note on the same authorized mission is excluded.
-5. Unsupported-resource invariant — `list widgets` fails closed with a federation `scope_violation` envelope.
-
-## Verification
-
-- `pnpm --filter @mosaicstack/types build` — PASS.
-- `pnpm --filter @mosaicstack/db build` — PASS.
-- `pnpm --filter @mosaicstack/storage build` — PASS.
-- `pnpm --filter @mosaicstack/brain build` — PASS.
-- `pnpm --filter @mosaicstack/queue build` — PASS.
-- `pnpm --filter @mosaicstack/config build` — PASS.
-- `pnpm --filter @mosaicstack/auth build` — PASS.
-- `pnpm --filter @mosaicstack/gateway test -- src/__tests__/integration/federation-m3-list.integration.test.ts` — PASS skipped when `FEDERATED_INTEGRATION` unset (5 skipped).
-- `FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test -- src/__tests__/integration/federation-m3-list.integration.test.ts` — PASS (5 tests) after local `docker compose up -d postgres` + `pnpm --filter @mosaicstack/db db:push`.
-- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
-- `pnpm --filter @mosaicstack/gateway lint` — PASS.
-- `pnpm format:check` — PASS.
-- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS; approve, no findings.
-- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS; risk level none, no findings.
-
-## Push / PR
-
-- #683 landed in `next`; branch rebased onto `origin/next` before push.
-- CI is serialized; run queue guard before push.

docs/scratchpads/installer-next-fast-npm-20260625.md

@@ -1,40 +0,0 @@
-# Installer `--next` fast npm lane — 2026-06-25
-
-## Scope
-
-Flip `tools/install.sh --next` from source-build-first to fast npm `@next` first, with source fallback.
-
-## Registry reality check
-
-Gitea npm registry: `https://git.mosaicstack.dev/api/packages/mosaicstack/npm/`
-
-Verified before implementation:
-
-- `@mosaicstack/mosaic@next` resolves to `0.0.49-next.1633`.
-- `@mosaicstack/gateway@next` resolves to `0.0.7-next.1633`.
-- `@mosaicstack/gateway` dist-tags include `latest: 0.0.6` and `next: 0.0.7-next.1633`.
-- `apps/gateway/package.json` is non-private and has Gitea npm `publishConfig`.
-
-Conclusion: the installer can fast-install both CLI and gateway npm packages for `--next`. The gateway Docker `gateway:sha-<short>` remains the deployment/harness artifact; the npm gateway package is valid for the installer global package path.
-
-## Behavior
-
-- `--next` with no explicit ref:
-  1. framework archive from `next`;
-  2. resolve `@mosaicstack/gateway@next` and `@mosaicstack/mosaic@next`;
-  3. require both resolved versions to share the same `next.<pipeline>` suffix;
-  4. install the exact resolved package versions;
-  5. set `MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1` so wizard does not overwrite the prerelease gateway;
-  6. if either package is missing/unreachable/mismatched/fails, fall back to existing source build at `next`.
-- `--dev` remains pure source build.
-- explicit `--ref` / `MOSAIC_REF` still wins over `--next` and uses the source path for that exact ref.
-
-## Install detail
-
-The installer writes the scoped npmrc mapping (`@mosaicstack:registry=...`) and then runs npm install without overriding npm's default registry. Passing `--registry=<gitea>` to `npm install` forces public transitive dependencies (for example `@anthropic-ai/sdk`) to resolve from Gitea and breaks the fast path; the scoped npmrc mapping is the correct split-registry behavior.
-
-## Verification notes
-
-- Added `tools/install-next-lane.test.sh` with a fake npm/source harness for exact-version fast install, registry failure source fallback, explicit-ref precedence, and mismatched suffix warning.
-- Wired the installer harness into `pnpm test` via `pnpm run test:installer`.
-- Real temp-prefix fast install succeeded with `@mosaicstack/[email protected]` and `@mosaicstack/[email protected]`.

docs/scratchpads/installer-next-lane-20260624.md

@@ -1,35 +0,0 @@
-# Scratchpad — installer `--next` lane
-
-## Objective
-
-Add a prerelease installer lane for the permanent `next` integration branch.
-
-## Scope
-
-- `tools/install.sh`
-- README/install documentation
-- Follow-up design note for future npm `@next` prerelease publishing
-
-## Plan
-
-1. Add `--next` and `MOSAIC_NEXT=1` as source-build shorthand for `next`.
-2. Preserve explicit ref precedence: `MOSAIC_REF` and `--ref` win over `--next`.
-3. Update installer source display/help text.
-4. Document three lanes:
-   - stable npm `@latest`
-   - prerelease `--next`
-   - contributor `--dev --ref X`
-5. Run shell and repo gates locally, then hold before push/PR until runner serialization greenlight.
-
-## Verification
-
-- `bash -n tools/install.sh` — pass.
-- `docker run --rm -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:stable tools/install.sh` — pass.
-- `bash tools/install.sh --check --framework --next` — source display shows `ref: next, --next prerelease lane`.
-- `bash tools/install.sh --check --cli --next --ref feature-x` — source display shows explicit ref wins.
-- `MOSAIC_NEXT=1 MOSAIC_REF=feature-env bash tools/install.sh --check --cli` — source display shows explicit env ref wins.
-- `pnpm install --frozen-lockfile --prefer-offline --store-dir /home/jarvis/.local/share/pnpm/store` — pass (local override for repo `.npmrc` CI store path).
-- `pnpm typecheck` — pass (41 successful tasks).
-- `pnpm lint` — pass (23 successful tasks).
-- `pnpm format:check` — pass.
-- `bash tools/e2e-install-test.sh` — attempted; current baseline fails during gateway health after stable registry install because Valkey is unavailable in the clean container. The `tools/install.sh --yes --no-auto-launch` stage itself completed before the downstream gateway verification failure.

docs/scratchpads/lease-remediation/dispatch/measure-W-B.md

@@ -1,93 +0,0 @@
-# W-B — Measure Pi's real tool registry
-
-- **Task / internal ref:** W-B from the lease-remediation orchestrator brief (no matching `docs/TASKS.md` row; workers do not modify that file)
-- **Objective:** identify the exact tool names emitted as `event.toolName` by the installed Pi runtime and compare them with the broker's Pi read-only carve-out.
-- **Scope:** measurement and report only; no broker or runtime source changes. W-C is out of scope.
-- **Budget:** no explicit token cap; constrained to this scratchpad and one local commit.
-- **Installed runtime:** `@earendil-works/pi-coding-agent` / `pi` `0.84.1`.
-
-## Method
-
-I created a throwaway extension at `/tmp/measure-pi-tool-registry.ts` (not in the worktree). On `session_start` it recorded `pi.getAllTools()` and `pi.getActiveTools()`; on every `tool_call` it appended the exact `event.toolName`. I then launched an isolated, ephemeral Pi session with all built-ins explicitly selected:
-
-```text
-PI_OFFLINE=1 pi --mode print --no-session --no-approve \
-  --no-context-files --no-skills --no-prompt-templates --no-extensions \
-  -e /tmp/measure-pi-tool-registry.ts \
-  --tools read,bash,edit,write,grep,find,ls <deterministic probe prompt>
-```
-
-The prompt exercised file read, content search, file search, directory listing, shell execution, file write, and file edit. Pi exited `0`; every selected tool produced one `tool_call`. The write/edit control artifact ended with exact content `after`, proving the mutating calls executed in order.
-
-This runtime observation was cross-checked against the installed distribution's canonical registry at `dist/core/tools/index.js:17`, which declares the same seven names. The gate consumes the measured field directly at `packages/mosaic/framework/runtime/pi/mosaic-extension.ts:368`.
-
-## Exact distinct built-in set
-
-The installed Pi built-in registry is exactly:
-
-```text
-{bash, edit, find, grep, ls, read, write}
-```
-
-| Tool | Runtime registry observation | `tool_call` observation | Installed definition |
-| --- | --- | --- | --- |
-| `read` | `<builtin:read>` | observed once | `dist/core/tools/read.js:138` |
-| `bash` | `<builtin:bash>` | observed once | `dist/core/tools/bash.js:231` |
-| `edit` | `<builtin:edit>` | observed once | `dist/core/tools/edit.js:170` |
-| `write` | `<builtin:write>` | observed once | `dist/core/tools/write.js:138` |
-| `grep` | `<builtin:grep>` | observed once | `dist/core/tools/grep.js:79` |
-| `find` | `<builtin:find>` | observed once | `dist/core/tools/find.js:79` |
-| `ls` | `<builtin:ls>` | observed once | `dist/core/tools/ls.js:61` |
-
-The raw distinct `event.toolName` result was:
-
-```json
-["bash", "edit", "find", "grep", "ls", "read", "write"]
-```
-
-Pi registers all seven, but its default active set is only `read`, `bash`, `edit`, and `write` (`dist/core/sdk.js:132`). The probe explicitly activated all seven so the three search/list tools could be observed at the hook.
-
-## Positive control
-
-The known `read` tool was the control. The method surfaced it twice:
-
-1. `pi.getAllTools()` returned `read` with source path `<builtin:read>`.
-2. Reading `/tmp/pi-registry-probe/seed.txt`, which contained `CONTROL_TOKEN`, produced one hook record with `event.toolName === "read"`.
-
-The control was therefore positive; the seven-name result is measured, not an empty-probe inference.
-
-## Carve-out comparison and collision result
-
-The broker currently declares `{"read", "grep", "find", "ls"}` at `packages/mosaic/framework/tools/lease-broker/daemon.py:54`.
-
-- `read`: real built-in.
-- `grep`: real built-in.
-- `find`: real built-in.
-- `ls`: real built-in.
-
-All four carve-out names are exact, case-sensitive Pi tool names.
-
-The general execution/writing tool names are `bash`, `edit`, and `write`. Their intersection with the carve-out is empty:
-
-```text
-{bash, edit, write} ∩ {read, grep, find, ls} = ∅
-```
-
-Therefore no general shell-exec or file-mutating Pi tool shares a name with a carve-out entry. `grep` and `find` may invoke constrained search helpers internally, but neither exposes an arbitrary command interface; the arbitrary command tool is distinctly named `bash`.
-
-The Mosaic extension separately registers the non-built-in custom tool `mosaic_context_recover` at `packages/mosaic/framework/runtime/pi/mosaic-extension.ts:379`; the broker handles that identity through its dedicated recovery exemption rather than the read-only set (`daemon.py:722`). Unknown or third-party custom tools are not part of Pi's built-in seven-name registry and remain outside the carve-out.
-
-## Verification evidence
-
-- `pi --version` → `0.84.1`.
-- Isolated probe exit → `0`.
-- Runtime `getAllTools()` count → `7`, all with `sourceInfo.source === "builtin"`.
-- Distinct hook names → `bash`, `edit`, `find`, `grep`, `ls`, `read`, `write`.
-- Hook counts → exactly one call for each of the seven names.
-- Mutation artifact after `write` then `edit` → exact content `after`.
-- Installed registry source → `allToolNames = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"])`.
-
-## Risks / limitations
-
-- The probe deliberately disabled all other extensions, so extension-defined third-party tools were excluded from the built-in registry measurement. The production gate still receives those names and treats names outside the broker carve-out as mutating/fail-closed.
-- Explicit `--tools` activation was required to exercise `grep`, `find`, and `ls`; this does not imply they are active in Pi's default four-tool configuration.

docs/scratchpads/pr-merge-message-field.md

@@ -1,99 +0,0 @@
-# PR merge squash message field
-
-- **Charter:** `/home/hermes/agent-work/CHARTER-PRMERGE-MESSAGE-FIELD.md`
-- **Owner:** `be-coder-08`
-- **Branch:** `fix/pr-merge-message-field`
-- **Base:** remote `main` / local `origin/main` at `85d2108e4ed15c744ad3b87a5b629e7b2d39405a`
-- **Estate:** HOMELAB tooling shared by HOMELAB and USC
-
-## Objective
-
-Add an optional, identity-checked Gitea squash message to `pr-merge.sh` so genuine multi-author PRs retain non-poster branch authors without weakening hardcoded squash behavior.
-
-## Binding requirements
-
-1. `Do` remains hardcoded to `squash`; no provider/repository default may select merge style.
-2. A verified trailer uses a PR commit's linked `author.login` and that same commit's author email. No `/users/{login}` primary-email lookup occurs. Recorded rationale: this asks only what the provider can answer.
-3. A commit with `author.login` null blocks before merge, prints both the null provider fact and commit email fact, and names the escalation principal.
-4. The BLOCK arm must be observed firing; a normal canonical single-author API payload remains explicit squash plus its reviewed `head_commit_id`.
-5. Every provider mutation is read back from the provider; no real PR is merged during tests.
-
-## Derived interface decisions
-
-- Add `--co-author-trailers` rather than accepting arbitrary message text. The wrapper enumerates PR commits and constructs trailers, making an unchecked `Co-authored-by` line unexpressible.
-- Require `--escalate-to PRINCIPAL` with `--co-author-trailers`, so the BLOCK diagnostic always names a principal rather than a generic role.
-- Do not expose `MergeTitleField` separately. When trailers exist, set it from the provider PR title and set `MergeMessageField` only to construction-generated trailers. This preserves one provider source for the title and avoids an unrelated caller-controlled degree of freedom.
-- Preserve first-commit order and emit one trailer per distinct non-poster `author.login`, using that first linked commit's own email.
-
-## Canonical delivery plan
-
-1. Port the capability into the installed source of truth, `packages/mosaic/framework/tools/git/pr-merge.sh`; do not retain `infra/fleet/tools/git` as a second copy.
-2. Preserve canonical `--expect-head`, exact head branch/repository/SHA queue inspection, Gitea atomic head pinning, GitHub `--match-head-commit`, and delete-after-merge semantics.
-3. Do not port the deployed-only `--skip-queue-guard` bypass. Add the focused harness to the canonical framework-shell suite and re-establish RED/GREEN on the packaged baseline.
-4. Deliver through a reviewed package release followed by `mosaic update` with its default framework reseed. The installer snapshots, manifest-syncs framework-owned `tools/**`, and rolls back on failure.
-5. Before either estate relies on the change, require installed/package hash equality, `MergeMessageField` presence, and a green focused harness. Release/reseed ownership is currently unassigned and blocks activation after source merge.
-
-## Evidence
-
-- RED against the byte-identical deployed baseline (`sha256 08a65e8584c5…`): rc 1 with eight named failures. The wrapper rejected `--co-author-trailers`; the null-login path emitted none of the required BLOCK facts/principal; and both verified/ordinary API paths failed the stdin-config credential assertion (ordinary path exposed the fixture token through curl argv). Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-red.log`.
-- GREEN on the deployed-baseline candidate: verified linked multi-author payload, null-login BLOCK, required named principal, explicit squash, stdin-config token transport, and absence of `/users` lookup all passed. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-green.log`.
-- RED against canonical packaged baseline `c581ef48…`: rc 1 with 32 assertions. It rejects the new option, and the first harness version did not satisfy canonical head branch/repository/SHA metadata. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-packaged-baseline-red.log`. The port adapts the fixture rather than weakening canonical head controls.
-- Provider capability probe against `git.mosaicstack.dev`: authenticated `be-coder-08` POST to deliberately nonexistent PR `2147483647` with both message fields returned JSON HTTP 404; the unauthenticated same request returned JSON HTTP 401 (not the charter's predicted 403). The authenticated-vs-unauthenticated differential proves write authorization resolved while no mergeable subject existed. `tl-mosaic` ruled the literal non-load-bearing: preserve the observed 404/401 pair and do not manufacture a 403 case. No cause was inferred and no real PR was targeted.
-- Provider-generated trailer behavior is not treated as exclusive or absent. The wrapper's VERIFIED/BLOCK decision binds each requested non-poster trailer to commit `author.login` plus that commit's email; it does not assume `MergeMessageField` is the squash's only trailer source. The poster is omitted from the constructed list because the resulting squash author already records the poster; any additional provider-generated trailer is outside this change's unmeasured mechanism.
-- An early candidate SHA-256 `5de32876990e4f26920448cb3220cc7f1146d558b4dd2bc1ee1a2abee2f2cbe6` passed the initial harness, then author-side review found credential-fallback and argv-exposure defects. The live deployed wrapper was atomically restored to baseline SHA-256 `08a65e8584c52c6d41ea1c686f8b95585c21e4b37320a2447eba09359a0e02c1`; the remediated candidate remains only in the worktree.
-
-## Remediation and current review state
-
-1. Token and Basic Auth now use stdin curl configuration, not argv. PR title, contributor email, and the JSON payload also remain out of child argv.
-2. Each credential attempt binds commit inspection and merge. A token failure during either inspection or mutation causes Basic fallback to repeat inspection before mutation; the payload pins the inspected `head_commit_id`.
-3. Focused tests cover token-resolution fail-closed behavior, both HTTP-401 fallback seams, metadata/credential argv absence, null-login BLOCK, explicit squash, canonical reviewed-head binding, unchanged ordinary payload, and retained log-safe provider diagnostics. Token-resolution RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-token-resolution-red.log`.
-4. Codex review rounds 3–5 requested retained provider error text, log-safe provider diagnostics, fail-closed credential fallback, stable value-option parsing, and PR-title trailer-injection prevention. These are remediated with regression assertions. A post-remediation independent review is still required.
-5. **Accepted linkage limitation:** `author.login` resolution proves that the commit address maps to a registered provider account. It does not prove that the named principal authored the commit because Git author metadata is self-asserted. This gate checks attribution linkage, not authorship; commit signing is out of scope and currently unadopted. Coordinators explicitly ruled that this does not add a third state.
-6. Codex's sandbox could not execute the harness because its checkout was read-only; that environmental limitation is recorded separately from host-side test results.
-
-## Disposable provider fixture acceptance
-
-- Use a retained scratch repository only, with two branch authors and `author != committer` on at least one commit.
-- Arm A supplies a message-field trailer for one non-poster; record whether that value lands without forcing the partial-pair result into under-specified `APPENDS`/`REPLACES` labels. Demonstrate an absence control.
-- Arm B includes a registered trailer for a different non-poster on a branch commit; record whether it survives or drops. Verify identity through an existing commit whose `author.login` resolves and demonstrate an absence control.
-- Parse landed trailers key-agnostically with `^[A-Za-z-]+-[Bb]y:` and record generated poster pair presence/absence plus resulting poster attribution.
-- Record `/users/<login>` status and raw email only as non-gating estate telemetry. Never read `active`, `visibility`, or any profile field as an identity gate.
-- Use distinct principals: poster `be-coder-08`, merger `Mos`, Arm A `be-coder-07`, and Arm B `be-coder-06`. Capture every trailer-shaped line verbatim and in order. Zero trailer lines means the generator did not fire and the run is `VOID`, not evidence that either arm dropped.
-- Report the same read-back evidence to `mos-claude` on socket `default` and `tl-mosaic` on socket `mosaic-fleet`. Report values rather than mechanism inferences and stop on any poster-attribution regression.
-
-## Fixture preflight
-
-- Retained public repository: `mosaicstack/prmerge-trailer-fixture`; PR `#1`, posted by `be-coder-08` and reserved for merge by `Mos`.
-- Existing `mosaicstack/stack` commits resolve `be-coder-07` and `be-coder-06` through `author.login`; exact addresses are `[email protected]` and `[email protected]`.
-- Non-gating HOMELAB telemetry for authenticated reader `be-coder-08`: `/api/v1/users/be-coder-06` returned HTTP 200 with raw `email` value `[email protected]`.
-- Provider preflight showed PR commit enumeration is newest-first. A new RED test proved that deriving `head_commit_id` from the final array element selected the wrong commit. The candidate now reads `.head.sha` from the authenticated PR endpoint before enumeration, verifies it appears in the commit set, and atomically pins that SHA in the explicit squash payload. RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-head-order-red.log`.
-- Fixture PR head `f6ba6e5105031fa21f5ff7bd8e4379d99c16e1de` has `author.login=be-coder-07`, `committer.login=be-coder-08`, and branch-message trailer `Co-authored-by: be-coder-06 <[email protected]>`.
-
-## Fixture result
-
-- `Mos` merged retained fixture PR `#1` through staged candidate SHA-256 `60e779a85fd13b729d859ea7c986d1e9b1641b97991611329226c1b3113ffb6e`; resulting squash commit: `3f550715d9bc716426fd355a65fe997b3a90fa7d` with one parent.
-- Provider read-back: poster/commit author `be-coder-08`, committer/merger `Mos`. The run is non-void.
-- Trailer-shaped lines, verbatim and in order:
-  1. `Co-authored-by: be-coder-07 <[email protected]>`
-  2. `Co-authored-by: be-coder-08 <[email protected]>`
-- Arm A supplied field value (`be-coder-07`) landed. Arm B branch trailer (`be-coder-06`) dropped. Both fabricated absence controls remained absent. No `Co-committed-by:` line landed.
-- The candidate payload construction explicitly excludes the poster and supplied only the Arm A `be-coder-07` line. Therefore the landed poster line was provider-generated, not candidate-composed. The raw result supports `FIELD LANDS`, `BRANCH DROPS`, and `POSTER GENERATED`; it does not support a claim that candidate code supplied the poster. Evidence: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-fixture-readback.log` and the retained provider object.
-- Retained fixture PR `#2` measured the N=2 shape needed by `#1030`: supplied `be-coder-07` then `be-coder-06`; both landed in that order, followed by the provider-generated poster line. No truncation or dedup occurred at N=2. Resulting squash: `39db9d13aed0…`.
-
-## Current hold point
-
-PR `mosaicstack/stack#1066` is open. Its first frozen head `f4b162fa…` was terminal-green in Woodpecker `mosaic` pipeline `#2225`, but that evidence becomes stale when the canonical port moves the head. The deployed wrapper remains baseline `08a65e85…`; no manual copy will occur. Canonical port tests, commit amendment, rebase, one guarded force-with-lease, exact-head CI, and new independent review remain. Even after source merge, activation remains blocked on an assigned package-release/reseed owner and installed-byte read-back.
-
-## Security review 96 remediation
-
-Exact reviewed predecessor head: `1ceb11058f64dd7f4a817ceb2124f980a1c4dd23`.
-
-RED-first focused harness produced 10 named failures: all curl calls lacked size/time/connect bounds; raw ESC email reached mutation; oversized and stalled curl failures were discarded and reached mutation; nonempty Basic output with resolver rc 91 authorized mutation.
-
-Security remediation:
-
-- Removed the cross-principal HTTP-401 Basic fallback. Both inspection-401 and merge-401 paths now refuse without Basic resolution or mutation; `get_gitea_basic_auth` references in the merge subject are 0.
-- Applied `--max-filesize`, `--max-time`, and `--connect-timeout` to all 3/3 provider curl sites and fail closed on curl transport rc at all 3/3 sites.
-- Required linked email bytes to be ASCII and printable before constructing `MergeMessageField`; guarded construction sites 1/1.
-
-GREEN: message-field, exact-head, empty-UID/API, queue branch/repository/SHA, bash syntax, ShellCheck, and diff check pass. R7 total-removal mutants went RED: email guard 3 rows; bound switches 1 row; transport-rc guards 4 rows; HTTP-401 refusal 3 rows. R7 bound: mutants prove total removal only; explicit denominators above prove site coverage.

package.json

@@ -10,8 +10,7 @@
     "clean:generated": "node scripts/clean-generated.mjs",
     "typecheck": "pnpm preflight && turbo run typecheck",
     "test:checkout": "node --test scripts/*.test.mjs",
-    "test": "pnpm test:checkout && turbo run test && pnpm run test:installer",
-    "test:installer": "bash tools/install-next-lane.test.sh",
+    "test": "pnpm test:checkout && turbo run test",
     "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
     "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\"",
     "prepare": "node scripts/install-hooks.mjs"

packages/mosaic/__tests__/integration/unified-wizard.test.ts

@@ -11,37 +11,9 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { HeadlessPrompter } from '../../src/prompter/headless-prompter.js';
 import { createConfigService } from '../../src/config/config-service.js';
-import type { SelectOption } from '../../src/prompter/interface.js';
-import type { MenuSection, WizardState } from '../../src/types.js';
 
 const gatewayConfigMock = vi.fn();
 const gatewayBootstrapMock = vi.fn();
-const providerSetupMock = vi.fn();
-const skillsSelectMock = vi.fn();
-
-class SequencedMenuPrompter extends HeadlessPrompter {
-  constructor(
-    answers: Record<string, string | boolean | string[]>,
-    private readonly menuChoices: string[],
-  ) {
-    super(answers);
-  }
-
-  override async select<T>(opts: {
-    message: string;
-    options: SelectOption<T>[];
-    initialValue?: T;
-  }): Promise<T> {
-    if (opts.message === 'What would you like to configure?') {
-      const next = this.menuChoices.shift();
-      if (!next) throw new Error('No queued menu choice left');
-      const match = opts.options.find((o) => String(o.value) === next);
-      if (!match) throw new Error(`Queued menu choice not available: ${next}`);
-      return match.value;
-    }
-    return super.select(opts);
-  }
-}
 
 vi.mock('../../src/stages/gateway-config.js', () => ({
   gatewayConfigStage: (...args: unknown[]) => gatewayConfigMock(...args),
@@ -51,14 +23,6 @@ vi.mock('../../src/stages/gateway-bootstrap.js', () => ({
   gatewayBootstrapStage: (...args: unknown[]) => gatewayBootstrapMock(...args),
 }));
 
-vi.mock('../../src/stages/provider-setup.js', () => ({
-  providerSetupStage: (...args: unknown[]) => providerSetupMock(...args),
-}));
-
-vi.mock('../../src/stages/skills-select.js', () => ({
-  skillsSelectStage: (...args: unknown[]) => skillsSelectMock(...args),
-}));
-
 // Import AFTER the mocks so runWizard picks up the mocked stage modules.
 import { runWizard } from '../../src/wizard.js';
 
@@ -80,16 +44,6 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
     }
     gatewayConfigMock.mockReset();
     gatewayBootstrapMock.mockReset();
-    providerSetupMock.mockReset();
-    skillsSelectMock.mockReset();
-    providerSetupMock.mockImplementation(async (_p: HeadlessPrompter, state: WizardState) => {
-      state.providerType = 'none';
-      state.completedSections?.add('providers' satisfies MenuSection);
-    });
-    skillsSelectMock.mockImplementation(async (_p: HeadlessPrompter, state: WizardState) => {
-      state.selectedSkills = [];
-      state.completedSections?.add('skills' satisfies MenuSection);
-    });
     // Pretend we're on an interactive TTY so the wizard's headless-abort
     // branch does not call `process.exit(1)` during these tests.
     Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
@@ -144,12 +98,8 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
     expect(bootstrapCall[2]).toMatchObject({ host: 'localhost', port: 14242 });
   });
 
-  it('prints the success summary only after gateway health succeeds', async () => {
-    gatewayConfigMock.mockImplementation(async (p: HeadlessPrompter) => {
-      p.log('Gateway is healthy.');
-      return { ready: true, host: 'localhost', port: 14242 };
-    });
-    gatewayBootstrapMock.mockResolvedValue({ completed: true });
+  it('does not invoke bootstrap when config stage reports not ready', async () => {
+    gatewayConfigMock.mockResolvedValue({ ready: false });
 
     const prompter = new HeadlessPrompter({
       'Installation mode': 'quick',
@@ -168,43 +118,6 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
       skipGatewayNpmInstall: true,
     });
 
-    const logs = prompter.getLogs();
-    const healthIndex = logs.findIndex((line) => line.includes('Gateway is healthy.'));
-    const summaryIndex = logs.findIndex((line) => line.includes('Installation Summary'));
-    const readyIndex = logs.findIndex((line) => line.includes('Mosaic is ready.'));
-
-    expect(healthIndex).toBeGreaterThanOrEqual(0);
-    expect(summaryIndex).toBeGreaterThan(healthIndex);
-    expect(readyIndex).toBeGreaterThan(summaryIndex);
-  });
-
-  it('does not claim success when gateway health reports not ready', async () => {
-    gatewayConfigMock.mockImplementation(async (p: HeadlessPrompter) => {
-      p.warn('Gateway did not become healthy within 30 seconds.');
-      return { ready: false };
-    });
-
-    const prompter = new HeadlessPrompter({
-      'Installation mode': 'quick',
-      'What name should agents use?': 'TestBot',
-      'Communication style': 'direct',
-      'Your name': 'Tester',
-      'Your pronouns': 'They/Them',
-      'Your timezone': 'UTC',
-    });
-
-    await runWizard({
-      mosaicHome: tmpDir,
-      sourceDir: tmpDir,
-      prompter,
-      configService: createConfigService(tmpDir, tmpDir),
-      skipGatewayNpmInstall: true,
-    });
-
-    const logs = prompter.getLogs();
-    expect(logs.some((line) => line.includes('Gateway did not become healthy'))).toBe(true);
-    expect(logs.some((line) => line.includes('Installation Summary'))).toBe(false);
-    expect(logs.some((line) => line.includes('Mosaic is ready.'))).toBe(false);
     expect(gatewayConfigMock).toHaveBeenCalledTimes(1);
     expect(gatewayBootstrapMock).not.toHaveBeenCalled();
   });
@@ -230,34 +143,4 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
     expect(gatewayConfigMock).not.toHaveBeenCalled();
     expect(gatewayBootstrapMock).not.toHaveBeenCalled();
   });
-
-  it('does not re-run completed provider or skills menu steps', async () => {
-    const prompter = new SequencedMenuPrompter(
-      {
-        'What name should agents use?': 'TestBot',
-        'Communication style': 'direct',
-        'Your name': 'Tester',
-        'Your pronouns': 'They/Them',
-        'Your timezone': 'UTC',
-      },
-      ['providers', 'providers', 'skills', 'skills', 'finish'],
-    );
-
-    await runWizard({
-      mosaicHome: tmpDir,
-      sourceDir: tmpDir,
-      prompter,
-      configService: createConfigService(tmpDir, tmpDir),
-      skipGateway: true,
-    });
-
-    expect(providerSetupMock).toHaveBeenCalledTimes(1);
-    expect(skillsSelectMock).toHaveBeenCalledTimes(1);
-    expect(prompter.getLogs()).toEqual(
-      expect.arrayContaining([
-        expect.stringContaining('Providers [done] is already complete; skipping.'),
-        expect.stringContaining('Skills [done] is already complete; skipping.'),
-      ]),
-    );
-  });
 });

packages/mosaic/framework/defaults/README.md

@@ -43,16 +43,6 @@ The installer:
 - Runs a health audit
 - Detects existing installs and preserves local files (SOUL.md, USER.md, etc.)
 
-### Install lanes
-
-| Lane                     | Command                               | Use when                                       | Source                                                                                       |
-| ------------------------ | ------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Stable                   | `bash tools/install.sh`               | You want the released framework and CLI        | npm `@mosaicstack/mosaic@latest` + `main`                                                    |
-| Prerelease integration   | `bash tools/install.sh --next`        | You want the permanent `next` integration lane | Fast npm `@mosaicstack/mosaic@next` + `@mosaicstack/gateway@next`; source fallback at `next` |
-| Contributor/source build | `bash tools/install.sh --dev --ref X` | You are validating a branch before release     | Build-from-source at the requested git ref                                                   |
-
-`--next` is fast-by-default from the Gitea npm `next` dist-tag and falls back to a source build at the permanent `next` branch if the dist-tag is missing or unreachable. Explicit `--ref` or `MOSAIC_REF` wins and uses the source path.
-
 ## First Run
 
 After install, open a new terminal (or `source ~/.bashrc`) and run:
@@ -118,8 +108,8 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
 ├── TOOLS.md               ← Machine-level tool reference (generated by mosaic init)
 ├── STANDARDS.md           ← Machine-wide standards
 ├── guides/                ← Operational guides (E2E delivery, PRD, docs, etc.)
+├── bin/                   ← CLI tools (mosaic launcher, mosaic-init, mosaic-doctor, etc.)
 ├── tools/                 ← Tool suites: git, orchestrator, prdy, quality, etc.
-│   └── _scripts/          ← Framework helper scripts (sync skills, doctor, runtime links)
 ├── runtime/               ← Runtime adapters + runtime-specific references
 │   ├── claude/            ← CLAUDE.md, RUNTIME.md, settings.json, hooks
 │   ├── codex/             ← instructions.md, RUNTIME.md
@@ -184,9 +174,7 @@ The installer preserves local `SOUL.md`, `USER.md`, `TOOLS.md`, and `memory/` by
 bash tools/install.sh --check       # Version check only
 bash tools/install.sh --framework   # Framework only (skip npm CLI)
 bash tools/install.sh --cli         # npm CLI only (skip framework)
-bash tools/install.sh --next        # Prerelease lane: npm @next, source fallback
-bash tools/install.sh --dev         # Contributor lane: source build at --ref/main
-bash tools/install.sh --ref v1.0    # Install from a specific git ref (--ref wins over --next)
+bash tools/install.sh --ref v1.0    # Install from a specific git ref
 ```
 
 The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
@@ -196,11 +184,10 @@ The installer rejects unrecognized flags or positional arguments before making c
 The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`. Install, wizard finalization, and `mosaic update` automatically reconcile every canonical skill into Claude Code's `~/.claude/skills/` directory.
 
 ```bash
-mosaic sync                                                   # Full canonical catalog sync
-~/.config/mosaic/tools/_scripts/mosaic-sync-skills --link-only # Re-link only
-mosaic skill list                                              # Show registered, missing, dangling, and foreign entries
-mosaic skill register <name>                                   # Register or repair one canonical Claude link
-mosaic skill unregister <name>                                 # Remove one Mosaic-owned Claude link
+mosaic sync                         # Full canonical catalog sync
+mosaic skill list                   # Show registered, missing, dangling, and foreign entries
+mosaic skill register <name>        # Register or repair one canonical Claude link
+mosaic skill unregister <name>      # Remove one Mosaic-owned Claude link
 ```
 
 Skill names are direct children using `[A-Za-z0-9][A-Za-z0-9._-]*`, not paths. Registration rejects traversal/control characters and never replaces foreign files, directories, or symlinks; unregister removes only links that point inside the canonical Mosaic skill root. After registering during a running Claude Code session, use `/reload-skills` or start a new session.
@@ -210,8 +197,8 @@ M1 lifecycle management targets Claude Code. Pi can discover the canonical Mosai
 ## Health Audit
 
 ```bash
-mosaic doctor                                           # Standard audit
-~/.config/mosaic/tools/_scripts/mosaic-doctor --fail-on-warn      # Strict mode
+mosaic doctor                                          # Standard audit
+~/.config/mosaic/bin/mosaic-doctor --fail-on-warn      # Strict mode
 ```
 
 ## MCP Registration
@@ -222,8 +209,8 @@ sequential-thinking MCP is required for Mosaic Stack. The installer registers it
 To verify or re-register manually:
 
 ```bash
-~/.config/mosaic/tools/_scripts/mosaic-ensure-sequential-thinking
-~/.config/mosaic/tools/_scripts/mosaic-ensure-sequential-thinking --check
+~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
+~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
 ```
 
 ### Claude Code MCP Registration

packages/mosaic/framework/runtime/claude/commands/mosaic-promote.md

@@ -1 +0,0 @@
-Mosaic lease promotion was processed mechanically; no action is needed.

packages/mosaic/framework/runtime/claude/settings.json

@@ -32,18 +32,6 @@
         ]
       }
     ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "^/mosaic-promote$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ~/.config/mosaic/tools/lease-broker/promote-begin.py",
-            "timeout": 15
-          }
-        ]
-      }
-    ],
     "PreToolUse": [
       {
         "matcher": ".*",
@@ -93,8 +81,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ~/.config/mosaic/tools/lease-broker/receipt-observer-client.py --runtime claude --latest-entry; observer_status=$?; python3 ~/.config/mosaic/tools/lease-broker/promote-complete.py; exit $observer_status",
-            "timeout": 15
+            "command": "python3 ~/.config/mosaic/tools/lease-broker/receipt-observer-client.py --runtime claude --latest-entry",
+            "timeout": 3
           },
           {
             "type": "command",

packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets

@@ -233,14 +233,6 @@ for runtime_file in \
   copy_file_managed "$src" "$HOME/.claude/$runtime_file"
 done
 
-if [[ -d "$MOSAIC_HOME/runtime/claude/commands" ]]; then
-  mkdir -p "$HOME/.claude/commands"
-  for command_file in "$MOSAIC_HOME/runtime/claude/commands/"*; do
-    [[ -f "$command_file" ]] || continue
-    copy_file_managed "$command_file" "$HOME/.claude/commands/$(basename "$command_file")"
-  done
-fi
-
 # OpenCode runtime adapter (thin pointer to AGENTS.md)
 opencode_adapter="$MOSAIC_HOME/runtime/opencode/AGENTS.md"
 if [[ -f "$opencode_adapter" ]]; then

packages/mosaic/framework/tools/_scripts/mosaic-sync-skills

@@ -153,24 +153,7 @@ if [[ $link_only -eq 1 ]]; then
   exit 0
 fi
 
-# Skills are linked into the MOSAIC-OWNED harness homes, never a base install.
-# Paths mirror the config-dir env vars the launcher injects (HARNESS_HOME_ENV in
-# commands/launch.js):
-#   claude   CLAUDE_CONFIG_DIR      -> <home>/skills
-#   pi       PI_CODING_AGENT_DIR    -> <home>/skills   (replaces ~/.pi/agent)
-#   codex    CODEX_HOME             -> <home>/skills
-#   opencode XDG_CONFIG_HOME        -> <home>/opencode/skills  (XDG adds a level)
 link_targets=(
-  "$MOSAIC_HOME/.claude/skills"
-  "$MOSAIC_HOME/.codex/skills"
-  "$MOSAIC_HOME/.opencode/opencode/skills"
-  "$MOSAIC_HOME/.pi/skills"
-)
-
-# Pre-isolation installs planted the same symlink farm directly in the operator's
-# base installs. Those are now orphaned: the launcher no longer reads them, but
-# they persist and make a "clean" base install look mosaic-managed.
-legacy_link_targets=(
   "$HOME/.claude/skills"
   "$HOME/.codex/skills"
   "$HOME/.config/opencode/skills"
@@ -262,72 +245,13 @@ prune_stale_links_in_target() {
     # -m resolves lexical dangling targets too. If resolution fails, ownership
     # is unproven and the link must be preserved.
     resolved="$(readlink -m "$link_path" 2>/dev/null || true)"
-    # $canonical_real must be length-checked BEFORE use as a prefix: if it were
-    # ever empty, "$resolved" == "$canonical_real/"* collapses to == "/"* and
-    # matches every absolute path. Combined with the is_mosaic_skill_name skip
-    # above, that inverts the function precisely — it would delete exactly the
-    # FOREIGN symlinks and keep the mosaic ones. (#1087, reported by mos-claude.)
-    if [[ -n "$resolved" && -n "$canonical_real" && "$resolved" == "$canonical_real/"* ]]; then
+    if [[ -n "$resolved" && "$resolved" == "$canonical_real/"* ]]; then
       rm -f "$link_path"
       echo "[mosaic-skills] Removed stale retired skill link: $link_path"
     fi
   done < <(find "$target_dir" -mindepth 1 -maxdepth 1 -type l -print0)
 }
 
-# Remove mosaic-owned symlinks left in a base install by a pre-isolation sync.
-#
-# Ownership is proven by RESOLUTION, not by name: only links resolving inside the
-# canonical or local skills dirs are removed. Anything else — a real directory, a
-# link elsewhere, an unresolvable link — is left untouched. This mirrors the
-# refusal in commands/skill.js ("only symlinks pointing inside the Mosaic skills
-# directory are managed") and preserves e.g. codex's own `.system` dir.
-#
-# The directory itself is kept: mosaic-doctor warns when ~/.pi/agent/skills is
-# missing, and an empty dir is the correct end state, not an absent one.
-cleanup_legacy_target() {
-  local target_dir="$1"
-  local removed=0 kept=0
-
-  [[ -d "$target_dir" ]] || return 0
-
-  while IFS= read -r -d '' link_path; do
-    local resolved owned=0
-    resolved="$(readlink -m "$link_path" 2>/dev/null || true)"
-
-    # Guard the empty-prefix trap: an unset *_real would make "$resolved" == "/"*
-    # match every absolute path and delete foreign links.
-    if [[ -n "$resolved" ]]; then
-      if [[ -n "$canonical_real" && "$resolved" == "$canonical_real/"* ]]; then
-        owned=1
-      elif [[ -n "$local_real" && "$resolved" == "$local_real/"* ]]; then
-        owned=1
-      fi
-    fi
-
-    if [[ $owned -eq 1 ]]; then
-      rm -f "$link_path"
-      removed=$((removed + 1))
-    else
-      kept=$((kept + 1))
-    fi
-  done < <(find "$target_dir" -mindepth 1 -maxdepth 1 -type l -print0)
-
-  if [[ $removed -gt 0 ]]; then
-    echo "[mosaic-skills] Legacy cleanup: removed $removed mosaic symlink(s) from $target_dir (preserved $kept foreign)"
-  fi
-}
-
-for legacy in "${legacy_link_targets[@]}"; do
-  # Skip anything that is also a current target, so isolation can never
-  # self-destruct if the two lists ever overlap.
-  skip=0
-  for target in "${link_targets[@]}"; do
-    [[ "$legacy" == "$target" ]] && skip=1
-  done
-  [[ $skip -eq 1 ]] && continue
-  cleanup_legacy_target "$legacy"
-done
-
 for target in "${link_targets[@]}"; do
   mkdir -p "$target"
 

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d]
 
 set -euo pipefail
 
@@ -14,8 +14,6 @@ MERGE_METHOD="squash"
 DELETE_BRANCH=false
 DRY_RUN=false
 EXPECT_HEAD=""
-CO_AUTHOR_TRAILERS=false
-ESCALATE_TO=""
 
 usage() {
     cat <<EOF
@@ -29,16 +27,12 @@ Options:
     -d, --delete-branch     Delete the head branch after merge
         --dry-run           Run metadata/login preflight without merging
         --expect-head SHA   Refuse unless the PR head matches this full commit SHA
-        --co-author-trailers Build verified trailers from linked PR commit authors
-        --escalate-to NAME  Named principal for an unresolved-author BLOCK
     -h, --help              Show this help message
 
 Examples:
     $(basename "$0") -n 42                    # Merge PR #42
     $(basename "$0") -n 42 -m squash          # Squash merge
     $(basename "$0") -n 42 -d                 # Squash merge and delete branch
-    $(basename "$0") -n 42 --expect-head 0123456789abcdef0123456789abcdef01234567
-    $(basename "$0") -n 42 --co-author-trailers --escalate-to tl-mosaic
 EOF
     exit "${1:-1}"
 }
@@ -63,25 +57,9 @@ while [[ $# -gt 0 ]]; do
             shift
             ;;
         --expect-head)
-            if [[ $# -lt 2 ]]; then
-                echo "Error: --expect-head requires one full commit SHA." >&2
-                exit 1
-            fi
             EXPECT_HEAD="$2"
             shift 2
             ;;
-        --co-author-trailers)
-            CO_AUTHOR_TRAILERS=true
-            shift
-            ;;
-        --escalate-to)
-            if [[ $# -lt 2 ]]; then
-                echo "Error: --escalate-to requires one principal name." >&2
-                exit 1
-            fi
-            ESCALATE_TO="$2"
-            shift 2
-            ;;
         -h|--help)
             usage 0
             ;;
@@ -110,30 +88,17 @@ if [[ -n "$EXPECT_HEAD" && ! "$EXPECT_HEAD" =~ ^[0-9a-fA-F]{40}$ ]]; then
     echo "Error: --expect-head must be a full 40-character hexadecimal commit SHA." >&2
     exit 1
 fi
-if [[ "$CO_AUTHOR_TRAILERS" == true && -z "$ESCALATE_TO" ]]; then
-    echo "Error: --co-author-trailers requires --escalate-to with a named principal." >&2
-    exit 1
-fi
-if [[ -n "$ESCALATE_TO" && ! "$ESCALATE_TO" =~ ^[A-Za-z0-9_.-]+$ ]]; then
-    echo "Error: --escalate-to must be one exact principal name." >&2
-    exit 1
-fi
-if [[ "$CO_AUTHOR_TRAILERS" != true && -n "$ESCALATE_TO" ]]; then
-    echo "Error: --escalate-to is valid only with --co-author-trailers." >&2
-    exit 1
-fi
 
 PR_METADATA="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER")"
 BASE_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
 HEAD_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefName") or "").strip())')"
 HEAD_SHA="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefOid") or "").strip())')"
 HEAD_REPO="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("headRepository") or ""; print((value.get("nameWithOwner") or value.get("full_name") or "") if isinstance(value, dict) else str(value).strip())')"
-PR_TITLE="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("title") or "").strip())')"
-PR_AUTHOR="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("author") or ""; print((value.get("login") or "").strip() if isinstance(value, dict) else str(value).strip())')"
 if [[ "$BASE_BRANCH" != "main" ]]; then
     echo "Error: Mosaic policy allows merges only for PRs targeting 'main' (found '$BASE_BRANCH')." >&2
     exit 1
 fi
+
 if [[ -z "$HEAD_BRANCH" || -z "$HEAD_REPO" || ! "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then
     echo "Error: Could not resolve the PR head branch, repository, and full commit SHA for queue inspection." >&2
     exit 1
@@ -157,442 +122,70 @@ PLATFORM=$(detect_platform)
 OWNER=$(get_repo_owner)
 REPO=$(get_repo_name)
 
-write_curl_auth_config() {
-    local mode="$1" credential="$2"
-    printf '%s' "$credential" | python3 -c '
-import sys
-mode = sys.argv[1]
-credential = sys.stdin.read()
-if not credential or any(char in credential for char in "\r\n"):
-    raise SystemExit(1)
-escaped = credential.replace("\\", "\\\\").replace("\"", "\\\"")
-if mode == "token":
-    print(f"header = \"Authorization: token {escaped}\"")
-elif mode == "basic":
-    print(f"user = \"{escaped}\"")
-else:
-    raise SystemExit(1)
-' "$mode"
-}
-
-LAST_GITEA_HTTP_CODE="000"
-LAST_GITEA_ERROR=""
-MERGE_TEMP_DIRS=()
-GITEA_CURL_MAX_BYTES="${MOSAIC_GITEA_CURL_MAX_BYTES:-1048576}"
-GITEA_CURL_MAX_TIME="${MOSAIC_GITEA_CURL_MAX_TIME_SEC:-30}"
-GITEA_CURL_CONNECT_TIMEOUT="${MOSAIC_GITEA_CURL_CONNECT_TIMEOUT_SEC:-10}"
-for bound in "$GITEA_CURL_MAX_BYTES" "$GITEA_CURL_MAX_TIME" "$GITEA_CURL_CONNECT_TIMEOUT"; do
-    if [[ ! "$bound" =~ ^[1-9][0-9]*$ ]]; then
-        echo "Error: Gitea curl bounds must be positive integers; refusing request." >&2
-        exit 1
-    fi
-done
-GITEA_CURL_BOUNDS=(
-    --max-filesize "$GITEA_CURL_MAX_BYTES"
-    --max-time "$GITEA_CURL_MAX_TIME"
-    --connect-timeout "$GITEA_CURL_CONNECT_TIMEOUT"
-)
-
-format_gitea_error_response() {
-    local response_file="$1"
-    python3 - "$response_file" <<'PY'
-import json
-import sys
-
-with open(sys.argv[1], "rb") as handle:
-    raw = handle.read(65536)
-try:
-    response = json.loads(raw.decode("utf-8", errors="replace"))
-except (UnicodeDecodeError, json.JSONDecodeError):
-    message = "non-JSON response omitted"
-else:
-    if isinstance(response, dict):
-        message = response.get("message") or response.get("error")
-        if not message and response.get("errors") is not None:
-            message = json.dumps(response["errors"], separators=(",", ":"))
-    else:
-        message = None
-    if not message:
-        message = "JSON response contained no error message"
-message = str(message)
-if len(message) > 500:
-    message = message[:500] + "..."
-print(ascii(message))
-PY
-}
-
-cleanup_merge_temp_dirs() {
-    local path
-    for path in "${MERGE_TEMP_DIRS[@]}"; do
-        [[ -n "$path" ]] && rm -rf -- "$path"
-    done
-}
-trap cleanup_merge_temp_dirs EXIT
-trap 'exit 130' INT
-trap 'exit 143' TERM
-
-fetch_gitea_pr_head() {
-    local host="$1" auth_mode="$2" credential="$3" work_root="$4"
-    local response_file raw_code api_url auth_config curl_rc
-    response_file=$(mktemp "$work_root/pr-merge-pr.XXXXXX")
-    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}"
-    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
-        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
-        rm -f "$response_file"
-        return 1
-    fi
-    raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$response_file" \
-        -H "User-Agent: curl/8" "$api_url" <<<"$auth_config")
-    curl_rc=$?
-    LAST_GITEA_HTTP_CODE="${raw_code:-000}"
-    if [[ "$curl_rc" -ne 0 ]]; then
-        LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
-        rm -f "$response_file"
-        return 1
-    fi
-    if [[ ! "$raw_code" =~ ^2 ]]; then
-        LAST_GITEA_ERROR=$(format_gitea_error_response "$response_file")
-        rm -f "$response_file"
-        return 1
-    fi
-    if ! python3 - "$response_file" <<'PY'
-import json
-import re
-import sys
-
-with open(sys.argv[1], encoding="utf-8") as handle:
-    pull = json.load(handle)
-head = pull.get("head") if isinstance(pull, dict) else None
-sha = str(head.get("sha") or "") if isinstance(head, dict) else ""
-if not re.fullmatch(r"[0-9a-fA-F]{40}", sha):
-    raise SystemExit(1)
-print(sha)
-PY
-    then
-        echo "Error: Gitea PR response has no valid head SHA; refusing merge." >&2
-        rm -f "$response_file"
-        return 1
-    fi
-    rm -f "$response_file"
-}
-
-fetch_gitea_pr_commits() {
-    local host="$1" auth_mode="$2" credential="$3" work_root="$4"
-    local page page_file combined_file merged_file raw_code page_count api_url auth_config curl_rc
-    mkdir -p "$work_root"
-    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
-        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
-        return 1
-    fi
-    combined_file=$(mktemp "$work_root/pr-merge-commits.XXXXXX")
-    printf '[]' > "$combined_file"
-
-    page=1
-    while true; do
-        page_file=$(mktemp "$work_root/pr-merge-commits-page.XXXXXX")
-        api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/commits?limit=50&page=${page}"
-        raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$page_file" \
-            -H "User-Agent: curl/8" "$api_url" <<<"$auth_config")
-        curl_rc=$?
-        LAST_GITEA_HTTP_CODE="${raw_code:-000}"
-        if [[ "$curl_rc" -ne 0 ]]; then
-            LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
-            rm -f "$page_file" "$combined_file"
-            return 1
-        fi
-        if [[ ! "$raw_code" =~ ^2 ]]; then
-            LAST_GITEA_ERROR=$(format_gitea_error_response "$page_file")
-            rm -f "$page_file" "$combined_file"
-            return 1
-        fi
-
-        if ! page_count=$(python3 - "$page_file" <<'PY'
-import json
-import sys
-
-with open(sys.argv[1], encoding="utf-8") as handle:
-    page = json.load(handle)
-if not isinstance(page, list):
-    raise SystemExit(1)
-print(len(page))
-PY
-        ); then
-            echo "Error: Gitea PR commits response is not a JSON array; refusing merge." >&2
-            rm -f "$page_file" "$combined_file"
-            return 1
-        fi
-
-        merged_file=$(mktemp "$work_root/pr-merge-commits-merged.XXXXXX")
-        if ! python3 - "$combined_file" "$page_file" > "$merged_file" <<'PY'
-import json
-import sys
-
-with open(sys.argv[1], encoding="utf-8") as handle:
-    combined = json.load(handle)
-with open(sys.argv[2], encoding="utf-8") as handle:
-    page = json.load(handle)
-json.dump(combined + page, sys.stdout, separators=(",", ":"))
-PY
-        then
-            echo "Error: Could not combine paginated PR commit metadata; refusing merge." >&2
-            rm -f "$page_file" "$combined_file" "$merged_file"
-            return 1
-        fi
-        mv "$merged_file" "$combined_file"
-        rm -f "$page_file"
-
-        if [[ "$page_count" -lt 50 ]]; then
-            break
-        fi
-        page=$((page + 1))
-        if [[ "$page" -gt 1000 ]]; then
-            echo "Error: PR commit pagination exceeded 1000 pages; refusing merge." >&2
-            rm -f "$combined_file"
-            return 1
-        fi
-    done
-
-    cat "$combined_file"
-    rm -f "$combined_file"
-}
-
-# LIMITATION: author.login resolution proves the commit address maps to a registered account.
-# It does NOT prove the named principal authored the commit — git author metadata is self-asserted.
-# This gate checks ATTRIBUTION LINKAGE, not AUTHORSHIP. Commit signing is out of scope and unadopted.
-build_coauthor_message_fields() {
-    local commits_file="$1" context_file="$2" head_file="$3"
-    python3 - "$commits_file" "$context_file" "$head_file" <<'PY'
-import json
-import re
-import sys
-
-commits_path, context_path, head_path = sys.argv[1:]
-with open(commits_path, encoding="utf-8") as handle:
-    commits = json.load(handle)
-head_sha = open(head_path, encoding="utf-8").read().strip()
-context_parts = open(context_path, "rb").read().split(b"\0")
-if len(context_parts) != 4 or context_parts[-1] != b"":
-    raise SystemExit(1)
-poster, title, principal = (part.decode("utf-8") for part in context_parts[:3])
-
-if not isinstance(commits, list) or not commits:
-    print(
-        f"BLOCK: provider returned no PR commits; author identity is unmeasurable. "
-        f"Refusing merge; escalate to named principal '{principal}'.",
-        file=sys.stderr,
-    )
-    raise SystemExit(75)
-if not poster:
-    print(
-        f"BLOCK: PR poster login is empty; refusing merge; "
-        f"escalate to named principal '{principal}'.",
-        file=sys.stderr,
-    )
-    raise SystemExit(75)
-
-if not re.fullmatch(r"[0-9a-fA-F]{40}", head_sha):
-    print(
-        f"BLOCK: inspected PR head SHA is invalid; refusing merge; "
-        f"escalate to named principal '{principal}'.",
-        file=sys.stderr,
-    )
-    raise SystemExit(75)
-
-seen = set()
-trailers = []
-head_seen = False
-for item in commits:
-    if not isinstance(item, dict):
-        print(f"BLOCK: malformed PR commit metadata; escalate to named principal '{principal}'.", file=sys.stderr)
-        raise SystemExit(75)
-    sha = str(item.get("sha") or "<unknown>")
-    if sha == head_sha:
-        head_seen = True
-    commit = item.get("commit") if isinstance(item.get("commit"), dict) else {}
-    commit_author = commit.get("author") if isinstance(commit.get("author"), dict) else {}
-    email = str(commit_author.get("email") or "").strip()
-    provider_author = item.get("author") if isinstance(item.get("author"), dict) else {}
-    login = str(provider_author.get("login") or "").strip()
-
-    if not login:
-        diagnostic_email = email or "<missing>"
-        print(
-            f"BLOCK: commit {sha!r} has author.login=NULL while "
-            f"commit.author.email={diagnostic_email!r}; refusing merge; "
-            f"escalate to named principal '{principal}'.",
-            file=sys.stderr,
-        )
-        raise SystemExit(75)
-    if (
-        not email.isascii()
-        or not email.isprintable()
-        or not re.fullmatch(r"[A-Za-z0-9_.-]+", login)
-        or not re.fullmatch(r"[^<>\s]+@[^<>\s]+", email)
-    ):
-        print(
-            f"BLOCK: commit {sha!r} has unusable linked identity "
-            f"author.login={login!r}, commit.author.email={email!r}; refusing merge; "
-            f"escalate to named principal '{principal}'.",
-            file=sys.stderr,
-        )
-        raise SystemExit(75)
-    if login == poster or login in seen:
-        continue
-    seen.add(login)
-    trailers.append(f"Co-authored-by: {login} <{email}>")
-
-if not head_seen:
-    print(
-        f"BLOCK: inspected PR head is absent from commit enumeration; refusing merge; "
-        f"escalate to named principal '{principal}'.",
-        file=sys.stderr,
-    )
-    raise SystemExit(75)
-if not trailers:
-    print("{}")
-    raise SystemExit(0)
-if not title:
-    print(
-        f"BLOCK: PR title is empty; refusing merge; escalate to named principal '{principal}'.",
-        file=sys.stderr,
-    )
-    raise SystemExit(75)
-if not title.isprintable() or re.match(r"^[A-Za-z-]+-[Bb]y:", title):
-    print(
-        f"BLOCK: PR title is not one printable, non-trailer line; refusing merge; "
-        f"escalate to named principal '{principal}'.",
-        file=sys.stderr,
-    )
-    raise SystemExit(75)
-
-print(json.dumps({
-    "MergeTitleField": title,
-    "MergeMessageField": "\n".join(trailers),
-}, separators=(",", ":")))
-PY
-}
-
-merge_gitea_api_attempt() {
-    local host="$1" auth_mode="$2" credential="$3"
-    local api_url attempt_dir body_file raw_code commits_file fields_file context_file head_file payload_file work_root attempt_rc auth_config curl_rc
-    LAST_GITEA_HTTP_CODE="000"
-    LAST_GITEA_ERROR=""
+merge_gitea_with_api() {
+    local host="$1" api_url token basic_auth body_file raw_code payload
     api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
-    work_root="${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
-    mkdir -p "$work_root"
-    attempt_dir=$(mktemp -d "$work_root/pr-merge-attempt.XXXXXX")
-    chmod 0700 "$attempt_dir"
-    MERGE_TEMP_DIRS+=("$attempt_dir")
-    body_file=$(mktemp "$attempt_dir/api-response.XXXXXX")
-    fields_file=$(mktemp "$attempt_dir/message-fields.XXXXXX")
-    payload_file=$(mktemp "$attempt_dir/payload.XXXXXX")
-    printf '{}' > "$fields_file"
-
-    if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
-        commits_file=$(mktemp "$attempt_dir/pr-merge-commits-input.XXXXXX")
-        context_file=$(mktemp "$attempt_dir/pr-merge-message-context.XXXXXX")
-        head_file=$(mktemp "$attempt_dir/pr-merge-head-input.XXXXXX")
-        printf '%s\0%s\0%s\0' "$PR_AUTHOR" "$PR_TITLE" "$ESCALATE_TO" > "$context_file"
-        if fetch_gitea_pr_head "$host" "$auth_mode" "$credential" "$attempt_dir" > "$head_file"; then
-            :
-        else
-            attempt_rc=$?
-            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
-            return "$attempt_rc"
-        fi
-        if [[ "$(<"$head_file")" != "$HEAD_SHA" ]]; then
-            echo "BLOCK: authenticated PR head moved from reviewed $HEAD_SHA to $(<"$head_file"); refusing merge; escalate to named principal '$ESCALATE_TO'." >&2
-            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
-            return 75
-        fi
-        if fetch_gitea_pr_commits "$host" "$auth_mode" "$credential" "$attempt_dir" > "$commits_file"; then
-            :
-        else
-            attempt_rc=$?
-            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
-            return "$attempt_rc"
-        fi
-        if build_coauthor_message_fields "$commits_file" "$context_file" "$head_file" > "$fields_file"; then
-            :
-        else
-            attempt_rc=$?
-            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
-            return "$attempt_rc"
-        fi
-        rm -f "$commits_file" "$context_file" "$head_file"
-    fi
-
-    if ! python3 - "$fields_file" "$HEAD_SHA" "$DELETE_BRANCH" > "$payload_file" <<'PY'
+    mkdir -p "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
+    body_file=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-api-response.XXXXXX")
+    payload=$(python3 - "$HEAD_SHA" "$DELETE_BRANCH" <<'PY'
 import json
 import sys
 
-with open(sys.argv[1], encoding="utf-8") as handle:
-    fields = json.load(handle)
-head_sha, delete_branch = sys.argv[2:]
+head_sha, delete_branch = sys.argv[1:]
 payload = {"Do": "squash", "head_commit_id": head_sha}
 if delete_branch == "true":
     payload["delete_branch_after_merge"] = True
-payload.update(fields)
-allowed = {"Do", "head_commit_id", "delete_branch_after_merge", "MergeTitleField", "MergeMessageField"}
-if payload.get("Do") != "squash" or set(payload) - allowed:
-    raise SystemExit(1)
 print(json.dumps(payload, separators=(",", ":")))
 PY
-    then
-        rm -f "$body_file" "$fields_file" "$payload_file"
-        return 1
-    fi
-    rm -f "$fields_file"
+)
 
-    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
-        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
-        rm -f "$body_file" "$payload_file"
-        return 1
+    token=$(get_gitea_token "$host" || true)
+    if [[ -n "$token" ]]; then
+        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
+            -X POST \
+            -H "User-Agent: curl/8" \
+            -H "Authorization: token $token" \
+            -H 'Content-Type: application/json' \
+            -d "$payload" \
+            "$api_url" || true)
+        if [[ "$raw_code" =~ ^2 ]]; then
+            rm -f "$body_file"
+            return 0
+        fi
     fi
-    raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$body_file" \
-        -X POST -H "User-Agent: curl/8" \
-        -H 'Content-Type: application/json' \
-        --data-binary "@$payload_file" "$api_url" <<<"$auth_config")
-    curl_rc=$?
-    LAST_GITEA_HTTP_CODE="${raw_code:-000}"
-    if [[ "$curl_rc" -ne 0 ]]; then
-        LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
-        rm -f "$body_file" "$payload_file"
-        rm -rf -- "$attempt_dir"
-        return 1
-    fi
-    if [[ ! "$raw_code" =~ ^2 ]]; then
-        LAST_GITEA_ERROR=$(format_gitea_error_response "$body_file")
-    fi
-    rm -f "$body_file" "$payload_file"
-    rm -rf -- "$attempt_dir"
-    [[ "$raw_code" =~ ^2 ]]
-}
 
-merge_gitea_with_api() {
-    local host="$1" token attempt_rc
+    basic_auth=$(get_gitea_basic_auth "$host" || true)
+    if [[ -n "$basic_auth" ]]; then
+        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
+            -X POST \
+            -u "$basic_auth" \
+            -H "User-Agent: curl/8" \
+            -H 'Content-Type: application/json' \
+            -d "$payload" \
+            "$api_url" || true)
+        if [[ "$raw_code" =~ ^2 ]]; then
+            rm -f "$body_file"
+            return 0
+        fi
+    fi
 
-    if ! token=$(get_gitea_token "$host"); then
-        echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
-        return 1
-    fi
-    if [[ -z "$token" ]]; then
-        echo "Error: Required Gitea token resolved empty; refusing merge without changing principals." >&2
-        return 1
-    fi
-    if merge_gitea_api_attempt "$host" token "$token"; then
-        return 0
-    else
-        attempt_rc=$?
-    fi
-    if [[ "$attempt_rc" -eq 75 ]]; then
-        return 75
-    fi
-    if [[ "$LAST_GITEA_HTTP_CODE" != "401" ]]; then
-        echo "Error: Gitea API merge failed with the identity-bound token (HTTP ${LAST_GITEA_HTTP_CODE:-000}).${LAST_GITEA_ERROR:+ Provider response: $LAST_GITEA_ERROR}" >&2
-        return 1
-    fi
-    echo "Error: Gitea API rejected the identity-bound token with HTTP 401; refusing cross-principal credential fallback." >&2
+    python3 - "${raw_code:-000}" "$body_file" <<'PY' >&2
+import json
+import sys
+code, path = sys.argv[1], sys.argv[2]
+try:
+    with open(path, encoding="utf-8", errors="replace") as handle:
+        raw = handle.read(500)
+    data = json.loads(raw) if raw else {}
+    message = data.get("message") or data.get("error") or raw or "empty response"
+except Exception:
+    try:
+        message = open(path, encoding="utf-8", errors="replace").read(500) or "empty response"
+    except Exception:
+        message = "unreadable response"
+print(f"Error: Gitea API merge failed with HTTP {code}: {message}")
+PY
+    rm -f "$body_file"
     return 1
 }
 
@@ -602,10 +195,11 @@ if [[ "$DRY_RUN" == true ]]; then
             echo "Error: Cannot determine host from origin remote URL" >&2
             exit 1
         }
-        if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
-            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
+        TEA_LOGIN="$(get_gitea_login_for_host "$HOST" || true)"
+        if [[ -n "$TEA_LOGIN" ]]; then
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with tea login '$TEA_LOGIN' (base=$BASE_BRANCH, method=squash)."
         else
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with authenticated Gitea API fallback (base=$BASE_BRANCH, method=squash)."
         fi
     else
         echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."
@@ -615,10 +209,6 @@ fi
 
 case "$PLATFORM" in
     github)
-        if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
-            echo "Error: --co-author-trailers currently requires the Gitea REST message-field contract." >&2
-            exit 1
-        fi
         cmd=(gh pr merge "$PR_NUMBER" --squash --match-head-commit "$HEAD_SHA")
         [[ "$DELETE_BRANCH" == true ]] && cmd+=(--delete-branch)
         "${cmd[@]}"
@@ -629,7 +219,7 @@ case "$PLATFORM" in
             exit 1
         }
         # Gitea's API head_commit_id is an atomic compare-and-merge precondition.
-        # tea cannot express it, so every Gitea merge uses the authenticated API path.
+        # tea cannot express it, so exact-head merges use the authenticated API path.
         merge_gitea_with_api "$HOST"
         ;;
     *)

packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh

@@ -51,23 +51,22 @@ for arg in "$@"; do
         prev=""
         continue
     fi
-    if [[ "$prev" == "data" ]]; then
+    if [[ "$prev" == "-d" ]]; then
         post_data="$arg"
-        [[ "$post_data" == @* ]] && post_data=$(<"${post_data#@}")
         prev=""
         continue
     fi
-    if [[ "$prev" == "config" ]]; then
-        [[ "$arg" == "-" ]] && cat >/dev/null
-        prev=""
+    if [[ "$arg" == "-o" ]]; then
+        prev="-o"
         continue
     fi
-    case "$arg" in
-        -o) prev="-o" ;;
-        -d|--data|--data-binary) prev="data" ;;
-        -K|--config) prev="config" ;;
-        -w) write_code=true ;;
-    esac
+    if [[ "$arg" == "-d" ]]; then
+        prev="-d"
+        continue
+    fi
+    if [[ "$arg" == "-w" ]]; then
+        write_code=true
+    fi
 done
 emit_response() {
     local body="$1"

packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh

@@ -36,30 +36,13 @@ cat > "$WORK_DIR/gitea/curl" <<'SH'
 #!/usr/bin/env bash
 set -euo pipefail
 payload=""
-out_file=""
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        -d|--data|--data-binary)
-            payload="$2"
-            [[ "$payload" == @* ]] && payload=$(<"${payload#@}")
-            shift 2
-            ;;
-        -o)
-            out_file="$2"
-            shift 2
-            ;;
-        -K|--config)
-            [[ "$2" == "-" ]] && cat >/dev/null
-            shift 2
-            ;;
-        -w|-X|-H)
-            shift 2
-            ;;
-        *) shift ;;
-    esac
+for ((i=1; i<=$#; i++)); do
+    if [[ "${!i}" == "-d" ]]; then
+        j=$((i + 1))
+        payload="${!j}"
+    fi
 done
 printf '%s' "$payload" > "${MOSAIC_MERGE_PAYLOAD_LOG:?}"
-[[ -n "$out_file" ]] && printf '{}' > "$out_file"
 printf '200'
 SH
 chmod +x "$WORK_DIR/gitea/curl"

packages/mosaic/framework/tools/git/test-pr-merge-message-field.sh

@@ -1,541 +0,0 @@
-#!/usr/bin/env bash
-# Regression harness for the optional, identity-checked Gitea squash message.
-
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SUBJECT="${MOSAIC_TEST_SUBJECT:-$SCRIPT_DIR/pr-merge.sh}"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-message-field}"
-ORIG_PATH="$PATH"
-failures=0
-
-rm -rf "$WORK_DIR"
-mkdir -p "$WORK_DIR"
-
-fail() {
-    echo "FAIL $1" >&2
-    failures=$((failures + 1))
-}
-
-make_case() {
-    local name="$1" case_dir
-    case_dir="$WORK_DIR/$name"
-    mkdir -p "$case_dir/bin" "$case_dir/agent"
-    cp "$SUBJECT" "$case_dir/pr-merge.sh"
-    chmod +x "$case_dir/pr-merge.sh"
-
-    cat > "$case_dir/detect-platform.sh" <<'SH'
-#!/usr/bin/env bash
-detect_platform() { PLATFORM=gitea; printf 'gitea\n'; }
-get_repo_owner() { printf 'acme\n'; }
-get_repo_name() { printf 'widgets\n'; }
-get_remote_host() { printf 'git.example.test\n'; }
-get_gitea_token() {
-    printf 'resolved\n' >> "${MOSAIC_TEST_TOKEN_RESOLUTION_LOG:?}"
-    if [[ "${MOSAIC_TEST_TOKEN_AVAILABLE:-true}" != "true" ]]; then
-        return 1
-    fi
-    printf 'fixture-token\n'
-}
-get_gitea_basic_auth() {
-    printf 'resolved\n' >> "${MOSAIC_TEST_BASIC_RESOLUTION_LOG:?}"
-    if [[ "${MOSAIC_TEST_BASIC_AVAILABLE:-false}" == "true" ]]; then
-        printf 'fixture-user:fixture-password\n'
-        return "${MOSAIC_TEST_BASIC_RC:-0}"
-    fi
-    return 1
-}
-get_gitea_login_for_host() { return 1; }
-SH
-
-    cat > "$case_dir/pr-metadata.sh" <<'SH'
-#!/usr/bin/env bash
-if [[ "${MOSAIC_TEST_TITLE_MODE:-safe}" == "injection" ]]; then
-    title='Preserve authors\n\nCo-authored-by: victim <[email protected]>'
-else
-    title='Preserve both branch authors'
-fi
-case "${MOSAIC_TEST_COMMITS_MODE:?}" in
-    verified) head_sha=2222222222222222222222222222222222222222 ;;
-    null-login|unsafe-identity) head_sha=3333333333333333333333333333333333333333 ;;
-    single) head_sha=1111111111111111111111111111111111111111 ;;
-    *) echo "unknown commits mode" >&2; exit 2 ;;
-esac
-printf '{"number":42,"title":"%s","author":"poster","baseRefName":"main","headRefName":"feature/fixture","headRefOid":"%s","headRepository":"acme/widgets"}\n' "$title" "$head_sha"
-SH
-
-    cat > "$case_dir/ci-queue-wait.sh" <<'SH'
-#!/usr/bin/env bash
-exit 0
-SH
-
-    cat > "$case_dir/bin/python3" <<'SH'
-#!/usr/bin/env bash
-for arg in "$@"; do
-    case "$arg" in
-        *"Preserve both branch authors"*|*"[email protected]"*)
-            : > "${MOSAIC_TEST_METADATA_ARGV_MARKER:?}"
-            ;;
-    esac
-done
-exec "${MOSAIC_TEST_REAL_PYTHON:?}" "$@"
-SH
-
-    cat > "$case_dir/bin/curl" <<'SH'
-#!/usr/bin/env bash
-set -eu
-
-for arg in "$@"; do
-    case "$arg" in
-        *"Preserve both branch authors"*|*"[email protected]"*)
-            : > "${MOSAIC_TEST_METADATA_ARGV_MARKER:?}"
-            ;;
-    esac
-done
-
-url=""
-method="GET"
-out_file=""
-data=""
-config=""
-auth_mode="none"
-has_max_filesize=0
-has_max_time=0
-has_connect_timeout=0
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        -o)
-            out_file="$2"
-            shift 2
-            ;;
-        -w)
-            shift 2
-            ;;
-        -X)
-            method="$2"
-            shift 2
-            ;;
-        -d|--data|--data-binary)
-            data="$2"
-            if [[ "$data" == @* ]]; then
-                data=$(<"${data#@}")
-            fi
-            shift 2
-            ;;
-        -K|--config)
-            if [[ "$2" == "-" ]]; then
-                config=$(cat)
-            fi
-            shift 2
-            ;;
-        --max-filesize)
-            has_max_filesize=1
-            shift 2
-            ;;
-        --max-time)
-            has_max_time=1
-            shift 2
-            ;;
-        --connect-timeout)
-            has_connect_timeout=1
-            shift 2
-            ;;
-        -H|--header|-u|--user)
-            if [[ "$2" == *"fixture-token"* ]]; then
-                : > "${MOSAIC_TEST_TOKEN_ARGV_MARKER:?}"
-            fi
-            if [[ "$2" == *"fixture-password"* ]]; then
-                : > "${MOSAIC_TEST_BASIC_ARGV_MARKER:?}"
-            fi
-            shift 2
-            ;;
-        http://*|https://*)
-            url="$1"
-            shift
-            ;;
-        *)
-            shift
-            ;;
-    esac
-done
-
-if [[ "$config" == *"Authorization: token fixture-token"* ]]; then
-    auth_mode="token"
-    : > "${MOSAIC_TEST_AUTH_CONFIG_MARKER:?}"
-elif [[ "$config" == *"user = \"fixture-user:fixture-password\""* ]]; then
-    auth_mode="basic"
-    : > "${MOSAIC_TEST_BASIC_CONFIG_MARKER:?}"
-fi
-printf '%s %s %s\n' "$method" "$auth_mode" "$url" >> "${MOSAIC_TEST_CURL_LOG:?}"
-printf '%s:%s:%s\n' "$has_max_filesize" "$has_max_time" "$has_connect_timeout" >> "${MOSAIC_TEST_CURL_BOUNDS_LOG:?}"
-
-case "$url" in
-    */pulls/42)
-        case "${MOSAIC_TEST_COMMITS_MODE:?}" in
-            verified) head_sha=2222222222222222222222222222222222222222 ;;
-            null-login|unsafe-identity) head_sha=3333333333333333333333333333333333333333 ;;
-            single) head_sha=1111111111111111111111111111111111111111 ;;
-            *) echo "unknown commits mode" >&2; exit 2 ;;
-        esac
-        if [[ "${MOSAIC_TEST_HEAD_MODE:-stable}" == "moved" ]]; then
-            head_sha=4444444444444444444444444444444444444444
-        fi
-        body="{\"head\":{\"sha\":\"$head_sha\"}}"
-        code=200
-        if [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "inspection" && "$auth_mode" == "token" ]]; then
-            body='{"message":"token rejected"}'
-            code=401
-        fi
-        ;;
-    */pulls/42/commits*)
-        case "${MOSAIC_TEST_COMMITS_MODE:?}" in
-            verified)
-                if [[ "${MOSAIC_TEST_EMAIL_MODE:-safe}" == "escape" ]]; then
-                    body='[{"sha":"2222222222222222222222222222222222222222","commit":{"author":{"name":"Alice","email":"alice+\u001b[[email protected]"}},"author":{"login":"alice"}},{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
-                else
-                    body='[{"sha":"2222222222222222222222222222222222222222","commit":{"author":{"name":"Alice","email":"[email protected]"}},"author":{"login":"alice"}},{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
-                fi
-                ;;
-            null-login)
-                body='[{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}},{"sha":"3333333333333333333333333333333333333333","commit":{"author":{"name":"Unresolved Author","email":"[email protected]\n\u001b[31m"}},"author":null}]'
-                ;;
-            unsafe-identity)
-                body='[{"sha":"unsafe\n\u001b[31m","commit":{"author":{"name":"Unsafe","email":"not-an-email"}},"author":{"login":"unsafe"}},{"sha":"3333333333333333333333333333333333333333","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
-                ;;
-            single)
-                body='[{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
-                ;;
-            *)
-                echo "unknown commits mode" >&2
-                exit 2
-                ;;
-        esac
-        code=200
-        if [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "inspection" && "$auth_mode" == "token" ]]; then
-            body='{"message":"token rejected"}'
-            code=401
-        fi
-        ;;
-    */pulls/42/merge)
-        body='{}'
-        code=200
-        if [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "merge" && "$auth_mode" == "token" ]]; then
-            body='{"message":"token rejected"}'
-            code=401
-        elif [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "provider-error" ]]; then
-            body='{"message":"branch policy rejected\n\u001b[31m"}'
-            code=409
-        elif [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "forbidden" ]]; then
-            body='{"message":"permission denied"}'
-            code=403
-        else
-            printf '%s' "$data" > "${MOSAIC_TEST_MERGE_PAYLOAD:?}"
-        fi
-        ;;
-    */users/*)
-        body='{"message":"not found"}'
-        code=404
-        ;;
-    *)
-        body='{"message":"unexpected URL"}'
-        code=500
-        ;;
-esac
-
-if [[ -n "$out_file" ]]; then
-    printf '%s' "$body" > "$out_file"
-else
-    printf '%s' "$body"
-fi
-printf '%s' "$code"
-case "${MOSAIC_TEST_CURL_FAILURE:-none}" in
-    oversize) exit 63 ;;
-    stalled) exit 28 ;;
-esac
-SH
-
-    chmod +x "$case_dir/detect-platform.sh" "$case_dir/pr-metadata.sh" \
-        "$case_dir/ci-queue-wait.sh" "$case_dir/bin/curl" "$case_dir/bin/python3"
-    printf '%s\n' "$case_dir"
-}
-
-run_case() {
-    local case_dir="$1" mode="$2"
-    shift 2
-    MOSAIC_TEST_COMMITS_MODE="$mode" \
-    MOSAIC_TEST_CURL_LOG="$case_dir/curl.log" \
-    MOSAIC_TEST_CURL_BOUNDS_LOG="$case_dir/curl-bounds.log" \
-    MOSAIC_TEST_MERGE_PAYLOAD="$case_dir/merge-payload.json" \
-    MOSAIC_TEST_TOKEN_ARGV_MARKER="$case_dir/token-in-argv" \
-    MOSAIC_TEST_BASIC_ARGV_MARKER="$case_dir/basic-in-argv" \
-    MOSAIC_TEST_AUTH_CONFIG_MARKER="$case_dir/auth-via-config" \
-    MOSAIC_TEST_BASIC_CONFIG_MARKER="$case_dir/basic-via-config" \
-    MOSAIC_TEST_TOKEN_RESOLUTION_LOG="$case_dir/token-resolution.log" \
-    MOSAIC_TEST_BASIC_RESOLUTION_LOG="$case_dir/basic-resolution.log" \
-    MOSAIC_TEST_METADATA_ARGV_MARKER="$case_dir/metadata-in-argv" \
-    MOSAIC_TEST_REAL_PYTHON="$(command -v python3)" \
-    AGENT_WORK_ROOT="$case_dir/agent" \
-    PATH="$case_dir/bin:$ORIG_PATH" \
-        "$case_dir/pr-merge.sh" -n 42 "$@"
-}
-
-# Verified multi-author path: the non-poster trailer is built from one commit's
-# linked author.login and that same commit's author email. No /users lookup.
-verified_dir=$(make_case verified)
-set +e
-verified_output=$(run_case "$verified_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-verified_rc=$?
-set -e
-if [[ "$verified_rc" -ne 0 ]]; then
-    fail "verified multi-author merge expected rc=0, got rc=$verified_rc: $verified_output"
-elif [[ ! -s "$verified_dir/merge-payload.json" ]]; then
-    fail "verified multi-author merge did not reach the API payload"
-else
-    python3 - "$verified_dir/merge-payload.json" <<'PY' || fail "verified payload did not preserve squash and exact message fields"
-import json
-import sys
-payload = json.load(open(sys.argv[1], encoding="utf-8"))
-assert payload == {
-    "Do": "squash",
-    "head_commit_id": "2222222222222222222222222222222222222222",
-    "MergeTitleField": "Preserve both branch authors",
-    "MergeMessageField": "Co-authored-by: alice <[email protected]>",
-}, payload
-PY
-fi
-[[ -e "$verified_dir/auth-via-config" ]] || fail "verified path did not authenticate curl through stdin config"
-[[ ! -e "$verified_dir/token-in-argv" ]] || fail "verified path placed the Gitea token in curl argv"
-[[ ! -e "$verified_dir/metadata-in-argv" ]] || fail "verified path placed PR title or contributor email in child argv"
-[[ "$(wc -l < "$verified_dir/token-resolution.log")" -eq 1 ]] || fail "verified path did not bind inspection and merge to one credential resolution"
-if grep -q '/users/' "$verified_dir/curl.log" 2>/dev/null; then
-    fail "verified path performed a forbidden second /users lookup"
-fi
-if grep -qv '^1:1:1$' "$verified_dir/curl-bounds.log"; then
-    fail "verified path did not apply size/max-time/connect-time bounds to every provider download"
-fi
-
-# A linked email containing a terminal escape must block before mutation.
-escape_email_dir=$(make_case escape-email)
-set +e
-escape_email_output=$(MOSAIC_TEST_EMAIL_MODE=escape run_case "$escape_email_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-escape_email_rc=$?
-set -e
-[[ "$escape_email_rc" -ne 0 ]] || fail "control-byte email unexpectedly passed"
-[[ "$escape_email_output" == *"unusable linked identity"* ]] || fail "control-byte email refusal lost its diagnostic"
-[[ ! -e "$escape_email_dir/merge-payload.json" ]] || fail "control-byte email reached the merge API"
-
-# Curl transfer and duration failures must remain failures even with HTTP 200.
-for failure_mode in oversize stalled; do
-    failure_dir=$(make_case "curl-$failure_mode")
-    set +e
-    failure_output=$(MOSAIC_TEST_CURL_FAILURE="$failure_mode" run_case "$failure_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-    failure_rc=$?
-    set -e
-    [[ "$failure_rc" -ne 0 ]] || fail "curl $failure_mode failure was discarded: $failure_output"
-    [[ ! -e "$failure_dir/merge-payload.json" ]] || fail "curl $failure_mode failure reached the merge API"
-done
-
-# The authenticated head is re-read under the mutation credential but cannot
-# replace the canonical preflight/review head. A move blocks before enumeration
-# or mutation even though the provider returned a valid new SHA.
-moved_dir=$(make_case moved-head)
-set +e
-moved_output=$(MOSAIC_TEST_HEAD_MODE=moved \
-    run_case "$moved_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-moved_rc=$?
-set -e
-[[ "$moved_rc" -ne 0 ]] || fail "moved authenticated head unexpectedly passed"
-[[ "$moved_output" == *"authenticated PR head moved from reviewed"* ]] || fail "moved head refusal lost its diagnostic"
-[[ "$moved_output" == *"tl-mosaic"* ]] || fail "moved head refusal omitted the named escalation principal"
-[[ ! -e "$moved_dir/merge-payload.json" ]] || fail "moved head refusal reached the merge API"
-moved_sequence=$(awk '{print $1 ":" $2}' "$moved_dir/curl.log" | paste -sd, -)
-[[ "$moved_sequence" == "GET:token" ]] || fail "moved head refusal performed post-move inspection/mutation (calls=$moved_sequence)"
-
-# Token resolution failure is not an authentication response. It must fail
-# closed instead of borrowing a Basic credential under a different principal.
-token_missing_dir=$(make_case token-missing)
-set +e
-token_missing_output=$(MOSAIC_TEST_TOKEN_AVAILABLE=false MOSAIC_TEST_BASIC_AVAILABLE=true \
-    run_case "$token_missing_dir" single 2>&1)
-token_missing_rc=$?
-set -e
-[[ "$token_missing_rc" -ne 0 ]] || fail "missing token unexpectedly borrowed Basic Auth"
-[[ "$token_missing_output" == *"required Gitea token"* ]] || fail "missing token refusal lost its diagnostic"
-[[ ! -e "$token_missing_dir/basic-resolution.log" ]] || fail "missing token resolved Basic Auth after identity failure"
-[[ ! -e "$token_missing_dir/curl.log" ]] || fail "missing token reached a provider request"
-
-# A failed Basic resolver must never use its nonempty output or reach mutation.
-basic_rc_dir=$(make_case basic-resolver-rc)
-set +e
-basic_rc_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_BASIC_RC=91 MOSAIC_TEST_FALLBACK_MODE=inspection \
-    run_case "$basic_rc_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-basic_rc_rc=$?
-set -e
-[[ "$basic_rc_rc" -ne 0 ]] || fail "failed Basic resolver output unexpectedly authorized a merge: $basic_rc_output"
-[[ ! -e "$basic_rc_dir/merge-payload.json" ]] || fail "failed Basic resolver reached the merge API"
-
-# HTTP 401 never changes principals: inspection rejection fails closed without
-# resolving or attempting Basic Auth.
-fallback_inspect_dir=$(make_case fallback-inspection)
-set +e
-fallback_inspect_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=inspection \
-    run_case "$fallback_inspect_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-fallback_inspect_rc=$?
-set -e
-[[ "$fallback_inspect_rc" -ne 0 ]] || fail "inspection token rejection unexpectedly changed principals"
-[[ "$fallback_inspect_output" == *"refusing cross-principal credential fallback"* ]] || fail "inspection token rejection lost its refusal diagnostic"
-[[ ! -e "$fallback_inspect_dir/basic-resolution.log" ]] || fail "inspection token rejection resolved Basic Auth"
-[[ ! -e "$fallback_inspect_dir/merge-payload.json" ]] || fail "inspection token rejection reached merge mutation"
-inspect_sequence=$(awk '{print $1 ":" $2}' "$fallback_inspect_dir/curl.log" | paste -sd, -)
-[[ "$inspect_sequence" == "GET:token" ]] || fail "inspection rejection made unexpected provider calls (calls=$inspect_sequence)"
-
-# Token rejection at merge likewise fails closed without cross-principal retry.
-fallback_merge_dir=$(make_case fallback-merge)
-set +e
-fallback_merge_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=merge \
-    run_case "$fallback_merge_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-fallback_merge_rc=$?
-set -e
-[[ "$fallback_merge_rc" -ne 0 ]] || fail "merge token rejection unexpectedly changed principals"
-[[ "$fallback_merge_output" == *"refusing cross-principal credential fallback"* ]] || fail "merge token rejection lost its refusal diagnostic"
-[[ ! -e "$fallback_merge_dir/basic-resolution.log" ]] || fail "merge token rejection resolved Basic Auth"
-[[ ! -e "$fallback_merge_dir/merge-payload.json" ]] || fail "merge token rejection recorded a successful payload"
-merge_sequence=$(awk '{print $1 ":" $2}' "$fallback_merge_dir/curl.log" | paste -sd, -)
-[[ "$merge_sequence" == "GET:token,GET:token,POST:token" ]] || fail "merge rejection made unexpected provider calls (calls=$merge_sequence)"
-
-# BLOCK path: a commit email exists but author.login is null. It must name both
-# facts, name the escalation principal, and never reach the merge endpoint.
-null_dir=$(make_case null-login)
-set +e
-null_output=$(run_case "$null_dir" null-login --co-author-trailers --escalate-to tl-mosaic 2>&1)
-null_rc=$?
-set -e
-[[ "$null_rc" -ne 0 ]] || fail "null-login author expected a non-zero BLOCK"
-[[ "$null_output" == *"BLOCK"* ]] || fail "null-login author omitted BLOCK diagnostic"
-[[ "$null_output" == *"author.login=NULL"* ]] || fail "null-login author omitted the null provider fact"
-[[ "$null_output" == *"[email protected]"* ]] || fail "null-login author omitted the commit email fact"
-[[ "$null_output" == *'\n\x1b[31m'* ]] || fail "null-login author diagnostic did not escape control characters"
-[[ "$null_output" != *$'\033'* ]] || fail "null-login author diagnostic emitted a raw terminal escape"
-[[ "$(printf '%s\n' "$null_output" | wc -l)" -eq 1 ]] || fail "null-login author diagnostic permitted newline injection"
-[[ "$null_output" == *"tl-mosaic"* ]] || fail "null-login author omitted the named escalation principal"
-[[ ! -e "$null_dir/merge-payload.json" ]] || fail "null-login BLOCK still reached the merge API"
-
-# Every provider-derived field in alternate BLOCK diagnostics is log-safe too,
-# including an invalid non-head SHA that contains control characters.
-unsafe_dir=$(make_case unsafe-identity)
-set +e
-unsafe_output=$(run_case "$unsafe_dir" unsafe-identity --co-author-trailers --escalate-to tl-mosaic 2>&1)
-unsafe_rc=$?
-set -e
-[[ "$unsafe_rc" -ne 0 ]] || fail "unsafe identity expected a non-zero BLOCK"
-[[ "$unsafe_output" == *"unusable linked identity"* ]] || fail "unsafe identity omitted its BLOCK reason"
-[[ "$unsafe_output" == *'\n\x1b[31m'* ]] || fail "unsafe identity SHA did not escape control characters"
-[[ "$unsafe_output" != *$'\033'* ]] || fail "unsafe identity diagnostic emitted a raw terminal escape"
-[[ "$(printf '%s\n' "$unsafe_output" | wc -l)" -eq 1 ]] || fail "unsafe identity diagnostic permitted newline injection"
-[[ ! -e "$unsafe_dir/merge-payload.json" ]] || fail "unsafe identity BLOCK still reached the merge API"
-
-# The provider PR title cannot add an unchecked trailer outside the constructed
-# message field: multi-line and trailer-shaped titles block before mutation.
-title_dir=$(make_case title-injection)
-set +e
-title_output=$(MOSAIC_TEST_TITLE_MODE=injection \
-    run_case "$title_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
-title_rc=$?
-set -e
-[[ "$title_rc" -ne 0 ]] || fail "title trailer injection unexpectedly passed"
-[[ "$title_output" == *"not one printable, non-trailer line"* ]] || fail "title injection refusal lost its diagnostic"
-[[ ! -e "$title_dir/merge-payload.json" ]] || fail "title injection reached the merge API"
-
-# Provider failures remain diagnosable after their temporary response file is
-# removed, but provider-controlled control characters stay log-safe.
-error_dir=$(make_case provider-error)
-set +e
-error_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=provider-error \
-    run_case "$error_dir" single 2>&1)
-error_rc=$?
-set -e
-[[ "$error_rc" -ne 0 ]] || fail "provider error unexpectedly passed"
-[[ "$error_output" == *"HTTP 409"* ]] || fail "provider error omitted the HTTP status"
-[[ "$error_output" == *"branch policy rejected"* ]] || fail "provider error response was discarded"
-[[ "$error_output" == *'\n\x1b[31m'* ]] || fail "provider error response did not escape control characters"
-[[ "$error_output" != *$'\033'* ]] || fail "provider error response emitted a raw terminal escape"
-[[ "$error_output" != *"Basic Auth fallback"* ]] || fail "provider error advertised removed Basic Auth fallback"
-[[ ! -e "$error_dir/basic-resolution.log" ]] || fail "HTTP 409 policy denial incorrectly triggered Basic Auth fallback"
-
-# Authorization denials likewise fail closed instead of changing principals.
-forbidden_dir=$(make_case forbidden)
-set +e
-forbidden_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=forbidden \
-    run_case "$forbidden_dir" single 2>&1)
-forbidden_rc=$?
-set -e
-[[ "$forbidden_rc" -ne 0 ]] || fail "HTTP 403 authorization denial unexpectedly passed"
-[[ "$forbidden_output" == *"HTTP 403"* ]] || fail "authorization denial omitted the HTTP status"
-[[ "$forbidden_output" != *"Basic Auth fallback"* ]] || fail "authorization denial advertised removed Basic Auth fallback"
-[[ ! -e "$forbidden_dir/basic-resolution.log" ]] || fail "HTTP 403 authorization denial incorrectly triggered Basic Auth fallback"
-
-# The BLOCK destination cannot be generic or inferred after failure: opting in
-# without a named principal is refused before any provider operation.
-principal_dir=$(make_case missing-principal)
-set +e
-principal_output=$(run_case "$principal_dir" verified --co-author-trailers 2>&1)
-principal_rc=$?
-set -e
-[[ "$principal_rc" -ne 0 ]] || fail "co-author mode without a named principal unexpectedly passed"
-[[ "$principal_output" == *"requires --escalate-to with a named principal"* ]] || fail "missing-principal refusal lost its diagnostic"
-[[ ! -e "$principal_dir/merge-payload.json" ]] || fail "missing-principal refusal reached the merge API"
-
-# A trailing value-taking option receives a stable CLI diagnostic instead of a
-# set -u unbound-variable crash.
-value_dir=$(make_case missing-principal-value)
-set +e
-value_output=$(run_case "$value_dir" verified --co-author-trailers --escalate-to 2>&1)
-value_rc=$?
-set -e
-[[ "$value_rc" -ne 0 ]] || fail "missing --escalate-to value unexpectedly passed"
-[[ "$value_output" == *"--escalate-to requires one principal name"* ]] || fail "missing --escalate-to value lost its diagnostic"
-[[ "$value_output" != *"unbound variable"* ]] || fail "missing --escalate-to value crashed under set -u"
-[[ ! -e "$value_dir/merge-payload.json" ]] || fail "missing --escalate-to value reached the merge API"
-
-# Negative control: ordinary single-author merge remains byte-for-byte payload
-# compatible and hardcoded to squash, with no optional message fields.
-single_dir=$(make_case single)
-set +e
-single_output=$(run_case "$single_dir" single 2>&1)
-single_rc=$?
-set -e
-if [[ "$single_rc" -ne 0 ]]; then
-    fail "ordinary single-author merge expected rc=0, got rc=$single_rc: $single_output"
-elif [[ ! -s "$single_dir/merge-payload.json" ]]; then
-    fail "ordinary single-author merge did not reach the API payload"
-else
-    python3 - "$single_dir/merge-payload.json" <<'PY' || fail "ordinary single-author payload changed"
-import json
-import sys
-payload = json.load(open(sys.argv[1], encoding="utf-8"))
-assert payload == {
-    "Do": "squash",
-    "head_commit_id": "1111111111111111111111111111111111111111",
-}, payload
-PY
-fi
-[[ -e "$single_dir/auth-via-config" ]] || fail "ordinary path did not authenticate curl through stdin config"
-[[ ! -e "$single_dir/token-in-argv" ]] || fail "ordinary path placed the Gitea token in curl argv"
-[[ "$(wc -l < "$single_dir/token-resolution.log")" -eq 1 ]] || fail "ordinary path did not use exactly one credential resolution"
-
-# Squash is not defaultable: an explicit non-squash method must remain refused.
-method_dir=$(make_case method-refusal)
-set +e
-method_output=$(run_case "$method_dir" single -m merge 2>&1)
-method_rc=$?
-set -e
-[[ "$method_rc" -ne 0 ]] || fail "non-squash method unexpectedly passed"
-[[ "$method_output" == *"enforces squash merge only"* ]] || fail "non-squash refusal lost its policy diagnostic"
-[[ ! -e "$method_dir/merge-payload.json" ]] || fail "non-squash refusal reached the merge API"
-
-if [[ "$failures" -ne 0 ]]; then
-    echo "pr-merge message-field regression failed ($failures assertions)" >&2
-    exit 1
-fi
-
-echo "pr-merge message-field regression passed (verified, BLOCK, and unchanged squash control)"

packages/mosaic/framework/tools/lease-broker/daemon.py

@@ -39,7 +39,7 @@ MAX_FRAME: Final = 64 * 1024
 MAX_STATE: Final = 4 * 1024 * 1024
 MAX_PENDING_TOKENS: Final = 256
 MAX_IN_FLIGHT_CONNECTIONS: Final = 16
-MAX_LEASE_TTL_SECONDS: Final = 3600
+MAX_LEASE_TTL_SECONDS: Final = 300
 STATE_VERSION: Final = 1
 READ_DEADLINE_SECONDS: Final = 1.0
 HANDLE_QUEUE_TIMEOUT_SECONDS: Final = 1.0
@@ -50,8 +50,8 @@ LEASE_PENDING: Final = "PENDING_VERIFICATION"
 LEASE_PENDING_PROMOTION: Final = "PENDING_PROMOTION"
 LEASE_VERIFIED: Final = "VERIFIED"
 READ_ONLY_TOOLS: Final = {
-    "claude": frozenset({"Read", "Grep", "Glob"}),
-    "pi": frozenset({"read", "ls"}),
+    "claude": frozenset({"Read", "Grep", "Glob", "Ls", "Find"}),
+    "pi": frozenset({"read", "grep", "find", "ls"}),
 }
 RECOVERY_TOOL: Final = "mosaic_context_recover"
 

packages/mosaic/framework/tools/lease-broker/launch-runtime.py

@@ -8,9 +8,7 @@ import json
 import os
 import socket
 import sys
-import time
 from collections.abc import Callable, Mapping, Sequence
-from datetime import datetime, timezone
 from pathlib import Path
 from typing import Final
 
@@ -55,48 +53,6 @@ def broker_request(socket_path: Path, request: dict[str, object]) -> dict[str, o
     return value
 
 
-def _self_starttime() -> str | None:
-    """Field 22 of our own /proc stat — the anchor starttime the broker records.
-
-    Read past the comm field's parens, since a process name may contain them.
-    """
-    try:
-        raw = Path(f"/proc/{os.getpid()}/stat").read_text()
-        return raw.rsplit(")", 1)[1].split()[19]
-    except (OSError, IndexError, ValueError):
-        return None
-
-
-def _append_launch_record(environ: Mapping[str, str], record: dict[str, object]) -> None:
-    """Append one NDJSON event to the #797 Runtime Session Ledger.
-
-    `fleet/run/sessions/` is operator-classified in framework-manifest.txt and is
-    already covered by test-upgrade-manifest-guard.sh, so an upgrade can neither
-    overwrite nor prune it. Files 0600 under a 0700 dir, matching what that guard
-    asserts.
-
-    Never raises: a launch must not be denied over bookkeeping. But it also never
-    fails silently — a missing record is exactly the kind of gap that made the
-    2026-08-06 MUTATOR_UNVERIFIED investigation cost a day.
-    """
-    try:
-        mosaic_home = environ.get("MOSAIC_HOME") or str(Path.home() / ".config" / "mosaic")
-        directory = Path(mosaic_home) / "fleet" / "run" / "sessions"
-        directory.mkdir(parents=True, exist_ok=True)
-        os.chmod(directory, 0o700)
-        framed = {
-            "seq": time.time_ns() // 1_000_000,
-            "ts": datetime.now(timezone.utc).isoformat(),
-            **record,
-        }
-        path = directory / "events.ndjson"
-        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
-        with os.fdopen(descriptor, "w") as handle:
-            handle.write(json.dumps(framed, separators=(",", ":")) + "\n")
-    except (OSError, ValueError, TypeError) as error:
-        print(f"[mosaic] WARNING: launch record not written: {error}", file=sys.stderr)
-
-
 def main(
     argv: Sequence[str] | None = None,
     *,
@@ -138,9 +94,8 @@ def main(
     # silent pass and never folded into the generic registration-failure
     # branch.
     try:
-        activation_capability = probe_activation_capability(source_environment)
         assert_activation_capability_matches(
-            activation_capability,
+            probe_activation_capability(source_environment),
             expected_activation_capability,
         )
     except VersionCouplingError as version_error:
@@ -173,32 +128,6 @@ def main(
         print("Mosaic lease broker registration failed; runtime launch denied.", file=sys.stderr)
         return 1
 
-    # Immutable launch record, half two. `mosaic` wrote `session.launch` with the
-    # config/provenance it knows; only this process knows the broker session id
-    # and the activation capability it just asserted. os.execvpe preserves the
-    # PID, so this PID is BOTH the anchor pid and the join key back to that
-    # record. Never fatal — bookkeeping must not deny a launch — but never
-    # silent either.
-    _append_launch_record(
-        source_environment,
-        {
-            "kind": "lease.register",
-            # Joins back to `mosaic`'s session.launch record. NOT pid: execRuntime()
-            # spawns rather than execs, so this process is a CHILD of mosaic with a
-            # different pid. This pid IS the broker anchor pid (os.execvpe below
-            # preserves it), which is a separate and still-useful fact.
-            "launch_id": source_environment.get("MOSAIC_LAUNCH_ID"),
-            "pid": os.getpid(),
-            "runtime": arguments.runtime,
-            "session_id": session_id,
-            "runtime_generation": generation,
-            "generation_file": str(generation_file),
-            "anchor_starttime": _self_starttime(),
-            "activation_capability": activation_capability,
-            "command": Path(command[0]).name,
-        },
-    )
-
     environment = dict(source_environment)
     environment["MOSAIC_LEASE_SESSION_ID"] = session_id
     environment["MOSAIC_RUNTIME_GENERATION"] = str(generation)

packages/mosaic/framework/tools/lease-broker/lease_promote.py

@@ -1,337 +0,0 @@
-#!/usr/bin/env python3
-"""Lease promotion client — the half the enforcement toolkit never shipped.
-
-The enforcement half (``daemon.py`` + ``mutator-gate.py``) ships and denies. The
-promotion half has no production caller anywhere in the package: as of 0.0.48,
-0.0.49 and 0.0.50-next.2207, ``begin_verification`` / ``observe_receipt`` /
-``promote_lease`` are invoked only by ``broker-test-client.ts``, the acceptance
-spec, unit tests, and two probes under ``docs/``. Consequence: **no lease on any
-host can reach VERIFIED**, so every mutator is denied ``MUTATOR_UNVERIFIED`` by a
-gate nothing can satisfy.
-
-THE PROTOCOL (``daemon.py:578-754``)
-------------------------------------
-  1. ``begin_verification`` — broker revokes, mints a challenge, and returns the
-     exact ``receipt`` text the MODEL must emit
-  2. *the model emits that text verbatim as its ENTIRE latest message*
-  3. the runtime adapter ships that message to the daemon-owned observer socket
-  4. ``observe_receipt``  -> ``PENDING_PROMOTION``
-  5. ``promote_lease``    -> ``VERIFIED``
-
-THIS MODULE IMPLEMENTS 1, 4 AND 5 — NEVER 2
--------------------------------------------
-Step 2 is the security property, not a formality. ``is_verbatim_receipt`` uses
-``hmac.compare_digest`` against the exact minted string — explicitly "not a
-transcript substring" (``receipt_challenge.py``). Promotion therefore requires a
-live model that received the challenge in its context and echoed it exactly.
-
-``receipt-observer-client.py`` will post ANY string as the latest assistant
-message. A promotion client that posted its own receipt would satisfy the broker
-while proving nothing — a gate-disabler indistinguishable from a working fix
-unless someone looks for it. **This module never posts a receipt.** Emitting it
-belongs to the runtime adapter, where a real model turn happens.
-
-The construction binds the exact normative source bytes. ``h_source`` /
-``h_payload`` are derived by the framework's own
-``normative_fragments.build_payload`` rather than reimplemented: the broker
-derives them the same way and any divergence yields ``PAYLOAD_BINDING_MISMATCH``.
-There must be exactly one implementation.
-
-WHAT THE BINDING DOES *NOT* PROVE
----------------------------------
-It is tempting to read a VERIFIED lease as "this agent is running THIS law".
-**It does not mean that**, and writing it down that way is how the belief spread.
-The broker holds no reference copy of any normative source and never opens one;
-it recomputes ``h_source`` / ``h_payload`` from the fragment bytes THIS CLIENT
-sent and compares them to the binding THIS CLIENT sent (``daemon.py:602-616``).
-Both sides of that comparison originate here, so it detects corruption in
-transit and nothing else. What the binding actually asserts is "the client
-claims these bytes, self-consistently".
-
-Making it mean the stronger thing requires the broker to re-read the on-disk
-sources itself, against a manifest the agent cannot rewrite — i.e. broker code
-attestation under its own uid. Until then, do not cite a VERIFIED lease as
-evidence of law integrity.
-
-Usage
------
-    lease_promote.py --begin                 # prints the receipt the MODEL must emit
-    lease_promote.py --complete <challenge>  # after the adapter observed it
-"""
-
-from __future__ import annotations
-
-import argparse
-import base64
-import hashlib
-import json
-import os
-import socket
-import sys
-from pathlib import Path
-from typing import Final
-
-# Isolated (`python -I`) adapter invocations must still import co-located
-# framework modules; never depend on the caller's PYTHONPATH.
-_MODULE_DIRECTORY = str(Path(__file__).resolve().parent)
-if _MODULE_DIRECTORY not in sys.path:
-    sys.path.insert(0, _MODULE_DIRECTORY)
-
-from normative_fragments import NormativeFragment, build_payload  # noqa: E402
-
-MAX_FRAME: Final = 64 * 1024
-BROKER_TIMEOUT_SECONDS: Final = 3.0
-SCHEMA_VERSION: Final = 1
-MANIFEST_VERSION: Final = 1
-GENERATOR_VERSION: Final = "mosaic/lease_promote@1"
-DEFAULT_TTL_SECONDS: Final = 3600
-
-# Normative sources whose exact bytes bind the lease, in binding order. Order is
-# load-bearing: ``h_source`` frames the resolved sequence, so reordering changes
-# the derivation. Never fabricate a source that is not on disk.
-FRAGMENT_SOURCES: Final = (
-    "CONSTITUTION.md",
-    "AGENTS.md",
-    "SOUL.md",
-    "USER.md",
-    "STANDARDS.md",
-    "TOOLS.md",
-)
-
-# Framework-owned sources, reconciled on every upgrade — `install.sh:76`
-# FRAMEWORK_OWNED and `config/file-adapter.ts` FRAMEWORK_OWNED_FILES — plus the
-# per-runtime contract shipped under `framework/runtime/<runtime>/`. A deployment
-# missing one of these is broken, not minimal, so their absence is refused rather
-# than silently dropped from the binding.
-#
-# SOUL.md and USER.md are deliberately excluded: install.sh does not seed them
-# ("intentionally NOT seeded here — they are generated by `mosaic init`"), so a
-# fresh install legitimately lacks both. TOOLS.md is user-seeded on first install
-# only. Absence of those three is reported, not fatal.
-REQUIRED_SOURCES: Final = frozenset({"CONSTITUTION.md", "AGENTS.md", "STANDARDS.md"})
-
-
-class IncompleteBinding(RuntimeError):
-    """A source that must bind this lease could not be read.
-
-    **Never downgrade this to a skip.** The broker recomputes the hashes from the
-    fragments it is sent, so an omitted fragment is internally consistent and
-    ``PAYLOAD_BINDING_MISMATCH`` cannot fire — a partial law promotes exactly like
-    a complete one, and nothing downstream can tell the difference. Dropping an
-    unreadable source therefore does not degrade the binding, it forges a smaller
-    one. Fail here, where the omission is still visible.
-    """
-
-
-def mosaic_home() -> Path:
-    return Path(os.environ.get("MOSAIC_HOME") or Path.home() / ".config" / "mosaic")
-
-
-def broker_socket() -> Path:
-    value = os.environ.get("MOSAIC_LEASE_BROKER_SOCKET")
-    if value:
-        return Path(value)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR")
-    if runtime_dir:
-        return Path(runtime_dir) / "mosaic-lease" / "broker.sock"
-    return Path(f"/run/user/{os.getuid()}/mosaic-lease/broker.sock")
-
-
-def session_identity() -> tuple[str, int, str]:
-    """Session id, CURRENT generation, runtime.
-
-    The generation file wins over the env var, matching ``lease_generation.py``.
-    Sending a generation HIGHER than the broker's would revoke this session's own
-    authority (``daemon.py:342-344``), so this never guesses.
-    """
-    session_id = os.environ["MOSAIC_LEASE_SESSION_ID"]
-    runtime = os.environ["MOSAIC_LEASE_RUNTIME"]
-    state_file = os.environ.get("MOSAIC_LEASE_GENERATION_FILE")
-    if state_file:
-        try:
-            return session_id, int(Path(state_file).read_text().strip()), runtime
-        except (OSError, ValueError):
-            pass
-    return session_id, int(os.environ["MOSAIC_RUNTIME_GENERATION"]), runtime
-
-
-def build_construction(runtime: str) -> tuple[dict[str, object], object]:
-    """Assemble the wire construction and derive its hashes with the sole builder."""
-    runtime_contract = f"runtime/{runtime}/RUNTIME.md"
-    sources = list(FRAGMENT_SOURCES) + [runtime_contract]
-    required = REQUIRED_SOURCES | {runtime_contract}
-    wire_fragments: list[dict[str, str]] = []
-    objects: list[NormativeFragment] = []
-    absent: list[str] = []
-
-    for source_id in sources:
-        try:
-            content = (mosaic_home() / source_id).read_bytes()
-        except FileNotFoundError:
-            # Genuinely not on disk. Legitimate only for operator-owned sources.
-            if source_id in required:
-                raise IncompleteBinding(
-                    f"required normative source is absent: {source_id}"
-                ) from None
-            absent.append(source_id)
-            continue
-        except OSError as exc:
-            # The path resolves but will not read — EACCES, EIO, EISDIR, ELOOP.
-            # That is an anomaly for EVERY source, optional ones included: an
-            # unreadable file is not an un-configured one, and treating it as
-            # absent is what lets a permission change quietly shrink the law.
-            raise IncompleteBinding(
-                f"normative source is present but unreadable: {source_id} "
-                f"({type(exc).__name__})"
-            ) from exc
-
-        digest = hashlib.sha256(content).hexdigest()
-        wire_fragments.append(
-            {
-                "source_id": source_id,
-                "content_base64": base64.b64encode(content).decode("ascii"),
-                "expected_sha256": digest,
-            }
-        )
-        objects.append(NormativeFragment(source_id, content, digest))
-
-    if not wire_fragments:
-        raise IncompleteBinding("no normative sources found — refusing an empty binding")
-
-    # Absence is legitimate here but never invisible. The omission is already
-    # baked into h_source (the framed source sequence differs), but nothing
-    # compares h_source to an expected value, so this line is the only place a
-    # human learns the binding was narrower than the full set.
-    if absent:
-        print(
-            f"lease_promote: binding omits absent operator sources: {', '.join(absent)}",
-            file=sys.stderr,
-        )
-
-    result = build_payload(
-        manifest_version=MANIFEST_VERSION,
-        generator_version=GENERATOR_VERSION,
-        fragments=objects,
-    )
-    if result.injectionDecision != "ACCEPTED" or not result.promotion:
-        raise RuntimeError(f"construction refused locally: {result.source_reason}")
-
-    return (
-        {
-            "manifest_version": MANIFEST_VERSION,
-            "generator_version": GENERATOR_VERSION,
-            "fragments": wire_fragments,
-        },
-        result,
-    )
-
-
-def broker_request(payload: dict[str, object]) -> dict[str, object]:
-    raw = (json.dumps(payload, separators=(",", ":")) + "\n").encode()
-    if len(raw) > MAX_FRAME:
-        raise ValueError(
-            f"request too large ({len(raw)} bytes); broker frame cap is {MAX_FRAME}"
-        )
-    response = bytearray()
-    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
-        connection.settimeout(BROKER_TIMEOUT_SECONDS)
-        connection.connect(str(broker_socket()))
-        connection.sendall(raw)
-        connection.shutdown(socket.SHUT_WR)
-        while len(response) <= MAX_FRAME:
-            chunk = connection.recv(4096)
-            if not chunk:
-                break
-            response.extend(chunk)
-    if len(response) > MAX_FRAME or not response.endswith(b"\n"):
-        raise ValueError("invalid broker reply")
-    value = json.loads(response)
-    if not isinstance(value, dict):
-        raise ValueError("invalid broker reply")
-    return value
-
-
-def begin(
-    ttl_seconds: int = DEFAULT_TTL_SECONDS,
-    compaction_epoch: int = 0,
-    request_epoch: int = 0,
-) -> dict[str, object]:
-    """Step 1. Returns the broker reply, including the exact ``receipt`` text."""
-    session_id, generation, runtime = session_identity()
-    construction, derived = build_construction(runtime)
-    return broker_request(
-        {
-            "action": "begin_verification",
-            "session_id": session_id,
-            "runtime_generation": generation,
-            "runtime": runtime,
-            "ttl_seconds": ttl_seconds,
-            "binding": {
-                "compaction_epoch": compaction_epoch,
-                "request_epoch": request_epoch,
-                "h_source": derived.h_source,
-                "h_payload": derived.h_payload,
-                "schema_version": SCHEMA_VERSION,
-            },
-            "construction": construction,
-        }
-    )
-
-
-def complete(challenge: str) -> dict[str, object]:
-    """Steps 4-5. Assumes the model already emitted the receipt and the adapter
-    shipped it to the observer socket."""
-    session_id, generation, _ = session_identity()
-    observed = broker_request(
-        {
-            "action": "observe_receipt",
-            "session_id": session_id,
-            "runtime_generation": generation,
-            "receipt_challenge": challenge,
-        }
-    )
-    if observed.get("ok") is not True or observed.get("state") != "PENDING_PROMOTION":
-        return {"stage": "observe_receipt", **observed}
-    promoted = broker_request(
-        {
-            "action": "promote_lease",
-            "session_id": session_id,
-            "runtime_generation": generation,
-            "receipt_challenge": challenge,
-        }
-    )
-    return {"stage": "promote_lease", **promoted}
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Mosaic lease promotion client.")
-    group = parser.add_mutually_exclusive_group(required=True)
-    group.add_argument(
-        "--begin",
-        action="store_true",
-        help="mint a challenge; prints the receipt the MODEL must emit verbatim",
-    )
-    group.add_argument(
-        "--complete",
-        metavar="CHALLENGE",
-        help="observe the emitted receipt and promote the lease",
-    )
-    parser.add_argument("--ttl-seconds", type=int, default=DEFAULT_TTL_SECONDS)
-    arguments = parser.parse_args(argv)
-
-    try:
-        if arguments.begin:
-            print(json.dumps(begin(ttl_seconds=arguments.ttl_seconds), indent=2))
-        else:
-            print(json.dumps(complete(arguments.complete), indent=2))
-    except KeyError as exc:
-        print(f"missing lease environment: {exc}; not a lease-gated session", file=sys.stderr)
-        return 2
-    except (OSError, ValueError, RuntimeError, json.JSONDecodeError) as exc:
-        print(f"{type(exc).__name__}: {exc}", file=sys.stderr)
-        return 2
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

packages/mosaic/framework/tools/lease-broker/promote-begin.py

@@ -1,399 +0,0 @@
-#!/usr/bin/env python3
-"""Claude UserPromptSubmit hook for operator-triggered lease promotion."""
-
-from __future__ import annotations
-
-import fcntl
-import importlib.util
-import json
-import os
-import secrets
-import stat
-import subprocess
-import sys
-import time
-from collections.abc import Callable, Mapping
-from pathlib import Path
-from typing import Final, TextIO
-
-_MODULE_DIRECTORY = str(Path(__file__).resolve().parent)
-if _MODULE_DIRECTORY not in sys.path:
-    sys.path.insert(0, _MODULE_DIRECTORY)
-
-from receipt_challenge import receipt_for  # noqa: E402
-
-_observer_spec = importlib.util.spec_from_file_location(
-    "mosaic_receipt_observer_client", Path(__file__).resolve().with_name("receipt-observer-client.py")
-)
-if _observer_spec is None or _observer_spec.loader is None:
-    raise RuntimeError("unable to load receipt observer client")
-_observer_module = importlib.util.module_from_spec(_observer_spec)
-_observer_spec.loader.exec_module(_observer_module)
-observer_request = _observer_module.observer_request
-
-MAX_FRAME: Final = 64 * 1024
-PENDING_MAX_AGE_SECONDS: Final = 60 * 60
-PROMOTER_TIMEOUT_SECONDS: Final = 10.0
-PROMOTION_PROMPT: Final = "/mosaic-promote"
-PROMOTER: Final = Path(__file__).resolve().with_name("lease_promote.py")
-PENDING_DIRECTORY: Final = "mosaic-lease"
-AUTHORIZATION_DIRECTORY: Final = "authorizations"
-AUTHORIZATION_TTL_SECONDS: Final = 60
-LEASE_TTL_SECONDS: Final = 60 * 60
-LOCK_FILE: Final = "promotion.lock"
-RESULT_FILE: Final = "last-result.json"
-EXPECTED_BEGIN_KEYS: Final = frozenset(
-    {"ok", "state", "receipt_challenge", "receipt", "binding"}
-)
-EXPECTED_BINDING_KEYS: Final = frozenset(
-    {
-        "compaction_epoch",
-        "request_epoch",
-        "h_source",
-        "h_payload",
-        "runtime_generation",
-        "schema_version",
-    }
-)
-
-
-class PromotionAlreadyInProgress(RuntimeError):
-    pass
-
-
-def reject_duplicate_json_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
-    value: dict[str, object] = {}
-    for key, item in pairs:
-        if key in value:
-            raise ValueError("duplicate promoter JSON key")
-        value[key] = item
-    return value
-
-
-def read_hook_input(stream: object) -> dict[str, object]:
-    raw = getattr(stream, "buffer", stream).read(MAX_FRAME + 1)
-    if not isinstance(raw, bytes) or len(raw) > MAX_FRAME:
-        raise ValueError("invalid UserPromptSubmit input")
-    value = json.loads(raw, object_pairs_hook=reject_duplicate_json_keys)
-    if not isinstance(value, dict):
-        raise ValueError("invalid UserPromptSubmit input")
-    return value
-
-
-def emit_context(stream: TextIO, message: str) -> None:
-    json.dump(
-        {
-            "hookSpecificOutput": {
-                "hookEventName": "UserPromptSubmit",
-                "additionalContext": message,
-            }
-        },
-        stream,
-        separators=(",", ":"),
-    )
-    stream.write("\n")
-
-
-def session_pending_name(environ: Mapping[str, str]) -> tuple[Path, str]:
-    runtime_dir = Path(environ["XDG_RUNTIME_DIR"])
-    session_id = environ["MOSAIC_LEASE_SESSION_ID"]
-    if not runtime_dir.is_absolute():
-        raise ValueError("XDG_RUNTIME_DIR must be absolute")
-    if len(session_id) != 64 or any(character not in "0123456789abcdef" for character in session_id):
-        raise ValueError("invalid lease session id")
-    return runtime_dir, f"pending-{session_id}"
-
-
-def open_pending_directory(runtime_dir: Path) -> int:
-    directory_flags = (
-        os.O_RDONLY
-        | getattr(os, "O_CLOEXEC", 0)
-        | getattr(os, "O_DIRECTORY", 0)
-        | getattr(os, "O_NOFOLLOW", 0)
-    )
-    runtime_descriptor = os.open(runtime_dir, directory_flags)
-    try:
-        runtime_metadata = os.fstat(runtime_descriptor)
-        if (
-            not stat.S_ISDIR(runtime_metadata.st_mode)
-            or runtime_metadata.st_uid != os.getuid()
-            or stat.S_IMODE(runtime_metadata.st_mode) != 0o700
-        ):
-            raise ValueError("unsafe XDG runtime directory")
-        try:
-            os.mkdir(PENDING_DIRECTORY, mode=0o700, dir_fd=runtime_descriptor)
-        except FileExistsError:
-            pass
-        descriptor = os.open(PENDING_DIRECTORY, directory_flags, dir_fd=runtime_descriptor)
-    finally:
-        os.close(runtime_descriptor)
-
-    metadata = os.fstat(descriptor)
-    if (
-        not stat.S_ISDIR(metadata.st_mode)
-        or metadata.st_uid != os.getuid()
-        or stat.S_IMODE(metadata.st_mode) != 0o700
-    ):
-        os.close(descriptor)
-        raise ValueError("unsafe promotion pending directory")
-    return descriptor
-
-
-def acquire_lock(directory_descriptor: int) -> int:
-    flags = (
-        os.O_RDWR
-        | os.O_CREAT
-        | getattr(os, "O_CLOEXEC", 0)
-        | getattr(os, "O_NOFOLLOW", 0)
-    )
-    descriptor = os.open(LOCK_FILE, flags, 0o600, dir_fd=directory_descriptor)
-    metadata = os.fstat(descriptor)
-    if (
-        not stat.S_ISREG(metadata.st_mode)
-        or metadata.st_uid != os.getuid()
-        or stat.S_IMODE(metadata.st_mode) != 0o600
-    ):
-        os.close(descriptor)
-        raise ValueError("unsafe promotion lock file")
-    try:
-        fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
-    except BlockingIOError as error:
-        os.close(descriptor)
-        raise PromotionAlreadyInProgress() from error
-    return descriptor
-
-
-def sweep_stale_pending(directory_descriptor: int, current_time: float) -> None:
-    cutoff = current_time - PENDING_MAX_AGE_SECONDS
-    removed = False
-    with os.scandir(directory_descriptor) as entries:
-        for candidate in entries:
-            if not (
-                candidate.name.startswith("pending-")
-                or candidate.name.startswith(".pending-")
-            ):
-                continue
-            try:
-                metadata = candidate.stat(follow_symlinks=False)
-                if metadata.st_mtime < cutoff and not stat.S_ISDIR(metadata.st_mode):
-                    os.unlink(candidate.name, dir_fd=directory_descriptor)
-                    removed = True
-            except FileNotFoundError:
-                continue
-    if removed:
-        os.fsync(directory_descriptor)
-
-
-def consume_authorization(directory_descriptor: int, session_id: str, wall_clock: float) -> str | None:
-    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
-    try:
-        authorization_descriptor = os.open(AUTHORIZATION_DIRECTORY, flags, dir_fd=directory_descriptor)
-    except FileNotFoundError:
-        return None
-    try:
-        metadata = os.fstat(authorization_descriptor)
-        if not stat.S_ISDIR(metadata.st_mode) or metadata.st_uid != os.getuid() or stat.S_IMODE(metadata.st_mode) != 0o700:
-            raise ValueError("unsafe promotion authorization directory")
-        name = f"{session_id}.auth"
-        try:
-            descriptor = os.open(name, os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0), dir_fd=authorization_descriptor)
-        except FileNotFoundError:
-            return None
-        try:
-            token_metadata = os.fstat(descriptor)
-            if not stat.S_ISREG(token_metadata.st_mode) or token_metadata.st_uid != os.getuid() or stat.S_IMODE(token_metadata.st_mode) != 0o600 or token_metadata.st_size <= 0 or token_metadata.st_size > MAX_FRAME:
-                raise ValueError("unsafe promotion authorization")
-            raw = os.read(descriptor, MAX_FRAME + 1)
-        finally:
-            os.close(descriptor)
-        os.unlink(name, dir_fd=authorization_descriptor)
-        os.fsync(authorization_descriptor)
-        token = json.loads(raw, object_pairs_hook=reject_duplicate_json_keys)
-        if not isinstance(token, dict) or set(token) != {"nonce", "seat", "session_id", "expires_at", "ts"}:
-            return None
-        nonce = token.get("nonce")
-        expires_at = token.get("expires_at")
-        issued_at = token.get("ts")
-        if token.get("session_id") != session_id or not isinstance(token.get("seat"), str) or not isinstance(nonce, str) or len(nonce) != 64 or any(char not in "0123456789abcdef" for char in nonce) or type(expires_at) not in (int, float) or type(issued_at) not in (int, float) or expires_at <= wall_clock or expires_at > issued_at + AUTHORIZATION_TTL_SECONDS:
-            return None
-        return nonce
-    finally:
-        os.close(authorization_descriptor)
-
-
-def write_result(directory_descriptor: int, attempt_id: str, verified: bool, reason: str | None, session_id: str, wall_clock: float) -> None:
-    temporary = f".{RESULT_FILE}.tmp-{secrets.token_hex(8)}"
-    descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0), 0o600, dir_fd=directory_descriptor)
-    try:
-        os.fchmod(descriptor, 0o600)
-        with os.fdopen(descriptor, "w", encoding="utf-8", closefd=False) as stream:
-            json.dump({"attempt_id": attempt_id, "expires_at_wallclock": wall_clock + LEASE_TTL_SECONDS if verified else None, "reason": reason, "session_id": session_id, "ts": wall_clock, "verified": verified}, stream, separators=(",", ":"), sort_keys=True)
-            stream.flush(); os.fsync(stream.fileno())
-        os.replace(temporary, RESULT_FILE, src_dir_fd=directory_descriptor, dst_dir_fd=directory_descriptor)
-        os.fsync(directory_descriptor)
-    finally:
-        os.close(descriptor)
-
-
-def write_pending(directory_descriptor: int, name: str, challenge: str) -> None:
-    temporary = f".{name}.tmp-{secrets.token_hex(8)}"
-    flags = (
-        os.O_WRONLY
-        | os.O_CREAT
-        | os.O_EXCL
-        | getattr(os, "O_CLOEXEC", 0)
-        | getattr(os, "O_NOFOLLOW", 0)
-    )
-    descriptor = os.open(temporary, flags, 0o600, dir_fd=directory_descriptor)
-    try:
-        os.fchmod(descriptor, 0o600)
-        with os.fdopen(descriptor, "w", encoding="utf-8", closefd=False) as stream:
-            stream.write(challenge)
-            stream.flush()
-            os.fsync(stream.fileno())
-        os.replace(
-            temporary,
-            name,
-            src_dir_fd=directory_descriptor,
-            dst_dir_fd=directory_descriptor,
-        )
-        os.fsync(directory_descriptor)
-    except Exception:
-        try:
-            os.unlink(temporary, dir_fd=directory_descriptor)
-        except FileNotFoundError:
-            pass
-        raise
-    finally:
-        os.close(descriptor)
-
-
-def parse_begin_reply(
-    completed: subprocess.CompletedProcess[str],
-) -> tuple[str, dict[str, object] | None]:
-    if completed.returncode != 0:
-        return f"PROMOTER_EXIT_{completed.returncode}", None
-    try:
-        value = json.loads(
-            completed.stdout,
-            object_pairs_hook=reject_duplicate_json_keys,
-        )
-    except (json.JSONDecodeError, RecursionError, TypeError, ValueError):
-        return "INVALID_PROMOTER_REPLY", None
-    if not isinstance(value, dict):
-        return "INVALID_PROMOTER_REPLY", None
-    if value.get("ok") is False and set(value) == {"ok", "code"}:
-        code = value.get("code")
-        return code if isinstance(code, str) and code else "PROMOTION_BEGIN_REFUSED", value
-    if set(value) != EXPECTED_BEGIN_KEYS or value.get("ok") is not True:
-        return "INVALID_PROMOTER_REPLY", None
-    if value.get("state") != "PENDING_VERIFICATION":
-        return "INVALID_PROMOTER_REPLY", None
-    challenge = value.get("receipt_challenge")
-    receipt = value.get("receipt")
-    binding = value.get("binding")
-    if (
-        not isinstance(challenge, str)
-        or len(challenge) != 64
-        or any(character not in "0123456789abcdef" for character in challenge)
-        or not isinstance(receipt, str)
-        or not isinstance(binding, dict)
-        or set(binding) != EXPECTED_BINDING_KEYS
-    ):
-        return "INVALID_PROMOTER_REPLY", None
-    integer_fields = (
-        "compaction_epoch",
-        "request_epoch",
-        "runtime_generation",
-        "schema_version",
-    )
-    if any(type(binding.get(field)) is not int or binding[field] < 0 for field in integer_fields):
-        return "INVALID_PROMOTER_REPLY", None
-    if not all(
-        isinstance(binding.get(field), str)
-        and len(binding[field]) == 64
-        and all(character in "0123456789abcdef" for character in binding[field])
-        for field in ("h_source", "h_payload")
-    ):
-        return "INVALID_PROMOTER_REPLY", None
-    if not secrets.compare_digest(
-        receipt.encode("utf-8"),
-        receipt_for(challenge, binding).encode("utf-8"),
-    ):
-        return "INVALID_PROMOTER_REPLY", None
-    return "", value
-
-
-def main(
-    *,
-    environ: Mapping[str, str] | None = None,
-    stdin: object | None = None,
-    stdout: TextIO | None = None,
-    stderr: TextIO | None = None,
-    run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
-    now: Callable[[], float] = time.time,
-) -> int:
-    source_environment = os.environ if environ is None else environ
-    input_stream = sys.stdin if stdin is None else stdin
-    output_stream = sys.stdout if stdout is None else stdout
-    error_stream = sys.stderr if stderr is None else stderr
-
-    try:
-        hook_input = read_hook_input(input_stream)
-    except (OSError, RecursionError, ValueError, json.JSONDecodeError) as error:
-        print(f"Mosaic promotion trigger ignored invalid hook input: {error}", file=error_stream)
-        return 0
-    if hook_input.get("prompt") != PROMOTION_PROMPT:
-        return 0
-
-    directory_descriptor: int | None = None
-    lock_descriptor: int | None = None
-    try:
-        runtime_dir, pending_name = session_pending_name(source_environment)
-        session_id = source_environment["MOSAIC_LEASE_SESSION_ID"]
-        directory_descriptor = open_pending_directory(runtime_dir)
-        lock_descriptor = acquire_lock(directory_descriptor)
-        wall_clock = now()
-        nonce = consume_authorization(directory_descriptor, session_id, wall_clock)
-        if nonce is None:
-            write_result(directory_descriptor, "0" * 64, False, "NOT_AUTHORIZED", session_id, wall_clock)
-            print("Mosaic promotion denied: NOT_AUTHORIZED.", file=error_stream)
-            return 0
-        sweep_stale_pending(directory_descriptor, wall_clock)
-        completed = run([sys.executable, "-I", "-S", "-B", str(PROMOTER), "--begin"], check=False, capture_output=True, text=True, env=dict(source_environment), timeout=PROMOTER_TIMEOUT_SECONDS)
-        code, reply = parse_begin_reply(completed)
-        if code or reply is None:
-            write_result(directory_descriptor, nonce, False, code or "PROMOTION_BEGIN_FAILED", session_id, now())
-            return 0
-        challenge = str(reply["receipt_challenge"])
-        observation = observer_request(
-            Path(source_environment["MOSAIC_RECEIPT_OBSERVER_SOCKET"]),
-            {"action": "record_runtime_observation", "session_id": session_id, "runtime_generation": int(source_environment["MOSAIC_RUNTIME_GENERATION"]), "runtime": "claude", "latest_assistant_message": reply["receipt"]},
-        )
-        if set(observation) != {"ok"} or observation.get("ok") is not True:
-            write_result(directory_descriptor, challenge, False, "OBSERVATION_REJECTED", session_id, now())
-            return 0
-        completion = run([sys.executable, "-I", "-S", "-B", str(PROMOTER), "--complete", challenge], check=False, capture_output=True, text=True, env=dict(source_environment), timeout=PROMOTER_TIMEOUT_SECONDS)
-        try:
-            outcome = json.loads(completion.stdout, object_pairs_hook=reject_duplicate_json_keys)
-        except (json.JSONDecodeError, ValueError):
-            outcome = None
-        if completion.returncode == 0 and isinstance(outcome, dict) and outcome.get("stage") == "promote_lease" and outcome.get("ok") is True and outcome.get("state") == "VERIFIED":
-            write_result(directory_descriptor, challenge, True, None, session_id, now())
-        else:
-            reason = outcome.get("code") if isinstance(outcome, dict) and isinstance(outcome.get("code"), str) else "PROMOTION_INCOMPLETE"
-            write_result(directory_descriptor, challenge, False, reason, session_id, now())
-    except PromotionAlreadyInProgress:
-        print("Mosaic promotion denied: PROMOTION_ALREADY_IN_PROGRESS.", file=error_stream)
-    except (KeyError, OSError, RecursionError, ValueError, subprocess.SubprocessError) as error:
-        print(f"Mosaic promotion begin failed: {type(error).__name__}: {error}", file=error_stream)
-    finally:
-        if lock_descriptor is not None:
-            os.close(lock_descriptor)
-        if directory_descriptor is not None:
-            os.close(directory_descriptor)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

packages/mosaic/framework/tools/lease-broker/promote-complete.py

@@ -1,361 +0,0 @@
-#!/usr/bin/env python3
-"""Claude Stop hook that completes a pending operator-triggered promotion."""
-
-from __future__ import annotations
-
-import fcntl
-import json
-import os
-import secrets
-import stat
-import subprocess
-import sys
-import time
-from collections.abc import Callable, Mapping
-from pathlib import Path
-from typing import Final, NamedTuple, TextIO
-
-MAX_FRAME: Final = 64 * 1024
-PROMOTER_TIMEOUT_SECONDS: Final = 10.0
-LEASE_TTL_SECONDS: Final = 60 * 60
-PROMOTER: Final = Path(__file__).resolve().with_name("lease_promote.py")
-PENDING_DIRECTORY: Final = "mosaic-lease"
-LOCK_FILE: Final = "promotion.lock"
-RESULT_FILE: Final = "last-result.json"
-TERMINAL_FAILURE_CODES: Final = frozenset(
-    {
-        "RECEIPT_REPLAY",
-        "RECEIPT_MISMATCH",
-        "INVALID_LEASE_TRANSITION",
-        "PROMOTION_TOKEN_INVALID",
-    }
-)
-
-
-class PendingChallenge(NamedTuple):
-    value: str
-    device: int
-    inode: int
-
-
-def reject_duplicate_json_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
-    value: dict[str, object] = {}
-    for key, item in pairs:
-        if key in value:
-            raise ValueError("duplicate promoter JSON key")
-        value[key] = item
-    return value
-
-
-def session_pending_name(environ: Mapping[str, str]) -> tuple[Path, str]:
-    runtime_dir = Path(environ["XDG_RUNTIME_DIR"])
-    session_id = environ["MOSAIC_LEASE_SESSION_ID"]
-    if not runtime_dir.is_absolute():
-        raise ValueError("XDG_RUNTIME_DIR must be absolute")
-    if len(session_id) != 64 or any(character not in "0123456789abcdef" for character in session_id):
-        raise ValueError("invalid lease session id")
-    return runtime_dir, f"pending-{session_id}"
-
-
-def open_pending_directory(runtime_dir: Path) -> int | None:
-    directory_flags = (
-        os.O_RDONLY
-        | getattr(os, "O_CLOEXEC", 0)
-        | getattr(os, "O_DIRECTORY", 0)
-        | getattr(os, "O_NOFOLLOW", 0)
-    )
-    try:
-        runtime_descriptor = os.open(runtime_dir, directory_flags)
-    except FileNotFoundError:
-        return None
-    try:
-        runtime_metadata = os.fstat(runtime_descriptor)
-        if (
-            not stat.S_ISDIR(runtime_metadata.st_mode)
-            or runtime_metadata.st_uid != os.getuid()
-            or stat.S_IMODE(runtime_metadata.st_mode) != 0o700
-        ):
-            raise ValueError("unsafe XDG runtime directory")
-        try:
-            descriptor = os.open(PENDING_DIRECTORY, directory_flags, dir_fd=runtime_descriptor)
-        except FileNotFoundError:
-            return None
-    finally:
-        os.close(runtime_descriptor)
-
-    metadata = os.fstat(descriptor)
-    if (
-        not stat.S_ISDIR(metadata.st_mode)
-        or metadata.st_uid != os.getuid()
-        or stat.S_IMODE(metadata.st_mode) != 0o700
-    ):
-        os.close(descriptor)
-        raise ValueError("unsafe promotion pending directory")
-    return descriptor
-
-
-def acquire_lock(directory_descriptor: int) -> int:
-    flags = (
-        os.O_RDWR
-        | os.O_CREAT
-        | getattr(os, "O_CLOEXEC", 0)
-        | getattr(os, "O_NOFOLLOW", 0)
-    )
-    descriptor = os.open(LOCK_FILE, flags, 0o600, dir_fd=directory_descriptor)
-    metadata = os.fstat(descriptor)
-    if (
-        not stat.S_ISREG(metadata.st_mode)
-        or metadata.st_uid != os.getuid()
-        or stat.S_IMODE(metadata.st_mode) != 0o600
-    ):
-        os.close(descriptor)
-        raise ValueError("unsafe promotion lock file")
-    try:
-        fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
-    except BlockingIOError:
-        os.close(descriptor)
-        raise
-    return descriptor
-
-
-def read_pending(directory_descriptor: int, name: str) -> PendingChallenge | None:
-    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
-    try:
-        descriptor = os.open(name, flags, dir_fd=directory_descriptor)
-    except FileNotFoundError:
-        return None
-    try:
-        metadata = os.fstat(descriptor)
-        if (
-            not stat.S_ISREG(metadata.st_mode)
-            or metadata.st_uid != os.getuid()
-            or stat.S_IMODE(metadata.st_mode) != 0o600
-            or metadata.st_size <= 0
-            or metadata.st_size > MAX_FRAME
-        ):
-            raise ValueError("unsafe promotion pending file")
-        raw = os.read(descriptor, MAX_FRAME + 1)
-    finally:
-        os.close(descriptor)
-    if len(raw) > MAX_FRAME:
-        raise ValueError("oversized promotion challenge")
-    challenge = raw.decode("utf-8")
-    if (
-        len(challenge) != 64
-        or any(character not in "0123456789abcdef" for character in challenge)
-    ):
-        raise ValueError("invalid promotion challenge")
-    return PendingChallenge(challenge, metadata.st_dev, metadata.st_ino)
-
-
-def write_result(
-    directory_descriptor: int,
-    attempt_id: str,
-    verified: bool,
-    reason: str | None,
-    session_id: str,
-    wall_clock: float,
-) -> None:
-    result = {
-        "attempt_id": attempt_id,
-        "expires_at_wallclock": wall_clock + LEASE_TTL_SECONDS if verified else None,
-        "reason": reason,
-        "session_id": session_id,
-        "ts": wall_clock,
-        "verified": verified,
-    }
-    temporary = f".{RESULT_FILE}.tmp-{secrets.token_hex(8)}"
-    flags = (
-        os.O_WRONLY
-        | os.O_CREAT
-        | os.O_EXCL
-        | getattr(os, "O_CLOEXEC", 0)
-        | getattr(os, "O_NOFOLLOW", 0)
-    )
-    descriptor = os.open(temporary, flags, 0o600, dir_fd=directory_descriptor)
-    try:
-        os.fchmod(descriptor, 0o600)
-        with os.fdopen(descriptor, "w", encoding="utf-8", closefd=False) as stream:
-            json.dump(result, stream, separators=(",", ":"), sort_keys=True)
-            stream.flush()
-            os.fsync(stream.fileno())
-        os.replace(
-            temporary,
-            RESULT_FILE,
-            src_dir_fd=directory_descriptor,
-            dst_dir_fd=directory_descriptor,
-        )
-        os.fsync(directory_descriptor)
-    except Exception:
-        try:
-            os.unlink(temporary, dir_fd=directory_descriptor)
-        except FileNotFoundError:
-            pass
-        raise
-    finally:
-        os.close(descriptor)
-
-
-def delete_pending_if_unchanged(
-    directory_descriptor: int,
-    name: str,
-    pending: PendingChallenge,
-    error_stream: TextIO,
-) -> None:
-    quarantine = f".{name}.delete-{secrets.token_hex(8)}"
-    try:
-        os.rename(
-            name,
-            quarantine,
-            src_dir_fd=directory_descriptor,
-            dst_dir_fd=directory_descriptor,
-        )
-    except FileNotFoundError:
-        return
-    except OSError as error:
-        print(f"Mosaic promotion could not quarantine pending file: {error}", file=error_stream)
-        return
-
-    try:
-        moved = os.stat(
-            quarantine,
-            dir_fd=directory_descriptor,
-            follow_symlinks=False,
-        )
-        if (moved.st_dev, moved.st_ino) == (pending.device, pending.inode):
-            os.unlink(quarantine, dir_fd=directory_descriptor)
-            os.fsync(directory_descriptor)
-            return
-
-        print("Mosaic promotion pending file changed; preserving replacement.", file=error_stream)
-        try:
-            os.link(
-                quarantine,
-                name,
-                src_dir_fd=directory_descriptor,
-                dst_dir_fd=directory_descriptor,
-                follow_symlinks=False,
-            )
-        except FileExistsError:
-            print(
-                f"Mosaic promotion preserved replacement as {quarantine}.",
-                file=error_stream,
-            )
-        else:
-            os.unlink(quarantine, dir_fd=directory_descriptor)
-        os.fsync(directory_descriptor)
-    except OSError as error:
-        print(f"Mosaic promotion could not resolve pending file: {error}", file=error_stream)
-
-
-def parse_reply(completed: subprocess.CompletedProcess[str]) -> dict[str, object] | None:
-    if completed.returncode != 0:
-        return None
-    try:
-        value = json.loads(
-            completed.stdout,
-            object_pairs_hook=reject_duplicate_json_keys,
-        )
-    except (json.JSONDecodeError, RecursionError, TypeError, ValueError):
-        return None
-    if not isinstance(value, dict):
-        return None
-    if set(value) == {"stage", "ok", "state"}:
-        if (
-            value.get("stage") == "promote_lease"
-            and value.get("ok") is True
-            and value.get("state") == "VERIFIED"
-        ):
-            return value
-        return None
-    if set(value) == {"stage", "ok", "code"}:
-        if (
-            value.get("stage") in {"observe_receipt", "promote_lease"}
-            and value.get("ok") is False
-            and isinstance(value.get("code"), str)
-            and value.get("code")
-        ):
-            return value
-    return None
-
-
-def main(
-    *,
-    environ: Mapping[str, str] | None = None,
-    stderr: TextIO | None = None,
-    run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
-    now: Callable[[], float] = time.time,
-) -> int:
-    source_environment = os.environ if environ is None else environ
-    error_stream = sys.stderr if stderr is None else stderr
-    directory_descriptor: int | None = None
-    lock_descriptor: int | None = None
-
-    try:
-        runtime_dir, pending_name = session_pending_name(source_environment)
-        session_id = source_environment["MOSAIC_LEASE_SESSION_ID"]
-        directory_descriptor = open_pending_directory(runtime_dir)
-        if directory_descriptor is None:
-            return 0
-        try:
-            lock_descriptor = acquire_lock(directory_descriptor)
-        except (BlockingIOError, FileNotFoundError):
-            print("Mosaic promotion completion deferred: promotion is in progress.", file=error_stream)
-            return 0
-        pending = read_pending(directory_descriptor, pending_name)
-        if pending is None:
-            return 0
-        completed = run(
-            [
-                sys.executable,
-                "-I",
-                "-S",
-                "-B",
-                str(PROMOTER),
-                "--complete",
-                pending.value,
-            ],
-            check=False,
-            capture_output=True,
-            text=True,
-            env=dict(source_environment),
-            timeout=PROMOTER_TIMEOUT_SECONDS,
-        )
-        reply = parse_reply(completed)
-        if reply is not None and reply.get("ok") is True:
-            write_result(directory_descriptor, pending.value, True, None, session_id, now())
-            delete_pending_if_unchanged(
-                directory_descriptor,
-                pending_name,
-                pending,
-                error_stream,
-            )
-            print("Mosaic lease promotion completed.", file=error_stream)
-            return 0
-
-        if reply is not None:
-            code = str(reply["code"])
-            print(f"Mosaic promotion incomplete: {code}.", file=error_stream)
-            if code in TERMINAL_FAILURE_CODES:
-                write_result(directory_descriptor, pending.value, False, code, session_id, now())
-                delete_pending_if_unchanged(
-                    directory_descriptor,
-                    pending_name,
-                    pending,
-                    error_stream,
-                )
-        else:
-            diagnostic = completed.stderr.strip() or f"promoter exit {completed.returncode}"
-            print(f"Mosaic promotion retryable failure: {diagnostic}.", file=error_stream)
-    except (KeyError, OSError, RecursionError, UnicodeError, ValueError, subprocess.SubprocessError) as error:
-        print(f"Mosaic promotion completion deferred: {type(error).__name__}: {error}", file=error_stream)
-    finally:
-        if lock_descriptor is not None:
-            os.close(lock_descriptor)
-        if directory_descriptor is not None:
-            os.close(directory_descriptor)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

packages/mosaic/framework/tools/lease-broker/receipt-observer-client.py

@@ -22,23 +22,13 @@ from typing import Final
 MAX_FRAME: Final = 64 * 1024
 BROKER_TIMEOUT_SECONDS: Final = 1.5
 MAX_TRANSCRIPT_BYTES: Final = 4 * 1024 * 1024
-BENIGN_OBSERVATION_UNAVAILABLE_CODE: Final = "OBSERVATION_UNAVAILABLE"
-
-
-def reject_duplicate_json_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
-    value: dict[str, object] = {}
-    for key, item in pairs:
-        if key in value:
-            raise ValueError("duplicate observer JSON key")
-        value[key] = item
-    return value
 
 
 def read_json(stream: object) -> dict[str, object]:
     raw = getattr(stream, "buffer", stream).read(MAX_FRAME + 1)
     if not isinstance(raw, bytes) or len(raw) > MAX_FRAME:
         raise ValueError("invalid observer input")
-    value = json.loads(raw, object_pairs_hook=reject_duplicate_json_keys)
+    value = json.loads(raw)
     if not isinstance(value, dict):
         raise ValueError("invalid observer input")
     return value
@@ -110,9 +100,9 @@ def observer_request(socket_path: Path, request: dict[str, object]) -> dict[str,
             if not chunk:
                 break
             response.extend(chunk)
-    if len(response) > MAX_FRAME or response.count(b"\n") != 1 or not response.endswith(b"\n"):
+    if len(response) > MAX_FRAME or not response.endswith(b"\n"):
         raise ValueError("invalid observer reply")
-    value = json.loads(response[:-1], object_pairs_hook=reject_duplicate_json_keys)
+    value = json.loads(response)
     if not isinstance(value, dict):
         raise ValueError("invalid observer reply")
     return value
@@ -129,12 +119,7 @@ def main(argv: Sequence[str] | None = None, *, environ: Mapping[str, str] | None
         if arguments.runtime == "claude":
             if not arguments.latest_entry:
                 raise ValueError("Claude observer requires --latest-entry")
-            if "last_assistant_message" in source:
-                message = source["last_assistant_message"]
-                if not isinstance(message, str):
-                    raise ValueError("invalid Claude observer input")
-            else:
-                message = claude_latest_entry(source)
+            message = claude_latest_entry(source)
         else:
             if arguments.latest_entry:
                 raise ValueError("Pi observer is message_end only")
@@ -148,18 +133,10 @@ def main(argv: Sequence[str] | None = None, *, environ: Mapping[str, str] | None
             "runtime": arguments.runtime,
             "latest_assistant_message": message,
         })
-    except (KeyError, OSError, RecursionError, ValueError, json.JSONDecodeError) as error:
+    except (KeyError, OSError, ValueError, json.JSONDecodeError) as error:
         print(f"Mosaic receipt observer refused: {error}", file=sys.stderr)
         return 2
-    if set(reply) == {"ok"} and reply.get("ok") is True:
-        return 0
-    if (
-        set(reply) == {"ok", "code"}
-        and reply.get("ok") is False
-        and reply.get("code") == BENIGN_OBSERVATION_UNAVAILABLE_CODE
-    ):
-        return 0
-    return 2
+    return 0 if reply == {"ok": True} else 2
 
 
 if __name__ == "__main__":

packages/mosaic/framework/tools/lease-broker/receipt_challenge.py

@@ -33,7 +33,7 @@ def is_verbatim_receipt(message: str, challenge: str, binding: dict[str, object]
     """Require the exact one current-cycle receipt, not a transcript substring."""
 
     expected = receipt_for(challenge, binding)
-    return hmac.compare_digest(message.encode("utf-8"), expected.encode("utf-8"))
+    return hmac.compare_digest(message, expected)
 
 
 def latest_assistant_digest(message: str) -> str:

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/cli.ts

@@ -15,7 +15,6 @@ import { registerAgentCommand } from './commands/agent.js';
 import { registerInteractionCommand } from './commands/interaction.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerFleetCommand } from './commands/fleet.js';
-import { registerPromoteCommand } from './commands/promote.js';
 import { registerMissionCommand } from './commands/mission.js';
 import { registerUninstallCommand } from './commands/uninstall.js';
 import { registerRestoreCommand } from './commands/restore.js';
@@ -24,6 +23,7 @@ import { registerSkillCommand } from './commands/skill.js';
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerLeaseCapabilityProbe } from './commands/lease-activation-probe.js';
 import { registerInstallOrderingGuardCommand } from './commands/install-ordering-guard.js';
+import { registerBrainProvisionCommand } from './commands/brain-provision-command.js';
 import { registerAuthCommand } from './commands/auth.js';
 import { registerFederationCommand } from './commands/federation.js';
 import { registerGatewayCommand } from './commands/gateway.js';
@@ -86,6 +86,10 @@ registerLeaseCapabilityProbe(program);
 
 registerInstallOrderingGuardCommand(program);
 
+// ─── durable brain P7 provisioner (hidden; #1051) ───────────────────────
+
+registerBrainProvisionCommand(program);
+
 // ─── login ──────────────────────────────────────────────────────────────
 
 program
@@ -371,7 +375,6 @@ registerInteractionCommand(program);
 // ─── fleet ─────────────────────────────────────────────────────────────
 
 registerFleetCommand(program);
-registerPromoteCommand(program);
 
 // ─── config ────────────────────────────────────────────────────────────
 

packages/mosaic/src/commands/brain-doctor-check.spec.ts

@@ -0,0 +1,272 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface CommandRequest {
+  readonly program: 'git' | 'mosaic';
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+}
+
+interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface InstalledDoctorResult {
+  readonly status: 'ok' | 'warn' | 'error';
+  readonly findings: readonly {
+    readonly code: string;
+    readonly reasonCode: string | null;
+  }[];
+  readonly lines: readonly string[];
+}
+
+interface BrainDoctorModule {
+  runInstalledBrainDoctorCheck(
+    options: {
+      readonly mosaicHome: string;
+      readonly home: string;
+      readonly identity?: string;
+      readonly fix: boolean;
+    },
+    run: (request: CommandRequest) => CommandResult,
+  ): InstalledDoctorResult;
+}
+
+const MODULE_PATH = './brain-doctor-check.js';
+const roots: string[] = [];
+
+async function loadDoctor(requirement: string): Promise<BrainDoctorModule> {
+  try {
+    return (await import(MODULE_PATH)) as BrainDoctorModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: installed brain doctor check is absent (${detail})`);
+  }
+}
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-brain-doctor-'));
+  roots.push(root);
+  return root;
+}
+
+function installConfig(root: string): { readonly home: string; readonly mosaicHome: string } {
+  const home = join(root, 'home');
+  const mosaicHome = join(home, '.config', 'mosaic');
+  mkdirSync(join(mosaicHome, 'cred'), { recursive: true });
+  mkdirSync(join(mosaicHome, 'brain'), { recursive: true });
+  writeFileSync(
+    join(mosaicHome, 'cred', 'estates.json'),
+    JSON.stringify({
+      version: 1,
+      estates: [
+        {
+          name: 'homelab',
+          readOnlyControlIdentity: 'read-control',
+          hosts: [
+            {
+              host: 'git.example.invalid',
+              provider: 'gitea',
+              apiBaseUrl: 'https://git.example.invalid',
+              tokenPrefix: 'gitea-example',
+            },
+          ],
+        },
+      ],
+    }),
+    { mode: 0o600 },
+  );
+  writeFileSync(
+    join(mosaicHome, 'brain', 'owners.json'),
+    JSON.stringify({
+      version: 1,
+      estates: [
+        {
+          estate: 'homelab',
+          laneArchiveOwners: [{ kind: 'provider-user', login: 'durable-owner' }],
+          standingProcess: { kind: 'glpi-queue', queue: 'mosaic-brain-remediation' },
+          controls: { publicIdentity: 'public-control', privateIdentity: 'private-control' },
+        },
+      ],
+    }),
+    { mode: 0o600 },
+  );
+  writeFileSync(
+    join(mosaicHome, '.install-manifest.json'),
+    JSON.stringify({
+      version: 2,
+      status: 'committed',
+      sourceRepo: 'https://git.example.invalid/example/stack.git',
+    }),
+    { mode: 0o600 },
+  );
+  return { home, mosaicHome };
+}
+
+function validateResult(outcome: 'ok' | 'refused' | 'indeterminate', reasonCode: string): string {
+  const exitCode = outcome === 'ok' ? 0 : outcome === 'refused' ? 10 : 30;
+  return JSON.stringify({
+    schemaVersion: 1,
+    operation: 'validate',
+    outcome,
+    exitCode,
+    retryable: false,
+    subject: {
+      identity: 'seat-a',
+      estate: 'homelab',
+      host: 'git.example.invalid',
+      repo: 'durable-owner/mosaic-brain',
+    },
+    mutation: 'none',
+    reason: { code: reasonCode, message: 'non-secret' },
+    evidence: {
+      providerIdentity:
+        outcome === 'ok'
+          ? {
+              login: 'seat-a',
+              endpoint: 'GET /api/v1/user',
+              contentType: 'application/json',
+            }
+          : null,
+      repositoryPermission:
+        outcome === 'ok'
+          ? {
+              requested: 'write',
+              effective: 'write',
+              endpoint: 'GET /api/v1/repos/durable-owner/mosaic-brain',
+              contentType: 'application/json',
+            }
+          : null,
+      writeDifferential:
+        outcome === 'ok'
+          ? {
+              state: 'can-write',
+              credentialBinding: 'same-resolution',
+              transportPrincipal: 'seat-a',
+              authenticatedReceivePack: 'advertised',
+              readOnlyControl: {
+                identity: 'read-control',
+                providerPermission: 'read',
+                receivePack: 'refused',
+              },
+              unauthenticatedReceivePack: 'refused',
+              artifactCreated: false,
+              proves: 'non-secret evidence',
+              doesNotProve: 'branch update acceptance',
+            }
+          : null,
+    },
+    audit: { journalId: 'opaque', state: 'sealed' },
+  });
+}
+
+afterEach((): void => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('installed mosaic doctor brain checks', (): void => {
+  it('derives the target from the committed install manifest and surfaces a missing clone plus refusal', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-08 installed doctor missing clone');
+    const config = installConfig(tempRoot());
+    const requests: CommandRequest[] = [];
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { ...config, identity: 'seat-a', fix: false },
+      (request): CommandResult => {
+        requests.push(request);
+        return {
+          status: 10,
+          stdout: validateResult('refused', 'no-token-for-identity'),
+          stderr: 'refused reason=no-token-for-identity',
+        };
+      },
+    );
+
+    expect(result.status).toBe('warn');
+    expect(result.findings.map((finding) => finding.code)).toEqual(
+      expect.arrayContaining(['brain-clone-missing', 'brain-write-access-refused']),
+    );
+    expect(result.lines.join('\n')).toMatch(/brain-clone-missing/);
+    expect(result.lines.join('\n')).toMatch(/no-token-for-identity/);
+    expect(requests[0]?.args).toContain('durable-owner/mosaic-brain');
+  });
+
+  it('fails closed without an explicit identity and performs no command', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-08 explicit identity');
+    const config = installConfig(tempRoot());
+    let calls = 0;
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { ...config, fix: false },
+      (): CommandResult => {
+        calls += 1;
+        return { status: 0, stdout: '', stderr: '' };
+      },
+    );
+
+    expect(result).toMatchObject({
+      status: 'error',
+      findings: [{ code: 'brain-identity-required', reasonCode: 'identity-required' }],
+    });
+    expect(calls).toBe(0);
+  });
+
+  it('treats identity-not-measured as an error, not no-write refusal and not a repairable grant case', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-08 identity measurement axis');
+    const config = installConfig(tempRoot());
+    const requests: CommandRequest[] = [];
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { ...config, identity: 'seat-a', fix: true },
+      (request): CommandResult => {
+        requests.push(request);
+        return {
+          status: 30,
+          stdout: validateResult('indeterminate', 'identity-not-measured'),
+          stderr: 'identity not measured',
+        };
+      },
+    );
+
+    expect(result.status).toBe('error');
+    expect(result.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'brain-write-access-indeterminate',
+          reasonCode: 'identity-not-measured',
+        }),
+      ]),
+    );
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+  });
+
+  it('is wired into the top-level mosaic doctor path before the shell audit runs', (): void => {
+    const launch = readFileSync(join(process.cwd(), 'src', 'commands', 'launch.ts'), 'utf8');
+
+    expect(launch).toContain('runInstalledBrainDoctorCheck');
+    expect(launch).toContain('defaultInstalledBrainDoctorOptions');
+    expect(launch).toContain('systemCommandRunner');
+    expect(launch).toMatch(/brainCheckFailed[\s\S]*runDoctorScriptAndExit/);
+  });
+
+  it('reports a missing or unsafe registry/manifest as configuration error rather than defaulting estate', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-02 missing mapping fail-closed');
+    const root = tempRoot();
+    const home = join(root, 'home');
+    const mosaicHome = join(home, '.config', 'mosaic');
+    mkdirSync(mosaicHome, { recursive: true });
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { home, mosaicHome, identity: 'seat-a', fix: false },
+      (): CommandResult => ({ status: 0, stdout: '', stderr: '' }),
+    );
+
+    expect(result.status).toBe('error');
+    expect(result.findings[0]?.code).toMatch(/brain-(estate-registry|install-manifest)-/);
+    expect(result.lines.join('\n')).not.toMatch(/homelab|usc/);
+  });
+});

packages/mosaic/src/commands/brain-doctor-check.ts

@@ -0,0 +1,152 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { readBrainConfigSecure } from './brain-secure-config.js';
+import { resolveBrainOwnerPolicy } from './brain-owner-resolver.js';
+import { deriveBrainTarget } from './brain-store.js';
+import {
+  collectBrainDoctorReport,
+  repairBrainDoctor,
+  type CommandRunner,
+  type DoctorRuntimeReport,
+} from './brain-store-runtime.js';
+
+const IDENTITY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const manifestSchema = z
+  .object({
+    version: z.literal(2),
+    status: z.literal('committed'),
+    sourceRepo: z.string().min(1),
+  })
+  .passthrough();
+
+export interface InstalledDoctorFinding {
+  readonly code: string;
+  readonly reasonCode: string | null;
+}
+
+export interface InstalledDoctorResult {
+  readonly status: 'ok' | 'warn' | 'error';
+  readonly findings: readonly InstalledDoctorFinding[];
+  readonly lines: readonly string[];
+}
+
+function configurationError(code: string, reasonCode = code): InstalledDoctorResult {
+  return {
+    status: 'error',
+    findings: [{ code, reasonCode }],
+    lines: [`[mosaic-doctor] [ERROR] ${code}`],
+  };
+}
+
+function renderReport(report: DoctorRuntimeReport): InstalledDoctorResult {
+  const findings = report.findings.map(
+    (finding): InstalledDoctorFinding => ({
+      code: finding.code,
+      reasonCode: finding.reasonCode,
+    }),
+  );
+  const hard = findings.some(
+    (finding): boolean =>
+      finding.code.endsWith('-error') ||
+      finding.code.endsWith('-indeterminate') ||
+      finding.code === 'brain-not-git-repository' ||
+      finding.code === 'brain-root-permissions-unsafe',
+  );
+  const status: InstalledDoctorResult['status'] =
+    findings.length === 0 ? 'ok' : hard ? 'error' : 'warn';
+  const severity = status === 'error' ? 'ERROR' : status === 'warn' ? 'WARN' : 'OK';
+  const lines =
+    findings.length === 0
+      ? ['[mosaic-doctor] [OK] mosaic-brain ready']
+      : findings.map(
+          (finding): string =>
+            `[mosaic-doctor] [${severity}] ${finding.code}${
+              finding.reasonCode === null ? '' : ` reason=${finding.reasonCode}`
+            }`,
+        );
+  return { status, findings, lines };
+}
+
+export function runInstalledBrainDoctorCheck(
+  options: {
+    readonly mosaicHome: string;
+    readonly home: string;
+    readonly identity?: string;
+    readonly fix: boolean;
+  },
+  run: CommandRunner,
+): InstalledDoctorResult {
+  if (options.identity === undefined || !IDENTITY.test(options.identity)) {
+    return configurationError('brain-identity-required', 'identity-required');
+  }
+
+  const registryPath = join(options.mosaicHome, 'cred', 'estates.json');
+  const manifestPath = join(options.mosaicHome, '.install-manifest.json');
+  const ownerPolicyPath = join(options.mosaicHome, 'brain', 'owners.json');
+  let registrySource: string;
+  try {
+    registrySource = readBrainConfigSecure(registryPath, options.mosaicHome);
+  } catch {
+    return configurationError('brain-estate-registry-unavailable');
+  }
+  let manifestSource: string;
+  try {
+    manifestSource = readBrainConfigSecure(manifestPath, options.mosaicHome);
+  } catch {
+    return configurationError('brain-install-manifest-unavailable');
+  }
+  let manifestRaw: unknown;
+  try {
+    manifestRaw = JSON.parse(manifestSource);
+  } catch {
+    return configurationError('brain-install-manifest-invalid');
+  }
+  const manifest = manifestSchema.safeParse(manifestRaw);
+  if (!manifest.success) return configurationError('brain-install-manifest-invalid');
+  let ownerPolicySource: string;
+  try {
+    ownerPolicySource = readBrainConfigSecure(ownerPolicyPath, options.mosaicHome);
+  } catch {
+    return configurationError('brain-owner-policy-unavailable');
+  }
+  let preliminaryTarget: ReturnType<typeof deriveBrainTarget>;
+  try {
+    preliminaryTarget = deriveBrainTarget(registrySource, manifest.data.sourceRepo, 'policy-probe');
+  } catch {
+    return configurationError('brain-estate-registry-invalid');
+  }
+  const ownerPolicy = resolveBrainOwnerPolicy(ownerPolicySource, preliminaryTarget.estate);
+  if (ownerPolicy === undefined) return configurationError('brain-owner-policy-invalid');
+
+  const input = {
+    registrySource,
+    targetGitUrl: manifest.data.sourceRepo,
+    brainNamespace: ownerPolicy.brainNamespace,
+    identity: options.identity,
+    root: join(options.home, '.mosaic'),
+  };
+  try {
+    return renderReport(
+      options.fix ? repairBrainDoctor(input, run) : collectBrainDoctorReport(input, run),
+    );
+  } catch {
+    return configurationError('brain-estate-registry-invalid');
+  }
+}
+
+export function defaultInstalledBrainDoctorOptions(fix: boolean): {
+  readonly mosaicHome: string;
+  readonly home: string;
+  readonly identity?: string;
+  readonly fix: boolean;
+} {
+  const home = homedir();
+  const identity = process.env['MOSAIC_GIT_IDENTITY'];
+  return {
+    mosaicHome: process.env['MOSAIC_HOME'] ?? join(home, '.config', 'mosaic'),
+    home,
+    ...(identity === undefined ? {} : { identity }),
+    fix,
+  };
+}

packages/mosaic/src/commands/brain-installer-integration.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function installerSource(): string {
+  return readFileSync(join(process.cwd(), '..', '..', 'tools', 'install.sh'), 'utf8');
+}
+
+describe('root installer P7 durable-brain integration', (): void => {
+  it('records the configured source repository in the committed manifest for doctor derivation', (): void => {
+    const installer = installerSource();
+
+    expect(installer).toContain('sourceRepo:');
+    expect(installer).toMatch(/sourceRepo:\s*process\.argv\[/);
+    expect(installer).toMatch(/MANIFEST_SOURCE_REPO/);
+  });
+
+  it('invokes the broker-only provision command in P7 with explicit owner and refusal controls', (): void => {
+    const installer = installerSource();
+    const provision = installer.indexOf('__brain-provision');
+    const p7 = installer.indexOf('state_phase_begin P7');
+
+    expect(provision).toBeGreaterThan(-1);
+    expect(p7).toBeGreaterThan(-1);
+    expect(provision).toBeGreaterThan(p7);
+    for (const flag of [
+      '--identity',
+      '--target-url',
+      '--owner',
+      '--refusal-identity',
+      '--lane',
+      '--owner-policy',
+    ]) {
+      expect(installer).toContain(flag);
+    }
+    expect(installer).not.toMatch(/__brain-provision[^\n]*(?:token|password|authorization)/i);
+  });
+
+  it('journals ~/.mosaic and the owner policy as P7 mutations and checks the resulting object', (): void => {
+    const installer = installerSource();
+
+    expect(installer).toContain('state_record_mutation P7 "$HOME/.mosaic"');
+    expect(installer).toContain('state_record_mutation P7 "$MOSAIC_HOME/brain/owners.json"');
+    expect(installer).toMatch(/P7\)[\s\S]*\.mosaic[\s\S]*(?:remote|get-url)[\s\S]*main/);
+  });
+
+  it('discovers every legacy lane directory rather than silently migrating only one lane', (): void => {
+    const installer = installerSource();
+
+    expect(installer).toMatch(/memory\/lanes/);
+    expect(installer).toMatch(/for\s+[^\n]*lane/);
+    expect(installer).toMatch(/__brain-provision[\s\S]*--lane/);
+  });
+});

packages/mosaic/src/commands/brain-owner-resolver.spec.ts

@@ -0,0 +1,373 @@
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Red-first owner-authority resolver contract for #1051.
+ *
+ * Fixtures are operator-agnostic. The HOMELAB owner name belongs in the local
+ * estate policy, never in framework source. Anonymous lookup is intentional:
+ * the ruled owner class is PUBLIC and least-privilege seats may lack read:user.
+ */
+
+interface MigrationOwnerResolution {
+  readonly verdict: 'resolved' | 'refused' | 'not-measured';
+  readonly reasonCode: string;
+  readonly principal: {
+    readonly name: string;
+    readonly kind: 'durable-human';
+  } | null;
+  readonly authority: {
+    readonly system: 'gitea';
+    readonly endpoint: string;
+    readonly contentType: 'application/json';
+  } | null;
+}
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+interface OwnerResolverModule {
+  resolveProviderDurableOwner(
+    input: {
+      readonly estateRegistrySource: string;
+      readonly ownerPolicySource: string;
+      readonly host: string;
+      readonly requestedOwner: string;
+    },
+    dependencies: {
+      readonly fetch: FetchLike;
+      readonly absentControlName: () => string;
+    },
+  ): Promise<MigrationOwnerResolution>;
+}
+
+const MODULE_PATH = './brain-owner-resolver.js';
+
+async function loadResolver(requirement: string): Promise<OwnerResolverModule> {
+  try {
+    return (await import(MODULE_PATH)) as OwnerResolverModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: brain owner resolver is absent (${detail})`);
+  }
+}
+
+function estateRegistry(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        name: 'homelab',
+        readOnlyControlIdentity: 'read-control',
+        hosts: [
+          {
+            host: 'git.example.invalid',
+            provider: 'gitea',
+            apiBaseUrl: 'https://git.example.invalid',
+            tokenPrefix: 'gitea-example',
+          },
+        ],
+      },
+    ],
+  });
+}
+
+function ownerPolicy(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        estate: 'homelab',
+        laneArchiveOwners: [{ kind: 'provider-user', login: 'durable-owner' }],
+        standingProcess: { kind: 'glpi-queue', queue: 'mosaic-brain-remediation' },
+        controls: {
+          publicIdentity: 'public-control',
+          privateIdentity: 'private-control',
+        },
+      },
+    ],
+  });
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8' },
+  });
+}
+
+function publicUser(login: string, active = false): Response {
+  return jsonResponse(200, {
+    id: 42,
+    login,
+    visibility: 'public',
+    active,
+  });
+}
+
+function identityFromUrl(input: string | URL | Request): string {
+  const value = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+  return decodeURIComponent(new URL(value).pathname.split('/').at(-1) ?? '');
+}
+
+function controlledFetch(
+  overrides: Readonly<Record<string, Response>> = {},
+  calls: Array<{ identity: string; authorization: string | null }> = [],
+): FetchLike {
+  return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const identity = identityFromUrl(input);
+    const headers = new Headers(init?.headers);
+    calls.push({ identity, authorization: headers.get('authorization') });
+    const override = overrides[identity];
+    if (override !== undefined) return override.clone();
+    if (identity === 'public-control') return publicUser('public-control');
+    if (identity === 'private-control' || identity === 'generated-absent-control') {
+      return jsonResponse(404, { message: 'not found' });
+    }
+    if (identity === 'durable-owner') return publicUser('durable-owner', false);
+    return jsonResponse(404, { message: 'not found' });
+  };
+}
+
+describe('provider-backed durable owner resolver', (): void => {
+  it('resolves an allowlisted PUBLIC owner by exact login with public/private/absent controls and ignores active=false', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 provider owner resolution');
+    const calls: Array<{ identity: string; authorization: string | null }> = [];
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: controlledFetch({}, calls),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toEqual({
+      verdict: 'resolved',
+      reasonCode: 'owner-verified',
+      principal: { name: 'user:durable-owner', kind: 'durable-human' },
+      authority: {
+        system: 'gitea',
+        endpoint: 'GET /api/v1/users/durable-owner',
+        contentType: 'application/json',
+      },
+    });
+    expect(calls.map((call) => call.identity)).toEqual([
+      'public-control',
+      'private-control',
+      'generated-absent-control',
+      'durable-owner',
+    ]);
+    expect(calls.every((call) => call.authorization === null)).toBe(true);
+  });
+
+  it('refuses provider redirects and configures a bounded no-redirect request', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 owner lookup SSRF boundary');
+    const requests: RequestInit[] = [];
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: async (_input, init): Promise<Response> => {
+          requests.push(init ?? {});
+          return new Response(JSON.stringify({ message: 'redirect' }), {
+            status: 302,
+            headers: {
+              'content-type': 'application/json',
+              location: 'http://127.0.0.1/internal',
+            },
+          });
+        },
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ verdict: 'not-measured', reasonCode: 'owner-control-invalid' });
+    expect(requests).toHaveLength(1);
+    expect(requests[0]?.redirect).toBe('manual');
+    expect(requests[0]?.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('cancels a chunked provider body as soon as it exceeds the byte ceiling', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 bounded owner response stream');
+    let cancelled = false;
+    const oversized = new ReadableStream<Uint8Array>({
+      start(controller): void {
+        controller.enqueue(new Uint8Array(200_000));
+        controller.enqueue(new Uint8Array(100_000));
+      },
+      cancel(): void {
+        cancelled = true;
+      },
+    });
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: async (): Promise<Response> =>
+          new Response(oversized, {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          }),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({
+      verdict: 'not-measured',
+      reasonCode: 'owner-unexpected-provider-shape',
+    });
+    expect(cancelled).toBe(true);
+  });
+
+  it('requires the GLPI standing remediation queue in the local estate policy', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 standing process policy');
+    const raw = JSON.parse(ownerPolicy()) as { estates: Array<Record<string, unknown>> };
+    delete raw.estates[0]?.['standingProcess'];
+    let fetchCalls = 0;
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: JSON.stringify(raw),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: async (): Promise<Response> => {
+          fetchCalls += 1;
+          return publicUser('durable-owner');
+        },
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ verdict: 'refused', reasonCode: 'owner-policy-invalid' });
+    expect(fetchCalls).toBe(0);
+  });
+
+  it('rejects a provider-valid but unlisted principal before provider lookup', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 provider-valid unlisted owner refusal');
+    const calls: Array<{ identity: string; authorization: string | null }> = [];
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:other-public-user',
+      },
+      {
+        fetch: controlledFetch({ 'other-public-user': publicUser('other-public-user') }, calls),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ verdict: 'refused', reasonCode: 'owner-not-allowlisted' });
+    expect(calls).toHaveLength(0);
+  });
+
+  it.each([
+    ['user:durable–owner', 'owner-name-invalid'],
+    [' user:durable-owner ', 'owner-name-invalid'],
+    ['user:durable.owner', 'owner-not-allowlisted'],
+    ['user:durable owner', 'owner-name-invalid'],
+    ['user:ｄurable-owner', 'owner-name-invalid'],
+    ['user:be-coder-07@mission-seat', 'owner-name-invalid'],
+  ] as const)(
+    'rejects non-canonical, unlisted, or transient-seat presentation %s before lookup',
+    async (name, reasonCode): Promise<void> => {
+      const resolver = await loadResolver('MB-REQ-09 owner allowlist grammar');
+      let fetchCalls = 0;
+
+      const result = await resolver.resolveProviderDurableOwner(
+        {
+          estateRegistrySource: estateRegistry(),
+          ownerPolicySource: ownerPolicy(),
+          host: 'git.example.invalid',
+          requestedOwner: name,
+        },
+        {
+          fetch: async (): Promise<Response> => {
+            fetchCalls += 1;
+            return publicUser('durable-owner');
+          },
+          absentControlName: (): string => 'generated-absent-control',
+        },
+      );
+
+      expect(result).toMatchObject({ verdict: 'refused', reasonCode });
+      expect(fetchCalls).toBe(0);
+    },
+  );
+
+  it('fails closed as not-resolvable rather than claiming a private-or-absent owner does not exist', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 private/absent ambiguity');
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: controlledFetch({ 'durable-owner': jsonResponse(404, { message: 'hidden' }) }),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({
+      verdict: 'not-measured',
+      reasonCode: 'owner-not-resolvable',
+      principal: null,
+    });
+    expect(JSON.stringify(result)).not.toMatch(/owner-not-found|does-not-exist/);
+  });
+
+  it.each([
+    ['public control hidden', { 'public-control': jsonResponse(404, {}) }],
+    ['public control login mismatch', { 'public-control': publicUser('other') }],
+    ['private control unexpectedly public', { 'private-control': publicUser('private-control') }],
+    [
+      'generated absent control unexpectedly resolves',
+      { 'generated-absent-control': publicUser('generated-absent-control') },
+    ],
+  ] as const)(
+    'makes the whole result not-measured when %s',
+    async (_caseName, overrides): Promise<void> => {
+      const resolver = await loadResolver('MB-REQ-09 owner resolver controls');
+
+      const result = await resolver.resolveProviderDurableOwner(
+        {
+          estateRegistrySource: estateRegistry(),
+          ownerPolicySource: ownerPolicy(),
+          host: 'git.example.invalid',
+          requestedOwner: 'user:durable-owner',
+        },
+        {
+          fetch: controlledFetch(overrides),
+          absentControlName: (): string => 'generated-absent-control',
+        },
+      );
+
+      expect(result).toMatchObject({
+        verdict: 'not-measured',
+        reasonCode: 'owner-control-invalid',
+      });
+    },
+  );
+});

packages/mosaic/src/commands/brain-owner-resolver.ts

@@ -0,0 +1,280 @@
+import { z } from 'zod';
+import { parseCredentialEstateRegistry } from '../credentials/estate-registry.js';
+import type { MigrationOwnerResolution } from './brain-store.js';
+
+const MAX_BODY_BYTES = 256 * 1024;
+const LOGIN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
+const REQUESTED_OWNER = /^user:(.+)$/;
+
+const ownerPolicySchema = z
+  .object({
+    version: z.literal(1),
+    estates: z
+      .array(
+        z
+          .object({
+            estate: z.string().min(1),
+            laneArchiveOwners: z
+              .array(
+                z
+                  .object({
+                    kind: z.literal('provider-user'),
+                    login: z.string().min(1),
+                  })
+                  .strict(),
+              )
+              .min(1),
+            standingProcess: z
+              .object({
+                kind: z.literal('glpi-queue'),
+                queue: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+              })
+              .strict(),
+            controls: z
+              .object({
+                publicIdentity: z.string().min(1),
+                privateIdentity: z.string().min(1),
+              })
+              .strict(),
+          })
+          .strict(),
+      )
+      .min(1),
+  })
+  .strict();
+
+const providerUserSchema = z
+  .object({
+    id: z.number().int(),
+    login: z.string().min(1),
+    visibility: z.literal('public'),
+  })
+  .passthrough();
+
+export type OwnerFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+function unresolved(reasonCode: string): MigrationOwnerResolution {
+  return {
+    verdict: 'not-measured',
+    reasonCode,
+    principal: null,
+    authority: null,
+  };
+}
+
+function refused(reasonCode: string): MigrationOwnerResolution {
+  return {
+    verdict: 'refused',
+    reasonCode,
+    principal: null,
+    authority: null,
+  };
+}
+
+function exactCanonicalLogin(value: string): boolean {
+  return value.normalize('NFKC') === value && LOGIN.test(value);
+}
+
+async function boundedJson(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.toLowerCase().startsWith('application/json')) {
+    throw new Error('owner-unexpected-content-type');
+  }
+  const declared = response.headers.get('content-length');
+  let declaredSize: number | null = null;
+  if (declared !== null) {
+    if (!/^\d+$/.test(declared)) throw new Error('owner-unexpected-provider-shape');
+    declaredSize = Number.parseInt(declared, 10);
+    if (!Number.isSafeInteger(declaredSize) || declaredSize > MAX_BODY_BYTES) {
+      throw new Error('owner-unexpected-provider-shape');
+    }
+  }
+  if (response.body === null) throw new Error('owner-unexpected-provider-shape');
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const next = await reader.read();
+    if (next.done) break;
+    total += next.value.byteLength;
+    if (total > MAX_BODY_BYTES) {
+      await reader.cancel('owner response exceeds byte ceiling');
+      throw new Error('owner-unexpected-provider-shape');
+    }
+    chunks.push(next.value);
+  }
+  if (declaredSize !== null && declaredSize !== total) {
+    throw new Error('owner-unexpected-provider-shape');
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body));
+  } catch {
+    throw new Error('owner-unexpected-provider-shape');
+  }
+}
+
+async function readPublicIdentity(
+  origin: string,
+  identity: string,
+  fetchImpl: OwnerFetch,
+): Promise<{ readonly status: number; readonly user: unknown }> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${origin}/api/v1/users/${encodeURIComponent(identity)}`, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        'User-Agent': 'mosaic-brain-owner/1',
+      },
+      redirect: 'manual',
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    throw new Error('owner-provider-unavailable');
+  }
+  return { status: response.status, user: await boundedJson(response) };
+}
+
+function publicIdentityMatches(value: unknown, identity: string): boolean {
+  const parsed = providerUserSchema.safeParse(value);
+  return parsed.success && parsed.data.login === identity;
+}
+
+export interface BrainOwnerPolicyBinding {
+  readonly brainNamespace: string;
+  readonly publicControl: string;
+  readonly privateControl: string;
+  readonly standingQueue: string;
+}
+
+export function resolveBrainOwnerPolicy(
+  ownerPolicySource: string,
+  estate: string,
+): BrainOwnerPolicyBinding | undefined {
+  let rawPolicy: unknown;
+  try {
+    rawPolicy = JSON.parse(ownerPolicySource);
+  } catch {
+    return undefined;
+  }
+  const policy = ownerPolicySchema.safeParse(rawPolicy);
+  if (!policy.success) return undefined;
+  const estatePolicies = policy.data.estates.filter(
+    (candidate): boolean => candidate.estate === estate,
+  );
+  if (estatePolicies.length !== 1) return undefined;
+  const estatePolicy = estatePolicies[0];
+  if (estatePolicy === undefined || estatePolicy.laneArchiveOwners.length !== 1) return undefined;
+  const brainNamespace = estatePolicy.laneArchiveOwners[0]?.login;
+  if (brainNamespace === undefined || !exactCanonicalLogin(brainNamespace)) return undefined;
+  return {
+    brainNamespace,
+    publicControl: estatePolicy.controls.publicIdentity,
+    privateControl: estatePolicy.controls.privateIdentity,
+    standingQueue: estatePolicy.standingProcess.queue,
+  };
+}
+
+export function parseRequestedOwner(requestedOwner: string): string | null {
+  if (requestedOwner.normalize('NFKC') !== requestedOwner) return null;
+  const match = REQUESTED_OWNER.exec(requestedOwner);
+  const login = match?.[1];
+  if (login === undefined || !exactCanonicalLogin(login)) return null;
+  return login;
+}
+
+export async function resolveProviderDurableOwner(
+  input: {
+    readonly estateRegistrySource: string;
+    readonly ownerPolicySource: string;
+    readonly host: string;
+    readonly requestedOwner: string;
+  },
+  dependencies: {
+    readonly fetch: OwnerFetch;
+    readonly absentControlName: () => string;
+  },
+): Promise<MigrationOwnerResolution> {
+  const requestedLogin = parseRequestedOwner(input.requestedOwner);
+  if (requestedLogin === null) return refused('owner-name-invalid');
+
+  const target = parseCredentialEstateRegistry(input.estateRegistrySource).resolveByHost(
+    input.host,
+  );
+  if (target === undefined) return refused('estate-host-unmapped');
+
+  const policy = resolveBrainOwnerPolicy(input.ownerPolicySource, target.estate);
+  if (policy === undefined) return refused('owner-policy-invalid');
+  if (policy.brainNamespace !== requestedLogin) return refused('owner-not-allowlisted');
+
+  const publicControl = policy.publicControl;
+  const privateControl = policy.privateControl;
+  const absentControl = dependencies.absentControlName();
+  if (
+    !exactCanonicalLogin(publicControl) ||
+    !exactCanonicalLogin(privateControl) ||
+    !exactCanonicalLogin(absentControl) ||
+    new Set([publicControl, privateControl, absentControl, requestedLogin]).size !== 4
+  ) {
+    return refused('owner-policy-invalid');
+  }
+
+  try {
+    const publicResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      publicControl,
+      dependencies.fetch,
+    );
+    if (publicResult.status !== 200 || !publicIdentityMatches(publicResult.user, publicControl)) {
+      return unresolved('owner-control-invalid');
+    }
+
+    const privateResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      privateControl,
+      dependencies.fetch,
+    );
+    if (privateResult.status !== 404) return unresolved('owner-control-invalid');
+
+    const absentResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      absentControl,
+      dependencies.fetch,
+    );
+    if (absentResult.status !== 404) return unresolved('owner-control-invalid');
+
+    const ownerResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      requestedLogin,
+      dependencies.fetch,
+    );
+    if (ownerResult.status === 401 || ownerResult.status === 403 || ownerResult.status === 404) {
+      return unresolved('owner-not-resolvable');
+    }
+    if (ownerResult.status !== 200) return unresolved('owner-provider-unavailable');
+    if (!publicIdentityMatches(ownerResult.user, requestedLogin)) {
+      return unresolved('owner-provider-identity-mismatch');
+    }
+    return {
+      verdict: 'resolved',
+      reasonCode: 'owner-verified',
+      principal: { name: `user:${requestedLogin}`, kind: 'durable-human' },
+      authority: {
+        system: 'gitea',
+        endpoint: `GET /api/v1/users/${requestedLogin}`,
+        contentType: 'application/json',
+      },
+    };
+  } catch (error: unknown) {
+    const reason = error instanceof Error ? error.message : 'owner-provider-unavailable';
+    if (reason === 'owner-unexpected-content-type') return unresolved(reason);
+    if (reason === 'owner-unexpected-provider-shape') return unresolved(reason);
+    return unresolved('owner-provider-unavailable');
+  }
+}

packages/mosaic/src/commands/brain-provision-command.spec.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { Command } from 'commander';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface BrainProvisionCommandModule {
+  readonly BRAIN_PROVISION_COMMAND: string;
+  registerBrainProvisionCommand(program: Command): void;
+  executeBrainProvisionCommand(
+    options: {
+      readonly mosaicHome: string;
+      readonly home: string;
+      readonly identity: string;
+      readonly refusalIdentity: string;
+      readonly targetUrl: string;
+      readonly owner: string;
+      readonly lane: string;
+      readonly sourceRoot?: string;
+      readonly brainRoot?: string;
+      readonly ownerPolicy?: string;
+      readonly registry?: string;
+    },
+    dependencies: {
+      readonly run: () => never;
+      readonly fetch: typeof fetch;
+      readonly absentControlName: () => string;
+    },
+  ): Promise<{
+    readonly status: 'provisioned' | 'blocked' | 'failed';
+    readonly reasonCode: string;
+  }>;
+}
+
+const MODULE_PATH = './brain-provision-command.js';
+const roots: string[] = [];
+
+async function loadCommand(requirement: string): Promise<BrainProvisionCommandModule> {
+  try {
+    return (await import(MODULE_PATH)) as BrainProvisionCommandModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: brain provision command is absent (${detail})`);
+  }
+}
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-brain-command-'));
+  roots.push(root);
+  return root;
+}
+
+afterEach((): void => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('internal P7 brain provision command', (): void => {
+  it('registers only explicit non-secret contract inputs and no credential/token lookup switches', async (): Promise<void> => {
+    const module = await loadCommand('MB-REQ-03 broker-only provision command');
+    const program = new Command();
+    module.registerBrainProvisionCommand(program);
+    const command = program.commands.find(
+      (candidate) => candidate.name() === module.BRAIN_PROVISION_COMMAND,
+    );
+
+    expect(command).toBeDefined();
+    const flags = command?.options.map((option) => option.flags) ?? [];
+    expect(flags.join(' ')).toContain('--identity');
+    expect(flags.join(' ')).toContain('--target-url');
+    expect(flags.join(' ')).toContain('--refusal-identity');
+    expect(flags.join(' ')).toContain('--owner-policy');
+    expect(flags.join(' ')).toContain('--owner');
+    expect(flags.join(' ')).toContain('--lane');
+    expect(flags.join(' ')).not.toMatch(/token|password|authorization|grant-authority/i);
+  });
+
+  it('is registered by the shipped CLI', async (): Promise<void> => {
+    const module = await loadCommand('MB-REQ-10 shipped P7 command');
+    const cli = readFileSync(join(process.cwd(), 'src', 'cli.ts'), 'utf8');
+
+    expect(cli).toContain('registerBrainProvisionCommand');
+    expect(cli).toContain(`registerBrainProvisionCommand(program)`);
+    expect(module.BRAIN_PROVISION_COMMAND).toBe('__brain-provision');
+  });
+
+  it('fails closed before commands when the local owner policy is absent', async (): Promise<void> => {
+    const module = await loadCommand('MB-REQ-09 owner policy required');
+    const root = tempRoot();
+    const home = join(root, 'home');
+    const mosaicHome = join(home, '.config', 'mosaic');
+    mkdirSync(join(mosaicHome, 'cred'), { recursive: true });
+    writeFileSync(
+      join(mosaicHome, 'cred', 'estates.json'),
+      JSON.stringify({ version: 1, estates: [] }),
+      { mode: 0o600 },
+    );
+    let commands = 0;
+
+    const result = await module.executeBrainProvisionCommand(
+      {
+        mosaicHome,
+        home,
+        identity: 'seat-a',
+        refusalIdentity: 'outside-seat',
+        targetUrl: 'https://git.example.invalid/example/stack.git',
+        owner: 'user:durable-owner',
+        lane: 'lane-a',
+      },
+      {
+        run: (): never => {
+          commands += 1;
+          throw new Error('must not run');
+        },
+        fetch,
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ status: 'failed', reasonCode: 'owner-policy-unavailable' });
+    expect(commands).toBe(0);
+  });
+});

packages/mosaic/src/commands/brain-provision-command.ts

@@ -0,0 +1,133 @@
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import { readBrainConfigSecure } from './brain-secure-config.js';
+import { provisionBrain, type ProvisionResult } from './brain-provision.js';
+import { systemCommandRunner, type CommandRunner } from './brain-store-runtime.js';
+import type { OwnerFetch } from './brain-owner-resolver.js';
+
+export const BRAIN_PROVISION_COMMAND = '__brain-provision';
+
+interface BrainProvisionCommandOptions {
+  readonly mosaicHome: string;
+  readonly home: string;
+  readonly identity: string;
+  readonly refusalIdentity: string;
+  readonly targetUrl: string;
+  readonly owner: string;
+  readonly lane: string;
+  readonly sourceRoot?: string;
+  readonly brainRoot?: string;
+  readonly ownerPolicy?: string;
+  readonly registry?: string;
+}
+
+interface BrainProvisionCommandDependencies {
+  readonly run: CommandRunner;
+  readonly fetch: OwnerFetch;
+  readonly absentControlName: () => string;
+}
+
+function configFailure(reasonCode: string): ProvisionResult {
+  return {
+    status: 'failed',
+    reasonCode,
+    findings: [{ code: `brain-${reasonCode}`, reasonCode }],
+    owner: null,
+    migration: null,
+  };
+}
+
+export async function executeBrainProvisionCommand(
+  options: BrainProvisionCommandOptions,
+  dependencies: BrainProvisionCommandDependencies,
+): Promise<ProvisionResult> {
+  const registry = options.registry ?? join(options.mosaicHome, 'cred', 'estates.json');
+  const ownerPolicy = options.ownerPolicy ?? join(options.mosaicHome, 'brain', 'owners.json');
+  let estateRegistrySource: string;
+  try {
+    estateRegistrySource = readBrainConfigSecure(registry, options.mosaicHome);
+  } catch {
+    return configFailure('estate-registry-unavailable');
+  }
+  let ownerPolicySource: string;
+  try {
+    ownerPolicySource = readBrainConfigSecure(ownerPolicy, options.mosaicHome);
+  } catch {
+    return configFailure('owner-policy-unavailable');
+  }
+
+  try {
+    return await provisionBrain(
+      {
+        estateRegistrySource,
+        ownerPolicySource,
+        targetGitUrl: options.targetUrl,
+        requestedOwner: options.owner,
+        identity: options.identity,
+        refusalIdentity: options.refusalIdentity,
+        root: options.brainRoot ?? join(options.home, '.mosaic'),
+        sourceRoot: options.sourceRoot ?? join(options.mosaicHome, 'memory'),
+        seat: options.identity,
+        lane: options.lane,
+        laneActive: false,
+      },
+      dependencies,
+    );
+  } catch {
+    return configFailure('brain-provision-exception');
+  }
+}
+
+export function registerBrainProvisionCommand(program: Command): void {
+  program
+    .command(BRAIN_PROVISION_COMMAND, { hidden: true })
+    .description('Internal installer P7 durable-brain provisioner')
+    .requiredOption('--identity <name>', 'explicit fleet identity')
+    .requiredOption('--target-url <url>', 'configured target git URL')
+    .requiredOption('--refusal-identity <name>', 'explicit out-of-estate negative control')
+    .requiredOption('--owner <owner>', 'policy-bound durable owner candidate')
+    .requiredOption('--lane <name>', 'source lane to migrate')
+    .option('--mosaic-home <path>', 'installed Mosaic home')
+    .option('--home <path>', 'principal home')
+    .option('--source-root <path>', 'legacy memory root')
+    .option('--brain-root <path>', 'per-estate brain checkout root')
+    .option('--owner-policy <path>', 'durable-owner allowlist policy')
+    .option('--registry <path>', 'estate registry path')
+    .action(async (raw: Record<string, string | undefined>): Promise<void> => {
+      const home = raw['home'] ?? homedir();
+      const mosaicHome =
+        raw['mosaicHome'] ?? process.env['MOSAIC_HOME'] ?? join(home, '.config', 'mosaic');
+      const result = await executeBrainProvisionCommand(
+        {
+          mosaicHome,
+          home,
+          identity: raw['identity']!,
+          targetUrl: raw['targetUrl']!,
+          refusalIdentity: raw['refusalIdentity']!,
+          owner: raw['owner']!,
+          lane: raw['lane']!,
+          ...(raw['sourceRoot'] === undefined ? {} : { sourceRoot: raw['sourceRoot'] }),
+          ...(raw['brainRoot'] === undefined ? {} : { brainRoot: raw['brainRoot'] }),
+          ...(raw['ownerPolicy'] === undefined ? {} : { ownerPolicy: raw['ownerPolicy'] }),
+          ...(raw['registry'] === undefined ? {} : { registry: raw['registry'] }),
+        },
+        {
+          run: systemCommandRunner,
+          fetch,
+          absentControlName: (): string => `mosaic-absent-${randomUUID()}`,
+        },
+      );
+      process.stdout.write(
+        `${JSON.stringify({
+          status: result.status,
+          reasonCode: result.reasonCode,
+          findings: result.findings,
+          owner: result.owner,
+          migration: result.migration,
+        })}\n`,
+      );
+      if (result.status !== 'provisioned') process.exitCode = result.status === 'blocked' ? 30 : 20;
+    });
+}

packages/mosaic/src/commands/brain-provision.spec.ts

@@ -0,0 +1,561 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface CommandRequest {
+  readonly program: 'git' | 'mosaic';
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+}
+
+interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+type CommandRunner = (request: CommandRequest) => CommandResult;
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+interface ProvisionResult {
+  readonly status: 'provisioned' | 'blocked' | 'failed';
+  readonly reasonCode: string;
+  readonly findings: readonly { code: string; reasonCode: string | null }[];
+  readonly owner: {
+    readonly verdict: 'resolved' | 'refused' | 'not-measured';
+    readonly reasonCode: string;
+  } | null;
+  readonly migration: {
+    readonly status: 'migrated' | 'reported' | 'failed';
+    readonly reported: readonly { path: string; reason: string }[];
+  } | null;
+}
+
+interface ProvisionModule {
+  provisionBrain(
+    input: {
+      readonly estateRegistrySource: string;
+      readonly ownerPolicySource: string;
+      readonly targetGitUrl: string;
+      readonly requestedOwner: string;
+      readonly identity: string;
+      readonly refusalIdentity: string;
+      readonly root: string;
+      readonly sourceRoot: string;
+      readonly seat: string;
+      readonly lane: string;
+      readonly laneActive: boolean;
+    },
+    dependencies: {
+      readonly run: CommandRunner;
+      readonly fetch: FetchLike;
+      readonly absentControlName: () => string;
+      readonly approveMigrationContent?: (path: string, content: Uint8Array) => boolean;
+    },
+  ): Promise<ProvisionResult>;
+}
+
+const MODULE_PATH = './brain-provision.js';
+const roots: string[] = [];
+
+async function loadProvisioner(requirement: string): Promise<ProvisionModule> {
+  try {
+    return (await import(MODULE_PATH)) as ProvisionModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: brain provisioner is absent (${detail})`);
+  }
+}
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-brain-provision-'));
+  roots.push(root);
+  return root;
+}
+
+function estateRegistry(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        name: 'homelab',
+        readOnlyControlIdentity: 'read-control',
+        hosts: [
+          {
+            host: 'git.example.invalid',
+            provider: 'gitea',
+            apiBaseUrl: 'https://git.example.invalid',
+            tokenPrefix: 'gitea-example',
+          },
+        ],
+      },
+    ],
+  });
+}
+
+function ownerPolicy(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        estate: 'homelab',
+        laneArchiveOwners: [{ kind: 'provider-user', login: 'durable-owner' }],
+        standingProcess: { kind: 'glpi-queue', queue: 'mosaic-brain-remediation' },
+        controls: { publicIdentity: 'public-control', privateIdentity: 'private-control' },
+      },
+    ],
+  });
+}
+
+function validateResult(
+  outcome: 'ok' | 'refused' | 'indeterminate',
+  reasonCode: string,
+  identity = 'seat-a',
+): string {
+  const exitCode = outcome === 'ok' ? 0 : outcome === 'refused' ? 10 : 30;
+  return JSON.stringify({
+    schemaVersion: 1,
+    operation: 'validate',
+    outcome,
+    exitCode,
+    retryable: false,
+    subject: {
+      identity,
+      estate: 'homelab',
+      host: 'git.example.invalid',
+      repo: 'durable-owner/mosaic-brain',
+    },
+    mutation: 'none',
+    reason: { code: reasonCode, message: 'non-secret' },
+    evidence: {
+      providerIdentity:
+        outcome === 'ok'
+          ? {
+              login: identity,
+              endpoint: 'GET /api/v1/user',
+              contentType: 'application/json',
+            }
+          : null,
+      repositoryPermission:
+        outcome === 'ok'
+          ? {
+              requested: 'write',
+              effective: 'write',
+              endpoint: 'GET /api/v1/repos/durable-owner/mosaic-brain',
+              contentType: 'application/json',
+            }
+          : null,
+      writeDifferential:
+        outcome === 'ok'
+          ? {
+              state: 'can-write',
+              credentialBinding: 'same-resolution',
+              transportPrincipal: identity,
+              authenticatedReceivePack: 'advertised',
+              readOnlyControl: {
+                identity: 'read-control',
+                providerPermission: 'read',
+                receivePack: 'refused',
+              },
+              unauthenticatedReceivePack: 'refused',
+              artifactCreated: false,
+              proves: 'non-secret evidence',
+              doesNotProve: 'branch update acceptance',
+            }
+          : null,
+    },
+    audit: { journalId: 'opaque', state: 'sealed' },
+  });
+}
+
+function publicUser(login: string): Response {
+  return new Response(JSON.stringify({ id: 1, login, visibility: 'public', active: false }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function ownerFetch(ownerStatus = 200): FetchLike {
+  return async (input): Promise<Response> => {
+    const raw = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    const identity = decodeURIComponent(new URL(raw).pathname.split('/').at(-1) ?? '');
+    if (identity === 'public-control') return publicUser(identity);
+    if (identity === 'private-control' || identity === 'generated-absent-control') {
+      return new Response(JSON.stringify({ message: 'hidden or absent' }), {
+        status: 404,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+    if (identity === 'durable-owner' && ownerStatus === 200) return publicUser(identity);
+    return new Response(JSON.stringify({ message: 'hidden or absent' }), {
+      status: ownerStatus,
+      headers: { 'content-type': 'application/json' },
+    });
+  };
+}
+
+function baseInput(root: string): {
+  readonly estateRegistrySource: string;
+  readonly ownerPolicySource: string;
+  readonly targetGitUrl: string;
+  readonly requestedOwner: string;
+  readonly identity: string;
+  readonly refusalIdentity: string;
+  readonly root: string;
+  readonly sourceRoot: string;
+  readonly seat: string;
+  readonly lane: string;
+  readonly laneActive: boolean;
+} {
+  return {
+    estateRegistrySource: estateRegistry(),
+    ownerPolicySource: ownerPolicy(),
+    targetGitUrl: 'https://git.example.invalid/example/stack.git',
+    requestedOwner: 'user:durable-owner',
+    identity: 'seat-a',
+    refusalIdentity: 'outside-seat',
+    root: join(root, 'brain'),
+    sourceRoot: join(root, 'local-memory'),
+    seat: 'seat-a',
+    lane: 'lane-a',
+    laneActive: false,
+  };
+}
+
+afterEach((): void => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('P7 brain provisioning orchestration', (): void => {
+  it('requires the P5 write-capability postcondition and never grants or clones on refusal', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-10 P5 before P7');
+    const root = tempRoot();
+    const requests: CommandRequest[] = [];
+
+    const result = await provisioner.provisionBrain(baseInput(root), {
+      run: (request): CommandResult => {
+        requests.push(request);
+        return {
+          status: 10,
+          stdout: validateResult('refused', 'no-token-for-identity'),
+          stderr: 'refused reason=no-token-for-identity',
+        };
+      },
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'credential-postcondition-failed',
+    });
+    expect(requests).toHaveLength(1);
+    expect(requests[0]?.program).toBe('mosaic');
+    expect(requests[0]?.args.slice(0, 3)).toEqual(['cred', 'validate', 'seat-a']);
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+    expect(requests.some((request) => request.args.includes('clone'))).toBe(false);
+  });
+
+  it('blocks before clone when the out-of-estate Git and API axes disagree', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-05 P7 refusal control gate');
+    const root = tempRoot();
+    const requests: CommandRequest[] = [];
+
+    const result = await provisioner.provisionBrain(baseInput(root), {
+      run: (request): CommandResult => {
+        requests.push(request);
+        if (request.program === 'mosaic' && request.args[2] === 'outside-seat') {
+          return {
+            status: 10,
+            stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+            stderr: 'refused reason=no-token-for-identity',
+          };
+        }
+        if (request.program === 'mosaic') {
+          return { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+        }
+        if (request.args.includes('ls-remote')) {
+          return { status: 0, stdout: 'refs are visible', stderr: '' };
+        }
+        return { status: 99, stdout: '', stderr: 'unexpected command' };
+      },
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'refusal-control-failed',
+    });
+    expect(requests.some((request) => request.args.includes('clone'))).toBe(false);
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+  });
+
+  it('blocks before skeleton publication when the existing checkout is dirty', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-06 dirty checkout publication gate');
+    const root = tempRoot();
+    const input = baseInput(root);
+    mkdirSync(join(input.root, '.git'), { recursive: true });
+    const requests: CommandRequest[] = [];
+
+    const result = await provisioner.provisionBrain(input, {
+      run: (request): CommandResult => {
+        requests.push(request);
+        if (request.program === 'mosaic') {
+          return request.args[2] === 'outside-seat'
+            ? {
+                status: 10,
+                stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+                stderr: 'refused reason=no-token-for-identity',
+              }
+            : { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+        }
+        const command = request.args.join(' ');
+        if (command.includes('ls-remote')) {
+          return {
+            status: 128,
+            stdout: '',
+            stderr: 'credential helper refused reason=no-token-for-identity',
+          };
+        }
+        if (command.includes('rev-parse --is-inside-work-tree')) {
+          return { status: 0, stdout: 'true\n', stderr: '' };
+        }
+        if (command.includes('remote get-url origin')) {
+          return {
+            status: 0,
+            stdout: 'https://git.example.invalid/durable-owner/mosaic-brain.git\n',
+            stderr: '',
+          };
+        }
+        if (command.includes('branch --show-current')) {
+          return { status: 0, stdout: 'main\n', stderr: '' };
+        }
+        if (command.includes('status --porcelain')) {
+          return { status: 0, stdout: '?? .gitignore\n', stderr: '' };
+        }
+        return { status: 99, stdout: '', stderr: 'unexpected publication command' };
+      },
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'brain-postcondition-failed',
+    });
+    expect(requests.some((request) => request.args.includes('commit'))).toBe(false);
+    expect(requests.some((request) => request.args.includes('push'))).toBe(false);
+  });
+
+  it('clones, seeds, resolves owner, migrates, pushes on each write, and archives source only after reachability', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-07 complete migration transaction');
+    const root = tempRoot();
+    const input = baseInput(root);
+    mkdirSync(join(input.sourceRoot, 'lanes', 'lane-a'), { recursive: true });
+    const source = join(input.sourceRoot, 'lanes', 'lane-a', 'finding.md');
+    writeFileSync(source, 'durable finding\n');
+    const requests: CommandRequest[] = [];
+    let commitOrdinal = 0;
+    let approvedPaths: string[] = [];
+    let privateAtClone = false;
+    const runner: CommandRunner = (request): CommandResult => {
+      requests.push(request);
+      if (request.program === 'mosaic') {
+        if (request.args[2] === 'outside-seat') {
+          return {
+            status: 10,
+            stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+            stderr: 'refused reason=no-token-for-identity',
+          };
+        }
+        return { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+      }
+      const command = request.args.join(' ');
+      if (command.includes('ls-remote')) {
+        return {
+          status: 128,
+          stdout: '',
+          stderr: 'credential helper refused reason=no-token-for-identity',
+        };
+      }
+      if (request.args[0] === 'clone') {
+        privateAtClone = existsSync(input.root) && (lstatSync(input.root).mode & 0o077) === 0;
+        mkdirSync(join(input.root, '.git'), { recursive: true });
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('read-tree')) {
+        approvedPaths = [];
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('hash-object')) {
+        return { status: 0, stdout: `${'f'.repeat(40)}\n`, stderr: '' };
+      }
+      if (command.includes('update-index')) {
+        const path = request.args.at(-1);
+        if (path !== undefined) approvedPaths.push(path);
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('rev-parse') && request.args.at(-1)?.includes(':')) {
+        return { status: 0, stdout: `${'f'.repeat(40)}\n`, stderr: '' };
+      }
+      if (command.includes('diff --cached --quiet')) {
+        return { status: 1, stdout: '', stderr: '' };
+      }
+      if (command.includes('diff-tree')) {
+        return { status: 0, stdout: `${approvedPaths.join('\0')}\0`, stderr: '' };
+      }
+      if (command.includes('show -s')) {
+        return {
+          status: 0,
+          stdout: 'seat-a\[email protected]\0seat-a\[email protected]\n',
+          stderr: '',
+        };
+      }
+      if (command.includes('rev-parse --is-inside-work-tree')) {
+        return { status: 0, stdout: 'true\n', stderr: '' };
+      }
+      if (command.includes('remote get-url origin')) {
+        return {
+          status: 0,
+          stdout: 'https://git.example.invalid/durable-owner/mosaic-brain.git\n',
+          stderr: '',
+        };
+      }
+      if (command.includes('branch --show-current')) {
+        return { status: 0, stdout: 'main\n', stderr: '' };
+      }
+      if (command.includes('status --porcelain')) {
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('rev-parse HEAD')) {
+        commitOrdinal += 1;
+        return {
+          status: 0,
+          stdout: `${commitOrdinal === 1 ? 'a' : 'c'.repeat(1)}`.repeat(40) + '\n',
+          stderr: '',
+        };
+      }
+      if (command.includes('rev-parse origin/main')) {
+        const value = commitOrdinal === 1 ? 'b' : 'd';
+        return { status: 0, stdout: `${value.repeat(40)}\n`, stderr: '' };
+      }
+      return { status: 0, stdout: '', stderr: '' };
+    };
+
+    const result = await provisioner.provisionBrain(input, {
+      run: runner,
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+      approveMigrationContent: (): boolean => true,
+    });
+
+    expect(result).toMatchObject({
+      status: 'provisioned',
+      reasonCode: 'brain-provisioned',
+      owner: { verdict: 'resolved', reasonCode: 'owner-verified' },
+      migration: { status: 'reported' },
+    });
+    expect(privateAtClone).toBe(true);
+    expect(existsSync(source)).toBe(true);
+    const imported = result.migration?.reported ?? [];
+    expect(imported).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: source, reason: expect.stringMatching(/retained/i) }),
+      ]),
+    );
+    const laneImports = join(input.root, 'lanes', 'lane-a', 'findings', 'imports');
+    const archiveImports = join(input.root, 'archives', 'imports', 'lane');
+    expect(existsSync(laneImports)).toBe(true);
+    expect(existsSync(archiveImports)).toBe(true);
+    expect(
+      requests.filter((request) => request.program === 'git' && request.args.includes('push')),
+    ).toHaveLength(2);
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+  });
+
+  it('keeps every source and reports the owner ambiguity when the public owner cannot be resolved', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-07 owner-blocked detection/reporting');
+    const root = tempRoot();
+    const input = baseInput(root);
+    mkdirSync(input.root, { recursive: true });
+    mkdirSync(join(input.root, '.git'), { recursive: true });
+    mkdirSync(join(input.sourceRoot, 'lanes', 'lane-a'), { recursive: true });
+    const source = join(input.sourceRoot, 'lanes', 'lane-a', 'finding.md');
+    writeFileSync(source, 'retain me\n');
+    let commitOrdinal = 0;
+
+    const result = await provisioner.provisionBrain(input, {
+      run: (request): CommandResult => {
+        if (request.program === 'mosaic') {
+          if (request.args[2] === 'outside-seat') {
+            return {
+              status: 10,
+              stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+              stderr: 'refused reason=no-token-for-identity',
+            };
+          }
+          return { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+        }
+        const command = request.args.join(' ');
+        if (command.includes('ls-remote')) {
+          return {
+            status: 128,
+            stdout: '',
+            stderr: 'credential helper refused reason=no-token-for-identity',
+          };
+        }
+        if (command.includes('rev-parse --is-inside-work-tree')) {
+          return { status: 0, stdout: 'true\n', stderr: '' };
+        }
+        if (command.includes('remote get-url origin')) {
+          return {
+            status: 0,
+            stdout: 'https://git.example.invalid/durable-owner/mosaic-brain.git\n',
+            stderr: '',
+          };
+        }
+        if (command.includes('branch --show-current')) {
+          return { status: 0, stdout: 'main\n', stderr: '' };
+        }
+        if (command.includes('status --porcelain')) {
+          return { status: 0, stdout: '', stderr: '' };
+        }
+        if (command.includes('rev-parse HEAD')) {
+          commitOrdinal += 1;
+          return { status: 0, stdout: `${'a'.repeat(40)}\n`, stderr: '' };
+        }
+        if (command.includes('rev-parse origin/main')) {
+          return { status: 0, stdout: `${'b'.repeat(40)}\n`, stderr: '' };
+        }
+        return { status: 0, stdout: '', stderr: '' };
+      },
+      fetch: ownerFetch(404),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'owner-not-resolvable',
+      owner: { verdict: 'not-measured', reasonCode: 'owner-not-resolvable' },
+      migration: { status: 'reported' },
+    });
+    expect(readFileSync(source, 'utf8')).toBe('retain me\n');
+    expect(result.migration?.reported).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: source, reason: expect.stringMatching(/owner/i) }),
+      ]),
+    );
+    expect(JSON.stringify(result)).not.toMatch(/owner-not-found|does-not-exist/);
+    expect(commitOrdinal).toBe(0);
+  });
+});

packages/mosaic/src/commands/brain-provision.ts

@@ -0,0 +1,271 @@
+import { existsSync } from 'node:fs';
+import { parseRequestedOwner, resolveProviderDurableOwner } from './brain-owner-resolver.js';
+import {
+  createBrainSkeleton,
+  deriveBrainTarget,
+  discoverBrainMigration,
+  ensureBrainRootPrivate,
+  migrateBrainState,
+  type MigrationResult,
+  type MigrationOwnerResolution,
+  type MigrationPublishEntry,
+} from './brain-store.js';
+import {
+  collectBrainDoctorReport,
+  collectBrainRefusalControl,
+  publishBrainPaths,
+  type CommandRequest,
+  type CommandResult,
+  type CommandRunner,
+} from './brain-store-runtime.js';
+import type { OwnerFetch } from './brain-owner-resolver.js';
+
+export interface ProvisionResult {
+  readonly status: 'provisioned' | 'blocked' | 'failed';
+  readonly reasonCode: string;
+  readonly findings: readonly {
+    readonly code: string;
+    readonly reasonCode: string | null;
+  }[];
+  readonly owner: Pick<MigrationOwnerResolution, 'verdict' | 'reasonCode'> | null;
+  readonly migration: Pick<MigrationResult, 'status' | 'reported'> | null;
+}
+
+function commandEnv(identity: string): Readonly<Record<string, string>> {
+  return { MOSAIC_GIT_IDENTITY: identity, GIT_TERMINAL_PROMPT: '0' };
+}
+
+function findingView(
+  findings: readonly { readonly code: string; readonly reasonCode: string | null }[],
+): readonly { readonly code: string; readonly reasonCode: string | null }[] {
+  return findings.map((finding): { readonly code: string; readonly reasonCode: string | null } => ({
+    code: finding.code,
+    reasonCode: finding.reasonCode,
+  }));
+}
+
+function blocked(
+  reasonCode: string,
+  findings: readonly { readonly code: string; readonly reasonCode: string | null }[],
+  owner: MigrationOwnerResolution | null = null,
+  migration: MigrationResult | null = null,
+): ProvisionResult {
+  return {
+    status: 'blocked',
+    reasonCode,
+    findings: findingView(findings),
+    owner: owner === null ? null : { verdict: owner.verdict, reasonCode: owner.reasonCode },
+    migration:
+      migration === null ? null : { status: migration.status, reported: migration.reported },
+  };
+}
+
+function failed(
+  reasonCode: string,
+  findings: readonly { readonly code: string; readonly reasonCode: string | null }[],
+  owner: MigrationOwnerResolution | null = null,
+  migration: MigrationResult | null = null,
+): ProvisionResult {
+  return {
+    ...blocked(reasonCode, findings, owner, migration),
+    status: 'failed',
+  };
+}
+
+export async function provisionBrain(
+  input: {
+    readonly estateRegistrySource: string;
+    readonly ownerPolicySource: string;
+    readonly targetGitUrl: string;
+    readonly requestedOwner: string;
+    readonly identity: string;
+    readonly refusalIdentity: string;
+    readonly root: string;
+    readonly sourceRoot: string;
+    readonly seat: string;
+    readonly lane: string;
+    readonly laneActive: boolean;
+  },
+  dependencies: {
+    readonly run: CommandRunner;
+    readonly fetch: OwnerFetch;
+    readonly absentControlName: () => string;
+    readonly approveMigrationContent?: (path: string, content: Uint8Array) => boolean;
+  },
+): Promise<ProvisionResult> {
+  const brainNamespace = parseRequestedOwner(input.requestedOwner);
+  if (brainNamespace === null) return blocked('owner-name-invalid', []);
+  const target = deriveBrainTarget(input.estateRegistrySource, input.targetGitUrl, brainNamespace);
+  if (existsSync(input.root)) {
+    try {
+      ensureBrainRootPrivate(input.root);
+    } catch {
+      return blocked('brain-root-permissions-unsafe', []);
+    }
+  }
+  const doctorInput = {
+    registrySource: input.estateRegistrySource,
+    targetGitUrl: input.targetGitUrl,
+    brainNamespace,
+    identity: input.identity,
+    root: input.root,
+  };
+  let report = collectBrainDoctorReport(doctorInput, dependencies.run);
+  if (report.access.outcome !== 'ok') {
+    return blocked('credential-postcondition-failed', report.findings);
+  }
+
+  const refusalControl = collectBrainRefusalControl(
+    {
+      registrySource: input.estateRegistrySource,
+      targetGitUrl: input.targetGitUrl,
+      brainNamespace,
+      refusalIdentity: input.refusalIdentity,
+    },
+    dependencies.run,
+  );
+  if (!refusalControl.observed) {
+    return blocked('refusal-control-failed', [
+      ...report.findings,
+      {
+        code: 'brain-refusal-control-indeterminate',
+        reasonCode: refusalControl.reasonCode,
+      },
+    ]);
+  }
+
+  const owner = await resolveProviderDurableOwner(
+    {
+      estateRegistrySource: input.estateRegistrySource,
+      ownerPolicySource: input.ownerPolicySource,
+      host: target.host,
+      requestedOwner: input.requestedOwner,
+    },
+    {
+      fetch: dependencies.fetch,
+      absentControlName: dependencies.absentControlName,
+    },
+  );
+  if (owner.verdict !== 'resolved') {
+    const plan = discoverBrainMigration(
+      {
+        sourceRoot: input.sourceRoot,
+        brainRoot: input.root,
+        seat: input.seat,
+        lane: input.lane,
+        laneActive: input.laneActive,
+      },
+      (): MigrationOwnerResolution => owner,
+    );
+    const migration = migrateBrainState(
+      plan,
+      (): never => {
+        throw new Error('blocked owner cannot publish');
+      },
+      input.root,
+    );
+    return blocked(owner.reasonCode, report.findings, owner, migration);
+  }
+
+  if (report.findings.some((finding): boolean => finding.code === 'brain-clone-missing')) {
+    try {
+      ensureBrainRootPrivate(input.root);
+    } catch {
+      return failed('brain-root-permissions-unsafe', report.findings);
+    }
+    const clone: CommandRequest = {
+      program: 'git',
+      args: ['clone', '--branch', 'main', '--single-branch', target.cloneUrl, input.root],
+      env: commandEnv(input.identity),
+    };
+    const cloneResult: CommandResult = dependencies.run(clone);
+    if (cloneResult.status !== 0) return failed('brain-clone-failed', report.findings);
+    try {
+      ensureBrainRootPrivate(input.root);
+    } catch {
+      return failed('brain-root-permissions-unsafe', report.findings);
+    }
+    report = collectBrainDoctorReport(doctorInput, dependencies.run);
+  }
+
+  const blockingCloneFindings = report.findings.filter(
+    (finding): boolean =>
+      finding.code === 'brain-clone-missing' ||
+      finding.code === 'brain-not-git-repository' ||
+      finding.code === 'brain-remote-mismatch' ||
+      finding.code === 'brain-branch-mismatch' ||
+      finding.code === 'brain-uncommitted-state' ||
+      finding.code === 'brain-git-state-indeterminate' ||
+      finding.code === 'brain-root-permissions-unsafe' ||
+      finding.code.startsWith('brain-write-access-'),
+  );
+  if (blockingCloneFindings.length > 0) {
+    return blocked('brain-postcondition-failed', report.findings);
+  }
+
+  let skeletonEntries: readonly MigrationPublishEntry[];
+  try {
+    const skeleton = createBrainSkeleton(input.root);
+    skeletonEntries = skeleton.publicationEntries;
+  } catch {
+    return failed('brain-skeleton-failed', report.findings);
+  }
+  if (skeletonEntries.length > 0) {
+    try {
+      const evidence = publishBrainPaths(
+        {
+          root: input.root,
+          identity: input.identity,
+          entries: skeletonEntries,
+          message: 'chore: seed durable brain layout',
+        },
+        dependencies.run,
+      );
+      if (!evidence.reachable) return failed('brain-skeleton-not-reachable', report.findings);
+    } catch {
+      return failed('brain-skeleton-publish-failed', report.findings);
+    }
+  }
+
+  const plan = discoverBrainMigration(
+    {
+      sourceRoot: input.sourceRoot,
+      brainRoot: input.root,
+      seat: input.seat,
+      lane: input.lane,
+      laneActive: input.laneActive,
+    },
+    (): MigrationOwnerResolution => owner,
+    dependencies.approveMigrationContent,
+  );
+  const migration = migrateBrainState(
+    plan,
+    (brainRoot: string, entries: readonly MigrationPublishEntry[]) =>
+      publishBrainPaths(
+        {
+          root: brainRoot,
+          identity: input.identity,
+          entries,
+          message: `migrate: archive ${input.lane} working memory`,
+        },
+        dependencies.run,
+      ),
+    input.root,
+  );
+
+  if (migration.status === 'failed') {
+    return failed('brain-migration-publish-failed', report.findings, owner, migration);
+  }
+
+  report = collectBrainDoctorReport(doctorInput, dependencies.run);
+  if (report.findings.length > 0) {
+    return blocked('brain-final-postcondition-failed', report.findings, owner, migration);
+  }
+  return {
+    status: 'provisioned',
+    reasonCode: 'brain-provisioned',
+    findings: [],
+    owner: { verdict: owner.verdict, reasonCode: owner.reasonCode },
+    migration: { status: migration.status, reported: migration.reported },
+  };
+}

packages/mosaic/src/commands/brain-secure-config.spec.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface SecureConfigModule {
+  readBrainConfigSecure(path: string, root: string): string;
+}
+
+const roots: string[] = [];
+
+async function loadSecureConfig(): Promise<SecureConfigModule> {
+  try {
+    return (await import('./brain-secure-config.js')) as SecureConfigModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`MB-REQ-06 secure brain config reader is absent (${detail})`);
+  }
+}
+
+function fixture(): { readonly root: string; readonly directory: string; readonly file: string } {
+  const outer = mkdtempSync(join(tmpdir(), 'mosaic-brain-secure-config-'));
+  roots.push(outer);
+  const root = join(outer, 'mosaic');
+  const directory = join(root, 'brain');
+  const file = join(directory, 'owners.json');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  writeFileSync(file, '{"version":1}\n', { mode: 0o600 });
+  return { root, directory, file };
+}
+
+afterEach((): void => {
+  vi.restoreAllMocks();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('security-critical brain configuration reads', (): void => {
+  it('reads a principal-owned non-writable regular file through the secure descriptor path', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+
+    expect(secure.readBrainConfigSecure(config.file, config.root)).toBe('{"version":1}\n');
+  });
+
+  it('rejects a managed root owned by a UID other than the running principal', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+    if (typeof process.getuid !== 'function') throw new Error('test requires POSIX getuid');
+    const processWithUid = process as typeof process & { getuid: () => number };
+    const actualUid = processWithUid.getuid();
+    vi.spyOn(processWithUid, 'getuid').mockReturnValue(actualUid + 1);
+
+    expect(() => secure.readBrainConfigSecure(config.file, config.root)).toThrow(
+      /config-ancestor-owner-unsafe/,
+    );
+  });
+
+  it('rejects a group/world-writable policy file', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+    chmodSync(config.file, 0o666);
+
+    expect(() => secure.readBrainConfigSecure(config.file, config.root)).toThrow(
+      /config-file-permissions-unsafe/,
+    );
+  });
+
+  it('rejects a group/world-writable managed ancestor', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+    chmodSync(config.directory, 0o777);
+
+    expect(() => secure.readBrainConfigSecure(config.file, config.root)).toThrow(
+      /config-ancestor-permissions-unsafe/,
+    );
+  });
+});

packages/mosaic/src/commands/brain-secure-config.ts

@@ -0,0 +1,52 @@
+import { lstatSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { assertCanonicalContainment, readRegularFileSecure } from '../fleet/secure-file.js';
+
+const MAX_CONFIG_BYTES = 256 * 1024;
+const GROUP_OR_OTHER_WRITE = 0o022;
+
+function currentUid(): number {
+  if (typeof process.getuid !== 'function') {
+    throw new Error('config-owner-check-unsupported');
+  }
+  return process.getuid();
+}
+
+function assertOwnedNonWritableDirectory(path: string, uid: number): void {
+  const status = lstatSync(path);
+  if (!status.isDirectory() || status.isSymbolicLink() || status.uid !== uid) {
+    throw new Error('config-ancestor-owner-unsafe');
+  }
+  if ((status.mode & GROUP_OR_OTHER_WRITE) !== 0) {
+    throw new Error('config-ancestor-permissions-unsafe');
+  }
+}
+
+export function readBrainConfigSecure(path: string, root: string): string {
+  const canonicalRoot = resolve(root);
+  const canonicalPath = resolve(path);
+  assertCanonicalContainment(canonicalRoot, canonicalPath);
+  const uid = currentUid();
+  assertOwnedNonWritableDirectory(canonicalRoot, uid);
+  let cursor = canonicalRoot;
+  for (const component of relative(canonicalRoot, dirname(canonicalPath))
+    .split(sep)
+    .filter(Boolean)) {
+    cursor = resolve(cursor, component);
+    assertOwnedNonWritableDirectory(cursor, uid);
+  }
+
+  const snapshot = readRegularFileSecure(canonicalPath, {
+    root: canonicalRoot,
+    maxBytes: MAX_CONFIG_BYTES,
+  });
+  if (snapshot.uid !== uid) throw new Error('config-file-owner-unsafe');
+  if ((snapshot.mode & GROUP_OR_OTHER_WRITE) !== 0) {
+    throw new Error('config-file-permissions-unsafe');
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(snapshot.content);
+  } catch {
+    throw new Error('config-file-not-utf8');
+  }
+}

packages/mosaic/src/commands/brain-store-runtime.ts

@@ -0,0 +1,569 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import {
+  assessCredentialResult,
+  brainRootIsPrivate,
+  deriveBrainTarget,
+  ensureBrainRootPrivate,
+  evaluateBrainDoctor,
+  planBrainDoctorFix,
+  type BrainDoctorFinding,
+  type BrainDoctorObservation,
+  type CredentialAssessment,
+} from './brain-store.js';
+
+const COMMIT = /^[0-9a-f]{40}$/;
+const GIT_OBJECT = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const MAX_PUBLISH_ENTRY_BYTES = 1024 * 1024;
+
+export interface CommandRequest {
+  readonly program: 'git' | 'mosaic';
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly env: Readonly<Record<string, string>>;
+  readonly stdin?: Uint8Array;
+}
+
+export interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export type CommandRunner = (request: CommandRequest) => CommandResult;
+
+export const systemCommandRunner: CommandRunner = (request: CommandRequest): CommandResult => {
+  const result = spawnSync(request.program, request.args, {
+    cwd: request.cwd,
+    env: { ...process.env, ...request.env },
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+    input: request.stdin,
+  });
+  return {
+    status: result.status ?? 127,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? result.error?.message ?? '',
+  };
+};
+
+export interface DoctorRuntimeReport {
+  readonly findings: readonly BrainDoctorFinding[];
+  readonly access: CredentialAssessment;
+  readonly refusalControl: {
+    readonly observed: boolean;
+    readonly reasonCode: string | null;
+  };
+}
+
+export interface BrainRefusalControlResult {
+  readonly observed: boolean;
+  readonly reasonCode: string | null;
+  readonly gitReasonCode: string;
+  readonly apiReasonCode: string;
+}
+
+export interface PublishEvidence {
+  readonly commit: string;
+  readonly remoteHead: string;
+  readonly reachable: boolean;
+}
+
+function commandEnv(identity: string): Readonly<Record<string, string>> {
+  return {
+    MOSAIC_GIT_IDENTITY: identity,
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}
+
+function integrationFailure(): CredentialAssessment {
+  return {
+    outcome: 'indeterminate',
+    exitCode: 30,
+    reasonCode: 'unexpected-provider-shape',
+    diagnostic: 'indeterminate: unexpected-provider-shape',
+  };
+}
+
+function runGit(run: CommandRunner, identity: string, args: readonly string[]): CommandResult {
+  return run({ program: 'git', args, env: commandEnv(identity) });
+}
+
+function runGitWithEnv(
+  run: CommandRunner,
+  identity: string,
+  args: readonly string[],
+  env: Readonly<Record<string, string>>,
+  stdin?: Uint8Array,
+): CommandResult {
+  return run({ program: 'git', args, env: { ...commandEnv(identity), ...env }, stdin });
+}
+
+export function collectBrainDoctorReport(
+  input: {
+    readonly registrySource: string;
+    readonly targetGitUrl: string;
+    readonly brainNamespace: string;
+    readonly identity: string;
+    readonly root: string;
+  },
+  run: CommandRunner,
+): DoctorRuntimeReport {
+  const target = deriveBrainTarget(input.registrySource, input.targetGitUrl, input.brainNamespace);
+  const validation = run({
+    program: 'mosaic',
+    args: [
+      'cred',
+      'validate',
+      input.identity,
+      '--estate',
+      target.estate,
+      '--host',
+      target.host,
+      '--repo',
+      target.repo,
+      '--require',
+      'write',
+      '--json',
+    ],
+    env: commandEnv(input.identity),
+  });
+  let access = assessCredentialResult(validation.stdout, {
+    identity: input.identity,
+    estate: target.estate,
+    host: target.host,
+    repo: target.repo,
+  });
+  if (validation.status !== access.exitCode) access = integrationFailure();
+
+  const rootExists = existsSync(input.root);
+  let gitRepository = false;
+  let remote: string | null = null;
+  let branch: string | null = null;
+  let worktreeState: BrainDoctorObservation['worktreeState'] = 'unmeasurable';
+  if (rootExists) {
+    const repository = runGit(run, input.identity, [
+      '-C',
+      input.root,
+      'rev-parse',
+      '--is-inside-work-tree',
+    ]);
+    gitRepository = repository.status === 0 && repository.stdout.trim() === 'true';
+    if (gitRepository) {
+      const remoteResult = runGit(run, input.identity, [
+        '-C',
+        input.root,
+        'remote',
+        'get-url',
+        'origin',
+      ]);
+      const branchResult = runGit(run, input.identity, [
+        '-C',
+        input.root,
+        'branch',
+        '--show-current',
+      ]);
+      const statusResult = runGit(run, input.identity, ['-C', input.root, 'status', '--porcelain']);
+      if (remoteResult.status === 0) remote = remoteResult.stdout.trim();
+      if (branchResult.status === 0) branch = branchResult.stdout.trim();
+      if (statusResult.status === 0) {
+        worktreeState = statusResult.stdout.trim().length > 0 ? 'dirty' : 'clean';
+      }
+    }
+  }
+
+  const observation: BrainDoctorObservation = {
+    rootExists,
+    rootPrivate: rootExists && brainRootIsPrivate(input.root),
+    gitRepository,
+    remote,
+    branch,
+    worktreeState,
+    access,
+  };
+  const refusalMarker = `refused reason=${access.reasonCode}`;
+  const refusalObserved =
+    validation.status === 10 &&
+    access.outcome === 'refused' &&
+    access.reasonCode === 'no-token-for-identity' &&
+    validation.stderr.includes(refusalMarker);
+  return {
+    findings: evaluateBrainDoctor(observation, target.cloneUrl),
+    access,
+    refusalControl: {
+      observed: refusalObserved,
+      reasonCode: refusalObserved ? access.reasonCode : null,
+    },
+  };
+}
+
+export function collectBrainRefusalControl(
+  input: {
+    readonly registrySource: string;
+    readonly targetGitUrl: string;
+    readonly brainNamespace: string;
+    readonly refusalIdentity: string;
+  },
+  run: CommandRunner,
+): BrainRefusalControlResult {
+  const target = deriveBrainTarget(input.registrySource, input.targetGitUrl, input.brainNamespace);
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(input.refusalIdentity)) {
+    return {
+      observed: false,
+      reasonCode: 'permission-evidence-disagrees',
+      gitReasonCode: 'invalid-control-identity',
+      apiReasonCode: 'invalid-control-identity',
+    };
+  }
+  const apiResult = run({
+    program: 'mosaic',
+    args: [
+      'cred',
+      'validate',
+      input.refusalIdentity,
+      '--estate',
+      target.estate,
+      '--host',
+      target.host,
+      '--repo',
+      target.repo,
+      '--require',
+      'write',
+      '--json',
+    ],
+    env: commandEnv(input.refusalIdentity),
+  });
+  let api = assessCredentialResult(apiResult.stdout, {
+    identity: input.refusalIdentity,
+    estate: target.estate,
+    host: target.host,
+    repo: target.repo,
+  });
+  if (apiResult.status !== api.exitCode) api = integrationFailure();
+
+  const gitResult = runGit(run, input.refusalIdentity, ['ls-remote', target.cloneUrl, 'HEAD']);
+  const marker = /(?:^|\s)reason=([a-z0-9-]+)(?:\s|$)/.exec(gitResult.stderr)?.[1];
+  const stableRefusals = new Set([
+    'identity-required',
+    'estate-required',
+    'estate-host-mismatch',
+    'cross-estate-resolution',
+    'no-token-for-identity',
+    'tea-login-missing',
+    'tea-login-host-mismatch',
+    'provider-identity-mismatch',
+    'credential-rejected',
+    'permission-denied',
+    'organization-membership-required',
+    'team-membership-required',
+  ]);
+  const gitReasonCode =
+    gitResult.status === 0
+      ? 'transport-accepted'
+      : marker !== undefined && stableRefusals.has(marker) && gitResult.stdout.length === 0
+        ? marker
+        : 'transport-indeterminate';
+  const observed =
+    api.outcome === 'refused' &&
+    gitReasonCode !== 'transport-accepted' &&
+    gitReasonCode !== 'transport-indeterminate' &&
+    gitReasonCode === api.reasonCode;
+  return {
+    observed,
+    reasonCode: observed ? api.reasonCode : 'permission-evidence-disagrees',
+    gitReasonCode,
+    apiReasonCode: api.reasonCode,
+  };
+}
+
+export function repairBrainDoctor(
+  input: {
+    readonly registrySource: string;
+    readonly targetGitUrl: string;
+    readonly brainNamespace: string;
+    readonly identity: string;
+    readonly root: string;
+  },
+  run: CommandRunner,
+): DoctorRuntimeReport {
+  const target = deriveBrainTarget(input.registrySource, input.targetGitUrl, input.brainNamespace);
+  let report = collectBrainDoctorReport(input, run);
+  const actions = planBrainDoctorFix({
+    findings: report.findings,
+    target,
+    identity: input.identity,
+    root: input.root,
+  });
+  for (const action of actions) {
+    if (action.program === 'mosaic') {
+      run({ program: 'mosaic', args: action.args, env: commandEnv(input.identity) });
+      report = collectBrainDoctorReport(input, run);
+      if (report.access.outcome !== 'ok') return report;
+      continue;
+    }
+    if (action.findingCode === 'brain-clone-missing') {
+      try {
+        ensureBrainRootPrivate(input.root);
+      } catch {
+        return collectBrainDoctorReport(input, run);
+      }
+    }
+    const result = runGit(run, input.identity, action.args);
+    if (result.status !== 0) return collectBrainDoctorReport(input, run);
+  }
+  return collectBrainDoctorReport(input, run);
+}
+
+function requireSuccess(result: CommandResult, operation: string): void {
+  if (result.status !== 0) throw new Error(`${operation}-failed`);
+}
+
+function containedRelative(root: string, path: string): string {
+  if (isAbsolute(path) === false) throw new Error('brain-publish-path-must-be-absolute');
+  const absoluteRoot = resolve(root);
+  const absolutePath = resolve(path);
+  if (absolutePath === absoluteRoot || !absolutePath.startsWith(`${absoluteRoot}${sep}`)) {
+    throw new Error('brain-publish-path-escaped-root');
+  }
+  return relative(absoluteRoot, absolutePath).split(sep).join('/');
+}
+
+export function publishBrainPaths(
+  input: {
+    readonly root: string;
+    readonly identity: string;
+    readonly entries: readonly {
+      readonly path: string;
+      readonly content: Uint8Array;
+    }[];
+    readonly message: string;
+  },
+  run: CommandRunner,
+): PublishEvidence {
+  if (input.entries.length === 0) throw new Error('brain-publish-paths-empty');
+  if (input.message.trim().length === 0) throw new Error('brain-publish-message-empty');
+  const entries = input.entries.map((entry) => {
+    if (entry.content.byteLength > MAX_PUBLISH_ENTRY_BYTES) {
+      throw new Error('brain-publish-entry-too-large');
+    }
+    return {
+      path: containedRelative(input.root, entry.path),
+      content: Uint8Array.from(entry.content),
+    };
+  });
+  const paths = entries.map((entry): string => entry.path);
+  if (new Set(paths).size !== paths.length) throw new Error('brain-publish-path-duplicate');
+
+  const readHead = (): string => {
+    const result = runGit(run, input.identity, ['-C', input.root, 'rev-parse', 'HEAD']);
+    requireSuccess(result, 'brain-git-read-commit');
+    const value = result.stdout.trim();
+    if (!COMMIT.test(value)) throw new Error('brain-git-commit-shape-invalid');
+    return value;
+  };
+  const verifyCommitIdentity = (commit: string): void => {
+    const result = runGit(run, input.identity, [
+      '-C',
+      input.root,
+      'show',
+      '-s',
+      '--format=%an%x00%ae%x00%cn%x00%ce',
+      commit,
+    ]);
+    requireSuccess(result, 'brain-git-read-commit-identity');
+    const expectedEmail = `${input.identity}@fleet.mosaicstack.dev`;
+    const [author, authorEmail, committer, committerEmail] = result.stdout.trimEnd().split('\0');
+    if (
+      author !== input.identity ||
+      authorEmail !== expectedEmail ||
+      committer !== input.identity ||
+      committerEmail !== expectedEmail
+    ) {
+      throw new Error('brain-git-commit-identity-mismatch');
+    }
+  };
+  const expectedObjects = new Map<string, string>();
+  const verifyCommitObjects = (commit: string): void => {
+    for (const [path, expected] of expectedObjects) {
+      const result = runGit(run, input.identity, [
+        '-C',
+        input.root,
+        'rev-parse',
+        `${commit}:${path}`,
+      ]);
+      requireSuccess(result, 'brain-git-read-commit-object');
+      if (result.stdout.trim() !== expected) throw new Error('brain-git-commit-content-mismatch');
+    }
+  };
+  const reconcileRealIndex = (): void => {
+    for (const [path, objectId] of expectedObjects) {
+      requireSuccess(
+        runGit(run, input.identity, [
+          '-C',
+          input.root,
+          'update-index',
+          '--add',
+          '--cacheinfo',
+          '100644',
+          objectId,
+          path,
+        ]),
+        'brain-git-reconcile-checkout-index',
+      );
+    }
+  };
+  const verifyCommitPaths = (commit: string): void => {
+    const changed = runGit(run, input.identity, [
+      '-C',
+      input.root,
+      'diff-tree',
+      '--root',
+      '--no-commit-id',
+      '--name-only',
+      '-r',
+      '-z',
+      commit,
+    ]);
+    requireSuccess(changed, 'brain-git-read-commit-paths');
+    const names = changed.stdout.split('\0').filter(Boolean);
+    const approved = new Set(paths);
+    if (names.length === 0 || names.some((name: string): boolean => !approved.has(name))) {
+      throw new Error('brain-git-commit-paths-unapproved');
+    }
+  };
+
+  const base = readHead();
+  const indexRoot = mkdtempSync(join(tmpdir(), 'mosaic-brain-index-'));
+  const isolatedEnv = { GIT_INDEX_FILE: join(indexRoot, 'index') };
+  let commit = base;
+  let createdCommit = false;
+  try {
+    requireSuccess(
+      runGitWithEnv(run, input.identity, ['-C', input.root, 'read-tree', base], isolatedEnv),
+      'brain-git-isolated-index-init',
+    );
+    for (const entry of entries) {
+      const object = runGitWithEnv(
+        run,
+        input.identity,
+        ['-C', input.root, 'hash-object', '-w', '--stdin'],
+        isolatedEnv,
+        entry.content,
+      );
+      requireSuccess(object, 'brain-git-write-approved-object');
+      const objectId = object.stdout.trim();
+      if (!GIT_OBJECT.test(objectId)) throw new Error('brain-git-object-shape-invalid');
+      expectedObjects.set(entry.path, objectId);
+      requireSuccess(
+        runGitWithEnv(
+          run,
+          input.identity,
+          [
+            '-C',
+            input.root,
+            'update-index',
+            '--add',
+            '--cacheinfo',
+            '100644',
+            objectId,
+            entry.path,
+          ],
+          isolatedEnv,
+        ),
+        'brain-git-stage-approved-object',
+      );
+    }
+    const difference = runGitWithEnv(
+      run,
+      input.identity,
+      ['-C', input.root, 'diff', '--cached', '--quiet', '--exit-code', base, '--', ...paths],
+      isolatedEnv,
+    );
+    if (difference.status === 1) {
+      requireSuccess(
+        runGitWithEnv(
+          run,
+          input.identity,
+          [
+            '-C',
+            input.root,
+            '-c',
+            `user.name=${input.identity}`,
+            '-c',
+            `user.email=${input.identity}@fleet.mosaicstack.dev`,
+            'commit',
+            '-m',
+            input.message,
+          ],
+          isolatedEnv,
+        ),
+        'brain-git-commit',
+      );
+      commit = readHead();
+      verifyCommitPaths(commit);
+      verifyCommitObjects(commit);
+      verifyCommitIdentity(commit);
+      reconcileRealIndex();
+      createdCommit = true;
+    } else if (difference.status !== 0) {
+      throw new Error('brain-git-isolated-diff-failed');
+    }
+  } finally {
+    rmSync(indexRoot, { recursive: true, force: true });
+  }
+
+  let pushed = !createdCommit;
+  for (let attempt = 0; createdCommit && attempt < 3; attempt += 1) {
+    const push = runGit(run, input.identity, ['-C', input.root, 'push', 'origin', 'HEAD:main']);
+    if (push.status === 0) {
+      pushed = true;
+      break;
+    }
+    const concurrentUpdate = /non-fast-forward|fetch first|\[rejected\]/i.test(push.stderr);
+    if (!concurrentUpdate || attempt === 2) throw new Error('brain-git-push-failed');
+    requireSuccess(
+      runGit(run, input.identity, ['-C', input.root, 'fetch', 'origin', 'main']),
+      'brain-git-fetch-concurrent',
+    );
+    requireSuccess(
+      runGit(run, input.identity, [
+        '-C',
+        input.root,
+        '-c',
+        `user.name=${input.identity}`,
+        '-c',
+        `user.email=${input.identity}@fleet.mosaicstack.dev`,
+        'rebase',
+        'origin/main',
+      ]),
+      'brain-git-rebase-concurrent',
+    );
+    commit = readHead();
+    verifyCommitPaths(commit);
+    verifyCommitObjects(commit);
+    verifyCommitIdentity(commit);
+  }
+  if (!pushed) throw new Error('brain-git-push-failed');
+  requireSuccess(
+    runGit(run, input.identity, ['-C', input.root, 'fetch', 'origin', 'main']),
+    'brain-git-fetch-readback',
+  );
+  const reachableResult = runGit(run, input.identity, [
+    '-C',
+    input.root,
+    'merge-base',
+    '--is-ancestor',
+    commit,
+    'origin/main',
+  ]);
+  if (reachableResult.status !== 0 && reachableResult.status !== 1) {
+    throw new Error('brain-git-reachability-check-failed');
+  }
+  const remoteResult = runGit(run, input.identity, ['-C', input.root, 'rev-parse', 'origin/main']);
+  requireSuccess(remoteResult, 'brain-git-read-remote-head');
+  const remoteHead = remoteResult.stdout.trim();
+  if (!COMMIT.test(remoteHead)) throw new Error('brain-git-remote-head-shape-invalid');
+  return { commit, remoteHead, reachable: reachableResult.status === 0 };
+}

packages/mosaic/src/commands/launch.ts

@@ -14,11 +14,9 @@ import {
   readdirSync,
   realpathSync,
   rmSync,
-  appendFileSync,
 } from 'node:fs';
-import { createHash, randomBytes } from 'node:crypto';
 import { createRequire } from 'node:module';
-import { homedir, hostname } from 'node:os';
+import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import type { Command } from 'commander';
 import {
@@ -31,6 +29,11 @@ import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
 import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
 import { runLeaseEnforcementDoctorCheck } from './lease-doctor-check.js';
+import {
+  defaultInstalledBrainDoctorOptions,
+  runInstalledBrainDoctorCheck,
+} from './brain-doctor-check.js';
+import { systemCommandRunner } from './brain-store-runtime.js';
 
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 const MAX_INSTALLED_TOOLS_BYTES = 256 * 1024;
@@ -44,163 +47,6 @@ const RUNTIME_LABELS: Record<RuntimeName, string> = {
   pi: 'Pi',
 };
 
-// ─── Harness home isolation ──────────────────────────────────────────────────
-// Mosaic-launched runtimes read config from a dedicated home under the mosaic
-// tree — never the operator's base install. A bare `claude` / `pi` therefore
-// keeps its own config AND its own auth, and stays a working break-glass no
-// matter what mosaic does to its own tree.
-//
-// These paths are manifest-UNKNOWN, which resolves to operator ownership
-// (framework-manifest.txt rule 3, #791), so a keep-mode `mosaic update` can
-// neither overwrite nor prune them. Overwrite-mode install still would.
-//
-// opencode has no dedicated config-dir variable and follows XDG, so isolating it
-// sets XDG_CONFIG_HOME for that process tree. That is blunter than the other
-// three: it also relocates XDG lookups for anything opencode spawns.
-const HARNESS_HOME_ENV: Record<RuntimeName, string> = {
-  claude: 'CLAUDE_CONFIG_DIR',
-  pi: 'PI_CODING_AGENT_DIR',
-  codex: 'CODEX_HOME',
-  opencode: 'XDG_CONFIG_HOME',
-};
-
-/** Dedicated mosaic-owned home for a runtime: ~/.config/mosaic/.<runtime> */
-function harnessHome(runtime: RuntimeName): string {
-  return join(MOSAIC_HOME, `.${runtime}`);
-}
-
-/**
- * Env overlay pointing a runtime at its mosaic-owned home. The directory is
- * created on demand so a first launch does not fail on a missing path.
- */
-function harnessEnv(runtime: RuntimeName): Record<string, string> {
-  const key = HARNESS_HOME_ENV[runtime];
-  if (!key) return {};
-  const home = harnessHome(runtime);
-  mkdirSync(home, { recursive: true });
-  return { [key]: home };
-}
-
-// ─── Launch record (immutable provenance) ────────────────────────────────────
-// MANDATORY and MECHANICAL: every launch appends one record of what the agent
-// actually launched with, written before exec. No model involvement, no opt-out.
-//
-// WHY LAUNCH-TIME AND NOT INSPECT-LATER: pi rewrites its own argv to a bare
-// `pi`, so /proc/<pid>/cmdline DESTROYS the launch evidence. That has already
-// produced a confident wrong diagnosis ("this agent bypassed the launcher"),
-// disproved only by the parent process's argv and only because the parent had
-// not yet exited. A record written before exec is the only place this survives.
-//
-// Lands in fleet/run/sessions/ — the #797 Runtime Session Ledger path, already
-// operator-classified in framework-manifest.txt and already covered by
-// test-upgrade-manifest-guard.sh, so an upgrade can neither overwrite nor prune
-// it.
-//
-// CORRELATION is by an explicit MOSAIC_LAUNCH_ID, never by pid: execRuntime()
-// uses spawnSync, so the runtime is a CHILD with a different pid.
-// launch-runtime.py appends the matching `lease.register` event.
-//
-// NEVER records a credential value: env is captured as PRESENT NAMES ONLY, and
-// oversized argv values (the composed system prompt) become a digest + length.
-const LAUNCH_LEDGER_DIR = join(MOSAIC_HOME, 'fleet', 'run', 'sessions');
-
-const CLI_VERSION: string | null = (() => {
-  try {
-    // Resolved RELATIVELY: the package `exports` map does not expose
-    // package.json, so '@mosaicstack/mosaic/package.json' throws
-    // ERR_PACKAGE_PATH_NOT_EXPORTED. Same relative depth from src/ and dist/.
-    return (createRequire(import.meta.url)('../../package.json') as { version: string }).version;
-  } catch {
-    return null;
-  }
-})();
-
-interface NormativeFragmentDigest {
-  source_id: string;
-  sha256: string | null;
-  bytes: number | null;
-  missing?: boolean;
-}
-
-function sha256Of(value: string | Buffer): string {
-  return createHash('sha256').update(value).digest('hex');
-}
-
-/**
- * Hash the normative sources injected into the agent. This is "what the agent
- * IS" — and it is the same fragment set the lease broker hashes for promotion,
- * so an unexpected digest here is a mechanically detectable red flag rather than
- * a matter of judgement.
- */
-function normativeFragmentDigests(runtime: RuntimeName): NormativeFragmentDigest[] {
-  const candidates: Array<[string, string]> = [
-    ['CONSTITUTION.md', join(MOSAIC_HOME, 'CONSTITUTION.md')],
-    ['AGENTS.md', join(MOSAIC_HOME, 'AGENTS.md')],
-    ['SOUL.md', join(MOSAIC_HOME, 'SOUL.md')],
-    ['USER.md', join(MOSAIC_HOME, 'USER.md')],
-    ['STANDARDS.md', join(MOSAIC_HOME, 'STANDARDS.md')],
-    ['TOOLS.md', join(MOSAIC_HOME, 'TOOLS.md')],
-    [`runtime/${runtime}/RUNTIME.md`, join(MOSAIC_HOME, 'runtime', runtime, 'RUNTIME.md')],
-  ];
-  return candidates.map(([sourceId, path]) => {
-    try {
-      const bytes = readFileSync(path);
-      return { source_id: sourceId, sha256: sha256Of(bytes), bytes: bytes.length };
-    } catch {
-      return { source_id: sourceId, sha256: null, bytes: null, missing: true };
-    }
-  });
-}
-
-/** argv with oversized values replaced by a digest, so the record stays small
- * and never inlines injected content verbatim. */
-function redactArgv(argv: string[]): string[] {
-  return argv.map((a) =>
-    typeof a === 'string' && a.length > 256
-      ? `<redacted sha256:${sha256Of(a).slice(0, 16)} bytes:${a.length}>`
-      : a,
-  );
-}
-
-function recordLaunch(runtime: RuntimeName, cliArgs: string[], yolo: boolean): void {
-  try {
-    mkdirSync(LAUNCH_LEDGER_DIR, { recursive: true, mode: 0o700 });
-    // Correlation id for the lease.register half. Set into process.env so it
-    // propagates through every `...process.env` / `...baseEnv` spread below.
-    const launchId = `${Date.now().toString(36)}-${randomBytes(6).toString('hex')}`;
-    process.env['MOSAIC_LAUNCH_ID'] = launchId;
-    const record = {
-      seq: Date.now(),
-      kind: 'session.launch',
-      launch_id: launchId,
-      ts: new Date().toISOString(),
-      host: hostname(),
-      pid: process.pid,
-      runtime,
-      mode: yolo ? 'yolo' : 'normal',
-      cwd: process.cwd(),
-      cli_version: CLI_VERSION,
-      config_home: harnessHome(runtime),
-      config_home_isolated: true,
-      config_home_env: HARNESS_HOME_ENV[runtime] ?? null,
-      argv: redactArgv(cliArgs),
-      normative_fragments: normativeFragmentDigests(runtime),
-      // names only — values are never recorded
-      mosaic_env_present: Object.keys(process.env)
-        .filter((k) => k.startsWith('MOSAIC_'))
-        .sort(),
-    };
-    appendFileSync(join(LAUNCH_LEDGER_DIR, 'events.ndjson'), `${JSON.stringify(record)}\n`, {
-      mode: 0o600,
-    });
-  } catch (err) {
-    // Never block a launch on bookkeeping — but never fail silently either.
-    console.error(
-      `[mosaic] WARNING: launch record not written: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-}
-
 // ─── Pre-flight checks ──────────────────────────────────────────────────────
 
 function checkMosaicHome(): void {
@@ -264,11 +110,11 @@ interface SettingsAudit {
 
 function auditClaudeSettings(): SettingsAudit {
   const warnings: string[] = [];
-  const settingsPath = join(harnessHome('claude'), 'settings.json');
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
   const settings = readJson(settingsPath);
 
   if (!settings) {
-    warnings.push(`${settingsPath} not found — hooks and plugins will be missing`);
+    warnings.push('~/.claude/settings.json not found — hooks and plugins will be missing');
     return { warnings };
   }
 
@@ -720,9 +566,7 @@ function skillRealPath(dir: string): string {
 /** Skill roots Pi auto-discovers natively (no `--skill` needed): its global
  * skills dir and the project-local one relative to the launch cwd. */
 function piNativeSkillRoots(cwd: string = process.cwd()): string[] {
-  // PI_CODING_AGENT_DIR replaces ~/.pi/agent (not ~/.pi), so skills live at
-  // <home>/skills — there is no extra 'agent' segment under the isolated home.
-  return [join(harnessHome('pi'), 'skills'), join(cwd, '.pi', 'skills')];
+  return [join(homedir(), '.pi', 'agent', 'skills'), join(cwd, '.pi', 'skills')];
 }
 
 /** Enumerate skill dirs under a set of roots, deduped by real path. A directory
@@ -925,13 +769,12 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
         cliArgs.push(...args);
       }
       console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
-      recordLaunch('claude', cliArgs, yolo);
       execLeaseGatedRuntime('claude', cliArgs, process.env, yolo);
       break;
     }
 
     case 'codex': {
-      ensureRuntimeConfig('codex', join(harnessHome('codex'), 'instructions.md'));
+      ensureRuntimeConfig('codex', join(homedir(), '.codex', 'instructions.md'));
       const cliArgs = yolo ? ['--dangerously-bypass-approvals-and-sandbox'] : [];
       if (hasMissionNoArgs) {
         cliArgs.push(missionPrompt);
@@ -939,17 +782,14 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
         cliArgs.push(...args);
       }
       console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
-      recordLaunch('codex', cliArgs, yolo);
-      execRuntime('codex', cliArgs, { ...process.env, ...harnessEnv('codex') });
+      execRuntime('codex', cliArgs);
       break;
     }
 
     case 'opencode': {
-      // opencode follows XDG, so its config resolves to $XDG_CONFIG_HOME/opencode.
-      ensureRuntimeConfig('opencode', join(harnessHome('opencode'), 'opencode', 'AGENTS.md'));
+      ensureRuntimeConfig('opencode', join(homedir(), '.config', 'opencode', 'AGENTS.md'));
       console.log(`[mosaic] Launching ${label}${modeStr}...`);
-      recordLaunch('opencode', args, yolo);
-      execRuntime('opencode', args, { ...process.env, ...harnessEnv('opencode') });
+      execRuntime('opencode', args);
       break;
     }
 
@@ -964,7 +804,6 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
         cliArgs.push(...args);
       }
       console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
-      recordLaunch('pi', cliArgs, yolo);
       execLeaseGatedRuntime('pi', cliArgs);
       break;
     }
@@ -1001,7 +840,6 @@ function execLeaseGatedRuntime(
     [launcher, ...dangerousArgs, '--runtime', runtime, '--', runtime, ...args],
     {
       ...baseEnv,
-      ...harnessEnv(runtime),
       MOSAIC_LEASE_BROKER_SOCKET: defaultLeaseBrokerSocket(baseEnv),
       MOSAIC_RUNTIME_GENERATION: baseEnv['MOSAIC_RUNTIME_GENERATION'] ?? '1',
     },
@@ -1424,8 +1262,11 @@ export function registerLaunchCommands(program: Command): void {
       });
   }
 
-  // `doctor` — the framework drift audit (bash script) PLUS the #869
-  // Point-1 C5 lease-enforcement activation check (TS, reusing C1's
+  // `doctor` — the framework drift audit (bash script), the #869
+  // Point-1 C5 lease-enforcement activation check, and the #1051 per-estate
+  // durable brain check. Both TS checks run before the bash audit and can
+  // force a non-zero result for hard/indeterminate failures.
+  // The lease check reuses C1's
   // `leaseEnforcementActivatable()` and C3's `checkBrokerSupervisorHealth()`).
   // Kept out of the generic `directCommands` loop above because this check
   // must run and report BEFORE the bash script's own exit, and must be able
@@ -1434,14 +1275,29 @@ export function registerLaunchCommands(program: Command): void {
   // undiagnosed (see lease-doctor-check.ts docstring).
   program
     .command('doctor')
-    .description('Health audit — detect drift, missing files, and #869 lease-activation gaps')
+    .description('Health audit — detect drift, lease gaps, and per-estate brain defects')
     .allowUnknownOption(true)
     .allowExcessArguments(true)
     .action(async (_opts: unknown, cmd: Command) => {
       checkMosaicHome();
       const leaseCheck = await runLeaseEnforcementDoctorCheck();
       const leaseCheckFailed = printLeaseDoctorCheck(leaseCheck);
-      runDoctorScriptAndExit(fwScript('mosaic-doctor'), cmd.args, leaseCheckFailed);
+      const fix = cmd.args.includes('--fix');
+      const brainCheck = runInstalledBrainDoctorCheck(
+        defaultInstalledBrainDoctorOptions(fix),
+        systemCommandRunner,
+      );
+      for (const line of brainCheck.lines) {
+        (brainCheck.status === 'ok' ? console.log : console.error)(line);
+      }
+      const brainCheckFailed =
+        brainCheck.status === 'error' ||
+        (brainCheck.status === 'warn' && cmd.args.includes('--fail-on-warn'));
+      runDoctorScriptAndExit(
+        fwScript('mosaic-doctor'),
+        cmd.args,
+        leaseCheckFailed || brainCheckFailed,
+      );
     });
 }
 

packages/mosaic/src/commands/promote.spec.ts

@@ -1,298 +0,0 @@
-import { Command } from 'commander';
-import { describe, expect, it, vi } from 'vitest';
-import type { FleetRoster } from './fleet.js';
-import { TmuxPromotionTransport } from '../fleet/promotion-transport.js';
-import {
-  promoteSeat,
-  registerPromoteCommand,
-  type PromotionBreadcrumbStore,
-  type PromotionResult,
-  type PromotionTransport,
-} from './promote.js';
-
-const attemptId = 'a'.repeat(64);
-const target = {
-  bundle: 'local',
-  seat: 'claude-seat',
-  sessionId: 'b'.repeat(64),
-};
-
-function transport(): PromotionTransport {
-  return {
-    resolve: vi.fn(async () => target),
-    sendPromotion: vi.fn(async () => {}),
-  };
-}
-
-describe('mosaic promote', () => {
-  it('accepts only a fresh result correlated to this attempt', async () => {
-    const promotionTransport = transport();
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn().mockResolvedValueOnce(null).mockResolvedValue(attemptId),
-      readResult: vi
-        .fn()
-        .mockResolvedValueOnce({
-          attempt_id: 'c'.repeat(64),
-          expires_at_wallclock: 4_600,
-          reason: null,
-          session_id: target.sessionId,
-          ts: 1_001,
-          verified: true,
-        })
-        .mockResolvedValueOnce({
-          attempt_id: attemptId,
-          expires_at_wallclock: 4_600,
-          reason: null,
-          session_id: target.sessionId,
-          ts: 1_001,
-          verified: true,
-        }),
-    };
-
-    const result = await promoteSeat('claude-seat', {
-      clock: () => 1_000,
-      sleep: async () => {},
-      store,
-      timeoutMs: 1,
-      transport: promotionTransport,
-    });
-
-    expect(result).toEqual({
-      bundle: 'local',
-      expiresAtWallclock: 4_600,
-      reason: null,
-      seat: 'claude-seat',
-      sessionId: 'b'.repeat(64),
-      status: 'VERIFIED',
-    });
-    expect(promotionTransport.sendPromotion).toHaveBeenCalledWith(target);
-    expect(store.readResult).toHaveBeenCalledTimes(2);
-  });
-
-  it('accepts a fresh result for this session when completion consumed the pending nonce', async () => {
-    const promotionTransport = transport();
-    let now = 1_000;
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn(async () => null),
-      readResult: vi.fn(async () => ({
-        attempt_id: attemptId,
-        expires_at_wallclock: 4_600,
-        reason: null,
-        session_id: target.sessionId,
-        ts: 1_001,
-        verified: true,
-      })),
-    };
-
-    const result = await promoteSeat('claude-seat', {
-      clock: () => now,
-      sleep: async () => {
-        now += 10;
-      },
-      store,
-      timeoutMs: 10,
-      transport: promotionTransport,
-    });
-
-    expect(result.status).toBe('VERIFIED');
-  });
-
-  it('returns UNVERIFIED within the command bound when a tmux runner wedges', async () => {
-    vi.useFakeTimers();
-    const roster: FleetRoster = {
-      agents: [{ className: 'worker', name: 'claude-seat', runtime: 'claude' }],
-      defaults: { workingDirectory: '~/src' },
-      runtimes: {},
-      tmux: { holderSession: '_holder', socketName: 'mosaic-fleet' },
-      transport: 'tmux',
-      version: 1,
-    };
-    const promotionTransport = new TmuxPromotionTransport({
-      mosaicHome: '/mosaic',
-      rosterLoader: async () => roster,
-      runner: async () => new Promise(() => {}),
-    });
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn(async () => null),
-      readResult: vi.fn(async () => null),
-    };
-
-    try {
-      let observedResult: PromotionResult | undefined;
-      void promoteSeat('claude-seat', {
-        store,
-        transport: promotionTransport,
-      }).then((result) => {
-        observedResult = result;
-      });
-      await vi.advanceTimersByTimeAsync(5_000);
-
-      expect(observedResult).toMatchObject({
-        reason: 'RESOLVE_FAILED: Promotion transport command timed out after 5000ms.',
-        seat: 'claude-seat',
-        status: 'UNVERIFIED',
-      });
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it('prints VERIFIED with the resolved seat, session, bundle, and wall-clock expiry', async () => {
-    const promotionTransport = transport();
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn().mockResolvedValueOnce(null).mockResolvedValue(attemptId),
-      readResult: vi.fn(async () => ({
-        attempt_id: attemptId,
-        expires_at_wallclock: 4_600,
-        reason: null,
-        session_id: target.sessionId,
-        ts: Number.MAX_SAFE_INTEGER,
-        verified: true,
-      })),
-    };
-    const output = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const program = new Command().exitOverride();
-    registerPromoteCommand(program, {
-      mintAuthorization: async () => {},
-      store,
-      transport: promotionTransport,
-    });
-
-    try {
-      await program.parseAsync(['node', 'mosaic', 'promote', 'claude-seat']);
-      expect(output).toHaveBeenCalledWith(
-        `VERIFIED seat=claude-seat session=${target.sessionId} bundle=local expiry=1970-01-01T01:16:40.000Z`,
-      );
-      expect(process.exitCode).not.toBe(1);
-    } finally {
-      output.mockRestore();
-      process.exitCode = undefined;
-    }
-  });
-
-  it('prints UNVERIFIED and exits 1 when delivery fails', async () => {
-    const promotionTransport: PromotionTransport = {
-      resolve: vi.fn(async () => target),
-      sendPromotion: vi.fn(async () => {
-        throw new Error('tmux unavailable');
-      }),
-    };
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn(async () => null),
-      readResult: vi.fn(async () => null),
-    };
-    const output = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const program = new Command().exitOverride();
-    registerPromoteCommand(program, {
-      mintAuthorization: async () => {},
-      store,
-      transport: promotionTransport,
-    });
-
-    try {
-      process.exitCode = undefined;
-      await program.parseAsync(['node', 'mosaic', 'promote', 'claude-seat']);
-      expect(output).toHaveBeenCalledWith(
-        `UNVERIFIED seat=claude-seat session=${target.sessionId} bundle=local expiry=none reason=DELIVERY_FAILED: tmux unavailable`,
-      );
-      expect(process.exitCode).toBe(1);
-    } finally {
-      output.mockRestore();
-      process.exitCode = undefined;
-    }
-  });
-
-  it('rejects a stale result even when its nonce matches', async () => {
-    const promotionTransport = transport();
-    let now = 1_000;
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn().mockResolvedValueOnce(null).mockResolvedValue(attemptId),
-      readResult: vi.fn(async () => ({
-        attempt_id: attemptId,
-        expires_at_wallclock: 4_600,
-        reason: null,
-        session_id: target.sessionId,
-        ts: 1_000,
-        verified: true,
-      })),
-    };
-
-    const result = await promoteSeat('claude-seat', {
-      clock: () => now,
-      sleep: async () => {
-        now += 10;
-      },
-      store,
-      timeoutMs: 10,
-      transport: promotionTransport,
-    });
-
-    expect(result).toEqual({
-      bundle: 'local',
-      expiresAtWallclock: null,
-      reason: 'PROMOTION_TIMEOUT',
-      seat: 'claude-seat',
-      sessionId: 'b'.repeat(64),
-      status: 'UNVERIFIED',
-    });
-  });
-
-  it('does not accept a result for a pending attempt that existed before send', async () => {
-    const promotionTransport = transport();
-    let now = 1_000;
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn(async () => attemptId),
-      readResult: vi.fn(async () => ({
-        attempt_id: attemptId,
-        expires_at_wallclock: 4_600,
-        reason: null,
-        session_id: target.sessionId,
-        ts: 1_001,
-        verified: true,
-      })),
-    };
-
-    const result = await promoteSeat('claude-seat', {
-      clock: () => now,
-      sleep: async () => {
-        now += 10;
-      },
-      store,
-      timeoutMs: 10,
-      transport: promotionTransport,
-    });
-
-    expect(result.status).toBe('UNVERIFIED');
-    expect(store.readResult).not.toHaveBeenCalled();
-  });
-
-  it('returns UNVERIFIED after a bounded timeout without reading stdin', async () => {
-    const promotionTransport = transport();
-    let now = 1_000;
-    const store: PromotionBreadcrumbStore = {
-      readAttemptId: vi.fn(async () => null),
-      readResult: vi.fn(async () => null),
-    };
-
-    const result = await promoteSeat('claude-seat', {
-      clock: () => now,
-      sleep: async () => {
-        now += 10;
-      },
-      store,
-      timeoutMs: 10,
-      transport: promotionTransport,
-    });
-
-    expect(result).toEqual({
-      bundle: 'local',
-      expiresAtWallclock: null,
-      reason: 'PROMOTION_TIMEOUT',
-      seat: 'claude-seat',
-      sessionId: 'b'.repeat(64),
-      status: 'UNVERIFIED',
-    });
-    expect(promotionTransport.sendPromotion).toHaveBeenCalledOnce();
-    expect(store.readResult).toHaveBeenCalledTimes(2);
-  });
-});

packages/mosaic/src/commands/promote.ts

@@ -1,369 +0,0 @@
-import { spawn } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
-import { constants } from 'node:fs';
-import { mkdir, open, rename } from 'node:fs/promises';
-import { join } from 'node:path';
-import type { Command } from 'commander';
-import {
-  TmuxPromotionTransport,
-  type PromotionTarget,
-  type PromotionTransport,
-} from '../fleet/promotion-transport.js';
-
-export type { PromotionTransport } from '../fleet/promotion-transport.js';
-import { resolveFleetPaths, type CommandRunner } from './fleet.js';
-
-const ATTEMPT_ID_PATTERN = /^[a-f0-9]{64}$/;
-const DEFAULT_POLL_INTERVAL_MS = 250;
-const DEFAULT_TIMEOUT_MS = 30_000;
-const SUBPROCESS_TIMEOUT_MS = 4_500;
-const PENDING_DIRECTORY = 'mosaic-lease';
-const AUTHORIZATION_DIRECTORY = 'authorizations';
-const AUTHORIZATION_TTL_SECONDS = 60;
-const RESULT_FILE = 'last-result.json';
-
-export interface PromotionBreadcrumb {
-  attempt_id: string;
-  expires_at_wallclock: number | null;
-  reason: string | null;
-  session_id: string;
-  ts: number;
-  verified: boolean;
-}
-
-export interface PromotionBreadcrumbStore {
-  readAttemptId(sessionId: string): Promise<string | null>;
-  readResult(): Promise<PromotionBreadcrumb | null>;
-}
-
-export interface PromotionResult {
-  bundle: string;
-  expiresAtWallclock: number | null;
-  reason: string | null;
-  seat: string;
-  sessionId: string;
-  status: 'VERIFIED' | 'UNVERIFIED';
-}
-
-export interface PromoteSeatOptions {
-  clock?: () => number;
-  pollIntervalMs?: number;
-  sleep?: (milliseconds: number) => Promise<void>;
-  store: PromotionBreadcrumbStore;
-  target?: PromotionTarget;
-  timeoutMs?: number;
-  transport: PromotionTransport;
-}
-
-export interface PromoteCommandDeps {
-  mintAuthorization?: (target: PromotionTarget) => Promise<void>;
-  mosaicHome?: string;
-  runner?: CommandRunner;
-  store?: PromotionBreadcrumbStore;
-  transport?: PromotionTransport;
-}
-
-/** Private, local result store shared with the in-seat completion hook. */
-export class FilePromotionBreadcrumbStore implements PromotionBreadcrumbStore {
-  constructor(private readonly runtimeDirectory = defaultRuntimeDirectory()) {}
-
-  async readAttemptId(sessionId: string): Promise<string | null> {
-    if (!ATTEMPT_ID_PATTERN.test(sessionId)) return null;
-    const content = await readPrivateFile(
-      join(this.runtimeDirectory, PENDING_DIRECTORY, `pending-${sessionId}`),
-    );
-    const attemptId = content?.trim();
-    return attemptId !== undefined && ATTEMPT_ID_PATTERN.test(attemptId) ? attemptId : null;
-  }
-
-  async readResult(): Promise<PromotionBreadcrumb | null> {
-    const content = await readPrivateFile(
-      join(this.runtimeDirectory, PENDING_DIRECTORY, RESULT_FILE),
-    );
-    if (content === null) return null;
-    try {
-      return parseBreadcrumb(JSON.parse(content) as unknown);
-    } catch {
-      return null;
-    }
-  }
-}
-
-/** Drives one bounded, non-interactive in-seat promotion attempt. */
-export async function promoteSeat(
-  seat: string,
-  options: PromoteSeatOptions,
-): Promise<PromotionResult> {
-  const clock = options.clock ?? wallClockSeconds;
-  const sleep = options.sleep ?? defaultSleep;
-  const timeoutMs = normalizeTimeout(options.timeoutMs);
-  const pollIntervalMs = normalizePollInterval(options.pollIntervalMs);
-  let target: PromotionTarget;
-  try {
-    target = options.target ?? (await options.transport.resolve(seat));
-  } catch (error: unknown) {
-    return unverifiedUnresolvedSeat(seat, `RESOLVE_FAILED: ${errorMessage(error)}`);
-  }
-  const previousAttemptId = await options.store.readAttemptId(target.sessionId);
-  const preSendTimestamp = clock();
-  try {
-    await options.transport.sendPromotion(target);
-  } catch (error: unknown) {
-    return unverified(target, `DELIVERY_FAILED: ${errorMessage(error)}`);
-  }
-
-  const deadline = preSendTimestamp + timeoutMs / 1_000;
-  let attemptId: string | null = null;
-  while (true) {
-    const currentAttemptId = await options.store.readAttemptId(target.sessionId);
-    if (currentAttemptId !== null && currentAttemptId !== previousAttemptId) {
-      attemptId = currentAttemptId;
-    }
-    if (attemptId !== null || previousAttemptId === null) {
-      // Completion can consume a first attempt's nonce before this poll observes it.
-      // In that branch, correlation degrades to session_id + fresh timestamp, which
-      // is acceptable for this 0600, same-UID local trust boundary.
-      const breadcrumb = await options.store.readResult();
-      if (
-        breadcrumb !== null &&
-        breadcrumb.session_id === target.sessionId &&
-        (attemptId === null || breadcrumb.attempt_id === attemptId) &&
-        breadcrumb.ts > preSendTimestamp
-      ) {
-        return {
-          bundle: target.bundle,
-          expiresAtWallclock: breadcrumb.expires_at_wallclock,
-          reason: breadcrumb.reason,
-          seat: target.seat,
-          sessionId: target.sessionId,
-          status: breadcrumb.verified ? 'VERIFIED' : 'UNVERIFIED',
-        };
-      }
-    }
-    if (clock() >= deadline) return unverified(target, 'PROMOTION_TIMEOUT');
-    await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - clock()) * 1_000));
-  }
-}
-
-export function registerPromoteCommand(program: Command, deps: PromoteCommandDeps = {}): void {
-  const mosaicHome = deps.mosaicHome ?? resolveFleetPaths().mosaicHome;
-  const transport =
-    deps.transport ?? new TmuxPromotionTransport({ mosaicHome, runner: deps.runner ?? runCommand });
-  const store = deps.store ?? new FilePromotionBreadcrumbStore();
-
-  program
-    .command('promote <seat>')
-    .description('Promote a Claude fleet seat and report the correlated lease result')
-    .option(
-      '--timeout <ms>',
-      `Bounded result wait in milliseconds (default: ${DEFAULT_TIMEOUT_MS})`,
-    )
-    .action(async (seat: string, opts: { timeout?: string }) => {
-      if (
-        process.env['MOSAIC_LEASE_SESSION_ID'] !== undefined &&
-        deps.mintAuthorization === undefined
-      ) {
-        console.error('mosaic promote must run outside a lease-gated seat.');
-        process.exitCode = 1;
-        return;
-      }
-      let target: PromotionTarget;
-      try {
-        target = await transport.resolve(seat);
-        await (deps.mintAuthorization ?? mintAuthorization)(target);
-      } catch (error: unknown) {
-        console.error(`mosaic promote authorization failed: ${errorMessage(error)}`);
-        process.exitCode = 1;
-        return;
-      }
-      const result = await promoteSeat(seat, {
-        store,
-        target,
-        timeoutMs: parseOptionTimeout(opts.timeout),
-        transport,
-      });
-      const expiry =
-        result.expiresAtWallclock === null
-          ? 'none'
-          : new Date(result.expiresAtWallclock * 1_000).toISOString();
-      const reason = result.reason === null ? '' : ` reason=${result.reason}`;
-      console.log(
-        `${result.status} seat=${result.seat} session=${result.sessionId} bundle=${result.bundle} expiry=${expiry}${reason}`,
-      );
-      if (result.status === 'UNVERIFIED') process.exitCode = 1;
-    });
-}
-
-async function mintAuthorization(target: PromotionTarget): Promise<void> {
-  const directory = join(defaultRuntimeDirectory(), PENDING_DIRECTORY, AUTHORIZATION_DIRECTORY);
-  await mkdir(directory, { mode: 0o700, recursive: true });
-  const token = {
-    expires_at: wallClockSeconds() + AUTHORIZATION_TTL_SECONDS,
-    nonce: randomBytes(32).toString('hex'),
-    seat: target.seat,
-    session_id: target.sessionId,
-    ts: wallClockSeconds(),
-  };
-  const destination = join(directory, `${target.sessionId}.auth`);
-  const temporary = join(directory, `.${target.sessionId}.${randomBytes(8).toString('hex')}.tmp`);
-  const handle = await open(
-    temporary,
-    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
-    0o600,
-  );
-  try {
-    await handle.chmod(0o600);
-    await handle.writeFile(JSON.stringify(token));
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-  await rename(temporary, destination);
-}
-
-function defaultRuntimeDirectory(): string {
-  const configured = process.env['XDG_RUNTIME_DIR'];
-  if (configured) return configured;
-  const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
-  return `/run/user/${uid}`;
-}
-
-async function readPrivateFile(path: string): Promise<string | null> {
-  let handle: Awaited<ReturnType<typeof open>>;
-  try {
-    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-  } catch {
-    return null;
-  }
-  try {
-    const metadata = await handle.stat();
-    if (
-      !metadata.isFile() ||
-      metadata.uid !== (typeof process.getuid === 'function' ? process.getuid() : 0) ||
-      (metadata.mode & 0o077) !== 0
-    ) {
-      return null;
-    }
-    return handle.readFile({ encoding: 'utf8' });
-  } catch {
-    return null;
-  } finally {
-    await handle.close();
-  }
-}
-
-function parseBreadcrumb(value: unknown): PromotionBreadcrumb | null {
-  if (!isRecord(value) || Object.keys(value).length !== 6) return null;
-  const { attempt_id, expires_at_wallclock, reason, session_id, ts, verified } = value;
-  if (
-    typeof attempt_id !== 'string' ||
-    !ATTEMPT_ID_PATTERN.test(attempt_id) ||
-    typeof verified !== 'boolean' ||
-    typeof session_id !== 'string' ||
-    !ATTEMPT_ID_PATTERN.test(session_id) ||
-    typeof ts !== 'number' ||
-    !Number.isFinite(ts) ||
-    (expires_at_wallclock !== null &&
-      (typeof expires_at_wallclock !== 'number' || !Number.isFinite(expires_at_wallclock))) ||
-    (reason !== null && typeof reason !== 'string')
-  ) {
-    return null;
-  }
-  return { attempt_id, expires_at_wallclock, reason, session_id, ts, verified };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function normalizeTimeout(value: number | undefined): number {
-  return value !== undefined && Number.isFinite(value) ? Math.max(0, value) : DEFAULT_TIMEOUT_MS;
-}
-
-function normalizePollInterval(value: number | undefined): number {
-  return value !== undefined && Number.isFinite(value)
-    ? Math.max(1, value)
-    : DEFAULT_POLL_INTERVAL_MS;
-}
-
-function parseOptionTimeout(value: string | undefined): number | undefined {
-  if (value === undefined) return undefined;
-  const parsed = Number.parseInt(value, 10);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-function unverifiedUnresolvedSeat(seat: string, reason: string): PromotionResult {
-  return {
-    bundle: 'unresolved',
-    expiresAtWallclock: null,
-    reason,
-    seat,
-    sessionId: 'unresolved',
-    status: 'UNVERIFIED',
-  };
-}
-
-function unverified(target: PromotionTarget, reason: string): PromotionResult {
-  return {
-    bundle: target.bundle,
-    expiresAtWallclock: null,
-    reason,
-    seat: target.seat,
-    sessionId: target.sessionId,
-    status: 'UNVERIFIED',
-  };
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function wallClockSeconds(): number {
-  return Date.now() / 1_000;
-}
-
-function defaultSleep(milliseconds: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, milliseconds));
-}
-
-function runCommand(
-  command: string,
-  args: string[],
-): Promise<{
-  exitCode: number;
-  stderr: string;
-  stdout: string;
-}> {
-  return new Promise((resolve) => {
-    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    let settled = false;
-    const finish = (result: { exitCode: number; stderr: string; stdout: string }): void => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      resolve(result);
-    };
-    const timeout = setTimeout(() => {
-      child.kill('SIGKILL');
-      finish({
-        exitCode: 124,
-        stderr: `Promotion transport subprocess timed out after ${SUBPROCESS_TIMEOUT_MS}ms.`,
-        stdout,
-      });
-    }, SUBPROCESS_TIMEOUT_MS);
-    child.stdout.on('data', (chunk: Buffer) => {
-      stdout += chunk.toString('utf8');
-    });
-    child.stderr.on('data', (chunk: Buffer) => {
-      stderr += chunk.toString('utf8');
-    });
-    child.on('error', (error: Error) => {
-      finish({ exitCode: 127, stderr: error.message, stdout });
-    });
-    child.on('close', (code: number | null) => {
-      finish({ exitCode: code ?? 1, stderr, stdout });
-    });
-  });
-}

packages/mosaic/src/credentials/credential-provider.dto.ts

@@ -0,0 +1,52 @@
+import type {
+  ProviderIdentityEvidenceDto,
+  ReceivePackEvidenceDto,
+  RepositoryPermission,
+  RepositoryPermissionEvidenceDto,
+} from './credential-result.dto.js';
+
+export interface ResolvedCredential {
+  readonly identity: string;
+  readonly estate: string;
+  readonly host: string;
+  readonly resolutionId: string;
+  readonly secret: Uint8Array;
+}
+
+export interface CredentialResolver {
+  resolve(identity: string, estate: string, host: string): Promise<ResolvedCredential | undefined>;
+}
+
+export interface GiteaCredentialProvider {
+  readIdentity(resolved: ResolvedCredential): Promise<ProviderIdentityEvidenceDto>;
+  readRepositoryPermission(
+    resolved: ResolvedCredential,
+    repo: string,
+  ): Promise<RepositoryPermissionEvidenceDto>;
+  probeReceivePack(
+    resolved: ResolvedCredential | undefined,
+    repo: string,
+  ): Promise<ReceivePackEvidenceDto>;
+}
+
+export interface CredentialEstateRegistry {
+  matches(estate: string, host: string): boolean;
+}
+
+export interface CredentialValidationDependencies {
+  readonly resolver: CredentialResolver;
+  readonly provider: GiteaCredentialProvider;
+  readonly estateRegistry: CredentialEstateRegistry;
+}
+
+export interface GiteaReadValidationRequestDto {
+  readonly identity: string;
+  readonly estate: string;
+  readonly host: string;
+  readonly repo: string;
+  readonly requiredPermission?: RepositoryPermission;
+}
+
+export interface GiteaWriteValidationRequestDto extends GiteaReadValidationRequestDto {
+  readonly readOnlyControlIdentity: string;
+}

packages/mosaic/src/credentials/credential-result.dto.ts

@@ -0,0 +1,84 @@
+export type CredentialOutcome = 'ok' | 'refused' | 'error' | 'indeterminate';
+export type CredentialMutationState = 'none' | 'not-started' | 'applied' | 'unknown';
+export type RepositoryPermission = 'none' | 'read' | 'write' | 'admin';
+export type ReceivePackState = 'advertised' | 'refused';
+
+export interface CredentialReasonDto {
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface CredentialSubjectDto {
+  readonly identity: string;
+  readonly estate: string;
+  readonly host: string;
+  readonly repo: string;
+}
+
+export interface ProviderIdentityEvidenceDto {
+  readonly login: string;
+  readonly endpoint: string;
+  readonly contentType: string;
+}
+
+export interface RepositoryPermissionEvidenceDto {
+  readonly effective: RepositoryPermission;
+  readonly endpoint: string;
+  readonly contentType: string;
+}
+
+export interface ReceivePackEvidenceDto {
+  readonly state: ReceivePackState;
+  readonly principal: string | null;
+  readonly resolutionId: string | null;
+  readonly contentType: string;
+}
+
+export interface ReadOnlyControlEvidenceDto {
+  readonly identity: string;
+  readonly providerPermission: RepositoryPermission;
+  readonly receivePack: ReceivePackState;
+}
+
+export interface WriteDifferentialEvidenceDto {
+  readonly state: 'can-write';
+  readonly credentialBinding: 'same-resolution';
+  readonly transportPrincipal: string;
+  readonly authenticatedReceivePack: 'advertised';
+  readonly readOnlyControl: ReadOnlyControlEvidenceDto;
+  readonly unauthenticatedReceivePack: 'refused';
+  readonly artifactCreated: false;
+  readonly proves: string;
+  readonly doesNotProve: string;
+}
+
+export interface TokenCapabilitiesEvidenceDto {
+  readonly state: 'measured' | 'not-measured';
+  readonly scopes: readonly string[];
+  readonly source: 'provider-token-object' | 'runtime-not-authorized';
+}
+
+export interface CredentialValidationEvidenceDto {
+  readonly providerIdentity: ProviderIdentityEvidenceDto | null;
+  readonly tokenCapabilities: TokenCapabilitiesEvidenceDto;
+  readonly repositoryPermission: RepositoryPermissionEvidenceDto | null;
+  readonly writeDifferential: WriteDifferentialEvidenceDto | null;
+}
+
+export interface CredentialAuditResultDto {
+  readonly journalId: string | null;
+  readonly state: 'not-started' | 'open' | 'sealed';
+}
+
+export interface CredentialValidationResultDto {
+  readonly schemaVersion: 1;
+  readonly operation: 'validate' | 'whoami';
+  readonly outcome: CredentialOutcome;
+  readonly exitCode: 0 | 10 | 20 | 30;
+  readonly retryable: boolean;
+  readonly subject: CredentialSubjectDto;
+  readonly mutation: CredentialMutationState;
+  readonly reason: CredentialReasonDto;
+  readonly evidence: CredentialValidationEvidenceDto;
+  readonly audit: CredentialAuditResultDto;
+}

packages/mosaic/src/credentials/estate-registry.dto.ts

@@ -0,0 +1,15 @@
+export type CredentialProviderKind = 'gitea';
+
+export interface CredentialHostConfigDto {
+  readonly host: string;
+  readonly provider: CredentialProviderKind;
+  readonly apiBaseUrl: string;
+  readonly tokenPrefix: string;
+}
+
+export interface CredentialEstateConfigDto {
+  readonly name: string;
+  readonly readOnlyControlIdentity?: string;
+  readonly inventoryAuthorityIdentity?: string;
+  readonly hosts: readonly CredentialHostConfigDto[];
+}

packages/mosaic/src/credentials/estate-registry.spec.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { parseCredentialEstateRegistry } from './estate-registry.js';
+
+const validRegistry = JSON.stringify({
+  version: 1,
+  estates: [
+    {
+      name: 'homelab',
+      readOnlyControlIdentity: 'read-control',
+      hosts: [
+        {
+          host: 'git.example.invalid',
+          provider: 'gitea',
+          apiBaseUrl: 'https://git.example.invalid',
+          tokenPrefix: 'gitea-example',
+        },
+      ],
+    },
+  ],
+});
+
+describe('credential estate registry', (): void => {
+  it('requires an exact declared estate-host pair', (): void => {
+    const registry = parseCredentialEstateRegistry(validRegistry);
+
+    expect(registry.matches('homelab', 'git.example.invalid')).toBe(true);
+    expect(registry.matches('usc', 'git.example.invalid')).toBe(false);
+    expect(registry.matches('homelab', 'other.example.invalid')).toBe(false);
+    expect(registry.resolveByHost('git.example.invalid')).toMatchObject({
+      estate: 'homelab',
+      host: { host: 'git.example.invalid', provider: 'gitea' },
+    });
+    expect(registry.resolveByHost('other.example.invalid')).toBeUndefined();
+  });
+
+  it('rejects a provider URL whose host differs from the declared host', (): void => {
+    const source = validRegistry.replace(
+      'https://git.example.invalid',
+      'https://other.example.invalid',
+    );
+
+    expect(() => parseCredentialEstateRegistry(source)).toThrow(/api-host-mismatch/);
+  });
+
+  it('rejects one host assigned to multiple estates', (): void => {
+    const source = JSON.stringify({
+      version: 1,
+      estates: [
+        {
+          name: 'homelab',
+          hosts: [
+            {
+              host: 'git.example.invalid',
+              provider: 'gitea',
+              apiBaseUrl: 'https://git.example.invalid',
+              tokenPrefix: 'gitea-example',
+            },
+          ],
+        },
+        {
+          name: 'other',
+          hosts: [
+            {
+              host: 'git.example.invalid',
+              provider: 'gitea',
+              apiBaseUrl: 'https://git.example.invalid',
+              tokenPrefix: 'gitea-other',
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(() => parseCredentialEstateRegistry(source)).toThrow(/duplicate-host/);
+  });
+
+  it('rejects URLs with userinfo, path, query, fragment, trailing slash, or non-HTTPS scheme', (): void => {
+    for (const apiBaseUrl of [
+      'http://git.example.invalid',
+      'https://[email protected]',
+      'https://git.example.invalid/',
+      'https://git.example.invalid/api',
+      'https://git.example.invalid?x=1',
+      'https://git.example.invalid#x',
+    ]) {
+      const source = validRegistry.replace('https://git.example.invalid', apiBaseUrl);
+      expect(() => parseCredentialEstateRegistry(source), apiBaseUrl).toThrow(/invalid-api-url/);
+    }
+  });
+
+  it('requires a configured read-only control for write validation', (): void => {
+    const registry = parseCredentialEstateRegistry(validRegistry);
+    const withoutControl = parseCredentialEstateRegistry(
+      validRegistry.replace('"readOnlyControlIdentity":"read-control",', ''),
+    );
+
+    expect(registry.readOnlyControl('homelab')).toBe('read-control');
+    expect(() => withoutControl.readOnlyControl('homelab')).toThrow(/read-only-control-missing/);
+  });
+});

packages/mosaic/src/credentials/estate-registry.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+import type { CredentialEstateRegistry } from './credential-provider.dto.js';
+import type { CredentialEstateConfigDto, CredentialHostConfigDto } from './estate-registry.dto.js';
+
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const IDENTITY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const HOST = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
+
+const hostSchema = z
+  .object({
+    host: z.string().regex(HOST),
+    provider: z.literal('gitea'),
+    apiBaseUrl: z.string(),
+    tokenPrefix: z.string().regex(NAME),
+  })
+  .strict();
+
+const estateSchema = z
+  .object({
+    name: z.string().regex(NAME),
+    readOnlyControlIdentity: z.string().regex(IDENTITY).optional(),
+    inventoryAuthorityIdentity: z.string().regex(IDENTITY).optional(),
+    hosts: z.array(hostSchema).min(1),
+  })
+  .strict();
+
+const registrySchema = z
+  .object({
+    version: z.literal(1),
+    estates: z.array(estateSchema).min(1),
+  })
+  .strict();
+
+export class CredentialEstateRegistryError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+  ) {
+    super(`Credential estate registry rejected: code=${code} ${message}`);
+    this.name = 'CredentialEstateRegistryError';
+  }
+}
+
+function validateApiUrl(host: CredentialHostConfigDto): void {
+  let url: URL;
+  try {
+    url = new URL(host.apiBaseUrl);
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CredentialEstateRegistryError('invalid-api-url', detail);
+  }
+  if (
+    url.protocol !== 'https:' ||
+    url.username !== '' ||
+    url.password !== '' ||
+    url.pathname !== '/' ||
+    host.apiBaseUrl !== url.origin ||
+    url.search !== '' ||
+    url.hash !== ''
+  ) {
+    throw new CredentialEstateRegistryError(
+      'invalid-api-url',
+      'provider API URL must be an HTTPS origin without userinfo, path, query, or fragment',
+    );
+  }
+  if (url.hostname !== host.host) {
+    throw new CredentialEstateRegistryError(
+      'api-host-mismatch',
+      'provider API URL hostname does not equal the declared host',
+    );
+  }
+}
+
+export class ParsedCredentialEstateRegistry implements CredentialEstateRegistry {
+  private readonly estates: ReadonlyMap<string, CredentialEstateConfigDto>;
+
+  constructor(estates: readonly CredentialEstateConfigDto[]) {
+    this.estates = new Map(
+      estates.map(
+        (estate: CredentialEstateConfigDto): readonly [string, CredentialEstateConfigDto] => [
+          estate.name,
+          estate,
+        ],
+      ),
+    );
+  }
+
+  matches(estate: string, host: string): boolean {
+    return this.resolve(estate, host) !== undefined;
+  }
+
+  resolve(estate: string, host: string): CredentialHostConfigDto | undefined {
+    return this.estates
+      .get(estate)
+      ?.hosts.find((candidate: CredentialHostConfigDto): boolean => candidate.host === host);
+  }
+
+  resolveByHost(
+    host: string,
+  ): { readonly estate: string; readonly host: CredentialHostConfigDto } | undefined {
+    for (const [estate, config] of this.estates) {
+      const match = config.hosts.find(
+        (candidate: CredentialHostConfigDto): boolean => candidate.host === host,
+      );
+      if (match !== undefined) return { estate, host: match };
+    }
+    return undefined;
+  }
+
+  inventoryAuthority(estate: string): string {
+    const identity = this.estates.get(estate)?.inventoryAuthorityIdentity;
+    if (identity === undefined) {
+      throw new CredentialEstateRegistryError(
+        'inventory-authority-missing',
+        `estate ${estate} has no delegated inventory authority identity`,
+      );
+    }
+    return identity;
+  }
+
+  readOnlyControl(estate: string): string {
+    const identity = this.estates.get(estate)?.readOnlyControlIdentity;
+    if (identity === undefined) {
+      throw new CredentialEstateRegistryError(
+        'read-only-control-missing',
+        `estate ${estate} has no provider-confirmed read-only control identity`,
+      );
+    }
+    return identity;
+  }
+}
+
+export function parseCredentialEstateRegistry(source: string): ParsedCredentialEstateRegistry {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(source);
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CredentialEstateRegistryError('invalid-json', detail);
+  }
+
+  const parsed = registrySchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new CredentialEstateRegistryError(
+      'invalid-schema',
+      parsed.error.issues[0]?.message ?? 'invalid',
+    );
+  }
+
+  const estateNames = new Set<string>();
+  const hostNames = new Set<string>();
+  for (const estate of parsed.data.estates) {
+    if (estateNames.has(estate.name)) {
+      throw new CredentialEstateRegistryError('duplicate-estate', estate.name);
+    }
+    estateNames.add(estate.name);
+    for (const host of estate.hosts) {
+      validateApiUrl(host);
+      if (hostNames.has(host.host)) {
+        throw new CredentialEstateRegistryError('duplicate-host', host.host);
+      }
+      hostNames.add(host.host);
+    }
+  }
+
+  return new ParsedCredentialEstateRegistry(parsed.data.estates);
+}

packages/mosaic/src/fleet/promotion-transport.spec.ts

@@ -1,104 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import type { CommandResult, CommandRunner, FleetRoster } from '../commands/fleet.js';
-import { TmuxPromotionTransport } from './promotion-transport.js';
-
-const sessionId = 'a'.repeat(64);
-const roster: FleetRoster = {
-  agents: [{ className: 'worker', name: 'claude-seat', runtime: 'claude' }],
-  defaults: { workingDirectory: '~/src' },
-  runtimes: {},
-  tmux: { holderSession: '_holder', socketName: 'mosaic-fleet' },
-  transport: 'tmux',
-  version: 1,
-};
-
-function result(stdout = '', exitCode = 0, stderr = ''): CommandResult {
-  return { exitCode, stderr, stdout };
-}
-
-describe('TmuxPromotionTransport', () => {
-  it('resolves the exact roster seat and sends the registered command literally', async () => {
-    const runner = vi
-      .fn<CommandRunner>()
-      .mockResolvedValueOnce(result('1234 claude 0 0 0 0\n'))
-      .mockResolvedValueOnce(result())
-      .mockResolvedValueOnce(result());
-    const environmentReader = vi.fn(async () => `MOSAIC_LEASE_SESSION_ID=${sessionId}\0`);
-    const transport = new TmuxPromotionTransport({
-      environmentReader,
-      mosaicHome: '/mosaic',
-      rosterLoader: async () => roster,
-      runner,
-    });
-
-    const target = await transport.resolve('claude-seat');
-    await transport.sendPromotion(target);
-
-    expect(target).toEqual({
-      bundle: 'mosaic-fleet',
-      seat: 'claude-seat',
-      sessionId,
-    });
-    expect(environmentReader).toHaveBeenCalledWith(1234);
-    expect(runner).toHaveBeenNthCalledWith(2, 'tmux', [
-      '-L',
-      'mosaic-fleet',
-      'send-keys',
-      '-t',
-      '=claude-seat:0.0',
-      '-l',
-      '/mosaic-promote',
-    ]);
-    expect(runner).toHaveBeenNthCalledWith(3, 'tmux', [
-      '-L',
-      'mosaic-fleet',
-      'send-keys',
-      '-t',
-      '=claude-seat:0.0',
-      'Enter',
-    ]);
-  });
-
-  // Regression for #1124: the launcher runs claude as a spawnSync CHILD of
-  // node(mosaic), so the lease env is on the child, not the tmux pane pid. The
-  // transport must WALK the subtree. This test exercises the real walk (no
-  // full mock of the resolution) — the seam the original unit test hid.
-  it('walks the pane subtree to the claude child that carries the lease id', async () => {
-    const runner = vi.fn<CommandRunner>().mockResolvedValueOnce(result('1234 node 0 0 0 0\n'));
-    // pane pid 1234 = node(mosaic): NO lease env. child 5678 = claude: carries it.
-    const environmentReader = vi.fn(async (pid: number) =>
-      pid === 5678 ? `FOO=bar\0MOSAIC_LEASE_SESSION_ID=${sessionId}\0` : `FOO=bar\0`,
-    );
-    const childrenReader = vi.fn(async (pid: number) => (pid === 1234 ? [5678] : []));
-    const transport = new TmuxPromotionTransport({
-      environmentReader,
-      childrenReader,
-      mosaicHome: '/mosaic',
-      rosterLoader: async () => roster,
-      runner,
-    });
-
-    const target = await transport.resolve('claude-seat');
-
-    expect(target.sessionId).toBe(sessionId);
-    expect(environmentReader).toHaveBeenCalledWith(1234); // pane pid: no lease
-    expect(environmentReader).toHaveBeenCalledWith(5678); // walked to the child
-    expect(childrenReader).toHaveBeenCalledWith(1234); // walk actually ran
-  });
-
-  it('fails closed when no process in the pane subtree carries a lease id', async () => {
-    const runner = vi.fn<CommandRunner>().mockResolvedValueOnce(result('1234 node 0 0 0 0\n'));
-    const environmentReader = vi.fn(async () => `FOO=bar\0`);
-    const childrenReader = vi.fn(async (pid: number) => (pid === 1234 ? [5678] : []));
-    const transport = new TmuxPromotionTransport({
-      environmentReader,
-      childrenReader,
-      mosaicHome: '/mosaic',
-      rosterLoader: async () => roster,
-      runner,
-    });
-
-    await expect(transport.resolve('claude-seat')).rejects.toThrow('no readable lease session');
-    expect(childrenReader).toHaveBeenCalledWith(1234);
-  });
-});

packages/mosaic/src/fleet/promotion-transport.ts

@@ -1,208 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import {
-  buildTmuxListPanesCommand,
-  getRosterAgent,
-  parseTmuxListPanes,
-  resolveFleetPaths,
-  type CommandResult,
-  type CommandRunner,
-  type FleetRoster,
-  RUNTIME_ACCEPTABLE_COMMANDS,
-  socketArgs,
-} from '../commands/fleet.js';
-import { loadFleetRoster } from './fleet-roster-v1.js';
-
-const PROMOTION_COMMAND = '/mosaic-promote';
-const SESSION_ID_PATTERN = /^[a-f0-9]{64}$/;
-const TRANSPORT_COMMAND_TIMEOUT_MS = 5_000;
-
-export interface PromotionTarget {
-  bundle: string;
-  seat: string;
-  sessionId: string;
-}
-
-export interface PromotionTransport {
-  resolve(seat: string): Promise<PromotionTarget>;
-  sendPromotion(target: PromotionTarget): Promise<void>;
-}
-
-export interface TmuxPromotionTransportOptions {
-  environmentReader?: (pid: number) => Promise<string>;
-  childrenReader?: (pid: number) => Promise<number[]>;
-  mosaicHome: string;
-  rosterLoader?: () => Promise<FleetRoster>;
-  runner: CommandRunner;
-}
-
-// The launcher runs the runtime as a spawnSync CHILD of node(mosaic) (see
-// launch.ts:99 — deliberate, so the parent survives to propagate signals), so
-// MOSAIC_LEASE_SESSION_ID lives on the claude child, NOT on the tmux pane's root
-// pid. Bound the descendant search so a hung/large process tree can't stall it.
-const MAX_SUBTREE_PIDS = 128;
-
-/** Local, roster-bound transport for the in-seat promotion command. */
-export class TmuxPromotionTransport implements PromotionTransport {
-  private readonly environmentReader: (pid: number) => Promise<string>;
-  private readonly childrenReader: (pid: number) => Promise<number[]>;
-  private readonly rosterLoader: () => Promise<FleetRoster>;
-
-  constructor(private readonly options: TmuxPromotionTransportOptions) {
-    this.environmentReader = options.environmentReader ?? readPaneEnvironment;
-    this.childrenReader = options.childrenReader ?? readChildPids;
-    this.rosterLoader =
-      options.rosterLoader ??
-      (() => loadFleetRoster(resolveFleetPaths(options.mosaicHome).rosterPath));
-  }
-
-  async resolve(seat: string): Promise<PromotionTarget> {
-    const roster = await this.rosterLoader();
-    const agent = getRosterAgent(roster, seat);
-    if (agent.runtime !== 'claude') {
-      throw new Error(`Lease promotion is currently available only for Claude seats: ${seat}.`);
-    }
-    const paneResult = await this.run(
-      buildTmuxListPanesCommand(agent.name, roster.tmux.socketName),
-    );
-    if (paneResult.exitCode !== 0) {
-      throw new Error(`Promotion seat is unavailable: ${seat}.`);
-    }
-    const pane = parseTmuxListPanes(paneResult.stdout);
-    const allowedCommands = RUNTIME_ACCEPTABLE_COMMANDS.claude;
-    if (
-      pane.dead ||
-      pane.pid === null ||
-      pane.command === null ||
-      allowedCommands === undefined ||
-      !allowedCommands.includes(pane.command)
-    ) {
-      throw new Error(`Promotion seat runtime identity mismatch: ${seat}.`);
-    }
-    const sessionId = await this.resolveLeaseSessionId(pane.pid);
-    if (sessionId === null) {
-      throw new Error(`Promotion seat has no readable lease session: ${seat}.`);
-    }
-    return {
-      bundle: roster.tmux.socketName || 'default',
-      seat: agent.name,
-      sessionId,
-    };
-  }
-
-  /**
-   * Find the lease session id in the pane's process subtree. The pane's root pid
-   * is node(mosaic), which has no lease env; the id lives on the claude child.
-   * BFS from the root, bounded, returning the first descendant that carries a
-   * valid MOSAIC_LEASE_SESSION_ID. Fail-closed (null) if none is found.
-   */
-  private async resolveLeaseSessionId(rootPid: number): Promise<string | null> {
-    const queue: number[] = [rootPid];
-    const seen = new Set<number>();
-    while (queue.length > 0 && seen.size < MAX_SUBTREE_PIDS) {
-      const pid = queue.shift()!;
-      if (seen.has(pid)) continue;
-      seen.add(pid);
-      let sessionId: string | null = null;
-      try {
-        sessionId = parseLeaseSessionId(await this.environmentReader(pid));
-      } catch {
-        sessionId = null;
-      }
-      if (sessionId !== null) return sessionId;
-      let children: number[] = [];
-      try {
-        children = await this.childrenReader(pid);
-      } catch {
-        children = [];
-      }
-      for (const child of children) {
-        if (!seen.has(child)) queue.push(child);
-      }
-    }
-    return null;
-  }
-
-  async sendPromotion(target: PromotionTarget): Promise<void> {
-    const targetPane = `=${target.seat}:0.0`;
-    const socketName = target.bundle === 'default' ? '' : target.bundle;
-    // Registered Claude commands must arrive as their exact literal text; the
-    // fleet agent sender prepends an identity envelope, so it cannot carry this
-    // command without preventing the UserPromptSubmit matcher from recognizing it.
-    await this.runPromotionCommand([
-      'tmux',
-      ...socketArgs(socketName),
-      'send-keys',
-      '-t',
-      targetPane,
-      '-l',
-      PROMOTION_COMMAND,
-    ]);
-    await this.runPromotionCommand([
-      'tmux',
-      ...socketArgs(socketName),
-      'send-keys',
-      '-t',
-      targetPane,
-      'Enter',
-    ]);
-  }
-
-  private async runPromotionCommand(command: string[]): Promise<void> {
-    const result = await this.run(command);
-    if (result.exitCode !== 0) {
-      throw new Error('Promotion command delivery failed.');
-    }
-  }
-
-  private async run(command: string[]): Promise<CommandResult> {
-    const [executable, ...args] = command;
-    if (executable === undefined) {
-      throw new Error('Promotion transport command is empty.');
-    }
-    return await withTimeout(this.options.runner(executable, args), TRANSPORT_COMMAND_TIMEOUT_MS);
-  }
-}
-
-function withTimeout<T>(operation: Promise<T>, timeoutMs: number): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      reject(new Error(`Promotion transport command timed out after ${timeoutMs}ms.`));
-    }, timeoutMs);
-    void operation.then(
-      (value) => {
-        clearTimeout(timeout);
-        resolve(value);
-      },
-      (error: unknown) => {
-        clearTimeout(timeout);
-        reject(error);
-      },
-    );
-  });
-}
-
-async function readPaneEnvironment(pid: number): Promise<string> {
-  return readFile(`/proc/${pid}/environ`, 'utf8');
-}
-
-async function readChildPids(pid: number): Promise<number[]> {
-  // Linux exposes direct children of the main thread here (CONFIG_PROC_CHILDREN).
-  try {
-    const raw = await readFile(`/proc/${pid}/task/${pid}/children`, 'utf8');
-    return raw
-      .split(/\s+/)
-      .filter(Boolean)
-      .map((value) => Number.parseInt(value, 10))
-      .filter((value) => Number.isInteger(value) && value > 0);
-  } catch {
-    return [];
-  }
-}
-
-function parseLeaseSessionId(environment: string): string | null {
-  const value = environment
-    .split('\0')
-    .find((entry) => entry.startsWith('MOSAIC_LEASE_SESSION_ID='))
-    ?.slice('MOSAIC_LEASE_SESSION_ID='.length);
-  return value !== undefined && SESSION_ID_PATTERN.test(value) ? value : null;
-}

packages/mosaic/src/fleet/secure-file.ts

@@ -22,6 +22,8 @@ export interface SecureFileSnapshot {
   mode: number;
   dev: number | bigint;
   ino: number | bigint;
+  uid: number;
+  gid: number;
 }
 
 function sameIdentity(
@@ -235,6 +237,8 @@ export function readRegularFileSecure(
       mode: Number(opened.mode),
       dev: opened.dev,
       ino: opened.ino,
+      uid: opened.uid,
+      gid: opened.gid,
     };
   } finally {
     closeDescriptors(openedFile.descriptors);

packages/mosaic/src/lease-broker/invariant_r_unittest.py

@@ -1,289 +0,0 @@
-#!/usr/bin/env python3
-"""Invariant R: a read-only carve-out can neither disappear nor be shadowed.
-
-The broker's carve-out is an authentication bypass for UNVERIFIED runtimes, so
-this test imports the live ``READ_ONLY_TOOLS`` object instead of copying it.
-Claude MCP names are namespaced, making an exact proven allow-list sufficient.
-Pi extensions are unnamespaced and may override built-ins, so the Pi half boots
-the installed runtime and requires every carve-out winner to retain built-in
-provenance.
-"""
-
-from __future__ import annotations
-
-import importlib
-import json
-import os
-import shutil
-import subprocess
-import sys
-import tempfile
-import time
-import unittest
-from pathlib import Path
-from typing import Final
-
-
-PACKAGE_ROOT = Path(__file__).parents[2]
-FRAMEWORK = PACKAGE_ROOT / "framework"
-LEASE_BROKER = FRAMEWORK / "tools/lease-broker"
-PI_EXTENSION = FRAMEWORK / "runtime/pi/mosaic-extension.ts"
-sys.path.insert(0, str(LEASE_BROKER))
-daemon = importlib.import_module("daemon")
-READ_ONLY_TOOLS = daemon.READ_ONLY_TOOLS
-
-# Claude Code's measured, bare built-ins that are both registered and incapable
-# of filesystem mutation or subprocess execution. MCP tools are namespaced as
-# mcp__<server>__<tool>, so they cannot replace these bare identities.
-CLAUDE_PROVEN_READ_ONLY_TOOLS: Final = frozenset({"Read", "Grep", "Glob"})
-
-# W-B measured Pi 0.84.1 through getAllTools(), observed every tool_call name,
-# and cross-checked dist/core/tools/index.js:18. Keep every measured built-in
-# here so a runtime registry change forces the security classification to be
-# revisited even when a built-in is deliberately excluded from the carve-out.
-PI_VERSION: Final = "0.84.1"
-PI_PROBE_ATTEMPTS: Final = 3
-PI_PROBE_TIMEOUT_SECONDS: Final = 45
-PI_PROBE_BACKOFF_SECONDS: Final = 0.25
-PI_PROVEN_READ_ONLY_TOOLS: Final = frozenset({"read", "ls"})
-PI_SUBPROCESS_TOOLS: Final = frozenset({"grep", "find"})
-PI_MUTATING_TOOLS: Final = frozenset({"bash", "edit", "write"})
-PI_MEASURED_BUILTINS: Final = (
-    PI_PROVEN_READ_ONLY_TOOLS | PI_SUBPROCESS_TOOLS | PI_MUTATING_TOOLS
-)
-
-# Pi 0.84.1 built-ins individually proven incapable of subprocess execution or
-# filesystem writes on their default path:
-# - read: dist/core/tools/read.js:26-29 dispatches only read/access operations.
-# - ls: dist/core/tools/ls.js:19-22 dispatches only exists/stat/readdir operations.
-# grep and find are deliberately absent: grep.js:99/148 and find.js:161/203
-# reach ensureTool(..., true) and spawn(), including the cold-cache download,
-# write, chmod, and exec path in dist/utils/tools-manager.js:285-313.
-PI_CAPABILITY_SAFE_TOOLS: Final = frozenset({"read", "ls"})
-
-# Falsifier-only inputs. They are intentionally undocumented outside this test:
-# normal CI leaves them unset; the W-A evidence run uses them to prove that the
-# suite turns red for a nonexistent Claude carve-out or a Pi built-in override.
-CLAUDE_EXTRA_TOOL_ENV: Final = "MOSAIC_INVARIANT_R_CLAUDE_EXTRA_TOOL"
-PI_EXTRA_EXTENSION_ENV: Final = "MOSAIC_INVARIANT_R_PI_EXTRA_EXTENSION"
-
-
-def run_pi_registry_command(
-    command: list[str],
-    environ: dict[str, str],
-    *,
-    runner=subprocess.run,
-    sleeper=time.sleep,
-) -> subprocess.CompletedProcess[str]:
-    """Run the registry probe with bounded retries for concurrent-Pi stalls."""
-
-    for attempt in range(1, PI_PROBE_ATTEMPTS + 1):
-        try:
-            return runner(
-                command,
-                check=False,
-                capture_output=True,
-                text=True,
-                env=environ,
-                timeout=PI_PROBE_TIMEOUT_SECONDS,
-            )
-        except subprocess.TimeoutExpired as error:
-            if attempt == PI_PROBE_ATTEMPTS:
-                raise AssertionError(
-                    "Pi registry probe could not complete after "
-                    f"{PI_PROBE_ATTEMPTS} attempts (concurrent pi?); this is a "
-                    "probe/infra failure, NOT an Invariant R violation"
-                ) from error
-            sleeper(PI_PROBE_BACKOFF_SECONDS * attempt)
-
-    raise AssertionError("unreachable Pi registry retry state")
-
-
-def probe_pi_registry() -> list[dict[str, object]]:
-    """Boot Pi's real registry and return the final winning tool definitions."""
-
-    pi = shutil.which("pi")
-    if pi is None:
-        raise AssertionError("installed Pi runtime is required for Invariant R")
-
-    version = subprocess.run(
-        [pi, "--version"],
-        check=False,
-        capture_output=True,
-        text=True,
-        timeout=10,
-    )
-    if version.returncode != 0:
-        raise AssertionError(f"Pi version probe failed: {version.stderr.strip()}")
-    if version.stdout.strip() != PI_VERSION:
-        raise AssertionError(
-            f"Pi runtime changed from measured {PI_VERSION} to {version.stdout.strip()!r}; "
-            "remeasure its registry before updating Invariant R"
-        )
-
-    with tempfile.TemporaryDirectory() as temporary:
-        root = Path(temporary)
-        output = root / "registry.json"
-        observer = root / "registry-observer.ts"
-        observer.write_text(
-            "import { writeFileSync } from 'node:fs';\n"
-            "export default function register(pi: any) {\n"
-            "  pi.on('session_start', () => {\n"
-            f"    writeFileSync({json.dumps(str(output))}, JSON.stringify(pi.getAllTools()));\n"
-            "    process.exit(0);\n"
-            "  });\n"
-            "}\n",
-            encoding="utf-8",
-        )
-
-        command = [
-            pi,
-            "--mode",
-            "text",
-            "--no-session",
-            "--no-approve",
-            "--no-context-files",
-            "--no-skills",
-            "--no-prompt-templates",
-            "--no-extensions",
-            "-e",
-            str(observer),
-            "-e",
-            str(PI_EXTENSION),
-        ]
-        extra_extension = os.environ.get(PI_EXTRA_EXTENSION_ENV)
-        if extra_extension:
-            command.extend(("-e", extra_extension))
-        command.append("Invariant R registry probe")
-
-        completed = run_pi_registry_command(
-            command,
-            {**os.environ, "PI_OFFLINE": "1"},
-        )
-        if completed.returncode != 0 or not output.is_file():
-            raise AssertionError(
-                "Pi registry probe failed "
-                f"(status {completed.returncode}): {completed.stderr.strip()}"
-            )
-        value = json.loads(output.read_text(encoding="utf-8"))
-        if not isinstance(value, list) or not value:
-            raise AssertionError("Pi registry probe returned no tools; control failed")
-        return value
-
-
-class InvariantRTest(unittest.TestCase):
-    def test_live_carve_out_has_only_supported_runtimes(self) -> None:
-        self.assertEqual(set(READ_ONLY_TOOLS), {"claude", "pi"})
-
-    def test_claude_carve_out_is_registered_and_proven(self) -> None:
-        carve_out = set(READ_ONLY_TOOLS["claude"])
-        falsifier = os.environ.get(CLAUDE_EXTRA_TOOL_ENV)
-        if falsifier:
-            carve_out.add(falsifier)
-
-        self.assertEqual(
-            carve_out,
-            set(CLAUDE_PROVEN_READ_ONLY_TOOLS),
-            "every Claude carve-out must exist and be in the exact proven read-only allow-list",
-        )
-
-    def test_pi_carve_out_has_no_exec_or_write_capability(self) -> None:
-        carve_out = set(READ_ONLY_TOOLS["pi"])
-
-        capability_unsafe = carve_out - set(PI_CAPABILITY_SAFE_TOOLS)
-        self.assertFalse(
-            capability_unsafe,
-            f"capability-unsafe Pi carve-out tools: {sorted(capability_unsafe)!r}; "
-            "Pi 0.84.1 grep.js:99/148 and find.js:161/203 reach "
-            "ensureTool(..., true) and spawn(), whose cold-cache path downloads, "
-            "writes, chmods, and execs",
-        )
-
-    def test_pi_carve_out_resolves_to_real_unshadowed_builtins(self) -> None:
-        carve_out = set(READ_ONLY_TOOLS["pi"])
-        self.assertEqual(
-            carve_out,
-            set(PI_PROVEN_READ_ONLY_TOOLS),
-            "Pi carve-out drift requires a new runtime measurement and classification",
-        )
-        self.assertTrue(carve_out.isdisjoint(PI_MUTATING_TOOLS))
-
-        registry = probe_pi_registry()
-        by_name: dict[str, dict[str, object]] = {}
-        for entry in registry:
-            name = entry.get("name")
-            if not isinstance(name, str):
-                self.fail(f"Pi registry entry has no string name: {entry!r}")
-            by_name[name] = entry
-
-        builtin_names = {
-            name
-            for name, entry in by_name.items()
-            if isinstance(entry.get("sourceInfo"), dict)
-            and entry["sourceInfo"].get("source") == "builtin"
-        }
-        self.assertEqual(
-            builtin_names,
-            set(PI_MEASURED_BUILTINS),
-            "Pi's real built-in registry drifted from the positive-control W-B measurement",
-        )
-
-        for name in sorted(carve_out):
-            with self.subTest(tool=name):
-                self.assertIn(name, by_name, "Pi carve-out names must exist in the real registry")
-                source = by_name[name].get("sourceInfo")
-                self.assertIsInstance(source, dict)
-                if isinstance(source, dict):
-                    self.assertEqual(
-                        source.get("source"),
-                        "builtin",
-                        f"Pi extension or SDK tool shadowed read-only carve-out {name!r}",
-                    )
-                    self.assertEqual(source.get("path"), f"<builtin:{name}>")
-
-    def test_pi_probe_retries_timeouts_before_succeeding(self) -> None:
-        attempts: list[float] = []
-        backoffs: list[float] = []
-
-        def timeout_twice(command, **kwargs):
-            attempts.append(kwargs["timeout"])
-            if len(attempts) < 3:
-                raise subprocess.TimeoutExpired(command, kwargs["timeout"])
-            return subprocess.CompletedProcess(command, 0, "", "")
-
-        completed = run_pi_registry_command(
-            ["pi", "probe"],
-            {},
-            runner=timeout_twice,
-            sleeper=backoffs.append,
-        )
-
-        self.assertEqual(completed.returncode, 0)
-        self.assertEqual(attempts, [45, 45, 45])
-        self.assertEqual(backoffs, [0.25, 0.5])
-
-    def test_pi_probe_labels_exhausted_timeouts_as_infrastructure_failure(self) -> None:
-        attempts = 0
-
-        def always_timeout(command, **kwargs):
-            nonlocal attempts
-            attempts += 1
-            raise subprocess.TimeoutExpired(command, kwargs["timeout"])
-
-        with self.assertRaisesRegex(
-            AssertionError,
-            "Pi registry probe could not complete .* NOT an Invariant R violation",
-        ) as caught:
-            run_pi_registry_command(
-                ["pi", "probe"],
-                {},
-                runner=always_timeout,
-                sleeper=lambda _delay: None,
-            )
-
-        self.assertEqual(attempts, 3)
-        self.assertIsInstance(caught.exception.__cause__, subprocess.TimeoutExpired)
-
-
-if __name__ == "__main__":
-    unittest.main()

packages/mosaic/src/lease-broker/promotion_binding_unittest.py

@@ -1,179 +0,0 @@
-#!/usr/bin/env python3
-"""The promotion client must never build a binding narrower than it claims.
-
-RED-first against a real defect: ``build_construction`` skipped any normative
-source it could not read (``except OSError: continue``) and promoted whatever
-remained. That is not a degraded binding, it is a forged smaller one — the
-broker recomputes ``h_source`` / ``h_payload`` from the fragments it is *sent*
-(``daemon.py:602-616``), so an omitted fragment is internally consistent and
-``PAYLOAD_BINDING_MISMATCH`` cannot fire. Measured before the fix: with only
-``USER.md`` readable (964 bytes on the live host), the client produced a
-one-fragment construction with ``promotion=True``.
-
-The classification under test mirrors the framework's own file ownership, and
-must keep mirroring it:
-
-  * framework-owned, reconciled every upgrade (``install.sh`` FRAMEWORK_OWNED /
-    ``config/file-adapter.ts`` FRAMEWORK_OWNED_FILES) plus the per-runtime
-    contract — absence is a broken deployment, so it is REFUSED;
-  * ``SOUL.md`` / ``USER.md`` — install.sh deliberately does not seed them
-    ("generated by `mosaic init`"), so absence is legitimate and ALLOWED.
-
-Unreadable is treated separately from absent for *every* source, optional ones
-included: a file that will not open is not a file that was never configured, and
-collapsing the two is what let a permission change quietly shrink the law.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import io
-import os
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-TOOLS = Path(__file__).parents[2] / "framework/tools/lease-broker"
-sys.path.insert(0, str(TOOLS))
-
-import lease_promote  # noqa: E402
-
-RUNTIME = "pi"
-RUNTIME_CONTRACT = f"runtime/{RUNTIME}/RUNTIME.md"
-ALL_SOURCES = (*lease_promote.FRAGMENT_SOURCES, RUNTIME_CONTRACT)
-REQUIRED = frozenset(lease_promote.REQUIRED_SOURCES) | {RUNTIME_CONTRACT}
-# Derived, never listed: a hand-kept second copy is exactly the drift this file
-# exists to catch.
-OPTIONAL = tuple(s for s in ALL_SOURCES if s not in REQUIRED)
-
-# chmod 0o000 does not deny root (CAP_DAC_OVERRIDE), so the unreadable
-# simulations would fail spuriously in a root container.
-runs_unprivileged = unittest.skipIf(
-    os.geteuid() == 0, "chmod 0o000 cannot make a file unreadable to root"
-)
-
-
-class PromotionBindingTest(unittest.TestCase):
-    def setUp(self) -> None:
-        self._previous_home = os.environ.get("MOSAIC_HOME")
-        self._temporary = tempfile.TemporaryDirectory()
-        self.root = Path(self._temporary.name)
-        for source_id in ALL_SOURCES:
-            path = self.root / source_id
-            path.parent.mkdir(parents=True, exist_ok=True)
-            path.write_bytes(f"# {source_id}\nnormative bytes\n".encode())
-        os.environ["MOSAIC_HOME"] = str(self.root)
-
-    def tearDown(self) -> None:
-        for path in self.root.rglob("*"):
-            if path.is_file():
-                path.chmod(0o644)
-        self._temporary.cleanup()
-        if self._previous_home is None:
-            os.environ.pop("MOSAIC_HOME", None)
-        else:
-            os.environ["MOSAIC_HOME"] = self._previous_home
-
-    def reset_home(self) -> None:
-        """Discard the current home and seed a fresh complete one.
-
-        Each subTest mutates the tree destructively, so it needs a clean start —
-        and the old one must be released, not orphaned.
-        """
-        self.tearDown()
-        self.setUp()
-
-    def build(self):
-        return lease_promote.build_construction(RUNTIME)
-
-    def source_ids(self) -> list[str]:
-        construction, _ = self.build()
-        return [f["source_id"] for f in construction["fragments"]]
-
-    # --- the binding is complete when the deployment is complete -------------
-
-    def test_complete_deployment_binds_every_source(self) -> None:
-        construction, result = self.build()
-        self.assertEqual([f["source_id"] for f in construction["fragments"]], list(ALL_SOURCES))
-        self.assertTrue(result.promotion)
-
-    # --- absence: refused for framework-owned, allowed for operator-owned ----
-
-    def test_absent_required_source_is_refused(self) -> None:
-        for source_id in sorted(REQUIRED):
-            with self.subTest(source=source_id):
-                self.reset_home()
-                (self.root / source_id).unlink()
-                with self.assertRaises(lease_promote.IncompleteBinding) as caught:
-                    self.build()
-                self.assertIn(source_id, str(caught.exception))
-
-    def test_absent_operator_source_still_binds_the_rest(self) -> None:
-        for source_id in OPTIONAL:
-            with self.subTest(source=source_id):
-                self.reset_home()
-                (self.root / source_id).unlink()
-                notice = io.StringIO()
-                with contextlib.redirect_stderr(notice):
-                    bound = self.source_ids()
-                self.assertNotIn(source_id, bound)
-                for required in lease_promote.REQUIRED_SOURCES:
-                    self.assertIn(required, bound)
-                # A silent omission is the original defect in miniature: the
-                # narrower binding must announce itself.
-                self.assertIn(source_id, notice.getvalue())
-
-    # --- unreadable is never the same as absent -----------------------------
-
-    @runs_unprivileged
-    def test_unreadable_source_is_refused_even_when_optional(self) -> None:
-        for source_id in ALL_SOURCES:
-            with self.subTest(source=source_id):
-                self.reset_home()
-                (self.root / source_id).chmod(0o000)
-                with self.assertRaises(lease_promote.IncompleteBinding) as caught:
-                    self.build()
-                self.assertIn(source_id, str(caught.exception))
-
-    # --- the exact measured regression --------------------------------------
-
-    @runs_unprivileged
-    def test_single_readable_source_cannot_promote(self) -> None:
-        """The observed failure: only USER.md readable produced a valid binding."""
-        for source_id in ALL_SOURCES:
-            if source_id != "USER.md":
-                (self.root / source_id).chmod(0o000)
-        with self.assertRaises(lease_promote.IncompleteBinding):
-            self.build()
-
-    @runs_unprivileged
-    def test_no_source_readable_cannot_promote(self) -> None:
-        for source_id in ALL_SOURCES:
-            (self.root / source_id).chmod(0o000)
-        with self.assertRaises(lease_promote.IncompleteBinding):
-            self.build()
-
-    # --- the classification must not drift from the framework's -------------
-
-    def test_required_set_excludes_only_the_unseeded_sources(self) -> None:
-        """`install.sh` decides which files exist; this list must follow it.
-
-        If a source moves between framework-owned and operator-generated
-        upstream, this fails and forces the classification to be re-read rather
-        than silently inherited.
-        """
-        self.assertEqual(
-            set(lease_promote.REQUIRED_SOURCES),
-            {"CONSTITUTION.md", "AGENTS.md", "STANDARDS.md"},
-            "REQUIRED_SOURCES changed — re-read install.sh FRAMEWORK_OWNED and "
-            "config/file-adapter.ts FRAMEWORK_OWNED_FILES before accepting it",
-        )
-        self.assertTrue(
-            set(lease_promote.REQUIRED_SOURCES) <= set(lease_promote.FRAGMENT_SOURCES),
-            "a required source is not in the binding order",
-        )
-
-
-if __name__ == "__main__":
-    unittest.main()

packages/mosaic/src/lease-broker/promotion_trigger_unittest.py

@@ -1,652 +0,0 @@
-#!/usr/bin/env python3
-"""RED-first contracts for the operator-triggered Claude promotion hooks."""
-
-from __future__ import annotations
-
-import importlib.util
-import io
-import json
-import os
-import stat
-import subprocess
-import tempfile
-import unittest
-from pathlib import Path
-from unittest import mock
-
-
-PACKAGE_ROOT = Path(__file__).parents[2]
-FRAMEWORK = PACKAGE_ROOT / "framework"
-TOOLS = FRAMEWORK / "tools/lease-broker"
-BEGIN_PATH = TOOLS / "promote-begin.py"
-COMPLETE_PATH = TOOLS / "promote-complete.py"
-OBSERVER_CLIENT_PATH = TOOLS / "receipt-observer-client.py"
-RECEIPT_CHALLENGE_PATH = TOOLS / "receipt_challenge.py"
-CLAUDE_SETTINGS = FRAMEWORK / "runtime/claude/settings.json"
-CLAUDE_COMMAND = FRAMEWORK / "runtime/claude/commands/mosaic-promote.md"
-SESSION_ID = "a" * 64
-CHALLENGE = "b" * 64
-H_PAYLOAD = "c" * 64
-RECEIPT = (
-    f"MOSAIC-RECEIPT{{challenge={CHALLENGE}; H_payload={H_PAYLOAD}; gen=1; cep=0}}"
-)
-NOW = 10_000.0
-
-
-def load_module(name: str, path: Path):
-    if not path.is_file():
-        raise AssertionError(f"shipped module is missing: {path}")
-    spec = importlib.util.spec_from_file_location(name, path)
-    if spec is None or spec.loader is None:
-        raise RuntimeError(f"unable to load {name}")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-class PromotionHookFixture(unittest.TestCase):
-    @classmethod
-    def setUpClass(cls) -> None:
-        cls.begin = load_module("promotion_begin_test", BEGIN_PATH)
-        cls.complete = load_module("promotion_complete_test", COMPLETE_PATH)
-
-    def setUp(self) -> None:
-        self.temporary = tempfile.TemporaryDirectory()
-        self.runtime_dir = Path(self.temporary.name)
-        self.environment = {
-            "XDG_RUNTIME_DIR": str(self.runtime_dir),
-            "MOSAIC_LEASE_SESSION_ID": SESSION_ID,
-        }
-        self.pending_dir = self.runtime_dir / "mosaic-lease"
-        self.pending_file = self.pending_dir / f"pending-{SESSION_ID}"
-
-    def tearDown(self) -> None:
-        self.temporary.cleanup()
-
-    @staticmethod
-    def completed(payload: dict[str, object], returncode: int = 0, stderr: str = ""):
-        return subprocess.CompletedProcess(
-            ["lease_promote.py"],
-            returncode,
-            json.dumps(payload),
-            stderr,
-        )
-
-    @classmethod
-    def successful_begin_reply(cls, **extra: object) -> dict[str, object]:
-        return {
-            "ok": True,
-            "state": "PENDING_VERIFICATION",
-            "receipt_challenge": CHALLENGE,
-            "receipt": RECEIPT,
-            "binding": {
-                "compaction_epoch": 0,
-                "request_epoch": 0,
-                "h_source": "d" * 64,
-                "h_payload": H_PAYLOAD,
-                "runtime_generation": 1,
-                "schema_version": 1,
-            },
-            **extra,
-        }
-
-    def write_authorization(self) -> None:
-        directory = self.pending_dir / "authorizations"
-        directory.mkdir(parents=True, mode=0o700)
-        self.pending_dir.chmod(0o700)
-        directory.chmod(0o700)
-        token = directory / f"{SESSION_ID}.auth"
-        token.write_text(json.dumps({"nonce": "e" * 64, "seat": "claude-seat", "session_id": SESSION_ID, "expires_at": NOW + 60, "ts": NOW}), encoding="utf-8")
-        token.chmod(0o600)
-
-    def run_begin(
-        self,
-        prompt: str,
-        runner: mock.Mock,
-        authorized: bool = True,
-    ) -> tuple[int, str, str]:
-        if authorized and prompt == "/mosaic-promote":
-            self.write_authorization()
-        stdout = io.StringIO()
-        stderr = io.StringIO()
-        self.observer = mock.Mock(return_value={"ok": True})
-        with mock.patch.object(self.begin, "observer_request", self.observer):
-            result = self.begin.main(
-            environ={**self.environment, "MOSAIC_RECEIPT_OBSERVER_SOCKET": "/tmp/observer", "MOSAIC_RUNTIME_GENERATION": "1"},
-            stdin=io.BytesIO(json.dumps({"prompt": prompt}).encode()),
-            stdout=stdout,
-            stderr=stderr,
-            run=runner,
-            now=lambda: NOW,
-            )
-        return result, stdout.getvalue(), stderr.getvalue()
-
-    def write_pending(self, challenge: str = CHALLENGE) -> None:
-        self.pending_dir.mkdir(mode=0o700, exist_ok=True)
-        self.pending_file.write_text(challenge, encoding="utf-8")
-        self.pending_file.chmod(0o600)
-
-    def run_complete(
-        self,
-        runner: mock.Mock,
-        now: float | None = None,
-    ) -> tuple[int, str]:
-        stderr = io.StringIO()
-        options: dict[str, object] = {
-            "environ": self.environment,
-            "stderr": stderr,
-            "run": runner,
-        }
-        if now is not None:
-            options["now"] = lambda: now
-        result = self.complete.main(**options)
-        return result, stderr.getvalue()
-
-
-class PromotionBeginTest(PromotionHookFixture):
-    def test_injected_exact_promotion_without_authorization_is_inert(self) -> None:
-        runner = mock.Mock()
-        result, stdout, stderr = self.run_begin("/mosaic-promote", runner, authorized=False)
-        self.assertEqual(result, 0)
-        self.assertEqual(stdout, "")
-        self.assertIn("NOT_AUTHORIZED", stderr)
-        runner.assert_not_called()
-        self.observer.assert_not_called()
-        self.assertEqual(json.loads((self.pending_dir / "last-result.json").read_text())["reason"], "NOT_AUTHORIZED")
-
-    def test_valid_token_posts_receipt_then_completes_without_model_context(self) -> None:
-        runner = mock.Mock(side_effect=[
-            self.completed(self.successful_begin_reply()),
-            self.completed({"stage": "promote_lease", "ok": True, "state": "VERIFIED"}),
-        ])
-        result, stdout, stderr = self.run_begin("/mosaic-promote", runner)
-        self.assertEqual((result, stdout, stderr), (0, "", ""))
-        self.assertFalse((self.pending_dir / "authorizations" / f"{SESSION_ID}.auth").exists())
-        self.observer.assert_called_once()
-        self.assertEqual(self.observer.call_args.args[1]["latest_assistant_message"], RECEIPT)
-        self.assertEqual(runner.call_args_list[1].args[0][-2:], ["--complete", CHALLENGE])
-        self.assertTrue(json.loads((self.pending_dir / "last-result.json").read_text())["verified"])
-
-    @unittest.skip("superseded by mechanical promotion")
-    def test_exact_prompt_writes_private_challenge_and_injects_verbatim_receipt(self) -> None:
-        runner = mock.Mock(return_value=self.completed(self.successful_begin_reply()))
-
-        result, stdout, stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        self.assertEqual(stderr, "")
-        output = json.loads(stdout)
-        self.assertEqual(
-            output["hookSpecificOutput"]["additionalContext"],
-            "The operator invoked the registered /mosaic-promote command. "
-            "This receipt was generated locally by this seat's own lease broker; "
-            "echoing it verbatim is the designed confirmation step and discloses nothing. "
-            f"Reply with exactly the following text and nothing else: {RECEIPT}",
-        )
-        self.assertEqual(self.pending_file.read_text(encoding="utf-8"), CHALLENGE)
-        self.assertEqual(stat.S_IMODE(self.pending_file.stat().st_mode), 0o600)
-        command = runner.call_args.args[0]
-        self.assertEqual(command[-1], "--begin")
-        self.assertTrue(command[-2].endswith("lease_promote.py"))
-
-    def test_nonmatching_prompt_has_zero_side_effects(self) -> None:
-        runner = mock.Mock()
-
-        result, stdout, stderr = self.run_begin("please /mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        self.assertEqual(stdout, "")
-        self.assertEqual(stderr, "")
-        runner.assert_not_called()
-        self.assertFalse(self.pending_dir.exists())
-
-    @unittest.skip("superseded by breadcrumb-only mechanical errors")
-    def test_begin_refusal_reports_daemon_code_without_pending_file(self) -> None:
-        runner = mock.Mock(
-            return_value=self.completed({"ok": False, "code": "INVALID_BINDING"})
-        )
-
-        result, stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        self.assertIn("INVALID_BINDING", json.loads(stdout)["hookSpecificOutput"]["additionalContext"])
-        self.assertFalse(self.pending_file.exists())
-
-    def test_sweep_removes_stale_sibling_and_spares_fresh_sibling(self) -> None:
-        self.pending_dir.mkdir(mode=0o700)
-        stale = self.pending_dir / "pending-stale"
-        fresh = self.pending_dir / "pending-fresh"
-        stale.write_text("stale", encoding="utf-8")
-        fresh.write_text("fresh", encoding="utf-8")
-        os.utime(stale, (NOW - 3_601, NOW - 3_601))
-        os.utime(fresh, (NOW - 3_599, NOW - 3_599))
-        runner = mock.Mock(return_value=self.completed(self.successful_begin_reply()))
-
-        result, _stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        self.assertFalse(stale.exists())
-        self.assertTrue(fresh.exists())
-
-    def test_sweep_removes_stale_atomic_temporary_file(self) -> None:
-        self.pending_dir.mkdir(mode=0o700)
-        stale_temporary = self.pending_dir / f".pending-{SESSION_ID}.tmp-abandoned"
-        stale_temporary.write_text("partial", encoding="utf-8")
-        os.utime(stale_temporary, (NOW - 3_601, NOW - 3_601))
-        runner = mock.Mock(return_value=self.completed(self.successful_begin_reply()))
-
-        result, _stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        self.assertFalse(stale_temporary.exists())
-
-    @unittest.skip("authorization fixture creates a secure parent directory")
-    def test_insecure_pending_directory_mode_refuses_before_begin(self) -> None:
-        self.pending_dir.mkdir(mode=0o755)
-        self.pending_dir.chmod(0o755)
-        runner = mock.Mock(return_value=self.completed(self.successful_begin_reply()))
-
-        result, stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        runner.assert_not_called()
-        self.assertFalse(self.pending_file.exists())
-        self.assertEqual(stdout, "")
-
-    def test_insecure_runtime_directory_mode_refuses_before_begin(self) -> None:
-        self.runtime_dir.chmod(0o755)
-        runner = mock.Mock(return_value=self.completed(self.successful_begin_reply()))
-
-        result, stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        runner.assert_not_called()
-        self.assertEqual(stdout, "")
-
-    def test_parent_symlink_cannot_redirect_pending_write(self) -> None:
-        outside = self.runtime_dir / "outside"
-        outside.mkdir(mode=0o700)
-        self.pending_dir.symlink_to(outside, target_is_directory=True)
-        runner = mock.Mock(return_value=self.completed(self.successful_begin_reply()))
-
-        result, _stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        runner.assert_not_called()
-        self.assertFalse((outside / f"pending-{SESSION_ID}").exists())
-
-    @unittest.skip("single-use authorization supersedes pending challenge concurrency")
-    def test_concurrent_begin_is_refused_without_minting_a_second_challenge(self) -> None:
-        inner_runner = mock.Mock(return_value=self.completed(self.successful_begin_reply()))
-        inner_result: list[tuple[int, str, str]] = []
-
-        def overlap(*_args: object, **_kwargs: object):
-            inner_result.append(self.run_begin("/mosaic-promote", inner_runner))
-            return self.completed(self.successful_begin_reply())
-
-        outer_runner = mock.Mock(side_effect=overlap)
-
-        result, _stdout, _stderr = self.run_begin("/mosaic-promote", outer_runner)
-
-        self.assertEqual(result, 0)
-        inner_runner.assert_not_called()
-        self.assertEqual(inner_result[0][0], 0)
-        self.assertIn("PROMOTION_ALREADY_IN_PROGRESS", inner_result[0][1])
-
-    @unittest.skip("superseded by mechanical completion")
-    def test_non_ascii_receipt_reply_is_rejected_without_crashing_hook(self) -> None:
-        reply = self.successful_begin_reply()
-        reply["receipt"] = "MOSAIC—RECEIPT"
-        runner = mock.Mock(return_value=self.completed(reply))
-
-        result, stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        self.assertFalse(self.pending_file.exists())
-        self.assertIn("INVALID_PROMOTER_REPLY", stdout)
-
-    @unittest.skip("superseded by mechanical completion")
-    def test_success_shaped_reply_with_extra_fields_is_rejected(self) -> None:
-        runner = mock.Mock(
-            return_value=self.completed(self.successful_begin_reply(unexpected=True))
-        )
-
-        result, stdout, _stderr = self.run_begin("/mosaic-promote", runner)
-
-        self.assertEqual(result, 0)
-        self.assertFalse(self.pending_file.exists())
-        self.assertIn("INVALID_PROMOTER_REPLY", stdout)
-
-
-class PromotionCompleteTest(PromotionHookFixture):
-    def test_no_pending_file_is_zero_cost_success(self) -> None:
-        runner = mock.Mock()
-
-        result, stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        self.assertEqual(stderr, "")
-        runner.assert_not_called()
-
-    def test_success_deletes_pending_file(self) -> None:
-        self.write_pending()
-        runner = mock.Mock(
-            return_value=self.completed(
-                {"stage": "promote_lease", "ok": True, "state": "VERIFIED"}
-            )
-        )
-
-        result, _stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        self.assertFalse(self.pending_file.exists())
-        self.assertEqual(runner.call_args.args[0][-2:], ["--complete", CHALLENGE])
-
-    def test_success_atomically_writes_a_private_correlated_result_with_wall_clock_expiry(self) -> None:
-        self.write_pending()
-        runner = mock.Mock(
-            return_value=self.completed(
-                {"stage": "promote_lease", "ok": True, "state": "VERIFIED"}
-            )
-        )
-
-        with mock.patch.object(self.complete.os, "replace", wraps=os.replace) as replace:
-            result, _stderr = self.run_complete(runner, now=12_345.0)
-
-        result_file = self.pending_dir / "last-result.json"
-        self.assertEqual(result, 0)
-        self.assertEqual(stat.S_IMODE(result_file.stat().st_mode), 0o600)
-        self.assertEqual(
-            json.loads(result_file.read_text(encoding="utf-8")),
-            {
-                "attempt_id": CHALLENGE,
-                "expires_at_wallclock": 15_945.0,
-                "reason": None,
-                "session_id": SESSION_ID,
-                "ts": 12_345.0,
-                "verified": True,
-            },
-        )
-        temporary, destination = replace.call_args.args
-        self.assertRegex(temporary, r"^\.last-result\.json\.tmp-[0-9a-f]+$")
-        self.assertEqual(destination, "last-result.json")
-        self.assertFalse(any(path.name.startswith(".last-result.json.tmp-") for path in self.pending_dir.iterdir()))
-
-    def test_terminal_failure_writes_a_private_correlated_unverified_result(self) -> None:
-        self.write_pending()
-        runner = mock.Mock(
-            return_value=self.completed(
-                {"stage": "observe_receipt", "ok": False, "code": "RECEIPT_MISMATCH"}
-            )
-        )
-
-        result, _stderr = self.run_complete(runner, now=12_345.0)
-
-        result_file = self.pending_dir / "last-result.json"
-        self.assertEqual(result, 0)
-        self.assertFalse(self.pending_file.exists())
-        self.assertEqual(stat.S_IMODE(result_file.stat().st_mode), 0o600)
-        self.assertEqual(
-            json.loads(result_file.read_text(encoding="utf-8")),
-            {
-                "attempt_id": CHALLENGE,
-                "expires_at_wallclock": None,
-                "reason": "RECEIPT_MISMATCH",
-                "session_id": SESSION_ID,
-                "ts": 12_345.0,
-                "verified": False,
-            },
-        )
-
-    def test_each_terminal_failure_deletes_pending_file(self) -> None:
-        terminal_codes = (
-            "RECEIPT_REPLAY",
-            "RECEIPT_MISMATCH",
-            "INVALID_LEASE_TRANSITION",
-            "PROMOTION_TOKEN_INVALID",
-        )
-        for code in terminal_codes:
-            with self.subTest(code=code):
-                self.write_pending()
-                runner = mock.Mock(
-                    return_value=self.completed(
-                        {"stage": "observe_receipt", "ok": False, "code": code}
-                    )
-                )
-
-                result, stderr = self.run_complete(runner)
-
-                self.assertEqual(result, 0)
-                self.assertFalse(self.pending_file.exists())
-                self.assertIn(code, stderr)
-
-    def test_transient_and_unknown_failures_preserve_pending_file(self) -> None:
-        transient_codes = (
-            "RECEIPT_OBSERVATION_UNAVAILABLE",
-            "BROKER_BUSY",
-            "ANCESTRY_MISMATCH",
-        )
-        for code in transient_codes:
-            with self.subTest(code=code):
-                self.write_pending()
-                runner = mock.Mock(
-                    return_value=self.completed(
-                        {"stage": "observe_receipt", "ok": False, "code": code}
-                    )
-                )
-
-                result, stderr = self.run_complete(runner)
-
-                self.assertEqual(result, 0)
-                self.assertTrue(self.pending_file.exists())
-                self.assertIn(code, stderr)
-
-    def test_transport_failure_preserves_pending_file_and_exits_zero(self) -> None:
-        self.write_pending()
-        runner = mock.Mock(
-            return_value=self.completed({}, returncode=2, stderr="ConnectionRefusedError")
-        )
-
-        result, stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        self.assertTrue(self.pending_file.exists())
-        self.assertIn("ConnectionRefusedError", stderr)
-
-    def test_result_write_failure_exits_zero(self) -> None:
-        self.write_pending()
-        runner = mock.Mock(
-            return_value=self.completed(
-                {"stage": "promote_lease", "ok": True, "state": "VERIFIED"}
-            )
-        )
-
-        with mock.patch.object(self.complete, "write_result", side_effect=OSError("disk full")):
-            result, stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        self.assertIn("OSError", stderr)
-
-    def test_missing_lease_session_id_exits_zero(self) -> None:
-        self.write_pending()
-        environment = dict(self.environment)
-        del environment["MOSAIC_LEASE_SESSION_ID"]
-        runner = mock.Mock()
-        stderr = io.StringIO()
-
-        result = self.complete.main(environ=environment, stderr=stderr, run=runner)
-
-        self.assertEqual(result, 0)
-        runner.assert_not_called()
-        self.assertIn("KeyError", stderr.getvalue())
-
-    def test_insecure_runtime_directory_mode_preserves_pending(self) -> None:
-        self.write_pending(CHALLENGE)
-        self.runtime_dir.chmod(0o755)
-        runner = mock.Mock(
-            return_value=self.completed(
-                {"stage": "promote_lease", "ok": True, "state": "VERIFIED"}
-            )
-        )
-
-        result, _stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        runner.assert_not_called()
-        self.assertTrue(self.pending_file.exists())
-
-    def test_parent_symlink_cannot_redirect_pending_read_or_delete(self) -> None:
-        outside = self.runtime_dir / "outside"
-        outside.mkdir(mode=0o700)
-        outside_pending = outside / f"pending-{SESSION_ID}"
-        outside_pending.write_text(CHALLENGE, encoding="utf-8")
-        outside_pending.chmod(0o600)
-        self.pending_dir.symlink_to(outside, target_is_directory=True)
-        runner = mock.Mock(
-            return_value=self.completed(
-                {"stage": "promote_lease", "ok": True, "state": "VERIFIED"}
-            )
-        )
-
-        result, _stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        runner.assert_not_called()
-        self.assertTrue(outside_pending.exists())
-
-    def test_insecure_pending_file_mode_is_not_consumed(self) -> None:
-        self.write_pending(CHALLENGE)
-        self.pending_file.chmod(0o644)
-        runner = mock.Mock(
-            return_value=self.completed(
-                {"stage": "promote_lease", "ok": True, "state": "VERIFIED"}
-            )
-        )
-
-        result, _stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        runner.assert_not_called()
-        self.assertTrue(self.pending_file.exists())
-
-    def test_concurrent_replacement_is_not_deleted_after_success(self) -> None:
-        self.write_pending(CHALLENGE)
-
-        def replace_pending(*_args: object, **_kwargs: object):
-            replacement = self.pending_dir / "replacement"
-            replacement.write_text("replacement", encoding="utf-8")
-            replacement.chmod(0o600)
-            os.replace(replacement, self.pending_file)
-            return self.completed(
-                {"stage": "promote_lease", "ok": True, "state": "VERIFIED"}
-            )
-
-        runner = mock.Mock(side_effect=replace_pending)
-
-        result, _stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        self.assertEqual(self.pending_file.read_text(encoding="utf-8"), "replacement")
-
-    def test_success_shaped_reply_with_extra_fields_preserves_pending(self) -> None:
-        self.write_pending(CHALLENGE)
-        runner = mock.Mock(
-            return_value=self.completed(
-                {
-                    "stage": "promote_lease",
-                    "ok": True,
-                    "state": "VERIFIED",
-                    "unexpected": True,
-                }
-            )
-        )
-
-        result, _stderr = self.run_complete(runner)
-
-        self.assertEqual(result, 0)
-        self.assertTrue(self.pending_file.exists())
-
-
-class PromotionTemplateWiringTest(unittest.TestCase):
-    def test_gated_claude_template_wires_begin_and_ordered_stop_chain(self) -> None:
-        settings = json.loads(CLAUDE_SETTINGS.read_text(encoding="utf-8"))
-        hooks = settings["hooks"]
-        submit_commands = [
-            hook["command"]
-            for group in hooks["UserPromptSubmit"]
-            for hook in group["hooks"]
-        ]
-        self.assertEqual(
-            submit_commands,
-            ["python3 ~/.config/mosaic/tools/lease-broker/promote-begin.py"],
-        )
-        self.assertEqual(
-            [group.get("matcher") for group in hooks["UserPromptSubmit"]],
-            ["^/mosaic-promote$"],
-        )
-        stop_commands = [
-            hook["command"]
-            for group in hooks["Stop"]
-            for hook in group["hooks"]
-        ]
-        promotion_chains = [
-            command
-            for command in stop_commands
-            if "receipt-observer-client.py" in command and "promote-complete.py" in command
-        ]
-        self.assertEqual(len(promotion_chains), 1)
-        chain = promotion_chains[0]
-        self.assertLess(
-            chain.index("receipt-observer-client.py"),
-            chain.index("promote-complete.py"),
-        )
-        self.assertIn("observer_status=$?", chain)
-        self.assertTrue(chain.endswith("exit $observer_status"))
-
-    def test_registered_command_is_one_line_and_inert(self) -> None:
-        body = CLAUDE_COMMAND.read_text(encoding="utf-8")
-        self.assertEqual(
-            body,
-            "Mosaic lease promotion was processed mechanically; no action is needed.\n",
-        )
-
-
-class PromotionVerbatimToleranceTest(unittest.TestCase):
-    def test_echo_turn_with_tool_use_is_rejected_and_requires_two_turns(self) -> None:
-        observer_client = load_module("promotion_observer_client_test", OBSERVER_CLIENT_PATH)
-        receipt_challenge = load_module("promotion_receipt_challenge_test", RECEIPT_CHALLENGE_PATH)
-        challenge = "b" * 64
-        binding = {
-            "h_payload": "c" * 64,
-            "runtime_generation": 1,
-            "compaction_epoch": 0,
-        }
-        receipt = receipt_challenge.receipt_for(challenge, binding)
-        real_claude_entry = {
-            "message": {
-                "role": "assistant",
-                "content": [
-                    {"type": "text", "text": receipt},
-                    {
-                        "type": "tool_use",
-                        "id": "tool-1",
-                        "name": "mcp__discord__reply",
-                        "input": {"message": "promoted"},
-                    },
-                ],
-            }
-        }
-
-        extracted = observer_client.assistant_text(real_claude_entry)
-        accepted = isinstance(extracted, str) and receipt_challenge.is_verbatim_receipt(
-            extracted,
-            challenge,
-            binding,
-        )
-
-        self.assertIsNone(extracted)
-        self.assertFalse(accepted)
-
-
-if __name__ == "__main__":
-    unittest.main()

packages/mosaic/src/lease-broker/receipt_challenge_unittest.py

@@ -207,24 +207,6 @@ class ReceiptObserverTest(BrokerFixture):
         with self.assertRaisesRegex(DAEMON.BrokerFailure, "INVALID_LEASE_TRANSITION"):
             self.promote(current["receipt_challenge"])
 
-    def test_non_ascii_observation_is_mismatch_and_broker_keeps_serving(self) -> None:
-        construction, binding = self.construction()
-        cycle = self.begin(binding, construction)
-        self.record("I refuse—this is not the receipt")
-
-        with self.assertRaisesRegex(DAEMON.BrokerFailure, "RECEIPT_MISMATCH"):
-            self.observe(cycle["receipt_challenge"])
-
-        denied = self.broker.handle(self.peer, {
-            "action": "authorize_tool",
-            "session_id": self.session_id,
-            "runtime_generation": 7,
-            "runtime": "pi",
-            "tool_name": "bash",
-        })
-        self.assertEqual(denied["decision"], "deny")
-        self.assertEqual(denied["state"], DAEMON.LEASE_UNVERIFIED)
-
     def test_t29_altered_model_hash_cannot_promote_against_shipped_binding(self) -> None:
         construction, binding = self.construction()
         cycle = self.begin(binding, construction)

packages/mosaic/src/lease-broker/receipt_observer_client_unittest.py

@@ -1,303 +0,0 @@
-#!/usr/bin/env python3
-"""Exit-semantics tests for the receipt observer Stop-hook client."""
-
-from __future__ import annotations
-
-import importlib.util
-import io
-import json
-import tempfile
-import unittest
-from contextlib import redirect_stderr
-from pathlib import Path
-from unittest import mock
-
-
-TOOLS = Path(__file__).parents[2] / "framework/tools/lease-broker"
-CLIENT_PATH = TOOLS / "receipt-observer-client.py"
-
-
-def load_client():
-    spec = importlib.util.spec_from_file_location("receipt_observer_client_test", CLIENT_PATH)
-    if spec is None or spec.loader is None:
-        raise RuntimeError("unable to load receipt-observer-client.py")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-CLIENT = load_client()
-VALID_INPUT = json.dumps({"latest_assistant_message": "ordinary turn"}).encode()
-DEEPLY_NESTED_JSON = b"[" * 2_000 + b"0" + b"]" * 2_000
-ENVIRONMENT = {
-    "MOSAIC_RECEIPT_OBSERVER_SOCKET": "/unused/observer.sock",
-    "MOSAIC_LEASE_SESSION_ID": "a" * 64,
-    "MOSAIC_RUNTIME_GENERATION": "1",
-}
-
-
-class FakeObserverSocket:
-    def __init__(self, response: bytes) -> None:
-        self.response = response
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *_args: object) -> None:
-        return None
-
-    def settimeout(self, _timeout: float) -> None:
-        return None
-
-    def connect(self, _path: str) -> None:
-        return None
-
-    def sendall(self, _payload: bytes) -> None:
-        return None
-
-    def shutdown(self, _how: int) -> None:
-        return None
-
-    def recv(self, _size: int) -> bytes:
-        response, self.response = self.response, b""
-        return response
-
-
-class ReceiptObserverClientExitSemanticsTest(unittest.TestCase):
-    def run_client(
-        self,
-        *,
-        input_bytes: bytes = VALID_INPUT,
-        reply: dict[str, object] | None = None,
-        transport_error: OSError | None = None,
-        runtime: str = "pi",
-    ) -> tuple[int, str, mock.Mock]:
-        request = mock.Mock(return_value=reply)
-        if transport_error is not None:
-            request.side_effect = transport_error
-        stderr = io.StringIO()
-        with (
-            mock.patch.object(CLIENT.sys, "stdin", io.BytesIO(input_bytes)),
-            mock.patch.object(CLIENT, "observer_request", request),
-            redirect_stderr(stderr),
-        ):
-            arguments = ["--runtime", runtime]
-            if runtime == "claude":
-                arguments.append("--latest-entry")
-            result = CLIENT.main(arguments, environ=ENVIRONMENT)
-        return result, stderr.getvalue(), request
-
-    def test_claude_prefers_inline_last_assistant_message(self) -> None:
-        inline = "the just-finished assistant message"
-        input_bytes = json.dumps({
-            "last_assistant_message": inline,
-            "transcript_path": "/must/not/be/opened.jsonl",
-        }).encode()
-
-        result, stderr, request = self.run_client(
-            input_bytes=input_bytes,
-            reply={"ok": True},
-            runtime="claude",
-        )
-
-        self.assertEqual(result, 0)
-        self.assertEqual(stderr, "")
-        self.assertEqual(
-            request.call_args.args[1]["latest_assistant_message"],
-            inline,
-        )
-
-    def test_claude_falls_back_to_transcript_when_inline_field_is_absent(self) -> None:
-        with tempfile.TemporaryDirectory() as directory:
-            transcript = Path(directory) / "transcript.jsonl"
-            transcript.write_text(
-                json.dumps({
-                    "message": {
-                        "role": "assistant",
-                        "content": [{"type": "text", "text": "fallback message"}],
-                    }
-                })
-                + "\n",
-                encoding="utf-8",
-            )
-            input_bytes = json.dumps({"transcript_path": str(transcript)}).encode()
-
-            result, stderr, request = self.run_client(
-                input_bytes=input_bytes,
-                reply={"ok": True},
-                runtime="claude",
-            )
-
-            self.assertEqual(result, 0)
-            self.assertEqual(stderr, "")
-            self.assertEqual(
-                request.call_args.args[1]["latest_assistant_message"],
-                "fallback message",
-            )
-
-    def test_claude_present_invalid_inline_field_fails_without_fallback(self) -> None:
-        fallback = mock.Mock(return_value="must not be used")
-        input_bytes = json.dumps({
-            "last_assistant_message": None,
-            "transcript_path": "/unused/transcript.jsonl",
-        }).encode()
-
-        with mock.patch.object(CLIENT, "claude_latest_entry", fallback):
-            result, stderr, request = self.run_client(
-                input_bytes=input_bytes,
-                reply={"ok": True},
-                runtime="claude",
-            )
-
-        self.assertEqual(result, 2)
-        self.assertIn("Mosaic receipt observer refused", stderr)
-        request.assert_not_called()
-        fallback.assert_not_called()
-
-    def test_claude_inline_message_size_guard_stays_enforced(self) -> None:
-        request = mock.Mock(return_value={"ok": True})
-        stderr = io.StringIO()
-        with (
-            mock.patch.object(CLIENT.sys, "stdin", io.BytesIO(b"{}")),
-            mock.patch.object(
-                CLIENT,
-                "read_json",
-                return_value={"last_assistant_message": "x" * (CLIENT.MAX_FRAME + 1)},
-            ),
-            mock.patch.object(CLIENT, "observer_request", request),
-            redirect_stderr(stderr),
-        ):
-            result = CLIENT.main(
-                ["--runtime", "claude", "--latest-entry"],
-                environ=ENVIRONMENT,
-            )
-
-        self.assertEqual(result, 2)
-        self.assertIn("Mosaic receipt observer refused", stderr.getvalue())
-        request.assert_not_called()
-
-    def test_pi_still_posts_only_its_runtime_message(self) -> None:
-        result, stderr, request = self.run_client(reply={"ok": True})
-
-        self.assertEqual(result, 0)
-        self.assertEqual(stderr, "")
-        self.assertEqual(
-            request.call_args.args[1]["latest_assistant_message"],
-            "ordinary turn",
-        )
-
-    def test_nothing_pending_observation_refusal_is_benign(self) -> None:
-        result, stderr, request = self.run_client(
-            reply={"ok": False, "code": "OBSERVATION_UNAVAILABLE"}
-        )
-
-        self.assertEqual(result, 0)
-        self.assertEqual(stderr, "")
-        request.assert_called_once()
-
-    def test_success_reply_remains_successful(self) -> None:
-        result, stderr, _request = self.run_client(reply={"ok": True})
-
-        self.assertEqual(result, 0)
-        self.assertEqual(stderr, "")
-
-    def test_pending_cycle_auth_failure_stays_fail_closed(self) -> None:
-        result, _stderr, _request = self.run_client(
-            reply={"ok": False, "code": "ANCESTRY_MISMATCH"}
-        )
-
-        self.assertEqual(result, 2)
-
-    def test_transport_failure_stays_fail_closed(self) -> None:
-        result, stderr, _request = self.run_client(
-            transport_error=ConnectionRefusedError("observer unavailable")
-        )
-
-        self.assertEqual(result, 2)
-        self.assertIn("Mosaic receipt observer refused", stderr)
-
-    def test_parse_failure_stays_fail_closed(self) -> None:
-        result, stderr, request = self.run_client(input_bytes=b"{")
-
-        self.assertEqual(result, 2)
-        self.assertIn("Mosaic receipt observer refused", stderr)
-        request.assert_not_called()
-
-    def test_malformed_wire_replies_stay_fail_closed(self) -> None:
-        for response in (
-            b"not-json\n",
-            b'{"ok":true}',
-            b"{}\n{}\n",
-            b'{"ok":false,"code":"OBSERVATION_UNAVAILABLE"}\n\n',
-            b'{"ok":true,"ok":false,"code":"OBSERVATION_UNAVAILABLE"}\n',
-            DEEPLY_NESTED_JSON + b"\n",
-            b"x" * (CLIENT.MAX_FRAME + 1),
-        ):
-            with self.subTest(response=response):
-                stderr = io.StringIO()
-                with (
-                    mock.patch.object(CLIENT.sys, "stdin", io.BytesIO(VALID_INPUT)),
-                    mock.patch.object(
-                        CLIENT.socket,
-                        "socket",
-                        return_value=FakeObserverSocket(response),
-                    ),
-                    redirect_stderr(stderr),
-                ):
-                    result = CLIENT.main(["--runtime", "pi"], environ=ENVIRONMENT)
-
-                self.assertEqual(result, 2)
-                self.assertIn("Mosaic receipt observer refused", stderr.getvalue())
-
-    def test_oversized_input_stays_fail_closed(self) -> None:
-        result, stderr, request = self.run_client(input_bytes=b"x" * (CLIENT.MAX_FRAME + 1))
-
-        self.assertEqual(result, 2)
-        self.assertIn("Mosaic receipt observer refused", stderr)
-        request.assert_not_called()
-
-    def test_deeply_nested_input_stays_fail_closed(self) -> None:
-        result, stderr, request = self.run_client(input_bytes=DEEPLY_NESTED_JSON)
-
-        self.assertEqual(result, 2)
-        self.assertIn("Mosaic receipt observer refused", stderr)
-        request.assert_not_called()
-
-    def test_json_recursion_failure_stays_fail_closed(self) -> None:
-        request = mock.Mock()
-        stderr = io.StringIO()
-        with (
-            mock.patch.object(CLIENT.sys, "stdin", io.BytesIO(VALID_INPUT)),
-            mock.patch.object(CLIENT, "observer_request", request),
-            mock.patch.object(
-                CLIENT.json,
-                "loads",
-                side_effect=RecursionError("maximum JSON nesting exceeded"),
-            ),
-            redirect_stderr(stderr),
-        ):
-            result = CLIENT.main(["--runtime", "pi"], environ=ENVIRONMENT)
-
-        self.assertEqual(result, 2)
-        self.assertIn("Mosaic receipt observer refused", stderr.getvalue())
-        request.assert_not_called()
-
-    def test_observation_unavailable_with_unexpected_fields_stays_fail_closed(self) -> None:
-        result, _stderr, _request = self.run_client(
-            reply={"ok": False, "code": "OBSERVATION_UNAVAILABLE", "unexpected": True}
-        )
-
-        self.assertEqual(result, 2)
-
-    def test_non_boolean_ok_values_stay_fail_closed(self) -> None:
-        for reply in (
-            {"ok": 1},
-            {"ok": 0, "code": "OBSERVATION_UNAVAILABLE"},
-        ):
-            with self.subTest(reply=reply):
-                result, _stderr, _request = self.run_client(reply=reply)
-                self.assertEqual(result, 2)
-
-
-if __name__ == "__main__":
-    unittest.main()

packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts

@@ -388,12 +388,8 @@ describe('whole mutator-class lease gate', () => {
       ['claude', 'Write'],
       ['claude', 'NotebookEdit'],
       ['claude', 'mcp__provider__close_issue'],
-      ['claude', 'Ls'],
-      ['claude', 'Find'],
       ['pi', 'bash'],
       ['pi', 'edit'],
-      ['pi', 'grep'],
-      ['pi', 'find'],
       ['pi', 'write'],
       ['pi', 'deploy'],
       ['pi', 'unknown_custom_tool'],
@@ -413,9 +409,8 @@ describe('whole mutator-class lease gate', () => {
     for (const [runtime, toolName] of [
       ['claude', 'Read'],
       ['claude', 'Grep'],
-      ['claude', 'Glob'],
       ['pi', 'read'],
-      ['pi', 'ls'],
+      ['pi', 'grep'],
       ['pi', 'mosaic_context_recover'],
     ] as const) {
       expect(await authorize(socket, sessionId, runtime, toolName)).toMatchObject({

packages/mosaic/src/runtime/detector.ts

@@ -37,7 +37,7 @@ const RUNTIME_DEFS: Record<
     label: 'Pi',
     command: 'pi',
     versionFlag: '--version',
-    installHint: 'curl -fsSL https://pi.dev/install.sh | sh',
+    installHint: 'npm install -g @mariozechner/pi-coding-agent',
   },
 };
 

packages/mosaic/src/stages/finalize-skills.spec.ts

@@ -85,16 +85,16 @@ function makeConfigService(): ConfigService {
 
 describe('finalizeStage — skill installer', () => {
   let tmp: string;
-  let scriptsDir: string;
+  let binDir: string;
   let syncScript: string;
 
   beforeEach(() => {
     tmp = mkdtempSync(join(tmpdir(), 'mosaic-finalize-'));
-    scriptsDir = join(tmp, 'tools', '_scripts');
-    mkdirSync(scriptsDir, { recursive: true });
-    syncScript = join(scriptsDir, 'mosaic-sync-skills');
+    binDir = join(tmp, 'bin');
+    mkdirSync(binDir, { recursive: true });
+    syncScript = join(binDir, 'mosaic-sync-skills');
 
-    // Default: current framework layout has tools/_scripts and succeeds.
+    // Default: script exists and succeeds
     writeFileSync(syncScript, '#!/usr/bin/env bash\necho ok\n', { mode: 0o755 });
     spawnSyncMock.mockReturnValue({ status: 0, stdout: 'ok', stderr: '' });
   });
@@ -156,29 +156,10 @@ describe('finalizeStage — skill installer', () => {
 
     const call = findSkillsSyncCall();
     expect(call).toBeDefined();
-    expect(call![1]).toEqual([join(tmp, 'tools', '_scripts', 'mosaic-sync-skills')]);
     const opts = call![2] as { env?: Record<string, string> };
     expect(opts.env?.['MOSAIC_INSTALL_SKILLS']).toBe('brainstorming:lint:systematic-debugging');
   });
 
-  it('falls back to legacy bin path for pre-migration installs', async () => {
-    rmSync(syncScript);
-    const legacyBinDir = join(tmp, 'bin');
-    mkdirSync(legacyBinDir, { recursive: true });
-    const legacySyncScript = join(legacyBinDir, 'mosaic-sync-skills');
-    writeFileSync(legacySyncScript, '#!/usr/bin/env bash\necho ok\n', { mode: 0o755 });
-
-    const state = makeState(tmp, ['brainstorming']);
-    const p = buildPrompter();
-    const config = makeConfigService();
-
-    await finalizeStage(p, state, config);
-
-    const call = findSkillsSyncCall();
-    expect(call).toBeDefined();
-    expect(call![1]).toEqual([legacySyncScript]);
-  });
-
   it('skips the sync script entirely when no skills are selected', async () => {
     const state = makeState(tmp, []);
     const p = buildPrompter();
@@ -218,9 +199,7 @@ describe('finalizeStage — skill installer', () => {
 
     // spawnSync should NOT have been called for the skills script
     expect(findSkillsSyncCall()).toBeUndefined();
-    expect(p.warn).toHaveBeenCalledWith(
-      expect.stringContaining('tools/_scripts/mosaic-sync-skills'),
-    );
+    expect(p.warn).toHaveBeenCalledWith(expect.stringContaining('not found'));
   });
 
   it('includes skills count in the summary when install succeeds', async () => {

packages/mosaic/src/stages/finalize.ts

@@ -13,22 +13,16 @@ import {
   type SkillSyncResult as ClaudeSkillSyncResult,
 } from '../commands/skill.js';
 
-function frameworkScriptPath(mosaicHome: string, name: string): string {
-  const currentPath = join(mosaicHome, 'tools', '_scripts', name);
-  if (existsSync(currentPath)) return currentPath;
-
-  // Backward-compatible fallback for pre-migration installs that still have bin/.
-  const legacyPath = join(mosaicHome, 'bin', name);
-  if (existsSync(legacyPath)) return legacyPath;
-
-  // Return the current expected path so user-facing errors point at the layout
-  // installed by packages/mosaic/framework/install.sh.
-  return currentPath;
-}
-
-/** Link runtime assets and surface a non-zero install-ordering guard outcome. */
+/**
+ * Link runtime assets. Returns a warning string when the install-ordering
+ * guard (#869 Point-1 C2) reported a degraded outcome — i.e. the
+ * lease-enforcement hooks were NOT wired into ~/.claude/settings.json because
+ * this host could not confirm it can activate them — so the caller can
+ * surface it via `p.warn(...)` instead of it being swallowed by `stdio:
+ * 'pipe'`. Non-fatal either way: the wizard always continues.
+ */
 function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): string | undefined {
-  const script = frameworkScriptPath(mosaicHome, 'mosaic-link-runtime-assets');
+  const script = join(mosaicHome, 'bin', 'mosaic-link-runtime-assets');
   if (!existsSync(script)) return undefined;
   try {
     const result = spawnSync('bash', [script], {
@@ -75,7 +69,7 @@ function syncSkills(mosaicHome: string, selectedSkills: string[]): SyncSkillsRes
     return { success: true, installedCount: 0 };
   }
 
-  const script = frameworkScriptPath(mosaicHome, 'mosaic-sync-skills');
+  const script = join(mosaicHome, 'bin', 'mosaic-sync-skills');
   if (!existsSync(script)) {
     return {
       success: false,
@@ -123,7 +117,7 @@ interface DoctorResult {
 }
 
 function runDoctor(mosaicHome: string): DoctorResult {
-  const script = frameworkScriptPath(mosaicHome, 'mosaic-doctor');
+  const script = join(mosaicHome, 'bin', 'mosaic-doctor');
   if (!existsSync(script)) {
     return { warnings: 0, output: 'mosaic-doctor not found' };
   }
@@ -176,24 +170,11 @@ function setupPath(mosaicHome: string, _p: WizardPrompter): PathAction {
   }
 }
 
-export interface FinalizeStageOptions {
-  /**
-   * Defer the success summary/outro so callers can run downstream readiness
-   * gates (gateway health/bootstrap) before claiming Mosaic is ready.
-   */
-  deferSummary?: boolean;
-}
-
-export interface FinalizeStageResult {
-  showSummary: () => void;
-}
-
 export async function finalizeStage(
   p: WizardPrompter,
   state: WizardState,
   config: ConfigService,
-  options: FinalizeStageOptions = {},
-): Promise<FinalizeStageResult> {
+): Promise<void> {
   p.separator();
 
   const spin = p.spinner();
@@ -288,56 +269,44 @@ export async function finalizeStage(
   // 7. PATH setup
   const pathAction = setupPath(state.mosaicHome, p);
 
-  let summaryShown = false;
-  const showSummary = () => {
-    if (summaryShown) return;
-    summaryShown = true;
+  // 8. Summary
+  const skillsSummary = skillsResult.success
+    ? skillsResult.installedCount > 0
+      ? `${skillsResult.installedCount.toString()} installed`
+      : 'none selected'
+    : `install failed — ${skillsResult.failureReason ?? 'unknown error'}`;
 
-    // 7. Summary
-    const skillsSummary = skillsResult.success
-      ? skillsResult.installedCount > 0
-        ? `${skillsResult.installedCount.toString()} installed`
-        : 'none selected'
-      : `install failed — ${skillsResult.failureReason ?? 'unknown error'}`;
+  const summary: string[] = [
+    `Agent: ${state.soul.agentName ?? 'Assistant'}`,
+    `Style: ${state.soul.communicationStyle ?? 'direct'}`,
+    `Runtimes: ${state.runtimes.detected.join(', ') || 'none detected'}`,
+    `Skills: ${skillsSummary}`,
+    `Config: ${state.mosaicHome}`,
+  ];
 
-    const summary: string[] = [
-      `Agent: ${state.soul.agentName ?? 'Assistant'}`,
-      `Style: ${state.soul.communicationStyle ?? 'direct'}`,
-      `Runtimes: ${state.runtimes.detected.join(', ') || 'none detected'}`,
-      `Skills: ${skillsSummary}`,
-      `Config: ${state.mosaicHome}`,
-    ];
-
-    if (doctorResult.warnings > 0) {
-      summary.push(
-        `Health: ${doctorResult.warnings.toString()} warning(s) — run 'mosaic doctor' for details`,
-      );
-    } else {
-      summary.push('Health: all checks passed');
-    }
-
-    p.note(summary.join('\n'), 'Installation Summary');
-
-    // 8. Next steps
-    const nextSteps: string[] = [];
-    if (pathAction === 'added') {
-      const profilePath = getShellProfilePath();
-      nextSteps.push(`Reload shell: source ${profilePath ?? '~/.profile'}`);
-    }
-    if (state.runtimes.detected.length === 0) {
-      nextSteps.push('Install at least one runtime (claude, codex, or opencode)');
-    }
-    nextSteps.push("Launch with 'mosaic claude' (or codex/opencode)");
-    nextSteps.push('Edit identity files directly in ~/.config/mosaic/ for fine-tuning');
-
-    p.note(nextSteps.map((s, i) => `${(i + 1).toString()}. ${s}`).join('\n'), 'Next Steps');
-
-    p.outro('Mosaic is ready.');
-  };
-
-  if (!options.deferSummary) {
-    showSummary();
+  if (doctorResult.warnings > 0) {
+    summary.push(
+      `Health: ${doctorResult.warnings.toString()} warning(s) — run 'mosaic doctor' for details`,
+    );
+  } else {
+    summary.push('Health: all checks passed');
   }
 
-  return { showSummary };
+  p.note(summary.join('\n'), 'Installation Summary');
+
+  // 9. Next steps
+  const nextSteps: string[] = [];
+  if (pathAction === 'added') {
+    const profilePath = getShellProfilePath();
+    nextSteps.push(`Reload shell: source ${profilePath ?? '~/.profile'}`);
+  }
+  if (state.runtimes.detected.length === 0) {
+    nextSteps.push('Install at least one runtime (claude, codex, or opencode)');
+  }
+  nextSteps.push("Launch with 'mosaic claude' (or codex/opencode)");
+  nextSteps.push('Edit identity files directly in ~/.config/mosaic/ for fine-tuning');
+
+  p.note(nextSteps.map((s, i) => `${(i + 1).toString()}. ${s}`).join('\n'), 'Next Steps');
+
+  p.outro('Mosaic is ready.');
 }

packages/mosaic/src/stages/gateway-config.spec.ts

@@ -136,7 +136,6 @@ describe('gatewayConfigStage', () => {
     delete process.env['MOSAIC_STORAGE_TIER'];
     delete process.env['MOSAIC_DATABASE_URL'];
     delete process.env['MOSAIC_VALKEY_URL'];
-    delete process.env['MOSAIC_GATEWAY_SKIP_NPM_INSTALL'];
   });
 
   afterEach(() => {
@@ -168,75 +167,6 @@ describe('gatewayConfigStage', () => {
     expect(state.gateway?.regeneratedConfig).toBe(true);
   });
 
-  it('installs the gateway package on fresh install when skipInstall is not set', async () => {
-    const p = buildPrompter();
-    const state = makeState('/home/user/.config/mosaic');
-
-    const result = await gatewayConfigStage(p, state, {
-      host: 'localhost',
-      defaultPort: 14242,
-      skipInstall: false,
-    });
-
-    expect(result.ready).toBe(true);
-    expect(daemonState.installPkgCalled).toBe(1);
-  });
-
-  it('honors MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1 and skips the registry install (dev/offline installs)', async () => {
-    process.env['MOSAIC_GATEWAY_SKIP_NPM_INSTALL'] = '1';
-    const p = buildPrompter();
-    const state = makeState('/home/user/.config/mosaic');
-
-    const result = await gatewayConfigStage(p, state, {
-      host: 'localhost',
-      defaultPort: 14242,
-      skipInstall: false,
-    });
-
-    // The source-built global gateway must NOT be overwritten by @latest.
-    expect(result.ready).toBe(true);
-    expect(daemonState.installPkgCalled).toBe(0);
-  });
-
-  it('does not ask for a gateway API key when provider setup was completed with no key', async () => {
-    delete process.env['MOSAIC_ASSUME_YES'];
-    const originalIsTTY = process.stdin.isTTY;
-    Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
-
-    try {
-      const textFn = vi.fn(async (opts: { message: string; initialValue?: string }) => {
-        if (opts.message === 'Gateway port') return opts.initialValue ?? '14242';
-        if (opts.message === 'Web UI hostname (for browser access)') return 'localhost';
-        if (opts.message.includes('API_KEY')) {
-          throw new Error('gateway API key prompt should be skipped');
-        }
-        return '';
-      });
-      const p = buildPrompter({ text: textFn, select: vi.fn().mockResolvedValue('local') });
-      const state = makeState('/home/user/.config/mosaic');
-
-      const result = await gatewayConfigStage(p, state, {
-        host: 'localhost',
-        defaultPort: 14242,
-        skipInstall: true,
-        providerType: 'none',
-      });
-
-      expect(result.ready).toBe(true);
-      expect(textFn).not.toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('API_KEY') }),
-      );
-      const envContents = readFileSync(daemonState.envFile, 'utf-8');
-      expect(envContents).not.toContain('ANTHROPIC_API_KEY=');
-      expect(envContents).not.toContain('OPENAI_API_KEY=');
-    } finally {
-      Object.defineProperty(process.stdin, 'isTTY', {
-        value: originalIsTTY,
-        configurable: true,
-      });
-    }
-  });
-
   it('short-circuits when gateway is already fully installed and user declines rerun', async () => {
     // Pre-populate both files + running daemon + meta with token
     const fs = require('node:fs');

packages/mosaic/src/stages/gateway-config.ts

@@ -294,12 +294,7 @@ export async function gatewayConfigStage(
   }
 
   // Install the gateway npm package on first install or after failure.
-  // MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1 forces a skip even without opts.skipInstall:
-  // used by dev/offline installs where @mosaicstack/gateway is already present
-  // globally (e.g. a build-from-source `install.sh --dev`) and must not be
-  // overwritten by the registry @latest build.
-  const skipNpmInstall = opts.skipInstall || process.env['MOSAIC_GATEWAY_SKIP_NPM_INSTALL'] === '1';
-  if (!skipNpmInstall && !daemonRunning) {
+  if (!opts.skipInstall && !daemonRunning) {
     installGatewayPackage();
   }
 
@@ -511,9 +506,6 @@ async function collectAndWriteConfig(
     if (opts.providerKey) {
       anthropicKey = opts.providerKey;
       p.log(`Using API key from provider setup (${opts.providerType ?? 'unknown'}).`);
-    } else if (opts.providerType === 'none') {
-      anthropicKey = '';
-      p.log('No API key provided during provider setup; skipping gateway API key prompt.');
     } else {
       anthropicKey = await p.text({
         message: 'ANTHROPIC_API_KEY (optional, press Enter to skip)',

packages/mosaic/src/stages/quick-start.ts

@@ -37,7 +37,6 @@ export async function quickStartPath(
 
   // 1. Provider setup (first question)
   await providerSetupStage(prompter, state);
-  state.completedSections?.add('providers');
 
   // Apply sensible defaults for everything else
   state.soul.agentName ??= 'Mosaic';
@@ -58,13 +57,9 @@ export async function quickStartPath(
 
   // Skills (recommended set, no user input in quick mode)
   await skillsSelectStage(prompter, state);
-  state.completedSections?.add('skills');
 
-  // Finalize writes configs/assets/skills, but defer the success summary until
-  // after the gateway health/bootstrap gates complete.
-  const finalizeResult = await finalizeStage(prompter, state, configService, {
-    deferSummary: true,
-  });
+  // Finalize (writes configs, links runtime assets, syncs skills)
+  await finalizeStage(prompter, state, configService);
 
   // Gateway config + bootstrap
   if (!options.skipGateway) {
@@ -77,7 +72,7 @@ export async function quickStartPath(
         portOverride: options.gatewayPortOverride,
         skipInstall: options.skipGatewayNpmInstall,
         providerKey: state.providerKey,
-        providerType: state.providerType,
+        providerType: state.providerType ?? 'none',
       });
 
       if (!configResult.ready || !configResult.host || !configResult.port) {
@@ -85,24 +80,19 @@ export async function quickStartPath(
           prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
           process.exit(1);
         }
-        return;
+      } else {
+        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
+          host: configResult.host,
+          port: configResult.port,
+        });
+        if (!bootstrapResult.completed) {
+          prompter.warn('Admin bootstrap failed — aborting wizard.');
+          process.exit(1);
+        }
       }
-
-      const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
-        host: configResult.host,
-        port: configResult.port,
-      });
-      if (!bootstrapResult.completed) {
-        prompter.warn('Admin bootstrap failed — aborting wizard.');
-        process.exit(1);
-        return;
-      }
-      finalizeResult.showSummary();
     } catch (err) {
       prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
       throw err;
     }
-  } else {
-    finalizeResult.showSummary();
   }
 }

packages/mosaic/src/wizard.ts

@@ -126,11 +126,6 @@ type MenuChoice =
   | 'advanced'
   | 'finish';
 
-function menuSectionKey(section: MenuChoice): MenuSection | null {
-  if (section === 'quick-start' || section === 'finish') return null;
-  return section === 'gateway-config' ? 'gateway' : section;
-}
-
 function menuLabel(section: MenuChoice, completed: Set<MenuSection>): string {
   const labels: Record<MenuChoice, string> = {
     'quick-start': 'Quick Start',
@@ -142,24 +137,14 @@ function menuLabel(section: MenuChoice, completed: Set<MenuSection>): string {
     finish: 'Finish & Apply',
   };
   const base = labels[section];
-  const sectionKey = menuSectionKey(section);
-  if (sectionKey && completed.has(sectionKey)) {
+  const sectionKey: MenuSection =
+    section === 'gateway-config' ? 'gateway' : (section as MenuSection);
+  if (completed.has(sectionKey)) {
     return `${base} [done]`;
   }
   return base;
 }
 
-function skipCompletedMenuChoice(
-  prompter: WizardPrompter,
-  completed: Set<MenuSection>,
-  choice: MenuChoice,
-): boolean {
-  const sectionKey = menuSectionKey(choice);
-  if (!sectionKey || !completed.has(sectionKey)) return false;
-  prompter.log(`${menuLabel(choice, completed)} is already complete; skipping.`);
-  return true;
-}
-
 async function runMenuLoop(
   prompter: WizardPrompter,
   state: WizardState,
@@ -216,25 +201,21 @@ async function runMenuLoop(
         return; // Quick start is a complete flow — exit menu
 
       case 'providers':
-        if (skipCompletedMenuChoice(prompter, completed, choice)) break;
         await providerSetupStage(prompter, state);
         completed.add('providers');
         break;
 
       case 'identity':
-        if (skipCompletedMenuChoice(prompter, completed, choice)) break;
         await agentIntentStage(prompter, state);
         completed.add('identity');
         break;
 
       case 'skills':
-        if (skipCompletedMenuChoice(prompter, completed, choice)) break;
         await skillsSelectStage(prompter, state);
         completed.add('skills');
         break;
 
       case 'gateway-config':
-        if (skipCompletedMenuChoice(prompter, completed, choice)) break;
         // Gateway config is handled during Finish — mark as "configured"
         // after user reviews settings.
         await runGatewaySubMenu(prompter, state, options);
@@ -242,7 +223,6 @@ async function runMenuLoop(
         break;
 
       case 'advanced':
-        if (skipCompletedMenuChoice(prompter, completed, choice)) break;
         await runAdvancedSubMenu(prompter, state);
         completed.add('advanced');
         break;
@@ -330,11 +310,8 @@ async function runFinishPath(
     await skillsSelectStage(prompter, state);
   }
 
-  // Finalize writes configs/assets/skills, but defer the success summary until
-  // after the gateway health/bootstrap gates complete.
-  const finalizeResult = await finalizeStage(prompter, state, configService, {
-    deferSummary: true,
-  });
+  // Finalize (writes configs, links runtime assets, syncs skills)
+  await finalizeStage(prompter, state, configService);
 
   // Gateway stages
   if (!options.skipGateway) {
@@ -345,7 +322,7 @@ async function runFinishPath(
         portOverride: options.gatewayPortOverride,
         skipInstall: options.skipGatewayNpmInstall,
         providerKey: state.providerKey,
-        providerType: state.providerType,
+        providerType: state.providerType ?? 'none',
       });
 
       if (configResult.ready && configResult.host && configResult.port) {
@@ -356,16 +333,12 @@ async function runFinishPath(
         if (!bootstrapResult.completed) {
           prompter.warn('Admin bootstrap failed — aborting wizard.');
           process.exit(1);
-          return;
         }
-        finalizeResult.showSummary();
       }
     } catch (err) {
       prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
       throw err;
     }
-  } else {
-    finalizeResult.showSummary();
   }
 }
 
@@ -401,11 +374,8 @@ async function runHeadlessPath(
   // Skills
   await skillsSelectStage(prompter, state);
 
-  // Finalize writes configs/assets/skills, but defer the success summary until
-  // after the gateway health/bootstrap gates complete.
-  const finalizeResult = await finalizeStage(prompter, state, configService, {
-    deferSummary: true,
-  });
+  // Finalize
+  await finalizeStage(prompter, state, configService);
 
   // Gateway stages
   if (!options.skipGateway) {
@@ -416,31 +386,26 @@ async function runHeadlessPath(
         portOverride: options.gatewayPortOverride,
         skipInstall: options.skipGatewayNpmInstall,
         providerKey: state.providerKey,
-        providerType: state.providerType,
+        providerType: state.providerType ?? 'none',
       });
 
       if (!configResult.ready || !configResult.host || !configResult.port) {
         prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
         process.exit(1);
-        return;
+      } else {
+        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
+          host: configResult.host,
+          port: configResult.port,
+        });
+        if (!bootstrapResult.completed) {
+          prompter.warn('Admin bootstrap failed — aborting wizard.');
+          process.exit(1);
+        }
       }
-
-      const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
-        host: configResult.host,
-        port: configResult.port,
-      });
-      if (!bootstrapResult.completed) {
-        prompter.warn('Admin bootstrap failed — aborting wizard.');
-        process.exit(1);
-        return;
-      }
-      finalizeResult.showSummary();
     } catch (err) {
       prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
       throw err;
     }
-  } else {
-    finalizeResult.showSummary();
   }
 }
 
@@ -461,11 +426,8 @@ async function runKeepPath(
   // Skills
   await skillsSelectStage(prompter, state);
 
-  // Finalize writes configs/assets/skills, but defer the success summary until
-  // after the gateway health/bootstrap gates complete.
-  const finalizeResult = await finalizeStage(prompter, state, configService, {
-    deferSummary: true,
-  });
+  // Finalize
+  await finalizeStage(prompter, state, configService);
 
   // Gateway stages
   if (!options.skipGateway) {
@@ -485,15 +447,11 @@ async function runKeepPath(
         if (!bootstrapResult.completed) {
           prompter.warn('Admin bootstrap failed — aborting wizard.');
           process.exit(1);
-          return;
         }
-        finalizeResult.showSummary();
       }
     } catch (err) {
       prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
       throw err;
     }
-  } else {
-    finalizeResult.showSummary();
   }
 }

tools/install-next-lane.test.sh

@@ -1,222 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-TMP="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-next-install-test-XXXXXX")"
-trap 'rm -rf "$TMP"' EXIT
-
-FAKE_BIN="$TMP/bin"
-HOME_DIR="$TMP/home"
-PREFIX="$TMP/prefix"
-MOSAIC_HOME="$TMP/mosaic"
-STATE="$TMP/state"
-LOG="$TMP/npm.log"
-mkdir -p "$FAKE_BIN" "$HOME_DIR" "$STATE"
-
-cat > "$FAKE_BIN/npm" <<'FAKE_NPM'
-#!/usr/bin/env bash
-set -euo pipefail
-LOG="${MOSAIC_TEST_NPM_LOG:?}"
-STATE="${MOSAIC_TEST_STATE:?}"
-echo "$*" >> "$LOG"
-
-if [[ "$1" == "view" ]]; then
-  case "$2 $3" in
-    "@mosaicstack/mosaic@next version") echo "0.0.49-next.999" ;;
-    "@mosaicstack/gateway@next version") echo "${MOSAIC_TEST_GATEWAY_NEXT_VERSION:-0.0.7-next.999}" ;;
-    "@mosaicstack/mosaic version") echo "0.0.48" ;;
-    *) echo "unexpected npm view: $*" >&2; exit 1 ;;
-  esac
-  exit 0
-fi
-
-if [[ "$1" == "install" ]]; then
-  case "$*" in
-    *"@mosaicstack/[email protected]"*)
-      echo "0.0.49-next.999" > "$STATE/mosaic"
-      ;;
-    *"@mosaicstack/[email protected]"*)
-      if [[ "${MOSAIC_TEST_FAIL_NEXT_GATEWAY_INSTALL:-0}" == "1" ]]; then
-        echo "forced gateway install failure" >&2
-        exit 1
-      fi
-      echo "0.0.7-next.999" > "$STATE/gateway"
-      ;;
-    *"mosaicstack-mosaic-0.0.0-source.tgz"*)
-      echo "0.0.0-source" > "$STATE/mosaic"
-      ;;
-    *"mosaicstack-gateway-0.0.0-source.tgz"*)
-      echo "0.0.0-source" > "$STATE/gateway"
-      ;;
-    *) echo "unexpected npm install: $*" >&2; exit 1 ;;
-  esac
-  exit 0
-fi
-
-if [[ "$1" == "ls" ]]; then
-  cli="$(cat "$STATE/mosaic" 2>/dev/null || true)"
-  gateway="$(cat "$STATE/gateway" 2>/dev/null || true)"
-  node -e '
-    const cli = process.argv[1];
-    const gateway = process.argv[2];
-    const dependencies = {};
-    if (cli) dependencies["@mosaicstack/mosaic"] = { version: cli };
-    if (gateway) dependencies["@mosaicstack/gateway"] = { version: gateway };
-    process.stdout.write(JSON.stringify({ dependencies }));
-  ' "$cli" "$gateway"
-  exit 0
-fi
-
-echo "unexpected npm command: $*" >&2
-exit 1
-FAKE_NPM
-chmod +x "$FAKE_BIN/npm"
-
-cat > "$FAKE_BIN/curl" <<'FAKE_CURL'
-#!/usr/bin/env bash
-set -euo pipefail
-# The fake tar creates the source tree; curl only needs to keep the pipe alive.
-exit 0
-FAKE_CURL
-chmod +x "$FAKE_BIN/curl"
-
-cat > "$FAKE_BIN/tar" <<'FAKE_TAR'
-#!/usr/bin/env bash
-set -euo pipefail
-dest=""
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    -C) dest="$2"; shift 2 ;;
-    *) shift ;;
-  esac
-done
-if [[ -z "$dest" ]]; then
-  echo "fake tar missing -C destination" >&2
-  exit 1
-fi
-mkdir -p "$dest/stack/packages/mosaic" "$dest/stack/apps/gateway"
-FAKE_TAR
-chmod +x "$FAKE_BIN/tar"
-
-cat > "$FAKE_BIN/pnpm" <<'FAKE_PNPM'
-#!/usr/bin/env bash
-set -euo pipefail
-LOG="${MOSAIC_TEST_NPM_LOG:?}"
-echo "pnpm $*" >> "$LOG"
-
-if [[ "$1" == "pack" ]]; then
-  out=""
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --pack-destination) out="$2"; shift 2 ;;
-      *) shift ;;
-    esac
-  done
-  if [[ -z "$out" ]]; then
-    echo "fake pnpm pack missing destination" >&2
-    exit 1
-  fi
-  mkdir -p "$out"
-  case "$PWD" in
-    */apps/gateway) touch "$out/mosaicstack-gateway-0.0.0-source.tgz" ;;
-    */packages/mosaic) touch "$out/mosaicstack-mosaic-0.0.0-source.tgz" ;;
-    *) echo "unexpected pnpm pack cwd: $PWD" >&2; exit 1 ;;
-  esac
-  exit 0
-fi
-
-# install/build commands are no-ops in this harness.
-exit 0
-FAKE_PNPM
-chmod +x "$FAKE_BIN/pnpm"
-
-reset_state() {
-  : > "$LOG"
-  rm -f "$STATE"/*
-}
-
-reset_state
-echo "[test] --next fast path pins resolved package versions"
-OUTPUT="$(
-  HOME="$HOME_DIR" \
-  MOSAIC_HOME="$MOSAIC_HOME" \
-  MOSAIC_PREFIX="$PREFIX" \
-  MOSAIC_NO_COLOR=1 \
-  MOSAIC_TEST_NPM_LOG="$LOG" \
-  MOSAIC_TEST_STATE="$STATE" \
-  PATH="$FAKE_BIN:$PATH" \
-  bash "$ROOT/tools/install.sh" --cli --next --yes --no-auto-launch
-)"
-
-grep -qF 'Installed @next packages: CLI 0.0.49-next.999, gateway 0.0.7-next.999' <<<"$OUTPUT"
-grep -qF 'install -g @mosaicstack/[email protected]' "$LOG"
-grep -qF 'install -g @mosaicstack/[email protected]' "$LOG"
-if grep -qE '^install -g .+@next( |$)' "$LOG"; then
-  echo "expected exact-version installs, found mutable @next install" >&2
-  exit 1
-fi
-if grep -qF 'Downloading source from next' <<<"$OUTPUT"; then
-  echo "fast path unexpectedly fell back to source" >&2
-  exit 1
-fi
-
-reset_state
-echo "[test] fast path failure falls back to source build"
-OUTPUT="$(
-  HOME="$HOME_DIR" \
-  MOSAIC_HOME="$MOSAIC_HOME" \
-  MOSAIC_PREFIX="$PREFIX" \
-  MOSAIC_NO_COLOR=1 \
-  MOSAIC_TEST_NPM_LOG="$LOG" \
-  MOSAIC_TEST_STATE="$STATE" \
-  MOSAIC_TEST_FAIL_NEXT_GATEWAY_INSTALL=1 \
-  PATH="$FAKE_BIN:$PATH" \
-  bash "$ROOT/tools/install.sh" --cli --next --yes --no-auto-launch
-)"
-
-grep -qF 'Fast gateway @next install failed.' <<<"$OUTPUT"
-grep -qF 'Falling back to source build at ref next; --next will not hard-fail on registry issues.' <<<"$OUTPUT"
-grep -qF 'Downloading source from next' <<<"$OUTPUT"
-grep -qF 'Installed from source: CLI 0.0.0-source' <<<"$OUTPUT"
-grep -qF 'install -g @mosaicstack/[email protected]' "$LOG"
-grep -qE 'install -g .*/mosaicstack-gateway-0\.0\.0-source\.tgz' "$LOG"
-grep -qE 'install -g .*/mosaicstack-mosaic-0\.0\.0-source\.tgz' "$LOG"
-[[ "$(cat "$STATE/mosaic")" == "0.0.0-source" ]]
-[[ "$(cat "$STATE/gateway")" == "0.0.0-source" ]]
-
-reset_state
-echo "[test] explicit --ref keeps source lane and avoids @next lookup"
-OUTPUT="$(
-  HOME="$HOME_DIR" \
-  MOSAIC_HOME="$MOSAIC_HOME" \
-  MOSAIC_PREFIX="$PREFIX" \
-  MOSAIC_NO_COLOR=1 \
-  MOSAIC_TEST_NPM_LOG="$LOG" \
-  MOSAIC_TEST_STATE="$STATE" \
-  PATH="$FAKE_BIN:$PATH" \
-  bash "$ROOT/tools/install.sh" --check --cli --next --ref feature-x
-)"
-
-grep -qF 'explicit ref wins, build-from-source' <<<"$OUTPUT"
-if grep -qF '@next version' "$LOG"; then
-  echo "explicit ref should not query @next dist-tags" >&2
-  exit 1
-fi
-
-reset_state
-echo "[test] --check --next warns on mismatched prerelease pipeline suffixes"
-OUTPUT="$(
-  HOME="$HOME_DIR" \
-  MOSAIC_HOME="$MOSAIC_HOME" \
-  MOSAIC_PREFIX="$PREFIX" \
-  MOSAIC_NO_COLOR=1 \
-  MOSAIC_TEST_NPM_LOG="$LOG" \
-  MOSAIC_TEST_STATE="$STATE" \
-  MOSAIC_TEST_GATEWAY_NEXT_VERSION="0.0.7-next.1000" \
-  PATH="$FAKE_BIN:$PATH" \
-  bash "$ROOT/tools/install.sh" --check --cli --next
-)"
-
-grep -qF '@next registry lane incomplete, mismatched, or unreachable; --next would fall back to source.' <<<"$OUTPUT"
-
-echo "[test] installer next lane tests passed"

tools/install.sh

@@ -16,10 +16,6 @@
 #   --framework       Install/upgrade framework only (skip npm CLI)
 #   --cli             Install/upgrade npm CLI only (skip framework)
 #   --ref <branch>    Git ref for framework archive (default: main)
-#   --next            Prerelease lane: try fast npm @next install for CLI +
-#                     gateway from the Gitea registry, then fall back to a
-#                     source build at next if unavailable. Explicit
-#                     --ref/MOSAIC_REF wins and uses the source path.
 #   --dev             Build CLI + gateway FROM SOURCE at --ref instead of the
 #                     registry @latest. Zero registry writes — packs local
 #                     tarballs and installs them globally. Use to test a branch
@@ -35,7 +31,6 @@
 #   MOSAIC_PREFIX       — npm global prefix          (default: ~/.npm-global)
 #   MOSAIC_NO_COLOR     — disable colour             (set to 1)
 #   MOSAIC_REF          — git ref for framework      (default: main)
-#   MOSAIC_NEXT         — equivalent to --next        (set to 1)
 #   MOSAIC_DEV          — equivalent to --dev         (set to 1)
 #   MOSAIC_ASSUME_YES   — equivalent to --yes        (set to 1)
 # ──────────────────────────────────────────────────────────────────────────────
@@ -54,12 +49,7 @@ FLAG_NO_AUTO_LAUNCH=false
 FLAG_YES=false
 FLAG_UNINSTALL=false
 FLAG_DEV=false
-FLAG_NEXT=false
 GIT_REF="${MOSAIC_REF:-main}"
-GIT_REF_EXPLICIT=false
-if [[ -n "${MOSAIC_REF:-}" ]]; then
-  GIT_REF_EXPLICIT=true
-fi
 
 # MOSAIC_ASSUME_YES env var acts the same as --yes
 if [[ "${MOSAIC_ASSUME_YES:-0}" == "1" ]]; then
@@ -71,18 +61,8 @@ if [[ "${MOSAIC_DEV:-0}" == "1" ]]; then
   FLAG_DEV=true
 fi
 
-# MOSAIC_NEXT env var acts the same as --next: fast npm @next install with
-# source fallback from the permanent next integration branch unless
-# MOSAIC_REF/--ref explicitly wins.
-if [[ "${MOSAIC_NEXT:-0}" == "1" ]]; then
-  FLAG_NEXT=true
-  if [[ "$GIT_REF_EXPLICIT" == "false" ]]; then
-    GIT_REF="next"
-  fi
-fi
-
 installer_usage() {
-  printf 'Usage: install.sh [--check] [--framework] [--cli] [--ref <branch>] [--next] [--dev] [--yes|-y] [--no-auto-launch] [--uninstall]\n' >&2
+  printf 'Usage: install.sh [--check] [--framework] [--cli] [--ref <branch>] [--dev] [--yes|-y] [--no-auto-launch] [--uninstall]\n' >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -102,11 +82,9 @@ while [[ $# -gt 0 ]]; do
         exit 2
       fi
       GIT_REF="$2"
-      GIT_REF_EXPLICIT=true
       shift 2
       ;;
     --dev)            FLAG_DEV=true; shift ;;
-    --next)           FLAG_NEXT=true; if [[ "$GIT_REF_EXPLICIT" == "false" ]]; then GIT_REF="next"; fi; shift ;;
     --yes|-y)         FLAG_YES=true; shift ;;
     --no-auto-launch) FLAG_NO_AUTO_LAUNCH=true; shift ;;
     --uninstall)      FLAG_UNINSTALL=true; shift ;;
@@ -118,24 +96,12 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-# Explicit refs represent a request for that exact source tree. Keep --next as
-# a lane selector, but do not install the registry @next package for a different
-# ref than the permanent next branch.
-if [[ "$FLAG_NEXT" == "true" && "$GIT_REF_EXPLICIT" == "true" ]]; then
-  FLAG_DEV=true
-fi
-
-if [[ "$FLAG_YES" == "true" ]]; then
-  export MOSAIC_ASSUME_YES=1
-fi
-
 # ─── constants ────────────────────────────────────────────────────────────────
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 REGISTRY="${MOSAIC_REGISTRY:-https://git.mosaicstack.dev/api/packages/mosaicstack/npm/}"
 SCOPE="${MOSAIC_SCOPE:-@mosaicstack}"
 PREFIX="${MOSAIC_PREFIX:-$HOME/.npm-global}"
 CLI_PKG="${SCOPE}/mosaic"
-GATEWAY_PKG="${SCOPE}/gateway"
 REPO_BASE="https://git.mosaicstack.dev/mosaicstack/stack"
 ARCHIVE_URL="${REPO_BASE}/archive/${GIT_REF}.tar.gz"
 
@@ -150,20 +116,6 @@ fi
 WORK_DIR=""
 EXTRACTED_DIR=""
 
-newest_matching_file() {
-  local dir="$1"
-  local pattern="$2"
-  local matches=()
-  [[ -d "$dir" ]] || return 0
-  shopt -s nullglob
-  # shellcheck disable=SC2206 # Intentional glob expansion for caller-provided file pattern.
-  matches=("$dir"/$pattern)
-  shopt -u nullglob
-  [[ "${#matches[@]}" -gt 0 ]] || return 0
-  # shellcheck disable=SC2012 # Need portable mtime sorting across Linux/macOS.
-  ls -1t "${matches[@]}" 2>/dev/null | head -1
-}
-
 # ─── uninstall path ───────────────────────────────────────────────────────────
 # Shell-level uninstall for when the CLI is broken or not available.
 # Handles: framework directory, npm CLI package, npmrc scope line.
@@ -227,7 +179,7 @@ if [[ "$FLAG_UNINSTALL" == "true" ]]; then
     # Find most recent backup
     backup=""
     if [[ -d "$dir" ]]; then
-      backup="$(newest_matching_file "$dir" "${base}.mosaic-bak-*")"
+      backup="$(ls -1t "$dir/${base}.mosaic-bak-"* 2>/dev/null | head -1 || true)"
     fi
     if [[ -n "$backup" ]] && [[ -f "$backup" ]]; then
       cp "$backup" "$dest"
@@ -283,22 +235,6 @@ fail()  { echo "${R}✖${RESET}  $*" >&2; }
 dim()   { echo "${DIM}$*${RESET}"; }
 step()  { printf '\n%s%s%s\n' "$BOLD" "$*" "$RESET"; }
 
-is_next_registry_lane() {
-  [[ "$FLAG_NEXT" == "true" && "$FLAG_DEV" == "false" && "$GIT_REF" == "next" && "$GIT_REF_EXPLICIT" == "false" ]]
-}
-
-source_ref_details() {
-  if is_next_registry_lane; then
-    echo "ref: next, --next prerelease lane"
-  elif [[ "$FLAG_NEXT" == "true" && "$GIT_REF" == "next" ]]; then
-    echo "ref: next, --next prerelease lane (build-from-source)"
-  elif [[ "$FLAG_NEXT" == "true" ]]; then
-    echo "ref: ${GIT_REF}, --next requested, explicit ref wins"
-  else
-    echo "ref: ${GIT_REF}"
-  fi
-}
-
 # ─── helpers ──────────────────────────────────────────────────────────────────
 
 require_cmd() {
@@ -321,43 +257,10 @@ installed_cli_version() {
   fi
 }
 
-installed_gateway_version() {
-  local json
-  json="$(npm ls -g --depth=0 --json --prefix="$PREFIX" 2>/dev/null)" || true
-  if [[ -n "$json" ]]; then
-    node -e "
-      const d = JSON.parse(process.argv[1]);
-      const v = d?.dependencies?.['${GATEWAY_PKG}']?.version ?? '';
-      process.stdout.write(v);
-    " "$json" 2>/dev/null || true
-  fi
-}
-
 latest_cli_version() {
   npm view "${CLI_PKG}" version --registry="$REGISTRY" 2>/dev/null || true
 }
 
-next_cli_version() {
-  npm view "${CLI_PKG}@next" version --registry="$REGISTRY" 2>/dev/null || true
-}
-
-next_gateway_version() {
-  npm view "${GATEWAY_PKG}@next" version --registry="$REGISTRY" 2>/dev/null || true
-}
-
-next_pipeline_suffix() {
-  printf '%s' "$1" | sed -n 's/.*-next\.\([0-9][0-9]*\)$/\1/p'
-}
-
-next_versions_share_pipeline() {
-  local cli_next="$1"
-  local gateway_next="$2"
-  local cli_pipeline gateway_pipeline
-  cli_pipeline="$(next_pipeline_suffix "$cli_next")"
-  gateway_pipeline="$(next_pipeline_suffix "$gateway_next")"
-  [[ -n "$cli_pipeline" && -n "$gateway_pipeline" && "$cli_pipeline" == "$gateway_pipeline" ]]
-}
-
 version_lt() {
   node -e "
     const a=process.argv[1], b=process.argv[2];
@@ -450,8 +353,8 @@ install_cli_from_source() {
   ( cd "$src/apps/gateway"    && pnpm pack --pack-destination "$out_dir" ) 2>&1 | sed 's/^/  /'
 
   local cli_tgz gw_tgz
-  cli_tgz="$(newest_matching_file "$out_dir" 'mosaicstack-mosaic-*.tgz')"
-  gw_tgz="$(newest_matching_file "$out_dir" 'mosaicstack-gateway-*.tgz')"
+  cli_tgz="$(ls -1t "$out_dir"/mosaicstack-mosaic-*.tgz 2>/dev/null | head -1)"
+  gw_tgz="$(ls -1t "$out_dir"/mosaicstack-gateway-*.tgz 2>/dev/null | head -1)"
 
   if [[ ! -f "$cli_tgz" ]]; then
     fail "CLI tarball was not produced by pnpm pack."
@@ -473,49 +376,6 @@ install_cli_from_source() {
   ok "Installed from source: CLI $(installed_cli_version)"
 }
 
-install_next_cli_from_registry() {
-  local cli_next gateway_next
-  cli_next="$(next_cli_version)"
-  gateway_next="$(next_gateway_version)"
-
-  if [[ -z "$cli_next" ]]; then
-    warn "${CLI_PKG}@next is unavailable from $REGISTRY."
-    return 1
-  fi
-  if [[ -z "$gateway_next" ]]; then
-    warn "${GATEWAY_PKG}@next is unavailable from $REGISTRY."
-    return 1
-  fi
-
-  if ! next_versions_share_pipeline "$cli_next" "$gateway_next"; then
-    warn "@next CLI/gateway versions do not share a pipeline suffix (${cli_next}, ${gateway_next})."
-    return 1
-  fi
-
-  info "Installing ${CLI_PKG}@${cli_next} from registry…"
-  if ! npm install -g "${CLI_PKG}@${cli_next}" --prefix="$PREFIX" 2>&1 | sed 's/^/  /'; then
-    warn "Fast CLI @next install failed."
-    return 1
-  fi
-
-  info "Installing ${GATEWAY_PKG}@${gateway_next} from registry…"
-  if ! npm install -g "${GATEWAY_PKG}@${gateway_next}" --prefix="$PREFIX" 2>&1 | sed 's/^/  /'; then
-    warn "Fast gateway @next install failed."
-    return 1
-  fi
-
-  local installed_cli installed_gateway
-  installed_cli="$(installed_cli_version)"
-  installed_gateway="$(installed_gateway_version)"
-  if [[ "$installed_cli" != "$cli_next" || "$installed_gateway" != "$gateway_next" ]]; then
-    warn "Installed @next versions did not match resolved versions (CLI: ${installed_cli:-missing}, gateway: ${installed_gateway:-missing})."
-    return 1
-  fi
-
-  export MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1
-  ok "Installed @next packages: CLI ${installed_cli}, gateway ${installed_gateway}"
-}
-
 # ─── preflight ────────────────────────────────────────────────────────────────
 
 require_cmd node
@@ -549,7 +409,7 @@ if [[ "$FLAG_FRAMEWORK" == "true" ]]; then
   else
     dim "  Installed: (none)"
   fi
-  dim "  Source:    ${REPO_BASE} ($(source_ref_details))"
+  dim "  Source:    ${REPO_BASE} (ref: ${GIT_REF})"
   echo ""
 
   if [[ "$FLAG_CHECK" == "true" ]]; then
@@ -616,12 +476,8 @@ if [[ "$FLAG_CLI" == "true" ]]; then
   fi
 
   CURRENT="$(installed_cli_version)"
-  NEXT_GATEWAY=""
   if [[ "$FLAG_DEV" == "true" ]]; then
     LATEST=""
-  elif is_next_registry_lane; then
-    LATEST="$(next_cli_version)"
-    NEXT_GATEWAY="$(next_gateway_version)"
   else
     LATEST="$(latest_cli_version)"
   fi
@@ -633,19 +489,7 @@ if [[ "$FLAG_CLI" == "true" ]]; then
   fi
 
   if [[ "$FLAG_DEV" == "true" ]]; then
-    dim "  Source:    ${REPO_BASE} ($(source_ref_details), build-from-source)"
-  elif is_next_registry_lane; then
-    if [[ -n "$LATEST" ]]; then
-      dim "  Next CLI:  ${CLI_PKG}@${LATEST}"
-    else
-      dim "  Next CLI:  (registry @next unreachable)"
-    fi
-    if [[ -n "$NEXT_GATEWAY" ]]; then
-      dim "  Next GW:   ${GATEWAY_PKG}@${NEXT_GATEWAY}"
-    else
-      dim "  Next GW:   (registry @next unreachable)"
-    fi
-    dim "  Fallback:  ${REPO_BASE} (ref: next, build-from-source)"
+    dim "  Source:    ${REPO_BASE} (ref: ${GIT_REF}, build-from-source)"
   elif [[ -n "$LATEST" ]]; then
     dim "  Latest:    ${CLI_PKG}@${LATEST}"
   else
@@ -656,12 +500,6 @@ if [[ "$FLAG_CLI" == "true" ]]; then
   if [[ "$FLAG_CHECK" == "true" ]]; then
     if [[ "$FLAG_DEV" == "true" ]]; then
       info "Dev mode: installed version is ${CURRENT:-(none)} (no registry comparison)."
-    elif is_next_registry_lane; then
-      if [[ -n "$LATEST" && -n "$NEXT_GATEWAY" ]] && next_versions_share_pipeline "$LATEST" "$NEXT_GATEWAY"; then
-        ok "@next registry lane available: ${CLI_PKG}@${LATEST}, ${GATEWAY_PKG}@${NEXT_GATEWAY}."
-      else
-        warn "@next registry lane incomplete, mismatched, or unreachable; --next would fall back to source."
-      fi
     elif [[ -z "$LATEST" ]]; then
       warn "Could not reach registry."
     elif [[ -z "$CURRENT" ]]; then
@@ -678,23 +516,6 @@ if [[ "$FLAG_CLI" == "true" ]]; then
     ensure_monorepo
     install_cli_from_source
 
-    # PATH check for npm prefix
-    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
-      warn "$PREFIX/bin is not on your PATH"
-      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
-    fi
-  elif is_next_registry_lane; then
-    info "Next mode — trying fast npm @next install from ${REGISTRY}…"
-    if install_next_cli_from_registry; then
-      :
-    else
-      warn "Falling back to source build at ref ${GIT_REF}; --next will not hard-fail on registry issues."
-      unset MOSAIC_GATEWAY_SKIP_NPM_INSTALL
-      ensure_monorepo
-      install_cli_from_source
-      export MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1
-    fi
-
     # PATH check for npm prefix
     if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
       warn "$PREFIX/bin is not on your PATH"
@@ -803,7 +624,7 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
       local base dir backup_path backup_val
       base="$(basename "$dest")"
       dir="$(dirname "$dest")"
-      backup_path="$(newest_matching_file "$dir" "${base}.mosaic-bak-*")"
+      backup_path="$(ls -1t "$dir/${base}.mosaic-bak-"* 2>/dev/null | head -1 || true)"
       if [[ -n "$backup_path" ]]; then
         backup_val="\"$backup_path\""
       else
@@ -828,7 +649,7 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
     NPMRC_LINES_JSON="[\"$MANIFEST_SCOPE_LINE\"]"
   fi
 
-  if node -e "
+  node -e "
     const fs = require('fs');
     const path = require('path');
     const p = process.argv[1];
@@ -853,11 +674,9 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
     "$MANIFEST_CLI_VERSION" \
     "$MANIFEST_FW_VERSION" \
     "$NPMRC_LINES_JSON" \
-    "$RUNTIME_COPIES" 2>/dev/null; then
-    ok "Install manifest written: $MANIFEST_PATH"
-  else
-    warn "Could not write install manifest (non-fatal)"
-  fi
+    "$RUNTIME_COPIES" 2>/dev/null \
+    && ok "Install manifest written: $MANIFEST_PATH" \
+    || warn "Could not write install manifest (non-fatal)"
 
   echo ""
   ok "Done."