Merge pull request 'chore(sync): merge main → next (B1) — resolve 8 conflicts, restore next current' (#1041) from sync/b1-main-into-next into next

chore(sync): merge main → next (B1) — restore next current, resolve 8 conflicts (#1041)

Brings next current with main incl the RM-03 guard fix (482/5); preserves next's 10 in-flight commits. Closes #1040.

.woodpecker/publish.yml

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

README.md

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

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

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

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

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

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

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

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

@@ -23,7 +23,10 @@ export class CommandExecutorService {
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(SystemOverrideService) private readonly systemOverride: SystemOverrideService,
     @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
-    @Inject(COMMANDS_REDIS) private readonly redis: QueueHandle['redis'],
+    // On Local tier COMMANDS_REDIS is null — provider login caching is skipped.
+    @Optional()
+    @Inject(COMMANDS_REDIS)
+    private readonly redis: QueueHandle['redis'] | null,
     @Inject(BRAIN) private readonly brain: Brain,
     @Optional()
     @Inject(forwardRef(() => ReloadService))
@@ -443,6 +446,7 @@ 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(
@@ -451,6 +455,7 @@ export class CommandExecutorService {
             'EX',
             300,
           );
+        }
         return {
           command: 'provider',
           success: true,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/PRD.md

@@ -146,36 +146,6 @@ lands. M0 consists only of these normative requirements, the complete task DAG,
 documentation IA checklist, and the legacy example/profile disposition inventory. Subsequent cards
 are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
 
-### Fleet git identity launch propagation (#1043)
-
-#### Problem and objective
-
-A fleet seat can have a registered per-agent Git credential while its launched runtime process lacks
-`MOSAIC_GIT_IDENTITY`. The credential resolver then cannot select the seat identity reliably, which
-blocks repository operations on fail-closed estates and can fall through to an unrelated identity on
-estates where that refusal is not active. The objective is to make Git identity a deterministic,
-roster-derived part of the generated launch projection and prove it reaches the launched process.
-
-#### Normative requirements
-
-1. `FGI-REQ-01`: Every generated fleet agent projection SHALL declare
-   `MOSAIC_GIT_IDENTITY=<MOSAIC_AGENT_NAME>`; a differing or unsafe identity SHALL fail closed before
-   tmux launch.
-2. `FGI-REQ-02`: The clean `/usr/bin/env -i` pane boundary SHALL pass every variable declared by the
-   generated projection, including `MOSAIC_GIT_IDENTITY`, to the launched runtime process.
-3. `FGI-REQ-03`: A behavioral integration test SHALL set-compare the complete generated projection
-   against the launched process environment. Source-text/string-presence assertions are insufficient.
-4. `FGI-REQ-04`: Verification SHALL include RED-first evidence and a delete-the-subject mutation that
-   removes Git-identity pane propagation and makes the behavioral test fail.
-
-#### Acceptance criteria
-
-1. `AC-FGI-01`: A launched seat process contains every key/value pair declared by its generated
-   environment projection, including the roster-derived Git identity.
-2. `AC-FGI-02`: Missing, unsafe, or split Git identity is rejected before a tmux session is created.
-3. `AC-FGI-03`: Focused launcher and generated-environment tests, repository quality gates,
-   independent review, and the required RED/green/R7 evidence are recorded before push.
-
 ---
 
 ## Exact Cross-Harness Fleet Communications Contract (#766)

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

@@ -0,0 +1,63 @@
+# 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/fleet/FLEET-LAUNCH.md

@@ -6,8 +6,8 @@ Generated environment files are rebuildable projections, not an operator-editabl
 ## Launch chain
 
 | Layer               | Responsibility                                                                                                                  |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket; Git identity is derived from the exact agent name. |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
 | Projection writer   | Renders deterministic fleet/agents/<name>.env.generated from the roster.                                                        |
 | Optional local data | Reads a strict, data-only fleet/agents/<name>.env.local; it cannot shadow generated keys.                                       |
 | systemd             | Starts the launcher with env -i and fixed bootstrap data. It does not preload either environment file.                          |
@@ -24,7 +24,6 @@ secret-like key names, duplicate keys, comments, quoted/export syntax, and unsaf
 
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
-MOSAIC_GIT_IDENTITY=<roster name>
 MOSAIC_AGENT_CLASS=<roster class>
 MOSAIC_AGENT_RUNTIME=<roster runtime>
 MOSAIC_AGENT_MODEL=<roster model hint>
@@ -34,10 +33,8 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
 
-`MOSAIC_GIT_IDENTITY` is not independently configurable: it must equal `MOSAIC_AGENT_NAME`, preventing
-split runtime and repository identity authority. The generated launch contract supports `claude`,
-`codex`, `opencode`, and `pi`. mosaic fleet add rejects another runtime before it writes the roster or
-modifies generated, local, or quarantine state.
+The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. mosaic fleet add
+rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
 The legacy dogfood stub remains an observability-only canary on its separate `mosaic-factory` socket;
 it has no generated-launch adapter and cannot be added through this path.
 

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

@@ -3,12 +3,11 @@
 The launcher consumes validated data, not shell configuration.
 
 1. Read and validate the canonical roster.
-2. Render deterministic <name>.env.generated data from that roster, including `MOSAIC_GIT_IDENTITY` derived exactly from the roster agent name.
+2. Render deterministic <name>.env.generated data from that roster.
 3. Parse optional <name>.env.local through a strict allowlist.
 4. Reject generated-key shadowing, unknown or sensitive-looking keys, unsafe paths/values, duplicates, malformed lines, shell syntax, and command overrides.
-5. Reject a Git identity that is unsafe or differs from the generated agent name.
-6. Derive the runtime command from validated runtime/model/reasoning data and pass every generated projection entry through the clean process environment boundary.
-7. Target only the exact configured tmux socket and roster session after ownership checks.
+5. Derive the runtime command from validated runtime/model/reasoning data.
+6. Target only the exact configured tmux socket and roster session after ownership checks.
 
 ## File precedence and ownership
 

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

@@ -35,7 +35,6 @@ values, credential material, or command text.
 
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
-MOSAIC_GIT_IDENTITY=<roster name>
 MOSAIC_AGENT_CLASS=<roster class>
 MOSAIC_AGENT_RUNTIME=<roster runtime>
 MOSAIC_AGENT_MODEL=<roster model hint>
@@ -45,9 +44,8 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
 
-`MOSAIC_GIT_IDENTITY` is derived from and must equal `MOSAIC_AGENT_NAME`; it is not a separate
-operator-controlled identity authority. The generated launch contract supports only `claude`, `codex`,
-`opencode`, and `pi`. fleet add uses that same runtime authority and rejects any other runtime before it writes the roster or changes
+The generated launch contract supports only `claude`, `codex`, `opencode`, and `pi`. fleet add
+uses that same runtime authority and rejects any other runtime before it writes the roster or changes
 projection, local, or quarantine files. The legacy dogfood stub on its separate `mosaic-factory`
 socket remains an observability canary; it has no generated-launch adapter and cannot be added through
 this projection path.

docs/guides/dev-guide.md

@@ -195,6 +195,17 @@ 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,8 +175,18 @@ 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`. Flags for
-non-interactive use:
+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:
 
 ```bash
 --yes               # Accept all defaults

docs/scratchpads/1019-zero-timeout-harness.md

@@ -1,71 +0,0 @@
-# #1019 — Zero-timeout queue-guard harness race
-
-- **Issue:** #1019 (parent status remains `believed-fixed, pending jarvis validation`; do not close)
-- **Branch:** `fix/1019-ci-queue-timeout-harness`
-- **Owner:** `be-coder-08`
-- **Base:** `origin/main` at `5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc`
-- **Charter:** `/home/hermes/agent-work/tl-mosaic/CHARTER-1019-HARNESS-FIX.md`
-
-## Objective
-
-Make `test-ci-queue-wait-tristate.sh` deterministic without changing any asserted outcome. Remove the indiscriminate zero-timeout race, require every status-classification case to prove the provider was observed, and prove the harness-controlled virtual clock is active.
-
-## Scope
-
-- In scope: `packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` only, plus this evidence scratchpad.
-- Out of scope: guard parsers, D2/D3 behavior, installer/reseed staleness, PR #1060, and issue closure.
-
-## Acceptance criteria
-
-1. RED deterministically reproduces deadline pre-emption before the provider call.
-2. Every case that intends status classification positively proves provider observation.
-3. Pending observes `pending` before deterministic virtual-time expiration.
-4. The virtual clock has a positive interception control; a broken-clock mutant makes the suite red.
-5. The exact CI-base image passes the final harness repeatedly with zero failures.
-6. Baseline gates, independent code/security review, exact-head CI, and coordinator-authorized squash merge pass.
-
-## Plan
-
-1. Add deterministic RED instrumentation for the known merge/provider-unreachable pre-emption.
-2. Replace global `-t 0` with a nonzero timeout interpreted under an event-driven virtual clock; stub sleep without wall waiting.
-3. Add provider-observation and virtual-clock positive controls without changing outcome assertions.
-4. Run focused shell checks, repeat in exact CI-base image, baseline gates, and independent reviews.
-5. Commit with both identity layers, queue-guard plus direct Woodpecker terminal-state verification, push, self-post PR, verify poster/head/CI, obtain coordinator merge authorization, then squash merge without closing #1019.
-
-## Budget
-
-- No explicit token cap supplied. Keep scope to one harness file and one scratchpad; stop/report at the charter's 60% context gate.
-
-## Evidence
-
-- RED, deterministic pre-provider expiry: `evidence/1019-harness-fix/red-pre-provider-expiry.log` — rc 1; merge/provider-unreachable got rc 124 instead of 75, omitted CANNOT_ASSERT, did not observe the status provider, and wrote no additional audit record (four named failures).
-- GREEN host focused harness: `evidence/1019-harness-fix/green-host.log` — rc 0, all outcome classes passed.
-- Load-bearing clock negative control: a temporary same-directory mutant replaced the virtual `date` body with `/bin/date`; `evidence/1019-harness-fix/red-clock-not-intercepted.log` — rc 1 with named `virtual clock interception did not run` failures. The mutant file was removed after the run.
-- Exact CI-base repeat: `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`, repository mounted read-only, harness work under container `/tmp`; `evidence/1019-harness-fix/ci-image-repeat/summary.log` — **100 pass / 0 fail / 100 total**.
-- Synchronization design: provider-status observation creates the event marker; virtual time is 1000 before the event and 1002 afterward. Pending alone reaches the stubbed no-op sleep and a post-observation deadline check. `-t 1` is uniquely load-bearing because removing it restores the 900-second default deadline at virtual time 1900, which 1002 does not cross. The numeric timeout is subject semantics under virtual time, not a wall-clock synchronization duration.
-
-## Review remediation — semantic timeout vs. liveness bound
-
-Security review found that virtual time remained at 1000 forever before provider observation and stubbed sleep never waited. A regression looping before the status endpoint—or blocking in the first provider call—therefore could prevent `run_guard` from returning, so the post-return provider assertion could never fire.
-
-**General rule:** A timeout usually serves two purposes: semantics and liveness. Removing wall time from semantic synchronization can silently remove the only independent hang bound. Preserve deterministic virtual time for subject semantics, but provide a separately implemented real-clock liveness watchdog and prove that watchdog fires.
-
-Remediation:
-
-- Every guard subject invocation is launched by absolute `/usr/bin/python3` in a new session. Python's internal monotonic `wait(timeout=...)` provides real-clock liveness independently of PATH; expiry kills the entire isolated process group, so neither PATH-front shims nor a blocked provider descendant can retain the capture pipe.
-- Watchdog expiry returns distinct harness rc 90 plus `FAIL HANG watchdog`, separate from subject timeout rc 124.
-- A first attempt using absolute `/usr/bin/timeout -s KILL` passed on GNU coreutils but failed in the exact Alpine CI-base image: BusyBox killed the immediate wrapper while the guard/provider descendants survived and retained the command-substitution pipe. The process-group kill is therefore required behavior, not portability polish.
-- A committed positive control hangs the branch-provider stub before the status endpoint. It must terminate through the watchdog, emit the hang-specific diagnostic, return rc 90, and prove the status provider was never reached.
-- RED before remediation: a temporary ordinary-success mutant hung before provider observation; only an external control could kill the suite (rc 137), and there was no internal hang-specific diagnostic (`red-watchdog-absent.log`).
-- The watchdog mutant/control is load-bearing: removing the internal watchdog leaves the control unable to produce its required rc 90 and diagnostic.
-
-Post-review evidence:
-
-- Host focused harness with process-group watchdog: rc 0 (`green-watchdog-process-group-host.log`).
-- Exact Alpine CI-base focused harness with process-group watchdog: rc 0 (`green-watchdog-ci-image.log`).
-- Hanging ordinary-success mutant: suite rc 1; success returned rc 90, emitted `FAIL HANG watchdog`, and loudly reported that provider/clock observation did not occur (`red-watchdog-fires.log`).
-- Removed-`-t 1` mutant: suite rc 1; pending was terminated by the watchdog instead of producing `ASSERTED_NOT_READY`, proving the explicit timeout is load-bearing (`red-timeout-argument-removed.log`).
-
-## 60% context hold
-
-Stopped before baseline/review/commit as required by the charter. Remaining: inspect final diff, shell/static/baseline gates, independent code/security review, remediation if any, identity-bound commit/trailer verification, mandatory queue guard plus direct terminal Woodpecker `mosaic` enumeration, push, self-posted PR/provider poster read-back, exact-head terminal-green CI, coordinator merge authorization, squash merge, main CI verification, and leave #1019 unclosed as `believed-fixed, pending jarvis validation`.

docs/scratchpads/1043-pane-git-identity.md

@@ -1,229 +0,0 @@
-# #1043 — Fleet pane git-identity propagation
-
-## Objective
-
-Ensure a fleet seat's launched runtime process receives its roster-derived `MOSAIC_GIT_IDENTITY`, and lock the complete generated-environment propagation boundary with an enumerated set comparison.
-
-## Tracking
-
-- External issue: `mosaicstack/stack#1043`
-- Branch: `fix/1043-pane-git-identity`
-- Coordinator: `tl-mosaic`
-- `docs/TASKS.md`: read-only by project worker contract; not modified.
-
-## Constraints
-
-- RED-first bug reproducer is mandatory.
-- R7 delete-the-subject mutation must turn the behavioral test red.
-- Assert launched-process environment, not source text.
-- One push only; do not poll CI after push.
-- Run the CI queue guard immediately before push and report its `state=` line as state, not evidence.
-- Do not modify a live host launcher or obtain/copy another credential.
-- Self-post the PR, verify provider attribution, then stop.
-- Final status wording: `believed-fixed, pending jarvis validation`.
-
-## Scope inventory
-
-Re-derived against `origin/main` at `85d2108e`:
-
-- Launch consumer: `packages/mosaic/framework/tools/fleet/start-agent-session.sh`
-- Behavioral launch test: `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
-- Generated-environment contract/parser: `packages/mosaic/src/fleet/generated-env-boundary.ts`
-- Roster projection producers:
-  - `packages/mosaic/src/commands/fleet.ts`
-  - `packages/mosaic/src/fleet/fleet-reconciler.ts`
-  - `packages/mosaic/src/fleet/fleet-agent-crud.ts`
-  - `packages/mosaic/src/fleet/v1-v2-migration.ts`
-- Contract and producer tests discovered by repository search.
-- Generated-environment operator/developer docs and their executable documentation contract test.
-
-Discrepancy sent to `tl-mosaic`: current main no longer contains the charter's `PANE_SHELL_SNIPPET`; #772 replaced it with an `/usr/bin/env -i` argv launch boundary, and current generated projections do not declare git identity. Code-read inventory is **NOT MEASURED** behavior.
-
-## Plan
-
-1. Add the process-environment set-comparison regression first and record RED.
-2. Add roster-derived `MOSAIC_GIT_IDENTITY=<agent name>` to the complete generated projection contract.
-3. Validate identity syntax and equality with `MOSAIC_AGENT_NAME`; pass it through the clean pane environment.
-4. Update affected projection tests and generated-environment docs.
-5. Run focused and baseline gates.
-6. Perform R7 by deleting the pane propagation entry, prove RED, restore, and prove GREEN.
-7. Run independent review, remediate, commit, queue guard, one push, self-post PR, verify provider attribution, and stop without CI polling.
-
-## Budget
-
-No explicit token cap was provided. Working cap: one narrow logical unit, no dependency installation unless existing tooling requires it, no unrelated refactor.
-
-## Evidence log
-
-### TDD and mutation evidence
-
-- RED-first, repository launcher: `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` exited 64 on pre-fix source with `code=unknown-key key=MOSAIC_GIT_IDENTITY`. The generated seat could not launch with the required declared identity.
-- GREEN: the same repository launcher test emitted `ok - start-agent-session generated environment boundary`.
-- R7 delete-the-subject: removed only `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"` from the repository launch array; the same test exited 1 with `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
-- R7 restoration: restored that launch entry; the same test returned green.
-- Launcher under test is explicitly `packages/mosaic/framework/tools/fleet/start-agent-session.sh` through the test's `$START`, **not** the stale installed host copy.
-
-### Situational and focused tests
-
-- Repository launcher boundary: green, including set comparison of all nine generated projection entries and fail-before-tmux cases for missing, unsafe, mismatched, and local-shadow Git identity.
-- Fleet systemd launcher integration: `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` — green.
-- Focused Mosaic Vitest set: 6 files, 311 tests — green.
-- `bash -n` on changed shell files — green.
-- `git diff --check` — green.
-
-### Baseline gates
-
-- `pnpm typecheck` — 45/45 tasks green.
-- `pnpm lint` — 25/25 tasks green.
-- `pnpm format:check` — green.
-- `pnpm test:checkout` — green.
-- Repository-wide Vitest under a hermetic current-version npm prefix: Mosaic 81/81 files and 1510/1510 tests green; other workspace test tasks shown green before the framework-shell phase.
-- Canonical `pnpm test` is not fully green on this host for unrelated environment-sensitive gates:
-  1. the first two runs exposed the globally installed Mosaic 0.0.48 update banner in three CLI smoke tests expecting empty stderr;
-  2. after isolating that global-version input, the framework wake assertion aborted at the known `#973` Bash `BASH_LINENO` convention check (exit 97; observed `[3 5]`, expected `[3 4]`).
-  No tests were weakened or bypassed; focused changed-surface tests are green. CI remains the canonical clean-environment result and is intentionally not polled after push per charter.
-
-### Independent review
-
-- Codex code review first pass: request changes for missing shell rejection-path coverage.
-- Remediation: added table-driven missing/unsafe/mismatch/local-shadow launcher cases, each asserting no tmux call.
-- Codex code re-review: **approve**, no findings, confidence 0.88.
-- Codex security review: risk `none`, no findings, confidence 0.97.
-
-### Acceptance criteria mapping
-
-| Acceptance criterion | Evidence |
-| --- | --- |
-| AC-FGI-01: launched process receives every generated key/value | Repository launcher process-environment `comm -23` set comparison; GREEN and R7 RED evidence above |
-| AC-FGI-02: missing, unsafe, or split identity fails before tmux | Table-driven shell cases plus TypeScript generated-boundary tests |
-| AC-FGI-03: focused/baseline/review evidence recorded | Commands and review outcomes above; host-sensitive full-suite limitations stated explicitly |
-
-### Documentation checklist
-
-- PRD updated with #1043 requirements and acceptance criteria.
-- Fleet launch runbook, generated-env concept, and generated-env reference updated.
-- No API/OpenAPI, sitemap, user publishing target, deployment, or external docs publication change applies.
-- `docs/TASKS.md` remains unmodified per its single-writer project contract.
-
-## Round 2 — PR #1073 review 97 remediation
-
-### Review blocker
-
-The launched-process suite was signed-excluded from CI enumeration. Manual GREEN/R7 evidence therefore did not prove a PR workflow could detect regression.
-
-### RED-first and canonical wiring
-
-1. Removed the suite's signed exclusion before adding a CI execution path.
-2. `check-test-enumeration.sh` went RED with exact `UNENUMERATED` output for `test-start-agent-session.sh`: population 49, enumerated 30, excluded 18.
-3. Added both `framework/tools/fleet/test-start-agent-session.sh` and `framework/systemd/user/test-fleet-units.sh` to `@mosaicstack/mosaic`'s canonical `test:framework-shell` chain.
-4. The guard returned GREEN: population 49, enumerated 32, excluded 18, surfaces 45. The systemd suite is outside the guard's tools-only population but now has the same explicit canonical execution disposition.
-
-### Workflow-level R7
-
-- Deleted only the pane launch entry `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"`.
-- Ran the exact `.woodpecker/ci.yml` test-step command, `pnpm test`, with only a temporary PATH-scoped npm shim reporting the checkout's current 0.0.49 version so the unrelated global 0.0.48 banner could not preempt the shell chain.
-- Result: exit 1 at `@mosaicstack/mosaic#test`, with the enumeration guard GREEN followed by `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
-- Restored the launch entry. The canonical `test:framework-shell` chain then reached both newly wired suites and printed both GREEN markers before the known unrelated #973 host-only `BASH_LINENO` abort.
-- An actual provider PR workflow on the intentionally broken mutant is **NOT MEASURED**: the one-push constraint forbids pushing a red mutant and then a repaired head. Local execution proves the exact PR workflow command and dependency chain go RED on the subject deletion; CI on the repaired pushed head remains canonical.
-
-### Workflow population
-
-- **DEFINED:** 3 workflows (`ci.yml`, `ci-image.yml`, `publish.yml`).
-- **ELIGIBLE for `pull_request`:** 1/3 (`ci.yml`), based on top-level `when:` clauses.
-- **REPORTED:** Round-1 exact-head provider read reported 1/1 eligible context (`ci/woodpecker/pr/ci`). Post-remediation-head reported count is **NOT MEASURED** by this seat because CI polling is prohibited; workflow definitions and eligibility did not change.
-
-### Independent remediation review
-
-- First Round-2 review identified a CI-image blocker: the newly wired launcher suite used Perl, which the Alpine CI base does not install.
-- Replaced the suite's three Perl-only fixture mutations with POSIX/BusyBox-compatible `sed -i` substitutions; production behavior and assertions are unchanged.
-- Codex re-review: **APPROVE**, confidence 0.93, no findings.
-
-### Vitest denominator reconciliation
-
-The PR's `311/311` is correct for its explicitly named six-file command at both the original and remediation worktrees:
-
-- generated environment boundary: 24
-- fleet documentation: 23
-- Tess service profile: 6
-- fleet regen command: 27
-- fleet agent CRUD command: 22
-- fleet command: 209
-- total: **311**
-
-Review 97 reported 312/312 without naming its six files. That is a different or miscounted population and cannot replace the command-scoped 311 denominator; the PR follow-up will name the exact files and arithmetic.
-
-## Round 3 — Alpine stale-marker portability
-
-### Objective and plan
-
-- Replace the GNU-only relative-date fixture with a deterministic POSIX/BusyBox timestamp while preserving the required stale-marker assertion.
-- Re-run the launcher suite in the canonical `ci-base:latest` Alpine image, then run applicable repository gates and independent review.
-- Update the PR body to name the repeated GNU-host/Alpine-CI portability pattern, run the mandatory queue guard, push once, verify provider attribution, and stop without CI polling.
-- Working budget: 8K tokens; scope is one fixture line plus delivery evidence. No production behavior changes.
-
-### RED-first evidence
-
-Before the fix, the canonical CI image command
-`docker run --rm -v "$PWD:/work" -w /work git.mosaicstack.dev/mosaicstack/stack/ci-base:latest bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
-exited 1 at the stale-marker setup with exact BusyBox output
-`touch: invalid date '10 seconds ago'`. The prior fresh-marker assertions had already executed, matching pipeline 2233's failure location.
-
-### Root cause and fix
-
-The test used GNU `touch -d` relative-date parsing although the PR workflow runs on Alpine/BusyBox. The fixture now uses POSIX `touch -t 200001010000.00`, a fixed timestamp that is unconditionally stale; the stale assertion remains mandatory and was not made tolerant of missing timestamp metadata.
-
-### Structural pattern
-
-This is the third GNU-host/Alpine-CI portability defect in the lane: GNU `grep` multi-match counting, Perl-only fixture mutation, and GNU `touch -d` date parsing. The repeated cause is shell suites authored on a GNU host but executed in an Alpine CI image; durable prevention belongs in CI-image execution or portability lint, not assertion weakening.
-
-### GREEN and quality evidence
-
-- Focused launcher suite in `ci-base:latest`: exit 0, `ok - start-agent-session generated environment boundary`.
-- Canonical test step in `ci-base:latest` with the pipeline's `pgvector/pgvector:pg17` service, readiness check, migration, and `pnpm test`: exit 0; 46/46 Turbo tasks; Mosaic 81/81 files and 1510/1510 tests; Gateway 57 passed/5 skipped files and 629 passed/11 skipped tests; enumeration 49 population / 32 enumerated / 18 signed exclusions / 45 named surfaces.
-- The first image-only `pnpm test` attempt lacked the pipeline PostgreSQL service and failed only on connection refusal after the launcher suite was GREEN. The rerun supplied the canonical service precondition and passed.
-- Canonical-image baseline: typecheck 45/45 tasks, lint 25/25 tasks, format check GREEN; `git diff --check` GREEN.
-- Independent Codex code review: APPROVE, confidence 0.96, 2/2 Round-3 files, no findings.
-- Independent Codex security review: risk none, confidence 0.99, 2/2 Round-3 files, no findings.
-
-### Re-derived inventory and denominators
-
-- Round-3 git delta: **2/2 files** — launcher suite and task scratchpad; 25 insertions / 1 deletion before evidence finalization.
-- Full PR path inventory against `origin/main` at `85d2108e`: **19/19 changed paths**; Round 3 adds no new PR path.
-- Workflow definition population: **1/3 pull-request-eligible** (`ci.yml` of `ci.yml`, `ci-image.yml`, `publish.yml`).
-- Do not re-litigate the settled 311/312 populations; both are valid for their separately named Tess6 and CRUD-core7 sets.
-
-## Round 4 — bound stale-marker observation
-
-### Objective and plan
-
-- Make the heartbeat assertion discriminate an initially stale native marker from a fresh marker without changing the production staleness threshold or shortening the polling window.
-- Freeze only the sidecar's numeric observation clock during the stale-fixture arm so elapsed assertion time cannot turn a fresh mutant stale.
-- Prove two independent mutants RED: disable production stale-marker detection while retaining the stale fixture; replace the stale fixture with a fresh marker. Restore the tree and prove GREEN in the canonical Alpine image.
-- Re-derive the changed-path inventory, run applicable quality and independent review gates, commit with environment-only author/committer identity, queue-guard, push once, verify provider attribution using curl stdin config, and stop without CI polling.
-- Working budget: 8K tokens. Scope is the launcher test and its scratchpad evidence; production launcher behavior remains unchanged.
-
-### Root cause and bounded observation
-
-The 30 × 0.1-second assertion window overlaps the production `now - marker > interval * 2 + 1` threshold at interval 1. Depending on second boundaries and load, a fresh marker can age past the threshold before the assertion ends. A focused pre-fix fresh-mutant attempt returned RED while Review 101's full-suite run returned GREEN; the differing result is itself timing dependence, not a discriminating assertion.
-
-The test now supplies a fixed numeric epoch only to the stale-fixture sidecar. Its real marker mtime is still read from the filesystem, but assertion runtime cannot advance `now`. Date formatting still delegates to the image's real `/bin/date`. Neither the production threshold nor the 30 × 0.1-second polling window changed.
-
-### Two-mutant RED / restored GREEN
-
-All three runs used `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`:
-
-1. **Stale-detection mutant RED:** replaced only the production stale-age predicate with `false` while retaining the fixed stale marker; suite exit 1 with `FAIL: heartbeat sidecar did not resume after native marker became stale or absent`.
-2. **Fresh-marker mutant RED:** replaced only `touch -t 200001010000.00` with fresh `touch`; suite exit 1 with the same failed stale-resumption assertion. The fixed observation epoch kept the mutant fresh throughout all 30 polls.
-3. **Restored tree GREEN:** suite exit 0 with `ok - start-agent-session generated environment boundary`.
-
-### Re-derived inventory
-
-- Round-4 delta: **2/2 files** — launcher test plus task scratchpad; production launcher delta is empty.
-- Full PR inventory against `origin/main`: **19/19 paths**; Round 4 adds no path.
-- Production stale threshold remains `now - marker > iv * 2 + 1`; assertion polling remains 30 × 0.1 seconds.
-- Review 101's confirmed enumeration/workflow/CI and attribution evidence is accepted without re-polling or re-derivation.
-
-## Residual risk
-
-- Landing on `main` does not update the currently installed host launcher. Host framework installation/reseed and Jarvis live-seat validation are separate downstream events.
-- Canonical CI result is pending and will not be polled by this seat.

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

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

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

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

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

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

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

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

@@ -0,0 +1,35 @@
+# 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/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,7 +10,8 @@
     "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",
+    "test": "pnpm test:checkout && turbo run test && pnpm run test:installer",
+    "test:installer": "bash tools/install-next-lane.test.sh",
     "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,9 +11,37 @@ 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),
@@ -23,6 +51,14 @@ 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';
 
@@ -44,6 +80,16 @@ 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 });
@@ -98,8 +144,12 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
     expect(bootstrapCall[2]).toMatchObject({ host: 'localhost', port: 14242 });
   });
 
