ci(publish): serialize workspace-consuming image builds after publish-next-npm (#1411 )

Pipeline 2648 failed build-gateway with ERR_PNPM_OUTDATED_LOCKFILE although publish-next-npm completed green and restored the workspace byte-exact ('git diff clean' in its own log). Root cause: build-gateway and publish-next-npm both depend on [build, verify] and run concurrently; kaniko's COPY of apps/gateway/package.json raced inside publish's in-place mutation window (transform .. publish .. restore). PR 1405's snapshot/restore governs the END state of its own step only — no mutual exclusion against a concurrent reader. The snapshot/restore set was already a superset of the transform's write set (both derive from apps/packages/plugins with the same exclusions — the tasking's apps-coverage hypothesis is refuted by the committed find). The defect is ordering, so the fix is a DAG edge: build-gateway, build-appservice, and build-web each gain publish-next-npm in depends_on, serializing every kaniko workspace consumer after the restore. publish-npm (main-only, transform is next-only) is unchanged. The invariant is stated inline at each edge: any new workspace-consuming step must depend on publish-next-npm. Red-first evidence (clean clone of next; scripts from the committed YAML; gateway manifest as the demonstration case): pre-fix DAG shows build-gateway deps == publish deps (concurrent); post-fix adds the edge. Reading apps/gateway/package.json mid-window shows 0.0.3-next.2648 pins (the 2648 dump shape) and pnpm install --frozen-lockfile fails ERR_PNPM_OUTDATED_LOCKFILE; the same read after restore shows workspace:^ and the identical clean tree installs rc=0. Closes #1411 (blocks PR 1401's merge — USC chain).
fix(ci): restore workspace manifests after publish pin transform (#1404 )
2026-08-24 19:40:24 -05:00 · 2026-08-24 18:38:52 -05:00 · 2026-08-24 23:11:50 +00:00 · 2026-08-24 23:05:37 +00:00 · 2026-08-24 21:43:09 +00:00 · 2026-08-24 20:15:08 +00:00
37 changed files with 3280 additions and 570 deletions
@@ -1,4 +1,11 @@
 {
+  "schema_version": 2,
  "integration_trunk": "next",
-  "release_branch": "main"
+  "release_branch": "main",
+  "flow": "trunk-release",
+  "canonical_remote": "https://git.mosaicstack.dev/mosaicstack/stack",
+  "canonical_clone": "host:/src/mosaic-stack",
+  "worktree_root": "host:/src/mosaic-stack-worktrees",
+  "worktree_policy": "orchestrator-precreated",
+  "notes": "next=development/integration; main=production release. Never branch work off main. worktree_policy is TRANSITIONAL: the wrapper worktree consumer is BLOCKED on the J3/#1174 amendment (checked roots + capacity guard); pre-creation is the interim orchestration choice, not closed policy — it becomes a timing choice only after the wrapper can validate this root."
 }
@@ -100,11 +100,6 @@ steps:
      # repo. Pins that comment BODIES render on both paths and that a tea
      # failure is named as what it was (git-config vs credential).
      - bash packages/mosaic/framework/tools/git/test-issue-view-comments.sh
-      # Hermetic regression for mint-seat-credential.sh (fleet onboarding moved into
-      # the framework): mock curl, sandboxed brain home, no tea, no network. Pins
-      # that the admin seat is configured rather than hardcoded and that the seat
-      # slot is written from the mint response at mode 600.
-      - bash packages/mosaic/framework/tools/fleet/test-mint-seat-credential.sh
      # Hermetic behavioural regression for the PreToolUse wrapper guard: proves
      # it still blocks the three mistakes AND still lets reads, unwrapped
      # endpoints and ordinary commands through. Both directions are asserted —
@@ -118,6 +113,40 @@ steps:
      # stub supplies the scale instead of the host's own checkout.
      - bash packages/mosaic/framework/tools/git/test-mosaic-worktree-large-repo.sh

+  # Canonical repo-structure declaration gate (T51 WP5c, spec §5.4 point 2):
+  # .mosaic/repo.json is the machine-readable structure SSOT consumed by git
+  # wrappers and the T32 gate seat; this is its repo-side CI enforcement.
+  # Path-conditional: runs when the declaration, the vendored validator, or this
+  # pipeline config changes (manual runs always include it). Fails the pipeline
+  # on any VALIDATION_ERROR and enforces the schema_version 2 authoring rule
+  # (--require-v2: edited/new declarations may not stay v1). The validator is
+  # vendored into the framework tree (spec §5.1 final home) — provenance in its
+  # header; the hostile-input suite (101 arms, hermetic) runs alongside so the
+  # gate's own instrument ships in the same commit as the gate.
+  structure-declaration:
+    image: *node_image
+    commands:
+      - apk add --no-cache bash git
+      # MOSAIC_HOST_ROOT is a runtime anchor (spec §1.2a: unset fails closed
+      # for managed validation). CI has no host, so the step provisions an
+      # EXPLICIT fixture root — honest configuration for the resolution path,
+      # never a guess about a real host; the per-host containment checks are
+      # runtime concerns and do not run against a fixture. Grammar, schema,
+      # refs, flow, remote normalization, and path grammar all prove here.
+      - mkdir -p /tmp/t51-ci-hostroot
+      - bash packages/mosaic/framework/tools/structure/validate-repo-json.sh .mosaic/repo.json --require-v2
+      - bash packages/mosaic/framework/tools/structure/test-validate-repo-json.sh
+    environment:
+      MOSAIC_HOST_ROOT: /tmp/t51-ci-hostroot
+    when:
+      - event: pull_request
+        path:
+          include:
+            - '.mosaic/repo.json'
+            - 'packages/mosaic/framework/tools/structure/**'
+            - '.woodpecker/ci.yml'
+      - event: manual
+
  # Canonical verify:release stage `upgrade-guard`.
  # Blocking gate (#791): a framework upgrade must never write or delete an
  # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
@@ -202,6 +202,20 @@ steps:
        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);'
+        # #1404: snapshot every publishable manifest BEFORE the transform so the
+        # workspace can be restored byte-exact after publish. The transform
+        # rewrites package.json in place (needed: pnpm publish reads the
+        # workspace manifests); without restore, later steps in this pipeline
+        # (build-gateway kaniko COPY + pnpm install --frozen-lockfile) see
+        # manifests that no longer match pnpm-lock.yaml and fail
+        # ERR_PNPM_OUTDATED_LOCKFILE. Snapshot dir is step-local tmp.
+        SNAPSHOT_DIR="$(mktemp -d /tmp/publish-next-manifests.XXXXXX)"
+        export SNAPSHOT_DIR
+        find apps packages plugins -name package.json -not -path "*/node_modules/*" -not -path "*/dist/*" | while read -r mf; do
+          mkdir -p "$SNAPSHOT_DIR/$(dirname "$mf")"
+          cp -p "$mf" "$SNAPSHOT_DIR/$mf"
+        done
+        echo "[publish-next] snapshotted $(find "$SNAPSHOT_DIR" -name package.json | wc -l) manifests to $SNAPSHOT_DIR"
        node <<'NODE'
        const fs = require('node:fs');
        const path = require('node:path');
@@ -209,23 +223,38 @@ steps:
        const pipelineNumber = process.env.CI_PIPELINE_NUMBER;
        const roots = ['apps', 'packages', 'plugins'];
        const updated = [];
+        const exactVersions = new Map(); // name -> bumped next version

-        function walk(dir) {
+        function walk(dir, visit) {
          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);
+              if (fs.existsSync(packagePath)) {
+                const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+                if (manifest.name?.startsWith('@mosaicstack/') && !manifest.private) {
+                  visit(manifest, packagePath);
+                }
+              }
+              walk(fullPath, visit);
            }
          }
        }

