ci(publish): pin next-channel @mosaicstack deps to exact same-pipeline builds (#1389)

The next publish step bumped each package's own version but left
@mosaicstack/* dependency ranges as published caret ranges
(^0.0.3-next.2636). A caret range leaves the resolver free to pick any
later build in the tuple — and on a host with a stale cache, an
installer-side scaffold pinned at stable, or a registry proxy hiccup,
that freedom is how a gateway@next install ends up executing stable-era
dependency code (web1 evidence in #1389: old tier validator, missing
migrations, stable versions in the dependency tree despite matching
-next builds existing).

Pipeline fix (not a per-package symptom patch): pass 2 of the publish
script rewrites every published manifest's @mosaicstack/* entries
(dependencies, devDependencies, peerDependencies, optionalDependencies)
to the EXACT same-pipeline build recorded in pass 1 — exact pins make
the stable-fallback class unrepresentable regardless of resolver path.
A dep outside the publish set fails the publish loudly (cannot pin).

New post-publish guard (same step, after the existing version check):
npm-views every freshly published manifest and fails the pipeline when
any @mosaicstack/* entry is not an exact -next.<pipeline> pin —
stable-range leaks and cross-pipeline pins both red.

Hermetic evidence (scripts extracted from the YAML, mock registry):
bump+pin rewrites a 3-package sandbox to exact next.9999 pins;
guard green on exact pins; red on ^0.0.3 stable range; red on
0.0.4-next.8888 cross-pipeline pin. No registry access needed to
re-verify (mock-npm pattern).

.mosaic/repo.json

@@ -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."
 }

.woodpecker/ci.yml

@@ -91,6 +91,15 @@ steps:
       # and sandboxes a throwaway git repo, so it resolves no real credentials and
       # joins CI directly rather than the exclusions file.
       - bash packages/mosaic/framework/tools/git/test-issue-close-fail-closed.sh
+      # Hermetic regression for the git identity ladder (#1356): mock tea on PATH,
+      # sandboxed repo, no real credentials (3/3 green under an empty HOME). Pins
+      # fail-closed: a seat whose login is missing gets a named error, never a
+      # borrowed identity. Joins CI directly; its #1007 exclusion is burned down.
+      - bash packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh
+      # Hermetic regression for issue-view.sh (#1357): mock tea/curl, sandboxed
+      # 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 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 —
@@ -104,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

.woodpecker/publish.yml

@@ -209,23 +209,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 +249,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 +292,71 @@ 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
     depends_on:
       - build
       - verify

packages/mosaic/framework/guides/TOOLS-REFERENCE.md

@@ -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

packages/mosaic/framework/tools/_scripts/mosaic-doctor

@@ -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.

packages/mosaic/framework/tools/_scripts/test-structure-anchor-check.sh

@@ -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"

packages/mosaic/framework/tools/fleet/seat-logins.sh

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+# seat-logins.sh — project seat credentials into tea's login config.
+#
+# Issue: mosaicstack/stack#1356 (tea login resolution fails open).
+#
+# WHY THIS EXISTS. tea 0.14.0 has no --token on its operations; it can only use a
+# login already stored in ~/.config/tea/config.yml. So the wrappers cannot read the
+# seat secrets dir on the tea path. The secrets dir stays authoritative and this
+# script projects it into tea's config, which is a DERIVED CACHE: regenerate it,
+# never hand-edit it. Same shape as the config-registry projector, same reason —
+# a third-party tool that cannot read our store has to be fed.
+#
+# Canonical login name is "<instance>-<seat>", which is what the identity ladder in
+# detect-platform.sh computes from the seat name. A login the ladder cannot compute
+# is a fail-open surface, so an ad-hoc name is a defect, not a style.
+#
+# COLLISIONS. tea refuses to store one token under two names ("token already been
+# used, delete login 'X' first"). A hand-made alias holding a seat's token there-
+# fore BLOCKS its canonical name. Detected up front by hashing, so a dry run shows
+# it; --adopt resolves it by deleting the alias and re-minting canonically. Same
+# token, same access, only the label changes.
+#
+# Tokens are never printed, never logged, and never passed on a visible command
+# line beyond tea's own --token, which is unavoidable with this client. tea's
+# stderr is echoed on failure with any token-shaped string redacted.
+#
+# Usage:
+#   seat-logins.sh                 # dry run, all seats  (default: changes nothing)
+#   seat-logins.sh --apply         # mint/refresh all seats
+#   seat-logins.sh --seat <seat>   # limit to one seat
+#   seat-logins.sh --apply --adopt # also rename ad-hoc aliases to canonical names
+set -euo pipefail
+
+BRAIN_HOME="${MOSAIC_BRAIN_HOME:-$HOME/.mosaic}"
+TEA_CONFIG="${TEA_CONFIG:-$HOME/.config/tea/config.yml}"
+APPLY=0
+ADOPT=0
+ONLY_SEAT=""
+
+# Instance -> server URL.
+#
+# Instances are named here because there is no registry to read them from yet.
+# Override per-instance without editing this file, which is how a deployment adds
+# its own hosts:  MOSAIC_GITEA_URL_<INSTANCE>=https://...
+declare -A INSTANCE_URL=(
+  [mosaicstack]="https://git.mosaicstack.dev"
+  [usc]="https://git.uscllc.com"
+)
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --apply) APPLY=1; shift ;;
+    --adopt) ADOPT=1; shift ;;
+    --seat)  ONLY_SEAT="${2:?--seat needs a name}"; shift 2 ;;
+    -h|--help) sed -n '2,33p' "$0"; exit 0 ;;
+    *) echo "seat-logins.sh: unknown argument '$1'" >&2; exit 2 ;;
+  esac
+done
+
+command -v tea >/dev/null || { echo "seat-logins.sh: tea not on PATH" >&2; exit 1; }
+
+url_for() {
+  local inst="$1" ovr
+  ovr="MOSAIC_GITEA_URL_$(printf '%s' "$inst" | tr '[:lower:]-' '[:upper:]_')"
+  if [ -n "${!ovr:-}" ]; then printf '%s' "${!ovr}"; return 0; fi
+  printf '%s' "${INSTANCE_URL[$inst]:-}"
+}
+
+# Redact anything token-shaped before any tea output reaches a log.
+redact() { sed -E 's/[A-Za-z0-9]{30,}/<REDACTED>/g'; }
+
+# token sha256 -> login name, for every login tea already holds. This is what
+# makes collisions visible in a DRY RUN instead of only as an apply-time error.
+declare -A TOKEN_OWNER=()
+if [ -r "$TEA_CONFIG" ]; then
+  while read -r sha lname; do
+    [ -n "${sha:-}" ] && TOKEN_OWNER["$sha"]="$lname"
+  done < <(python3 - "$TEA_CONFIG" <<'PY'
+import sys, yaml, hashlib
+try:
+    cfg = yaml.safe_load(open(sys.argv[1])) or {}
+except Exception:
+    sys.exit(0)
+for l in (cfg.get('logins') or []):
+    t = l.get('token')
+    if t:
+        print(hashlib.sha256(t.encode()).hexdigest(), l.get('name'))
+PY
+  )
+fi
+
+minted=0; refreshed=0; skipped=0; failed=0; planned=0; adopted=0; blocked=0
+
+existing="$(tea login list --output simple 2>/dev/null | awk '{print $1}' || true)"
+
+shopt -s nullglob
+for tokfile in "$BRAIN_HOME"/fleet/agents/*/secrets/gitea-*.token; do
+  seat="${tokfile#"$BRAIN_HOME"/fleet/agents/}"; seat="${seat%%/*}"
+  [ -n "$ONLY_SEAT" ] && [ "$seat" != "$ONLY_SEAT" ] && continue
+
+  base="$(basename "$tokfile" .token)"          # gitea-<instance>-<seat>
+  inst="${base#gitea-}"; inst="${inst%-"$seat"}"
+  name="${inst}-${seat}"
+  url="$(url_for "$inst")"
+
+  if [ -z "$url" ]; then
+    echo "  SKIP  $name — no URL known for instance '$inst' (set MOSAIC_GITEA_URL_${inst^^})"
+    skipped=$((skipped+1)); continue
+  fi
+  if [ ! -r "$tokfile" ]; then
+    echo "  SKIP  $name — token not readable"
+    skipped=$((skipped+1)); continue
+  fi
+
+  action="mint"
+  grep -qx "$name" <<<"$existing" && action="refresh"
+
+  # Is this exact token already stored under some OTHER name?
+  tsha="$(sha256sum < "$tokfile" | awk '{print $1}')"
+  owner="${TOKEN_OWNER[$tsha]:-}"
+  collision=""
+  [ -n "$owner" ] && [ "$owner" != "$name" ] && collision="$owner"
+
+  if [ "$APPLY" -eq 0 ]; then
+    if [ -n "$collision" ]; then
+      if [ "$ADOPT" -eq 1 ]; then
+        echo "  PLAN  adopt  $collision -> $name  ($url)"
+      else
+        echo "  BLOCK $name — token already stored as '$collision'; re-run with --adopt"
+        blocked=$((blocked+1)); continue
+      fi
+    else
+      echo "  PLAN  $action $name -> $url"
+    fi
+    planned=$((planned+1)); continue
+  fi
+
+  if [ -n "$collision" ]; then
+    if [ "$ADOPT" -eq 0 ]; then
+      echo "  BLOCK $name — token already stored as '$collision'; re-run with --adopt"
+      blocked=$((blocked+1)); continue
+    fi
+    tea login delete "$collision" >/dev/null 2>&1 || true
+    action="adopt"
+  fi
+
+  # tea has no idempotent add; refresh is delete-then-add so a rotated token lands.
+  [ "$action" = refresh ] && tea login delete "$name" >/dev/null 2>&1 || true
+
+  if err="$(tea login add --name "$name" --url "$url" \
+              --token "$(cat "$tokfile")" --no-version-check 2>&1 >/dev/null)"; then
+    case "$action" in
+      mint)    minted=$((minted+1)) ;;
+      refresh) refreshed=$((refreshed+1)) ;;
+      adopt)   adopted=$((adopted+1)) ;;
+    esac
+    if [ "$action" = adopt ]; then
+      echo "  OK    adopt  $collision -> $name  ($url)"
+    else
+      echo "  OK    $action $name -> $url"
+    fi
+  else
+    # A failure here is real information: the seat's token is dead, or the server
+    # refused it. Do not paper over it; the seat cannot act until it is reminted.
+    # tea's own words, redacted — a summarised FAIL hides whether the cause is the
+    # credential or the client, which cost a diagnosis on 2026-08-21.
+    echo "  FAIL  $action $name -> $url"
+    echo "        tea: $(printf '%s' "$err" | redact | head -1)"
+    failed=$((failed+1))
+  fi
+done
+
+echo
+if [ "$APPLY" -eq 0 ]; then
+  echo "dry run: $planned login(s) would be written, $skipped skipped, $blocked blocked."
+  [ "$blocked" -gt 0 ] && echo "re-run with --adopt to rename ad-hoc aliases to canonical names."
+  echo "no changes made. re-run with --apply."
+else
+  echo "minted=$minted adopted=$adopted refreshed=$refreshed skipped=$skipped blocked=$blocked failed=$failed"
+fi
+[ "$failed" -eq 0 ] && [ "$blocked" -eq 0 ]