-  it('does not invoke bootstrap when config stage reports not ready', async () => {
-    gatewayConfigMock.mockResolvedValue({ ready: false });
+  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 });
 
     const prompter = new HeadlessPrompter({
       'Installation mode': 'quick',
@@ -118,6 +168,43 @@ 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();
   });
@@ -143,4 +230,34 @@ 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,6 +43,16 @@ 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:
@@ -108,8 +118,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
@@ -174,7 +184,9 @@ 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 --ref v1.0    # Install from a specific git ref
+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)
 ```
 
 The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
@@ -185,6 +197,7 @@ The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/ski
 
 ```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
@@ -198,7 +211,7 @@ M1 lifecycle management targets Claude Code. Pi can discover the canonical Mosai
 
 ```bash
 mosaic doctor                                           # Standard audit
-~/.config/mosaic/bin/mosaic-doctor --fail-on-warn      # Strict mode
+~/.config/mosaic/tools/_scripts/mosaic-doctor --fail-on-warn      # Strict mode
 ```
 
 ## MCP Registration
@@ -209,8 +222,8 @@ sequential-thinking MCP is required for Mosaic Stack. The installer registers it
 To verify or re-register manually:
 
 ```bash
-~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
-~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
+~/.config/mosaic/tools/_scripts/mosaic-ensure-sequential-thinking
+~/.config/mosaic/tools/_scripts/mosaic-ensure-sequential-thinking --check
 ```
 
 ### Claude Code MCP Registration