-        function updatePackage(packagePath) {
-          const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
-          if (!manifest.name?.startsWith('@mosaicstack/') || manifest.private) return;
+        // #1389: two passes. Pass 1 bumps every publishable manifest to
+        // <stable+1>-next.<pipeline> exactly as before, recording name ->
+        // bumped version. Pass 2 rewrites every published manifest's
+        // @mosaicstack/* dependency entries (dependencies, devDependencies,
+        // peerDependencies, optionalDependencies) to the EXACT same-pipeline
+        // build. A caret range like ^0.0.3-next.2636 leaves the resolver free
+        // to pick any later build — and on a host with a stale cache, an
+        // installer-side scaffold pinned at stable, or a registry hiccup, that
+        // freedom is how a "next" install ends up executing stable-era code
+        // (web1 evidence: old tier validator, missing migrations). Exact pins
+        // make the defect class unrepresentable regardless of resolver path.
+        function bump(manifest, packagePath) {
          const stableMatch = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(manifest.version);
          if (!stableMatch) {
            throw new Error(manifest.name + " has unsupported semver version '" + manifest.version + "'");
@@ -234,13 +263,40 @@ steps:
          const oldVersion = manifest.version;
          manifest.version = major + '.' + minor + '.' + (Number(patch) + 1) + '-next.' + pipelineNumber;
          fs.writeFileSync(packagePath, JSON.stringify(manifest, null, 2) + '\n');
+          exactVersions.set(manifest.name, manifest.version);
          updated.push(manifest.name + ' ' + oldVersion + ' -> ' + manifest.version);
        }

-        for (const root of roots) walk(root);
+        const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+        let pinnedEntries = 0;
+        function pin(manifest, packagePath) {
+          let changed = false;
+          for (const field of DEP_FIELDS) {
+            const deps = manifest[field];
+            if (!deps || typeof deps !== 'object') continue;
+            for (const [name, range] of Object.entries(deps)) {
+              if (!name.startsWith('@mosaicstack/')) continue;
+              const exact = exactVersions.get(name);
+              if (!exact) {
+                throw new Error(
+                  manifest.name + ' depends on ' + name +
+                  ' which has no bumped version in this publish set — cannot pin');
+              }
+              if (range === exact) continue;
+              deps[name] = exact;
+              pinnedEntries++;
+              changed = true;
+            }
+          }
+          if (changed) fs.writeFileSync(packagePath, JSON.stringify(manifest, null, 2) + '\n');
+        }
+
+        for (const root of roots) walk(root, bump);
+        for (const root of roots) walk(root, pin);
        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);
+        console.log('[publish-next] pinned ' + pinnedEntries + ' @mosaicstack/* dep entries to exact same-pipeline versions across ' + updated.length + ' manifests');
        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")"
@@ -250,6 +306,94 @@ steps:
          exit 1
        fi
        echo "[publish-next] @mosaicstack/mosaic@next resolves to $RESOLVED_VERSION"
+        # #1389 post-publish guard: every freshly published manifest must carry
+        # EXACT same-pipeline @mosaicstack/* dep pins (no ranges, no stable
+        # fallback). A leak here fails the pipeline instead of shipping.
+        node <<'GUARD'
+        const { execFileSync } = require('node:child_process');
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const pipelineNumber = process.env.CI_PIPELINE_NUMBER;
+        const registry = 'https://git.mosaicstack.dev/api/packages/mosaicstack/npm/';
+        const roots = ['apps', 'packages', 'plugins'];
+        const published = [];
+        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)) {
+                const m = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+                if (m.name?.startsWith('@mosaicstack/') && !m.private) published.push(m.name);
+              }
+              walk(fullPath);
+            }
+          }
+        }
+        for (const root of roots) walk(root);
+        let failures = 0;
+        for (const name of published) {
+          let manifest;
+          try {
+            const out = execFileSync('npm', ['view', name + '@next', '--json', '--registry', registry],
+                                     { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+            const arr = JSON.parse(out);
+            manifest = Array.isArray(arr) ? arr[arr.length - 1] : arr;
+          } catch (e) {
+            console.error('[publish-next-guard] FAIL ' + name + ': npm view failed: ' + e.message);
+            failures++;
+            continue;
+          }
+          const fields = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+          for (const field of fields) {
+            const deps = manifest[field];
+            if (!deps || typeof deps !== 'object') continue;
+            for (const [dep, range] of Object.entries(deps)) {
+              if (!dep.startsWith('@mosaicstack/')) continue;
+              const expected = dep === name ? manifest.version : null;
+              const isExactPin = /^\d+\.\d+\.\d+-next\./.test(range);
+              const samePipeline = range.endsWith('-next.' + pipelineNumber);
+              if (!isExactPin) {
+                console.error('[publish-next-guard] FAIL ' + name + ' -> ' + dep + ' range "' + range + '" is not an exact -next pin (stable-leak class, #1389)');
+                failures++;
+              } else if (!samePipeline) {
+                console.error('[publish-next-guard] FAIL ' + name + ' -> ' + dep + ' pinned "' + range + '" but this pipeline published -next.' + pipelineNumber + ' (cross-pipeline pin)');
+                failures++;
+              }
+            }
+          }
+        }
+        if (failures > 0) {
+          console.error('[publish-next-guard] FATAL: ' + failures + ' dep-pin violation(s) — stable-dep leak into next publish (#1389)');
+          process.exit(1);
+        }
+        console.log('[publish-next-guard] OK: all ' + published.length + ' published manifests carry exact same-pipeline @mosaicstack/* dep pins');
+        GUARD
+        # #1404 restore: put the workspace manifests back byte-exact so later
+        # steps (build-gateway frozen-lockfile install) see the committed tree.
+        RESTORE_FAIL=0
+        while read -r mf; do
+          if [ -f "$SNAPSHOT_DIR/$mf" ]; then
+            cp -p "$SNAPSHOT_DIR/$mf" "$mf"
+          else
+            echo "[publish-next] FATAL: no snapshot for $mf — cannot restore (snapshot incomplete?)" >&2
+            RESTORE_FAIL=1
+          fi
+        done < <(find apps packages plugins -name package.json -not -path "*/node_modules/*" -not -path "*/dist/*")
+        # Pristine guard (#1404 red-first control): the publish step must leave
+        # the workspace byte-identical to the checkout for every manifest.
+        # git diff is the arbiter — any residual mutation fails THIS step
+        # instead of surfacing as ERR_PNPM_OUTDATED_LOCKFILE in build-gateway.
+        if ! git diff --exit-code -- '**/package.json' >/dev/null 2>&1; then
+          echo "[publish-next] FATAL: workspace package.json files still differ from HEAD after restore (#1404 class)" >&2
+          git diff --stat -- '**/package.json' >&2 || true
+          RESTORE_FAIL=1
+        fi
+        rm -rf "$SNAPSHOT_DIR"
+        if [ "$RESTORE_FAIL" -ne 0 ]; then exit 1; fi
+        echo "[publish-next] workspace manifests restored byte-exact (git diff clean); later steps see the committed tree"
    depends_on:
      - build
      - verify
@@ -305,6 +449,14 @@ steps:
    depends_on:
      - build
      - verify
+      # #1411: publish-next-npm mutates workspace manifests in place during
+      # its transform window and restores them at step end. Any step that
+      # reads the pipeline workspace (kaniko COPY of manifests, later
+      # installs) must run AFTER publish-next-npm, never concurrently —
+      # pipeline 2648 raced a COPY inside the window and failed
+      # ERR_PNPM_OUTDATED_LOCKFILE despite a clean restore. This edge is the
+      # serialization invariant; add it to every new workspace consumer.
+      - publish-next-npm

  build-appservice:
    image: gcr.io/kaniko-project/executor:debug
@@ -332,6 +484,14 @@ steps:
    depends_on:
      - build
      - verify
+      # #1411: publish-next-npm mutates workspace manifests in place during
+      # its transform window and restores them at step end. Any step that
+      # reads the pipeline workspace (kaniko COPY of manifests, later
+      # installs) must run AFTER publish-next-npm, never concurrently —
+      # pipeline 2648 raced a COPY inside the window and failed
+      # ERR_PNPM_OUTDATED_LOCKFILE despite a clean restore. This edge is the
+      # serialization invariant; add it to every new workspace consumer.
+      - publish-next-npm

  build-web:
    image: gcr.io/kaniko-project/executor:debug
@@ -359,3 +519,11 @@ steps:
    depends_on:
      - build
      - verify
+      # #1411: publish-next-npm mutates workspace manifests in place during
+      # its transform window and restores them at step end. Any step that
+      # reads the pipeline workspace (kaniko COPY of manifests, later
+      # installs) must run AFTER publish-next-npm, never concurrently —
+      # pipeline 2648 raced a COPY inside the window and failed
+      # ERR_PNPM_OUTDATED_LOCKFILE despite a clean restore. This edge is the
+      # serialization invariant; add it to every new workspace consumer.
+      - publish-next-npm
@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// The module under test imports @mosaicstack/db at module scope; we replace only the
+// pieces DatabaseModule uses (partial mock — the real module also exports the
+// schema the storage adapter's import chain needs) so the test pins the #1392
+// contract (refuse to start on an incomplete schema) without a live database.
+vi.mock('@mosaicstack/db', async (importOriginal) => {
+  const actual: object = await importOriginal();
+  return {
+    ...actual,
+    createDb: vi.fn(),
+    createPgliteDb: vi.fn(),
+    getMigrationStatus: vi.fn(),
+    runPgliteMigrations: vi.fn(),
+  };
+});
+
+import { DatabaseModule } from './database.module.js';
+import { getMigrationStatus } from '@mosaicstack/db';
+import type { DbHandle } from '@mosaicstack/db';
+import type { StorageAdapter } from '@mosaicstack/storage';
+import type { MosaicConfig } from '@mosaicstack/config';
+
+function makeModule(storageType: 'postgres' | 'pglite', tier: string) {
+  const storageAdapter = {
+    name: storageType,
+    migrate: vi.fn(),
+    close: vi.fn(),
+  } as unknown as StorageAdapter;
+  const handle = { close: vi.fn() } as unknown as DbHandle;
+  const config = {
+    tier,
+    storage: { type: storageType, url: 'postgresql://x' },
+  } as unknown as MosaicConfig;
+  return {
+    mod: new DatabaseModule(handle, storageAdapter, config),
+    storageAdapter,
+  };
+}
+
+describe('DatabaseModule.onModuleInit — #1392 schema verification', () => {
+  it('refuses to start when the postgres schema is incomplete', async () => {
+    const { mod, storageAdapter } = makeModule('postgres', 'standalone');
+    vi.mocked(getMigrationStatus).mockResolvedValue({
+      appliedCount: 15,
+      expectedCount: 17,
+      expectedLastTag: '0016_salty_morlocks',
+      complete: false,
+    });
+    await expect(mod.onModuleInit()).rejects.toThrow('Database schema incomplete: 15/17');
+    expect(storageAdapter.migrate).toHaveBeenCalled(); // migrations attempted first
+  });
+
+  it('starts normally when the schema is complete', async () => {
+    const { mod } = makeModule('postgres', 'standalone');
+    vi.mocked(getMigrationStatus).mockResolvedValue({
+      appliedCount: 17,
+      expectedCount: 17,
+      expectedLastTag: '0016_salty_morlocks',
+      complete: true,
+    });
+    await expect(mod.onModuleInit()).resolves.toBeUndefined();
+  });
+
+  it('does not verify postgres status for the local tier (PGlite migrates itself)', async () => {
+    const { mod } = makeModule('pglite', 'local');
+    vi.mocked(getMigrationStatus).mockClear();
+    await expect(mod.onModuleInit()).resolves.toBeUndefined();
+    expect(getMigrationStatus).not.toHaveBeenCalled();
+  });
+});
@@ -12,6 +12,7 @@ import {
 import {
  createDb,
  createPgliteDb,
+  getMigrationStatus,
  runPgliteMigrations,
  type Db,
  type DbHandle,
@@ -74,6 +75,11 @@ export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
  // the same DATABASE_URL, so a single call covers both the gateway DB and
  // the storage tables. We deliberately do NOT call runMigrations() here to
  // avoid opening a second short-lived connection and doubling startup cost.
+  //
+  // #1392: we DO verify afterwards (getMigrationStatus opens one short-lived
+  // connection) and refuse to start on an incomplete schema. A gateway that
+  // boots "healthy" on an empty or partial database is precisely the failure
+  // that shipped in the T63 batch: silent at startup, catastrophic later.
  async onModuleInit(): Promise<void> {
    if (this.config.tier === 'local') {
      this.logger.log('Applying PGlite schema migrations...');
@@ -81,6 +87,24 @@ export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
    }
    this.logger.log(`Initializing storage adapter (${this.storageAdapter.name})...`);
    await this.storageAdapter.migrate();
+
+    if (this.config.storage.type === 'postgres') {
+      const status = await getMigrationStatus(this.config.storage.url);
+      if (!status.complete) {
+        this.logger.error(
+          `Database schema incomplete: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied ` +
+            `(last expected: ${status.expectedLastTag}). ` +
+            'Refusing to start on a partial schema — see issues #1392/#1402. ' +
+            "Remediation: re-run 'mosaic gateway install' (it now verifies), or apply migrations manually.",
+        );
+        throw new Error(
+          `Database schema incomplete: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied`,
+        );
+      }
+      this.logger.log(
+        `Database schema verified: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied.`,
+      );
+    }
  }

  async onApplicationShutdown(): Promise<void> {
@@ -1,6 +1,15 @@
 export { createDb, type Db, type DbHandle } from './client.js';
 export { createPgliteDb } from './client-pglite.js';
-export { runMigrations, runPgliteMigrations } from './migrate.js';
+export {
+  runMigrations,
+  runPgliteMigrations,
+  getMigrationStatus,
+  readJournalTags,
+  applyMigrationsByHash,
+  type HashLedgerDeps,
+  type MigrationPlanEntry,
+  type MigrationStatus,
+} from './migrate.js';
 export * from './schema.js';
 export * from './federation.js';
 export {
@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  applyMigrationsByHash,
+  readJournalTags,
+  type HashLedgerDeps,
+  type MigrationPlanEntry,
+} from './migrate.js';
+
+/* ------------------------------------------------------------------ */
+/*  In-memory hash-ledger harness                                      */
+/* ------------------------------------------------------------------ */
+
+interface LedgerHarness extends HashLedgerDeps {
+  ledger: Map<string, number>;
+  /** Recorded statement executions in order: `${hashPrefix}:${stmtIndex}`. */
+  executed: string[];
+  /** Optional: statements that should throw when executed. */
+  failOn?: (migrationHash: string, stmtIdx: number) => boolean;
+}
+
+function makeHarness(plan: MigrationPlanEntry[]): LedgerHarness {
+  const hashToEntry = new Map(plan.map((p) => [p.hash, p]));
+  const h: LedgerHarness = {
+    ledger: new Map(),
+    executed: [],
+    ensureLedger: async () => {},
+    appliedHashes: async () => [...h.ledger.keys()],
+    recordApplied: async (hash, folderMillis) => {
+      h.ledger.set(hash, folderMillis);
+    },
+    runStatement: async (statement) => {
+      void statement;
+      // runStatement does not know which migration it belongs to; the
+      // executed log is filled by the wrapper below.
+    },
+  };
+  // Wrap runStatement so the executed log records migration context. We
+  // reconstruct context by tracking a cursor the core advances per migration.
+  let cursor = 0;
+  const flat: Array<{ hash: string; idx: number }> = [];
+  for (const m of plan)
+    for (const [i] of m.statements.entries()) flat.push({ hash: m.hash, idx: i });
+  h.runStatement = async () => {
+    const at = flat[cursor] ?? { hash: '??', idx: -1 };
+    cursor += 1;
+    if (h.failOn && at.hash !== '??' && h.failOn(at.hash, at.idx)) {
+      throw new Error(`simulated failure in ${at.hash} #${at.idx.toString()}`);
+    }
+    h.executed.push(`${at.hash.slice(0, 6)}:${at.idx.toString()}`);
+  };
+  void hashToEntry;
+  return h;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Fixtures                                                           */
+/* ------------------------------------------------------------------ */
+
+// Reproduces the REAL journal defect shape (#1402 D1): 0009/0010 carry
+// `when` timestamps BELOW 0008's. Under the old drizzle postgres-js
+// migrator these were silently skipped on any upgrade whose ledger was
+// last stamped in the 0008 era.
+const JOURNAL_FIXTURE: MigrationPlanEntry[] = [
+  { hash: 'aaaa0000', folderMillis: 1773368153122, statements: ['CREATE TABLE a (id int)'] },
+  { hash: 'bbbb0008', folderMillis: 1776822435828, statements: ['CREATE TABLE b (id int)'] },
+  // Backdated entries, exactly as shipped:
+  {
+    hash: 'cccc0009',
+    folderMillis: 1745280000000,
+    statements: ['ALTER TYPE t ADD VALUE', "CREATE TABLE c (s t DEFAULT 'pending')"],
+  },
+  { hash: 'dddd0010', folderMillis: 1745366400000, statements: ['CREATE TABLE d (id int)'] },
+];
+
+/** A ledger last stamped at the 0008 era: only pre-0009 hashes recorded. */
+const LEDGER_AT_0008_ERA = new Map<string, number>([
+  ['aaaa0000', 1773368153122],
+  ['bbbb0008', 1776822435828],
+]);
+
+/* ------------------------------------------------------------------ */
+/*  The core: apply-by-hash in journal order                           */
+/* ------------------------------------------------------------------ */
+
+describe('applyMigrationsByHash', () => {
+  it('applies backdated journal entries that a timestamp-based migrator would skip (#1402 D1)', async () => {
+    const h = makeHarness(JOURNAL_FIXTURE);
+    h.ledger = new Map(LEDGER_AT_0008_ERA);
+
+    const result = await applyMigrationsByHash(h, JOURNAL_FIXTURE);
+
+    // D1 in one sentence: 0009 and 0010 applied despite folderMillis < 0008.
+    expect(result).toEqual({ applied: 2, skipped: 2 });
+    expect(h.ledger.has('cccc0009')).toBe(true);
+    expect(h.ledger.has('dddd0010')).toBe(true);
+  });
+
+  it('executes statements individually (ALTER TYPE visibility, #1402 D2 shape)', async () => {
+    const h = makeHarness(JOURNAL_FIXTURE);
+    await applyMigrationsByHash(h, JOURNAL_FIXTURE);
+    // 0009's two statements recorded as separate executions, in order.
+    expect(h.executed).toContain('cccc00:0');
+    expect(h.executed).toContain('cccc00:1');
+    expect(h.executed.indexOf('cccc00:0')).toBeLessThan(h.executed.indexOf('cccc00:1'));
+  });
+
+  it('is idempotent: a fully-applied ledger applies nothing', async () => {
+    const h = makeHarness(JOURNAL_FIXTURE);
+    const first = await applyMigrationsByHash(h, JOURNAL_FIXTURE);
+    const second = await applyMigrationsByHash(h, JOURNAL_FIXTURE);
+    expect(first.applied).toBe(4);
+    expect(second).toEqual({ applied: 0, skipped: 4 });
+    expect(h.executed).toHaveLength(5); // 5 statements; second run executed NONE (not 10)
+  });
+
+  it('records no ledger row when a statement fails (crash prefix replays loudly)', async () => {
+    const h = makeHarness(JOURNAL_FIXTURE);
+    h.failOn = (hash, idx) => hash === 'cccc0009' && idx === 1;
+
+    await expect(applyMigrationsByHash(h, JOURNAL_FIXTURE)).rejects.toThrow(
+      /cccc0009 statement #1 failed: simulated failure/,
+    );
+    // Statement 0 of 0009 executed, but NO ledger row for 0009: the next run
+    // replays it and fails loudly on "already exists" instead of silently
+    // believing 0009 applied.
+    expect(h.ledger.has('cccc0009')).toBe(false);
+    expect(h.executed).toContain('cccc00:0');
+  });
+
+  it('applies in JOURNAL order, not timestamp order', async () => {
+    const h = makeHarness(JOURNAL_FIXTURE);
+    await applyMigrationsByHash(h, JOURNAL_FIXTURE);
+    // 5 statements total (0009 has two); prefix per migration: journal order,
+    // so 0009's pair sits between 0008 and 0010.
+    const order = h.executed.map((e) => e.slice(0, 4));
+    expect(order).toEqual(['aaaa', 'bbbb', 'cccc', 'cccc', 'dddd']);
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/*  Journal integrity against the shipped folder                       */
+/* ------------------------------------------------------------------ */
+
+describe('readJournalTags', () => {
+  it('reads the shipped journal in order and sees the known backdated pair', () => {
+    const folder = resolve(__dirname, '../drizzle');
+    const tags = readJournalTags(folder);
+    expect(tags.length).toBeGreaterThan(0);
+    // The shipped defect (#1402 D1): these two entries carry April-2025
+    // timestamps below 0008's June-2026 one. If this assertion ever fails
+    // because the journal was FIXED (timestamps corrected or drizzle-kit
+    // regenerated), update #1402 — the hash-ledger core stays correct either
+    // way; this test pins the shipped reality the core was built for.
+    const t9 = tags.find((t) => t.startsWith('0009_'));
+    const t10 = tags.find((t) => t.startsWith('0010_'));
+    const t8 = tags.find((t) => t.startsWith('0008_'));
+    expect([t8, t9, t10]).toBeDefined();
+    const journal = JSON.parse(readFileSync(resolve(folder, 'meta', '_journal.json'), 'utf8')) as {
+      entries: Array<{ tag: string; when: number }>;
+    };
+    const when = new Map(journal.entries.map((e) => [e.tag, e.when]));
+    if (t8 && t9 && t10) {
+      expect(when.get(t9)!).toBeLessThan(when.get(t8)!); // backdated below 0008
+      expect(when.get(t10)!).toBeLessThan(when.get(t8)!); // backdated below 0008
+    }
+  });
+});
@@ -1,8 +1,7 @@
+import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { sql } from 'drizzle-orm';
-import { drizzle as drizzlePostgres } from 'drizzle-orm/postgres-js';
-import { migrate as migratePostgres } from 'drizzle-orm/postgres-js/migrator';
 import { readMigrationFiles } from 'drizzle-orm/migrator';
 import postgres from 'postgres';
 import { DEFAULT_DATABASE_URL } from './defaults.js';
@@ -21,89 +20,243 @@ function migrationsFolder(): string {
  return resolve(here, '../drizzle');
 }

+/* ------------------------------------------------------------------ */
+/*  Shared hash-ledger migration core (#1392 / #1402)                  */
+/* ------------------------------------------------------------------ */
+//
+// Both tiers migrate through this single core, which applies migrations in
+// JOURNAL ORDER, one statement at a time, and skips by HASH — never by
+// folderMillis timestamp. The previous postgres path delegated to drizzle's
+// postgres-js migrator, which:
+//
+//   * applies only migrations with folderMillis > last-applied, silently
+//     skipping journal entries whose `when` is older than the ledger's newest
+//     stamp — 0009/0010 carry April-2025 timestamps below 0008's June-2026
+//     one, so any database last migrated in the 0008 era silently loses
+//     0009/0010 forever (#1402 D1); and
+//   * wraps each migration in ONE transaction, which breaks migrations that
+//     do `ALTER TYPE ADD VALUE` and then reference the new value in the same
+//     migration (0009) — Postgres' check_safe_enum_use rejects it (#1402 D2).
+//
+// Per-statement execution (each statement autocommits) and skip-by-hash fix
+// both. The PGlite path has run this way since it was written; this is the
+// TODO it left behind, now shared instead of duplicated.
+
+/** One migration as loaded from the shipped drizzle/ folder. */
+export interface MigrationPlanEntry {
+  hash: string;
+  folderMillis: number;
+  statements: string[];
+}
+
+/** The persistence operations the hash-ledger core needs, per tier. */
+export interface HashLedgerDeps {
+  /** Create the drizzle schema + ledger table if absent (idempotent). */
+  ensureLedger(): Promise<void>;
+  /** Hashes already recorded in the ledger. */
+  appliedHashes(): Promise<string[]>;
+  /** Record one fully-applied migration in the ledger. */
+  recordApplied(hash: string, folderMillis: number): Promise<void>;
+  /** Execute one SQL statement, autocommitting (never inside a wider tx). */
+  runStatement(statement: string): Promise<void>;
+}
+
+function loadPlan(): MigrationPlanEntry[] {
+  return readMigrationFiles({ migrationsFolder: migrationsFolder() }).map((m) => ({
+    hash: m.hash,
+    folderMillis: m.folderMillis,
+    statements: m.sql.map((s) => s.trim()).filter((s) => s.length > 0),
+  }));
+}
+
+/**
+ * Apply every unapplied migration in journal order, skipping by hash.
+ *
+ * Failure model: each statement autocommits, and the ledger row is written
+ * only after all statements of a migration succeed. A crash mid-migration
+ * leaves the prefix applied with no ledger entry, so the next boot replays
+ * those statements and fails loudly on "already exists". Recovery: drop the
+ * partially-applied objects, or insert the migration's hash into
+ * `drizzle.__drizzle_migrations` manually. The thrown error identifies the
+ * statement and migration that failed.
+ */
+export async function applyMigrationsByHash(
+  deps: HashLedgerDeps,
+  plan: MigrationPlanEntry[] = loadPlan(),
+): Promise<{ applied: number; skipped: number }> {
+  await deps.ensureLedger();
+  const alreadyApplied = new Set(await deps.appliedHashes());
+
+  let applied = 0;
+  let skipped = 0;
+  for (const migration of plan) {
+    if (alreadyApplied.has(migration.hash)) {
+      skipped += 1;
+      continue;
+    }
+    for (const [stmtIdx, stmt] of migration.statements.entries()) {
+      try {
+        await deps.runStatement(stmt);
+      } catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `migration hash=${migration.hash} statement #${stmtIdx} failed: ${cause}\n` +
+            `Statement: ${stmt.slice(0, 200)}${stmt.length > 200 ? '…' : ''}`,
+          { cause: err },
+        );
+      }
+    }
+    await deps.recordApplied(migration.hash, migration.folderMillis);
+    applied += 1;
+  }
+  return { applied, skipped };
+}
+
+const LEDGER_DDL = [
+  'CREATE SCHEMA IF NOT EXISTS drizzle',
+  `CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
+      id SERIAL PRIMARY KEY,
+      hash text NOT NULL,
+      created_at bigint
+    )`,
+];
+
+function connectionString(url?: string): string {
+  return url ?? process.env['DATABASE_URL'] ?? DEFAULT_DATABASE_URL;
+}
+
+/**
+ * Apply Drizzle migrations against a postgres database, hash-ledger style.
+ * Idempotent: re-running against a fully-migrated database applies nothing.
+ */
 export async function runMigrations(url?: string): Promise<void> {
-  const connectionString = url ?? process.env['DATABASE_URL'] ?? DEFAULT_DATABASE_URL;
-  const sqlClient = postgres(connectionString, { max: 1 });
-  const db = drizzlePostgres(sqlClient);
+  const sqlClient = postgres(connectionString(url), { max: 1 });
  try {
-    // TODO: postgres-tier first-install also fails because (a) Drizzle wraps every
-    // migration in one transaction (breaks 0009's ALTER TYPE ADD VALUE → SET DEFAULT
-    // sequence) and (b) drizzle/meta/_journal.json has 0009 ordered before 0008,
-    // which the postgres-js migrator skips by `created_at < folderMillis`. The
-    // PGlite path below sidesteps both. A follow-up should either share the
-    // per-statement loop (see runPgliteMigrations) or fix the journal ordering.
-    await migratePostgres(db, { migrationsFolder: migrationsFolder() });
+    await applyMigrationsByHash({
+      ensureLedger: async () => {
+        for (const ddl of LEDGER_DDL) await sqlClient.unsafe(ddl);
+      },
+      appliedHashes: async () => {
+        const rows = (await sqlClient.unsafe(
+          'SELECT hash FROM drizzle.__drizzle_migrations',
+        )) as Array<{ hash: string }>;
+        return rows.map((r) => String(r.hash));
+      },
+      recordApplied: async (hash, folderMillis) => {
+        await sqlClient.unsafe(
+          'INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES ($1, $2)',
+          [hash, folderMillis],
+        );
+      },
+      runStatement: async (stmt) => {
+        await sqlClient.unsafe(stmt);
+      },
+    });
  } finally {
    await sqlClient.end();
  }
 }

-// Apply Drizzle migrations against an embedded PGlite database.
-//
-// We don't reuse drizzle's pglite migrator because it wraps ALL migrations in
-// one outer transaction, which breaks Postgres' `check_safe_enum_use` rule —
-// e.g. migration 0009 does `ALTER TYPE ADD VALUE 'pending'` then references
-// `'pending'` as a default in the same tx. PGlite's `exec()` runs each
-// statement under the Simple Query protocol, autocommitting between them.
-//
-// We still write to the standard `drizzle.__drizzle_migrations` ledger so the
-// result is interoperable with `runMigrations()` on a postgres-backed deploy
-// (modulo the journal-ordering bug noted above).
-//
-// We skip-by-hash rather than skip-by-folderMillis (which is what Drizzle's
-// postgres-js migrator does). That's deliberate — out-of-order timestamps in
-// `_journal.json` won't silently drop migrations.
-//
-// Failure model: each statement autocommits, and the ledger row is written
-// only after all statements in a migration succeed. A crash mid-migration
-// leaves the prefix applied with no ledger entry, so the next boot will
-// replay those statements and fail loudly on "already exists". Recovery:
-// drop the partially-applied objects, or insert the migration's hash into
-// `drizzle.__drizzle_migrations` manually. The error log identifies which
-// statement of which migration was the culprit.
+/**
+ * Apply Drizzle migrations against an embedded PGlite database.
+ *
+ * We don't reuse drizzle's pglite migrator for the same reasons as the
+ * postgres path (single-transaction wrap; folderMillis skip). PGlite's
+ * `exec()` runs each statement under the Simple Query protocol,
+ * autocommitting between them — exactly the semantics the shared core needs.
+ *
+ * The ledger rows this writes are interoperable with the postgres path (same
+ * schema, same hashes), because both consume the same shipped migrations.
+ */
 export async function runPgliteMigrations(handle: DbHandle): Promise<void> {
  const client = (handle.db as unknown as { $client?: PgliteExecutor }).$client;
  if (!client || typeof client.exec !== 'function') {
    throw new Error('runPgliteMigrations: handle.db is not backed by a PGlite client');
  }

-  await client.exec('CREATE SCHEMA IF NOT EXISTS drizzle');
-  await client.exec(`
-    CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
-      id SERIAL PRIMARY KEY,
-      hash text NOT NULL,
-      created_at bigint
-    )
-  `);
+  await applyMigrationsByHash({
+    ensureLedger: async () => {
+      for (const ddl of LEDGER_DDL) await client.exec(ddl);
+    },
+    appliedHashes: async () => {
+      const rows = (await handle.db.execute(
+        sql`SELECT hash FROM drizzle.__drizzle_migrations`,
+      )) as unknown as ExecuteRows<{ hash: string }>;
+      return rows.rows.map((r) => String(r.hash));
+    },
+    recordApplied: async (hash, folderMillis) => {
+      await handle.db.execute(
+        sql`INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES (${hash}, ${folderMillis})`,
+      );
+    },
+    runStatement: async (stmt) => {
+      await client.exec(stmt);
+    },
+  });
+}

-  const appliedRows = (await handle.db.execute(
-    sql`SELECT hash FROM drizzle.__drizzle_migrations`,
-  )) as unknown as ExecuteRows<{ hash: string }>;
-  const applied = new Set(appliedRows.rows.map((r) => r.hash));
+/* ------------------------------------------------------------------ */
+/*  Migration status (#1392: the installer must VERIFY, not assume)     */
+/* ------------------------------------------------------------------ */

-  const migrations = readMigrationFiles({ migrationsFolder: migrationsFolder() });
-  for (const migration of migrations) {
-    if (applied.has(migration.hash)) continue;
+/** Read the journal tags (migration folder names) in journal order. */
+export function readJournalTags(folder: string = migrationsFolder()): string[] {
+  const journal = JSON.parse(readFileSync(resolve(folder, 'meta', '_journal.json'), 'utf8')) as {
+    entries?: Array<{ tag?: string }>;
+  };
+  return (journal.entries ?? []).map((e) => e.tag ?? '').filter((t) => t.length > 0);
+}

-    // Run each statement-breakpoint chunk in its own exec() call so PGlite
-    // commits between statements — this is what lets `ALTER TYPE ADD VALUE`
-    // become visible before a subsequent statement references the new value.
-    for (const [stmtIdx, stmt] of migration.sql.entries()) {
-      const trimmed = stmt.trim();
-      if (!trimmed) continue;
-      try {
-        await client.exec(trimmed);
-      } catch (err) {
-        const cause = err instanceof Error ? err.message : String(err);
-        throw new Error(
-          `runPgliteMigrations: migration hash=${migration.hash} statement #${stmtIdx} failed: ${cause}\n` +
-            `Statement: ${trimmed.slice(0, 200)}${trimmed.length > 200 ? '…' : ''}`,
-          { cause: err },
-        );
-      }
+export interface MigrationStatus {
+  /** Hashes recorded in the database's ledger (0 if no ledger exists). */
+  appliedCount: number;
+  /** Migrations shipped in this package's drizzle/ folder. */
+  expectedCount: number;
+  /** The tag (folder name) of the last journal entry, for error messages. */
+  expectedLastTag: string;
+  /** True iff every shipped migration's hash is in the ledger. */
+  complete: boolean;
+}
+
+/**
+ * Report whether a postgres database carries the full shipped schema.
+ *
+ * Read-only apart from `ensureLedger` semantics: it never creates the ledger
+ * (unlike the migrators), so a database with NO ledger reports
+ * appliedCount=0 / complete=false — the exact #1392/#1389 signature (an
+ * install whose dependency set shipped no migrations at all).
+ */
+export async function getMigrationStatus(url?: string): Promise<MigrationStatus> {
+  const sqlClient = postgres(connectionString(url), { max: 1 });
+  try {
+    const plan = loadPlan();
+    const tags = readJournalTags();
+    const expectedHashes = new Set(plan.map((m) => m.hash));
+
+    let appliedHashes: string[] = [];
+    const regRows = (await sqlClient.unsafe(
+      "SELECT to_regclass('drizzle.__drizzle_migrations') AS reg",
+    )) as Array<{ reg: string | null }>;
+    if (regRows[0]?.reg) {
+      const rows = (await sqlClient.unsafe(
+        'SELECT hash FROM drizzle.__drizzle_migrations',
+      )) as Array<{ hash: string }>;
+      appliedHashes = rows.map((r) => String(r.hash));
    }
-    await handle.db.execute(
-      sql`INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES (${migration.hash}, ${migration.folderMillis})`,
-    );
+
+    const appliedSet = new Set(appliedHashes);
+    return {
+      appliedCount: appliedHashes.length,
+      expectedCount: plan.length,
+      expectedLastTag: tags[tags.length - 1] ?? '',
+      complete:
+        plan.length > 0 &&
+        plan.every((m) => appliedSet.has(m.hash)) &&
+        // A ledger with entries OUTSIDE the shipped plan means the database
+        // came from a different (e.g. newer) build — not "complete" either.
+        appliedHashes.every((h) => expectedHashes.has(h)),
+    };
+  } finally {
+    await sqlClient.end();
  }
 }
@@ -111,7 +111,7 @@ approve path carries the trap.) `pr-review.sh` sends the correct token for the d
 Whatever you use, re-read `GET /pulls/{n}/reviews` and assert the state before reporting a verdict
 placed.

-The guard exits nonzero for any provider-asserted non-green, missing, or malformed CI state. If credentials or the provider are unavailable, it emits `CANNOT_ASSERT` and writes a JSONL audit record. Push degrades to exit 0 so recovery work is not bricked; merge holds with retryable exit 75 until the provider recovers, then self-clears without manual reset. Neither outcome is evidence that CI was clear. `pr-merge.sh` automatically inspects the exact PR head repository and full commit SHA rather than its `main` base; this also handles fork PRs without branch-name ambiguity. Pass `--expect-head <approved-full-sha>` to bind a commit-specific review or merge-gate verdict; Gitea uses atomic `head_commit_id` and GitHub uses `--match-head-commit`.
+The guard exits nonzero for any provider-asserted non-green, missing, or malformed CI state. If credentials or the provider are unavailable, it emits `CANNOT_ASSERT` and writes a JSONL audit record. Push degrades to exit 0 so recovery work is not bricked; merge holds with retryable exit 75 until the provider recovers, then self-clears without manual reset. Neither outcome is evidence that CI was clear. For a repository with no CI configured at all, `pr-merge.sh --no-ci-expected` is the sanctioned merge path: it forwards to `ci-queue-wait.sh --no-ci-expected`, which reclassifies a zero-context merge head as queue-clear only when the acting token holds repository admin and `MOSAIC_GIT_IDENTITY` names the asserting identity (a caller without one is refused with exit 78 before the admin lookup), and records the assertion (or its refusal) in the same JSONL audit log. `pr-merge.sh` automatically inspects the exact PR head repository and full commit SHA rather than its `main` base; this also handles fork PRs without branch-name ambiguity. Pass `--expect-head <approved-full-sha>` to bind a commit-specific review or merge-gate verdict; Gitea uses atomic `head_commit_id` and GitHub uses `--match-head-commit`.

 ### Code Review (Codex)

@@ -219,6 +219,23 @@ Multi-instance support: `-a <instance>` selects a named instance (e.g. `personal
 ~/.config/mosaic/tools/health/stack-health.sh -f json
 ```

+### Repo Structure Declaration (T51)
+
+```bash
+# Validate a .mosaic/repo.json declaration (schema v1/v2, host:/ grammar,
+# ref grammar, cross-field rules, remote normalization; spec §5)
+~/.config/mosaic/tools/structure/validate-repo-json.sh <repo>/.mosaic/repo.json
+
+# CI authoring rule: new/edited declarations must be schema_version 2
+~/.config/mosaic/tools/structure/validate-repo-json.sh <repo>/.mosaic/repo.json --require-v2
+
+# Display mode (warns and omits root-dependent checks when MOSAIC_HOST_ROOT unset)
+~/.config/mosaic/tools/structure/validate-repo-json.sh <repo>/.mosaic/repo.json --mode display
+
+# Hermetic hostile-input suite (101 arms)
+~/.config/mosaic/tools/structure/test-validate-repo-json.sh
+```
+
 ### Shared Credential Loader

 ```bash
@@ -379,8 +379,54 @@ check_fleet_transport() {
  fi
 }

+check_structure_anchor_provisioning() {
+  # T51 WP0b (spec §1.2a + PHASE2-MAP F7): audit the two declaration anchors.
+  # Doctor runs from operator shells and CI where the launcher exports do not
+  # exist, so this is an AUDIT ONLY — it never exports, writes, or fabricates
+  # values for consumption. Four states (charter):
+  #   both present+nonempty  PASS (values reported as paths only)
+  #   one missing/empty     WARN naming the var + the launcher as authority
+  #   neither present       INFORMATIONAL launcher-equivalent derivation,
+  #                         explicitly non-authoritative, + launcher warning;
+  #                         never an error by design (F7(b))
+  # Severity follows the doctor's existing conventions: pass/note are quiet
+  # (note unless --verbose), warn counts toward --fail-on-warn.
+  local host_root="${MOSAIC_HOST_ROOT:-}" brain_home="${MOSAIC_BRAIN_HOME:-}"
+  # T51P2WP0BRW B1: presence is tracked SEPARATELY from value — `${VAR:-}`
+  # collapses exported-empty into genuinely-unset, which mis-filed both-empty
+  # and the mixed empty/unset states as informational. Only BOTH-genuinely-
+  # absent may be informational (charter state 3); any present-but-empty or
+  # single-present state warns.
+  local host_set=0 brain_set=0
+  [[ -v MOSAIC_HOST_ROOT ]]  && host_set=1
+  [[ -v MOSAIC_BRAIN_HOME ]] && brain_set=1
+  if [[ "$host_set" -eq 1 && "$brain_set" -eq 1 && -n "$host_root" && -n "$brain_home" ]]; then
+    pass "Structure anchors provisioned: MOSAIC_HOST_ROOT=$host_root MOSAIC_BRAIN_HOME=$brain_home (paths reported only; not expanded, not consumed)"
+    return
+  fi
+  if [[ "$host_set" -eq 0 && "$brain_set" -eq 0 ]]; then
+    note "Structure anchors not provisioned in this environment. Launcher-equivalent derivation (INFORMATIONAL, NON-AUTHORITATIVE — seats receive the authoritative values from the launchers): MOSAIC_HOST_ROOT would default to the operator home; MOSAIC_BRAIN_HOME would default to the brain tree resolved at launch. Doctor does not guess values for consumption; it audits provisioning."
+    note "Provision both anchors via the seat launchers (launch-seat.sh / launch-seat-claude.sh export them; see T51 spec §1.2a)."
+    return
+  fi
+  # At least one variable is present (possibly empty), or exactly one exists:
+  # every missing/empty anchor gets its own loud WARN naming the launchers.
+  if [[ "$host_set" -eq 0 ]]; then
+    warn "MOSAIC_HOST_ROOT is not set in this environment while MOSAIC_BRAIN_HOME is — declaration consumers fail closed without it (spec §1.2a). The seat launchers are the authoritative source."
+  elif [[ -z "$host_root" ]]; then
+    warn "MOSAIC_HOST_ROOT is present but EMPTY in this environment — declaration consumers fail closed without a usable value (spec §1.2a). The seat launchers are the authoritative source."
+  fi
+  if [[ "$brain_set" -eq 0 ]]; then
+    warn "MOSAIC_BRAIN_HOME is not set in this environment while MOSAIC_HOST_ROOT is — the projects/ mirror and brain declaration resolve from it (spec §1.2a). The seat launchers are the authoritative source."
+  elif [[ -z "$brain_home" ]]; then
+    warn "MOSAIC_BRAIN_HOME is present but EMPTY in this environment — the projects/ mirror and brain declaration resolve from it (spec §1.2a). The seat launchers are the authoritative source."
+  fi
+}
+
 check_fleet_transport

+check_structure_anchor_provisioning
+
 check_brain_home

 # Legacy migration surfaces should no longer contain symlink trees.
@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# Covers the structure-anchor provisioning check in `mosaic-doctor` (T51 WP0b).
+#
+# Same discipline as test-brain-home-check.sh: functions are extracted from the
+# shipped script (exact header + closing brace), never copied — a test carrying
+# its own copy of the logic keeps passing after the shipped copy changes.
+#
+# Four contract states (charter T51P2WP0B-20260824):
+#   1. both present+nonempty      -> pass ([OK]), no warns, no notes
+#   2a. host missing, brain set   -> warn naming MOSAIC_HOST_ROOT + launchers
+#   2b. brain missing, host set   -> warn naming MOSAIC_BRAIN_HOME + launchers
+#   2c. present-but-EMPTY counts as missing (warns; NEVER informational)
+#   3. neither present            -> informational notes, NON-AUTHORITATIVE, never warn
+# Arms include genuinely-UNSET (env -u) forms, not only empty strings.
+# Red control: empty-vs-unset distinction removed in a mutated copy -> suite red.
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname "$0")" && pwd)
+DOCTOR="$SCRIPT_DIR/mosaic-doctor"
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+[ -f "$DOCTOR" ] || fail "missing mosaic-doctor at $DOCTOR"
+
+extract_function() {
+  local name="$1"
+  local extracted
+  extracted=$(sed -n "/^${name}() {/,/^}/p" "$DOCTOR")
+  [ -n "$extracted" ] || fail "could not extract ${name}() from mosaic-doctor — script reshaped?"
+  printf '%s\n' "$extracted"
+}
+
+for fn in check_structure_anchor_provisioning; do
+  extract_function "$fn" >/dev/null
+done
+
+# run_case LABEL EXPECT(ok|warn|note) [env assignments as args; -u VAR tokens for unset]
+run_case() {
+  local label="$1" expect="$2"
+  shift 2
+  local envs=() unsets=()
+  local a
+  for a in "$@"; do
+    case "$a" in
+      -u:*) unsets+=("${a#-u:}") ;;
+      *) envs+=("$a") ;;
+    esac
+  done
+  local out warns notes oks
+  # build the env command with proper -u flags (array expansion must not
+  # glue '-u VAR' into one word)
+  local cmd=(env)
+  local e u
+  # env(1) parses options only before the first assignment — -u flags FIRST
+  for u in "${unsets[@]:-}"; do [ -n "$u" ] && cmd+=(-u "$u"); done
+  for e in "${envs[@]:-}"; do [ -n "$e" ] && cmd+=("$e"); done
+  cmd+=(bash -c "warn() { echo \"[WARN] \$*\"; }; note() { echo \"[NOTE] \$*\"; return 0; }; pass() { echo \"[OK] \$*\"; return 0; }; $(extract_function check_structure_anchor_provisioning); check_structure_anchor_provisioning")
+  out=$("${cmd[@]}" 2>&1)
+  warns=$(printf '%s\n' "$out" | grep -c '^\[WARN\]' || true)
+  notes=$(printf '%s\n' "$out" | grep -c '^\[NOTE\]' || true)
+  oks=$(printf '%s\n' "$out" | grep -c '^\[OK\]' || true)
+  if [[ "$expect" == ok && "$oks" -gt 0 && "$warns" -eq 0 && "$notes" -eq 0 ]]; then
+    echo "ok - $label"
+  elif [[ "$expect" == warn && "$warns" -ge 1 && "$notes" -eq 0 ]]; then
+    echo "ok - $label (warned x$warns)"
+  elif [[ "$expect" == note && "$notes" -gt 0 && "$warns" -eq 0 ]]; then
+    echo "ok - $label (noted)"
+  else
+    echo "output: $out" >&2
+    fail "$label: expected $expect (oks=$oks warns=$warns notes=$notes)"
+  fi
+}
+
+ROOT=$(mktemp -d)
+trap 'rm -rf "$ROOT"' EXIT
+HOST="$ROOT/host"
+BRAIN="$ROOT/brain"
+
+# ── state 1: both present + nonempty → pass ────────────────────────────────
+run_case "both anchors present passes" ok \
+  MOSAIC_HOST_ROOT="$HOST" MOSAIC_BRAIN_HOME="$BRAIN"
+
+# ── state 2a: host missing (unset), brain set → exactly one warn ───────────
+run_case "unset host root warns" warn \
+  -u:MOSAIC_HOST_ROOT MOSAIC_BRAIN_HOME="$BRAIN"
+
+# ── state 2b: brain missing (unset), host set → exactly one warn ───────────
+run_case "unset brain home warns" warn \
+  MOSAIC_HOST_ROOT="$HOST" -u:MOSAIC_BRAIN_HOME
+
+# ── state 2c-empty: present-but-empty counts as missing ────────────────────
+run_case "empty-string host root warns (empty != set)" warn \
+  MOSAIC_HOST_ROOT= MOSAIC_BRAIN_HOME="$BRAIN"
+run_case "empty-string brain home warns (empty != set)" warn \
+  MOSAIC_HOST_ROOT="$HOST" MOSAIC_BRAIN_HOME=
+
+# ── state 3: neither present (genuinely unset) → notes, never warn ─────────
+run_case "both unset yields non-authoritative notes" note \
+  -u:MOSAIC_HOST_ROOT -u:MOSAIC_BRAIN_HOME
+run_case "both empty-string warns (empty is present, not absent)" warn \
+  MOSAIC_HOST_ROOT= MOSAIC_BRAIN_HOME=
+run_case "host empty + brain unset warns" warn \
+  MOSAIC_HOST_ROOT= -u:MOSAIC_BRAIN_HOME
+run_case "host unset + brain empty warns" warn \
+  -u:MOSAIC_HOST_ROOT MOSAIC_BRAIN_HOME=
+
+# ── red control (mutation): presence tracking removed → red ────────────────
+# Mutant regresses to the reviewed defect shape: presence derived from
+# NONEMPTINESS (the `${VAR:-}` collapse) instead of true -v tracking. Both-empty
+# then looks genuinely-absent and is mis-filed as informational; the both-empty
+# warn arm above finds no WARN and the suite reds.
+MUT="$ROOT/mosaic-doctor.mutant"
+sed 's/\[\[ -v MOSAIC_HOST_ROOT \]\]  \&\& host_set=1/[[ -n "${MOSAIC_HOST_ROOT:-}" ]] \&\& host_set=1/; s/\[\[ -v MOSAIC_BRAIN_HOME \]\] \&\& brain_set=1/[[ -n "${MOSAIC_BRAIN_HOME:-}" ]] \&\& brain_set=1/' \
+  "$DOCTOR" > "$MUT"
+if cmp -s "$DOCTOR" "$MUT"; then
+  echo "SKIP red control (mutation anchor not found — sed pattern drifted)" >&2
+else
+  mut_fn=$(sed -n "/^check_structure_anchor_provisioning() {/,/^}/p" "$MUT")
+  outm=$(env MOSAIC_HOST_ROOT= MOSAIC_BRAIN_HOME= bash -c \
+    "warn() { echo \"[WARN] \$*\"; }; note() { echo \"[NOTE] \$*\"; return 0; }; pass() { echo \"[OK] \$*\"; return 0; }; $mut_fn; check_structure_anchor_provisioning" 2>&1)
+  if printf '%s\n' "$outm" | grep -q '^\[NOTE\]'; then
+    echo "ok - red control bites (mutant collapses empty into informational; shipped does not)"
+  else
+    fail "red control did not reproduce the regression shape (mutant output unexpected)"
+  fi
+fi
+
+echo "structure anchor doctor check: all arms passed"
@@ -1,24 +0,0 @@
-# Fleet tools
-
-Seat lifecycle tools for a Mosaic fleet. Paths are relative to
-`packages/mosaic/framework/tools/fleet/` (deployed to `~/.config/mosaic/tools/fleet/`).
-
-| Script                                                                                          | Purpose                                                                                                                                      |
-| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `start-agent-session.sh`                                                                        | launch, stop, or attach a roster-driven agent session (reads `<seat>.env.generated`, honours `MOSAIC_TMUX_SOCKET`)                           |
-| `seat-logins.sh`                                                                                | project seat tokens into `tea` logins named `<instance>-<seat>` (dry-run by default, `--apply`, `--adopt`)                                   |
-| `mint-seat-credential.sh`                                                                       | create the Gitea account for a seat on every configured instance, mint a token, write the seat's credential slot, then project it into `tea` |
-| `start-interaction-service.sh`, `print-interaction-effective-policy.sh`, `start-tmux-holder.sh` | operator interaction service and tmux holder                                                                                                 |
-
-## Onboarding a seat's credential
-
-```
-MOSAIC_ADMIN_SEAT=<admin-seat> MOSAIC_SEAT_EMAIL_DOMAIN=<domain> mint-seat-credential.sh <seat>
-```
-
- The admin token is read from `$MOSAIC_BRAIN_HOME/fleet/agents/<admin-seat>/secrets/gitea-<instance>-<admin-seat>.token`. It is never printed.
- `MOSAIC_SEAT_EMAIL_DOMAIN` is required (no default): the framework ships no estate-specific domain.
- Instances default to the map shared with `seat-logins.sh`; `MOSAIC_GITEA_INSTANCES="a b"` limits the set and `MOSAIC_GITEA_URL_<INSTANCE>` overrides a server URL (hyphens in the instance name become underscores in the variable, as in `seat-logins.sh`).
- The seat slot is written from the mint response: `.token`, `.scopes` (what was granted), `.principal`, each mode 600.
- `tea` absent is a warning, not a failure: REST-path wrappers work with the token alone.
- Regression suite: `test-mint-seat-credential.sh` (hermetic, mock curl, no network).
@@ -1,198 +0,0 @@
-#!/usr/bin/env bash
-# mint-seat-credential.sh — create the Gitea account and mint a token for one seat,
-# on every configured instance, writing the result into that seat's credential slot.
-#
-#   mint-seat-credential.sh [--admin-seat <seat>] [--instances "<a> <b>"] <seat>
-#
-# Configuration (environment; flags win over environment):
-#   MOSAIC_ADMIN_SEAT               seat whose admin token is used to call the Gitea
-#                                   admin API. Required. Its token is read from
-#                                   $MOSAIC_BRAIN_HOME/fleet/agents/<admin>/secrets/
-#                                   gitea-<instance>-<admin>.token. Never printed.
-#   MOSAIC_GITEA_INSTANCES          space-separated instance names to mint on.
-#                                   Default: every instance in the map below.
-#   MOSAIC_GITEA_URL_<INSTANCE>     server URL override per instance (same
-#                                   convention as seat-logins.sh).
-#   MOSAIC_SEAT_EMAIL_DOMAIN        domain for the account email (<seat>@<domain>).
-#                                   Required, no default: the framework tree
-#                                   carries no estate-specific domain
-#                                   (framework-PR firewall; the instance host
-#                                   map stays per seat-logins.sh precedent).
-#   MOSAIC_BRAIN_HOME               brain checkout; default ~/.mosaic.
-#
-# Exit codes: 0 minted and projected on every instance; 1 at least one instance
-# failed (the others are untouched or complete); 3 usage error.
-#
-# WHY BASIC AUTH, WHICH LOOKS WRONG AT FIRST
-#   Gitea refuses token auth on POST /users/{user}/tokens by design, and the Sudo
-#   header and sudo query parameter are both rejected there (probed 2026-08-19, probe
-#   token deleted). So minting for another account needs a password: this script
-#   generates a random one, uses it once, and never stores or prints it. Agents
-#   authenticate by token; the password is not a credential anyone keeps.
-#
-# The .scopes file is written from the mint RESPONSE rather than from what was
-# requested, so the record is what was granted rather than what was asked for.
-#
-# SECRETS NEVER TOUCH ARGV (#1343 class, rev-security-01 review 259): the admin
-# token, the generated password, and the minted seat token all pass through
-# 0600 curl --config / --data files — the landed in-tree standard
-# (gitea_write_auth_config in detect-platform.sh). argv is world-readable via
-# /proc/<pid>/cmdline for the life of each request, and a bash -x trace would
-# print every secret otherwise. The staging files are unlinked after each use.
-set -Eeuo pipefail
-
-# Stage secrets into 0600 files; nothing secret reaches argv or a trace.
-# write_auth_config <token>  -> curl --config carrying the Authorization header
-#                               (same shape as gitea_write_auth_config in
-#                               detect-platform.sh, local so this script stays
-#                               standalone under tools/fleet).
-# write_user_config <u> <pw> -> curl --config with `user =` (covers -u).
-# write_body <json>          -> 0600 file for --data @file.
-write_auth_config() {
-  local f; f=$(mktemp "${TMPDIR:-/tmp}/mosaic-mint-auth.XXXXXX") || return 1
-  printf 'header = "Authorization: token %s"\n' "$1" >"$f" || { rm -f "$f"; return 1; }
-  chmod 600 "$f"; printf '%s' "$f"
-}
-write_user_config() {
-  local f; f=$(mktemp "${TMPDIR:-/tmp}/mosaic-mint-user.XXXXXX") || return 1
-  printf 'user = "%s:%s"\n' "$1" "$2" >"$f" || { rm -f "$f"; return 1; }
-  chmod 600 "$f"; printf '%s' "$f"
-}
-write_body() {
-  local f; f=$(mktemp "${TMPDIR:-/tmp}/mosaic-mint-body.XXXXXX") || return 1
-  printf '%s' "$1" >"$f" || { rm -f "$f"; return 1; }
-  chmod 600 "$f"; printf '%s' "$f"
-}
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-BRAIN="${MOSAIC_BRAIN_HOME:-$HOME/.mosaic}"
-ADMIN="${MOSAIC_ADMIN_SEAT:-}"
-INSTANCES="${MOSAIC_GITEA_INSTANCES:-}"
-EMAIL_DOMAIN="${MOSAIC_SEAT_EMAIL_DOMAIN:-}"
-SEAT=""
-
-usage() { sed -n '2,20p' "${BASH_SOURCE[0]}" >&2; exit 3; }
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --admin-seat) ADMIN="${2:-}"; shift 2 ;;
-    --instances)  INSTANCES="${2:-}"; shift 2 ;;
-    -h|--help)    usage ;;
-    -*)           echo "mint: unknown flag: $1" >&2; exit 3 ;;
-    *)            [[ -z "$SEAT" ]] || { echo "mint: one seat only" >&2; exit 3; }; SEAT="$1"; shift ;;
-  esac
-done
-
-[[ -n "$SEAT" ]] || usage
-[[ "$SEAT" =~ ^[a-z0-9][a-z0-9-]*$ ]] || { echo "mint: bad seat name: $SEAT" >&2; exit 3; }
-[[ -n "$ADMIN" ]] || { echo "mint: no admin seat. Set MOSAIC_ADMIN_SEAT or pass --admin-seat." >&2; exit 3; }
-[[ "$ADMIN" =~ ^[a-z0-9][a-z0-9-]*$ ]] || { echo "mint: bad admin seat name: $ADMIN" >&2; exit 3; }
-[[ -n "$EMAIL_DOMAIN" ]] || { echo "mint: no email domain. Set MOSAIC_SEAT_EMAIL_DOMAIN (the framework ships no estate default)." >&2; exit 3; }
-
-# Instance -> server URL. Same map and override convention as seat-logins.sh:
-# hyphens in instance names map to underscores in the override variable
-# (MOSAIC_GITEA_URL_MY-INST is not a valid shell name; MY_INST is).
-url_override_var() { printf 'MOSAIC_GITEA_URL_%s' "$(printf '%s' "$1" | tr '[:lower:]-' '[:upper:]_')"; }
-declare -A INSTANCE_URL=(
-  [mosaicstack]="https://git.mosaicstack.dev"
-  [usc]="https://git.uscllc.com"
-)
-for inst in "${!INSTANCE_URL[@]}"; do
-  ov="$(url_override_var "$inst")"
-  [[ -n "${!ov:-}" ]] && INSTANCE_URL[$inst]="${!ov}"
-done
-[[ -n "$INSTANCES" ]] || INSTANCES="$(printf '%s\n' "${!INSTANCE_URL[@]}" | sort | tr '\n' ' ')"
-
-SCOPES='["read:user","write:repository","write:issue","read:organization"]'
-D="$BRAIN/fleet/agents/$SEAT/secrets"
-mkdir -p "$D"; chmod 700 "$D"
-
-rc=0
-for KEY in $INSTANCES; do
-  ov="$(url_override_var "$KEY")"
-  BASE="${INSTANCE_URL[$KEY]:-${!ov:-}}"
-  [[ -n "$BASE" ]] || { echo "  $KEY: no URL known for this instance (set $ov), skipped" >&2; rc=1; continue; }
-  ADMIN_TOKEN_FILE="$BRAIN/fleet/agents/$ADMIN/secrets/gitea-$KEY-$ADMIN.token"
-  [[ -r "$ADMIN_TOKEN_FILE" ]] || { echo "  $KEY: no admin token for seat '$ADMIN' ($ADMIN_TOKEN_FILE), skipped" >&2; rc=1; continue; }
-  T="$(cat "$ADMIN_TOKEN_FILE")"
-  AUTH_CFG="$(write_auth_config "$T")"
-  PW="$(openssl rand -base64 33 | tr -d '\n/+=' | head -c 32)"
-  USER_CFG="$(write_user_config "$SEAT" "$PW")"
-
-  if curl -sf -o /dev/null --config "$AUTH_CFG" "$BASE/api/v1/users/$SEAT"; then
-    BODY="$(write_body "{\"login_name\":\"$SEAT\",\"source_id\":0,\"password\":\"$PW\",\"must_change_password\":false}")"
-    curl -s -o /dev/null -X PATCH -H "Content-Type: application/json" \
-      --config "$AUTH_CFG" --data "@$BODY" \
-      "$BASE/api/v1/admin/users/$SEAT"
-    rm -f "$BODY"; BODY=""
-    act="reset-pw"
-  else
-    BODY="$(write_body "{\"username\":\"$SEAT\",\"email\":\"$SEAT@$EMAIL_DOMAIN\",\"password\":\"$PW\",\"must_change_password\":false,\"full_name\":\"Mosaic fleet seat $SEAT\"}")"
-    curl -s -o /dev/null -X POST -H "Content-Type: application/json" \
-      --config "$AUTH_CFG" --data "@$BODY" \
-      "$BASE/api/v1/admin/users"
-    rm -f "$BODY"; BODY=""
-    act="create"
-  fi
-
-  tmp="$(mktemp)"; chmod 600 "$tmp"
-  MINT_BODY="$(write_body "{\"name\":\"mosaic-seat\",\"scopes\":$SCOPES}")"
-  code="$(curl -s -o "$tmp" -w '%{http_code}' -X POST -H "Content-Type: application/json" \
-    --config "$USER_CFG" --data "@$MINT_BODY" "$BASE/api/v1/users/$SEAT/tokens")"
-  rm -f "$MINT_BODY"; MINT_BODY=""
-  if [[ "$code" != "201" ]]; then
-    echo "  $KEY: mint FAILED http=$code ($act)" >&2; rm -f "$tmp"; rc=1; PW=""; rm -f "$AUTH_CFG" "$USER_CFG"; continue
-  fi
-
-  python3 - "$tmp" "$D" "$KEY" "$SEAT" <<'PY'
-import json,sys,pathlib
-tmp,d,key,seat=sys.argv[1:5]
-t=json.load(open(tmp))
-p=pathlib.Path(d)
-(p/f"gitea-{key}-{seat}.token").write_text(t["sha1"]+"\n")
-(p/f"gitea-{key}-{seat}.scopes").write_text(json.dumps(t.get("scopes",[]))+"\n")
-(p/f"gitea-{key}-{seat}.principal").write_text(seat+"\n")
-for suf in ("token","scopes","principal"):
-    (p/f"gitea-{key}-{seat}.{suf}").chmod(0o600)
-PY
-  rm -f "$tmp"; PW=""; rm -f "$AUTH_CFG" "$USER_CFG"
-
-  VERIFY_CFG="$(write_auth_config "$(cat "$D/gitea-$KEY-$SEAT.token")")"
-  login="$(curl -s --config "$VERIFY_CFG" "$BASE/api/v1/user" \
-    | python3 -c 'import json,sys;print(json.load(sys.stdin).get("login","ERR"))' 2>/dev/null || echo ERR)"
-  rm -f "$VERIFY_CFG"
-  if [[ "$login" == "$SEAT" ]]; then
-    echo "  $KEY: $act, minted, GET /user -> $login"
-  else
-    echo "  $KEY: minted but identity check returned '$login', expected '$SEAT'" >&2; rc=1
-  fi
-done
-
-# ── Project into tea ─────────────────────────────────────────────────────────
-# A token in the secrets dir is only half a credential. tea 0.14.0 cannot read
-# that store, it only uses logins already in its own config, so a seat minted
-# but not projected holds a working token and no login. Minting and projecting
-# are therefore ONE operation.
-#
-# --adopt is deliberately NOT passed. Adopting deletes an operator-made login,
-# which is a human decision. A collision reports BLOCK and a nonzero rc instead.
-#
-# tea absent is not a minting failure. The REST-path wrappers still work with
-# the token that was just written, so warn and carry on.
-SEAT_LOGINS="$SCRIPT_DIR/seat-logins.sh"
-if [[ "$rc" -eq 0 ]]; then
-  if command -v tea >/dev/null 2>&1; then
-    if "$SEAT_LOGINS" --apply --seat "$SEAT"; then
-      :
-    else
-      echo "  projection FAILED: token is minted and valid, but no tea login exists for $SEAT." >&2
-      echo "  tea-path wrappers will not act as this seat. Re-run:" >&2
-      echo "    $SEAT_LOGINS --apply --seat $SEAT" >&2
-      rc=1
-    fi
-  else
-    echo "  tea not on PATH: token minted, no login projected (REST-path wrappers still work)." >&2
-  fi
-fi
-
-exit $rc
@@ -1,161 +0,0 @@
-#!/usr/bin/env bash
-# Hermetic regression for mint-seat-credential.sh: mock curl on PATH, sandboxed
-# brain home, no tea, no network, no real credentials.
-#
-# Pins:
-#   M1  the seat slot is written from the mint RESPONSE (token, granted scopes,
-#       principal), each file mode 600, and the identity check passes.
-#   M2  the admin token is read from MOSAIC_ADMIN_SEAT's slot, never hardcoded;
-#       a missing admin token is reported per instance and exits nonzero.
-#   M3  MOSAIC_GITEA_INSTANCES limits which instances are touched, and the URL
-#       override MOSAIC_GITEA_URL_<INSTANCE> is honoured.
-#   M4  no admin seat configured is a usage error (rc=3), nothing written.
-#   M5  the admin token value never appears on stdout or stderr.
-#   M6  secrets never touch argv: no Authorization header, no -u user:pass, no
-#       inline --data JSON carrying the password, on any curl invocation; auth
-#       travels in --config files and bodies in --data @files (#1343 class,
-#       rev-security-01 review 259 blocker).
-#   M7  the scopes record discriminates: a requested-but-not-granted scope
-#       (write:issue) must be ABSENT from .scopes — the pin is on the RESPONSE,
-#       and a mutant writing the requested set fails here (both reviewers).
-#   M8  hyphenated instance names resolve their override through the underscore
-#       variable, matching seat-logins.sh (SF3).
-#   M9  MOSAIC_SEAT_EMAIL_DOMAIN is required: unset is a usage error (rc=3),
-#       nothing written (framework-PR firewall answer).
-set -euo pipefail
-
-WORK_ROOT="${AGENT_WORK_ROOT:-${TMPDIR:-/tmp}}"
-SANDBOX="$WORK_ROOT/mint-seat-credential-test-$$"
-MOCK_BIN="$SANDBOX/bin"; BRAIN="$SANDBOX/brain"; CALLS="$SANDBOX/calls.log"
-cleanup() { rm -rf "$SANDBOX"; }
-trap cleanup EXIT
-fail() { echo "FAIL: $*"; exit 1; }
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TARGET="$SCRIPT_DIR/mint-seat-credential.sh"
-[ -f "$TARGET" ] || fail "mint-seat-credential.sh not found beside this test"
-
-mkdir -p "$MOCK_BIN" "$BRAIN/fleet/agents/admin-seat/secrets" || fail "setup: sandbox"
-: > "$CALLS"
-ADMIN_TOKEN_VALUE="admin-token-value-sentinel-4491"
-printf '%s\n' "$ADMIN_TOKEN_VALUE" > "$BRAIN/fleet/agents/admin-seat/secrets/gitea-alpha-admin-seat.token"
-chmod 600 "$BRAIN/fleet/agents/admin-seat/secrets/gitea-alpha-admin-seat.token"
-
-# A PATH with only the mock bin plus the system tools the script needs, and no tea.
-SYS_BIN="$SANDBOX/sys"; mkdir -p "$SYS_BIN"
-for t in bash sed cat mktemp openssl tr head python3 sort printf chmod mkdir rm dirname grep stat; do
-    p="$(command -v "$t" 2>/dev/null || true)"; [ -n "$p" ] && ln -s "$p" "$SYS_BIN/$t"
-done
-export PATH="$MOCK_BIN:$SYS_BIN" CALLS
-export MOSAIC_BRAIN_HOME="$BRAIN"
-export MOSAIC_GITEA_URL_ALPHA="https://alpha.example.test"
-export MOSAIC_SEAT_EMAIL_DOMAIN="seats.example.test"
-unset MOSAIC_ADMIN_SEAT MOSAIC_GITEA_INSTANCES
-
-# --- mock curl: records method + URL + a REDACTED auth marker, answers minting --
-cat > "$MOCK_BIN/curl" <<'EOF'
-#!/bin/bash
-method=GET; url=""; out=""; wcode=0; auth=""; body=""
-while [ $# -gt 0 ]; do
-    case "$1" in
-        -X) method="$2"; shift 2 ;;
-        -o) out="$2"; shift 2 ;;
-        -w) wcode=1; shift 2 ;;
-        --config)
-            if grep -q 'Authorization: token' "$2" 2>/dev/null; then auth="${auth}token,"; fi
-            if grep -q '^user = ' "$2" 2>/dev/null; then auth="${auth}user,"; fi
-            shift 2 ;;
-        --data)
-            case "$2" in
-                @*) body="@file" ;;
-                *)  body="inline" ;;
-            esac
-            shift 2 ;;
-        -H|-u) shift 2 ;;
-        http*) url="$1"; shift ;;
-        *) shift ;;
-    esac
-done
-printf '%s %s auth=%s body=%s\n' "$method" "$url" "${auth:-NONE}" "$body" >> "$CALLS"
-emit() { if [ -n "$out" ]; then printf '%s' "$1" > "$out"; else printf '%s' "$1"; fi; }
-case "$method $url" in
-    "GET "*/api/v1/users/newseat)        exit 22 ;;   # 404 under -f: account does not exist yet
-    "POST "*/api/v1/admin/users)         emit '{}'; exit 0 ;;
-    "POST "*/api/v1/users/newseat/tokens) emit '{"id":9,"name":"mosaic-seat","sha1":"minted-token-7f3a","scopes":["read:user","write:repository"]}'
-                                          [ "$wcode" = 1 ] && printf '201'; exit 0 ;;
-    "GET "*/api/v1/user)                 emit '{"login":"newseat"}'; exit 0 ;;
-    *) emit '{}'; exit 0 ;;
-esac
-EOF
-chmod +x "$MOCK_BIN/curl"
-[ "$(command -v curl)" = "$MOCK_BIN/curl" ] || fail "setup: curl does not resolve to the mock"
-command -v tea >/dev/null 2>&1 && fail "setup: tea must be absent from the sandbox PATH"
-
-run() { bash "$TARGET" "$@" >"$SANDBOX/out" 2>"$SANDBOX/err"; echo $?; }
-
-# M4: no admin seat configured.
-rc=$(run newseat)
-[ "$rc" = 3 ] || fail "M4: expected rc=3 without an admin seat, got $rc: $(cat "$SANDBOX/err")"
-grep -q 'MOSAIC_ADMIN_SEAT' "$SANDBOX/err" || fail "M4: error does not name MOSAIC_ADMIN_SEAT"
-[ ! -e "$BRAIN/fleet/agents/newseat/secrets/gitea-alpha-newseat.token" ] || fail "M4: a token was written without an admin seat"
-
-# M9: email domain is required, unset is a usage error, nothing written.
-rc=$(MOSAIC_ADMIN_SEAT=admin-seat MOSAIC_GITEA_INSTANCES=alpha MOSAIC_SEAT_EMAIL_DOMAIN= run newseat)
-[ "$rc" = 3 ] || fail "M9: expected rc=3 with no email domain, got $rc: $(cat "$SANDBOX/err")"
-grep -q 'MOSAIC_SEAT_EMAIL_DOMAIN' "$SANDBOX/err" || fail "M9: error does not name MOSAIC_SEAT_EMAIL_DOMAIN"
-[ ! -s "$CALLS" ] || fail "M9: API called without an email domain"
-[ ! -e "$BRAIN/fleet/agents/newseat/secrets/gitea-alpha-newseat.token" ] || fail "M9: token written without an email domain"
-
-# M1 + M3 + M5: mint on the single configured instance.
-: > "$CALLS"
-rc=$(MOSAIC_ADMIN_SEAT=admin-seat MOSAIC_GITEA_INSTANCES=alpha run newseat)
-[ "$rc" = 0 ] || fail "M1: expected rc=0, got $rc: $(cat "$SANDBOX/err")"
-SLOT="$BRAIN/fleet/agents/newseat/secrets"
-[ "$(cat "$SLOT/gitea-alpha-newseat.token")" = "minted-token-7f3a" ] || fail "M1: token file not written from the mint response"
-grep -q 'write:repository' "$SLOT/gitea-alpha-newseat.scopes" || fail "M1: scopes file not written from the response"
-[ "$(cat "$SLOT/gitea-alpha-newseat.principal")" = "newseat" ] || fail "M1: principal file wrong"
-for suf in token scopes principal; do
-    m=$(stat -c '%a' "$SLOT/gitea-alpha-newseat.$suf"); [ "$m" = 600 ] || fail "M1: $suf is mode $m, expected 600"
-done
-grep -q 'alpha: create, minted, GET /user -> newseat' "$SANDBOX/out" || fail "M1: success line missing: $(cat "$SANDBOX/out")"
-grep -q 'https://alpha.example.test/api/v1/admin/users' "$CALLS" || fail "M3: URL override not honoured: $(cat "$CALLS")"
-if grep -q 'usc\|mosaicstack' "$CALLS"; then fail "M3: an instance outside MOSAIC_GITEA_INSTANCES was touched: $(cat "$CALLS")"; fi
-grep -q 'tea not on PATH' "$SANDBOX/err" || fail "tea-absent path should warn, not fail: $(cat "$SANDBOX/err")"
-if grep -q "$ADMIN_TOKEN_VALUE" "$SANDBOX/out" "$SANDBOX/err" "$CALLS"; then fail "M5: admin token value leaked to output or call log"; fi
-
-# M7: scopes pin discriminates — requested-but-not-granted scope is ABSENT.
-if grep -q 'write:issue' "$SLOT/gitea-alpha-newseat.scopes"; then
-    fail "M7: write:issue appears in .scopes — the record is the REQUESTED set, not the response"
-fi
-
-# M6: no secret ever travels argv — every call authenticates via --config
-# (token header or user= basic-auth directive) and bodies go as --data @file.
-while IFS= read -r line; do
-    case "$line" in
-        *auth=NONE*)     fail "M6: unauthenticated call: $line" ;;
-        *body=inline*)   fail "M6: inline body (secret in argv risk): $line" ;;
-    esac
-done < "$CALLS"
-[ "$(grep -c 'auth=token' "$CALLS")" -eq 3 ] || fail "M6: expected exactly 3 token-auth calls (exists-check, admin write, verify), got: $(cat "$CALLS")"
-grep -q 'auth=user' "$CALLS" || fail "M6: mint call did not use the user= directive: $(cat "$CALLS")"
-
-# M8: hyphenated instance name resolves its override via the underscore variable.
-printf '%s\n' "$ADMIN_TOKEN_VALUE" > "$BRAIN/fleet/agents/admin-seat/secrets/gitea-my-inst-admin-seat.token"
-chmod 600 "$BRAIN/fleet/agents/admin-seat/secrets/gitea-my-inst-admin-seat.token"
-export MOSAIC_GITEA_URL_MY_INST="https://myinst.example.test"
-: > "$CALLS"; rm -rf "$BRAIN/fleet/agents/newseat"
-rc=$(MOSAIC_ADMIN_SEAT=admin-seat MOSAIC_GITEA_INSTANCES=my-inst run newseat)
-[ "$rc" = 0 ] || fail "M8: hyphenated instance mint failed rc=$rc: $(cat "$SANDBOX/err")"
-grep -q 'https://myinst.example.test/api/v1/admin/users' "$CALLS" || fail "M8: hyphen override (MY_INST) not honoured: $(cat "$CALLS")"
-unset MOSAIC_GITEA_URL_MY_INST
-
-# M2: admin token missing for the instance is reported, rc=1, nothing written.
-rm -rf "$BRAIN/fleet/agents/newseat"
-: > "$CALLS"
-rc=$(MOSAIC_ADMIN_SEAT=other-admin MOSAIC_GITEA_INSTANCES=alpha run newseat)
-[ "$rc" = 1 ] || fail "M2: expected rc=1 with no admin token, got $rc"
-grep -q "no admin token for seat 'other-admin'" "$SANDBOX/err" || fail "M2: missing-admin-token not reported: $(cat "$SANDBOX/err")"
-[ ! -s "$CALLS" ] || fail "M2: API was called without an admin token: $(cat "$CALLS")"
-[ ! -e "$BRAIN/fleet/agents/newseat/secrets/gitea-alpha-newseat.token" ] || fail "M2: token written without an admin token"
-
-echo "mint-seat-credential regression harness passed"
@@ -1,6 +1,6 @@
 #!/bin/bash
 # ci-queue-wait.sh - Wait until project CI queue is clear (no running/queued pipeline on branch head)
-# Usage: ci-queue-wait.sh [-B branch] [-t timeout_sec] [-i interval_sec] [--purpose push|merge] [--require-status]
+# Usage: ci-queue-wait.sh [-B branch] [-t timeout_sec] [-i interval_sec] [--purpose push|merge] [--require-status] [--no-ci-expected]

 set -euo pipefail

@@ -14,10 +14,11 @@ TIMEOUT_SEC=900
 INTERVAL_SEC=15
 PURPOSE="merge"
 REQUIRE_STATUS=0
+NO_CI_EXPECTED=0

 usage() {
    cat <<EOF
-Usage: $(basename "$0") [-B branch] [-R owner/repo] [--sha full-40] [-t timeout_sec] [-i interval_sec] [--purpose push|merge] [--require-status]
+Usage: $(basename "$0") [-B branch] [-R owner/repo] [--sha full-40] [-t timeout_sec] [-i interval_sec] [--purpose push|merge] [--require-status] [--no-ci-expected]

 Options:
  -B, --branch BRANCH      Branch head to inspect (default: current branch)
@@ -27,6 +28,7 @@ Options:
  -i, --interval SECONDS   Poll interval in seconds (default: 15)
      --purpose VALUE      Log context: push|merge (default: merge)
      --require-status     Fail if no CI status contexts are present
+      --no-ci-expected     Assert this repository has no CI configured: a merge guard on a zero-context head becomes queue-clear (requires the acting token to hold repository admin); refused with exit 78 when MOSAIC_GIT_IDENTITY is unset or empty
  -h, --help               Show this help

 Examples:
@@ -175,6 +177,50 @@ PY
    return 0
 }

+# Durable audit record for an explicit no-CI assertion event (granted or
+# refused). Same JSONL sink and field shape as record_cannot_assert so one
+# reader covers all three outcomes; the outcome value distinguishes them.
+# rc 70 on an unwritable sink: a merge pass that cannot be audited must not
+# be reachable, mirroring record_cannot_assert's refusal of a degraded pass.
+record_assertion_event() {
+    local outcome="$1" reason="$2" asserted_by="$3"
+    local audit_log="${MOSAIC_CI_QUEUE_AUDIT_LOG:-${XDG_STATE_HOME:-${HOME:-}/.local/state}/mosaic/audit/ci-queue-wait.jsonl}"
+
+    if [[ -z "$audit_log" ]] || ! mkdir -p "$(dirname "$audit_log")"; then
+        echo "Error: could not write ${outcome} audit record (audit directory unavailable at ${audit_log})." >&2
+        return 70
+    fi
+
+    if ! python3 - "$audit_log" "$outcome" "$reason" "$asserted_by" "${PLATFORM:-unknown}" "$PURPOSE" "${BRANCH:-unknown}" "${OWNER:-unknown}/${REPO:-unknown}" <<'PY'
+import datetime
+import json
+import os
+import sys
+
+path, outcome, reason, asserted_by, platform, purpose, branch, repo = sys.argv[1:]
+record = {
+    "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+    "outcome": outcome,
+    "reason": reason,
+    "platform": platform,
+    "purpose": purpose,
+    "branch": branch,
+    "repo": repo,
+    "asserted_by": asserted_by,
+}
+fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+try:
+    os.write(fd, (json.dumps(record, separators=(",", ":")) + "\n").encode())
+finally:
+    os.close(fd)
+PY
+    then
+        echo "Error: could not write ${outcome} audit record at ${audit_log}; refusing to proceed unaudited." >&2
+        return 70
+    fi
+    return 0
+}
+
 github_get_branch_head_sha() {
    local owner="$1"
    local repo="$2"
@@ -182,6 +228,24 @@ github_get_branch_head_sha() {
    gh api "repos/${owner}/${repo}/branches/${branch}" --jq '.commit.sha'
 }

+# Repository-admin state for the acting credential, GitHub flavor. The
+# repository object's permissions.admin is the field; read through the same
+# gh CLI the guard already authenticates with. rc 0 = admin, 1 = not admin
+# (or field absent), 2 = indeterminate (transport/API failure).
+github_repo_admin_state() {
+    local owner="$1"
+    local repo="$2"
+    local perm
+    if ! perm=$(gh api "repos/${owner}/${repo}" --jq '.permissions.admin' 2>/dev/null); then
+        return 2
+    fi
+    case "$perm" in
+        true)  return 0 ;;
+        false|null|"") return 1 ;;
+        *)     return 2 ;;
+    esac
+}
+
 github_get_commit_status_json() {
    local owner="$1"
    local repo="$2"
@@ -306,6 +370,41 @@ gitea_get_commit_status_json() {
    curl -fsSL -H "User-Agent: curl/8" -H "Authorization: token ${token}" "$url"
 }

+# Repository-admin state for the acting credential, Gitea flavor. The guard's
+# existing fetches (branch head, combined status) carry no permissions object
+# (measured: neither response includes one), so the elevation check reads the
+# repository object's permissions.admin, the one documented carrier of that
+# field. rc 0 = admin, 1 = not admin (or field absent), 2 = indeterminate
+# (non-200 or unparseable).
+gitea_repo_admin_state() {
+    local host="$1"
+    local repo="$2"
+    local token="$3"
+    local url="https://${host}/api/v1/repos/${repo}"
+    local resp code body
+    resp=$(curl -sS -H "User-Agent: curl/8" -H "Authorization: token ${token}" -w $'\n%{http_code}' "$url") || return 2
+    code="${resp##*$'\n'}"
+    body="${resp%$'\n'*}"
+    if [[ "$code" != "200" ]]; then
+        return 2
+    fi
+    printf '%s' "$body" | python3 -c '
+import json
+import sys
+
+try:
+    payload = json.load(sys.stdin)
+except Exception:
+    raise SystemExit(2)
+if not isinstance(payload, dict):
+    raise SystemExit(2)
+permissions = payload.get("permissions")
+if not isinstance(permissions, dict) or permissions.get("admin") is not True:
+    raise SystemExit(1)
+raise SystemExit(0)
+'
+}
+
 while [[ $# -gt 0 ]]; do
    case "$1" in
        -B|--branch)
@@ -336,6 +435,10 @@ while [[ $# -gt 0 ]]; do
            REQUIRE_STATUS=1
            shift
            ;;
+        --no-ci-expected)
+            NO_CI_EXPECTED=1
+            shift
+            ;;
        -h|--help)
            usage
            exit 0
@@ -365,6 +468,10 @@ if [[ "$PURPOSE" != "push" && "$PURPOSE" != "merge" ]]; then
    echo "Error: --purpose must be push or merge." >&2
    exit 1
 fi
+if [[ "$NO_CI_EXPECTED" -eq 1 && "$REQUIRE_STATUS" -eq 1 ]]; then
+    echo "Error: --no-ci-expected and --require-status contradict each other: one asserts the repository has no CI, the other demands status contexts. Pass at most one." >&2
+    exit 1
+fi

 OWNER="unknown"
 REPO="unknown"
@@ -484,6 +591,48 @@ while true; do
                echo "[ci-queue-wait] queue-clear state=no-status purpose=push branch=${BRANCH}; no queued or running CI."
                exit 0
            fi
+            if [[ "$NO_CI_EXPECTED" -eq 1 ]]; then
+                # Explicit, elevated, audit-visible assertion that this
+                # repository has no CI to wait on. The zero-context case is
+                # the ONLY state the flag reclassifies: a pending or failed
+                # context still holds or fails exactly as without it, and a
+                # non-admin token is refused rather than trusted.
+                # The assertion must name an asserting identity: "unknown"
+                # attributes nothing, so a caller with MOSAIC_GIT_IDENTITY
+                # unset or empty is refused (exit 78) BEFORE the permission
+                # lookup -- an unattributable caller never triggers that
+                # network call.
+                if [[ -z "${MOSAIC_GIT_IDENTITY:-}" ]]; then
+                    record_assertion_event "ASSERTION_UNATTRIBUTABLE" "actor-unattributable" "unknown" \
+                        || echo "Warning: could not write the ASSERTION_UNATTRIBUTABLE audit record; the refusal itself stands." >&2
+                    echo "Error: ASSERTION_UNATTRIBUTABLE state=no-status purpose=merge asserted-by=unknown reason=no-ci-expected branch=${BRANCH}; --no-ci-expected requires MOSAIC_GIT_IDENTITY to name the asserting identity and it is unset or empty (exit 78)." >&2
+                    exit 78
+                fi
+                ASSERTED_BY="${MOSAIC_GIT_IDENTITY}"
+                ADMIN_STATE=2
+                if [[ "$PLATFORM" == "github" ]]; then
+                    if github_repo_admin_state "$OWNER" "$REPO"; then ADMIN_STATE=0; else ADMIN_STATE=$?; fi
+                else
+                    if gitea_repo_admin_state "$HOST" "$OWNER/$REPO" "$TOKEN"; then ADMIN_STATE=0; else ADMIN_STATE=$?; fi
+                fi
+                case "$ADMIN_STATE" in
+                    0)
+                        record_assertion_event "NO_CI_ASSERTED" "no-ci-expected" "$ASSERTED_BY" || exit $?
+                        echo "[ci-queue-wait] queue-clear state=no-status purpose=merge asserted-by=${ASSERTED_BY} reason=no-ci-expected branch=${BRANCH}"
+                        exit 0
+                        ;;
+                    1)
+                        record_assertion_event "ASSERTION_REFUSED" "actor-not-repo-admin" "$ASSERTED_BY" \
+                            || echo "Warning: could not write the ASSERTION_REFUSED audit record; the refusal itself stands." >&2
+                        echo "Error: ASSERTION_REFUSED state=no-status purpose=merge asserted-by=${ASSERTED_BY} reason=no-ci-expected branch=${BRANCH}; --no-ci-expected requires repository admin and the acting token is not an admin of ${OWNER}/${REPO} (exit 77)." >&2
+                        exit 77
+                        ;;
+                    *)
+                        record_cannot_assert "repo-permissions-unavailable"
+                        exit $?
+                        ;;
+                esac
+            fi
            echo "Error: ASSERTED_NOT_READY state=no-status purpose=${PURPOSE} branch=${BRANCH}." >&2
            exit 3
            ;;
@@ -19,6 +19,41 @@ ISSUE=""

 # get_remote_host, get_gitea_token, get_repo_info, and get_gitea_repo_args are provided by detect-platform.sh

+gitea_default_branch() {
+    # Forge default branch for the current repo (T51-P2 WP5a / spec E4): the
+    # API fallback must not guess a base. Empty output or any lookup failure
+    # returns nonzero so the caller fails loud instead of mistargeting a PR.
+    local host repo token url body branch
+    host=$(get_remote_host) || return 1
+    repo=$(get_repo_info) || return 1
+    token=$(get_gitea_token "$host") || return 1
+    url="https://${host}/api/v1/repos/${repo}"
+    # Fetch and parse as separate steps (T51P2WP5AR B2): a piped
+    # `curl | python` reports only python's status, so an HTTP failure that
+    # still emits parseable JSON would masquerade as success. curl's own
+    # exit status is authoritative here.
+    if ! body=$(curl -fsS \
+        -H "User-Agent: curl/8" \
+        -H "Authorization: token ${token}" \
+        "$url" 2>/dev/null); then
+        return 1
+    fi
+    # A valid base is a NONBLANK JSON STRING (T51P2WP5AR B3): null, numbers,
+    # and whitespace-only values are failed resolution, never a POSTed base.
+    branch=$(printf '%s' "$body" | python3 -c '
+import json, sys
+try:
+    value = json.load(sys.stdin).get("default_branch")
+except Exception:
+    sys.exit(1)
+if not isinstance(value, str) or not value.strip():
+    sys.exit(1)
+print(value.strip())
+' 2>/dev/null) || return 1
+    [[ -n "$branch" ]] || return 1
+    printf '%s' "$branch"
+}
+
 gitea_pr_create_api() {
    local host repo token url payload
    host=$(get_remote_host) || {
@@ -38,14 +73,28 @@ gitea_pr_create_api() {
        echo "Warning: API fallback applies title/body/head/base only; labels/milestone/draft require authenticated tea setup." >&2
    fi

-    payload=$(TITLE="$TITLE" BODY="$BODY" HEAD_BRANCH="$HEAD_BRANCH" BASE_BRANCH="$BASE_BRANCH" python3 - <<'PY'
+    # Base resolution (spec E4): an explicit -B always wins; with none, the
+    # forge default branch is resolved from the provider API -- never the
+    # historical "main" literal, which mistargeted every fallback PR on
+    # repos whose trunk is not main (e.g. mosaicstack/stack -> next).
+    local api_base=""
+    if [[ -n "$BASE_BRANCH" ]]; then
+        api_base="$BASE_BRANCH"
+    else
+        api_base=$(gitea_default_branch) || {
+            echo "Error: could not resolve the forge default branch for the API-fallback base; pass -B <branch> explicitly" >&2
+            return 1
+        }
+    fi
+
+    payload=$(TITLE="$TITLE" BODY="$BODY" HEAD_BRANCH="$HEAD_BRANCH" API_BASE="$api_base" python3 - <<'PY'
 import json
 import os

 payload = {
    "title": os.environ["TITLE"],
    "head": os.environ["HEAD_BRANCH"],
-    "base": os.environ["BASE_BRANCH"] or "main",
+    "base": os.environ["API_BASE"],
 }
 body = os.environ.get("BODY", "")
 if body:
@@ -72,7 +121,7 @@ Create a pull request on the current repository (Gitea or GitHub).
 Options:
    -t, --title TITLE       PR title (required, or use --issue)
    -b, --body BODY         PR description/body
-    -B, --base BRANCH       Base branch to merge into (default: main/master)
+    -B, --base BRANCH       Base branch to merge into (default: the forge repository's default branch)
    -H, --head BRANCH       Head branch with changes (default: current branch)
    -l, --labels LABELS     Comma-separated labels
    -m, --milestone NAME    Milestone name
@@ -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] [--expect-head SHA] [--no-ci-expected] [--co-author-trailers --escalate-to PRINCIPAL]

 set -euo pipefail

@@ -16,6 +16,7 @@ DRY_RUN=false
 EXPECT_HEAD=""
 CO_AUTHOR_TRAILERS=false
 ESCALATE_TO=""
+NO_CI_EXPECTED=false

 usage() {
    cat <<EOF
@@ -29,6 +30,7 @@ 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
+        --no-ci-expected    Assert the target repository has no CI: forward --no-ci-expected to the queue guard (requires repository admin)
        --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
@@ -70,6 +72,10 @@ while [[ $# -gt 0 ]]; do
            EXPECT_HEAD="$2"
            shift 2
            ;;
+        --no-ci-expected)
+            NO_CI_EXPECTED=true
+            shift
+            ;;
        --co-author-trailers)
            CO_AUTHOR_TRAILERS=true
            shift
@@ -154,13 +160,18 @@ if [[ "$DRY_RUN" != true ]]; then
    if [[ -z "$BASE_REPO" ]]; then
        BASE_REPO="$(get_repo_owner)/$(get_repo_name)"
    fi
-    "$SCRIPT_DIR/ci-queue-wait.sh" \
-        --purpose merge \
-        -B "$HEAD_BRANCH" \
-        -R "$BASE_REPO" \
-        --sha "$HEAD_SHA" \
-        -t "${MOSAIC_CI_QUEUE_TIMEOUT_SEC:-900}" \
+    guard_args=(
+        --purpose merge
+        -B "$HEAD_BRANCH"
+        -R "$BASE_REPO"
+        --sha "$HEAD_SHA"
+        -t "${MOSAIC_CI_QUEUE_TIMEOUT_SEC:-900}"
        -i "${MOSAIC_CI_QUEUE_POLL_SEC:-15}"
+    )
+    if [[ "$NO_CI_EXPECTED" == true ]]; then
+        guard_args+=(--no-ci-expected)
+    fi
+    "$SCRIPT_DIR/ci-queue-wait.sh" "${guard_args[@]}"
 fi

 PLATFORM=$(detect_platform)
@@ -0,0 +1,323 @@
+#!/usr/bin/env bash
+# Regression harness for ci-queue-wait.sh's --no-ci-expected assertion:
+# the sanctioned merge path for a repository with no CI configured at all.
+#
+# Zero status contexts ("no-status") stays fail-closed for --purpose merge
+# by default, because at merge time no-status can also mean "CI has not
+# reported yet". --no-ci-expected reclassifies ONLY that zero-context case
+# as queue-clear, and only for a caller whose acting token holds repository
+# admin. This harness pins:
+#   (a) merge + no-status + flag + admin     -> exit 0, audit line + JSONL.
+#   (b) merge + no-status, no flag           -> exit 3, existing text (unchanged).
+#   (c) merge + no-status + flag + non-admin -> exit 77 ASSERTION_REFUSED
+#       (distinct text, exit code NOT 3) + JSONL refusal record.
+#   (c2) flag + admin payload without the admin field -> fail closed as (c).
+#   (d) flag + --require-status              -> usage error, before any network.
+#   (e) flag + a real pending context        -> still holds (timeout 124),
+#       and the admin endpoint is never consulted.
+#   (f) push + no-status, with and without the flag -> push queue-clear
+#       unchanged; no admin consultation on push.
+#   (g) flag + admin lookup unreachable      -> CANNOT_ASSERT hold (75),
+#       not a silent pass and not a refusal.
+#   (h) flag + admin stub + NO MOSAIC_GIT_IDENTITY -> refusal BEFORE
+#       queue-clear and BEFORE the admin lookup: exit 78, no queue-clear
+#       line, an ASSERTION_UNATTRIBUTABLE JSONL record, no repos/ call.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/ci-queue-wait-no-ci-expected}"
+REPO_DIR="$WORK_DIR/repo"
+STUB_DIR="$WORK_DIR/stubs"
+URL_LOG="$WORK_DIR/urls.log"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$REPO_DIR" "$STUB_DIR"
+
+git -C "$REPO_DIR" init -q
+git -C "$REPO_DIR" remote add origin https://git.example.test/acme/widgets.git
+
+# Same stub conventions as test-ci-queue-wait-no-status.sh; adds the
+# repository-object endpoint (admin state) selected by MOSAIC_STUB_ADMIN_MODE.
+cat > "$STUB_DIR/curl" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+has_w=0
+url=""
+for arg in "$@"; do
+    case "$arg" in
+        -w) has_w=1 ;;
+        http://*|https://*) url="$arg" ;;
+    esac
+done
+printf '%s\n' "$url" >> "${MOSAIC_STUB_URL_LOG:?}"
+
+case "$url" in
+    */branches/*)
+        body='{"commit":{"id":"deadbeefcafef00d0123456789abcdef01234567"}}'
+        if [[ "$has_w" == 1 ]]; then
+            printf '%s\n200' "$body"
+        else
+            printf '%s' "$body"
+        fi
+        exit 0
+        ;;
+    */status)
+        mode="${MOSAIC_STUB_STATUS_MODE:?MOSAIC_STUB_STATUS_MODE not set}"
+        case "$mode" in
+            no-status)   body='{"state":"","statuses":[]}' ;;
+            real-pending) body='{"state":"pending","statuses":[{"context":"ci/woodpecker","status":"running","target_url":""}]}' ;;
+            *) echo "curl stub: unknown status mode=$mode" >&2; exit 2 ;;
+        esac
+        printf '%s' "$body"
+        exit 0
+        ;;
+    */repos/*)
+        mode="${MOSAIC_STUB_ADMIN_MODE:?MOSAIC_STUB_ADMIN_MODE not set}"
+        case "$mode" in
+            admin)          body='{"permissions":{"admin":true,"push":true,"pull":true}}' ;;
+            non-admin)      body='{"permissions":{"admin":false,"push":true,"pull":true}}' ;;
+            no-admin-field) body='{"permissions":{}}' ;;
+            unreachable)    exit 7 ;;
+            *) echo "curl stub: unknown admin mode=$mode" >&2; exit 2 ;;
+        esac
+        if [[ "$has_w" == 1 ]]; then
+            printf '%s\n200' "$body"
+        else
+            printf '%s' "$body"
+        fi
+        exit 0
+        ;;
+    *)
+        echo "curl stub: unrecognized URL: $url" >&2
+        exit 2
+        ;;
+esac
+SH
+chmod +x "$STUB_DIR/curl"
+
+failures=0
+
+run_guard() {
+    local name="$1"; shift
+    (
+        cd "$REPO_DIR" || exit
+        export PATH="$STUB_DIR:$PATH"
+        export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+        export MOSAIC_CI_QUEUE_AUDIT_LOG="$WORK_DIR/audit-$name.jsonl"
+        export MOSAIC_STUB_URL_LOG="$URL_LOG"
+        export GITEA_TOKEN="stub-token"
+        export GITEA_URL="https://git.example.test"
+        export MOSAIC_GIT_IDENTITY="test-identity"
+        "$SCRIPT_DIR/ci-queue-wait.sh" -B main -t 3 -i 1 "$@"
+    )
+}
+
+# The suite exports test-identity globally, so the unattributable-caller
+# case must strip it from the child environment at invocation with env -u,
+# not rely on the export order.
+run_guard_no_identity() {
+    local name="$1"; shift
+    (
+        cd "$REPO_DIR" || exit
+        export PATH="$STUB_DIR:$PATH"
+        export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+        export MOSAIC_CI_QUEUE_AUDIT_LOG="$WORK_DIR/audit-$name.jsonl"
+        export MOSAIC_STUB_URL_LOG="$URL_LOG"
+        export GITEA_TOKEN="stub-token"
+        export GITEA_URL="https://git.example.test"
+        export MOSAIC_GIT_IDENTITY="test-identity"
+        env -u MOSAIC_GIT_IDENTITY \
+            "$SCRIPT_DIR/ci-queue-wait.sh" -B main -t 3 -i 1 "$@"
+    )
+}
+
+expect_rc() {
+    local name="$1" want="$2" got="$3"
+    if [[ "$want" == "not3" ]]; then
+        if [[ "$got" -eq 0 || "$got" -eq 3 ]]; then
+            echo "FAIL $name: expected a refusal rc (nonzero, not 3), got $got" >&2
+            failures=$((failures + 1))
+            return 1
+        fi
+    elif [[ "$got" -ne "$want" ]]; then
+        echo "FAIL $name: expected rc=$want, got rc=$got" >&2
+        failures=$((failures + 1))
+        return 1
+    fi
+    return 0
+}
+
+expect_text() {
+    local name="$1" want="$2" output="$3" polarity="${4:-present}"
+    if [[ "$polarity" == "present" && "$output" != *"$want"* ]]; then
+        echo "FAIL $name: output missing '$want'" >&2
+        printf '%s\n' "$output" >&2
+        failures=$((failures + 1))
+    elif [[ "$polarity" == "absent" && "$output" == *"$want"* ]]; then
+        echo "FAIL $name: output unexpectedly contains '$want'" >&2
+        printf '%s\n' "$output" >&2
+        failures=$((failures + 1))
+    fi
+}
+
+repo_root_fetched() {
+    grep -q 'repos/acme/widgets$' "$URL_LOG"
+}
+
+# (a) merge + no-status + flag + admin -> exit 0, assertion line, JSONL record.
+: > "$URL_LOG"
+set +e
+out_a=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=admin run_guard a --purpose merge --no-ci-expected 2>&1)
+rc_a=$?
+set -u
+if expect_rc a 0 "$rc_a"; then
+    expect_text a "queue-clear state=no-status purpose=merge asserted-by=test-identity reason=no-ci-expected branch=main" "$out_a"
+    expect_text a "ASSERTED_NOT_READY" "$out_a" absent
+    if ! grep -q '"outcome":"NO_CI_ASSERTED"' "$WORK_DIR/audit-a.jsonl" 2>/dev/null; then
+        echo "FAIL a: expected a NO_CI_ASSERTED JSONL audit record" >&2
+        failures=$((failures + 1))
+    elif ! grep -q '"asserted_by":"test-identity"' "$WORK_DIR/audit-a.jsonl"; then
+        echo "FAIL a: audit record does not name the asserting identity" >&2
+        failures=$((failures + 1))
+    fi
+fi
+
+# (b) merge + no-status, no flag -> exit 3, existing error text unchanged.
+: > "$URL_LOG"
+set +e
+out_b=$(MOSAIC_STUB_STATUS_MODE=no-status run_guard b --purpose merge 2>&1)
+rc_b=$?
+set -u
+if expect_rc b 3 "$rc_b"; then
+    expect_text b "Error: ASSERTED_NOT_READY state=no-status purpose=merge branch=main." "$out_b"
+    expect_text b "asserted-by" "$out_b" absent
+fi
+if repo_root_fetched; then
+    echo "FAIL b: admin endpoint consulted without the flag" >&2
+    failures=$((failures + 1))
+fi
+
+# (c) merge + no-status + flag + non-admin -> distinct refusal, rc NOT 3.
+: > "$URL_LOG"
+set +e
+out_c=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=non-admin run_guard c --purpose merge --no-ci-expected 2>&1)
+rc_c=$?
+set -u
+if expect_rc c not3 "$rc_c"; then
+    if [[ "$rc_c" -ne 77 ]]; then
+        echo "FAIL c: expected the documented refusal rc=77, got $rc_c" >&2
+        failures=$((failures + 1))
+    fi
+    expect_text c "ASSERTION_REFUSED state=no-status purpose=merge asserted-by=test-identity reason=no-ci-expected branch=main" "$out_c"
+    expect_text c "ASSERTED_NOT_READY" "$out_c" absent
+    if ! grep -q '"outcome":"ASSERTION_REFUSED"' "$WORK_DIR/audit-c.jsonl" 2>/dev/null; then
+        echo "FAIL c: expected an ASSERTION_REFUSED JSONL audit record" >&2
+        failures=$((failures + 1))
+    fi
+fi
+
+# (c2) admin payload with no admin field -> fail closed as non-admin.
+: > "$URL_LOG"
+set +e
+out_c2=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=no-admin-field run_guard c2 --purpose merge --no-ci-expected 2>&1)
+rc_c2=$?
+set -u
+if expect_rc c2 77 "$rc_c2"; then
+    expect_text c2 "ASSERTION_REFUSED" "$out_c2"
+fi
+
+# (d) flag + --require-status -> usage error before any network I/O.
+: > "$URL_LOG"
+set +e
+out_d=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=admin run_guard d --purpose merge --no-ci-expected --require-status 2>&1)
+rc_d=$?
+set -u
+if expect_rc d 1 "$rc_d"; then
+    expect_text d "--no-ci-expected and --require-status contradict" "$out_d"
+fi
+if [[ -s "$URL_LOG" ]]; then
+    echo "FAIL d: usage error must precede every network call" >&2
+    failures=$((failures + 1))
+fi
+
+# (e) flag + a real pending context -> still holds; admin endpoint never asked.
+: > "$URL_LOG"
+set +e
+out_e=$(MOSAIC_STUB_STATUS_MODE=real-pending MOSAIC_STUB_ADMIN_MODE=admin run_guard e --purpose merge --no-ci-expected 2>&1)
+rc_e=$?
+set -u
+if expect_rc e 124 "$rc_e"; then
+    expect_text e "ASSERTED_NOT_READY" "$out_e"
+    expect_text e "ci/woodpecker=running" "$out_e"
+fi
+if repo_root_fetched; then
+    echo "FAIL e: a pending context must not trigger the admin assertion" >&2
+    failures=$((failures + 1))
+fi
+
+# (f) push + no-status stays queue-clear, with and without the flag.
+: > "$URL_LOG"
+set +e
+out_f=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=non-admin run_guard f --purpose push 2>&1)
+rc_f=$?
+set -u
+if expect_rc f 0 "$rc_f"; then
+    expect_text f "queue-clear state=no-status purpose=push branch=main; no queued or running CI." "$out_f"
+fi
+: > "$URL_LOG"
+set +e
+out_f2=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=non-admin run_guard f2 --purpose push --no-ci-expected 2>&1)
+rc_f2=$?
+set -u
+if expect_rc f2 0 "$rc_f2"; then
+    expect_text f2 "queue-clear state=no-status purpose=push branch=main; no queued or running CI." "$out_f2"
+    expect_text f2 "asserted-by" "$out_f2" absent
+fi
+if repo_root_fetched; then
+    echo "FAIL f: push must not consult the admin endpoint" >&2
+    failures=$((failures + 1))
+fi
+
+# (g) flag + admin lookup unreachable -> CANNOT_ASSERT hold (75), not a pass.
+: > "$URL_LOG"
+set +e
+out_g=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=unreachable run_guard g --purpose merge --no-ci-expected 2>&1)
+rc_g=$?
+set -u
+if expect_rc g 75 "$rc_g"; then
+    expect_text g "CANNOT_ASSERT reason=repo-permissions-unavailable" "$out_g"
+fi
+if ! grep -q '"outcome":"CANNOT_ASSERT"' "$WORK_DIR/audit-g.jsonl" 2>/dev/null; then
+    echo "FAIL g: expected a CANNOT_ASSERT JSONL audit record" >&2
+    failures=$((failures + 1))
+fi
+
+# (h) flag + admin stub + no asserting identity -> refusal before queue-clear
+# and before the admin lookup: rc 78, no queue-clear line, an
+# ASSERTION_UNATTRIBUTABLE JSONL record, and zero repos/ network calls.
+: > "$URL_LOG"
+set +e
+out_h=$(MOSAIC_STUB_STATUS_MODE=no-status MOSAIC_STUB_ADMIN_MODE=admin run_guard_no_identity h --purpose merge --no-ci-expected 2>&1)
+rc_h=$?
+set -u
+if expect_rc h 78 "$rc_h"; then
+    expect_text h "ASSERTION_UNATTRIBUTABLE state=no-status purpose=merge asserted-by=unknown reason=no-ci-expected branch=main" "$out_h"
+    expect_text h "queue-clear" "$out_h" absent
+    if ! grep -q '"outcome":"ASSERTION_UNATTRIBUTABLE"' "$WORK_DIR/audit-h.jsonl" 2>/dev/null; then
+        echo "FAIL h: expected an ASSERTION_UNATTRIBUTABLE JSONL audit record" >&2
+        failures=$((failures + 1))
+    fi
+fi
+if repo_root_fetched; then
+    echo "FAIL h: an unattributable caller must not trigger the permission lookup" >&2
+    failures=$((failures + 1))
+fi
+
+if [[ "$failures" -ne 0 ]]; then
+    echo "ci-queue-wait no-ci-expected regression failed ($failures assertions)" >&2
+    exit 1
+fi
+
+echo "ci-queue-wait no-ci-expected regression passed (all outcome classes)"
@@ -100,6 +100,15 @@ case "$url" in
    */commits/*/status)
        printf '{"state":"success","statuses":[{"context":"ci/mock","status":"success"}]}'
        ;;
+    # Repo roots: the pr-create API fallback resolves its base from the forge
+    # default_branch (T51-P2 WP5a). Exact-suffix matches so the /pulls POST
+    # endpoint (no trailing path) still falls through to the catch-all.
+    */api/v1/repos/USC/uconnect)
+        printf '{"default_branch":"main"}'
+        ;;
+    */api/v1/repos/mosaicstack/stack)
+        printf '{"default_branch":"next"}'
+        ;;
    *)
        printf '{}'
        ;;
@@ -67,7 +67,18 @@ cat > "$BIN_DIR/curl" <<'SH'
 #!/usr/bin/env bash
 set -euo pipefail
 printf 'curl %s\n' "$*" >> "$MOSAIC_TEST_LOG"
-printf '%s\n' '{"number":703}'
+# Repo roots: the pr-create API fallback resolves its base from the forge
+# default_branch (T51-P2 WP5a). Exact-suffix so every other endpoint keeps
+# the historical answer below.
+url="${*: -1}"
+case "$url" in
+    */api/v1/repos/mosaicstack/stack)
+        printf '%s\n' '{"default_branch":"next"}'
+        ;;
+    *)
+        printf '%s\n' '{"number":703}'
+        ;;
+esac
 SH
 chmod +x "$BIN_DIR/tea" "$BIN_DIR/curl"

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# test-pr-create-fallback-default-base.sh — hermetic test for the API-fallback
+# base resolution in pr-create.sh (T51-P2 WP5a / spec E4).
+#
+# The API-fallback payload historically hardcoded "base": "main", mistargeting
+# every fallback PR on repos whose trunk is not main (e.g. mosaicstack/stack,
+# default branch "next"). The fix: an explicit -B always wins; with none, the
+# base is resolved from the provider API default_branch, and a failed
+# resolution fails loud instead of guessing.
+#
+# Hermetic by construction: every curl invocation is a PATH-first stub; the
+# fixture repo's remote is git.example.test (never dialed); HOME is a sandbox
+# with no tea config (so the wrapper takes the API fallback path); GITEA_TOKEN
+# comes from the environment. No real forge is contacted.
+
+# shellcheck disable=SC2317
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-create-fallback-base}"
+
+PASS=0 FAIL=0 FAILED_CASES=""
+
+ok()  { PASS=$((PASS + 1)); }
+bad() { FAIL=$((FAIL + 1)); FAILED_CASES="$FAILED_CASES $1"; printf 'FAIL: %s\n' "$1" >&2; }
+
+assert_rc()    { local d="$1" e="$2" a="$3"; [ "$e" = "$a" ] && ok || bad "$d (expected rc=$e got rc=$a)"; }
+assert_eq()    { local d="$1" e="$2" a="$3"; [ "$e" = "$a" ] && ok || bad "$d (expected [$e] got [$a])"; }
+assert_contains() { local d="$1" h="$2" n="$3"; case "$h" in *"$n"*) ok ;; *) bad "$d (missing [$n])" ;; esac; }
+
+json_field() { # $1 payload file, $2 field
+    python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get(sys.argv[2], ""))' "$1" "$2"
+}
+
+rm -rf "$WORK_DIR"
+
+# ---- fixture -----------------------------------------------------------------
+ROOT="$WORK_DIR/fixture"
+TOOLS="$ROOT/tools/git"
+mkdir -p "$TOOLS" "$ROOT/repo" "$ROOT/home" "$ROOT/stub"
+cp "$SCRIPT_DIR/pr-create.sh" "$TOOLS/pr-create.sh"
+cp "$SCRIPT_DIR/detect-platform.sh" "$TOOLS/detect-platform.sh"
+
+git -C "$ROOT/repo" init -q -b fix/e4
+git -C "$ROOT/repo" -c user.name=fixture -c user.email=fixture@test commit -q --allow-empty -m base
+git -C "$ROOT/repo" remote add origin https://git.example.test/acme/widgets.git
+
+# curl stub: GET repo -> default_branch JSON (or failure mode); POST pulls ->
+# capture payload, answer with a minimal PR JSON. Every call is logged.
+cat > "$ROOT/stub/curl" <<STUB
+#!/usr/bin/env bash
+set -u
+mode="\${CURL_STUB_GET_MODE:-ok}"
+printf '%s\n' "\$*" >> "$ROOT/curl-calls.log"
+url="\${!#}"
+if [[ "\$url" == */api/v1/repos/acme/widgets ]]; then
+    # repo GET (default-branch resolution). Modes cover the value shapes the
+    # resolver must accept or refuse (T51P2WP5AR B2/B3).
+    case "\$mode" in
+        ok)         printf '%s\n' '{"id":1,"default_branch":"next","full_name":"acme/widgets"}' ;;
+        fail)       echo "curl stub: simulated repo lookup failure" >&2; exit 1 ;;
+        fail-json)  printf '%s\n' '{"default_branch":"next"}'; exit 22 ;;
+        null)       printf '%s\n' '{"default_branch":null}' ;;
+        numeric)    printf '%s\n' '{"default_branch":7}' ;;
+        blank)      printf '%s\n' '{"default_branch":"   "}' ;;
+        *)          echo "curl stub: unknown GET mode \$mode" >&2; exit 1 ;;
+    esac
+    exit 0
+fi
+if [[ "\$url" == */api/v1/repos/acme/widgets/pulls ]]; then
+    # PR POST: capture the payload, emit a PR-shaped answer
+    while [[ \$# -gt 0 ]]; do
+        case "\$1" in
+            -d) printf '%s' "\$2" > "$ROOT/payload.json"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+    printf '%s\n' '{"number":42,"html_url":"https://git.example.test/acme/widgets/pulls/42"}'
+    exit 0
+fi
+echo "curl stub: unexpected URL \$url" >&2
+exit 1
+STUB
+chmod +x "$ROOT/stub/curl"
+
+run_pr_create() { # args... -> sets RC/OUT/ERR
+    RC=0
+    OUT=$(cd "$ROOT/repo" && env -i \
+        PATH="$ROOT/stub:/usr/bin:/bin" \
+        HOME="$ROOT/home" \
+        GITEA_TOKEN=stub-token \
+        bash "$TOOLS/pr-create.sh" "$@" 2>"$ROOT/err.txt")
+    RC=$?
+    ERR="$(cat "$ROOT/err.txt")"
+}
+
+calls_matching() { grep -c -- "$1" "$ROOT/curl-calls.log" 2>/dev/null || true; }
+
+echo "== (1) no -B: fallback base resolves to the forge default branch, not main =="
+: > "$ROOT/curl-calls.log"; rm -f "$ROOT/payload.json"
+run_pr_create -t "fix thing"
+assert_rc "rc" 0 "$RC"
+assert_contains "API fallback path taken (tea login unresolvable in fixture)" "$ERR" "trying Gitea API fallback"
+assert_eq "repo GET performed" 1 "$(calls_matching '/api/v1/repos/acme/widgets$')"
+assert_eq "POST performed" 1 "$(calls_matching '/pulls$')"
+assert_eq "payload base is forge default (next)" "next" "$(json_field "$ROOT/payload.json" base)"
+assert_eq "payload head" "fix/e4" "$(json_field "$ROOT/payload.json" head)"
+assert_eq "payload title" "fix thing" "$(json_field "$ROOT/payload.json" title)"
+
+echo "== (2) explicit -B wins; the default branch is not consulted =="
+: > "$ROOT/curl-calls.log"; rm -f "$ROOT/payload.json"
+run_pr_create -t "fix thing" -B release/1.x
+assert_rc "rc" 0 "$RC"
+assert_eq "repo GET not consulted for explicit base" 0 "$(calls_matching '/api/v1/repos/acme/widgets$')"
+assert_eq "payload base is the explicit -B" "release/1.x" "$(json_field "$ROOT/payload.json" base)"
+
+echo "== (3) default-branch lookup failure: loud refusal, no POST =="
+: > "$ROOT/curl-calls.log"; rm -f "$ROOT/payload.json"
+RC=0
+OUT=$(cd "$ROOT/repo" && env -i \
+    PATH="$ROOT/stub:/usr/bin:/bin" \
+    HOME="$ROOT/home" \
+    GITEA_TOKEN=stub-token \
+    CURL_STUB_GET_MODE=fail \
+    bash "$TOOLS/pr-create.sh" -t "fix thing" 2>"$ROOT/err.txt")
+RC=$?
+ERR="$(cat "$ROOT/err.txt")"
+assert_rc "nonzero rc on unresolvable base" 1 "$RC"
+assert_contains "loud error names -B" "$ERR" "could not resolve the forge default branch"
+assert_contains "error names the remedy" "$ERR" "pass -B <branch> explicitly"
+assert_eq "no POST issued" 0 "$(calls_matching '/pulls$')"
+
+echo "== (4) payload never contains the literal fallback main =="
+: > "$ROOT/curl-calls.log"; rm -f "$ROOT/payload.json"
+run_pr_create -t "fix thing"
+assert_rc "rc" 0 "$RC"
+assert_eq "base field is next, never main" "next" "$(json_field "$ROOT/payload.json" base)"
+
+echo "== (5) B2: HTTP failure with parseable JSON on stdout is a FAILED resolution =="
+: > "$ROOT/curl-calls.log"; rm -f "$ROOT/payload.json"
+RC=0
+OUT=$(cd "$ROOT/repo" && env -i \
+    PATH="$ROOT/stub:/usr/bin:/bin" \
+    HOME="$ROOT/home" \
+    GITEA_TOKEN=stub-token \
+    CURL_STUB_GET_MODE=fail-json \
+    bash "$TOOLS/pr-create.sh" -t "fix thing" 2>"$ROOT/err.txt")
+RC=$?
+ERR="$(cat "$ROOT/err.txt")"
+assert_rc "nonzero rc on HTTP failure despite valid JSON" 1 "$RC"
+assert_contains "loud error names -B" "$ERR" "could not resolve the forge default branch"
+assert_contains "error names the remedy" "$ERR" "pass -B <branch> explicitly"
+assert_eq "no POST issued" 0 "$(calls_matching '/pulls$')"
+
+echo "== (6) B3: null / numeric / blank default_branch are failed resolutions =="
+for bad in null numeric blank; do
+    : > "$ROOT/curl-calls.log"; rm -f "$ROOT/payload.json"
+    RC=0
+    OUT=$(cd "$ROOT/repo" && env -i \
+        PATH="$ROOT/stub:/usr/bin:/bin" \
+        HOME="$ROOT/home" \
+        GITEA_TOKEN=stub-token \
+        CURL_STUB_GET_MODE="$bad" \
+        bash "$TOOLS/pr-create.sh" -t "fix thing" 2>"$ROOT/err.txt")
+    RC=$?
+    ERR="$(cat "$ROOT/err.txt")"
+    assert_rc "B3 $bad: nonzero rc" 1 "$RC"
+    assert_contains "B3 $bad: loud error" "$ERR" "could not resolve the forge default branch"
+    assert_eq "B3 $bad: no POST issued" 0 "$(calls_matching '/pulls$')"
+done
+
+echo
+echo "pass=$PASS fail=$FAIL"
+if [ "$FAIL" -gt 0 ]; then
+    echo "FAILED CASES:$FAILED_CASES"
+    exit 1
+fi
+echo "ALL GREEN"
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# pr-merge must forward --no-ci-expected to the queue guard, and only then.
+# The flag is the sanctioned merge path for a repository with no CI configured
+# (see test-ci-queue-wait-no-ci-expected.sh for the guard-side semantics);
+# this harness pins only the pass-through: present when requested, absent when
+# not, with the rest of the guard invocation unchanged.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-no-ci-expected}"
+FIXTURE_DIR="$WORK_DIR/tools/git"
+CALL_LOG="$WORK_DIR/queue-call.log"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$FIXTURE_DIR"
+cp "$SCRIPT_DIR/pr-merge.sh" "$FIXTURE_DIR/pr-merge.sh"
+cp "$SCRIPT_DIR/detect-platform.sh" "$FIXTURE_DIR/detect-platform.sh"
+
+cat > "$FIXTURE_DIR/pr-metadata.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' '{"baseRefName":"main","baseRepository":"mosaicstack/stack","headRefName":"fix/no-ci-fixture","headRefOid":"0123456789abcdef0123456789abcdef01234567","headRepository":"mosaicstack/stack"}'
+SH
+
+cat > "$FIXTURE_DIR/ci-queue-wait.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' "$*" > "${MOSAIC_QUEUE_CALL_LOG:?}"
+exit 42
+SH
+chmod +x "$FIXTURE_DIR"/*.sh
+
+run_merge() {
+    (
+        cd "$WORK_DIR"
+        export MOSAIC_QUEUE_CALL_LOG="$CALL_LOG"
+        "$FIXTURE_DIR/pr-merge.sh" -n 123 "$@"
+    ) >/dev/null 2>&1
+}
+
+fail=0
+
+# With the flag: it must reach the guard invocation.
+: > "$CALL_LOG"
+set +e
+run_merge --no-ci-expected
+rc_with=$?
+set -e
+if [[ "$rc_with" -ne 42 ]]; then
+    echo "FAIL(with): expected queue stub rc=42 to propagate, got $rc_with" >&2
+    fail=1
+elif ! grep -q -- '--no-ci-expected' "$CALL_LOG"; then
+    echo "FAIL(with): --no-ci-expected did not reach the queue guard" >&2
+    cat "$CALL_LOG" >&2
+    fail=1
+fi
+# The rest of the guard invocation is unchanged by the flag.
+for required in '--purpose merge' '-B fix/no-ci-fixture' '-R mosaicstack/stack' \
+    '--sha 0123456789abcdef0123456789abcdef01234567'; do
+    if ! grep -qF -- "$required" "$CALL_LOG"; then
+        echo "FAIL(with): guard invocation lost '$required'" >&2
+        cat "$CALL_LOG" >&2
+        fail=1
+    fi
+done
+
+# Without the flag: it must NOT appear in the guard invocation.
+: > "$CALL_LOG"
+set +e
+run_merge
+rc_without=$?
+set -e
+if [[ "$rc_without" -ne 42 ]]; then
+    echo "FAIL(without): expected queue stub rc=42 to propagate, got $rc_without" >&2
+    fail=1
+elif grep -q -- '--no-ci-expected' "$CALL_LOG"; then
+    echo "FAIL(without): --no-ci-expected reached the guard without being requested" >&2
+    cat "$CALL_LOG" >&2
+    fail=1
+fi
+
+if [[ "$fail" -eq 0 ]]; then
+    echo "pr-merge no-ci-expected pass-through regression passed"
+fi
+exit "$fail"
@@ -515,12 +515,40 @@ FIXTURES="$TMP/fixtures.tsv"
  printf '0\t{"tool_input":{"command":"curl -s https://git.example.invalid/api/v1/repos/a/b/issues?q=a%%20b"}}\ta percent-escape in a READ is not this hook'"'"'s business\n'
 } > "$FIXTURES"

+# Flake containment (#1380-FF, pipelines 2635/2637): a transient failure of the
+# ASSERTION TOOLING (grep rc>=2 — fork/alloc error under node pressure) is not a
+# contract drift, but the `if ! ... | grep -Fq` shape printed the identical
+# FAIL line for both, failing merge verifies on correct guard output. Classify
+# instead: retry tool errors 3x; rc=1 is the real mismatch; persistent tool
+# failure reports TOOL-ERROR (fail stays 1 — never green on infra noise — but
+# the line names the class so a re-run can be judged, not debugged).
+assert_out_contains() { # needle why
+  local attempt rc1
+  for attempt in 1 2 3; do
+    printf '%s' "$out" | grep -Fq -- "$1" && return 0
+    rc1=$?
+    [ "$rc1" -eq 1 ] && return 1   # grep answered NO — real mismatch
+    sleep 0.2                      # rc>=2: grep itself errored — retry
+  done
+  printf 'TOOL-ERROR %s (assertion grep failed 3x — infra/tooling, not guard drift)\n' "$2" >&2
+  return 2
+}
+
 fail=0 n=0
 while IFS=$'\t' read -r want payload why remedy; do
  [ -n "${want:-}" ] || continue
  n=$((n + 1))
  out="$(printf '%s' "$payload" | "$GUARD" 2>&1)"
  got=$?
+  # Flake containment (stack#1380-FF, pipeline 2635): a transient failure of
+  # the ASSERTION TOOLING (grep/fork/alloc error under node pressure) is not a
+  # contract drift, but this loop's `if !` shape made it indistinguishable
+  # from one — the harness printed the advice-mismatch FAIL and failed a merge
+  # verify on a run whose guard output was correct. Distinguish the two: an
+  # assertion tool that itself fails is retried a bounded number of times, and
+  # if it never succeeds the case reports a TOOL-ERROR line (fail=1 stays, so
+  # the run is never green-on-infra-noise, but the line names the real class
+  # and a re-run can be judged instead of debugged as a guard defect).
  if [ "$got" != "$want" ]; then
    printf 'FAIL  %s (want exit %s, got %s)\n' "$why" "$want" "$got"
    fail=1
@@ -530,10 +558,15 @@ while IFS=$'\t' read -r want payload why remedy; do
  # now it was invisible here: the harness read the exit code and nothing else,
  # so /issues/1/labels blocking with "use issue-create.sh" passed every run for
  # six rounds. Where a fixture states the remediation it expects, assert it.
-  if [ -n "${remedy:-}" ] && ! printf '%s' "$out" | grep -Fq -- "$remedy"; then
-    printf 'FAIL  %s (blocked, but the advice does not name %s)\n' "$why" "$remedy"
-    fail=1
-    continue
+  if [ -n "${remedy:-}" ]; then
+    assert_out_contains "$remedy" "$why"
+    arcret=$?
+    if [ "$arcret" -eq 1 ]; then
+      printf 'FAIL  %s (blocked, but the advice does not name %s)\n' "$why" "$remedy"
+      fail=1
+      continue
+    fi
+    [ "$arcret" -eq 0 ] || { fail=1; continue; }
  fi
  printf 'ok    %s\n' "$why"
 done < "$FIXTURES"
@@ -572,10 +605,15 @@ home_case() {
    fail=1
    return
  fi
-  if [ -n "$needle" ] && ! printf '%s' "$out" | grep -Fq -- "$needle"; then
-    printf 'FAIL  %s (exit %s, but the message does not say %s)\n' "$why" "$got" "$needle"
-    fail=1
-    return
+  if [ -n "$needle" ]; then
+    assert_out_contains "$needle" "$why"
+    arcret=$?
+    if [ "$arcret" -eq 1 ]; then
+      printf 'FAIL  %s (exit %s, but the message does not say %s)\n' "$why" "$got" "$needle"
+      fail=1
+      return
+    fi
+    [ "$arcret" -eq 0 ] || { fail=1; return; }
  fi
  printf 'ok    %s\n' "$why"
 }
@@ -665,10 +703,15 @@ lone_case() {
    fail=1
    return
  fi
-  if [ -n "$needle" ] && ! printf '%s' "$out" | grep -Fq -- "$needle"; then
-    printf 'FAIL  %s [standalone] (exit %s, but the message does not say %s)\n' "$why" "$got" "$needle"
-    fail=1
-    return
+  if [ -n "$needle" ]; then
+    assert_out_contains "$needle" "$why"
+    arcret=$?
+    if [ "$arcret" -eq 1 ]; then
+      printf 'FAIL  %s [standalone] (exit %s, but the message does not say %s)\n' "$why" "$got" "$needle"
+      fail=1
+      return
+    fi
+    [ "$arcret" -eq 0 ] || { fail=1; return; }
  fi
  printf 'ok    %s [standalone]\n' "$why"
 }
@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+# test-validate-repo-json.sh — hostile-input suite for the T51 declaration validator.
+# (Vendored with validate-repo-json.sh from mosaic-brain @ 515bcbab — see the
+# validator header for provenance.)
+#
+# Hermetic: all fixtures in a tracked mktemp sandbox removed by an EXIT trap
+# (pass and fail paths both — zero residue). No network, no real repos, no host
+# state mutated. MOSAIC_HOST_ROOT is set/unset per arm via env only.
+#
+# T51P2RW1: arms extended per review T51P2R1 (F1-F5): root gate for ordinary
+# v2 declarations (unset AND explicitly empty; display warns), git-grammar
+# branch arms (double slash, dot component, control byte), contract-escape
+# arms (list enums, invalid UTF-8, NaN — one VALIDATION_ERROR line, never a
+# traceback), remote normalization (.git/ ordering, port preservation), and
+# mirror-component fullmatch arms (trailing newline, control bytes).
+
+set -u
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+V="$HERE/validate-repo-json.sh"
+
+PASS=0; FAIL=0; FAILED=""
+ok()  { PASS=$((PASS+1)); }
+bad() { FAIL=$((FAIL+1)); FAILED="$FAILED $1"; printf 'FAIL: %s\n' "$1" >&2; }
+
+SB=$(mktemp -d "${TMPDIR:-/tmp}/vrj-test.XXXXXX")
+trap 'rm -rf "$SB"' EXIT
+
+fx() { printf '%s' "$2" > "$SB/$1"; }
+
+run() { # [env KV=V ...] -- args...
+  local envs=()
+  while [ "$1" != "--" ]; do envs+=("$1"); shift; done; shift
+  OUT=$(env "${envs[@]:-_=_}" bash "$V" "$@" 2>&1 < /dev/null; echo "__RC__$?")
+  RC=${OUT##*__RC__}; OUT=${OUT%__RC__*}; OUT=${OUT%$'\n'}
+}
+expect_ok()   { local d="$1"; shift; run "$@"; if [ "$RC" = 0 ] && printf '%s' "$OUT" | grep -q '^OK'; then ok; else bad "$d (rc=$RC out=$(printf '%s' "$OUT" | head -1))"; fi; }
+expect_err() { # desc expected-substring [env... -- args...]
+  local d="$1" sub="$2"; shift 2
+  run "$@"
+  if [ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "VALIDATION_ERROR.*$sub"; then ok
+  else bad "$d (rc=$RC, wanted error ~$sub, got: ${OUT%%$'\n'*})"; fi
+}
+expect_err_notrace() { # like expect_err, plus no traceback anywhere in output
+  local d="$1" sub="$2"; shift 2
+  run "$@"
+  if [ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "VALIDATION_ERROR.*$sub" && ! printf '%s' "$OUT" | grep -q "Traceback"; then ok
+  else bad "$d (rc=$RC, wanted clean error ~$sub, got: ${OUT%%$'\n'*})"; fi
+}
+
+STACK='{"schema_version":2,"integration_trunk":"next","release_branch":"main","flow":"trunk-release","canonical_remote":"https://git.mosaicstack.dev/mosaicstack/stack","canonical_clone":"host:/src/mosaic-stack","worktree_root":"host:/src/mosaic-stack-worktrees","worktree_policy":"orchestrator-precreated","notes":"x"}'
+BRAIN='{"schema_version":2,"integration_trunk":"main","release_branch":"main","flow":"direct","canonical_remote":"https://git.example.invalid/acme/brain","canonical_clone":"host:/.mosaic","worktree_root":"host:/.mosaic-worktrees","worktree_policy":"orchestrator-precreated"}'
+ROOT="$SB/hostroot"; mkdir -p "$ROOT"
+
+echo "== (0) syntax + version =="
+bash -n "$V" && ok || bad "bash -n"
+run -- --version; [ "$RC" = 0 ] && case "$OUT" in validate-repo-json\ *) ok ;; *) bad "version output" ;; esac || bad "version rc"
+
+echo "== (1) spec examples: stack + brain OK (root set) =="
+fx stack.json "$STACK"; fx brain.json "$BRAIN"
+expect_ok a1 MOSAIC_HOST_ROOT=$ROOT -- "$SB/stack.json"
+expect_ok a2 MOSAIC_HOST_ROOT=$ROOT -- "$SB/brain.json"
+
+echo "== (2) malformed JSON (stable contract, no traceback) =="
+fx bad.json '{"schema_version": 2, '
+expect_err_notrace b1 "json:" -- "$SB/bad.json"
+fx arr.json '[1,2]'
+expect_err_notrace b2 "top level" -- "$SB/arr.json"
+printf '\xff\xfe{"schema_version":2}' > "$SB/utf8.json"
+expect_err_notrace b3 "UTF-8" MOSAIC_HOST_ROOT=$ROOT -- "$SB/utf8.json"
+fx nan.json '{"schema_version":NaN}'
+expect_err_notrace b4 "malformed JSON" MOSAIC_HOST_ROOT=$ROOT -- "$SB/nan.json"
+
+echo "== (3) unknown schema_version = ABSENT-loud =="
+fx v3.json "${STACK/schema_version\":2/schema_version\":3}"
+expect_err c1 "schema_version" MOSAIC_HOST_ROOT=$ROOT -- "$SB/v3.json"
+
+echo "== (4) v1 mode + authoring rule (v1 consumes no paths: no root needed) =="
+fx v1.json '{"integration_trunk":"next","release_branch":"main"}'
+expect_ok  d1 -- "$SB/v1.json"
+expect_err d2 "schema_version" -- --require-v2 "$SB/v1.json"
+fx v1x.json '{"integration_trunk":"next","release_branch":"main","notes":"no"}'
+expect_err d3 "x_extensions" -- "$SB/v1x.json"
+
+echo "== (5) unknown top-level key rejected; x_extensions home OK =="
+fx unk.json "${STACK%\}*},\"typo_key\":1}"
+expect_err e1 "typo_key" MOSAIC_HOST_ROOT=$ROOT -- "$SB/unk.json"
+fx ext.json "${STACK%\}*},\"x_extensions\":{\"future\":true}}"
+expect_ok e2 MOSAIC_HOST_ROOT=$ROOT -- "$SB/ext.json"
+
+echo "== (6) flow: required (no defaulting) + cross-field =="
+fx noflow.json "$(printf '%s' "$STACK" | python3 -c 'import json,sys; d=json.load(sys.stdin); del d["flow"]; print(json.dumps(d))')"
+expect_err f1 "flow" MOSAIC_HOST_ROOT=$ROOT -- "$SB/noflow.json"
+fx xdirect.json "${STACK/\"trunk-release\"/\"direct\"}"
+expect_err f2 "direct" MOSAIC_HOST_ROOT=$ROOT -- "$SB/xdirect.json"
+fx xtr.json "${BRAIN/\"direct\"/\"trunk-release\"}"
+expect_err f3 "trunk-release" MOSAIC_HOST_ROOT=$ROOT -- "$SB/xtr.json"
+
+echo "== (7) dot-segment / empty-segment / tilde escapes =="
+fx dots.json "${STACK/host:\/src\/mosaic-stack\"/host:/src/../secrets\"}"
+expect_err g1 "dot segment" MOSAIC_HOST_ROOT=$ROOT -- "$SB/dots.json"
+fx dot1.json "${STACK/host:\/src\/mosaic-stack\"/host:/src/./mosaic-stack\"}"
+expect_err g2 "dot segment" MOSAIC_HOST_ROOT=$ROOT -- "$SB/dot1.json"
+fx empty.json "${STACK/host:\/src\/mosaic-stack\"/host://src/mosaic-stack\"}"
+expect_err g3 "empty segment" MOSAIC_HOST_ROOT=$ROOT -- "$SB/empty.json"
+fx tild.json "${STACK/host:\/src\/mosaic-stack\"/~jw/src/mosaic-stack\"}"
+expect_err g4 "tilde" MOSAIC_HOST_ROOT=$ROOT -- "$SB/tild.json"
+fx tailslash.json "${STACK/host:\/src\/mosaic-stack\"/host:/src/mosaic-stack/\"}"
+expect_err g5 "empty segment" MOSAIC_HOST_ROOT=$ROOT -- "$SB/tailslash.json"
+fx noanchor.json "${STACK/host:\/src\/mosaic-stack\"//src/mosaic-stack\"}"
+expect_err g6 "host:/" MOSAIC_HOST_ROOT=$ROOT -- "$SB/noanchor.json"
+
+echo "== (8) branch-name grammar (delegated to git check-ref-format, F2) =="
+fx badbr.json "${STACK/\"next\"/\"bad..name\"}"
+expect_err h1 "branch name" MOSAIC_HOST_ROOT=$ROOT -- "$SB/badbr.json"
+fx sp.json "${STACK/\"next\"/\"fea ture\"}"
+expect_err h2 "branch name" MOSAIC_HOST_ROOT=$ROOT -- "$SB/sp.json"
+fx lock.json "${STACK/\"next\"/\"feature/x.lock\"}"
+expect_err h3 "branch name" MOSAIC_HOST_ROOT=$ROOT -- "$SB/lock.json"
+fx slash.json "${STACK/\"next\"/\"feature/x\"}"
+expect_ok h4 MOSAIC_HOST_ROOT=$ROOT -- "$SB/slash.json"
+fx dslash.json "${STACK/\"next\"/\"feature//x\"}"
+expect_err h5 "branch name" MOSAIC_HOST_ROOT=$ROOT -- "$SB/dslash.json"
+fx hidden.json "${STACK/\"next\"/\"feature/.hidden\"}"
+expect_err h6 "branch name" MOSAIC_HOST_ROOT=$ROOT -- "$SB/hidden.json"
+fx ctrl.json "$(printf '%s' "$STACK" | python3 -c 'import json,sys; d=json.load(sys.stdin); d["integration_trunk"]="feature/\x01x"; print(json.dumps(d))')"
+expect_err h7 "branch name" MOSAIC_HOST_ROOT=$ROOT -- "$SB/ctrl.json"
+
+echo "== (8b) reflog shorthand rejected independent of ambient checkout history (B1) =="
+# Hermetic repo WITH checkout history: proves '@{-1}' (which git would expand to
+# 'main' from THIS repo's reflog) is still refused by the pre-delegation gate.
+HISTREPO="$SB/histrepo"; mkdir -p "$HISTREPO"
+(cd "$HISTREPO" && git init -q -b main . \
+  && git -c user.name=t -c user.email=t@t commit -q --allow-empty -m m \
+  && git checkout -q -b feature/x \
+  && git checkout -q main \
+  && git check-ref-format --branch "@{-1}" >/dev/null 2>&1 && echo "ambient-expandable" || echo "not-expandable") \
+  | grep -q ambient-expandable && ok || bad "fixture repo failed to make @{-1} expandable"
+fx atminus1.json "$(printf '%s' "$STACK" | python3 -c 'import json,sys; d=json.load(sys.stdin); d["integration_trunk"]="@{-1}"; print(json.dumps(d))')"
+# Run the validator from INSIDE the history repo via command substitution so the
+# assertion runs in the PARENT shell (T51P2R3 B1: the previous ( subshell ) form
+# mutated ok/bad counters only in a dead subshell — FAIL printed, suite rc 0).
+OUTX=$(cd "$HISTREPO" && MOSAIC_HOST_ROOT=$ROOT bash "$V" "$SB/atminus1.json" 2>&1 </dev/null; echo "__RC__$?")
+RCX=${OUTX##*__RC__}
+if [ "$RCX" = 1 ] && printf '%s' "$OUTX" | grep -q "VALIDATION_ERROR.*@{"; then ok
+else bad "@{-1} must be rejected inside a repo with checkout history (got rc=$RCX)"; fi
+fx atbrace.json "$(printf '%s' "$STACK" | python3 -c 'import json,sys; d=json.load(sys.stdin); d["integration_trunk"]="@{u}"; print(json.dumps(d))')"
+expect_err h9 "@{" MOSAIC_HOST_ROOT=$ROOT -- "$SB/atbrace.json"
+
+echo "== (9) canonical_remote: userinfo, list-type, normalization (F3/F4) =="
+fx user.json "${STACK/https:\/\/git.mosaicstack.dev/https:\/\/bot:s3cret@git.mosaicstack.dev}"
+expect_err_notrace i1 "userinfo" MOSAIC_HOST_ROOT=$ROOT -- "$SB/user.json"
+fx listflow.json "${STACK/\"trunk-release\"/[\"trunk-release\"]}"
+expect_err_notrace i2 "flow" MOSAIC_HOST_ROOT=$ROOT -- "$SB/listflow.json"
+fx listpol.json "${STACK/\"orchestrator-precreated\"/[\"tool-managed\"]}"
+expect_err_notrace i3 "worktree_policy" MOSAIC_HOST_ROOT=$ROOT -- "$SB/listpol.json"
+run -- --normalize-remote "HTTPS://Git.Example.Invalid/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://git.example.invalid/o/r" ] && ok || bad "norm .git/case ($OUT)"
+run -- --normalize-remote "https://git.mosaicstack.dev/mosaicstack/stack/"
+[ "$RC" = 0 ] && [ "$OUT" = "https://git.mosaicstack.dev/mosaicstack/stack" ] && ok || bad "norm trailing slash ($OUT)"
+run -- --normalize-remote "git.mosaicstack.dev/mosaicstack/stack"
+[ "$RC" = 1 ] && ok || bad "schemeless must fail"
+run -- --normalize-remote "HTTPS://Git.Example.Invalid/o/r.git/"
+[ "$RC" = 0 ] && [ "$OUT" = "https://git.example.invalid/o/r" ] && ok || bad "norm .git-then-slash ($OUT)"
+run -- --normalize-remote "https://Git.Example.Invalid:8443/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://git.example.invalid:8443/o/r" ] && ok || bad "port must be preserved ($OUT)"
+run -- --normalize-remote "https://[2001:db8::1]:8443/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://[2001:db8::1]:8443/o/r" ] && ok || bad "IPv6 must stay bracketed with port ($OUT)"
+run -- --normalize-remote "https://[2001:db8::1]/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://[2001:db8::1]/o/r" ] && ok || bad "IPv6 must stay bracketed ($OUT)"
+run -- --normalize-remote "https://Git.Example.Invalid:0/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://git.example.invalid:0/o/r" ] && ok || bad "explicit port 0 must be preserved ($OUT)"
+run -- --normalize-remote "https://[::1].evil.example/o/r.git"
+[ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "canonical_remote" && ok || bad "suffix after ] must be rejected (.evil.example)"
+run -- --normalize-remote "https://[::1]x:8443/o/r.git"
+[ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "canonical_remote" && ok || bad "suffix after ] must be rejected (x:8443)"
+run -- --normalize-remote "https://[::1]x/o/r.git"
+[ "$RC" = 1 ] && ok || bad "suffix after ] must be rejected (x)"
+echo "== (9b) IPvFuture bracketed authorities (R4-B1: guard keys off raw netloc) =="
+run -- --normalize-remote "https://[v1.fe80]/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://[v1.fe80]/o/r" ] && ok || bad "valid IPvFuture must keep brackets ($OUT)"
+run -- --normalize-remote "https://[vF.foo]:8443/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://[vf.foo]:8443/o/r" ] && ok || bad "valid IPvFuture+port must keep brackets ($OUT)"
+run -- --normalize-remote "https://[v1.fe80]evil/o/r.git"
+[ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "canonical_remote" && ok || bad "IPvFuture suffix must be rejected (evil)"
+run -- --normalize-remote "https://[v1.fe80].evil.example/o/r.git"
+[ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "canonical_remote" && ok || bad "IPvFuture suffix must be rejected (.evil.example)"
+run -- --normalize-remote "https://[vF.foo]x:8443/o/r.git"
+[ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "canonical_remote" && ok || bad "IPvFuture suffix must be rejected (x:8443)"
+echo "== (9d) non-bracketed authority grammar (R6-B1) =="
+for U in "https://:8443/o/r.git" "https://bad host/o/r.git" "https://bad^host/o/r.git" "https://bad\\host/o/r.git" "https://bad%zz/o/r.git" "https://bad%2/o/r.git" "https://bad%/o/r.git"; do
+  run -- --normalize-remote "$U"
+  if [ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "VALIDATION_ERROR canonical_remote"; then ok
+  else bad "non-bracketed authority must be rejected: $U (rc=$RC out=$OUT)"; fi
+done
+run -- --normalize-remote "https://git.mosaicstack.dev:9000/mosaicstack/stack"
+[ "$RC" = 0 ] && [ "$OUT" = "https://git.mosaicstack.dev:9000/mosaicstack/stack" ] && ok || bad "valid host:port unchanged ($OUT)"
+run -- --normalize-remote "https://192.168.1.10:8443/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://192.168.1.10:8443/o/r" ] && ok || bad "IPv4 reg-name stays valid ($OUT)"
+run -- --normalize-remote "https://bad%2Fx/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://bad%2fx/o/r" ] && ok || bad "complete %HH must stay legal, case-normalized ($OUT)"
+echo "== (9e) ASCII-only authority bytes (R7-B1) =="
+# isolated port arm (R8): VALID ASCII host + full-width-digit port ONLY —
+# unconfounded, so restoring Unicode-aware isdigit() goes red right here.
+run -- --normalize-remote "https://git.example.invalid:４４３/o/r.git"
+if [ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "ASCII digits only"; then ok
+else bad "full-width-digit port on a VALID host must be rejected with the port reason (rc=$RC out=$OUT)"; fi
+for U in "https://éxample.invalid/o/r.git" "https://例え.テスト/o/r.git" "https://full－width.invalid/o/r.git" "https://mosaic－stack.dev:４４３/o/r.git"; do
+  run -- --normalize-remote "$U"
+  if [ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "VALIDATION_ERROR canonical_remote"; then ok
+  else bad "non-ASCII authority must be rejected: $U (rc=$RC out=$OUT)"; fi
+done
+run -- --normalize-remote "https://xn--xample-9ua.invalid/o/r.git"
+[ "$RC" = 0 ] && [ "$OUT" = "https://xn--xample-9ua.invalid/o/r" ] && ok || bad "punycode xn-- host must stay legal ($OUT)"
+echo "== (9c) bracket-payload grammar + raw control bytes (R5-B1) =="
+for P in "v1. " "v1.a b" "v1.a^b" "v1.a\\b" "v1.%20" "not-an-ip" "::gg::1"; do
+  run -- --normalize-remote "https://[$P]/o/r.git"
+  if [ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "VALIDATION_ERROR canonical_remote"; then ok
+  else bad "bracket payload [$P] must be rejected (rc=$RC out=$OUT)"; fi
+done
+for CB in $'\t' $'\n' $'\r'; do
+  run -- --normalize-remote "https://[v1.a${CB}b]/o/r.git"
+  if [ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "control byte"; then ok
+  else bad "raw control byte must be rejected before urlsplit (rc=$RC out=$OUT)"; fi
+done
+run -- --normalize-remote "https://[v1.fe80%zone]/o/r.git"
+[ "$RC" = 1 ] && ok || bad "percent (not in RFC host grammar) must be rejected ($OUT)"
+run -- --normalize-remote "https://[fe80::1%eth0]/o/r.git"
+[ "$RC" = 1 ] && printf '%s' "$OUT" | grep -q "canonical_remote" && ok || bad "IPv6 zone-id (not RFC host grammar) must be rejected ($OUT)"
+
+echo "== (10) root gate: every v2 managed validation fails closed (F1) =="
+# NOTE (spec §4.5): host:/ paths resolve UNDER MOSAIC_HOST_ROOT by construction,
+# so tool-managed is not declarable today — the cross-check fails for every
+# host:/ root until the anchor scheme grows an outside-root form (J3 era).
+expect_err j1 "MOSAIC_HOST_ROOT" MOSAIC_HOST_ROOT= -- "$SB/stack.json"
+expect_err j2 "MOSAIC_HOST_ROOT" MOSAIC_HOST_ROOT= -- "$SB/brain.json"
+expect_err j3 "MOSAIC_HOST_ROOT" MOSAIC_HOST_ROOT= -- "$SB/stack.json"
+# rider (T51P2R2): genuine ABSENCE, not just explicitly empty — captured via
+# command substitution, asserted in the parent shell (no subshell-counter shape).
+OUTU=$(cd "$SB" && env -u MOSAIC_HOST_ROOT bash "$V" "$SB/stack.json" 2>&1 </dev/null; echo "__RC__$?")
+RCU=${OUTU##*__RC__}
+if [ "$RCU" = 1 ] && printf '%s' "$OUTU" | grep -q "VALIDATION_ERROR.*MOSAIC_HOST_ROOT"; then ok
+else bad "unset-by-absence root must fail closed in managed mode (rc=$RCU)"; fi
+run MOSAIC_HOST_ROOT= -- --mode display "$SB/stack.json"
+if [ "$RC" = 0 ] && printf '%s' "$OUT" | grep -q '^OK' && printf '%s' "$OUT" | grep -q "host root unset"; then ok
+else bad "display-mode unset must pass with the specified warning (rc=$RC)"; fi
+run MOSAIC_HOST_ROOT= -- --mode display "$SB/brain.json"
+if [ "$RC" = 0 ] && printf '%s' "$OUT" | grep -q "host root unset"; then ok
+else bad "display-mode warn missing for brain fixture"; fi
+TM='{"schema_version":2,"integration_trunk":"next","release_branch":"main","flow":"trunk-release","canonical_remote":"https://git.mosaicstack.dev/mosaicstack/stack","canonical_clone":"host:/src/mosaic-stack","worktree_root":"host:/src/mosaic-stack-worktrees","worktree_policy":"tool-managed"}'
+fx tm.json "$TM"; mkdir -p "$ROOT/src"
+expect_err j4 "inside MOSAIC_HOST_ROOT" MOSAIC_HOST_ROOT=$ROOT -- "$SB/tm.json"
+fx tm_noroot.json "$(printf '%s' "$TM" | python3 -c 'import json,sys; d=json.load(sys.stdin); del d["worktree_root"]; print(json.dumps(d))')"
+expect_err j5 "worktree_root" MOSAIC_HOST_ROOT=$ROOT -- "$SB/tm_noroot.json"
+echo "== (10b) symlink escape cannot fake outside-ness (B3 fix: lexical containment) =="
+OUTSIDE="$SB/outside-target"; mkdir -p "$OUTSIDE"
+ln -s "$OUTSIDE" "$ROOT/escape"
+TM_ESC="${TM/host:\/src\/mosaic-stack-worktrees/host:/escape/worktrees}"
+fx tmsym.json "$TM_ESC"
+expect_err j6 "inside MOSAIC_HOST_ROOT" MOSAIC_HOST_ROOT=$ROOT -- "$SB/tmsym.json"
+
+echo "== (11) mirror-path components: collision/delimiter/control fixtures (F5) =="
+run -- --mirror-path git.mosaicstack.dev mosaicstack stack
+[ "$RC" = 0 ] && [ "$OUT" = "projects/git.mosaicstack.dev/mosaicstack/stack/repo.json" ] && ok || bad "mirror path ok ($OUT)"
+expect_err k1 "mirror-component" -- --mirror-path "git.mosaicstack.dev" "a__b" "c"
+expect_err k2 "mirror-component" -- --mirror-path "git.mosaicstack.dev" "a" "b__c"
+expect_err k3 "mirror-component" -- --mirror-path "git.mosaicstack.dev/x" "a" "b"
+expect_err k4 "mirror-component" -- --mirror-path "git.mosaicstack.dev" "A" "B"
+expect_err k5 "mirror-component" -- --mirror-path "git.mosaicstack.dev" "" "stack"
+run -- --mirror-path git.mosaicstack.dev a b.c
+[ "$RC" = 0 ] && [ "$OUT" = "projects/git.mosaicstack.dev/a/b.c/repo.json" ] && ok || bad "distinct path ($OUT)"
+run -- --mirror-path $'git.example.invalid\n' owner repo
+[ "$RC" = 1 ] && ok || bad "trailing-newline host must be rejected (fullmatch)"
+run -- --mirror-path $'git.\texample' owner repo
+[ "$RC" = 1 ] && ok || bad "control-byte host must be rejected"
+
+echo "== (12) missing required keys =="
+for key in release_branch canonical_clone; do
+  fx miss.json "$(printf '%s' "$STACK" | python3 -c "import json,sys; d=json.load(sys.stdin); del d['$key']; print(json.dumps(d))")"
+  expect_err "l-$key" "$key" MOSAIC_HOST_ROOT=$ROOT -- "$SB/miss.json"
+done
+
+echo "== (13) absent file =="
+expect_err m1 "file" -- "$SB/nonexistent.json"
+
+echo
+echo "pass=$PASS fail=$FAIL"
+if [ "$FAIL" -gt 0 ]; then echo "FAILED:$FAILED"; exit 1; fi
+echo "ALL GREEN"
@@ -0,0 +1,386 @@
+#!/usr/bin/env bash
+# validate-repo-json.sh — declaration validator for T51 repo structure declarations.
+#
+# Spec of record: docs/plans/2026-08-23_repo-structure-declaration.md @ 1896adc1
+# (R3). Implements the spec's validation surface: schema v1/v2 (§1.2), host:/
+# path grammar with canonical segment normalization — empty/./.. rejected
+# BEFORE resolution — and tilde rejection (§1.2a), mirror path component
+# validation (§3.1), cross-field rules (§5.2), remote normalization (§5.3).
+#
+# PROVENANCE (T51 WP5c vendoring): ported verbatim from the mosaic-brain tree —
+# tools/repo-structure-decl/validate-repo-json.sh @ brain main merge 515bcbab
+# (PR 28, wave-1 R9 PASS, 101-arm suite green). This file is now the framework
+# home per spec §5.1 ("shipped in the framework package"); the brain copy is the
+# development origin. Re-sync rule: changes land here via reviewed PR and are
+# back-ported to the brain tree (or the brain copy retires) — never fork silently.
+# Validator version at port: 1.1.0+t51spec-r3+t51p2rw1 (R2-R8 rework included).
+# No operator literal appears in this file; the host root is read from
+# MOSAIC_HOST_ROOT configuration only.
+#
+# Unset-root semantics (spec §1.2a, fail-closed; T51P2R1 F1): v2 declarations
+# always consume a path (canonical_clone is required), so in --mode managed an
+# unset OR EMPTY MOSAIC_HOST_ROOT is a VALIDATION_ERROR for every v2 file —
+# not only tool-managed. In --mode display it warns and omits root-dependent
+# resolution; grammar checks still run.
+#
+# Error contract (T51P2R1 F3): every malformed input — bad UTF-8, non-RFC JSON
+# constants (NaN/Infinity), wrong-typed enums, anything unexpected — yields
+# exactly one stable VALIDATION_ERROR line and exit 1. No traceback ever
+# escapes. Branch names are validated by delegating to `git check-ref-format
+# --branch` (F2), translated into this contract.
+#
+# Usage:
+#   validate-repo-json.sh <repo.json> [--mode managed|display] [--require-v2]
+#   validate-repo-json.sh --mirror-path <host> <owner> <repo>   # §3.1 component check
+#   validate-repo-json.sh --normalize-remote <url>              # §5.3, prints normalized
+#   validate-repo-json.sh --version
+#
+# Output: OK (exit 0) | VALIDATION_ERROR <key>: <reason> (exit 1) | warnings on stderr.
+set -euo pipefail
+
+VERSION="1.1.0+t51spec-r3+t51p2rw1"
+
+if [ "${1:-}" = "--version" ]; then echo "validate-repo-json $VERSION"; exit 0; fi
+
+exec python3 - "$@" <<'PYEOF'
+import json, os, re, subprocess, sys, urllib.parse
+
+def err(key, reason):
+    print(f"VALIDATION_ERROR {key}: {reason}")
+    sys.exit(1)
+
+def warn(msg):
+    print(f"warning: {msg}", file=sys.stderr)
+
+def main():
+    ARGS = sys.argv[1:]
+    MODE = "managed"
+    REQUIRE_V2 = False
+
+    # ---- subcommands first (they take no file argument) ----
+    def check_mirror_components(host, owner, repo):
+        # fullmatch: '$' must bind at true end (F5 — a trailing newline must
+        # NOT pass); the charset excludes control bytes outright.
+        comp_re = re.compile(r"[a-z0-9][a-z0-9.-]*")
+        for label, value in (("host", host), ("owner", owner), ("repo", repo)):
+            if not isinstance(value, str) or not value or not comp_re.fullmatch(value):
+                err("mirror-component", f"{label} {value!r} fails §3.1 charset ^[a-z0-9][a-z0-9.-]*$ (fullmatch, no '/', no delimiter, no control bytes)")
+        return f"projects/{host}/{owner}/{repo}/repo.json"
+
+    def normalize_remote(url):
+        # R5-B1 part 1: reject raw control bytes BEFORE urlsplit — urlsplit
+        # silently strips TAB/LF/CR, so different input bytes would normalize
+        # to a different host. The raw bytes ARE the input; nothing may rewrite them.
+        for ch in url:
+            if ord(ch) < 0x20 or ord(ch) == 0x7F:
+                err("canonical_remote", "control byte in URL rejected before parsing (urlsplit would strip it and change the host)")
+        try:
+            p = urllib.parse.urlsplit(url)
+        except ValueError as e:
+            # py3.12 urlsplit itself validates bracketed hosts (ipaddress) and
+            # raises for garbage authorities — translate, never traceback.
+            err("canonical_remote", f"invalid URL authority: {e}")
+        if not p.scheme or not p.netloc:
+            err("canonical_remote", f"not a URL with scheme+host: {url!r}")
+        if p.username or p.password or "@" in (p.netloc or ""):
+            err("canonical_remote", "userinfo in URL is rejected (§5.3)")
+        scheme = p.scheme.lower()
+        # T51P2R4 B1: bracketing is detected from the RAW netloc ('[' prefix),
+        # not from a ':' in the parsed hostname — IPvFuture literals ([v1.fe80])
+        # contain no colon and must not bypass the raw-authority proof.
+        bracketed = p.netloc.startswith("[")
+        if bracketed:
+            # Prove the RAW authority is exactly '[host]' + optional ':port'
+            # (case-normalized); any text after ']' is hostile/truncated input,
+            # rejected — never silently rewritten.
+            import re as _re
+            import ipaddress as _ip
+            m = _re.fullmatch(r"\[([^\]]*)\](?::([0-9]+))?", p.netloc)
+            if not m:
+                err("canonical_remote", f"malformed bracketed authority {p.netloc!r}: text after ']' is rejected (no silent truncation)")
+            payload = m.group(1)
+            # R5-B1 part 2: the bracket payload must be a REAL RFC literal —
+            # an IPv6 address (ipaddress parse) or an IPvFuture literal
+            # ("v" + HEXDIG+ + "." + unreserved / sub-delims / ":" only).
+            # Anything else inside brackets is rejected, closing the payload
+            # grammar as a class.
+            if _re.fullmatch(r"v[0-9A-Fa-f]+\.[A-Za-z0-9._~!$&'()*+,;=:-]*", payload):
+                pass  # IPvFuture (case-normalized below)
+            elif _re.fullmatch(r"[0-9A-Fa-f:.]+", payload):
+                # strict IPv6 lexical form (hex/colon/dot only — ipaddress alone
+                # would also accept scoped zone-ids like fe80::1%eth0, which are
+                # not valid URI host grammar unless %25-encoded)
+                try:
+                    _ip.IPv6Address(payload)
+                except ValueError:
+                    err("canonical_remote",
+                        f"bracket payload {payload!r} is not a valid IPv6 address")
+            else:
+                err("canonical_remote",
+                    f"bracket payload {payload!r} is neither a valid IPv6 address nor an IPvFuture literal (v+HEXDIG+.+unreserved/sub-delims/colon)")
+            host = f"[{payload.lower()}]"  # brackets preserved (IPv6 + IPvFuture)
+        else:
+            # R6-B1: the non-bracketed branch — urlsplit PARSES but does not
+            # VALIDATE reg-name, and netloc-nonempty is not host presence.
+            # Split the raw authority ourselves (host[:port]) and validate the
+            # raw host against real grammar: unreserved / sub-delims / complete
+            # %HH octets (reg-name), or IPv4 dotted-quad (reg-name's numeric
+            # case). Port must be all digits. No branch trusts urlsplit alone.
+            import re as _re
+            raw_host, sep, raw_port = p.netloc.rpartition(":")
+            if sep and _re.fullmatch(r"[0-9]+", raw_port):
+                pass  # host:port split
+            elif sep:
+                err("canonical_remote", f"invalid port {raw_port!r} in authority {p.netloc!r} (ASCII digits only)")
+            else:
+                raw_host, raw_port = p.netloc, None
+            if not raw_host:
+                err("canonical_remote", f"empty host in authority {p.netloc!r}")
+            # strict reg-name / IPv4 scan: unreserved + sub-delims, with '%'
+            # only inside complete %HH octets (IPv4 dotted-quad is a subset of
+            # this charset — digits and dots — so one scan covers both).
+            import re as _re
+            i = 0
+            ok_host = True
+            while i < len(raw_host):
+                c = raw_host[i]
+                if c == "%":
+                    if i + 2 >= len(raw_host) or not _re.fullmatch(r"[0-9A-Fa-f]{2}", raw_host[i+1:i+3]):
+                        ok_host = False; break
+                    i += 3
+                elif c in "!$&'()*+,;=-._~" or ("a" <= c <= "z") or ("A" <= c <= "Z") or ("0" <= c <= "9"):
+                    # R7-B1: EXPLICIT ASCII only — str.isalnum() is Unicode-aware
+                    # and admits non-ASCII letters/digits (é, full-width ０). Policy
+                    # is ASCII-only reg-name; punycode xn-- is the sanctioned
+                    # Unicode spelling and remains legal under this charset.
+                    i += 1
+                else:
+                    ok_host = False; break
+            if not ok_host:
+                err("canonical_remote", f"host {raw_host!r} is not valid reg-name/IPv4 grammar (unreserved/sub-delims/complete %HH only)")
+            host = raw_host.lower()
+        port = p.port  # None when absent; preserved whenever explicitly present (B2: incl. 0)
+        authority = host + (f":{port}" if port is not None else "")
+        path = p.path or "/"
+        # canonical trailing-slash + .git strip as ONE operation (F4): slash
+        # first, then .git, then any slash exposed by that strip.
+        path = path.rstrip("/")
+        if path.endswith(".git"):
+            path = path[:-4].rstrip("/")
+        return f"{scheme}://{authority}{path or ''}"
+
+    if "--mirror-path" in ARGS:
+        idx = ARGS.index("--mirror-path")
+        parts = ARGS[idx + 1:]
+        if len(parts) != 3:
+            err("usage", "--mirror-path takes <host> <owner> <repo>")
+        print(check_mirror_components(*parts))
+        sys.exit(0)
+    if "--normalize-remote" in ARGS:
+        idx = ARGS.index("--normalize-remote")
+        vals = ARGS[idx + 1:]
+        if len(vals) != 1:
+            err("usage", "--normalize-remote takes <url>")
+        print(normalize_remote(vals[0]))
+        sys.exit(0)
+
+    # ---- arg parsing ----
+    if not ARGS:
+        err("usage", "a repo.json path is required")
+    path = None
+    i = 0
+    while i < len(ARGS):
+        a = ARGS[i]
+        if a == "--mode":
+            i += 1
+            if i >= len(ARGS) or ARGS[i] not in ("managed", "display"):
+                err("usage", "--mode takes managed|display")
+            MODE = ARGS[i]
+        elif a == "--require-v2":
+            REQUIRE_V2 = True
+        elif a.startswith("--"):
+            err("usage", f"unknown option {a}")
+        else:
+            if path is not None:
+                err("usage", "multiple file arguments")
+            path = a
+        i += 1
+    if path is None:
+        err("usage", "a repo.json path is required")
+
+    # ---- load: strict UTF-8, strict RFC JSON (F3) ----
+    try:
+        with open(path, "rb") as fh:
+            raw_bytes = fh.read()
+    except OSError as e:
+        err("file", str(e))
+    try:
+        raw = raw_bytes.decode("utf-8")
+    except UnicodeDecodeError as e:
+        err("json", f"invalid UTF-8: {e}")
+    def _reject_constant(name):
+        raise ValueError(f"non-RFC JSON constant {name}")
+    try:
+        doc = json.loads(raw, parse_constant=_reject_constant)
+    except (json.JSONDecodeError, ValueError) as e:
+        err("json", f"malformed JSON: {e}")
+    if not isinstance(doc, dict):
+        err("json", "top level must be an object")
+
+    HOST_ROOT = os.environ.get("MOSAIC_HOST_ROOT", "")
+
+    V1_KEYS = {"integration_trunk", "release_branch"}
+    V2_REQUIRED = ["schema_version", "integration_trunk", "release_branch", "flow",
+                   "canonical_remote", "canonical_clone"]
+    V2_OPTIONAL = {"worktree_root", "worktree_policy", "notes", "x_extensions"}
+    ENUM_FLOW = {"direct", "trunk-release"}
+    ENUM_POLICY = {"tool-managed", "orchestrator-precreated"}
+
+    def check_branch(key, value):
+        # Delegate the full git branch grammar to git itself (F2). B1: reject
+        # reflog shorthand BEFORE delegation — `git check-ref-format --branch
+        # '@{-n}'` expands from the CALLER repo's checkout history, making
+        # validation cwd-dependent; a persistent declaration must never bind
+        # to ambient reflog state.
+        if not isinstance(value, str) or not value:
+            err(key, "must be a non-empty string")
+        if "@{" in value:
+            err(key, f"{value!r} contains '@{{' reflog/namespace shorthand — declarations must be literal branch names (B1)")
+        if value.startswith("refs/heads/"):  # check-ref-format --branch strips this; we do not allow it
+            err(key, "bare branch name expected, not a full ref")
+        try:
+            r = subprocess.run(["git", "check-ref-format", "--branch", value],
+                               capture_output=True)
+        except OSError as e:
+            err(key, f"cannot invoke git check-ref-format: {e}")
+        if r.returncode != 0:
+            err(key, f"{value!r} is not a valid git branch name (git check-ref-format, §5.2)")
+
+    def check_host_path(key, value):
+        # §1.2a: host:/-anchored; canonical segment normalization; empty/./.. rejected
+        # BEFORE resolution; tilde rejected outright.
+        if not isinstance(value, str) or not value:
+            err(key, "must be a non-empty string")
+        if "~" in value:
+            err(key, "tilde-anchored path rejected (§1.2a: ~ binds to caller HOME)")
+        if not value.startswith("host:/"):
+            err(key, "must be host:/-anchored (§1.2a)")
+        rest = value[len("host:/"):]
+        if rest == "":
+            err(key, "no segments after host:/")
+        segments = rest.split("/")
+        for seg in segments:
+            if seg == "":
+                err(key, f"empty segment in {value!r} (canonical normalization, §1.2a)")
+            if seg in (".", ".."):
+                err(key, f"dot segment {seg!r} rejected before resolution (§1.2a)")
+        return segments
+
+    # ---- version ----
+    sv = doc.get("schema_version")
+    if "schema_version" in doc:
+        if not isinstance(sv, int) or isinstance(sv, bool):
+            err("schema_version", "must be an integer")
+        if sv not in (1, 2):
+            err("schema_version", f"unknown schema_version {sv} — treated as ABSENT per keep-list K3; update tooling")
+        version = sv
+    else:
+        version = 1
+        warn("schema_version absent → v1 compatibility mode (two keys only)")
+
+    if REQUIRE_V2 and version != 2:
+        err("schema_version", "CI authoring rule: new or edited declarations must declare schema_version 2")
+
+    # ---- v1 ----
+    if version == 1:
+        for k in V1_KEYS:
+            check_branch(k, doc.get(k))
+        extra = set(doc) - V1_KEYS
+        if extra:
+            err("x_extensions", f"unknown top-level keys in v1: {sorted(extra)}")
+        print("OK (v1)")
+        sys.exit(0)
+
+    # ---- v2 required ----
+    for k in V2_REQUIRED:
+        if k not in doc:
+            err(k, "required for v2 (§1.2)")
+
+    check_branch("integration_trunk", doc["integration_trunk"])
+    check_branch("release_branch", doc["release_branch"])
+
+    # type-check BEFORE membership (F3: list-typed enums must not traceback)
+    if not isinstance(doc["flow"], str) or doc["flow"] not in ENUM_FLOW:
+        err("flow", f"must be one of {sorted(ENUM_FLOW)} (§1.2, required — no defaulting, R7)")
+
+    unknown = set(doc) - set(V2_REQUIRED) - V2_OPTIONAL
+    if unknown:
+        err("x_extensions", f"unknown top-level keys {sorted(unknown)} — place extensions inside x_extensions")
+
+    if "worktree_policy" in doc and (not isinstance(doc["worktree_policy"], str)
+                                     or doc["worktree_policy"] not in ENUM_POLICY):
+        err("worktree_policy", f"must be one of {sorted(ENUM_POLICY)}")
+    if "notes" in doc and not isinstance(doc["notes"], str):
+        err("notes", "must be a string")
+    if "x_extensions" in doc and not isinstance(doc["x_extensions"], dict):
+        err("x_extensions", "must be an object")
+    for strkey in ("canonical_remote", "canonical_clone", "worktree_root"):
+        if strkey in doc and not isinstance(doc[strkey], str):
+            err(strkey, "must be a string")
+
+    # ---- remote (§5.3) ----
+    if not isinstance(doc["canonical_remote"], str):
+        err("canonical_remote", "must be a string")
+    else:
+        normalize_remote(doc["canonical_remote"])
+
+    # ---- paths (§1.2a) ----
+    canonical_segments = check_host_path("canonical_clone", doc["canonical_clone"])
+    wt_segments = None
+    if "worktree_root" in doc:
+        wt_segments = check_host_path("worktree_root", doc["worktree_root"])
+
+    # ---- cross-field (§5.2) ----
+    trunk, rel, flow = doc["integration_trunk"], doc["release_branch"], doc["flow"]
+    if flow == "direct" and trunk != rel:
+        err("flow", "direct requires integration_trunk == release_branch (§5.2)")
+    if flow == "trunk-release" and trunk == rel:
+        err("flow", "trunk-release requires integration_trunk != release_branch (§5.2)")
+
+    # ---- root gate (§1.2a fail-closed; T51P2R1 F1) ----
+    # Every v2 declaration consumes a path (canonical_clone is required), so
+    # managed mode cannot proceed without a provable host anchor. Display mode
+    # warns and omits root-dependent resolution only.
+    if not HOST_ROOT:
+        if MODE == "managed":
+            err("MOSAIC_HOST_ROOT",
+                "unset or empty — managed validation of a v2 declaration consumes paths "
+                "(canonical_clone required); fail closed (§1.2a, DR3 X2b)")
+        else:
+            warn("host root unset; root-dependent resolution omitted (display mode, §1.2a)")
+
+    if doc.get("worktree_policy") == "tool-managed":
+        if "worktree_root" not in doc:
+            err("worktree_policy", "tool-managed requires worktree_root (containment provable, §4.5)")
+        if HOST_ROOT:
+            root_real = os.path.realpath(HOST_ROOT)
+            # B3 fix: containment is tested on the LEXICAL normalized path, not
+            # on realpath of the joined result — a child symlink under the host
+            # root can no longer fake outside-ness. host:/ segments are always
+            # lexically under the root, so tool-managed fails universally until
+            # the anchor scheme grows a real outside-root form (J3 charter).
+            resolved = os.path.normpath(os.path.join(root_real, *wt_segments))
+            if resolved == root_real or resolved.startswith(root_real + os.sep):
+                err("worktree_policy",
+                    f"tool-managed worktree_root resolves inside MOSAIC_HOST_ROOT (§4.5: outside-root requirement)")
+        # no-root case: managed mode already failed at the gate above; display warned
+
+    print("OK")
+
+try:
+    main()
+except SystemExit:
+    raise
+except Exception as e:  # F3: no traceback may ever escape the contract
+    err("internal", f"input rejected (unexpected condition: {type(e).__name__})")
+PYEOF
@@ -25,7 +25,7 @@
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.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/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_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-edit.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-no-status.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-fork-ci-status.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/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.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 && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.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/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_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-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.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-no-status.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-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.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/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.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 && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -15,6 +15,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { ClackPrompter } from '../../prompter/clack-prompter.js';
+import type { VerifyResult } from './verify.js';
 import type { WizardState } from '../../types.js';

 interface InstallOpts {
@@ -89,13 +90,23 @@ export async function runInstall(opts: InstallOpts): Promise<void> {
    prompter.log(`  Logs:      mosaic gateway logs`);
    prompter.log(`  Status:    mosaic gateway status`);

-    // Post-install verification (CU-07-03) — non-fatal.
+    // Post-install verification (CU-07-03). Health/token/bootstrap failures
+    // stay non-fatal (courtesy checks), but a FAILED database schema check is
+    // fatal (#1392): an install that reports success over an empty/partial
+    // database is the exact T63 failure this command must never reproduce.
+    let verifyResult: VerifyResult | undefined;
    try {
      const { runPostInstallVerification } = await import('./verify.js');
-      await runPostInstallVerification(configResult.host, configResult.port);
+      verifyResult = await runPostInstallVerification(configResult.host, configResult.port);
    } catch {
      // Non-fatal — verification is a courtesy
    }
+    if (verifyResult && verifyResult.schemaMigrated === false) {
+      prompter.warn(
+        'Gateway install ABORTED: database schema verification failed (remediation above).',
+      );
+      process.exit(1);
+    }
  } catch (err) {
    // Stages normally return structured results for expected failures.
    // Anything that reaches here is an unexpected runtime error — render a
@@ -0,0 +1,156 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  checkDatabaseSchema,
+  SCHEMA_FAIL_REMEDIATION,
+  type SchemaCheckDeps,
+} from './schema-check.js';
+
+/* ------------------------------------------------------------------ */
+/*  Fixture config                                                     */
+/* ------------------------------------------------------------------ */
+
+const tmpDirs: string[] = [];
+
+function writeConfig(cfg: Record<string, unknown>): string {
+  const dir = mkdtempSync(join(tmpdir(), 'schema-check-'));
+  tmpDirs.push(dir);
+  const path = join(dir, 'mosaic.config.json');
+  writeFileSync(path, JSON.stringify(cfg));
+  return path;
+}
+
+const STANDALONE_CFG = {
+  tier: 'standalone',
+  storage: { type: 'postgres', url: 'postgresql://u:p@localhost:5434/x' },
+  queue: { type: 'bullmq', url: 'redis://localhost:6380' },
+  memory: { type: 'keyword' },
+};
+
+const LOCAL_CFG = {
+  tier: 'local',
+  storage: { type: 'pglite', dataDir: '.mosaic/storage-pglite' },
+  queue: { type: 'local', dataDir: '.mosaic/queue' },
+  memory: { type: 'keyword' },
+};
+
+function deps(overrides: Partial<SchemaCheckDeps> = {}): SchemaCheckDeps {
+  return {
+    runMigrations: vi.fn().mockResolvedValue(undefined),
+    getMigrationStatus: vi.fn().mockResolvedValue({
+      appliedCount: 17,
+      expectedCount: 17,
+      expectedLastTag: '0016_x',
+      complete: true,
+    }),
+    ...overrides,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Tests                                                              */
+/* ------------------------------------------------------------------ */
+
+describe('checkDatabaseSchema', () => {
+  beforeEach(() => {
+    process.env['MOSAIC_CONFIG'] = '';
+    vi.stubEnv('DATABASE_URL', 'postgresql://env:env@localhost:9999/env');
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    for (const d of tmpDirs.splice(0)) rmSync(d, { recursive: true, force: true });
+  });
+
+  it('passes when the ledger matches the shipped journal', async () => {
+    const cfg = writeConfig(STANDALONE_CFG);
+    const d = deps();
+    const result = await checkDatabaseSchema(d, cfg);
+    expect(result.status).toBe('ok');
+    expect(result.detail).toContain('17/17');
+    expect(d.runMigrations).toHaveBeenCalledWith(STANDALONE_CFG.storage.url);
+    expect(d.getMigrationStatus).toHaveBeenCalledWith(STANDALONE_CFG.storage.url);
+  });
+
+  it('FAILS when the ledger is incomplete — the #1389 empty-database signature', async () => {
+    const cfg = writeConfig(STANDALONE_CFG);
+    const d = deps({
+      getMigrationStatus: vi.fn().mockResolvedValue({
+        appliedCount: 0,
+        expectedCount: 17,
+        expectedLastTag: '0016_x',
+        complete: false,
+      }),
+    });
+    const result = await checkDatabaseSchema(d, cfg);
+    expect(result.status).toBe('fail');
+    if (result.status !== 'fail') throw new Error('expected fail');
+    expect(result.detail).toContain('0/17');
+    expect(result.remediation).toBe(SCHEMA_FAIL_REMEDIATION);
+    expect(result.remediation).toContain('#1389');
+  });
+
+  it('FAILS when the ledger is only PARTIALLY migrated (#1402 upgrade case)', async () => {
+    const cfg = writeConfig(STANDALONE_CFG);
+    const d = deps({
+      getMigrationStatus: vi.fn().mockResolvedValue({
+        appliedCount: 9,
+        expectedCount: 17,
+        expectedLastTag: '0016_x',
+        complete: false,
+      }),
+    });
+    const result = await checkDatabaseSchema(d, cfg);
+    expect(result.status).toBe('fail');
+    expect(result.detail).toContain('9/17');
+  });
+
+  it('FAILS (never crashes) when the migration run itself throws', async () => {
+    const cfg = writeConfig(STANDALONE_CFG);
+    const d = deps({
+      runMigrations: vi.fn().mockRejectedValue(new Error('connection refused')),
+    });
+    const result = await checkDatabaseSchema(d, cfg);
+    expect(result.status).toBe('fail');
+    expect(result.detail).toContain('connection refused');
+  });
+
+  it('skips the local tier (gateway migrates its own PGlite at startup)', async () => {
+    const cfg = writeConfig(LOCAL_CFG);
+    const d = deps();
+    const result = await checkDatabaseSchema(d, cfg);
+    expect(result.status).toBe('skipped');
+    expect(d.runMigrations).not.toHaveBeenCalled();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/*  Config resolution priority                                         */
+/* ------------------------------------------------------------------ */
+
+describe('resolveSchemaCheckConfigPath', () => {
+  it('prefers the daemon-written gateway config over cwd copies', async () => {
+    const { resolveSchemaCheckConfigPath } = await import('./schema-check.js');
+    const cwdCfg = writeConfig(STANDALONE_CFG); // in a temp dir
+    const daemonDir = mkdtempSync(join(tmpdir(), 'schema-check-daemon-'));
+    tmpDirs.push(daemonDir);
+    const daemonHome = join(daemonDir, '.config', 'mosaic', 'gateway');
+    mkdirSync(daemonHome, { recursive: true });
+    writeFileSync(join(daemonHome, 'mosaic.config.json'), JSON.stringify(LOCAL_CFG));
+
+    const prevHome = process.env['HOME'];
+    vi.stubEnv('HOME', daemonDir);
+    vi.stubEnv('MOSAIC_CONFIG', '');
+    try {
+      const resolved = resolveSchemaCheckConfigPath();
+      // Must NOT pick the cwd copy (cwd is the vitest project dir, not our
+      // temp dir — so the only resolvable candidates are daemon + $HOME/.mosaic).
+      expect(resolved).toBe(join(daemonHome, 'mosaic.config.json'));
+      void cwdCfg;
+    } finally {
+      if (prevHome !== undefined) vi.stubEnv('HOME', prevHome);
+    }
+  });
+});
@@ -0,0 +1,107 @@
+/**
+ * Install-time database schema verification (#1392).
+ *
+ * Fresh standalone (postgres) installs once ended "healthy" with a completely
+ * empty database: the resolved dependency set shipped no migrations at all
+ * (#1389), the gateway started fine, and nothing failed until the first real
+ * query. The issue's own conclusion: the installer must "instruct and verify".
+ *
+ * This check runs AFTER migrations have been (re-)applied, so the only way it
+ * fails is a genuinely broken migration set or database — which is exactly
+ * when install must not report success. Failure is fatal by design (fast-fail
+ * STANDARDS); callers print the remediation text and exit non-zero.
+ */
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { loadConfig } from '@mosaicstack/config';
+
+export interface SchemaStatusCounts {
+  appliedCount: number;
+  expectedCount: number;
+  expectedLastTag: string;
+  complete: boolean;
+}
+
+/** Injectable migration surface — keeps this unit-testable without a DB. */
+export interface SchemaCheckDeps {
+  runMigrations(url: string): Promise<void>;
+  getMigrationStatus(url: string): Promise<SchemaStatusCounts>;
+}
+
+export type SchemaCheckResult =
+  | { status: 'ok'; detail: string }
+  | { status: 'skipped'; detail: string }
+  | { status: 'fail'; detail: string; remediation: string };
+
+export const SCHEMA_FAIL_REMEDIATION = [
+  'The gateway database does not carry the full schema.',
+  'Causes seen in the wild: dependency set resolved without migrations (#1389), or a partially-migrated database (#1402).',
+  'Remediation:',
+  '  1. Re-run: mosaic gateway install  (applies migrations and verifies again)',
+  '  2. Check the resolved @mosaicstack/db version is the same pipeline as the gateway (npm ls -g @mosaicstack/db)',
+  '  3. Manual apply: run runMigrations() from @mosaicstack/db against the storage URL, then re-verify',
+].join('\n');
+
+/**
+ * Resolve the config the INSTALLED gateway would use — same priority the
+ * daemon applies (apps/gateway/src/env.ts resolveGatewayConfigPath), minus
+ * the source-tree anchors that do not exist on an installed host. Verifying
+ * against any other config could green-light a database the daemon never
+ * reads (#1392: verify what runs, not what happens to lie in cwd).
+ */
+export function resolveSchemaCheckConfigPath(explicit?: string): string | undefined {
+  if (explicit) return resolve(explicit);
+  const candidates = [
+    process.env['MOSAIC_CONFIG'],
+    join(homedir(), '.config', 'mosaic', 'gateway', 'mosaic.config.json'), // daemon-written
+    resolve(process.cwd(), 'mosaic.config.json'),
+    join(homedir(), '.mosaic', 'mosaic.config.json'),
+  ];
+  for (const c of candidates) {
+    if (c && existsSync(c)) return c;
+  }
+  return undefined; // loadConfig falls back to env-var detection
+}
+
+export async function checkDatabaseSchema(
+  deps: SchemaCheckDeps,
+  configPath?: string,
+): Promise<SchemaCheckResult> {
+  const config = loadConfig(resolveSchemaCheckConfigPath(configPath));
+
+  // Local tier: the gateway itself runs PGlite migrations at startup (see
+  // DatabaseModule.onModuleInit), and a broken local tier fails the health
+  // check instead. Nothing for the installer to verify here.
+  if (config.storage.type !== 'postgres') {
+    return {
+      status: 'skipped',
+      detail: 'database schema (local tier — migrated by gateway at startup)',
+    };
+  }
+
+  const url = config.storage.url;
+  try {
+    await deps.runMigrations(url);
+    const status = await deps.getMigrationStatus(url);
+    if (status.complete) {
+      return {
+        status: 'ok',
+        detail: `database schema (${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations)`,
+      };
+    }
+    return {
+      status: 'fail',
+      detail: `database schema incomplete (${status.appliedCount.toString()}/${status.expectedCount.toString()} applied, last expected: ${status.expectedLastTag})`,
+      remediation: SCHEMA_FAIL_REMEDIATION,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      status: 'fail',
+      detail: `database schema check errored: ${msg}`,
+      remediation: SCHEMA_FAIL_REMEDIATION,
+    };
+  }
+}
@@ -44,6 +44,8 @@ export interface VerifyResult {
  gatewayHealthy: boolean;
  adminTokenOnFile: boolean;
  bootstrapReachable: boolean;
+  /** False only on a FAILED postgres schema check; true when ok or skipped. */
+  schemaMigrated: boolean;
  allPassed: boolean;
 }

@@ -89,7 +91,36 @@ export async function runPostInstallVerification(
    fail('bootstrap endpoint reach', 'Run: mosaic gateway status  /  mosaic gateway logs');
  }

-  const allPassed = gatewayHealthy && adminTokenOnFile && bootstrapReachable;
+  // ─── Check 4: Database schema migrated (#1392) ────────────────────────────
+  // Fatal-on-failure for install: the #1389 failure mode was an install that
+  // reported success over an empty database. Local tiers skip (the gateway
+  // migrates its own PGlite at startup and would fail health if it couldn't).
+  let schemaMigrated = true;
+  try {
+    const { checkDatabaseSchema } = await import('./schema-check.js');
+    const { runMigrations, getMigrationStatus } = await import('@mosaicstack/db');
+    const result = await checkDatabaseSchema(
+      { runMigrations, getMigrationStatus },
+      process.env['MOSAIC_CONFIG'],
+    );
+    if (result.status === 'ok') {
+      ok(result.detail);
+    } else if (result.status === 'skipped') {
+      ok(result.detail);
+    } else {
+      fail(result.detail, result.remediation);
+      schemaMigrated = false;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    fail(
+      `database schema check errored: ${msg}`,
+      'See #1392/#1389; re-run: mosaic gateway install',
+    );
+    schemaMigrated = false;
+  }
+
+  const allPassed = gatewayHealthy && adminTokenOnFile && bootstrapReachable && schemaMigrated;

  if (!allPassed) {
    console.log(
@@ -98,7 +129,7 @@ export async function runPostInstallVerification(
    );
  }

-  return { gatewayHealthy, adminTokenOnFile, bootstrapReachable, allPassed };
+  return { gatewayHealthy, adminTokenOnFile, bootstrapReachable, schemaMigrated, allPassed };
 }

 /**
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import {
  chmodSync,
  mkdtempSync,
@@ -16,6 +16,7 @@ import {
  renderPeerReach,
  readFleetCommsBlock,
  resolveCommsBlock,
+  resolveFleetIdentity,
  resolvePeerCommand,
  renderToolsContractStatus,
 } from './comms-onboarding.js';
@@ -61,6 +62,68 @@ describe('shared fleet roster v1 resolver', () => {
    });
  });

+  // stack#1380 verification unblock: the fleet's own roster-v2 tooling writes
+  // the v1 body plus a generation fence and seat lifecycle/launch envelopes.
+  // The parser tolerates exactly that envelope (validated, opaque to comms).
+  const V2_ROSTER = [
+    'version: 2',
+    'generation: 8',
+    'transport: tmux',
+    'tmux:',
+    '  socket_name: mosaic-fleet',
+    'defaults:',
+    '  working_directory: ~/.mosaic',
+    '  runtime: claude',
+    'agents:',
+    '  - name: orch-01',
+    '    runtime: claude',
+    '    class: orchestrator',
+    '    model: opus',
+    '    reasoning: high',
+    '    lifecycle:',
+    '      enabled: true',
+    '      desired_state: running',
+    '    launch:',
+    '      yolo: false',
+    '',
+  ].join('\n');
+
+  it('accepts the roster-v2 envelope (generation + lifecycle/launch) on the v1 body', () => {
+    const resolved = parseFleetRosterV1(V2_ROSTER, 'yaml');
+    expect(resolved.tmux.socketName).toBe('mosaic-fleet');
+    expect(resolved.agents[0]?.name).toBe('orch-01');
+  });
+
+  it('rejects a non-integer generation', () => {
+    expect(() =>
+      parseFleetRosterV1(V2_ROSTER.replace('generation: 8', 'generation: eight'), 'yaml'),
+    ).toThrow(/generation must be a non-negative integer/);
+  });
+
+  it('rejects an invalid lifecycle desired_state', () => {
+    expect(() =>
+      parseFleetRosterV1(
+        V2_ROSTER.replace('desired_state: running', 'desired_state: paused'),
+        'yaml',
+      ),
+    ).toThrow(/desired_state must be running\|stopped/);
+  });
+
+  it('rejects unknown fields inside the lifecycle envelope', () => {
+    expect(() =>
+      parseFleetRosterV1(
+        V2_ROSTER.replace('      enabled: true', '      enabled: true\n      surprise: 1'),
+        'yaml',
+      ),
+    ).toThrow(/lifecycle has unknown field/);
+  });
+
+  it('rejects a non-boolean launch.yolo', () => {
+    expect(() =>
+      parseFleetRosterV1(V2_ROSTER.replace('yolo: false', 'yolo: sometimes'), 'yaml'),
+    ).toThrow(/launch\.yolo must be a boolean/);
+  });
+
  it('rejects unknown fields instead of leniently constructing a second roster view', () => {
    expect(() => parseFleetRosterV1(`${ROSTER}\nunknown: value\n`, 'yaml')).toThrow(
      /unknown field/i,
@@ -493,6 +556,11 @@ describe('resolvePeerCommand', () => {
 describe('readFleetCommsBlock — spawned-agent context', () => {
  let home: string;
  beforeEach(() => {
+    // Hermetic helper fallback (stack#1380): the resolver probes
+    // $HOME/.config/mosaic when mosaicHome itself carries no helper — point
+    // HOME at a sandbox parent so tests never see the real host install.
+    vi.stubEnv('HOME', mkdtempSync(join(tmpdir(), 'mosaic-homeless-')));
+    vi.stubEnv('MOSAIC_HOME', '');
    home = mkdtempSync(join(tmpdir(), 'mosaic-comms-'));
    mkdirSync(join(home, 'fleet'), { recursive: true });
    mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
@@ -501,7 +569,10 @@ describe('readFleetCommsBlock — spawned-agent context', () => {
    writeFileSync(helper, '#!/bin/sh\n');
    chmodSync(helper, 0o755);
  });
-  afterEach(() => rmSync(home, { recursive: true, force: true }));
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    rmSync(home, { recursive: true, force: true });
+  });

  it('uses the authoritative self host and global socket from the shared roster resolver', () => {
    const result = readFleetCommsBlock(home, 'enhancer', 'process-host-must-not-win');
@@ -564,23 +635,27 @@ describe('readFleetCommsBlock — spawned-agent context', () => {
      },
    ],
    [
-      'symlink',
+      'symlink escaping the install home',
      () => {
        const helper = join(home, 'tools', 'tmux', 'agent-send.sh');
        rmSync(helper);
-        writeFileSync(join(home, 'real-send.sh'), '#!/bin/sh\n');
-        symlinkSync(join(home, 'real-send.sh'), helper);
+        const outside = mkdtempSync(join(tmpdir(), 'mosaic-helper-outside-'));
+        writeFileSync(join(outside, 'real-send.sh'), '#!/bin/sh\n', { mode: 0o755 });
+        symlinkSync(join(outside, 'real-send.sh'), helper);
      },
    ],
    ['non-executable', () => chmodSync(join(home, 'tools', 'tmux', 'agent-send.sh'), 0o644)],
-  ])('fails closed for a %s helper with deterministic repair guidance', (_case, mutate) => {
-    mutate();
-    const result = readFleetCommsBlock(home, 'enhancer', 'w-jarvis');
-    expect(result.ok).toBe(false);
-    expect(result.output).toBe('');
-    expect(result.error).toContain('mosaic update --repair-tools');
-    expect(result.error).toContain('no active context or session was rewritten');
-  });
+  ])(
+    'fails closed for a %s helper with deterministic guidance (no forbidden remedy)',
+    (_case, mutate) => {
+      mutate();
+      const result = readFleetCommsBlock(home, 'enhancer', 'w-jarvis');
+      expect(result.ok).toBe(false);
+      expect(result.output).toBe('');
+      expect(result.error).not.toContain('--repair-tools'); // stack#1380 M5a
+      expect(result.error).toContain('no active context or session was rewritten');
+    },
+  );

  it('does not rewrite the roster while resolving context', () => {
    const path = join(home, 'fleet', 'roster.yaml');
@@ -603,11 +678,11 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {
  });
  afterEach(() => rmSync(home, { recursive: true, force: true }));

-  it('uses the supported repair command when installed TOOLS.md is missing', () => {
+  it('names operator-verified recovery instead of a forbidden remedy when installed TOOLS.md is missing', () => {
    const status = renderToolsContractStatus(home);
-    expect(status).toContain('mosaic update --repair-tools');
-    expect(status).not.toContain('--reseed');
    expect(status).toContain('authorized operator');
+    expect(status).not.toContain('--repair-tools'); // stack#1380 M5a
+    expect(status).not.toContain('--reseed');
  });

  it('reports stale preserved content without rewriting it', () => {
@@ -616,8 +691,8 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {
    writeFileSync(path, stale);
    const status = renderToolsContractStatus(home);
    expect(status).toContain('fleet-comms-contract: 1');
-    expect(status).toContain('digest-qualified backup');
-    expect(status).toContain('mosaic update --repair-tools');
+    expect(status).toContain('authorized operator');
+    expect(status).not.toContain('--repair-tools'); // stack#1380 M5a
    expect(status).toContain('active context was not rewritten');
    expect(readFileSync(path, 'utf8')).toBe(stale);
  });
@@ -648,7 +723,7 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {
    expect(renderToolsContractStatus(home)).not.toBe('');
  });

-  it('treats installed TOOLS.md symlinks as stale without following or rewriting them', () => {
+  it('reads an installed TOOLS.md symlink whose validated target diverges (stack#1380 resolve-then-validate)', () => {
    const external = join(home, 'external-tools.md');
    const externalContent = '# external\n<!-- fleet-comms-contract: 1 -->\n';
    writeFileSync(external, externalContent);
@@ -656,24 +731,23 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {

    const status = renderToolsContractStatus(home);

-    expect(status).toContain('unavailable');
-    expect(status).toContain('mosaic update --repair-tools');
+    expect(status).toContain('does not byte-match');
    expect(readFileSync(external, 'utf8')).toBe(externalContent);
  });

-  it('treats source TOOLS.md symlinks as unavailable without following them', () => {
-    const external = join(home, 'external-source.md');
+  it('treats a source TOOLS.md symlink escaping the install home as unavailable', () => {
+    const outside = mkdtempSync(join(tmpdir(), 'mosaic-source-outside-'));
    const content = '# authoritative tools\n<!-- fleet-comms-contract: 1 -->\n';
-    writeFileSync(external, content);
+    writeFileSync(join(outside, 'external-source.md'), content);
    rmSync(join(home, 'defaults', 'TOOLS.md'));
-    symlinkSync(external, join(home, 'defaults', 'TOOLS.md'));
+    symlinkSync(join(outside, 'external-source.md'), join(home, 'defaults', 'TOOLS.md'));
    writeFileSync(join(home, 'TOOLS.md'), content);

    const status = renderToolsContractStatus(home);

    expect(status).toContain('source contract');
    expect(status).toContain('unavailable');
-    expect(readFileSync(external, 'utf8')).toBe(content);
+    expect(readFileSync(join(outside, 'external-source.md'), 'utf8')).toBe(content);
  });

  it('accepts byte-equal bounded source and installed contracts', () => {
@@ -730,3 +804,91 @@ describe('resolveCommsBlock — mosaic agent comms-block', () => {
    expect(result.error).toContain('requires');
  });
 });
+
+describe('resolveFleetIdentity — stack#1380 split-home layouts', () => {
+  // Brain-shaped mosaicHome (fleet state, NO tools/tmux) + framework config
+  // home carrying the helper, roster unified by the framework-created symlink
+  // <configHome>/fleet/roster.yaml -> <brain>/fleet/roster.yaml. This is the
+  // host layout that was down; all probes are POSITIONAL per the #1380
+  // verification protocol (an object arg proves nothing — M5b). HOME is
+  // stubbed so the config-default fallback stays inside the sandbox.
+  let brain: string;
+  let configHome: string;
+
+  beforeEach(() => {
+    const parent = mkdtempSync(join(tmpdir(), 'mosaic-i1380-parent-'));
+    brain = join(parent, 'brain');
+    // Framework home at the stubbed DEFAULT location so the fallback derives
+    // exactly as in production ($HOME/.config/mosaic), not by coincidence.
+    configHome = join(parent, 'home', '.config', 'mosaic');
+    vi.stubEnv('HOME', join(parent, 'home'));
+    vi.stubEnv('MOSAIC_HOME', '');
+    mkdirSync(join(brain, 'fleet'), { recursive: true });
+    writeFileSync(join(brain, 'fleet', 'roster.yaml'), ROSTER, { mode: 0o600 });
+    mkdirSync(join(configHome, 'fleet'), { recursive: true });
+    symlinkSync(join(brain, 'fleet', 'roster.yaml'), join(configHome, 'fleet', 'roster.yaml'));
+    mkdirSync(join(configHome, 'tools', 'tmux'), { recursive: true });
+    writeFileSync(join(configHome, 'tools', 'tmux', 'agent-send.sh'), '#!/bin/sh\n', {
+      mode: 0o755,
+    });
+    process.env['MOSAIC_BRAIN_HOME'] = brain;
+  });
+
+  afterEach(() => {
+    delete process.env['MOSAIC_BRAIN_HOME'];
+    vi.unstubAllEnvs();
+    rmSync(join(brain, '..'), { recursive: true, force: true });
+  });
+
+  it('resolves a member through the roster symlink under the config home', () => {
+    const result = resolveFleetIdentity(configHome, 'orchestrator', 'w-jarvis');
+    expect(result.ok).toBe(true);
+    expect(result.identity?.member.name).toBe('orchestrator');
+    expect(result.identity?.agentSendPath).toBe(join(configHome, 'tools', 'tmux', 'agent-send.sh'));
+  });
+
+  it('resolves a member when mosaicHome is the brain (helper found under the framework home)', () => {
+    const result = resolveFleetIdentity(brain, 'enhancer', 'w-jarvis');
+    expect(result.ok).toBe(true);
+    expect(result.identity?.member.name).toBe('enhancer');
+    expect(result.identity?.agentSendPath).toBe(join(configHome, 'tools', 'tmux', 'agent-send.sh'));
+  });
+
+  it('no-name control stays a quiet no-op', () => {
+    expect(resolveFleetIdentity(configHome, undefined, 'w-jarvis')).toEqual({ ok: true });
+    expect(resolveFleetIdentity(brain, undefined, 'w-jarvis')).toEqual({ ok: true });
+  });
+
+  it('a nonce name fails naming membership, not the symlink or the helper', () => {
+    const result = resolveFleetIdentity(configHome, 'nonce-' + Date.now(), 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.error).not.toContain('symbolic link');
+    expect(result.error).not.toContain('helper');
+    expect(result.error).toContain('nonce-');
+  });
+
+  it('a non-member failure names membership, not the symlink (protocol control)', () => {
+    const result = resolveFleetIdentity(configHome, 'jarvis', 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.error).not.toContain('symbolic link');
+    expect(result.error).not.toContain('helper is unavailable');
+    expect(result.error).toContain('orchestrator'); // known-member listing
+  });
+
+  it('names every searched framework home when the helper is missing everywhere', () => {
+    rmSync(join(configHome, 'tools'), { recursive: true, force: true });
+    const result = resolveFleetIdentity(brain, 'orchestrator', 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('agent-send.sh');
+    expect(result.error).toContain(join(brain, 'tools', 'tmux', 'agent-send.sh'));
+    expect(result.error).not.toContain('--repair-tools');
+  });
+
+  it('readFleetCommsBlock composes the full contract on the split-home layout', () => {
+    const result = readFleetCommsBlock(configHome, 'orchestrator', 'w-jarvis');
+    expect(result.ok).toBe(true);
+    expect(result.output).toContain(
+      'Helper: `' + join(configHome, 'tools', 'tmux', 'agent-send.sh'),
+    );
+  });
+});
@@ -9,8 +9,9 @@
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { homedir, hostname } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { readRegularFileSecure } from './secure-file.js';
+import { resolveBrainHome } from './brain-home.js';
 import {
  parseFleetRosterV1,
  resolveInstalledFleetRosterPath,
@@ -260,7 +261,13 @@ context and have an authorized operator relaunch only this exact roster member w

 function validateAgentSendHelper(path: string, mosaicHome: string): string | undefined {
  try {
-    readRegularFileSecure(path, { root: mosaicHome, executable: true });
+    readRegularFileSecure(path, {
+      root: mosaicHome,
+      executable: true,
+      // The helper tree may live under the framework config home while this
+      // caller's mosaicHome is the brain; both are framework-owned roots.
+      symlinkTargetRoots: [resolveBrainHome(mosaicHome)],
+    });
    return undefined;
  } catch (error) {
    const reason = error instanceof Error ? error.message : String(error);
@@ -268,8 +275,48 @@ function validateAgentSendHelper(path: string, mosaicHome: string): string | und
  }
 }

+/**
+ * Framework install homes probed for tools/tmux/agent-send.sh (stack#1380 M2).
+ * The helper ships with the FRAMEWORK install, which on split-home layouts is
+ * the config home — not the brain (~/.mosaic carries fleet state, no tools).
+ */
+function frameworkHelperHomes(mosaicHome: string): string[] {
+  const homes = [resolve(mosaicHome)];
+  const envHome = process.env['MOSAIC_HOME'];
+  if (envHome && envHome.trim() !== '' && resolve(envHome) !== resolve(mosaicHome)) {
+    homes.push(resolve(envHome));
+  }
+  const configDefault = join(homedir(), '.config', 'mosaic');
+  if (resolve(configDefault) !== resolve(mosaicHome)) homes.push(configDefault);
+  return homes;
+}
+
+function resolveAgentSendHelper(mosaicHome: string): { path: string; error?: string } {
+  const homes = frameworkHelperHomes(mosaicHome);
+  for (const home of homes) {
+    const helper = join(home, 'tools', 'tmux', 'agent-send.sh');
+    if (!existsSync(helper)) continue;
+    const error = validateAgentSendHelper(helper, home);
+    if (!error) return { path: helper };
+    // Present but unsafe: surface that verdict instead of silently probing on.
+    return { path: helper, error };
+  }
+  return {
+    path: join(resolve(mosaicHome), 'tools', 'tmux', 'agent-send.sh'),
+    error:
+      `fleet helper agent-send.sh was not found under any framework install home ` +
+      `(${homes.map((h) => join(h, 'tools', 'tmux', 'agent-send.sh')).join('; ')}). ` +
+      `Verify the framework install for this host (the helper ships with the framework ` +
+      `config home; the brain home carries fleet state, not tools) and have an authorized ` +
+      `operator restore it if missing.`,
+  };
+}
+
 function helperFailureGuidance(reason: string): string {
-  return `${reason}. Run \`mosaic update --repair-tools\` to restore the supported current-version helper and TOOLS contract, then retry exact-member composition; no active context or session was rewritten.`;
+  // stack#1380 M5a: `mosaic update --repair-tools` is a forbidden remedy on the
+  // affected estate (and wrong for a layout/missing-helper failure). Name the
+  // actual recovery shape instead.
+  return `${reason}. Verify the framework install provides tools/tmux/agent-send.sh under the framework config home and that the roster resolves (split-home layouts symlink the roster into the brain); contact the operator if it persists; no active context or session was rewritten.`;
 }

 export function resolveFleetIdentity(
@@ -278,9 +325,15 @@ export function resolveFleetIdentity(
  localHost: string = shortHostname(),
 ): FleetIdentityResult {
  if (!requestedName) return { ok: true };
-  const agentSendPath = join(mosaicHome, 'tools', 'tmux', 'agent-send.sh');
-  const helperError = validateAgentSendHelper(agentSendPath, mosaicHome);
-  if (helperError) return { ok: false, error: helperFailureGuidance(helperError) };
+  const helper = resolveAgentSendHelper(mosaicHome);
+  if (helper.error) return { ok: false, error: helperFailureGuidance(helper.error) };
+  const agentSendPath = helper.path;
+
+  // Split-home layouts unify the roster by symlinking
+  // <configHome>/fleet/roster.yaml -> <brain>/fleet/roster.yaml. The secure
+  // read resolves that framework-created symlink when the brain is a
+  // sanctioned target root (stack#1380 M1).
+  const rosterSymlinkRoots = [resolveBrainHome(mosaicHome)];

  let rosterPath: string;
  try {
@@ -301,7 +354,10 @@ export function resolveFleetIdentity(
  let roster: FleetRoster;
  try {
    roster = parseFleetRosterV1(
-      readRegularFileSecure(rosterPath, { root: mosaicHome }).content.toString('utf8'),
+      readRegularFileSecure(rosterPath, {
+        root: mosaicHome,
+        symlinkTargetRoots: rosterSymlinkRoots,
+      }).content.toString('utf8'),
      rosterPath.endsWith('.json') ? 'json' : 'yaml',
    );
  } catch (error) {
@@ -399,7 +455,9 @@ function boundedContractDigest(
 }

 function replacementGuidance(): string {
-  return `Run \`mosaic update --repair-tools\` to make a digest-qualified backup and restore the supported current-version TOOLS contract, then have an authorized operator explicitly relaunch the exact roster member. The active context was not rewritten.`;
+  // stack#1380 M5a: never recommend the forbidden --repair-tools remedy from
+  // error text; name the operator-verified recovery shape instead.
+  return `Verify the installed TOOLS contract against the framework source with an authorized operator (the installed file must byte-match the supported current version) and have the operator explicitly relaunch the exact roster member. The active context was not rewritten.`;
 }

 /** Detect preserved installed TOOLS.md drift without changing it. */
@@ -7,6 +7,7 @@ import { canonicalizeRoleClass } from '../commands/fleet-personas.js';
 interface RawFleetRoster {
  version?: unknown;
  transport?: unknown;
+  generation?: unknown;
  tmux?: {
    socket_name?: unknown;
    socketName?: unknown;
@@ -41,6 +42,10 @@ interface RawFleetRoster {
    resetBetweenTasks?: unknown;
    kickstart_template?: unknown;
    kickstartTemplate?: unknown;
+    model?: unknown;
+    reasoning?: unknown;
+    lifecycle?: { enabled?: unknown; desired_state?: unknown };
+    launch?: { yolo?: unknown };
  }>;
  connector?: {
    kind?: unknown;
@@ -216,7 +221,17 @@ function normalizeFleetRosterV1Unchecked(raw: RawFleetRoster): FleetRoster {
    'runtimes',
    'agents',
    'connector',
+    // stack#1380 verification unblock: the fleet's own roster-v2 mutation
+    // tooling writes a `generation` fence on the same v1 body. Tolerated here
+    // as an opaque non-negative integer; comms semantics are unchanged.
+    'generation',
  ]);
+  if (
+    raw.generation !== undefined &&
+    (typeof raw.generation !== 'number' || !Number.isInteger(raw.generation) || raw.generation < 0)
+  ) {
+    throw new Error('Fleet roster generation must be a non-negative integer.');
+  }
  if (raw.tmux !== undefined) {
    assertObject(raw.tmux, 'Fleet roster tmux');
    assertKnownKeys(raw.tmux, 'Fleet roster tmux', [
@@ -231,6 +246,8 @@ function normalizeFleetRosterV1Unchecked(raw: RawFleetRoster): FleetRoster {
    assertKnownKeys(raw.defaults, 'Fleet roster defaults', [
      'working_directory',
      'workingDirectory',
+      // stack#1380 verification unblock: roster-v2 default runtime hint.
+      'runtime',
    ]);
  }
  if (raw.runtimes !== undefined) {
@@ -243,7 +260,9 @@ function normalizeFleetRosterV1Unchecked(raw: RawFleetRoster): FleetRoster {
      ]);
    }
  }
-  if (raw.version !== 1) throw new Error('Fleet roster version must be 1.');
+  if (raw.version !== 1 && raw.version !== 2) {
+    throw new Error('Fleet roster version must be 1 or 2.');
+  }
  if (raw.transport !== 'tmux') throw new Error('Fleet roster transport must be "tmux".');
  if (!Array.isArray(raw.agents) || raw.agents.length === 0) {
    throw new Error('Fleet roster must define at least one agent.');
@@ -318,7 +337,52 @@ function normalizeAgent(raw: NonNullable<RawFleetRoster['agents']>[number]): Fle
    'resetBetweenTasks',
    'kickstart_template',
    'kickstartTemplate',
+    // stack#1380 verification unblock: roster-v2 envelope fields written by
+    // the fleet's own mutation tooling. Validated, then opaque to comms.
+    'model',
+    'reasoning',
+    'lifecycle',
+    'launch',
  ]);
+  if (raw.model !== undefined && typeof raw.model !== 'string') {
+    throw new Error('Fleet roster agent model must be a string.');
+  }
+  if (raw.reasoning !== undefined && typeof raw.reasoning !== 'string') {
+    throw new Error('Fleet roster agent reasoning must be a string.');
+  }
+  const lifecycle = raw.lifecycle as { enabled?: unknown; desired_state?: unknown } | undefined;
+  if (lifecycle !== undefined) {
+    if (typeof lifecycle !== 'object' || lifecycle === null) {
+      throw new Error('Fleet roster agent lifecycle must be an object.');
+    }
+    const lifecycleKeys = Object.keys(lifecycle);
+    if (!lifecycleKeys.every((key) => key === 'enabled' || key === 'desired_state')) {
+      throw new Error('Fleet roster agent lifecycle has unknown field(s).');
+    }
+    if (lifecycle.enabled !== undefined && typeof lifecycle.enabled !== 'boolean') {
+      throw new Error('Fleet roster agent lifecycle.enabled must be a boolean.');
+    }
+    if (
+      lifecycle.desired_state !== undefined &&
+      (typeof lifecycle.desired_state !== 'string' ||
+        !['running', 'stopped'].includes(lifecycle.desired_state))
+    ) {
+      throw new Error('Fleet roster agent lifecycle.desired_state must be running|stopped.');
+    }
+  }
+  const launch = raw.launch as { yolo?: unknown } | undefined;
+  if (launch !== undefined) {
+    if (typeof launch !== 'object' || launch === null) {
+      throw new Error('Fleet roster agent launch must be an object.');
+    }
+    const launchKeys = Object.keys(launch);
+    if (!launchKeys.every((key) => key === 'yolo')) {
+      throw new Error('Fleet roster agent launch has unknown field(s).');
+    }
+    if (launch.yolo !== undefined && typeof launch.yolo !== 'boolean') {
+      throw new Error('Fleet roster agent launch.yolo must be a boolean.');
+    }
+  }
  const name = stringValue(raw.name, '', 'Fleet roster agent name');
  const runtime = stringValue(
    raw.runtime,
@@ -10,12 +10,14 @@ import {
  type PathLike,
 } from 'node:fs';
 import type * as NodeFs from 'node:fs';
+import type { Stats } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';

 interface FilesystemRaceState {
  afterLstat?: (path: string) => void;
  afterOpen?: (path: string) => void;
+  afterStat?: (path: string, stats: Stats) => Stats;
 }

 const filesystemRaceState = vi.hoisted<FilesystemRaceState>(() => ({}));
@@ -29,6 +31,10 @@ vi.mock('node:fs', async (importOriginal) => {
      filesystemRaceState.afterLstat?.(String(path));
      return result;
    },
+    statSync: (path: PathLike) => {
+      const result = actual.statSync(path);
+      return filesystemRaceState.afterStat?.(String(path), result) ?? result;
+    },
    openSync: (path: PathLike, flags: string | number, mode?: number) => {
      const fd = actual.openSync(path, flags, mode);
      filesystemRaceState.afterOpen?.(String(path));
@@ -46,11 +52,13 @@ describe('secure file reads', () => {
    root = mkdtempSync(join(tmpdir(), 'mosaic-secure-file-'));
    filesystemRaceState.afterLstat = undefined;
    filesystemRaceState.afterOpen = undefined;
+    filesystemRaceState.afterStat = undefined;
  });

  afterEach(() => {
    filesystemRaceState.afterLstat = undefined;
    filesystemRaceState.afterOpen = undefined;
+    filesystemRaceState.afterStat = undefined;
    rmSync(root, { recursive: true, force: true });
  });

@@ -60,27 +68,89 @@ describe('secure file reads', () => {
    );
  });

-  it('rejects a symlink in a file ancestor', () => {
+  // stack#1380: the guard resolves symlinks and validates the resolved target
+  // instead of refusing any symlink component.
+  it('permits a symlink ancestor whose resolved target is inside the root', () => {
    const external = join(root, 'external');
    mkdirSync(external);
    writeFileSync(join(external, 'file'), 'external\n');
    symlinkSync(external, join(root, 'linked'));

-    expect(() => readRegularFileSecure(join(root, 'linked', 'file'), { root })).toThrow(
-      'path ancestor is a symbolic link',
-    );
+    const snapshot = readRegularFileSecure(join(root, 'linked', 'file'), { root });
+    expect(snapshot.content.toString('utf8')).toBe('external\n');
  });

-  it('rejects a symlink target', () => {
-    const external = join(root, 'external');
+  it('permits a symlinked file whose resolved target is inside the root', () => {
+    const external = join(root, 'external-file');
    writeFileSync(external, 'external\n');
    symlinkSync(external, join(root, 'linked-file'));

-    expect(() => readRegularFileSecure(join(root, 'linked-file'), { root })).toThrow(
-      'file is a symbolic link',
+    const snapshot = readRegularFileSecure(join(root, 'linked-file'), { root });
+    expect(snapshot.content.toString('utf8')).toBe('external\n');
+  });
+
+  it('permits a symlink resolving into an additional sanctioned root (split-home roster shape)', () => {
+    const brain = `${root}-brain`;
+    mkdirSync(join(brain, 'fleet'), { recursive: true });
+    writeFileSync(join(brain, 'fleet', 'roster.yaml'), 'roster\n', { mode: 0o600 });
+    mkdirSync(join(root, 'fleet'));
+    symlinkSync(join(brain, 'fleet', 'roster.yaml'), join(root, 'fleet', 'roster.yaml'));
+
+    const snapshot = readRegularFileSecure(join(root, 'fleet', 'roster.yaml'), {
+      root,
+      symlinkTargetRoots: [brain],
+    });
+    expect(snapshot.content.toString('utf8')).toBe('roster\n');
+  });
+
+  it('refuses a symlink whose resolved target escapes every sanctioned root', () => {
+    const outside = mkdtempSync(join(tmpdir(), 'mosaic-secure-outside-'));
+    try {
+      mkdirSync(join(root, 'fleet'), { recursive: true });
+      writeFileSync(join(outside, 'roster.yaml'), 'escaped\n', { mode: 0o600 });
+      symlinkSync(join(outside, 'roster.yaml'), join(root, 'fleet', 'roster.yaml'));
+
+      expect(() => readRegularFileSecure(join(root, 'fleet', 'roster.yaml'), { root })).toThrow(
+        /symlink target escapes managed roots/,
+      );
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses a group-writable symlink target', () => {
+    const loose = join(root, 'loose');
+    mkdirSync(loose);
+    chmodSync(loose, 0o770); // group-writable bit survives umask via explicit chmod
+    writeFileSync(join(loose, 'file'), 'loose\n');
+    symlinkSync(loose, join(root, 'linked-loose'));
+
+    expect(() => readRegularFileSecure(join(root, 'linked-loose', 'file'), { root })).toThrow(
+      /group- or world-writable/,
    );
  });

+  it('refuses a symlink target owned by another user', () => {
+    const external = join(root, 'foreign');
+    mkdirSync(external);
+    writeFileSync(join(external, 'file'), 'foreign\n');
+    symlinkSync(external, join(root, 'linked-foreign'));
+
+    filesystemRaceState.afterStat = (path, stats): Stats => {
+      if (resolve(path) === resolve(external)) {
+        return { ...stats, uid: stats.uid + 4242 } as Stats;
+      }
+      return stats;
+    };
+    try {
+      expect(() => readRegularFileSecure(join(root, 'linked-foreign', 'file'), { root })).toThrow(
+        /not owned by the current user/,
+      );
+    } finally {
+      filesystemRaceState.afterStat = undefined;
+    }
+  });
+
  it('keeps ancestor traversal bound when an opened directory is substituted', () => {
    const tools = join(root, 'tools');
    const displacedTools = join(root, 'tools.displaced');
@@ -7,14 +7,25 @@ import {
  mkdirSync,
  openSync,
  readFileSync,
+  readlinkSync,
+  statSync,
 } from 'node:fs';
 import { platform } from 'node:os';
-import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';

 export interface SecureFileReadOptions {
  root: string;
  maxBytes?: number;
  executable?: boolean;
+  /**
+   * Additional roots a symlink component may resolve into (stack#1380).
+   * Default: only the managed root itself. Every symlink hop is validated —
+   * containment under the root or one of these roots, current-user ownership,
+   * no group/world-writable mode — and refusal stays the default for anything
+   * else. Callers that operate the split-home layout pass the brain home so
+   * the framework-created roster symlink resolves.
+   */
+  symlinkTargetRoots?: string[];
 }

 export interface SecureFileSnapshot {
@@ -88,7 +99,57 @@ function openDirectoryChain(absoluteDirectory: string): { fd: number; descriptor
  }
 }

-function openFileBeneathRoot(root: string, target: string): { fd: number; descriptors: number[] } {
+function containedUnder(root: string, target: string): boolean {
+  const rel = relative(resolve(root), resolve(target));
+  return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel) && rel !== '';
+}
+
+const MAX_SYMLINK_HOPS = 40;
+
+/**
+ * Resolve every symlink on `lexical` component-wise, validating each hop
+ * (stack#1380 resolve-then-validate): the hop target must stay under one of
+ * the sanctioned roots, must be owned by the current user (or root), and must
+ * not be group- or world-writable. Returns a symlink-free absolute path.
+ */
+function resolveRealPath(lexical: string, sanctionedRoots: string[]): string {
+  const hopTargets: string[] = [];
+  let current: string = sep;
+  for (const piece of resolve(lexical).split(sep).filter(Boolean)) {
+    current = resolve(current, piece);
+    for (let hops = 0; lstatSync(current).isSymbolicLink(); ) {
+      if (++hops > MAX_SYMLINK_HOPS) {
+        throw new Error(`symlink chain exceeds ${MAX_SYMLINK_HOPS} hops: ${lexical}`);
+      }
+      const linkTarget = readlinkSync(current);
+      const absolute = resolve(dirname(current), linkTarget);
+      if (!sanctionedRoots.some((root) => containedUnder(root, absolute))) {
+        throw new Error(
+          `symlink target escapes managed roots [${sanctionedRoots.join(', ')}]: ${absolute}`,
+        );
+      }
+      hopTargets.push(absolute);
+      current = absolute;
+    }
+  }
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+  for (const hop of hopTargets) {
+    const stat = statSync(hop);
+    if (stat.uid !== uid && stat.uid !== 0) {
+      throw new Error(`symlink target is not owned by the current user: ${hop}`);
+    }
+    if (stat.mode & 0o022) {
+      throw new Error(`symlink target is group- or world-writable: ${hop}`);
+    }
+  }
+  return current;
+}
+
+function openFileBeneathRoot(
+  root: string,
+  target: string,
+  symlinkTargetRoots: string[] = [],
+): { fd: number; descriptors: number[] } {
  const canonicalRoot = resolve(root);
  const canonicalTarget = resolve(target);
  assertCanonicalContainment(canonicalRoot, canonicalTarget);
@@ -96,39 +157,52 @@ function openFileBeneathRoot(root: string, target: string): { fd: number; descri
  const fileName = components.pop();
  if (fileName === undefined) throw new Error('managed file path names the managed root');

-  const rootChain = openDirectoryChain(canonicalRoot);
+  // stack#1380: resolve-then-validate. The lexical path must name the managed
+  // root (above); symlink components are then resolved hop-by-hop under the
+  // sanctioned roots (validated per hop), and the descriptor traversal walks
+  // the symlink-free real path — keeping the O_NOFOLLOW chain as the race
+  // guard for anything substituted after resolution.
+  let realRoot: string;
+  try {
+    realRoot = resolveRealPath(canonicalRoot, [canonicalRoot]);
+  } catch (error) {
+    throw secureFilesystemError(
+      'secure descriptor traversal failed: symbolic link, unavailable, or not a directory',
+      error,
+    );
+  }
+  const sanctioned = [realRoot, ...symlinkTargetRoots.map((extra) => resolve(extra))];
+  let realTarget: string;
+  try {
+    realTarget = resolveRealPath(canonicalTarget, sanctioned);
+  } catch (error) {
+    if (error instanceof Error && !('code' in error)) throw error;
+    throw secureFilesystemError(
+      'secure descriptor traversal failed: symbolic link, unavailable, or not a directory',
+      error,
+    );
+  }
+  if (!sanctioned.some((sr) => containedUnder(sr, realTarget) || resolve(sr) === realTarget)) {
+    throw new Error(
+      `resolved path escapes managed roots [${sanctioned.join(', ')}]: ${realTarget}`,
+    );
+  }
+
+  const chain = openDirectoryChain(dirname(realTarget));
  try {
-    let parentFd = rootChain.fd;
-    for (const component of components) {
-      try {
-        parentFd = openSync(
-          procDescriptorPath(parentFd, component),
-          constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
-        );
-      } catch (error) {
-        throw secureFilesystemError(
-          'path ancestor is a symbolic link, unavailable, or not a directory',
-          error,
-        );
-      }
-      rootChain.descriptors.push(parentFd);
-      if (!fstatSync(parentFd).isDirectory()) {
-        throw new Error('path ancestor is a symbolic link or not a directory');
-      }
-    }
    let fd: number;
    try {
      fd = openSync(
-        procDescriptorPath(parentFd, fileName),
+        procDescriptorPath(chain.fd, basename(realTarget)),
        constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW,
      );
    } catch (error) {
      throw secureFilesystemError('file is a symbolic link or unavailable', error);
    }
-    rootChain.descriptors.push(fd);
-    return { fd, descriptors: rootChain.descriptors };
+    chain.descriptors.push(fd);
+    return { fd, descriptors: chain.descriptors };
  } catch (error) {
-    closeDescriptors(rootChain.descriptors);
+    closeDescriptors(chain.descriptors);
    if (error instanceof Error) throw error;
    throw new Error('secure managed file open failed');
  }
@@ -203,7 +277,7 @@ export function readRegularFileSecure(
  path: string,
  options: SecureFileReadOptions,
 ): SecureFileSnapshot {
-  const openedFile = openFileBeneathRoot(options.root, path);
+  const openedFile = openFileBeneathRoot(options.root, path, options.symlinkTargetRoots ?? []);
  try {
    const opened = fstatSync(openedFile.fd);
    if (!opened.isFile()) throw new Error('managed file is not a regular file');
@@ -168,7 +168,9 @@ describe('repairFleetCommsTools', () => {
    const result = repairFleetCommsTools(framework, home);

    expect(result).toMatchObject({ ok: false, changed: false });
-    expect(result.reason).toContain('symbolic link');
+    // stack#1380: resolve-then-validate — an escaping symlink is still
+    // refused, with the new escape diagnostic.
+    expect(result.reason).toContain('symlink target escapes managed roots');
    expect(readFileSync(target, 'utf8')).toBe('do not touch\n');
    expect(lstatSync(join(home, 'tools', 'tmux', 'agent-send.sh')).isSymbolicLink()).toBe(true);
  });
@@ -222,7 +224,10 @@ describe('repairFleetCommsTools', () => {
      const result = repairFleetCommsTools(framework, targetHome);

      expect(result, testCase.name).toMatchObject({ ok: false, changed: false });
-      expect(result.reason, testCase.name).toContain('symbolic link');
+      // stack#1380: escaping ancestor symlinks stay refused. The home case is
+      // caught by the managed-root guard ('is a symbolic link'); deeper
+      // components by resolve-then-validate ('symlink target escapes').
+      expect(result.reason, testCase.name).toMatch(/symbolic link|symlink target escapes/);
      expect(readdirSync(external), testCase.name).toEqual([]);
    }
  });
@@ -63,7 +63,6 @@ export const STAGES = [
      'bash packages/mosaic/framework/tools/git/test-issue-close-fail-closed.sh',
      'bash packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh',
      'bash packages/mosaic/framework/tools/git/test-issue-view-comments.sh',
-      'bash packages/mosaic/framework/tools/fleet/test-mint-seat-credential.sh',
      'bash packages/mosaic/framework/tools/git/test-wrapper-guard.sh',
      'bash packages/mosaic/framework/tools/git/test-mosaic-worktree-large-repo.sh',
    ],
Author	SHA1	Message	Date
code-be-01	8d27e0f78c	ci(publish): serialize workspace-consuming image builds after publish-next-npm (#1411 ) ci/woodpecker/pr/ci Pipeline was successful Details Pipeline 2648 failed build-gateway with ERR_PNPM_OUTDATED_LOCKFILE although publish-next-npm completed green and restored the workspace byte-exact ('git diff clean' in its own log). Root cause: build-gateway and publish-next-npm both depend on [build, verify] and run concurrently; kaniko's COPY of apps/gateway/package.json raced inside publish's in-place mutation window (transform .. publish .. restore). PR 1405's snapshot/restore governs the END state of its own step only — no mutual exclusion against a concurrent reader. The snapshot/restore set was already a superset of the transform's write set (both derive from apps/packages/plugins with the same exclusions — the tasking's apps-coverage hypothesis is refuted by the committed find). The defect is ordering, so the fix is a DAG edge: build-gateway, build-appservice, and build-web each gain publish-next-npm in depends_on, serializing every kaniko workspace consumer after the restore. publish-npm (main-only, transform is next-only) is unchanged. The invariant is stated inline at each edge: any new workspace-consuming step must depend on publish-next-npm. Red-first evidence (clean clone of next; scripts from the committed YAML; gateway manifest as the demonstration case): pre-fix DAG shows build-gateway deps == publish deps (concurrent); post-fix adds the edge. Reading apps/gateway/package.json mid-window shows 0.0.3-next.2648 pins (the 2648 dump shape) and pnpm install --frozen-lockfile fails ERR_PNPM_OUTDATED_LOCKFILE; the same read after restore shows workspace:^ and the identical clean tree installs rc=0. Closes #1411 (blocks PR 1401's merge — USC chain).	2026-08-24 19:40:24 -05:00
code-be-01	1a28212a89	fix(ci): restore workspace manifests after publish pin transform (#1404 ) ci/woodpecker/pr/ci Pipeline was successful Details PR #1400's transform rewrites package.json files in the shared pipeline workspace (pnpm publish reads the workspace manifests, so in-place is required) but did not restore them. build-gateway's kaniko build then COPYs the mutated manifests and its pnpm install --frozen-lockfile refuses: pnpm-lock.yaml still records workspace:^ while the manifest says 0.0.x-next.NNNN — ERR_PNPM_OUTDATED_LOCKFILE, next tip red (pipeline 2646). Fix (restore, chosen over tarball-scoped pack because pnpm publish must read the workspace tree anyway — a temp-copy pack would need to reconstruct the workspace linkage per package; restore is one cp per manifest and byte-exact): snapshot every publishable manifest to a step-local mktemp dir BEFORE the transform; after publish + the #1389 guard, restore byte-exact (cp -p preserves mtime), then a pristine guard runs git diff --exit-code over '**/package.json' and fails THIS step if any residual mutation remains — the #1404 class now fails in publish-next-npm with a named cause instead of surfacing as a frozen- lockfile error in build-gateway. Red-first control (scratch clone of next, real scripts extracted from the committed YAML): transform without restore -> git diff dirty (guard red) AND pnpm install --frozen-lockfile reproduces ERR_PNPM_OUTDATED_LOCKFILE verbatim (the 2646 failure class); with snapshot+restore -> git diff clean, frozen install rc=0. Also fixed a trailing space after the NODE heredoc opener introduced with #1400's edit that would have broken the heredoc invocation in real CI.	2026-08-24 18:38:52 -05:00
ops-deploy-01andorch-01	4d24ae8618	fix(#1392 ): hash-ledger migrations + install-time schema verification (closes #1392 , closes #1402 ) (#1403 ) ci/woodpecker/push/publish Pipeline failed Details Co-authored-by: ops-deploy-01 <[email protected]>	2026-08-24 23:11:50 +00:00
code-be-01andorch-01	d790572e2e	ci(publish): pin next-channel @mosaicstack deps to exact same-pipeline builds (#1389 ) (#1400 ) ci/woodpecker/push/publish Pipeline was canceled Details Co-authored-by: code-be-01 <[email protected]>	2026-08-24 23:05:37 +00:00
code-be-01andorch-01	d7b1dd9601	test(git-tools): wrapper-guard harness distinguishes tool failure from drift (#1380-FF) (#1388 ) ci/woodpecker/push/publish Pipeline was successful Details Co-authored-by: code-be-01 <[email protected]>	2026-08-24 21:43:09 +00:00
code-be-01andorch-01	0db2d19a22	feat(framework): mosaic doctor structure-anchor provisioning check (T51 WP0b) (#1379 ) ci/woodpecker/push/publish Pipeline was successful Details Co-authored-by: code-be-01 <[email protected]>	2026-08-24 20:15:08 +00:00
code-be-01andorch-01	8eb7e6354e	fix(fleet): resolve-then-validate symlink guard + framework helper resolution (#1380 ) (#1383 ) ci/woodpecker/push/publish Pipeline failed Details Co-authored-by: code-be-01 <[email protected]>	2026-08-24 19:39:13 +00:00
code-be-01andorch-01	9014a510a9	ci(mosaic): repo-structure declaration CI gate (T51 WP5c) (#1378 ) ci/woodpecker/push/publish Pipeline was successful Details Co-authored-by: code-be-01 <[email protected]>	2026-08-24 04:43:26 +00:00
code-be-01andorch-01	974e4740ab	docs(mosaic): declare repo structure v2 (T51 WP2a) (#1377 ) ci/woodpecker/push/publish Pipeline was successful Details Co-authored-by: code-be-01 <[email protected]>	2026-08-24 03:49:33 +00:00
orch-01	9cd6d39b71	fix(git-tools): pr-create API fallback resolves base from forge default branch (E4) (#1376 ) ci/woodpecker/push/publish Pipeline was successful Details	2026-08-24 02:49:38 +00:00
code-be-01andorch-01	143f925fd8	fix(git-tools): admin-gated --no-ci-expected merge assertion for CI-less repositories (#1373 ) ci/woodpecker/push/publish Pipeline was successful Details Co-authored-by: code-be-01 <[email protected]>	2026-08-23 18:54:49 +00:00