packages/mosaic/framework/tools/git/README.md

@@ -102,6 +102,36 @@ of their own — `MOSAIC_GIT_IDENTITY=<id>` with a provisioned slot. There is de
 environment variable that restores the fallback; one would reintroduce exactly the
 substitution this removes.
 
+### The tea path: login resolution (#1356)
+
+The wrappers that go through `tea` (`issue-list.sh`, `pr-list.sh`, `pr-view.sh`,
+`lane-brief.sh`, and the tea half of `issue-close.sh`) cannot use a token directly: tea
+0.14 only acts as a **login** already stored in `~/.config/tea/config.yml`. Those wrappers
+therefore resolve a login name, not a token, and the resolution follows the same identity
+as above:
+
+1. Resolve the identity (`MOSAIC_GIT_IDENTITY`, then `git config mosaic.gitIdentity`).
+2. Derive the Gitea instance from the repo host (`git.mosaicstack.dev` → `mosaicstack`,
+   `git.uscllc.com` → `usc`), or from the owner when `--repo owner/name` is given.
+3. The canonical login is `<instance>-<identity>`. If tea has it, that login acts.
+4. If the identity is set but that login is missing, the wrapper **fails closed**: nonzero
+   exit, empty stdout, and a stderr line naming the login it wanted and the source of the
+   identity. When `tea` itself is not installed the message says so instead, since "no such
+   login" would send the reader to create a login they cannot create.
+5. With **no identity set**, the old host-default behaviour is unchanged (first login
+   configured for that host, else the API fallback).
+
+Step 4 replaced a fallback that picked any login configured for the host, which meant a
+seat with no login of its own silently acted as whichever seat had configured one. That
+satisfied the author≠reviewer gate on paper while one actor held both names.
+
+**Provisioning the logins.** `tools/fleet/seat-logins.sh` projects each seat's token from
+its secrets store into tea's config under the canonical name. tea's config is a derived
+cache of the secrets store: regenerate it with the script, never hand-edit it. Run it with
+`--seat <seat>` for one seat (all seats when omitted), dry-run by default, `--apply` to write. A hand-made
+alias holding a seat's token blocks its canonical name (tea refuses one token under two
+names); `--adopt` renames it.
+
 ### Enabling it for a clone
 
 The framework installer syncs `git-credential-mosaic` to

packages/mosaic/framework/tools/git/ci-queue-wait.sh

@@ -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
             ;;

packages/mosaic/framework/tools/git/detect-platform.sh

@@ -180,6 +180,66 @@ raise SystemExit(1)
 PY
 }
 