packages/mosaic/framework/systemd/user/test-fleet-units.sh

@@ -112,7 +112,6 @@ EOF
   chmod 700 "$AGENT_HOME/fleet/agents"
   cat > "$AGENT_HOME/fleet/agents/$AGENT_NAME.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$AGENT_NAME
-MOSAIC_GIT_IDENTITY=$AGENT_NAME
 MOSAIC_AGENT_CLASS=code
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=

packages/mosaic/framework/tools/fleet/start-agent-session.sh

@@ -97,7 +97,7 @@ is_sensitive_key() {
 
 is_generated_key() {
   case "$1" in
-    MOSAIC_AGENT_NAME|MOSAIC_GIT_IDENTITY|MOSAIC_AGENT_CLASS|MOSAIC_AGENT_RUNTIME|MOSAIC_AGENT_MODEL|MOSAIC_AGENT_REASONING|MOSAIC_AGENT_TOOL_POLICY|MOSAIC_AGENT_WORKDIR|MOSAIC_TMUX_SOCKET) return 0 ;;
+    MOSAIC_AGENT_NAME|MOSAIC_AGENT_CLASS|MOSAIC_AGENT_RUNTIME|MOSAIC_AGENT_MODEL|MOSAIC_AGENT_REASONING|MOSAIC_AGENT_TOOL_POLICY|MOSAIC_AGENT_WORKDIR|MOSAIC_TMUX_SOCKET) return 0 ;;
     *) return 1 ;;
   esac
 }
@@ -114,7 +114,6 @@ validate_generated_value() {
   local value="$2"
   case "$key" in
     MOSAIC_AGENT_NAME) safe_agent_name "$value" || fail_env unsafe-agent-name "$key" "$value" ;;
-    MOSAIC_GIT_IDENTITY) safe_agent_name "$value" || fail_env unsafe-git-identity "$key" "$value" ;;
     MOSAIC_AGENT_CLASS) safe_policy_name "$value" || fail_env unsafe-class "$key" "$value" ;;
     MOSAIC_AGENT_RUNTIME)
       case "$value" in claude|codex|opencode|pi) ;; *) fail_env unsupported-runtime "$key" "$value" ;; esac
@@ -176,7 +175,7 @@ load_environment_file() {
 
 load_environment_file "$GENERATED_ENV" generated
 for required_key in \
-  MOSAIC_AGENT_NAME MOSAIC_GIT_IDENTITY MOSAIC_AGENT_CLASS MOSAIC_AGENT_RUNTIME MOSAIC_AGENT_MODEL \
+  MOSAIC_AGENT_NAME MOSAIC_AGENT_CLASS MOSAIC_AGENT_RUNTIME MOSAIC_AGENT_MODEL \
   MOSAIC_AGENT_REASONING MOSAIC_AGENT_TOOL_POLICY MOSAIC_AGENT_WORKDIR MOSAIC_TMUX_SOCKET; do
   [ -n "${GENERATED_VALUES[$required_key]+set}" ] || fail_env missing-key "$required_key" ''
 done
@@ -184,15 +183,12 @@ load_environment_file "$LOCAL_ENV" local
 
 [ "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}" = "$AGENT_NAME" ] || \
   fail_env agent-name-mismatch MOSAIC_AGENT_NAME "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}"
-[ "${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}" = "$AGENT_NAME" ] || \
-  fail_env git-identity-mismatch MOSAIC_GIT_IDENTITY "${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}"
 
 MOSAIC_TMUX_SOCKET=${GENERATED_VALUES[MOSAIC_TMUX_SOCKET]}
 MOSAIC_AGENT_RUNTIME=${GENERATED_VALUES[MOSAIC_AGENT_RUNTIME]}
 MOSAIC_AGENT_MODEL=${GENERATED_VALUES[MOSAIC_AGENT_MODEL]}
 MOSAIC_AGENT_REASONING=${GENERATED_VALUES[MOSAIC_AGENT_REASONING]}
 MOSAIC_AGENT_WORKDIR=${GENERATED_VALUES[MOSAIC_AGENT_WORKDIR]}
-MOSAIC_GIT_IDENTITY=${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}
 MOSAIC_AGENT_CLASS=${GENERATED_VALUES[MOSAIC_AGENT_CLASS]}
 MOSAIC_AGENT_TOOL_POLICY=${GENERATED_VALUES[MOSAIC_AGENT_TOOL_POLICY]}
 MOSAIC_RUNTIME_BIN=${LOCAL_VALUES[MOSAIC_RUNTIME_BIN]:-}
@@ -347,7 +343,6 @@ LAUNCH_ENV=(
   "PATH=$PANE_PATH"
   "MOSAIC_HOME=$MOSAIC_HOME"
   "MOSAIC_AGENT_NAME=$AGENT_NAME"
-  "MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"
   "MOSAIC_AGENT_CLASS=$MOSAIC_AGENT_CLASS"
   "MOSAIC_AGENT_RUNTIME=$MOSAIC_AGENT_RUNTIME"
   "MOSAIC_AGENT_MODEL=$MOSAIC_AGENT_MODEL"

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh

@@ -62,19 +62,6 @@ env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
 SHIM
 chmod +x "$FAKE_BIN/mosaic"
 
-# Freeze numeric epoch reads only when a test arm supplies an observation bound.
-# Formatting reads still use the real BusyBox/POSIX date implementation.
-cat > "$FAKE_BIN/date" <<'SHIM'
-#!/usr/bin/env bash
-set -euo pipefail
-if [ -n "${MOSAIC_TEST_FIXED_EPOCH:-}" ] && [ "${1:-}" = '+%s' ]; then
-  printf '%s\n' "$MOSAIC_TEST_FIXED_EPOCH"
-  exit 0
-fi
-exec /bin/date "$@"
-SHIM
-chmod +x "$FAKE_BIN/date"
-
 write_generated() {
   local home="$1"
   local agent="$2"
@@ -84,7 +71,6 @@ write_generated() {
   chmod 600 "$home/fleet/run/holder-owner"
   cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
-MOSAIC_GIT_IDENTITY=$agent
 MOSAIC_AGENT_CLASS=code
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=openai-codex/gpt-5.6-sol
@@ -102,7 +88,6 @@ run_start() {
   local agent="$2"
   HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
     MOSAIC_TEST_PANE_PID="${MOSAIC_TEST_PANE_PID:-}" \
-    MOSAIC_TEST_FIXED_EPOCH="${MOSAIC_TEST_FIXED_EPOCH:-}" \
     MOSAIC_TEST_HOME="$home" \
     MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
     MOSAIC_HOME="$home" "$START" "$agent"
@@ -129,42 +114,6 @@ fi
 echo "$valid_args" | grep -qxF '/usr/bin/env' || fail "pane does not use absolute env"
 echo "$valid_args" | grep -qxF -- '-i' || fail "pane environment is not cleared"
 
-# Git identity is generated authority, not an optional or independently mutable
-# local value. Each invalid form must fail before fake tmux receives a call.
-assert_git_identity_rejected() {
-  local case_name="$1"
-  local expected_code="$2"
-  local home="$ROOT/git-identity-$case_name"
-  local agent="coder-git-identity-$case_name"
-  local generated="$home/fleet/agents/$agent.env.generated"
-  write_generated "$home" "$agent"
-
-  case "$case_name" in
-    missing) grep -v '^MOSAIC_GIT_IDENTITY=' "$generated" > "$generated.next" && mv "$generated.next" "$generated" ;;
-    unsafe) sed -i 's|^MOSAIC_GIT_IDENTITY=.*$|MOSAIC_GIT_IDENTITY=bad/identity|' "$generated" ;;
-    mismatch) sed -i 's|^MOSAIC_GIT_IDENTITY=.*$|MOSAIC_GIT_IDENTITY=other-agent|' "$generated" ;;
-    local-shadow)
-      printf 'MOSAIC_GIT_IDENTITY=%s\n' "$agent" > "$home/fleet/agents/$agent.env.local"
-      chmod 600 "$home/fleet/agents/$agent.env.local"
-      ;;
-    *) fail "unknown Git identity rejection case: $case_name" ;;
-  esac
-  chmod 600 "$generated"
-
-  : > "$TMUX_CALLS"
-  if output=$(run_start "$home" "$agent" 2>&1); then
-    fail "Git identity case $case_name was accepted"
-  fi
-  [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before Git identity $case_name rejection"
-  echo "$output" | grep -qF "code=$expected_code" || \
-    fail "Git identity $case_name diagnostic omitted code $expected_code"
-}
-
-assert_git_identity_rejected missing missing-key
-assert_git_identity_rejected unsafe unsafe-git-identity
-assert_git_identity_rejected mismatch git-identity-mismatch
-assert_git_identity_rejected local-shadow generated-key-shadow
-
 # The generated-file parent is a security boundary too: even a private regular
 # file is untrusted if its parent can be replaced or written by another user.
 # Validation must happen before fake tmux receives even a has-session call.
@@ -325,18 +274,6 @@ after_pane_env=$(printf '%s\n' "$pane_args" | grep -n -m1 -F '/usr/bin/env' | cu
 printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i' || \
   fail "pane command did not clear its environment"
 pane_environment=$(tr '\0' '\n' < "$HOME_PANE_BOUNDARY/fleet/pane-environment")
-# Exercise the repository launcher at $START, not the independently installed
-# host copy. Set-compare every declared generated projection entry with the
-# launched process environment so a newly declared identity cannot be omitted
-# by a hand-maintained per-variable assertion.
-declared_generated_environment=$(sort "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.generated")
-missing_or_changed_generated_environment=$(comm -23 \
-  <(printf '%s\n' "$declared_generated_environment") \
-  <(printf '%s\n' "$pane_environment" | sort))
-if [ -n "$missing_or_changed_generated_environment" ]; then
-  missing_or_changed_keys=$(printf '%s\n' "$missing_or_changed_generated_environment" | cut -d= -f1 | paste -sd, -)
-  fail "runtime pane omitted or changed generated environment keys: $missing_or_changed_keys"
-fi
 echo "$pane_environment" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
   fail "runtime pane did not receive trusted HOME"
 echo "$pane_environment" | grep -qF "$PANE_STALE_PATH" && fail "runtime pane received stale PATH"
@@ -353,7 +290,6 @@ write_interaction_generated() {
   chmod 600 "$home/fleet/run/holder-owner"
   cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
-MOSAIC_GIT_IDENTITY=$agent
 MOSAIC_AGENT_CLASS=operator-interaction
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol
@@ -416,12 +352,8 @@ write_generated "$HOME_NATIVE_STALE" "coder-native-stale"
 write_heartbeat_local "$HOME_NATIVE_STALE" "coder-native-stale"
 STALE_HB="$HOME_NATIVE_STALE/run/coder-native-stale.hb"
 printf 'ts=native\npid=1\nstatus=busy\nmodel=stale-model\n' > "$STALE_HB"
-touch -t 200001010000.00 "$STALE_HB.native"
-# Hold the sidecar's observation epoch constant: assertion runtime must not age
-# a fresh-marker mutant into the stale state that this fixture must distinguish.
-STALE_OBSERVATION_EPOCH=$(date +%s)
-MOSAIC_TEST_FIXED_EPOCH="$STALE_OBSERVATION_EPOCH" \
-  MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_STALE" coder-native-stale
+touch -d '10 seconds ago' "$STALE_HB.native"
+MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_STALE" coder-native-stale
 wait_for_sidecar_status "$STALE_HB"
 
 HOME_NATIVE_ABSENT="$ROOT/native-absent"
@@ -449,7 +381,7 @@ echo "$output" | grep -qF 'code=unknown-key' || fail "interaction did not use sh
 : > "$TMUX_CALLS"
 HOME_INTERACTION_POLICY="$ROOT/interaction-policy"
 write_interaction_generated "$HOME_INTERACTION_POLICY" "interaction-policy"
-sed -i 's|^MOSAIC_AGENT_RUNTIME=pi$|MOSAIC_AGENT_RUNTIME=codex|' \
+perl -0pi -e 's/MOSAIC_AGENT_RUNTIME=pi/MOSAIC_AGENT_RUNTIME=codex/' \
   "$HOME_INTERACTION_POLICY/fleet/agents/interaction-policy.env.generated"
 if output=$(run_interaction "$HOME_INTERACTION_POLICY" interaction-policy 2>&1); then
   fail "interaction wrapper accepted a policy-incompatible projection"

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
-    fi
-    raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$body_file" \
-        -X POST -H "User-Agent: curl/8" \
+    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' \
-        --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
-
-    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
+            -d "$payload" \
+            "$api_url" || true)
+        if [[ "$raw_code" =~ ^2 ]]; then
+            rm -f "$body_file"
             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
+
+    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
-    echo "Error: Gitea API rejected the identity-bound token with HTTP 401; refusing cross-principal credential fallback." >&2
+    fi
+
+    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-ci-queue-wait-tristate.sh

@@ -9,51 +9,10 @@ WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/ci-queue-wait-tristate}
 REPO_DIR="$WORK_DIR/repo"
 STUB_DIR="$WORK_DIR/stubs"
 AUDIT_LOG="$WORK_DIR/audit/ci-queue-wait.jsonl"
-STATUS_OBSERVED="$WORK_DIR/status-observed"
-CLOCK_LOG="$WORK_DIR/clock.log"
-WATCHDOG_PYTHON="/usr/bin/python3"
-WATCHDOG_SCRIPT="$WORK_DIR/real-clock-watchdog.py"
-WATCHDOG_TIMEOUT_SEC=5
-WATCHDOG_EXIT=90
 FEATURE_BRANCH="fix/rm-03-fixture"
 
-if [[ ! -x "$WATCHDOG_PYTHON" ]]; then
-    echo "FAIL setup: required real-clock watchdog runtime is unavailable at $WATCHDOG_PYTHON" >&2
-    exit 1
-fi
-
 rm -rf "$WORK_DIR"
 mkdir -p "$REPO_DIR" "$STUB_DIR"
-cat > "$WATCHDOG_SCRIPT" <<'PY'
-import os
-import signal
-import subprocess
-import sys
-
-if len(sys.argv) < 3:
-    raise SystemExit(2)
-
-timeout_seconds = float(sys.argv[1])
-process = subprocess.Popen(sys.argv[2:], start_new_session=True)
-try:
-    return_code = process.wait(timeout=timeout_seconds)
-except subprocess.TimeoutExpired:
-    try:
-        os.killpg(process.pid, signal.SIGKILL)
-    except ProcessLookupError:
-        pass
-    process.wait()
-    print(
-        f"FAIL HANG watchdog: subject exceeded {timeout_seconds:g}s "
-        "before completing its intended path",
-        file=sys.stderr,
-    )
-    raise SystemExit(90)
-
-if return_code < 0:
-    raise SystemExit(128 - return_code)
-raise SystemExit(return_code)
-PY
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" checkout -q -b "$FEATURE_BRANCH"
 git -C "$REPO_DIR" remote add origin https://git.example.test/acme/widgets.git
@@ -74,9 +33,6 @@ printf '%s\n' "$url" >> "${MOSAIC_STUB_URL_LOG:?}"
 
 case "$url" in
     */branches/*)
-        if [[ "${MOSAIC_STUB_BRANCH_MODE:-ok}" == "hang-before-provider" ]]; then
-            while :; do :; done
-        fi
         if [[ "${MOSAIC_STUB_BRANCH_MODE:-ok}" == "unreachable" ]]; then
             exit 7
         fi
@@ -88,7 +44,6 @@ case "$url" in
         fi
         ;;
     */status)