+# Map a host to the instance prefix used in canonical tea login names
+# ("<instance>-<identity>"). This deliberately mirrors the _idpfx case in
+# get_gitea_token(): the two credential paths must agree on what a host is called,
+# or an agent authenticates as itself on one path and as somebody else on the other.
+gitea_instance_for_host() {
+    case "${1:-}" in
+        git.uscllc.com)      echo usc ;;
+        git.mosaicstack.dev) echo mosaicstack ;;
+        *)                   return 1 ;;
+    esac
+}
+
+# Resolve the acting git identity, same precedence as get_gitea_token() step 0.
+# Prints "<identity>\t<source>" so the caller can name the source in an error.
+resolve_git_identity() {
+    local ident src
+    ident="${MOSAIC_GIT_IDENTITY:-}"
+    src="MOSAIC_GIT_IDENTITY"
+    if [[ -z "$ident" ]]; then
+        ident="$(git config --get mosaic.gitIdentity 2>/dev/null || true)"
+        src="git config mosaic.gitIdentity"
+    fi
+    [[ -n "$ident" ]] || return 1
+    printf '%s\t%s\n' "$ident" "$src"
+}
+
+# Map a repo owner to an instance. Used only by the --repo override path, which
+# has an owner and no host. Previously lived inline in lane-brief.sh; one copy so
+# the two override callers cannot drift apart.
+gitea_instance_for_owner() {
+    local owner="${1:-}"
+    owner="${owner%%/*}"
+    case "$owner" in
+        usc|USC)            echo usc ;;
+        mosaicstack|mosaic) echo mosaicstack ;;
+        *)                  return 1 ;;
+    esac
+}
+
+# Does a login of this name exist at all? The --repo override path cannot check
+# host agreement, because it has no host.
+tea_login_exists() {
+    local login_name="$1"
+    local logins_json
+    command -v tea >/dev/null 2>&1 || return 1
+    logins_json=$(tea login list --output json 2>/dev/null) || return 1
+    TEA_LOGINS_JSON="$logins_json" python3 - "$login_name" <<'PY_INNER'
+import json, os, sys
+want = sys.argv[1]
+try:
+    logins = json.loads(os.environ.get("TEA_LOGINS_JSON", "[]"))
+except Exception:
+    raise SystemExit(1)
+for login in logins if isinstance(logins, list) else []:
+    if str(login.get("name") or login.get("Name") or "") == want:
+        raise SystemExit(0)
+raise SystemExit(1)
+PY_INNER
+}
+
 tea_login_matches_host() {
     local login_name="$1" host="$2"
     local logins_json
@@ -276,6 +336,40 @@ get_gitea_login_for_host() {
         fi
     fi
 
+    # IDENTITY LADDER (#1356). Below this point the old code took the FIRST login
+    # matching the host, which is not an identity — with 43 logins on a fleet host,
+    # ~22 match one server, so a seat with no login of its own silently acted as
+    # whichever happened to be first in ~/.config/tea/config.yml. Gate 16 depends on
+    # author != reviewer, and borrowing satisfies it mechanically while violating it
+    # in fact. The token path already refuses to borrow; this is the same refusal.
+    #
+    # Enforced ONLY when an identity is resolvable, exactly like get_gitea_token():
+    # no identity means a human at a terminal, and neither path enforces there.
+    local ident ident_src inst canon
+    if IFS=$'\t' read -r ident ident_src < <(resolve_git_identity); then
+        if inst=$(gitea_instance_for_host "$host"); then
+            canon="${inst}-${ident}"
+            if tea_login_matches_host "$canon" "$host"; then
+                echo "$canon"
+                return 0
+            fi
+            # Say which of the two it is. "No such login" when tea is simply not
+            # installed is a diagnosis of a cause that was never checked, and it
+            # sends the reader off to create a login they cannot create.
+            if ! command -v tea >/dev/null 2>&1; then
+                echo "Error: git identity '$ident' requested (via $ident_src) for host '$host', but tea is not installed," >&2
+                echo "       so no login can be resolved. Refusing to guess an identity." >&2
+                return 1
+            fi
+            echo "Error: git identity '$ident' requested (via $ident_src) for host '$host', but no tea login named '$canon' exists." >&2
+            echo "       Refusing to borrow another login. Acting as a different identity would satisfy gate 16 mechanically while violating it." >&2
+            echo "       Create it with:  ~/.config/mosaic/tools/fleet/seat-logins.sh --apply --seat $ident" >&2
+            return 1
+        fi
+        # Identity known but the host is not a Mosaic instance. Fall through: the
+        # canonical name is undefined for it, so there is nothing to enforce.
+    fi
+
     login=$(find_tea_login_for_host "$host" || true)
     if [[ -n "$login" ]]; then
         echo "$login"
@@ -351,14 +445,49 @@ raise SystemExit(1)
 PY
 }
 
+# Resolve a login for an explicit --repo override, which supplies an owner and no
+# host. Takes "owner" or "owner/repo".
+#
+# The old body fell through to get_default_tea_login(), which returns the
+# default-marked login or, failing that, the first login of ANY host — arbitrary
+# identity, chosen by config file order. That is the #1356 fail-open in its worst
+# form, because unlike the host path it does not even constrain the server.
 get_gitea_login_for_repo_override() {
-    local login
+    local owner="${1:-}"
+    local login ident ident_src inst canon
 
     if [[ -n "${GITEA_LOGIN:-}" ]]; then
         echo "$GITEA_LOGIN"
         return 0
     fi
 
+    if IFS=$'\t' read -r ident ident_src < <(resolve_git_identity); then
+        if inst=$(gitea_instance_for_owner "$owner"); then
+            canon="${inst}-${ident}"
+            if tea_login_exists "$canon"; then
+                echo "$canon"
+                return 0
+            fi
+            # Same split as the host path above (#1357 S1): a missing tea binary
+            # is not a missing login, and the "create it with" advice cannot be
+            # followed without tea.
+            if ! command -v tea >/dev/null 2>&1; then
+                echo "Error: git identity '$ident' (via $ident_src) requested for owner '${owner%%/*}', but tea is not installed," >&2
+                echo "       so no login can be resolved. Refusing to guess an identity." >&2
+                return 1
+            fi
+            echo "Error: git identity '$ident' (via $ident_src) has no tea login '$canon' for owner '${owner%%/*}'." >&2
+            echo "       Create it with:  ~/.config/mosaic/tools/fleet/seat-logins.sh --apply --seat $ident" >&2
+            return 1
+        fi
+        echo "Error: git identity '$ident' (via $ident_src) is set, but owner '${owner%%/*}' maps to no known instance," >&2
+        echo "       so the login name cannot be derived. Refusing to fall back to an arbitrary login." >&2
+        echo "       Set GITEA_LOGIN to name the login explicitly." >&2
+        return 1
+    fi
+
+    # No identity: a human at a terminal. Unchanged, and the same place the token
+    # path stops enforcing.
     login=$(get_default_tea_login || true)
     if [[ -n "$login" ]]; then
         echo "$login"

packages/mosaic/framework/tools/git/issue-list.sh

@@ -99,8 +99,8 @@ case "$PLATFORM" in
         ;;
     gitea)
         if [[ -n "$REPO_OVERRIDE" ]]; then
-            GITEA_LOGIN_NAME=$(get_gitea_login_for_repo_override) || {
-                echo "Error: Could not resolve Gitea login for --repo override. Set GITEA_LOGIN or configure a default tea login." >&2
+            GITEA_LOGIN_NAME=$(get_gitea_login_for_repo_override "$REPO_OVERRIDE") || {
+                echo "Error: could not resolve a Gitea login for the --repo override (the lines above say why). Set GITEA_LOGIN to name one explicitly." >&2
                 exit 1
             }
         else

packages/mosaic/framework/tools/git/issue-view.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# issue-view.sh - View issue details on GitHub or Gitea
+# issue-view.sh - View issue details, including comments, on GitHub or Gitea
 # Usage: issue-view.sh -i <issue_number>
 
 set -e
@@ -28,11 +28,47 @@ gitea_issue_view_api() {
     }
 
     url="https://${host}/api/v1/repos/${repo}/issues/${ISSUE_NUMBER}"
-    if command -v python3 >/dev/null 2>&1; then
-        curl -fsS -H "User-Agent: curl/8" -H "Authorization: token ${token}" "$url" | python3 -m json.tool
-    else
-        curl -fsS -H "User-Agent: curl/8" -H "Authorization: token ${token}" "$url"
+    local -a curl_args=(-fsS -H "User-Agent: curl/8" -H "Authorization: token ${token}")
+    if ! command -v python3 >/dev/null 2>&1; then
+        # No renderer: raw JSON is all this path can give. Comments are a
+        # second resource, so fetch them too rather than only the count.
+        curl "${curl_args[@]}" "$url"
+        curl "${curl_args[@]}" "${url}/comments"
+        return
     fi
+    # Render issue + comments as text (#1357 F2). The old fallback dumped the
+    # issue JSON, which carries only a comment COUNT, so every comment body was
+    # invisible on this path and the wrapper could never show what
+    # `tea issues --comments` shows.
+    {
+        curl "${curl_args[@]}" "$url"
+        echo
+        echo "__MOSAIC_COMMENTS__"
+        curl "${curl_args[@]}" "${url}/comments"
+    } | python3 -c '
+import json, sys
+raw = sys.stdin.read()
+issue_raw, _, comments_raw = raw.partition("__MOSAIC_COMMENTS__")
+issue = json.loads(issue_raw)
+comments = json.loads(comments_raw) if comments_raw.strip() else []
+print("#%s %s" % (issue["number"], issue["title"]))
+print("State: %s  Author: %s  Created: %s" % (issue["state"], issue["user"]["login"], issue["created_at"]))
+labels = ", ".join(l["name"] for l in issue.get("labels") or [])
+if labels:
+    print("Labels: " + labels)
+if issue.get("milestone"):
+    print("Milestone: " + issue["milestone"]["title"])
+print("URL: " + issue["html_url"])
+print()
+print(issue.get("body") or "(no body)")
+if comments:
+    print()
+    print("--- Comments (%d) ---" % len(comments))
+    for c in comments:
+        print()
+        print("[%s at %s]" % (c["user"]["login"], c["created_at"]))
+        print(c.get("body") or "")
+'
 }
 
 while [[ $# -gt 0 ]]; do
@@ -46,6 +82,8 @@ while [[ $# -gt 0 ]]; do
             echo ""
             echo "Options:"
             echo "  -i, --issue    Issue number (required)"
+            echo ""
+            echo "Comments are always included (tea --comments / Gitea API /comments)."
             echo "  -h, --help     Show this help"
             exit 0
             ;;
@@ -67,11 +105,30 @@ if [[ "$PLATFORM" == "github" ]]; then
     gh issue view "$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if command -v tea >/dev/null 2>&1; then
-        if tea issue "$ISSUE_NUMBER" $(get_gitea_repo_args); then
+        # --comments is what makes tea print the comment bodies (#1357 F3).
+        # Without it tea prompts for them interactively, which in a
+        # non-interactive wrapper means they are silently never shown.
+        tea_err=$(mktemp)
+        if tea issue "$ISSUE_NUMBER" $(get_gitea_repo_args) --comments 2>"$tea_err"; then
+            rm -f "$tea_err"
             exit 0
         fi
-        echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
-        { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
+        # Name the cause tea actually reported, not a guessed one (#1357 F1/F4).
+        # tea reads the cwd's git config before honouring --repo; a repo with
+        # extensions.worktreeconfig=true makes it exit 1 with a
+        # repositoryformatversion error. That is a git-config condition, not a
+        # credential one. The old path printed the REVOKED OR STALE TOKEN note
+        # here unconditionally, which sent readers to rotate a token that was fine.
+        if grep -q 'repositoryformatversion' "$tea_err"; then
+            echo "Warning: tea cannot read this repo's git config (extensions.worktreeconfig); not a credential problem. Using Gitea API fallback." >&2
+        elif grep -q 'user does not exist' "$tea_err"; then
+            echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
+            { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
+        else
+            echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
+        fi
+        sed 's/^/  tea: /' "$tea_err" >&2
+        rm -f "$tea_err"
     fi
     gitea_issue_view_api
 else

packages/mosaic/framework/tools/git/lane-brief.sh

@@ -49,11 +49,27 @@ if [[ -z "$LOGIN" ]]; then
   if [[ -n "${GITEA_LOGIN:-}" ]]; then
     LOGIN="$GITEA_LOGIN"
   else
-    case "${REPO%%/*}" in
-      usc|USC) LOGIN=usc ;;
-      mosaicstack|mosaic) LOGIN=mosaicstack ;;
-      *) LOGIN="$(get_gitea_login_for_repo_override 2>/dev/null || true)" ;;
-    esac
+    # #1356: the owner-derived map below picks a SHARED login (bare `usc` /
+    # `mosaicstack`). On a seat that is borrowing another identity, which is
+    # exactly what gate 16 forbids. So the identity ladder goes first and the
+    # map is only the no-identity fallback (a human at a terminal), which is
+    # where the token path stops enforcing too.
+    if LOGIN="$(get_gitea_login_for_repo_override "$REPO")"; then
+      :
+    elif resolve_git_identity >/dev/null 2>&1; then
+      # A git identity IS set and the ladder still could not resolve a login.
+      # The named reason is already on stderr. Falling through to the map here
+      # would hand this seat a SHARED login (bare `usc` / `mosaicstack`) — the
+      # identity-borrowing #1356 exists to stop. Fail closed instead.
+      exit 2
+    else
+      # No identity: a human at a terminal. Owner-derived map, unchanged. This
+      # is the same point at which the token path stops enforcing.
+      case "${REPO%%/*}" in
+        usc|USC) LOGIN=usc ;;
+        mosaicstack|mosaic) LOGIN=mosaicstack ;;
+      esac
+    fi
   fi
 fi
 [[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 2; }

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

@@ -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

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

@@ -94,8 +94,8 @@ case "$PLATFORM" in
         ;;
     gitea)
         if [[ -n "$REPO_OVERRIDE" ]]; then
-            GITEA_LOGIN_NAME=$(get_gitea_login_for_repo_override) || {
-                echo "Error: Could not resolve Gitea login for --repo override. Set GITEA_LOGIN or configure a default tea login." >&2
+            GITEA_LOGIN_NAME=$(get_gitea_login_for_repo_override "$REPO_OVERRIDE") || {
+                echo "Error: could not resolve a Gitea login for the --repo override (the lines above say why). Set GITEA_LOGIN to name one explicitly." >&2
                 exit 1
             }
         else

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

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--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)

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

@@ -59,8 +59,8 @@ if [[ "$PLATFORM" == "github" ]]; then
     gh pr view "$PR_NUMBER" --repo "$REPO_INFO"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if [[ -n "$REPO_OVERRIDE" ]]; then
-        GITEA_LOGIN_NAME=$(get_gitea_login_for_repo_override) || {
-            echo "Error: Could not resolve Gitea login for --repo override. Set GITEA_LOGIN or configure a default tea login." >&2
+        GITEA_LOGIN_NAME=$(get_gitea_login_for_repo_override "$REPO_OVERRIDE") || {
+            echo "Error: could not resolve a Gitea login for the --repo override (the lines above say why). Set GITEA_LOGIN to name one explicitly." >&2
             exit 1
         }
     else

packages/mosaic/framework/tools/git/test-ci-queue-wait-no-ci-expected.sh

@@ -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)"

packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh

@@ -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 '{}'
         ;;
@@ -110,8 +119,20 @@ chmod +x "$BIN_DIR/tea" "$BIN_DIR/curl"
 
 run_in_repo() {
     (
+        # HERMETICITY, second half (#1356). The empty repo-local `mosaic.gitIdentity`
+        # above pins the git-config route into identity resolution. It does NOT pin
+        # the environment route, and MOSAIC_GIT_IDENTITY is checked FIRST — so on any
+        # provisioned seat, where the launcher exports it, this suite failed before
+        # any change: rc=1 as-is, rc=0 under `env -u MOSAIC_GIT_IDENTITY`, one
+        # variable. A suite that cannot run on a seat cannot guard this code for the
+        # agents that actually run it.
+        #
+        # Unset rather than set empty: an empty MOSAIC_GIT_IDENTITY and an absent one
+        # take different branches in resolve_git_identity(), and the case under test
+        # is "no identity at all".
         cd "$REPO_DIR"
-        PATH="$BIN_DIR:$PATH" \
+        env -u MOSAIC_GIT_IDENTITY \
+        PATH="${_SANDBOX_BIN:-$BIN_DIR}:$PATH" \
         HOME="$HOME_DIR" \
         MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
         MOSAIC_TEST_LOG="$LOG_FILE" \
@@ -307,14 +328,11 @@ SH
 chmod +x "$BIN_DIR2/tea"
 
 run_in_repo2() {
-    (
-        cd "$REPO_DIR"
-        PATH="$BIN_DIR2:$PATH" \
-        HOME="$HOME_DIR" \
-        MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
-        MOSAIC_TEST_LOG="$LOG_FILE" \
-        "$@"
-    )
+    # Same sandbox as run_in_repo, different mock tea (BIN_DIR2 defines a
+    # mosaicstack login). This MUST delegate rather than re-implement: it was a
+    # copy once, and the copy silently missed the MOSAIC_GIT_IDENTITY unset, so
+    # the suite kept failing on a seat after run_in_repo was already fixed.
+    _SANDBOX_BIN="$BIN_DIR2" run_in_repo "$@"
 }
 
 git -C "$REPO_DIR" remote set-url origin https://git.mosaicstack.dev/mosaicstack/stack.git
@@ -340,6 +358,151 @@ if [[ "$override_wins" != "mosaicstack" ]]; then
 fi
 git -C "$REPO_DIR" remote set-url origin https://git.uscllc.com/USC/uconnect.git
 
+# ---------------------------------------------------------------------------
+# #1356: the git-identity ladder. A seat declares who it is (MOSAIC_GIT_IDENTITY
+# or `git config mosaic.gitIdentity`); resolution must use THAT seat's login and
+# must REFUSE to borrow another one when it is absent. Silently borrowing
+# satisfies gate 16 mechanically (a review exists) while violating it (the
+# reviewer and the author are the same actor under two names).
+#
+# BIN_DIR3 mocks a tea that holds a canonical per-seat login, which is what a
+# projected seat looks like. BIN_DIR2 (mosaicstack only) is reused as the
+# "seat has no login" case — no third mock needed for the negative branch.
+# ---------------------------------------------------------------------------
+BIN_DIR3="$WORK_DIR/bin3"
+mkdir -p "$BIN_DIR3"
+cp "$BIN_DIR/curl" "$BIN_DIR3/curl"
+cat > "$BIN_DIR3/tea" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$*" == "login list --output json" ]]; then
+    cat <<'JSON'
+[
+  {"name":"mosaicstack","url":"https://git.mosaicstack.dev","user":"ci-bot"},
+  {"name":"mosaicstack-testseat","url":"https://git.mosaicstack.dev","user":"testseat"},
+  {"name":"usc","url":"https://git.uscllc.com","user":"ci-bot"}
+]
+JSON
+    exit 0
+fi
+printf 'tea %s\n' "$*" >> "$MOSAIC_TEST_LOG"
+exit 0
+SH
+chmod +x "$BIN_DIR3/tea"
+
+run_in_repo3() { _SANDBOX_BIN="$BIN_DIR3" run_in_repo "$@"; }
+
+git -C "$REPO_DIR" remote set-url origin https://git.mosaicstack.dev/mosaicstack/stack.git
+
+# Branch 1 (host path): identity set, canonical login PRESENT -> that login wins
+# over the shared `mosaicstack` one, which is what host-matching alone would pick.
+ladder_hit=$(run_in_repo3 env MOSAIC_GIT_IDENTITY=testseat bash -c '
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_host git.mosaicstack.dev
+')
+if [[ "$ladder_hit" != "mosaicstack-testseat" ]]; then
+    echo "Expected identity ladder to select 'mosaicstack-testseat'; got '$ladder_hit'" >&2
+    exit 1
+fi
+
+# CONTROL for branch 1: the same mock, no identity, must still resolve by host.
+# Without this, branch 1 passing proves nothing about the ladder specifically --
+# it would also pass if the code just picked the last matching login.
+ladder_none=$(run_in_repo3 bash -c '
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_host git.mosaicstack.dev
+')
+if [[ "$ladder_none" != "mosaicstack" ]]; then
+    echo "Expected no-identity host resolution to stay 'mosaicstack'; got '$ladder_none'" >&2
+    exit 1
+fi
+
+# Branch 2 (host path): identity set, canonical login ABSENT -> fail closed with a
+# named error. Two assertions, and they are not the same one twice: rc!=0 proves
+# it refused, and the ABSENCE of any login on stdout proves it did not borrow the
+# `mosaicstack` login that is sitting right there matching the host.
+ladder_err=$(run_in_repo2 env MOSAIC_GIT_IDENTITY=testseat bash -c '
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_host git.mosaicstack.dev
+' 2>&1 1>/dev/null || true)
+ladder_out=$(run_in_repo2 env MOSAIC_GIT_IDENTITY=testseat bash -c '
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_host git.mosaicstack.dev
+' 2>/dev/null || true)
+if [[ -n "$ladder_out" ]]; then
+    echo "Identity ladder BORROWED login '$ladder_out' instead of failing closed" >&2
+    exit 1
+fi
+if ! grep -q "mosaicstack-testseat" <<<"$ladder_err"; then
+    echo "Expected the error to name the login it wanted; got: $ladder_err" >&2
+    exit 1
+fi
+
+# Branch 3: `git config mosaic.gitIdentity` is the second rung and must work when
+# the environment variable is absent -- a seat may be configured either way.
+git -C "$REPO_DIR" config mosaic.gitIdentity testseat
+ladder_gitcfg=$(run_in_repo3 bash -c '
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_host git.mosaicstack.dev
+')
+git -C "$REPO_DIR" config --unset mosaic.gitIdentity || true
+if [[ "$ladder_gitcfg" != "mosaicstack-testseat" ]]; then
+    echo "Expected git-config identity rung to select 'mosaicstack-testseat'; got '$ladder_gitcfg'" >&2
+    exit 1
+fi
+
+# Branch 4 (--repo override path): same rule, owner-derived instead of host-derived.
+override_ladder=$(run_in_repo3 env MOSAIC_GIT_IDENTITY=testseat bash -c '
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_repo_override mosaicstack/stack
+')
+if [[ "$override_ladder" != "mosaicstack-testseat" ]]; then
+    echo "Expected --repo override ladder to select 'mosaicstack-testseat'; got '$override_ladder'" >&2
+    exit 1
+fi
+
+# Branch 5: explicit GITEA_LOGIN outranks the ladder. An operator naming a login
+# by hand is a deliberate act, not an accident to be second-guessed.
+override_explicit=$(run_in_repo3 env MOSAIC_GIT_IDENTITY=testseat GITEA_LOGIN=mosaicstack bash -c '
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_repo_override mosaicstack/stack
+')
+if [[ "$override_explicit" != "mosaicstack" ]]; then
+    echo "Expected explicit GITEA_LOGIN to outrank the identity ladder; got '$override_explicit'" >&2
+    exit 1
+fi
+
+# Branch 6 (#1357 S1): with tea ABSENT from PATH, the override path must say tea is
+# missing, not "no tea login named X exists" (a cause that was never checked) and
+# not the seat-logins.sh advice, which cannot be followed without tea.
+NOTEA_BIN="$WORK_DIR/notea-bin"; mkdir -p "$NOTEA_BIN"
+for t in bash git python3 sed grep cat mktemp dirname basename readlink env sort head tr cut; do
+    _p="$(command -v "$t" 2>/dev/null || true)"; [[ -n "$_p" ]] && ln -sf "$_p" "$NOTEA_BIN/$t"
+done
+override_notea_rc=0
+override_notea_err=$(cd "$REPO_DIR" && env -u GITEA_LOGIN \
+    PATH="$NOTEA_BIN" HOME="$HOME_DIR" MOSAIC_GIT_IDENTITY=testseat \
+    bash -c '
+    command -v tea >/dev/null 2>&1 && { echo "SETUP: tea still on PATH"; exit 99; }
+    source "'"$SCRIPT_DIR"'/detect-platform.sh"
+    get_gitea_login_for_repo_override mosaicstack/stack
+' 2>&1 >/dev/null) || override_notea_rc=$?
+if [[ "$override_notea_rc" != 1 ]]; then
+    echo "Expected --repo override path to fail (rc=1) with tea absent; got rc=$override_notea_rc: $override_notea_err" >&2
+    exit 1
+fi
+if ! grep -q 'tea is not installed' <<<"$override_notea_err"; then
+    echo "Expected --repo override path to name tea as absent; got: $override_notea_err" >&2
+    exit 1
+fi
+if grep -q 'has no tea login\|seat-logins.sh' <<<"$override_notea_err"; then
+    echo "Override path diagnosed a missing LOGIN while tea itself is absent: $override_notea_err" >&2
+    exit 1
+fi
+
+git -C "$REPO_DIR" remote set-url origin https://git.uscllc.com/USC/uconnect.git
+
+
 # ---------------------------------------------------------------------------
 # #865 Blocker 1 & 2: get_gitea_token_for_login must resolve the SAME token as
 # PyYAML would (or fail closed identically) even when PyYAML is ABSENT, and must

packages/mosaic/framework/tools/git/test-issue-close-fail-closed.sh

@@ -76,7 +76,22 @@ exit 0
 EOF
     chmod +x "$MOCK_BIN/tea"
 }
+# #1356: login resolution is now identity-aware, so the tea-branch fixture must
+# offer the login the RUNNER's identity resolves to; otherwise every case below
+# fails closed before reaching the branch under test.
+#
+# This does NOT make the suite hermetic, and it is not trying to. The API-path
+# cases (5-7) need a usable Gitea token, and with an identity set the token path
+# reads that seat's credential file rather than the GITEA_TOKEN exported above.
+# So this suite passes only where the runner owns a real credential for its own
+# identity, and fails with no identity at all -- on this branch and on its base
+# alike. That is a pre-existing hole in the fixture, filed separately; pinning a
+# synthetic identity here would only convert it into a confident-looking green.
+_LOGIN_IDENT="${MOSAIC_GIT_IDENTITY:-}"
 LOGIN_JSON='[{"name":"git.mosaicstack.dev","url":"https://git.mosaicstack.dev"}]'
+if [[ -n "$_LOGIN_IDENT" ]]; then
+    LOGIN_JSON='[{"name":"mosaicstack-'"$_LOGIN_IDENT"'","url":"https://git.mosaicstack.dev"},{"name":"git.mosaicstack.dev","url":"https://git.mosaicstack.dev"}]'
+fi
 
 # The mocks must be the ones that run. Without this, a failed setup silently falls through
 # to the real tea/curl and the "test" mutates the real provider.

packages/mosaic/framework/tools/git/test-issue-create-body-safety.sh

@@ -10,6 +10,12 @@
 
 set -euo pipefail
 
+# HERMETICITY (#1356): this suite's subject is body quoting, not identity. An
+# ambient MOSAIC_GIT_IDENTITY (every provisioned seat exports one) would make the
+# identity ladder demand a per-seat login this fixture does not define, and the
+# suite would fail for a reason it is not testing.
+unset MOSAIC_GIT_IDENTITY
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-create-body-safety}"
 REPO_DIR="$WORK_DIR/repo"

packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh

@@ -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"
 

packages/mosaic/framework/tools/git/test-issue-view-comments.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Regression: issue-view.sh must show comment BODIES, on both paths, and must name
+# the failure tea actually reported instead of guessing a credential cause (#1357).
+#
+# Four defects, each with its own case below:
+#   F1  tea exits 1 in any repo with extensions.worktreeconfig=true; the wrapper must
+#       say so (git-config condition) and fall back to the API.
+#   F2  the API fallback dumped raw issue JSON, which carries only a comment COUNT.
+#   F3  the tea path never passed --comments, so tea prompted (non-interactively: nothing).
+#   F4  on ANY tea failure the wrapper printed the REVOKED OR STALE TOKEN note.
+#
+# Verification bar (plan §6): assert a real comment BODY appears, not a count and not
+# `grep -c comment` (that instrument matched the issue title and read inverted).
+#
+# Hermetic: mock tea and curl on PATH, sandboxed repo. Resolves no real credentials.
+set -euo pipefail
+
+WORK_ROOT="${AGENT_WORK_ROOT:-${TMPDIR:-/tmp}}"
+SANDBOX="$WORK_ROOT/issue-view-comments-test-$$"
+MOCK_BIN="$SANDBOX/bin"; REPO_DIR="$SANDBOX/repo"; CALLS="$SANDBOX/calls.log"
+cleanup() { rm -rf "$SANDBOX"; }
+trap cleanup EXIT
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET="$SCRIPT_DIR/issue-view.sh"
+[ -f "$TARGET" ] || { echo "FAIL: issue-view.sh not found beside this test"; exit 1; }
+fail() { echo "FAIL: $*"; exit 1; }
+
+mkdir -p "$MOCK_BIN" "$REPO_DIR" || fail "setup: cannot create sandbox under $WORK_ROOT"
+: > "$CALLS"                     || fail "setup: cannot write calls log at $CALLS"
+cd "$REPO_DIR"                   || fail "setup: cannot cd into $REPO_DIR"
+git init -q                      || fail "setup: git init failed"
+git remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git || fail "setup: git remote add failed"
+export PATH="$MOCK_BIN:$PATH" CALLS
+export GITEA_URL="https://git.mosaicstack.dev"
+export GITEA_TOKEN="redacted-test-token"
+# The identity ladder must not reach for this seat's real login; the mock tea below
+# defines the only login that exists in this sandbox.
+unset MOSAIC_GIT_IDENTITY
+# No fleet in the sandbox: on a host that runs one, get_gitea_token fails closed for an
+# identity-less caller (by design), which would make this test measure the host, not
+# the wrapper. An empty brain home makes the sandbox the same on every host.
+export MOSAIC_BRAIN_HOME="$SANDBOX/brain"
+mkdir -p "$MOSAIC_BRAIN_HOME" || fail "setup: cannot create sandbox brain home"
+
+# Distinctive strings: a comment body that appears nowhere else, and an issue title
+# that contains the word "comment" so a count-of-the-word instrument would misread.
+BODY_MARKER="zebra-quill-comment-body-7731"
+ISSUE_TITLE="wrapper never shows a comment"
+
+# --- mock curl: serves the issue and its comments; logs every call --------------
+cat > "$MOCK_BIN/curl" <<EOF
+#!/bin/bash
+url=""
+while [ \$# -gt 0 ]; do
+    case "\$1" in
+        http*) url="\$1"; shift ;;
+        *) shift ;;
+    esac
+done
+printf 'curl %s\n' "\$url" >> "$CALLS"
+case "\$url" in
+    */issues/77/comments)
+        if [ "\${MOCK_NO_COMMENTS:-}" = "1" ]; then echo '[]'; else
+        echo '[{"id":1,"user":{"login":"alice"},"created_at":"2026-08-21T00:00:00Z","body":"$BODY_MARKER"}]'; fi ;;
+    */issues/77)
+        echo '{"number":77,"title":"$ISSUE_TITLE","state":"open","user":{"login":"bob"},"created_at":"2026-08-21T00:00:00Z","labels":[],"milestone":null,"html_url":"https://git.mosaicstack.dev/mosaicstack/stack/issues/77","body":"issue body","comments":1}' ;;
+    *) echo '{}' ;;
+esac
+exit 0
+EOF
+chmod +x "$MOCK_BIN/curl"
+
+# --- mock tea: MOCK_TEA_MODE selects the behaviour under test --------------------
+#   ok         : prints the issue, and the comment body ONLY when --comments is passed (F3)
+#   wtconfig   : exits 1 with the repositoryformatversion error (F1/F4)
+#   badtoken   : exits 1 with tea's credential error (F4 control: credential wording allowed)
+cat > "$MOCK_BIN/tea" <<EOF
+#!/bin/bash
+printf 'tea %s\n' "\$*" >> "$CALLS"
+if [[ "\$*" == *"login list"* ]]; then
+    echo '[{"name":"git.mosaicstack.dev","url":"https://git.mosaicstack.dev"}]'; exit 0
+fi
+case "\${MOCK_TEA_MODE:-ok}" in
+    wtconfig) echo 'Error: core.repositoryformatversion does not support extension: worktreeconfig' >&2; exit 1 ;;
+    badtoken) echo 'Failed to create Gitea client: invalid username, password or token' >&2; exit 1 ;;
+esac
+echo "# #77 $ISSUE_TITLE (open)"
+echo "issue body"
+if [[ "\$*" == *"--comments"* ]]; then echo "$BODY_MARKER"; fi
+exit 0
+EOF
+chmod +x "$MOCK_BIN/tea"
+
+[ "$(command -v tea)" = "$MOCK_BIN/tea" ]   || fail "setup: tea does not resolve inside the sandbox"
+[ "$(command -v curl)" = "$MOCK_BIN/curl" ] || fail "setup: curl does not resolve inside the sandbox"
+
+run() { bash "$TARGET" -i 77 >"$SANDBOX/out" 2>"$SANDBOX/err"; echo $?; }
+
+# F3: tea path shows the comment body, which the mock emits only under --comments.
+: > "$CALLS"
+rc=$(MOCK_TEA_MODE=ok run)
+[ "$rc" = 0 ] || fail "F3: expected rc=0 on the tea path, got $rc: $(cat "$SANDBOX/err")"
+grep -q -- '--comments' "$CALLS"        || fail "F3: tea was not invoked with --comments: $(cat "$CALLS")"
+grep -q "$BODY_MARKER" "$SANDBOX/out"   || fail "F3: comment body missing from tea-path output"
+if grep -q '^curl' "$CALLS"; then fail "F3: tea path succeeded but the API fallback ran anyway"; fi
+
+# F1 + F2: worktreeconfig failure is named as a git-config condition, falls back to
+# the API, and the API rendering includes the comment BODY.
+: > "$CALLS"
+rc=$(MOCK_TEA_MODE=wtconfig run)
+[ "$rc" = 0 ] || fail "F1: expected rc=0 via API fallback, got $rc: $(cat "$SANDBOX/err")"
+grep -q 'worktreeconfig' "$SANDBOX/err" || fail "F1: stderr does not name the worktreeconfig cause: $(cat "$SANDBOX/err")"
+grep -q 'not a credential problem' "$SANDBOX/err" || fail "F1: stderr does not rule out the credential cause"
+grep -q 'issues/77/comments' "$CALLS"   || fail "F2: API fallback never fetched /comments: $(cat "$CALLS")"
+grep -q "$BODY_MARKER" "$SANDBOX/out"   || fail "F2: comment body missing from API-path output"
+grep -q "$ISSUE_TITLE" "$SANDBOX/out"   || fail "F2: issue title missing from API-path output"
+if grep -q 'REVOKED OR STALE' "$SANDBOX/err"; then fail "F4: stale-token note printed for a git-config failure"; fi
+if grep -q '"comments": 1' "$SANDBOX/out"; then fail "F2: output is still raw JSON (comment count instead of bodies)"; fi
+
+# F4 control: a real credential error from tea may still carry the credential note,
+# and tea's own line must be relayed so the reader sees the actual cause.
+: > "$CALLS"
+rc=$(MOCK_TEA_MODE=badtoken run)
+[ "$rc" = 0 ] || fail "F4 control: expected rc=0 via API fallback, got $rc"
+grep -q 'invalid username, password or token' "$SANDBOX/err" || fail "F4: tea's own error line was not relayed"
+if grep -q 'worktreeconfig' "$SANDBOX/err"; then fail "F4: git-config wording printed for a credential failure"; fi
+
+# Negative control: an issue with no comments prints no comment section on the API
+# path. Without this, a renderer that always prints a section would pass F2.
+: > "$CALLS"
+rc=$(MOCK_TEA_MODE=wtconfig MOCK_NO_COMMENTS=1 run)
+[ "$rc" = 0 ] || fail "negative control: expected rc=0, got $rc"
+if grep -q -- '--- Comments' "$SANDBOX/out"; then fail "negative control: comment section printed for an issue with no comments"; fi
+if grep -q "$BODY_MARKER" "$SANDBOX/out"; then fail "negative control: a comment body appeared for an issue with no comments"; fi
+
+echo "issue-view comments regression harness passed"

packages/mosaic/framework/tools/git/test-pr-create-fallback-default-base.sh

@@ -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"

packages/mosaic/framework/tools/git/test-pr-merge-no-ci-expected.sh

@@ -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"

packages/mosaic/framework/tools/git/test-wrapper-guard.sh

@@ -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"
 }

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

@@ -13,7 +13,6 @@
 # --- tools/git: the #1007 five — non-hermetic, resolve real credentials ---
 packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix (git -C scoping)
 packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
-packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
 packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh | resolves real credentials (#1007 census, fourth entry via family-grep); joins CI after the wrapper-half hermeticity fix
 packages/mosaic/framework/tools/git/test-issue-comment-readback.sh | resolves real credentials (#1007 census, fifth entry); joins CI after the wrapper-half hermeticity fix
 

packages/mosaic/framework/tools/structure/test-validate-repo-json.sh

@@ -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"

packages/mosaic/framework/tools/structure/validate-repo-json.sh

@@ -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

packages/mosaic/framework/tools/tmux/send-message.sh

@@ -32,7 +32,9 @@
 #   0  delivered (submitted) or queued (agent busy; will process when free)
 #   1  tmux target not found
 #   2  submission NOT confirmed — either still an unsubmitted draft, or the REPL
-#      input prompt could not be located to confirm the message actually landed.
+#      input box could not be located to confirm the message actually landed.
+#      Locating the box is runtime-specific; see locate_input_box() below, and
+#      add a shape there before pointing this tool at a new runtime.
 #      Delivery is NEVER inferred from absence of evidence: if we cannot positively
 #      see the input box clear of the message (or the queued banner), we fail loud
 #      so the sender learns immediately instead of a silent worker->lead stall.
@@ -97,10 +99,50 @@ printf '%s' "$MSG" | "${tmux_cmd[@]}" load-buffer -b "$BUF" -
 #   would otherwise accumulate forever.
 sleep 0.5
 
+# Locate the REPL input box in a captured pane. Prints the box's contents on
+# stdout and returns 0 when the box was FOUND; returns 1 when it could not be
+# located at all. Found-but-empty is a real, distinct answer (an empty input box
+# is what a submitted message leaves behind), so the caller must branch on the
+# return code, never on whether the output is empty.
+#
+# Two REPL shapes are recognised:
+#   * a prompt-glyph line — `❯`, a leading `>`, or `│ >`. Claude Code and most
+#     readline REPLs.
+#   * a box drawn as two horizontal `─` rules with the input between them and NO
+#     prompt glyph anywhere. pi renders this. Anchoring on the LAST rule pair is
+#     what makes it safe: agent output can contain its own rules, but nothing is
+#     drawn below the input box except the status line.
+#
+# Adding a runtime means adding its shape HERE. A shape that is missing does not
+# degrade gracefully: it turns every send to that runtime into a false
+# "may be UNDELIVERED", which is what #1362 measured on pi and #1257 on another
+# arm of the same probe.
+locate_input_box() {
+  local pane=$1 glyph_line rule_lines top bottom
+  glyph_line=$(printf '%s\n' "$pane" | grep -E '❯|^>|│ >' | tail -1)
+  if [ -n "$glyph_line" ]; then printf '%s\n' "$glyph_line"; return 0; fi
+  rule_lines=$(printf '%s\n' "$pane" | grep -nE '^[[:space:]]*─{4,}[[:space:]]*$' | cut -d: -f1 | tail -2)
+  [ -n "$rule_lines" ] || return 1
+  # Split the (at most two) captured line numbers with parameter expansion. Not
+  # `head -1`: piping into an early-exiting consumer SIGPIPEs the producer, which
+  # under `set -euo pipefail` aborts the caller with rc=141 and no output. The
+  # scripts/pipefail-early-exit.test.mjs guard reds on that shape, correctly.
+  # With one rule captured both halves resolve to the same value and the
+  # ordering test below rejects it, which is the answer we want anyway.
+  top=${rule_lines%%$'\n'*}
+  bottom=${rule_lines##*$'\n'}
+  [ "$top" != "$bottom" ] || return 1
+  [ "$bottom" -gt "$top" ] || return 1
+  # An empty range (adjacent rules) prints nothing and still returns 0: found,
+  # empty, which is the delivered shape.
+  printf '%s\n' "$pane" | sed -n "$((top + 1)),$((bottom - 1))p"
+  return 0
+}
+
 # 2) Submit, then POSITIVELY confirm submission; flush with another Enter if it is
 #    still a draft. Success requires positive evidence — the queued banner, OR the
 #    REPL input box located AND clear of our message tail. The historical bug was
-#    treating ABSENCE of a draft as delivery: if the prompt glyph was never matched
+#    treating ABSENCE of a draft as delivery: if the input box was never located
 #    (wrong pane / prompt-glyph drift), an unsubmitted message read as "delivered"
 #    and worker->lead relays stalled silently. We now default to UNCONFIRMED and only
 #    upgrade to delivered on positive evidence; anything we cannot confirm fails loud.
@@ -113,15 +155,14 @@ for attempt in $(seq 1 $((RETRIES + 1))); do
   if grep -qF "$QUEUED_RE" <<<"$pane"; then
     status="queued"; break
   fi
-  # Locate the REPL input box (prompt glyph). If we cannot see it, we have NO
-  # evidence of submission state — stay UNCONFIRMED and retry; never infer delivery.
-  promptline=$(printf '%s' "$pane" | grep -E '❯|^>|│ >' | tail -1)
-  if [ -z "$promptline" ]; then
+  # If we cannot see the input box, we have NO evidence of submission state —
+  # stay UNCONFIRMED and retry; never infer delivery.
+  if ! inputbox=$(locate_input_box "$pane"); then
     status="unconfirmed"; continue
   fi
   # Input box located AND still carrying our tail => unsubmitted draft. Flush + retry.
-  # (Submitted messages scroll up into history; a draft stays on the ❯ line.)
-  if [ -n "$snippet" ] && grep -qF "$snippet" <<<"$promptline"; then
+  # (Submitted messages scroll up into history; a draft stays in the box.)
+  if [ -n "$snippet" ] && grep -qF "$snippet" <<<"$inputbox"; then
     status="draft"; continue
   fi
   # Input box located AND clear of our tail => positively submitted. This is the
@@ -135,6 +176,6 @@ case "$status" in
   delivered)   echo "✓ delivered to $TARGET"; exit 0 ;;
   queued)      echo "✓ queued to $TARGET (agent busy — will process when it returns to prompt)"; exit 0 ;;
   draft)       echo "✗ still an unsubmitted draft on $TARGET after $RETRIES flush attempts" >&2; exit 2 ;;
-  unconfirmed) echo "✗ could not confirm submission on $TARGET: REPL input prompt not locatable after $((RETRIES + 1)) attempts — message may be UNDELIVERED (check target/pane, retry, or escalate)" >&2; exit 2 ;;
+  unconfirmed) echo "✗ could not confirm submission on $TARGET: REPL input box not locatable after $((RETRIES + 1)) attempts — message may be UNDELIVERED (check target/pane, retry, or escalate)" >&2; exit 2 ;;
   *)           echo "✗ could not confirm submission on $TARGET (unexpected state '$status')" >&2; exit 2 ;;
 esac

packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh

@@ -10,6 +10,13 @@
 #                    "could not confirm submission").
 #   3. DRAFT       — a `❯ `-prompt pane that never submits (message stays on the
 #                    input line) => exit 2, stderr "unsubmitted draft".
+#   4. DELIVERED   — a pane whose input box is two `─` rules with NO prompt glyph
+#      (box shape)   anywhere (pi's shape) and which submits => exit 0. Pre-#1362
+#                    the glyph probe could not see this box at all, so EVERY send
+#                    to such a pane reported "may be UNDELIVERED" while landing.
+#   5. DRAFT       — the same glyphless box, holding our tail across every flush
+#      (box shape)   Enter => exit 2, stderr "unsubmitted draft". Pre-#1362 this
+#                    also reported unconfirmed, so the true state was invisible.
 set -uo pipefail
 
 HERE=$(cd -- "$(dirname -- "$0")" && pwd)
@@ -69,6 +76,56 @@ else
   fi
 fi
 
+# --- Fixtures 4 and 5: a pi-shaped pane. The input box is two `─` rules with the
+#     text between them and NO prompt glyph anywhere, so the glyph probe alone can
+#     never locate it and every send reports "may be UNDELIVERED" (#1362). The
+#     renderer below is the shape, not the runtime: MODE=clear submits (box empties),
+#     MODE=keep leaves the text sitting in the box.
+cat > "$TMP/pibox.sh" <<'PIBOX'
+#!/usr/bin/env bash
+MODE=${1:-clear}
+RULE=$(printf '─%.0s' $(seq 1 60))
+buf=""
+draw() {
+  printf '\033[H\033[2J'
+  printf 'fixture output line\n\n'
+  printf '%s\n' "$RULE"
+  printf '%s\n' "$buf"
+  printf '%s\n' "$RULE"
+  printf '~/fixture (main)\n'
+  printf 'tok 0 model fixture\n'
+}
+draw
+while IFS= read -r line; do
+  # keep: hold the tail across every flush Enter, which is what a stuck draft does.
+  if [ "$MODE" = keep ]; then [ -n "$line" ] && buf=$line; else buf=""; fi
+  draw
+done
+PIBOX
+chmod +x "$TMP/pibox.sh"
+
+tmux -L "$SOCKET" new-session -d -s pibox -c "$TMP" "exec bash '$TMP/pibox.sh' clear"
+sleep 0.3
+out=$("$SEND" -L "$SOCKET" -t "=pibox" -m "pi fixture four delivered ok" 2>"$TMP/e4"); rc=$?
+if [ "$rc" -eq 0 ] && grep -qF "✓ delivered" <<<"$out"; then
+  ok "delivered: glyphless box-drawn REPL that submits => exit 0 ✓ delivered"
+else
+  no "delivered: glyphless box-drawn REPL that submits => exit 0 ✓ delivered" "rc=$rc out=[$out] err=[$(cat "$TMP/e4")]"
+fi
+
+tmux -L "$SOCKET" new-session -d -s piboxdraft -c "$TMP" "exec bash '$TMP/pibox.sh' keep"
+sleep 0.3
+if out=$("$SEND" -L "$SOCKET" -t "=piboxdraft" -r 1 -m "pi fixture five stuck in the box" 2>"$TMP/e5"); then
+  no "draft: glyphless box-drawn pane holding our tail must NOT report success" "expected exit 2, got 0 (out=[$out])"
+else
+  rc=$?
+  if [ "$rc" -eq 2 ] && grep -qF "unsubmitted draft" "$TMP/e5"; then
+    ok "draft: message left in a glyphless box => exit 2 + 'unsubmitted draft'"
+  else
+    no "draft: message left in a glyphless box => exit 2 + stderr" "rc=$rc err=[$(cat "$TMP/e5")]"
+  fi
+fi
+
 echo "---"
 echo "PASS=$PASS FAIL=$FAIL"
 [ "$FAIL" -eq 0 ]

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 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:*",

packages/mosaic/src/fleet/comms-onboarding.spec.ts

@@ -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'),
+    );
+  });
+});

packages/mosaic/src/fleet/comms-onboarding.ts

@@ -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. */

packages/mosaic/src/fleet/fleet-roster-v1.ts

@@ -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,

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

@@ -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');

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

@@ -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');

packages/mosaic/src/runtime/update-checker.reseed.spec.ts

@@ -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([]);
     }
   });

scripts/verify-release.mjs

@@ -61,6 +61,8 @@ export const STAGES = [
       'bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh --self-test',
       'bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh',
       '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/git/test-wrapper-guard.sh',
       'bash packages/mosaic/framework/tools/git/test-mosaic-worktree-large-repo.sh',
     ],