-        : > "${MOSAIC_STUB_STATUS_OBSERVED:?}"
         case "${MOSAIC_STUB_STATUS_MODE:?}" in
             success)   printf '%s' '{"state":"success","statuses":[{"status":"success"}]}' ;;
             pending)   printf '%s' '{"state":"pending","statuses":[{"status":"pending","context":"ci/test"}]}' ;;
@@ -108,31 +63,7 @@ case "$url" in
     *) echo "unexpected curl URL: $url" >&2; exit 2 ;;
 esac
 SH
-
-cat > "$STUB_DIR/date" <<'SH'
-#!/usr/bin/env bash
-set -euo pipefail
-
-if [[ "$#" -ne 1 || "$1" != "+%s" ]]; then
-    echo "unexpected date invocation: $*" >&2
-    exit 2
-fi
-
-if [[ -e "${MOSAIC_STUB_STATUS_OBSERVED:?}" ]]; then
-    printf 'date-phase=after-status\n' >> "${MOSAIC_STUB_CLOCK_LOG:?}"
-    printf '1002\n'
-else
-    printf 'date-phase=before-status\n' >> "${MOSAIC_STUB_CLOCK_LOG:?}"
-    printf '1000\n'
-fi
-SH
-
-cat > "$STUB_DIR/sleep" <<'SH'
-#!/usr/bin/env bash
-set -euo pipefail
-printf 'sleep-after-status=%s\n' "$*" >> "${MOSAIC_STUB_CLOCK_LOG:?}"
-SH
-chmod +x "$STUB_DIR/curl" "$STUB_DIR/date" "$STUB_DIR/sleep"
+chmod +x "$STUB_DIR/curl"
 
 run_guard() {
     local status_mode="$1"
@@ -152,46 +83,13 @@ run_guard() {
             export GITEA_URL=https://git.example.test
             export MOSAIC_STUB_STATUS_MODE="$status_mode"
         fi
-        rm -f "$STATUS_OBSERVED" "$CLOCK_LOG"
         export MOSAIC_STUB_URL_LOG="$WORK_DIR/urls.log"
-        export MOSAIC_STUB_STATUS_OBSERVED="$STATUS_OBSERVED"
-        export MOSAIC_STUB_CLOCK_LOG="$CLOCK_LOG"
         export MOSAIC_CI_QUEUE_AUDIT_LOG="$audit_log"
-        # Provider observation is the synchronization event. The one-second
-        # timeout is subject semantics under virtual time, never a wall wait.
-        # The absolute Python runtime uses an internal monotonic wait and kills
-        # the subject's isolated process group. Neither operation can resolve
-        # to the virtual date/sleep stubs at the front of PATH.
-        local subject_rc
-        if "$WATCHDOG_PYTHON" "$WATCHDOG_SCRIPT" "$WATCHDOG_TIMEOUT_SEC" \
-            "$SCRIPT_DIR/ci-queue-wait.sh" --purpose "${MOSAIC_TEST_PURPOSE:-push}" -t 1 -i 1 "$@"; then
-            subject_rc=0
-        else
-            subject_rc=$?
-        fi
-        return "$subject_rc"
+        "$SCRIPT_DIR/ci-queue-wait.sh" --purpose "${MOSAIC_TEST_PURPOSE:-push}" -t 0 -i 0 "$@"
     )
 }
 
 failures=0
-assert_provider_observed() {
-    local name="$1" require_expiration="${2:-0}"
-    if [[ ! -e "$STATUS_OBSERVED" ]]; then
-        echo "FAIL $name: status provider was not observed" >&2
-        failures=$((failures + 1))
-    fi
-    if [[ ! -s "$CLOCK_LOG" ]] || ! grep -q '^date-phase=before-status$' "$CLOCK_LOG"; then
-        echo "FAIL $name: virtual clock interception did not run before provider observation" >&2
-        failures=$((failures + 1))
-    fi
-    if [[ "$require_expiration" -eq 1 ]]; then
-        if ! grep -q '^sleep-after-status=' "$CLOCK_LOG" || ! grep -q '^date-phase=after-status$' "$CLOCK_LOG"; then
-            echo "FAIL $name: pending path did not expire after provider observation" >&2
-            failures=$((failures + 1))
-        fi
-    fi
-}
-
 run_assertion() {
     local name="$1" expected_rc="$2" status_mode="$3" required_text="$4"
     local output rc
@@ -226,13 +124,6 @@ run_assertion() {
         printf '%s\n' "$output" >&2
         failures=$((failures + 1))
     fi
-    if [[ "$status_mode" != "credential-unresolvable" ]]; then
-        if [[ "$status_mode" == "pending" ]]; then
-            assert_provider_observed "$name" 1
-        else
-            assert_provider_observed "$name"
-        fi
-    fi
 }
 
 set -e
@@ -249,27 +140,6 @@ run_assertion large-payload not126 large-success 'state=terminal-success'
 run_assertion credential-unresolvable zero credential-unresolvable 'CANNOT_ASSERT'
 run_assertion provider-unreachable zero unreachable 'CANNOT_ASSERT'
 
-# Positive liveness control: a subject mutant hangs before the branch lookup
-# can reach the status provider. Only the independent real-clock watchdog may
-# terminate it, and its failure must be distinct from subject timeout rc=124.
-set +e
-watchdog_output=$(MOSAIC_STUB_BRANCH_MODE=hang-before-provider run_guard success "$AUDIT_LOG" 2>&1)
-watchdog_rc=$?
-set -e
-if [[ "$watchdog_rc" -ne "$WATCHDOG_EXIT" ]]; then
-    echo "FAIL watchdog-control: expected hang-specific rc=$WATCHDOG_EXIT, got rc=$watchdog_rc" >&2
-    failures=$((failures + 1))
-fi
-if [[ "$watchdog_output" != *"FAIL HANG watchdog:"* ]]; then
-    echo "FAIL watchdog-control: expected distinct hang-specific diagnostic" >&2
-    printf '%s\n' "$watchdog_output" >&2
-    failures=$((failures + 1))
-fi
-if [[ -e "$STATUS_OBSERVED" ]]; then
-    echo "FAIL watchdog-control: hanging mutant unexpectedly reached the status provider" >&2
-    failures=$((failures + 1))
-fi
-
 if [[ ! -s "$AUDIT_LOG" ]] || ! grep -q '"outcome":"CANNOT_ASSERT"' "$AUDIT_LOG"; then
     echo "FAIL provider-unreachable-audit: expected durable CANNOT_ASSERT JSONL record" >&2
     failures=$((failures + 1))
@@ -290,7 +160,6 @@ if [[ "$merge_unreachable_output" != *"CANNOT_ASSERT"* ]]; then
     echo "FAIL merge-provider-unreachable: expected loud CANNOT_ASSERT diagnostic" >&2
     failures=$((failures + 1))
 fi
-assert_provider_observed merge-provider-unreachable
 merge_audit_lines_after=$(wc -l < "$AUDIT_LOG")
 if [[ "$merge_audit_lines_after" -le "$merge_audit_lines_before" ]]; then
     echo "FAIL merge-provider-unreachable: expected an additional audit record" >&2
@@ -354,7 +223,6 @@ if [[ "$audit_failure_output" != *"audit"* ]]; then
     echo "FAIL audit-unavailable: expected loud audit failure diagnostic" >&2
     failures=$((failures + 1))
 fi
-assert_provider_observed audit-unavailable
 
 if [[ "$failures" -ne 0 ]]; then
     echo "ci-queue-wait tri-state regression failed ($failures assertions)" >&2

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/quality/scripts/test-upgrade-rollback.sh

@@ -39,12 +39,11 @@ ORIG_PATH="$PATH"
 # loop — which would make the control a false negative. A root dotfile is
 # operator-owned (unknown→operator), so the sync loop skips it. Clean up on exit.
 STRIPPED="$FW/.install-rollback-control.tmp.sh"
-SIGNALED="$FW/.install-signal-control.tmp.sh"
 NOEXIT="$FW/.install-noexit-control.tmp.sh"
 D1CTRL="$FW/.install-d1guard-control.tmp.sh"
 D2CTRL="$FW/.install-d2guard-control.tmp.sh"
-rm -f "$STRIPPED" "$SIGNALED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
-trap 'rm -f "$STRIPPED" "$SIGNALED" "$NOEXIT" "$D1CTRL" "$D2CTRL"' EXIT
+rm -f "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
+trap 'rm -f "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"' EXIT
 
 pass=0; fail=0
 chk() { if eval "$2"; then echo "  ✓ $1"; pass=$((pass + 1)); else echo "  ✗ $1"; fail=$((fail + 1)); fi; }
@@ -181,86 +180,41 @@ chk "[control] without -E the mid-sync corruption survives (no rollback)" \
 # ── Part C: an INT/TERM interrupt must terminate, not resume (blocker-A) ──────
 # A bash signal trap that merely returns lets the script continue past the
 # interrupt — restoring the snapshot, then resuming the sync and reporting
-# success. The earlier test used a child cp shim to signal its parent, making
-# child completion race Bash's interrupted wait. Concurrency is not part of the
-# guarded property: sync_framework_keep() runs in the installer's own Bash
-# process, and `kill` is a builtin. Generate two installer fixtures that signal
-# themselves at the same known mid-sync point. Their TERM handlers emit the same
-# observable before diverging, so missing signal delivery fails BOTH arms rather
-# than manufacturing a pass. The only semantic difference between fixtures is
-# the explicit `exit 1` whose load-bearing behavior this control proves.
-TERM_MARKER='[test-control] TERM handler entered'
-HANDLER_WITH_EXIT="trap 'echo \"$TERM_MARKER\" >&2; restore_snapshot; exit 1' TERM  # TEST-TERM-HANDLER"
-HANDLER_WITHOUT_EXIT="trap 'echo \"$TERM_MARKER\" >&2; restore_snapshot' TERM  # TEST-TERM-HANDLER"
-
-make_signal_installer() {
-  local output="$1" handler="$2"
-  local target_trap="trap 'restore_snapshot; exit 1' ERR INT TERM"
-  local target_cp='    cp "$abs" "$dst/$rel"'
-  local inject_open="    if [[ \"\$rel\" == \"$POISON_REL\" ]]; then"
-  local inject_kill='      kill -TERM "$$"  # TEST-TERM-INJECTION'
-  local inject_close='    fi'
-
-  if ! awk \
-    -v target_trap="$target_trap" -v target_cp="$target_cp" \
-    -v handler="$handler" -v inject_open="$inject_open" \
-    -v inject_kill="$inject_kill" -v inject_close="$inject_close" '
-      $0 == target_cp {
-        print inject_open
-        print inject_kill
-        print inject_close
-        injection_sites++
-      }
-      { print }
-      $0 == target_trap {
-        print handler
-        handler_sites++
-      }
-      END {
-        if (handler_sites != 1 || injection_sites != 1) exit 42
-      }
-    ' "$INSTALL" > "$output"; then
-    rm -f "$output"
-    fail "Could not construct the self-TERM control installer at the exact trap/copy sites"
-    exit 1
-  fi
-  chmod +x "$output"
+# success. We inject a SIGTERM mid-sync with a cp that SUCCEEDS (so set -e never
+# fires and ONLY the signal path governs), and assert the shipped installer
+# restores AND exits without reporting success. The control strips `exit 1` from
+# the trap and shows the buggy resume-to-success.
+make_term_shim() {
+  local dir="$1"
+  cat > "$dir/cp" <<SHIM
+#!/usr/bin/env bash
+dest="\${@: -1}"
+case "\$dest" in
+  */$POISON_REL)
+    kill -TERM "\$PPID" 2>/dev/null   # signal install.sh; the copy still succeeds
+    exec env PATH="$ORIG_PATH" cp "\$@" ;;
+esac
+exec env PATH="$ORIG_PATH" cp "\$@"
+SHIM
+  chmod +x "$dir/cp"
 }
 
-make_signal_installer "$SIGNALED" "$HANDLER_WITH_EXIT"
-make_signal_installer "$NOEXIT" "$HANDLER_WITHOUT_EXIT"
-signal_fixture_ready() {
-  local fixture="$1" expected_handler="$2"
-  [[ "$(grep -cF '# TEST-TERM-INJECTION' "$fixture")" -eq 1 ]] \
-    && [[ "$(grep -cF '# TEST-TERM-HANDLER' "$fixture")" -eq 1 ]] \
-    && grep -Fqx "$expected_handler" "$fixture"
-}
-signaled_fixture_ready() { signal_fixture_ready "$SIGNALED" "$HANDLER_WITH_EXIT"; }
-noexit_fixture_ready() { signal_fixture_ready "$NOEXIT" "$HANDLER_WITHOUT_EXIT"; }
-chk "[signal] shipped fixture has exactly one self-TERM injection and marked handler" \
-  "signaled_fixture_ready"
-chk "[control] no-exit fixture has exactly one self-TERM injection and marked handler" \
-  "noexit_fixture_ready"
-chk "[control] removing the explicit TERM exit changes the fixture" \
-  "! cmp -s '$SIGNALED' '$NOEXIT'"
-
-# Run one keep-mode upgrade whose own shell delivers SIGTERM synchronously at
-# the selected copy. Echoes "<exit>\t<out>\t<home>".
+# Run one keep-mode upgrade with the SIGTERM shim. Echoes "<exit>\t<out>\t<home>".
 run_signal_upgrade() {
-  local installer="$1" H OUT rc
-  H=$(mktemp -d); OUT=$(mktemp)
+  local installer="$1" H OUT SHIM rc
+  H=$(mktemp -d); OUT=$(mktemp); SHIM=$(mktemp -d)
   seed_home "$H"
+  make_term_shim "$SHIM"
   set +e
-  PATH="$ORIG_PATH" \
+  PATH="$SHIM:$ORIG_PATH" \
     MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash "$installer" >"$OUT" 2>&1
   rc=$?
   set -e 2>/dev/null || true
+  rm -rf "$SHIM"
   printf '%s\t%s\t%s\n' "$rc" "$OUT" "$H"
 }
 
-IFS=$'\t' read -r rcC OUTC HC < <(run_signal_upgrade "$SIGNALED")
-chk "[signal] TERM handler observable fires exactly once" \
-  "[ \"\$(grep -cF '$TERM_MARKER' '$OUTC')\" -eq 1 ]"
+IFS=$'\t' read -r rcC OUTC HC < <(run_signal_upgrade "$INSTALL")
 chk "[signal] SIGTERM mid-sync aborts non-zero (trap exits, does not resume)" \
   "[ '$rcC' -ne 0 ]"
 chk "[signal] restore_snapshot fires on the interrupt" \
@@ -268,13 +222,13 @@ chk "[signal] restore_snapshot fires on the interrupt" \
 chk "[signal] does NOT resume to report sync success after the interrupt" \
   "! grep -q 'file phase complete' '$OUTC'"
 
-IFS=$'\t' read -r rcD OUTD HD < <(run_signal_upgrade "$NOEXIT")
-chk "[control] TERM handler observable fires exactly once" \
-  "[ \"\$(grep -cF '$TERM_MARKER' '$OUTD')\" -eq 1 ]"
-chk "[control] without 'exit 1' the handler restores before returning" \
-  "grep -q 'restoring previous state from snapshot' '$OUTD'"
-chk "[control] without 'exit 1' the installer exits zero after resuming" \
-  "[ '$rcD' -eq 0 ]"
+# Control: strip `exit 1` from the signal trap → the handler returns, the script
+# resumes past the interrupt and wrongly reports success. In $FW so SOURCE_DIR resolves.
+sed "s/trap 'restore_snapshot; exit 1' ERR INT TERM/trap 'restore_snapshot' ERR INT TERM/" \
+  "$INSTALL" > "$NOEXIT"
+chk "[control] the exit-strip actually changed the installer" \
+  "! cmp -s '$INSTALL' '$NOEXIT'"
+IFS=$'\t' read -r _rcD OUTD HD < <(run_signal_upgrade "$NOEXIT")
 chk "[control] without 'exit 1' the trap resumes and reports sync success (the bug)" \
   "grep -q 'file phase complete' '$OUTD'"
 
@@ -355,10 +309,10 @@ chk "[control] without the D2 recovery line the operator gets no snapshot pointe
 # Reap any snapshot the reset-fail runs left in /tmp (reset failed → never cleaned).
 grep -o '/[^ ]*mosaic-snapshot[^ ]*' "$OUTH" 2>/dev/null | head -1 | while read -r s; do rm -rf "$s"; done
 
-# Cleanup (generated installer controls are also removed by the EXIT trap).
+# Cleanup ($STRIPPED / $NOEXIT / $D1CTRL / $D2CTRL are also removed by the EXIT trap).
 for d in "$HA" "$REFA" "$HB" "$REFB" "$HC" "$HD" "$HE" "$REFE" "$HF" "$REFF" "$HG" "$HH"; do rm -rf "$d"; done
 rm -f "$OUTA" "$OUTB" "$OUTC" "$OUTD" "$OUTE" "$OUTF" "$OUTG" "$OUTH" \
-  "$STRIPPED" "$SIGNALED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
+  "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
 
 echo
 echo "RESULT: $pass passed, $fail failed"

packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt

@@ -32,6 +32,7 @@ packages/mosaic/framework/tools/tmux/test-send-message-socket.sh | requires a re
 packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its sibling)
 
 # --- single-suite directories: unmeasured in CI ---
+packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | unmeasured in CI image; stubs tmux via a fake bin dir, likely CI-fit; #1017 burndown
 packages/mosaic/framework/tools/glpi/test-list-http-status.sh | unmeasured in CI image; stub-based (#807 regression harness), likely CI-fit; #1017 burndown
 packages/mosaic/framework/tools/orchestrator/test-board-roll.sh | unmeasured in CI image; file-fixture based, likely CI-fit; #1017 burndown
 packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasured in CI image; drives ci-wait.sh against a stub pipeline-status.sh, likely CI-fit; #1017 burndown

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 && bash framework/tools/fleet/test-start-agent-session.sh && bash framework/systemd/user/test-fleet-units.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-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/commands/fleet-regen-command.spec.ts

@@ -131,14 +131,13 @@ async function exists(path: string): Promise<boolean> {
 }
 
 describe('projectRosterV2AgentGeneratedEnv', (): void => {
-  it('maps a roster-v2 agent to exactly the nine generated projection keys', (): void => {
+  it('maps a roster-v2 agent to exactly the eight generated projection keys', (): void => {
     const roster = parseRosterV2(rosterYaml, 'yaml');
     const agent = roster.agents.find((candidate) => candidate.name === 'coder0');
     expect(agent).toBeDefined();
     const values = projectRosterV2AgentGeneratedEnv(roster, agent!);
     expect(values).toEqual({
       MOSAIC_AGENT_NAME: 'coder0',
-      MOSAIC_GIT_IDENTITY: 'coder0',
       MOSAIC_AGENT_CLASS: 'code',
       MOSAIC_AGENT_RUNTIME: 'pi',
       MOSAIC_AGENT_MODEL: 'gpt-5.6-sol',

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

@@ -422,7 +422,6 @@ describe('fleet roster parsing', () => {
     expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toBe(
       [
         'MOSAIC_AGENT_NAME=coder0',
-        'MOSAIC_GIT_IDENTITY=coder0',
         // Reflects the roster's canonicalized compatibility class (A3a).
         'MOSAIC_AGENT_CLASS=code',
         'MOSAIC_AGENT_RUNTIME=codex',
@@ -3800,7 +3799,6 @@ describe('fleet add command', () => {
       'utf8',
     );
     expect(envContent).toContain('MOSAIC_AGENT_NAME=coder0');
-    expect(envContent).toContain('MOSAIC_GIT_IDENTITY=coder0');
     expect(envContent).toContain('MOSAIC_AGENT_RUNTIME=codex');
   });
 

packages/mosaic/src/commands/fleet.ts

@@ -484,7 +484,6 @@ function generateAgentEnvValues(
   const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
   return {
     MOSAIC_AGENT_NAME: agent.name,
-    MOSAIC_GIT_IDENTITY: agent.name,
     MOSAIC_AGENT_CLASS: agent.className,
     MOSAIC_AGENT_RUNTIME: agent.runtime,
     MOSAIC_AGENT_MODEL: agent.modelHint ?? '',

packages/mosaic/src/fleet/fleet-agent-crud.ts

@@ -358,7 +358,6 @@ function generatedValues(
 ): Readonly<Record<string, string>> {
   return {
     MOSAIC_AGENT_NAME: agent.name,
-    MOSAIC_GIT_IDENTITY: agent.name,
     MOSAIC_AGENT_CLASS: agent.className,
     MOSAIC_AGENT_RUNTIME: agent.runtime,
     MOSAIC_AGENT_MODEL: agent.model,

packages/mosaic/src/fleet/fleet-documentation.spec.ts

@@ -380,7 +380,7 @@ const COMMAND_RECORDS: Readonly<Record<string, RegExp>> = {
 
 const DATA_PROFILE_BODIES: Readonly<Record<string, string>> = {
   'DATA.DOTENV.FLEET_LAUNCH':
-    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_GIT_IDENTITY=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
+    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
   'DATA.TEXT_TABLE.FLEET_TASKS':
     '| W-FLEET | in-progress | Fleet (agent-session execution layer) | Phase 2/5 | docs/fleet/TASKS.md | observability dogfooded on live stub fleet; control plane rides federation (W1) |',
   'DATA.TEXT_DIAGRAM.BACKLOG_FLOW':
@@ -406,7 +406,7 @@ const DATA_PROFILE_BODIES: Readonly<Record<string, string>> = {
   'DATA.JSON.MUTATION_RESULT':
     '{\n  "applied": false,\n  "authoritativeRoster": "committed",\n  "projections": "incomplete",\n  "recovery": {\n    "code": "projection-apply-failed",\n    "action": "regenerate-projections-from-roster"\n  }\n}',
   'DATA.DOTENV.GENERATED_ENV':
-    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_GIT_IDENTITY=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
+    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
   'DATA.YAML.ROSTER_FIELDS':
     'version: 2\ngeneration: 1\ntransport: tmux\ntmux:\n  socket_name: mosaic-fleet\n  holder_session: _holder\ndefaults:\n  working_directory: ~/src\n  runtime: pi\nruntimes:\n  pi:\n    reset_command: /new\nagents:\n  - name: coder0\n    alias: Coder 0\n    class: code\n    runtime: pi\n    provider: openai\n    model: gpt-5.6-sol\n    reasoning: high\n    tool_policy: code\n    working_directory: ~/src\n    persistent_persona: false\n    reset_between_tasks: true\n    lifecycle:\n      enabled: true\n      desired_state: stopped\n    launch:\n      yolo: true',
 };
@@ -922,8 +922,8 @@ describe('fleet operator documentation', (): void => {
     );
     expect(
       surfaces.filter((surface): boolean => surface.category === 'InlineLiteral'),
-    ).toHaveLength(863);
-    expect(surfaces).toHaveLength(887);
+    ).toHaveLength(858);
+    expect(surfaces).toHaveLength(882);
 
     const rosterSource = await readFile(join(fleetDocs, 'examples', 'roster-v2.yaml'), 'utf8');
     const auxiliary: CodeSurface = {

packages/mosaic/src/fleet/fleet-reconciler.ts

@@ -597,7 +597,6 @@ export function projectRosterV2AgentGeneratedEnv(
 ): Readonly<Record<string, string>> {
   return {
     MOSAIC_AGENT_NAME: agent.name,
-    MOSAIC_GIT_IDENTITY: agent.name,
     MOSAIC_AGENT_CLASS: agent.className,
     MOSAIC_AGENT_RUNTIME: agent.runtime,
     MOSAIC_AGENT_MODEL: agent.model,

packages/mosaic/src/fleet/generated-env-boundary.spec.ts

@@ -22,7 +22,6 @@ import {
 
 const generatedValues = {
   MOSAIC_AGENT_NAME: 'coder0',
-  MOSAIC_GIT_IDENTITY: 'coder0',
   MOSAIC_AGENT_CLASS: 'code',
   MOSAIC_AGENT_RUNTIME: 'pi',
   MOSAIC_AGENT_MODEL: 'openai-codex/gpt-5.6-sol',
@@ -46,7 +45,6 @@ describe('generated fleet agent environment boundary', (): void => {
     expect(renderGeneratedAgentEnvironment(generatedValues)).toBe(
       [
         'MOSAIC_AGENT_NAME=coder0',
-        'MOSAIC_GIT_IDENTITY=coder0',
         'MOSAIC_AGENT_CLASS=code',
         'MOSAIC_AGENT_RUNTIME=pi',
         'MOSAIC_AGENT_MODEL=openai-codex/gpt-5.6-sol',
@@ -80,22 +78,6 @@ describe('generated fleet agent environment boundary', (): void => {
     expect(String(error)).toMatch(/key=.*sha256=/);
   });
 
-  it.each([
-    ['unsafe-git-identity', 'other/identity'],
-    ['git-identity-mismatch', 'reviewer0'],
-  ])('rejects %s before any launch consumer can use it', (code: string, identity: string): void => {
-    expect((): void => {
-      renderGeneratedAgentEnvironment({
-        ...generatedValues,
-        MOSAIC_GIT_IDENTITY: identity,
-      });
-    }).toThrow(
-      expect.objectContaining({
-        diagnostic: expect.objectContaining({ code, key: 'MOSAIC_GIT_IDENTITY' }),
-      }),
-    );
-  });
-
   it('rejects unsafe generated paths before any launch consumer can use them', (): void => {
     expect((): void => {
       renderGeneratedAgentEnvironment({

packages/mosaic/src/fleet/generated-env-boundary.ts

@@ -73,7 +73,6 @@ export class AgentEnvBoundaryError extends Error {
 
 export const GENERATED_AGENT_ENV_KEYS = [
   'MOSAIC_AGENT_NAME',
-  'MOSAIC_GIT_IDENTITY',
   'MOSAIC_AGENT_CLASS',
   'MOSAIC_AGENT_RUNTIME',
   'MOSAIC_AGENT_MODEL',
@@ -403,7 +402,6 @@ function assertGeneratedValues(values: Readonly<Record<string, string>>): void {
     if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
   }
   const name = requiredGeneratedValue(values, 'MOSAIC_AGENT_NAME');
-  const gitIdentity = requiredGeneratedValue(values, 'MOSAIC_GIT_IDENTITY');
   const className = requiredGeneratedValue(values, 'MOSAIC_AGENT_CLASS');
   const runtime = requiredGeneratedValue(values, 'MOSAIC_AGENT_RUNTIME');
   const model = requiredGeneratedValue(values, 'MOSAIC_AGENT_MODEL');
@@ -414,12 +412,6 @@ function assertGeneratedValues(values: Readonly<Record<string, string>>): void {
 
   if (!AGENT_NAME.test(name))
     throw new AgentEnvBoundaryError('unsafe-agent-name', 'MOSAIC_AGENT_NAME', name);
-  if (!AGENT_NAME.test(gitIdentity)) {
-    throw new AgentEnvBoundaryError('unsafe-git-identity', 'MOSAIC_GIT_IDENTITY', gitIdentity);
-  }
-  if (gitIdentity !== name) {
-    throw new AgentEnvBoundaryError('git-identity-mismatch', 'MOSAIC_GIT_IDENTITY', gitIdentity);
-  }
   if (!POLICY_NAME.test(className)) {
     throw new AgentEnvBoundaryError('unsafe-class', 'MOSAIC_AGENT_CLASS', className);
   }

packages/mosaic/src/fleet/v1-v2-migration.ts

@@ -1405,7 +1405,6 @@ function generatedValues(
 ): Readonly<Record<string, string>> {
   return {
     MOSAIC_AGENT_NAME: agent.name,
-    MOSAIC_GIT_IDENTITY: agent.name,
     MOSAIC_AGENT_CLASS: agent.className,
     MOSAIC_AGENT_RUNTIME: agent.runtime,
     MOSAIC_AGENT_MODEL: agent.model,

packages/mosaic/src/runtime/detector.ts

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

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

@@ -85,16 +85,16 @@ function makeConfigService(): ConfigService {
 
 describe('finalizeStage — skill installer', () => {
   let tmp: string;
-  let binDir: string;
+  let scriptsDir: string;
   let syncScript: string;
 
   beforeEach(() => {
     tmp = mkdtempSync(join(tmpdir(), 'mosaic-finalize-'));
-    binDir = join(tmp, 'bin');
-    mkdirSync(binDir, { recursive: true });
-    syncScript = join(binDir, 'mosaic-sync-skills');
+    scriptsDir = join(tmp, 'tools', '_scripts');
+    mkdirSync(scriptsDir, { recursive: true });
+    syncScript = join(scriptsDir, 'mosaic-sync-skills');
 
-    // Default: script exists and succeeds
+    // Default: current framework layout has tools/_scripts and succeeds.
     writeFileSync(syncScript, '#!/usr/bin/env bash\necho ok\n', { mode: 0o755 });
     spawnSyncMock.mockReturnValue({ status: 0, stdout: 'ok', stderr: '' });
   });
@@ -156,10 +156,29 @@ 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();
@@ -199,7 +218,9 @@ describe('finalizeStage — skill installer', () => {
 
     // spawnSync should NOT have been called for the skills script
     expect(findSkillsSyncCall()).toBeUndefined();
-    expect(p.warn).toHaveBeenCalledWith(expect.stringContaining('not found'));
+    expect(p.warn).toHaveBeenCalledWith(
+      expect.stringContaining('tools/_scripts/mosaic-sync-skills'),
+    );
   });
 
   it('includes skills count in the summary when install succeeds', async () => {

packages/mosaic/src/stages/finalize.ts

@@ -13,16 +13,22 @@ import {
   type SkillSyncResult as ClaudeSkillSyncResult,
 } from '../commands/skill.js';
 
-/**
- * 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 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. */
 function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): string | undefined {
-  const script = join(mosaicHome, 'bin', 'mosaic-link-runtime-assets');
+  const script = frameworkScriptPath(mosaicHome, 'mosaic-link-runtime-assets');
   if (!existsSync(script)) return undefined;
   try {
     const result = spawnSync('bash', [script], {
@@ -69,7 +75,7 @@ function syncSkills(mosaicHome: string, selectedSkills: string[]): SyncSkillsRes
     return { success: true, installedCount: 0 };
   }
 
-  const script = join(mosaicHome, 'bin', 'mosaic-sync-skills');
+  const script = frameworkScriptPath(mosaicHome, 'mosaic-sync-skills');
   if (!existsSync(script)) {
     return {
       success: false,
@@ -117,7 +123,7 @@ interface DoctorResult {
 }
 
 function runDoctor(mosaicHome: string): DoctorResult {
-  const script = join(mosaicHome, 'bin', 'mosaic-doctor');
+  const script = frameworkScriptPath(mosaicHome, 'mosaic-doctor');
   if (!existsSync(script)) {
     return { warnings: 0, output: 'mosaic-doctor not found' };
   }
@@ -170,11 +176,24 @@ 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,
-): Promise<void> {
+  options: FinalizeStageOptions = {},
+): Promise<FinalizeStageResult> {
   p.separator();
 
   const spin = p.spinner();
@@ -269,7 +288,12 @@ export async function finalizeStage(
   // 7. PATH setup
   const pathAction = setupPath(state.mosaicHome, p);
 
-  // 8. Summary
+  let summaryShown = false;
+  const showSummary = () => {
+    if (summaryShown) return;
+    summaryShown = true;
+
+    // 7. Summary
     const skillsSummary = skillsResult.success
       ? skillsResult.installedCount > 0
         ? `${skillsResult.installedCount.toString()} installed`
@@ -294,7 +318,7 @@ export async function finalizeStage(
 
     p.note(summary.join('\n'), 'Installation Summary');
 
-  // 9. Next steps
+    // 8. Next steps
     const nextSteps: string[] = [];
     if (pathAction === 'added') {
       const profilePath = getShellProfilePath();
@@ -309,4 +333,11 @@ export async function finalizeStage(
     p.note(nextSteps.map((s, i) => `${(i + 1).toString()}. ${s}`).join('\n'), 'Next Steps');
 
     p.outro('Mosaic is ready.');
+  };
+
+  if (!options.deferSummary) {
+    showSummary();
+  }
+
+  return { showSummary };
 }

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

@@ -136,6 +136,7 @@ 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(() => {
@@ -167,6 +168,75 @@ 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,7 +294,12 @@ export async function gatewayConfigStage(
   }
 
   // Install the gateway npm package on first install or after failure.
-  if (!opts.skipInstall && !daemonRunning) {
+  // 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) {
     installGatewayPackage();
   }
 
@@ -506,6 +511,9 @@ 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,6 +37,7 @@ 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';
@@ -57,9 +58,13 @@ export async function quickStartPath(
 
   // Skills (recommended set, no user input in quick mode)
   await skillsSelectStage(prompter, state);
+  state.completedSections?.add('skills');
 
-  // Finalize (writes configs, links runtime assets, syncs skills)
-  await finalizeStage(prompter, state, configService);
+  // 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,
+  });
 
   // Gateway config + bootstrap
   if (!options.skipGateway) {
@@ -72,7 +77,7 @@ export async function quickStartPath(
         portOverride: options.gatewayPortOverride,
         skipInstall: options.skipGatewayNpmInstall,
         providerKey: state.providerKey,
-        providerType: state.providerType ?? 'none',
+        providerType: state.providerType,
       });
 
       if (!configResult.ready || !configResult.host || !configResult.port) {
@@ -80,7 +85,9 @@ export async function quickStartPath(
           prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
           process.exit(1);
         }
-      } else {
+        return;
+      }
+
       const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
         host: configResult.host,
         port: configResult.port,
@@ -88,11 +95,14 @@ export async function quickStartPath(
       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,6 +126,11 @@ 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',
@@ -137,14 +142,24 @@ function menuLabel(section: MenuChoice, completed: Set<MenuSection>): string {
     finish: 'Finish & Apply',
   };
   const base = labels[section];
-  const sectionKey: MenuSection =
-    section === 'gateway-config' ? 'gateway' : (section as MenuSection);
-  if (completed.has(sectionKey)) {
+  const sectionKey = menuSectionKey(section);
+  if (sectionKey && 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,
@@ -201,21 +216,25 @@ 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);
@@ -223,6 +242,7 @@ async function runMenuLoop(
         break;
 
       case 'advanced':
+        if (skipCompletedMenuChoice(prompter, completed, choice)) break;
         await runAdvancedSubMenu(prompter, state);
         completed.add('advanced');
         break;
@@ -310,8 +330,11 @@ async function runFinishPath(
     await skillsSelectStage(prompter, state);
   }
 
-  // Finalize (writes configs, links runtime assets, syncs skills)
-  await finalizeStage(prompter, state, configService);
+  // 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,
+  });
 
   // Gateway stages
   if (!options.skipGateway) {
@@ -322,7 +345,7 @@ async function runFinishPath(
         portOverride: options.gatewayPortOverride,
         skipInstall: options.skipGatewayNpmInstall,
         providerKey: state.providerKey,
-        providerType: state.providerType ?? 'none',
+        providerType: state.providerType,
       });
 
       if (configResult.ready && configResult.host && configResult.port) {
@@ -333,12 +356,16 @@ 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();
   }
 }
 
@@ -374,8 +401,11 @@ async function runHeadlessPath(
   // Skills
   await skillsSelectStage(prompter, state);
 
-  // Finalize
-  await finalizeStage(prompter, state, configService);
+  // 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,
+  });
 
   // Gateway stages
   if (!options.skipGateway) {
@@ -386,13 +416,15 @@ async function runHeadlessPath(
         portOverride: options.gatewayPortOverride,
         skipInstall: options.skipGatewayNpmInstall,
         providerKey: state.providerKey,
-        providerType: state.providerType ?? 'none',
+        providerType: state.providerType,
       });
 
       if (!configResult.ready || !configResult.host || !configResult.port) {
         prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
         process.exit(1);
-      } else {
+        return;
+      }
+
       const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
         host: configResult.host,
         port: configResult.port,
@@ -400,12 +432,15 @@ async function runHeadlessPath(
       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();
   }
 }
 
@@ -426,8 +461,11 @@ async function runKeepPath(
   // Skills
   await skillsSelectStage(prompter, state);
 
-  // Finalize
-  await finalizeStage(prompter, state, configService);
+  // 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,
+  });
 
   // Gateway stages
   if (!options.skipGateway) {
@@ -447,11 +485,15 @@ 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

@@ -0,0 +1,222 @@
+#!/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,6 +16,10 @@
 #   --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
@@ -31,6 +35,7 @@
 #   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)
 # ──────────────────────────────────────────────────────────────────────────────
@@ -49,7 +54,12 @@ 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
@@ -61,8 +71,18 @@ 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>] [--dev] [--yes|-y] [--no-auto-launch] [--uninstall]\n' >&2
+  printf 'Usage: install.sh [--check] [--framework] [--cli] [--ref <branch>] [--next] [--dev] [--yes|-y] [--no-auto-launch] [--uninstall]\n' >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -82,9 +102,11 @@ 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 ;;
@@ -96,12 +118,24 @@ 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"
 
@@ -116,6 +150,20 @@ 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.
@@ -179,7 +227,7 @@ if [[ "$FLAG_UNINSTALL" == "true" ]]; then
     # Find most recent backup
     backup=""
     if [[ -d "$dir" ]]; then
-      backup="$(ls -1t "$dir/${base}.mosaic-bak-"* 2>/dev/null | head -1 || true)"
+      backup="$(newest_matching_file "$dir" "${base}.mosaic-bak-*")"
     fi
     if [[ -n "$backup" ]] && [[ -f "$backup" ]]; then
       cp "$backup" "$dest"
@@ -235,6 +283,22 @@ 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() {
@@ -257,10 +321,43 @@ 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];
@@ -353,8 +450,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="$(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)"
+  cli_tgz="$(newest_matching_file "$out_dir" 'mosaicstack-mosaic-*.tgz')"
+  gw_tgz="$(newest_matching_file "$out_dir" 'mosaicstack-gateway-*.tgz')"
 
   if [[ ! -f "$cli_tgz" ]]; then
     fail "CLI tarball was not produced by pnpm pack."
@@ -376,6 +473,49 @@ 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
@@ -409,7 +549,7 @@ if [[ "$FLAG_FRAMEWORK" == "true" ]]; then
   else
     dim "  Installed: (none)"
   fi
-  dim "  Source:    ${REPO_BASE} (ref: ${GIT_REF})"
+  dim "  Source:    ${REPO_BASE} ($(source_ref_details))"
   echo ""
 
   if [[ "$FLAG_CHECK" == "true" ]]; then
@@ -476,8 +616,12 @@ 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
@@ -489,7 +633,19 @@ if [[ "$FLAG_CLI" == "true" ]]; then
   fi
 
   if [[ "$FLAG_DEV" == "true" ]]; then
-    dim "  Source:    ${REPO_BASE} (ref: ${GIT_REF}, build-from-source)"
+    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)"
   elif [[ -n "$LATEST" ]]; then
     dim "  Latest:    ${CLI_PKG}@${LATEST}"
   else
@@ -500,6 +656,12 @@ 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
@@ -516,6 +678,23 @@ 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"
@@ -624,7 +803,7 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
       local base dir backup_path backup_val
       base="$(basename "$dest")"
       dir="$(dirname "$dest")"
-      backup_path="$(ls -1t "$dir/${base}.mosaic-bak-"* 2>/dev/null | head -1 || true)"
+      backup_path="$(newest_matching_file "$dir" "${base}.mosaic-bak-*")"
       if [[ -n "$backup_path" ]]; then
         backup_val="\"$backup_path\""
       else
@@ -649,7 +828,7 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
     NPMRC_LINES_JSON="[\"$MANIFEST_SCOPE_LINE\"]"
   fi
 
-  node -e "
+  if node -e "
     const fs = require('fs');
     const path = require('path');
     const p = process.argv[1];
@@ -674,9 +853,11 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
     "$MANIFEST_CLI_VERSION" \
     "$MANIFEST_FW_VERSION" \
     "$NPMRC_LINES_JSON" \
-    "$RUNTIME_COPIES" 2>/dev/null \
-    && ok "Install manifest written: $MANIFEST_PATH" \
-    || warn "Could not write install manifest (non-fatal)"
+    "$RUNTIME_COPIES" 2>/dev/null; then
+    ok "Install manifest written: $MANIFEST_PATH"
+  else
+    warn "Could not write install manifest (non-fatal)"
+  fi
 
   echo ""
   ok "Done."