fix(ci): image pushes read the registry secrets that exist (#1275)

All kaniko image steps (publish.yml build-gateway/build-ci-base/build-*
and ci-image.yml build-ci-base) referenced from_secret: gitea_username /
gitea_password - which do not exist at repo level - while the repo
carries unused REGISTRY_USERNAME/REGISTRY_PASSWORD secrets. Result: every
image push fails at kaniko's push-permission check (measured: 2482 and
2488 build-gateway 'error checking push permissions'; the same auth gap
is documented in ci.yml's step-level pi install comment re ci-base).

Rewire all six references to the REGISTRY_* secrets that exist. If those
credentials are valid, next push pipelines go fully green behind the new
verify gate; if not, the failure moves to an explicit 401 - either way
the ambiguous permission error resolves into a known state.

.woodpecker/ci-image.yml

@@ -22,9 +22,9 @@ steps:
     image: gcr.io/kaniko-project/executor:debug
     environment:
       REGISTRY_USER:
-        from_secret: gitea_username
+        from_secret: REGISTRY_USERNAME
       REGISTRY_PASS:
-        from_secret: gitea_password
+        from_secret: REGISTRY_PASSWORD
       CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
       CI_COMMIT_TAG: ${CI_COMMIT_TAG}
       CI_COMMIT_SHA: ${CI_COMMIT_SHA}

.woodpecker/ci.yml

@@ -30,6 +30,19 @@ steps:
       # the baked pnpm store.
       - pnpm install --frozen-lockfile --prefer-offline
 
+  # ---------------------------------------------------------------------------
+  # The steps below (sanitization, upgrade-guard, typecheck, lint, format,
+  # test) are the COMPLETE mandatory verification set. SDLC-D-034 mirrors them
+  # one-for-one in the canonical terminal verification command — root
+  # `pnpm verify:release` (scripts/verify-release.mjs) — which the publish
+  # pipeline (.woodpecker/publish.yml `verify` step) runs before ANY publish
+  # effect. These lines stay direct (not routed through the runner) because the
+  # #1017 test-enumeration guard audits framework tool paths through THIS
+  # surface; scripts/verify-release.test.mjs enforces that the runner's stage
+  # table keeps matching these commands exactly, so the two cannot drift.
+  # ---------------------------------------------------------------------------
+
+  # Canonical verify:release stage `sanitization`.
   # Blocking gate: public framework package must contain no operator-specific
   # personal data or private $HOME defaults. Runs early (no node_modules needed).
   sanitization:
@@ -47,6 +60,7 @@ steps:
       # with everything it guards; this direct line keeps one instrument running.
       - bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh
 
+  # 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
   # survives a keep-mode reseed byte-identical (with rsync present AND absent —
@@ -68,6 +82,8 @@ steps:
       - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh
       - bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
 
+  # Canonical verify:release stage `typecheck` — the same `pnpm typecheck`
+  # invocation (which runs the checkout preflight first, then turbo).
   typecheck:
     image: *node_image
     commands:
@@ -78,7 +94,8 @@ steps:
       - sanitization
       - upgrade-guard
 
-  # lint, format, and test are independent — run in parallel after typecheck
+  # lint, format, and test are independent — run in parallel after typecheck.
+  # Each runs exactly its canonical verify:release stage command.
   lint:
     image: *node_image
     commands:
@@ -95,6 +112,12 @@ steps:
     depends_on:
       - typecheck
 
+  # Canonical verify:release stage `test` — the `pnpm test` line below is the
+  # shared command; everything else in this step is PIPELINE-LEVEL
+  # prerequisite the canonical command expects its caller to provide (SDLC-D-034):
+  # the ci-postgres service + pg_isready wait + db:migrate (postgres path),
+  # `apk add openssl`, and the pinned pi install. None of those can move into
+  # the runner (it must also work locally on the PGlite path with no database).
   test:
     image: *node_image
     environment:

.woodpecker/publish.yml

@@ -1,5 +1,19 @@
 # Build, publish npm packages, and push Docker images
 # Runs on main for stable publishes and on next for integration-line prereleases/images
+#
+# SDLC-D-034 publish gate: every publish effect (publish-npm, publish-next-npm,
+# and every image build/push step) depends DIRECTLY on the `verify` step below.
+# `verify` (a) asserts the provider's commit identity matches the actual
+# checkout (CI_COMMIT_SHA == git rev-parse HEAD, fail closed on mismatch or
+# emptiness) and (b) runs the canonical terminal verification command
+# (`pnpm verify:release`), which mirrors the PR CI pipeline's complete
+# mandatory set (sanitization, upgrade-guard, preflight+typecheck, lint,
+# format:check, test, build) — see scripts/verify-release.mjs. A missing,
+# failed, skipped, cancelled, or inconclusive verification therefore skips the
+# dependent publish effects (fail closed). Path-filtered short-circuits may
+# skip publish EFFECTS (e.g. docs-only merges) but never bypass `verify` for a
+# publish that does run: `verify` itself carries no path filter.
+# scripts/verify-release.test.mjs enforces this DAG invariant at checkout time.
 
 variables:
   # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
@@ -48,6 +62,45 @@ steps:
       # Resolve from the baked pnpm store instead of a cold network fetch.
       - pnpm install --frozen-lockfile --prefer-offline
 
+  # SDLC-D-034 exact-commit publish gate. No `when`/path filter on purpose: it
+  # runs for every event this pipeline serves so no publish effect can ever
+  # start without it. Fails closed on commit-identity mismatch (or either SHA
+  # being empty) and on any incomplete verification.
+  verify:
+    image: *node_image
+    commands:
+      - *enable_pnpm
+      # (a) Commit identity: the provider's claimed SHA must equal the actual
+      # checkout HEAD — verification of anything else must never authorize a
+      # publish of this commit.
+      - |
+        if [ -z "$CI_COMMIT_SHA" ]; then
+          echo "[verify] FATAL: CI_COMMIT_SHA is empty — cannot certify commit identity" >&2
+          exit 1
+        fi
+        CHECKOUT_SHA="$(git rev-parse HEAD 2>/dev/null || true)"
+        if [ -z "$CHECKOUT_SHA" ]; then
+          echo "[verify] FATAL: git rev-parse HEAD returned nothing — cannot certify commit identity" >&2
+          exit 1
+        fi
+        if [ "$CI_COMMIT_SHA" != "$CHECKOUT_SHA" ]; then
+          echo "[verify] FATAL: provider commit ($CI_COMMIT_SHA) != checkout HEAD ($CHECKOUT_SHA)" >&2
+          exit 1
+        fi
+        echo "[verify] commit identity confirmed: $CHECKOUT_SHA"
+      # (b) Canonical terminal verification. Caller-provided prerequisites the
+      # runner expects (see .woodpecker/ci.yml comments): bash/rsync for the
+      # guard stages, openssl + the pinned pi binary for the test stage. git is
+      # baked into ci-base but re-asserted here so the identity check above can
+      # never silently depend on a stale baked image. DATABASE_URL is
+      # deliberately NOT set: the canonical command must hold on the PGlite
+      # path too and never sets or requires a database itself.
+      - apk add --no-cache bash rsync openssl git
+      - npm install -g @earendil-works/[email protected]
+      - pnpm verify:release
+    depends_on:
+      - install
+
   build:
     image: *node_image
     commands:
@@ -55,6 +108,7 @@ steps:
       - pnpm build
     depends_on:
       - install
+      - verify
 
   publish-npm:
     image: *node_image
@@ -114,6 +168,7 @@ steps:
         exit 1
     depends_on:
       - build
+      - verify
 
   publish-next-npm:
     image: *node_image
@@ -192,6 +247,7 @@ steps:
         echo "[publish-next] @mosaicstack/mosaic@next resolves to $RESOLVED_VERSION"
     depends_on:
       - build
+      - verify
 
   # TODO: Uncomment when ready to publish to npmjs.org
   # publish-npmjs:
@@ -205,6 +261,7 @@ steps:
   #     - bash scripts/publish-npmjs.sh
   #   depends_on:
   #     - build
+  #     - verify
   #   when:
   #     - event: [tag]
 
@@ -213,9 +270,9 @@ steps:
     when: *image_build_when
     environment:
       REGISTRY_USER:
-        from_secret: gitea_username
+        from_secret: REGISTRY_USERNAME
       REGISTRY_PASS:
-        from_secret: gitea_password
+        from_secret: REGISTRY_PASSWORD
       CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
       CI_COMMIT_TAG: ${CI_COMMIT_TAG}
       CI_COMMIT_SHA: ${CI_COMMIT_SHA}
@@ -242,15 +299,16 @@ steps:
         /kaniko/executor --context . --dockerfile docker/gateway.Dockerfile $DESTINATIONS
     depends_on:
       - build
+      - verify
 
   build-appservice:
     image: gcr.io/kaniko-project/executor:debug
     when: *main_image_build_when
     environment:
       REGISTRY_USER:
-        from_secret: gitea_username
+        from_secret: REGISTRY_USERNAME
       REGISTRY_PASS:
-        from_secret: gitea_password
+        from_secret: REGISTRY_PASSWORD
       CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
       CI_COMMIT_TAG: ${CI_COMMIT_TAG}
       CI_COMMIT_SHA: ${CI_COMMIT_SHA}
@@ -268,15 +326,16 @@ steps:
         /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
     depends_on:
       - build
+      - verify
 
   build-web:
     image: gcr.io/kaniko-project/executor:debug
     when: *main_image_build_when
     environment:
       REGISTRY_USER:
-        from_secret: gitea_username
+        from_secret: REGISTRY_USERNAME
       REGISTRY_PASS:
-        from_secret: gitea_password
+        from_secret: REGISTRY_PASSWORD
       CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
       CI_COMMIT_TAG: ${CI_COMMIT_TAG}
       CI_COMMIT_SHA: ${CI_COMMIT_SHA}
@@ -294,3 +353,4 @@ steps:
         /kaniko/executor --context . --dockerfile docker/web.Dockerfile $DESTINATIONS
     depends_on:
       - build
+      - verify

apps/gateway/src/__tests__/cross-user-isolation.test.ts

@@ -190,7 +190,13 @@ beforeEach((ctx) => {
 });
 
 afterAll(async () => {
-  if (!handle) return;
+  // Cleanup only when the fixture actually installed rows. `handle` is set
+  // before the first query (createDb connects lazily), so on an unreachable
+  // database `handle` is truthy while nothing was inserted — cleanup must
+  // honor `dbAvailable` or the skip path fails the file with ECONNREFUSED in
+  // afterAll (caught live by the publish pipeline's no-DATABASE_URL verify
+  // step, pipeline 2486).
+  if (!handle || !dbAvailable) return;
   const db = handle.db;
 
   // Delete in dependency order (FK constraints)

docs/PRD.md

@@ -1368,3 +1368,38 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
 10. ASSUMPTION: **Conversations and messages get their own PG tables** (not stored in brain's entity model). They follow a chat-specific schema with proper foreign keys to users and projects. Rationale: Chat has different access patterns (streaming, pagination, search) than brain entities.
 
 11. RESOLVED: **Pi handles all target LLM providers natively.** Anthropic, OpenAI/Codex, Z.ai, Ollama, LM Studio, and llama.cpp are all supported via Pi's built-in providers or `models.json` configuration with `openai-completions` API type. No custom provider adapters needed in @mosaicstack/agent — only configuration management.
+
+---
+
+## Release Integrity Workstream (RI, #1275)
+
+### Problem and objective
+
+At `next` 476db12b (review of 2026-08-17), publication from `next` is not bound to the full verification pipeline for the same commit: the publish pipeline's publish steps depend on `build` only, while ordinary push CI excludes `next`. Public Forge/MACP paths contain false-success placeholders: a stub executor that reports `completed` with exit zero, planning/remediation gates that execute literal `true`, a review gate that echoes an approving verdict, and a gate runner that treats empty commands and unimplemented CI-provider gates as passing. Shipping UI surfaces can render a failed fetch as an empty, healthy collection.
+
+Objective: for alpha 0.0.50, the release cannot publish, report, or display work state that the repository has not actually verified. Decisions SDLC-D-033 through SDLC-D-038 (Jason, 2026-08-17) scope this floor; full decision text and required-behavior lists live in jarvis-brain `docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` and `data/decisions/mosaic-stack-sdlc-protocol.json`. This section restates only the normative requirements.
+
+### Normative requirements
+
+1. **RI-N1 Exact-commit publication verification (SDLC-D-034).** One canonical terminal verification command performs self-contained re-verification in the publish pipeline against the job's checked-out commit before any external publication effect. The command contains or invokes the complete mandatory verification set (semantic parity with the PR merge gate, including sanitization, upgrade-guard, typecheck, lint, format check, tests, and build); CI and publication do not maintain separate semantic checklists. Every publish step depends on the verification step in the executable pipeline DAG. Provider commit identity and `git rev-parse HEAD` must identify the same commit. Missing, skipped, cancelled, stale, or inconclusive checks fail closed. Documentation-only runs may skip publication but cannot bypass verification when a publication effect will occur. A negative control must prove that a broken check blocks every publish step.
+
+2. **RI-N2 Fail-closed Forge/MACP with explicit simulation (SDLC-D-035).** Simulation requires explicit caller intent (e.g. `--simulate`) and produces a distinct typed `simulated` state that can never satisfy dependencies, acceptance criteria, gates, merge, or release. Normal execution exits nonzero with a typed capability failure when a required executor, reviewer, command, or CI provider is absent — no stub completion, no literal-`true` gates, no synthetic approvals, no empty-command passes. A manual gate with no automation enters a waiting state; it does not pass. Positive tests prove explicit simulation still works; negative controls prove simulation and every missing-provider case cannot advance lifecycle state.
+
+3. **RI-N3 One transitional PRD authority (SDLC-D-036).** `@mosaicstack/prdy` structured storage under `docs/prdy/`, driven by `mosaic mission --plan`, is the authoritative PRD representation for the alpha. `mosaic prdy` either routes through the same application service or operates only as an explicit, named Markdown import/export adapter; `docs/PRD.md` is not a peer authority. `mission --plan` must persist the mission↔PRD linkage (mission id/version, PRD id/version, selected requirements). Markdown output is a generated view carrying source identity; editing it cannot mutate authority silently. Import is explicit, validated, and conflict-aware (proposed successor, never overwrite). Structural validity is separate from approval.
+
+4. **RI-N4 One quality-rails evaluator (SDLC-D-037).** The TypeScript quality-rails package is the sole authoritative evaluator. A complete probe inventory maps every current TypeScript and shell check to one canonical check with disposition (preserve/strengthen/retire, each named). Effective shell enforcement probes are absorbed before their independent paths retire; expected-file presence alone is not parity. The evaluator returns typed results (`passed`/`failed`/`blocked`/`error`/`not-applicable`) with check version, subject, and reason; missing implementation, missing input, unknown check, process error, timeout, or malformed output can never become `passed` or an unqualified skip. Check definitions and policy are versioned and digested. Shell commands become thin adapters with no separate verdict logic. The canonical terminal verification command (RI-N1) invokes this evaluator rather than duplicating its logic. Contract, parity, and negative-control tests are required, plus independent review of probe equivalence.
+
+5. **RI-N5 Consequence-aware stale UI (SDLC-D-038).** Mission Control distinguishes typed freshness states (`current`, `stale`, `partial`, `unknown`, `unavailable`) rather than inferring from empty arrays or null. A failed fetch never renders as an empty healthy collection. Last-known data may display for situational awareness only with source identity, version, and age visibly labeled; any derived completion/assurance/release verdict whose inputs are stale becomes `unknown`; all state-changing actions are disabled until fresh state loads and is revalidated. With no verified snapshot, surfaces show an explicit unavailable state. Cache corruption, cross-workspace data, schema mismatch, and version regression invalidate the snapshot. Tests cover the failure matrix (network, auth, malformed, partial, corruption, stale age, schema mismatch, recovery, stale-action rejection) with negative controls proving no case yields a current green verdict or enabled mutation.
+
+### Acceptance criteria
+
+- AC-RI-1: A push to `next` that fails any mandatory verification step publishes nothing (no npm package, no image), demonstrated by a checked-in negative control and by pipeline evidence on a real `next` publish run where the verification step is green and every publish step depends on it.
+- AC-RI-2: With no executor/reviewer/CI provider wired, Forge and MACP normal runs exit nonzero with typed capability failures; with `--simulate`, runs complete but every result is typed `simulated` and cannot satisfy any gate, dependency, or completion state — proven by unit tests including negative controls.
+- AC-RI-3: A PRD created or revised through either `mosaic mission --plan` or `mosaic prdy` resolves to one authority under `docs/prdy/` with stable identities and versions; the mission↔PRD linkage survives restart; a Markdown export is labeled as generated and cannot silently become a second writer; divergent legacy content blocks baseline claims until explicitly resolved — proven by contract tests.
+- AC-RI-4: `quality-rails check` through any entry point (TS CLI, framework shell adapter) returns the same typed verdict for the same subject; the probe inventory names every legacy check's disposition; a deliberately broken probe fails closed — proven by contract/parity/negative-control tests and independent review of probe equivalence.
+- AC-RI-5: No shipping surface renders a failed fetch as an empty healthy state; stale/partial/unavailable states are typed, labeled, and mutation-disabled — proven by the failure-matrix tests.
+- AC-RI-6: All cards merged to `next` via squash PR with terminal-green CI; release evidence for 0.0.50 records commit, verification run, and published artifacts.
+
+### Out of scope
+
+The canonical dispatcher/control-plane vertical slice (work graph, execution attempts, fenced leases, typed check-in, independent verifier dispatch) is decided post-alpha (SDLC-D-033, option B). Multi-pipeline verification certificates (SDLC-D-034 option B) are post-alpha. Full AF-1..AF-4 objective matrices and Mission Control portfolio surfaces are post-alpha.

docs/release-integrity/TASKS.md

@@ -0,0 +1,42 @@
+# Tasks — Release Integrity Workstream (RI-050, #1275)
+
+> Single-writer: the RI-050 orchestrator (jarvis, dragon-lin) only. Workers read but never modify.
+>
+> **Mission:** alpha 0.0.50 release-integrity floor (decisions SDLC-D-033..038).
+> **PRD:** [docs/PRD.md § Release Integrity Workstream](../PRD.md#release-integrity-workstream-ri-1275)
+> **Issue:** #1275 (remains open until RI-V-001 closes)
+> **Base branch:** `next` (all cards branch from `origin/next`, squash-merge via PR)
+>
+> **Execution note:** the `agent` column uses `pi-glm-5.3` — outside the pipeline-cron model
+> table on purpose. This workstream is executed by jarvis on dragon-lin with local pi workers
+> (`pi --model zai/glm-5.3:high`); pipeline crons must not auto-claim these rows.
+>
+> **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa`
+> `done` requires: repo quality gates green, independent review recorded, terminal-green CI on
+> the PR head, squash merge to `next`, and acceptance evidence in notes.
+
+| id       | status      | description                                                                                                                                                                                                                                                                      | issue | agent      | repo              | branch                            | depends_on                                                 | estimate | notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---------- | ----------------- | --------------------------------- | ---------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| RI-0-001 | in-progress | Bootstrap: issue #1275, PRD section, this DAG, scratchpad (docs only)                                                                                                                                                                                                            | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-mission-bootstrap     | —                                                          | 6K       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-1-001 | in-progress | RI-N1: canonical terminal verification command + publish-pipeline exact-commit gate (every publish step depends on verify; commit identity check; fail closed)                                                                                                                   | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-publish-gate          | RI-0-001                                                   | 25K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-1-002 | not-started | RI-N1 negative control: checked-in tests proving a broken mandatory check blocks every publish step and that DAG edges cannot be bypassed                                                                                                                                        | #1275 | pi-glm-5.3 | mosaicstack/stack | test/ri-050-publish-gate-negative | RI-1-001                                                   | 12K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-2-001 | in-progress | RI-N2 (Forge): remove stub-executor false success; `--simulate` typed `simulated` results that satisfy nothing; literal-`true` gates and echo-review replaced with real gates or typed waiting-for-authority                                                                     | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-forge-fail-closed      | RI-0-001                                                   | 20K      | Independent review APPROVED 2026-08-17 (Gitea review 172 on PR #1278, head 99b8f6ea; reviewing seat fargo — recorded under shared host principal mos-dt-0, provenance correction posted by fred; wrapper gap filed by fred). Executed at head: forge tests 116/116, lint green, typecheck green after building macp dist (minimal-install artifact, not a defect), workspace typecheck 45/45, no external type consumers of the changed interfaces. CI red = known lane-wide fleet-test failure only, carries no information about this change (fred, log-content analysis, pipelines 2456-2458). Non-blocking finding: README L141-143 + skills/mosaic-forge/SKILL.md document bare forge run/resume, which now fails closed — fast-follow docs touch. Merge queued behind #1270. |
+| RI-2-002 | in-progress | RI-N2 (MACP): gate runner fails closed on empty commands, stub executors, and unimplemented CI-provider gates unless explicit simulate; typed capability failures                                                                                                                | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-macp-fail-closed       | RI-0-001                                                   | 15K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-3-001 | not-started | RI-N4: complete probe inventory mapping every TS and shell quality-rail check to one canonical check with disposition (preserve/strengthen/retire, each named)                                                                                                                   | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-qr-probe-inventory    | RI-0-001                                                   | 12K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-3-002 | not-started | RI-N4: TS evaluator absorbs effective shell probes; typed results (passed/failed/blocked/error/not-applicable) with versioned digested check definitions; shell commands become thin adapters; contract/parity/negative-control tests                                            | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-qr-evaluator          | RI-3-001                                                   | 30K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-4-001 | in-progress | RI-N3: one PRD application service — `mission --plan` persists mission↔PRD linkage (ids/versions/selected requirements); `mosaic prdy` routes through the service or becomes a named import/export adapter; Markdown is a labeled generated view; explicit conflict-aware import | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-prd-authority         | RI-0-001                                                   | 35K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-5-001 | not-started | RI-N5: typed freshness states (current/stale/partial/unknown/unavailable); no failed-fetch-renders-empty; stale derived verdicts → unknown; mutations disabled when stale; failure-matrix tests                                                                                  | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-web-stale-safety      | RI-0-001                                                   | 25K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RI-V-001 | not-started | Final verification + release evidence: all cards verified merged, negative controls demonstrated, real `next` publish run green on exact commit, evidence pack recorded                                                                                                          | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-release-evidence      | RI-1-002, RI-2-001, RI-2-002, RI-3-002, RI-4-001, RI-5-001 | 10K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
+## Dispatch waves (max 2 parallel workers)
+
+1. RI-1-001 + RI-2-001
+2. RI-2-002 + RI-4-001
+3. RI-3-001 + RI-5-001
+4. RI-1-002 + RI-3-002
+5. RI-V-001
+
+## Budget
+
+Derived soft cap: 250K tokens (no explicit cap given). Projected total: 190K.
+Conservative mode (1 worker) above 70% projected; freeze above 90%.

docs/scratchpads/ri-050.md

@@ -0,0 +1,242 @@
+# Scratchpad — RI-050 orchestrator (jarvis, dragon-lin)
+
+Mission: alpha 0.0.50 release-integrity floor. Issue #1275. Base `next` @ 476db12b.
+Design SSOT: jarvis-brain `docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` (SDLC-D-033..038).
+
+## Mode (Jason's directives)
+
+- Orchestrator: jarvis (this session, dragon-lin). NOT mos-claude; work stays on this host.
+- Workers: local pi headless — `pi --model zai/glm-5.3:high -p` in the card's worktree, tools read,bash,edit,write.
+- Delegation override of stack AGENTS.md `agent` column: rows carry `pi-glm-5.3` (outside cron table so no auto-claim).
+- Target branch: `next`. Cards branch from `origin/next`, squash-merge via PR.
+
+## Operational constraints (measured this session)
+
+- Main checkout at `/home/jwoltje/src/mosaic-stack` is a dirty diverged `main` (ahead 1139/behind 711) — NEVER touched. All work in `/home/jwoltje/src/mosaic-stack-worktrees/<branch>`.
+- Disk: /home 187G free. /tmp only 8.7G — keep pnpm stores/node_modules under /home.
+- `main` and `next` have DIVERGED; PRs target `next`.
+- Identity: pin `GITEA_LOGIN=mosaicstack-jarvis` for all wrapper ops. Issue #1275 verified authored by @jarvis.
+- `ci-queue-wait.sh` on this host is fail-open (board: fix #1032 not installed) — substitute SHA-status checks via `/commits/{sha}/status` and diff failing step names.
+- CI on PRs runs `pull_request` pipelines (any branch) incl. ci-postgres service. Push CI runs on main only; publish runs on push/tag to next + manual.
+- Wrapper gaps on this host per board (7 gaps; e.g. no pr-review-list, issue-assign broken, pr-merge makes no trailers): verify outcomes by reading back provider state, never trust rc alone.
+- Publish pipeline currently: install → build → publish-npm/publish-next-npm (+image). No verify. CI steps: install, sanitization, upgrade-guard, typecheck, lint, format, test, ci-postgres.
+
+## Budget
+
+Soft cap 250K. Projected 190K across 10 cards. Track per-card used vs estimate in TASKS.md notes.
+
+## Progress log
+
+- 2026-08-16 23:52 — Issue #1275 created (@jarvis verified).
+- 2026-08-16 23:5x — Bootstrap branch `docs/ri-050-mission-bootstrap` from origin/next@476db12b; PRD section + TASKS.md + this scratchpad written. RI-0-001 in-progress.
+
+## Wave 1 dispatched (2026-08-17 00:35)
+
+- RI-1-001 worker: pi glm-5.3:high, pid 2322125, worktree ri-1-001, log /var/tmp/ri-050/ri-1-001-run.log
+- RI-2-001 worker: pi glm-5.3:high, pid 2322126, worktree ri-2-001, log /var/tmp/ri-050/ri-2-001-run.log
+- Gotcha recorded: pi has no -f flag (that's pi-do.sh); pass brief as positional message. First launch died "Unknown option: -f" — relaunched.
+- CI lane: PR #1276 (bootstrap) fails `test` at base like every next PR — fred's green #1270 unblocks (comms sent 2026-08-17T05:21Z, `comms/20260817T052148Z__from-jarvis__650fe8.md`). Merge gate for all RI PRs queues behind #1270.
+- Live RI-N1 evidence posted to #1275 (comment 22915): pipeline 2439 publish-next-npm SUCCESS beside build-gateway FAILURE.
+
+---
+
+# HANDOFF — RI-050 continuation (written 2026-08-17 ~08:45 UTC, jarvis/dragon-lin)
+
+You are taking over the alpha 0.0.50 release-integrity workstream in place. Everything you
+need is on the remote. Read this whole file, then `docs/release-integrity/TASKS.md` (same
+branch), then the PRD section (`docs/PRD.md` § Release Integrity Workstream, same branch).
+
+## Identity / mode
+
+- Orchestrator identity: `jarvis` (dragon-lin). You continue as the RI-050 orchestrator under
+  whatever identity Jason gives you — if you are NOT jarvis, say so in comms and PR bodies.
+- Jason's standing directives for this mission: work happens on THIS repo (mosaicstack/stack),
+  PRs target `next` (NOT main), workers are local pi headless sessions on
+  `zai/glm-5.3:high`. Do not hand this to mos-claude. Do not borrow other seats' lanes.
+- All wrapper ops: pin `GITEA_LOGIN=mosaicstack-jarvis` (issue #1275 was verified authored by
+  @jarvis; keep identity consistent or verify yours with issue-view and READ BACK user.login).
+- CI substitution rule (this host's ci-queue-wait.sh is fail-open; fix #1032 not installed):
+  judge CI by SHA-status via `/api/v1/repos/mosaicstack/stack/commits/{sha}/status` or the
+  woodpecker API (`pipeline-status.sh -r mosaicstack/stack -n N -f json`), and DIFF THE
+  FAILING STEP NAMES rather than trusting rc.
+
+## Mission state at handoff
+
+Mission: alpha 0.0.50 release-integrity floor. Issue #1275 (open, has live-evidence comment).
+Decisions SDLC-D-033..038 live in jarvis-brain
+`docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` (normative text also mirrored in the
+PRD section on this branch, so this repo is self-sufficient).
+
+Base: `origin/next` @ 476db12b. NOTE: `main` and `next` have DIVERGED — never base on main.
+
+Branches (all pushed, all clean trees):
+
+- `docs/ri-050-mission-bootstrap` @ 5114faa2 → PR #1276 (open, mergeable) — bootstrap docs +
+  this scratchpad + TASKS.md DAG. STATUS: CI red on `test` only, which is the known lane-wide
+  failure (see blocker below); own prettier issue already fixed.
+- `feat/ri-050-publish-gate` @ 0aa5ed35 → PR #1277 (open, mergeable) — RI-1-001 COMPLETE
+  (worker reported success, orchestrator review PASSED: verify step asserts CI_COMMIT_SHA ==
+  git rev-parse HEAD then runs canonical `pnpm verify:release`; every publish/image step
+  depends_on verify directly, confirmed by parsing the DAG: publish-npm, publish-next-npm,
+  build-gateway/appservice/web all -> [build, verify]; invariant test
+  scripts/verify-release.test.mjs passes 7/7 locally with negative fixtures). CI: same known
+  lane-red `test` step only.
+- `fix/ri-050-forge-fail-closed` @ 99b8f6ea → PR #1278 (open, mergeable) — RI-2-001 worker
+  reported success (typed `FORGE_*` capability errors, --simulate typed simulated everywhere,
+  vacuous true/echo gates replaced, closed ForgeOutcome set, 116 tests green incl. 16 new).
+  ORCHESTRATOR REVIEW NOT YET DONE — your first job. Review the diff
+  (1391 insertions across forge src), check the fail-closed paths and that simulated
+  results cannot satisfy any consumer, run `pnpm --filter @mosaicstack/forge test`.
+
+## The one blocker
+
+Every `next` PR pipeline is red on ONE assertion:
+`packages/mosaic/framework/tools/fleet/test-start-agent-session.sh:103` ("host provides 'pi'
+in the system path"). Pre-existing at base; affects PRs #1276/#1277/#1278 identically.
+fred's PR #1270 ("unblocks every PR on next") is green and open — it is HIS to merge; do not
+merge it yourself. jarvis sent comms (`comms/20260817T052148Z__from-jarvis__650fe8.md` in
+jarvis-brain) asking merge timing; no reply yet as of handoff. Merge gates for ALL RI PRs
+queue behind #1270 landing. Until then: review/develop freely, merge nothing that needs the
+green gate (docs-only #1276 arguably could merge red-lane with Jason's explicit call — ask,
+don't assume).
+
+## Remaining DAG (docs/release-integrity/TASKS.md is canonical)
+
+Wave 2 (next): RI-2-002 MACP fail-closed (brief pattern: mirror RI-2-001 for
+packages/macp/src/gate-runner.ts — empty commands, stub executors, unimplemented CI-provider
+gates fail closed; explicit simulate) and RI-4-001 PRD authority (one PRD service;
+@mosaicstack/prdy docs/prdy authoritative via `mosaic mission --plan`; `mosaic prdy` routes
+or becomes named Markdown adapter; mission<->PRD linkage persists — see PRD RI-N3).
+Wave 3: RI-3-001 probe inventory (docs), RI-5-001 web stale-safety.
+Wave 4: RI-1-002 negative-control tests, RI-3-002 TS evaluator absorbs shell probes.
+Final: RI-V-001 evidence pack (real green next publish run post-gate + all cards verified).
+
+## Worker mechanics (measured, reuse)
+
+- Dispatch: create worktree `git -C /home/jwoltje/src/mosaic-stack worktree add
+/home/jwoltje/src/mosaic-stack-worktrees/<id> -b <branch> origin/next`, write a brief to
+  /var/tmp/ri-050/, then run from INSIDE the worktree:
+  `pi -p --no-session --model zai/glm-5.3:high --tools read,bash,edit,write "$(cat brief.md)"`
+  (pi has NO -f flag — pass the brief as a positional message; first dispatch died on that).
+- Briefs for 1-001/2-001 are at /var/tmp/ri-050/ on dragon-lin (may not survive; the
+  pattern is fully described above and in TASKS.md).
+- Briefs must carry: worktree path, branch, base, requirements, known base-red list (so the
+  worker doesn't chase it), gates to run, PR creation command with GITEA_LOGIN pin, "do NOT
+  merge, do NOT touch docs/TASKS.md", and the JSON report format.
+- Verify worker claims: read the PR, run their tests yourself, parse pipeline step names.
+
+## Do-not-touch
+
+- Main checkout at /home/jwoltje/src/mosaic-stack (dirty diverged main) — never touch.
+- fred's open PRs (#1270 and others) — review evidence welcome, merging his is not yours.
+- Other RI PRs' authors' lanes: #1277/#1278 are yours to gate and merge ONCE lane is green
+  and review is recorded.
+- Never `--no-verify`; never bypass the wrapper-fails-closed rule (wrapper failure ⇒
+  `blocked + report exact command + stop`).
+
+## Session-restore command sequence
+
+1. `git -C /home/jwoltje/src/mosaic-stack-worktrees/ri-050 fetch origin --prune`
+2. Read this file + `docs/release-integrity/TASKS.md` + PRD section.
+3. Check PR states (#1270, #1276, #1277, #1278) and lane CI (SHA-status per above).
+4. Review RI-2-001 (PR #1278) if not yet done; then dispatch wave 2.
+
+— jarvis, 2026-08-17
+
+---
+
+# CONTINUATION — fargo (sb-it-1-dt)
+
+Orchestrator seat is now **fargo** on sb-it-1-dt (Jason, 2026-08-17): Claude seat, worktree discipline
+per fred's ruling (`~/agent-work/<slug>`, create → work → commit → push → remove as one act; the
+helper's `/src` refusal is a web1 convention, does not bind here). fred supports; lane rulings are
+his. Workers remain local pi `zai/glm-5.3:high` + limited Claude per Jason.
+
+## 2026-08-17 — RI-2-001 independent review DONE
+
+- **PR #1278 APPROVED** (Gitea review 172, pinned to head 99b8f6ea). Executed evidence, not read-only:
+  forge suite 116/116 at head (matches PR claim), forge lint green, forge typecheck green after
+  building `@mosaicstack/macp` dist (TS2307 on bare `pnpm install --frozen-lockfile` is a
+  minimal-install build-order artifact — the macp import is type-only, vitest passes unbuilt; CI
+  installs build workspace deps, hence green there), **workspace typecheck 45/45 at head**,
+  consumer sweep: no external type consumers of RunManifest/StageStatus/ForgeTaskResult/
+  TaskExecutor; only importer of the package is packages/mosaic via registerForgeCommand
+  (smoke test asserts registration/help only — cannot break). Digest gate (shaggy's) before==after
+  with both-arm reactivity controls.
+- CI red on #1276/#1277/#1278: lane-wide `test` failure only
+  (test-start-agent-session.sh:103, fred's guard mis-wired; #1270 unwires it). Fred measured log
+  content: one real byte-identical failure per pipeline (2456/2457/2458); 13 of ~14 `FAIL` grep
+  hits are passing fail-loud test NAMES. **The red carries no information about the RI changes.**
+- Non-blocking finding: README L141-143 + skills/mosaic-forge/SKILL.md document bare
+  `mosaic forge run`/`resume`, which now exits 1 FORGE_NO_EXECUTOR — fast-follow docs touch.
+- **Identity incident, ruled on by fred:** review 172 recorded under shared host principal
+  mos-dt-0, not fargo. Mechanism (measured, wrapper source): pr-review.sh resolves its acting login
+  from the tea login list only; no fargo tea login on this host → silent host-default fallback;
+  MOSAIC_GIT_IDENTITY is only read in detect-platform.sh get_gitea_token's fallback arm, never
+  reached. Exact-id read-back verifies against the writing token, so it passed while attribution
+  was wrong — durable-provenance machinery proves the write, not the seat. Fred's ruling: review
+  172 stands (substance/verdict/pin correct; label wrong); NO re-approval (one approval,
+  annotated, is the stronger record); fred posts the provenance correction under @fred with
+  --login fred-ms (hard-fail path); no fargo tea login ever (freeze + Jason's to authorize);
+  tooling gap filed by fred. Also explains (does not reopen) #1228's mos-dt-0 attribution.
+- Merge gate: all RI PRs queue behind fred's green #1270 (Jason's call).
+
+## Next
+
+1. Wave 2 dispatch: RI-2-002 (MACP fail-closed, mirror RI-2-001 pattern for
+   packages/macp/src/gate-runner.ts) + RI-4-001 (PRD authority). Two parallel workers max.
+2. Docs fast-follow (README + mosaic-forge skill) — fold into #1276 or a tiny docs card.
+3. RI-V-001 evidence at the end.
+
+— fargo, 2026-08-17
+
+---
+
+# RESUMPTION + DAILY-HANDOFF PROTOCOL (Jason, 2026-08-17)
+
+Orchestrator seat is back with **jarvis** (dragon-lin). Expect daily handoff between jarvis
+and fargo. Protocol (both seats, every handoff):
+
+1. **This file is the shared mission log.** Append a dated section per session: state
+   measured, actions taken, PR/review states, next actions. Never rewrite prior sections.
+2. **TASKS.md stays current within one session** — status, PR number in notes, review
+   evidence. Stale rows are handoff debt.
+3. **Cross-review rule (SDLC-D-011 in practice):** the reviewing seat must differ from the
+   producing seat. jarvis reviews fargo-dispatched PRs, fargo reviews jarvis-dispatched
+   PRs. Producers are always pi workers; dispatching seats verify before push; the other
+   seat records the Gitea review.
+4. Handoff = append here + push + (optional) issue #1275 comment if a decision changed.
+
+## RESUMED — jarvis/dragon-lin, 2026-08-17 (afternoon)
+
+- Measured: next = 8199261c (#1270 merged — lane unblocked for new PRs). #1293/#1294
+  (fargo, wave 2) CI-green, mergeable, no recorded reviews. #1276/#1277/#1278 still based
+  on 476db12b with stale red CI → need rebase onto 8199261c. #1278 review pinned to old
+  head 99b8f6ea by @mos-dt-0 (fargo's, mis-attributed per his note) — rebase will dismiss
+  it; re-approval must come from fargo/fred (author is @jarvis, cannot self-approve).
+- Live evidence #2: push pipeline 2462 (the #1270 merge itself) ran publish-next-npm
+  SUCCESS beside build-gateway FAILURE again.
+- Plan: rebase the three original branches; independently review #1293/#1294; merge order
+  once green+reviewed: #1276 (docs) → #1277 (publish gate) → #1278/#1293/#1294 (code).
+  After #1277 merges, watch the next push pipeline prove the verify gate live.
+- fargo's non-RI PRs (#1291/#1296/#1297/#1281) stay strictly his lane.
+
+## jarvis session 2026-08-17 (evening) — reviews, rebases, merge plan
+
+- Rebased #1276/#1277/#1278 onto 8199261c (heads 59e2c460 / 46784c8d / 4917df1f);
+  invariant tests 7/7 and forge 116/116 re-run green at new heads. #1270 touched
+  test-enumeration-exclusions.txt + package.json, NOT ci.yml — no semantic overlap with
+  #1277's ci.yml changes (checked, was a real concern).
+- Independent reviews recorded: #1293 APPROVED (review 173; macp 109/109; fail-closed paths
+  + aggregate state machine verified), #1294 APPROVED (review 174; prdy 20/20 + command
+  specs 9/9; single-writer + linkage persistence + labeled export + conflict-aware import
+  verified). Note: 19 unrelated mosaic suites fail on bare minimal install (known workspace
+  build-order artifact, documented by fargo) — not this change.
+- Measured: `next` has NO branch protection (API: only main listed). Cross-seat review
+  discipline is protocol-enforced, not Gitea-enforced. Flagged to fargo for Jason: direct
+  pushes to next trigger ungated publishes; protection is Jason's call (#1231 adjacent).
+- Merge order planned: #1276 (docs-only — no publish run) -> #1277 (first gated publish)
+  -> #1278 -> #1293 -> #1294. Sent fargo review requests with pinned head SHAs
+  (comms/20260818T011932Z__from-jarvis__a9c02b.md). Not merging #1293/#1294 before my three
+  clear fargo's review — order optimality beats speed; every pre-#1277 merge publishes ungated.
+- CI on the three rebased heads: pending at time of this entry.

package.json

@@ -9,6 +9,7 @@
     "preflight": "node scripts/preflight.mjs",
     "clean:generated": "node scripts/clean-generated.mjs",
     "typecheck": "pnpm preflight && turbo run typecheck",
+    "verify:release": "node scripts/verify-release.mjs",
     "test:checkout": "node --test scripts/*.test.mjs",
     "test": "pnpm test:checkout && turbo run test && pnpm run test:installer",
     "test:installer": "bash tools/install-next-lane.test.sh",

packages/mosaic/__tests__/platform/detect.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// homedir/platform are read at call time, so they can be stubbed per case.
+vi.mock('node:os', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:os')>();
+  return {
+    ...actual,
+    homedir: () => '/home/tester',
+    platform: () => mockPlatform,
+  };
+});
+
+let mockPlatform: NodeJS.Platform = 'linux';
+
+const { getShellProfilePath, detectShell } = await import('../../src/platform/detect.js');
+
+describe('getShellProfilePath', () => {
+  const originalShell = process.env['SHELL'];
+  const originalZdotdir = process.env['ZDOTDIR'];
+
+  beforeEach(() => {
+    mockPlatform = 'linux';
+    delete process.env['ZDOTDIR'];
+  });
+
+  afterEach(() => {
+    if (originalShell === undefined) delete process.env['SHELL'];
+    else process.env['SHELL'] = originalShell;
+    if (originalZdotdir === undefined) delete process.env['ZDOTDIR'];
+    else process.env['ZDOTDIR'] = originalZdotdir;
+  });
+
+  // The regression this guards: setupPath() in stages/finalize.ts appends the
+  // PATH export to whatever this returns. A line written to ~/.bashrc is
+  // unreachable to `bash -lc`, systemd units and agent seats, because Debian's
+  // default .bashrc returns early for non-interactive shells — so an install
+  // reported success and left `mosaic: command not found`. Same for .zshrc,
+  // which zsh only reads for interactive shells.
+  it('never targets an interactive-only rc file', () => {
+    for (const shell of ['/bin/bash', '/usr/bin/zsh']) {
+      process.env['SHELL'] = shell;
+      const profile = getShellProfilePath();
+      expect(profile).not.toMatch(/\.bashrc$/);
+      expect(profile).not.toMatch(/\.zshrc$/);
+    }
+  });
+
+  it('uses ~/.profile for bash', () => {
+    process.env['SHELL'] = '/bin/bash';
+    expect(getShellProfilePath()).toBe('/home/tester/.profile');
+  });
+
+  it('uses ~/.zshenv for zsh', () => {
+    process.env['SHELL'] = '/usr/bin/zsh';
+    expect(getShellProfilePath()).toBe('/home/tester/.zshenv');
+  });
+
+  it('honours ZDOTDIR for zsh', () => {
+    process.env['SHELL'] = '/usr/bin/zsh';
+    process.env['ZDOTDIR'] = '/custom/zdot';
+    expect(getShellProfilePath()).toBe('/custom/zdot/.zshenv');
+  });
+
+  it('falls back to ~/.profile for an unknown shell', () => {
+    process.env['SHELL'] = '/bin/somethingelse';
+    expect(detectShell()).toBe('unknown');
+    expect(getShellProfilePath()).toBe('/home/tester/.profile');
+  });
+
+  it('still routes fish to its own config', () => {
+    process.env['SHELL'] = '/usr/bin/fish';
+    expect(getShellProfilePath()).toBe('/home/tester/.config/fish/config.fish');
+  });
+});

packages/mosaic/framework/defaults/AGENTS.md

@@ -82,7 +82,6 @@ is re-seeded a genuinely missing core file is a stop-and-report condition — no
 
 Confirm: required + situational tests passed (primary gate); aligned to `docs/PRD.md`; acceptance
 criteria mapped to evidence; independent code review passed (if code changed); required docs updated;
-scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on the integration
+scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on `main`, terminal-green
-trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), terminal-green
 CI, linked issue closed (or `docs/TASKS.md` equivalent). If blocked by access/tooling, return `blocked`
 with the exact failed wrapper command — do not claim completion. Full checklist: `guides/E2E-DELIVERY.md`.

packages/mosaic/framework/defaults/CONSTITUTION.md

@@ -21,23 +21,11 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse
 
 ## Hard Gates
 
-The **integration trunk** is the branch a project designates in its root `AGENTS.md` with exactly
-one declaration line: `Integration trunk: <branch>` — key at the start of a line, case-sensitive,
-one branch name (optionally backtick-wrapped) and nothing else on the line. Absent a declaration,
-the trunk is `main`. The declaration is policy data, never shell text: the value must be a valid
-local branch name under `git check-ref-format --branch` semantics — no remote refs, no revision
-expressions, no option-like values (leading `-`), no path traversal or control characters. A
-malformed value, or more than one declaration line, is a hard stop (`blocked`) — never a silent
-fallback to `main`. Ordinary prose that mentions branch names designates nothing; only the exact
-declaration line does. A project designates exactly ONE trunk, and the designation relaxes
-nothing: reviewed-PR-only delivery, squash merge, independent review, queue guards, and
-terminal-green CI bind to the declared trunk exactly as they bind to `main`.
-
 1. Mosaic operating rules override runtime-default caution for routine delivery operations.
 2. Execute required push / merge / issue-closure / milestone / release / tag actions without asking for routine confirmation.
 3. Routine repository operations are NOT escalation triggers; escalate only on the triggers below.
 4. For source-code delivery, completion is forbidden at the PR-open stage.
-5. Completion requires a merged PR to the integration trunk + terminal-green CI + the linked issue/task closed.
+5. Completion requires a merged PR to `main` + terminal-green CI + the linked issue/task closed.
 6. Before any push or merge, run the CI queue guard.
 7. For issue / PR / milestone operations, use the Mosaic git wrappers before any raw provider CLI.
 8. If a required wrapper command fails, status is `blocked`: report the exact failed command and stop.
@@ -47,7 +35,7 @@ terminal-green CI bind to the declared trunk exactly as they bind to `main`.
 12. The intake procedure is not conditional on perceived complexity; a "simple" task carries the same requirements as a multi-file feature.
 13. **Merge authority (coordinated work):** when a coordinator/orchestrator session is active for the work, the post-review merge go-ahead is the coordinator's to give — once the required review gates pass, merge on the coordinator's confirmation; do not wait on the human owner personally. Solo (uncoordinated) delivery keeps the default: merge per gates 2 and 9. A "No self-merge" note on a PR means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges.
 14. Never hardcode secrets; never emit credential values in any output (not even partially, not "to confirm").
-15. Trunk-based git only: branch from the integration trunk, merge via a reviewed PR (squash), never push directly to the trunk.
+15. Trunk-based git only: branch from `main`, merge via a reviewed PR (squash), never push directly to `main`.
 16. If you modify source code, an independent review (author ≠ reviewer) must pass before completion.
 
 ## Integrity (quality gates are never bypassed)

packages/mosaic/framework/fleet/README.md

@@ -12,6 +12,33 @@ The default tmux socket is `mosaic-fleet` so fleet commands do not touch the
 default tmux server. The roster is the desired-state authority; generated environment files are
 rebuildable projections, never a second source of configuration.
 
+## Brain-home split (fleet state vs framework templates)
+
+When a mosaic-brain clone is present, fleet **state** resolves from the brain
+home while framework templates and dispatch state stay in the config home
+(three-tree model, canon `docs/STRUCTURE-CANON.md` §2):
+
+| Path                                                                            | Without brain (legacy)                | With brain                     |
+| ------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------ |
+| `fleet/agents/<seat>.env.*`                                                     | `~/.config/mosaic/fleet/agents/`      | `~/.mosaic/fleet/agents/`      |
+| `fleet/roles.local/` (overrides)                                                | `~/.config/mosaic/fleet/roles.local/` | `~/.mosaic/fleet/roles.local/` |
+| `fleet/profiles/` (working copies)                                              | `~/.config/mosaic/fleet/profiles/`    | `~/.mosaic/fleet/profiles/`    |
+| `fleet/roster.yaml`, `fleet/roles/` (baseline), `fleet/run/`, `fleet/services/` | `~/.config/mosaic/fleet/…`            | unchanged (config home)        |
+
+Activation (`packages/mosaic/src/fleet/brain-home.ts`, mirrored in
+`tools/fleet/start-agent-session.sh`):
+
+1. `MOSAIC_BRAIN_HOME` env var — explicit, always wins.
+2. Canonical `~/.mosaic` — adopted only when `MOSAIC_HOME` is the default
+   `~/.config/mosaic` AND `~/.mosaic/fleet/agents` exists. Custom
+   `--mosaic-home` values (tests, sandboxes, canaries) never adopt, keeping
+   them hermetic.
+3. Otherwise the config home (legacy single-tree behavior).
+
+Seat env dirs under a brain are subject to the same privacy boundary (0700
+dirs, 0600 files); `.env.generated` files are structure-valuable and tracked
+in the brain repo, hand-maintained `.env`/`.env.local` stay ignored and private.
+
 ## Examples
 
 - `examples/minimal.yaml` starts one local canary slot.

packages/mosaic/framework/guides/BOOTSTRAP.md

@@ -12,7 +12,7 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
 4. Issue tracking is consistent across projects
 5. Documentation standards and API contracts are enforced from day one
 6. PRD requirements are established before coding begins
-7. Branching/merging is consistent: branch -> integration trunk (default `main`) via PR with squash-only merges
+7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges
 8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention
 
 ## Agent Host Prerequisites
@@ -206,7 +206,7 @@ Every runtime context file should contain:
 6. **Issue tracking** — Issue and commit conventions
 7. **Code review** — Required review process
 8. **Runtime notes** — Runtime-specific behavior references
-9. **Branch and merge policy** — Trunk workflow (branch -> integration trunk via PR, squash-only)
+9. **Branch and merge policy** — Trunk workflow (`branch -> main` via PR, squash-only)
 10. **Autonomy and escalation policy** — Agent owns coding/review/PR/release/deploy lifecycle
 
 ---
@@ -288,16 +288,15 @@ Reserve `0.1.0` for the MVP release milestone.
 
 ---
 
-## Step 5b: Configure Trunk Branch Protection (Hard Rule)
+## Step 5b: Configure Main Branch Protection (Hard Rule)
 
-Apply equivalent settings in Gitea, GitHub, or GitLab, targeting the project's integration trunk
+Apply equivalent settings in Gitea, GitHub, or GitLab:
-(the branch its root `AGENTS.md` declares; default `main` — see `CONSTITUTION.md` Hard Gates):
 
-1. Protect the integration trunk from direct pushes.
+1. Protect `main` from direct pushes.
-2. Require pull requests to merge into the integration trunk.
+2. Require pull requests to merge into `main`.
 3. Require required CI/status checks to pass before merge.
 4. Require code review approval before merge.
-5. Allow **squash merge only** for PRs into the integration trunk (disable merge commits and rebase merges for it).
+5. Allow **squash merge only** for PRs into `main` (disable merge commits and rebase merges for `main`).
 
 This enforces one merge strategy across human and agent workflows.
 
@@ -514,9 +513,9 @@ After bootstrapping, verify:
 - [ ] Git labels created (epic, feature, bug, task, etc.)
 - [ ] Initial pre-MVP milestone created (0.0.1)
 - [ ] MVP milestone reserved for release (0.1.0)
-- [ ] The integration trunk is protected from direct pushes
+- [ ] `main` is protected from direct pushes
-- [ ] PRs into the integration trunk are required
+- [ ] PRs into `main` are required
-- [ ] Merge method for the integration trunk is squash-only
+- [ ] Merge method for `main` is squash-only
 - [ ] Quality gates run successfully
 - [ ] `.env.example` exists (if project uses env vars)
 - [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)

packages/mosaic/framework/guides/CI-CD-PIPELINES.md

@@ -4,11 +4,6 @@
 
 ## Overview
 
-> **Integration trunk:** the YAML examples in this guide use the default integration trunk `main`
-> in branch conditions and version rules. A project that declares a different trunk in its root
-> `AGENTS.md` (see `CONSTITUTION.md` Hard Gates) substitutes its declared trunk wherever `main`
-> appears as the trunk branch.
-
 This guide covers the canonical CI/CD pattern used across projects. The pipeline runs in Woodpecker CI and follows this flow:
 
 ```
@@ -870,7 +865,7 @@ steps:
    ```yaml
    image: git.example.com/org/service@${IMAGE_DIGEST}
    ```
-7. **Test on a short-lived non-trunk branch first** — open a PR and verify quality gates before merging to the integration trunk
+7. **Test on a short-lived non-main branch first** — open a PR and verify quality gates before merging to `main`
 8. **Verify images appear** in Gitea Packages tab after successful pipeline
 
 ## Terminal-Green Full-Step Contract
@@ -911,7 +906,7 @@ For source-code delivery, completion is not allowed at "PR opened" stage.
 
 Required sequence:
 
-1. Merge PR to the integration trunk (squash) via Mosaic wrapper.
+1. Merge PR to `main` (squash) via Mosaic wrapper.
 2. Monitor CI to terminal status:
    ```bash
    ~/.config/mosaic/tools/git/pr-ci-wait.sh -n <PR_NUMBER>
@@ -1117,5 +1112,5 @@ If a project currently uses Verdaccio (e.g., U-Connect at `npm.uscllc.net`), fol
 
 ### Pipeline runs Docker builds on pull requests
 
-- Verify `when` clause on Docker build steps restricts to the integration trunk (`branch: [main]` by default)
+- Verify `when` clause on Docker build steps restricts to `branch: [main]`
 - Pull requests should only run quality gates, not build/push images

packages/mosaic/framework/guides/CODE-REVIEW.md

@@ -10,10 +10,9 @@ If implementation diverges from `docs/PRD.md` or `docs/PRD.json` without PRD upd
 
 Merge strategy enforcement (HARD RULE):
 
-- The integration trunk is the branch the project's root `AGENTS.md` declares (default: `main`) — see `CONSTITUTION.md` Hard Gates.
+- PR target for delivery is `main`.
-- PR target for delivery is the integration trunk.
+- Direct pushes to `main` are prohibited.
-- Direct pushes to the integration trunk are prohibited.
+- Merge to `main` MUST be squash-only.
-- Merge to the integration trunk MUST be squash-only.
 - Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}` (or PowerShell equivalent).
 
 ## Review Checklist
@@ -115,8 +114,8 @@ Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` whenever code/A
 # List the issue being addressed
 ~/.config/mosaic/tools/git/issue-list.sh -i {issue-number}
 
-# View the changes (diff against the integration trunk; default: main)
+# View the changes
-git diff {integration_trunk}...HEAD
+git diff main...HEAD
 ```
 
 ### Providing Feedback
@@ -152,4 +151,4 @@ This pattern appears in 3 places. A shared helper would reduce duplication.
 2. If changes requested, assign back to author
 3. If approved, note approval in issue comments
 4. For merges, ensure CI passes first
-5. Merge PR to the integration trunk with squash strategy only
+5. Merge PR to `main` with squash strategy only

packages/mosaic/framework/guides/E2E-DELIVERY.md

@@ -78,7 +78,7 @@ For implementation work, you MUST run this cycle in order:
 7. `commit` - commit only when the logical unit passes tests and review.
 8. `pre-push queue guard` - before pushing, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. `push` - push immediately after queue guard passes.
-10. `PR integration` - if external git provider is available, create/update PR to the integration trunk (the project's declared trunk, default `main`) and merge with required strategy via Mosaic wrappers.
+10. `PR integration` - if external git provider is available, create/update PR to `main` and merge with required strategy via Mosaic wrappers.
 11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines on the exact PR head to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 12. `CI/pipeline verification` - wait for terminal CI status and require green before completion (`~/.config/mosaic/tools/git/pr-ci-wait.sh` for PR-based workflow).
 13. `issue closure` - close linked external issue (or close internal `docs/TASKS.md` task ref when provider is unavailable).
@@ -199,7 +199,7 @@ Before running this checklist, pause and self-interrogate: did I fulfill the use
 10. No unresolved blocker hidden.
 11. If deployment is in scope, deployment target, release version, and post-deploy verification evidence are documented.
 12. `docs/TASKS.md` status and issue/internal references are updated to match delivered work.
-13. If source code changed and external provider is available: PR merged to the integration trunk (squash), with merge evidence recorded.
+13. If source code changed and external provider is available: PR merged to `main` (squash), with merge evidence recorded.
 14. CI/pipeline status is terminal green for the merged PR/head commit.
 15. Linked external issue is closed (or internal task ref is closed when no provider exists).
 16. If any of items 13-15 fail due access/tooling, report `blocked` with exact failed wrapper command and do not claim completion.

packages/mosaic/framework/guides/ORCHESTRATOR-PROTOCOL.md

@@ -253,7 +253,7 @@ status → mission → run → repeat
 
 - [ ] All milestone tasks in TASKS.md are `done`
 - [ ] CI/pipeline green
-- [ ] PR merged to the integration trunk
+- [ ] PR merged to `main`
 - [ ] Issues closed
 - [ ] Update manifest: milestone status → completed
 - [ ] Update scratchpad: session log entry

packages/mosaic/framework/guides/ORCHESTRATOR.md

@@ -15,7 +15,7 @@ mosaic claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md th
 - You MUST keep the TASKS.md file updated with agent and tasks statuses.
 - You MUST keep `docs/` root clean. Reports and working artifacts MUST be stored in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
 - You MUST enforce plan/token usage budgets when provided, and adapt orchestration strategy to remain within limits.
-- You MUST enforce trunk workflow: workers branch from the integration trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), PR target is the integration trunk, direct push to the trunk is forbidden, and PR merges to the trunk are squash-only.
+- You MUST enforce trunk workflow: workers branch from `main`, PR target is `main`, direct push to `main` is forbidden, and PR merges to `main` are squash-only.
 - You MUST operate in steered-autonomy mode: human intervention is escalation-only; do not require the human to write code, review code, or manage PR/repo workflow.
 - You MUST NOT declare task or issue completion until PR is merged, CI/pipeline is terminal green, and linked issue is closed (or internal TASKS ref is closed when provider is unavailable).
 - Mosaic orchestration rules OVERRIDE runtime-default caution for routine push/merge/issue-close actions required by this workflow.
@@ -133,10 +133,10 @@ Milestone versioning (HARD RULE):
 
 Branch and merge strategy (HARD RULE):
 
-- Workers use short-lived task branches from `origin/{integration_trunk}` (default `main`).
+- Workers use short-lived task branches from `origin/main`.
-- Worker task branches merge back via PR to the integration trunk only.
+- Worker task branches merge back via PR to `main` only.
-- Direct pushes to the integration trunk are prohibited.
+- Direct pushes to `main` are prohibited.
-- PR merges to the integration trunk MUST use squash merge.
+- PR merges to `main` MUST use squash merge.
 
 **Available templates:**
 
@@ -427,7 +427,7 @@ git push
     - Before merging, run queue guard:
       `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`
     - Ensure PR exists for the task branch (create/update via wrappers if needed):
-      `~/.config/mosaic/tools/git/pr-create.sh ... -B {integration_trunk}` (default `main`)
+      `~/.config/mosaic/tools/git/pr-create.sh ... -B main`
     - Merge via wrapper:
       `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
     - Wait for terminal CI status:
@@ -619,7 +619,7 @@ Construct this from the task row and pass to worker via Task tool:
 
 ## Workflow
 
-1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/{integration_trunk}) && git rebase origin/{integration_trunk}` ({integration_trunk} = the project's declared trunk, default `main`)
+1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/main) && git rebase origin/main`
 2. Read `docs/PRD.md` or `docs/PRD.json` and align implementation with PRD requirements
 3. Read the finding details from the report
 4. Implement the fix following existing code patterns
@@ -637,7 +637,7 @@ Do NOT leave lint warnings or errors for someone else to clean up. 6. Run REQUIR
 For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
 
 - `~/.config/mosaic/tools/git/issue-view.sh -i {N}`
-- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B {integration_trunk}`
+- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B main`
 - Push: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B {task_branch}`
 - Merge: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B {pr_head_branch} -R {pr_head_owner/repo} --sha {pr_head_full_sha}`
 - `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
@@ -994,13 +994,13 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
 
 ---
 
-## Merge-to-Trunk Candidate Protocol (Container Deployments)
+## Merge-to-Main Candidate Protocol (Container Deployments)
 
-If deployment is in scope and container images are used, every merge to the integration trunk MUST execute this protocol:
+If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:
 
 1. Build and push immutable candidate image tags:
    - `sha-<shortsha>` (always)
-   - `v{base-version}-rc.{build}` (for integration-trunk merges)
+   - `v{base-version}-rc.{build}` (for `main` merges)
    - `testing` mutable pointer to the same digest
 2. Resolve and record the image digest for each service.
 3. Deploy by digest to testing environment (never deploy by mutable tag alone).

packages/mosaic/framework/install.sh

@@ -35,6 +35,18 @@ SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 
+# Normalize the ambient umask so directory modes are a property of the installer
+# and not of whatever shell invoked it (#1236). Debian/Ubuntu ship umask 002, so
+# every `mkdir -p` below yielded 0775 — and the fleet env boundary rejects any
+# managed directory with `mode & 0o022`, which made `mosaic fleet init --write`
+# impossible on a stock install of those distros. Fedora/RHEL ship 022 and did
+# not trip it, so the product worked or did not depending on the operator's
+# login shell. 022 is what this script already assumes it produces: see the
+# umask note in make_durable_snapshot, which restores to the ambient value
+# precisely so "every later sync copy and new framework dir" gets 0644/0755.
+# Now that value is 022 rather than whatever was inherited.
+umask 022
+
 # Deliberately parsed from "$@" (a real, explicit, per-invocation argument) —
 # never an environment variable — so this opt-out can never sit silently
 # inherited in a shell profile. See #869 Point-1 C2.
@@ -696,6 +708,52 @@ sync_framework
 mkdir -p "$TARGET_DIR/memory"
 mkdir -p "$TARGET_DIR/credentials"
 
+# Three directories must be 0700, not merely not-group-writable (#1236).
+# The fleet code guards them with two different masks in two different
+# languages, and the strict one wins:
+#
+#   assertPrivateManagedDirectory (fleet-reconciler.js, `mode & 0o077`)
+#       -> MOSAIC_HOME and MOSAIC_HOME/fleet, checked before the roster lock is
+#          taken, so every mutating `mosaic fleet` command dies at 0755.
+#   assert_private_directory (tools/fleet/start-agent-session.sh, `mode & 077`)
+#       -> MOSAIC_HOME/fleet/agents, checked before a pane is ever spawned.
+#
+# Their laxer siblings (`mode & 0o022`) accept 0755, which is why normalizing
+# the umask above is necessary and not sufficient — a correct umask-022 install
+# still produces 0755 and still cannot run `mosaic fleet init --write`. Say the
+# strict modes outright rather than inferring them from a umask.
+#
+# Only these. The rest of the tree is content, stays 0755, and is only ever
+# reached by the 0o022 checks, which 0755 satisfies.
+chmod 700 "$TARGET_DIR" 2>/dev/null || \
+  warn "Could not set 0700 on $TARGET_DIR — 'mosaic fleet' mutations will fail as unsafe-permissions."
+if [[ -d "$TARGET_DIR/fleet" ]]; then
+  chmod 700 "$TARGET_DIR/fleet" 2>/dev/null || \
+    warn "Could not set 0700 on $TARGET_DIR/fleet — 'mosaic fleet' mutations will fail as unsafe-permissions."
+fi
+# fleet/agents does not exist on a first install — the CLI creates it 0700 on
+# demand. It is chmod'd here for the UPGRADE case: a tree built under umask 002
+# has it at 0775, and the repair sweep below cannot rescue it, because stripping
+# group/other write from 0755 leaves 0750 and `mode & 077` is still non-zero.
+if [[ -d "$TARGET_DIR/fleet/agents" ]]; then
+  chmod 700 "$TARGET_DIR/fleet/agents" 2>/dev/null || \
+    warn "Could not set 0700 on $TARGET_DIR/fleet/agents — agent sessions will fail to start as unsafe-permissions."
+fi
+# credentials/ holds secrets and was never meant to be group-readable either.
+# It is not on the fleet boundary, so a failure here breaks nothing — but it is
+# the one directory where a silently-failed chmod leaves secrets group-readable,
+# which is precisely the failure worth a line in the output.
+chmod 700 "$TARGET_DIR/credentials" 2>/dev/null || \
+  warn "Could not set 0700 on $TARGET_DIR/credentials — stored secrets may be readable by other users on this host."
+
+# Repair an existing tree. The umask above only governs directories this run
+# creates, so a host installed under umask 002 before this fix keeps its 0775
+# dirs through every upgrade and stays broken. Strips group/other WRITE only —
+# never read or execute — so it can repair the boundary violation without
+# changing who can traverse or read anything. Scoped to directories: file modes
+# are the manifest's business, not this fix's.
+find "$TARGET_DIR" -type d -perm /022 -exec chmod go-w {} + 2>/dev/null || true
+
 # Reconcile contract files from defaults/ into the framework root: framework-owned
 # files (CONSTITUTION/AGENTS/STANDARDS) are overwritten every upgrade (a divergent
 # copy is backed up once); user-seeded files (TOOLS) are written on first install only.

packages/mosaic/framework/systemd/user/mosaic-agent@.service

@@ -4,6 +4,14 @@ Documentation=https://git.mosaicstack.dev/mosaicstack/stack
 Requires=mosaic-tmux-holder.service
 After=mosaic-tmux-holder.service
 PartOf=mosaic-tmux-holder.service
+# Do not attempt a seat before its generated env exists. `install` enables this
+# unit (WantedBy=default.target) but on a roster-v2 fleet the reconciler owns the
+# generated env, so between `install` and the first `apply`/`regen --write` there
+# is a boot window where ExecStart would run against an absent env file and the
+# launcher would fail the unit. A skipped unit is the honest state for "enabled
+# but not yet configured"; systemd re-evaluates the condition on every start, so
+# the seat comes up on the next start once the reconciler has written env.
+ConditionPathExists=%h/.config/mosaic/fleet/agents/%i.env.generated
 
 [Service]
 Type=oneshot

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

@@ -128,6 +128,14 @@ EOF
 sleep 30
 EOF
   chmod 700 "$AGENT_BIN/mosaic"
+  # The launcher resolves the roster's runtime against PANE_PATH before it
+  # spawns anything (#1241), so the runtime this projection names has to be
+  # present here even though the fake `mosaic` above never execs it.
+  cat > "$AGENT_BIN/pi" <<'EOF'
+#!/bin/sh
+sleep 30
+EOF
+  chmod 700 "$AGENT_BIN/pi"
   server_environment_before=$(tmux -L "$TEST_SOCKET" show-environment -g | sort)
   server_sessions_before=$(tmux -L "$TEST_SOCKET" list-sessions | sort)
   if /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin MOSAIC_HOME="$AGENT_HOME" \

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

@@ -225,6 +225,54 @@ else
   warn "mosaic-ensure-sequential-thinking helper missing"
 fi
 
+# Fleet transport binary (#1240).
+#
+# `mosaic fleet --help` reads "Manage the local Mosaic tmux fleet" and every
+# roster the CLI scaffolds sets `transport: tmux`, but nothing in the install
+# path provides tmux and, until now, nothing here noticed it was absent. On a
+# greenfield host that produced a fleet which installed clean, started clean,
+# and had no live seat; `mosaic fleet ps` was the operator's first and only
+# signal that anything was wrong.
+#
+# The roster's own `transport:` is read rather than assumed, so a host that
+# declares something other than tmux is told about the binary it actually
+# needs. Absent a roster the check still runs — `mosaic fleet init` will
+# scaffold a tmux fleet on this host, and finding out beforehand is the point.
+#
+# `tools/install.sh` carries a deliberately parallel check at the end of its
+# summary. The two are separate because the installer must be able to say this
+# before the framework's own scripts are guaranteed to be on disk; keep their
+# wording in step.
+fleet_declared_transport() {
+  local roster="$MOSAIC_HOME/fleet/roster.yaml"
+  local declared=""
+
+  if [[ -f "$roster" ]]; then
+    declared="$(sed -n 's/^[[:space:]]*transport:[[:space:]]*//p' "$roster" | head -1 |
+      tr -d '"'\''' | tr -d '\r' | awk '{print $1}')"
+  fi
+
+  printf '%s\n' "${declared:-tmux}"
+}
+
+check_fleet_transport() {
+  local transport
+  transport="$(fleet_declared_transport)"
+
+  if command -v "$transport" >/dev/null 2>&1; then
+    pass "Fleet transport available: $transport"
+    return
+  fi
+
+  if [[ -f "$MOSAIC_HOME/fleet/roster.yaml" ]]; then
+    warn "Fleet transport '$transport' is not installed — this host has a roster and no seat can launch. Install it (e.g. sudo apt-get install -y $transport), then 'mosaic fleet start'."
+  else
+    warn "Fleet transport '$transport' is not installed — 'mosaic fleet' cannot run seats here. Install it (e.g. sudo apt-get install -y $transport) before 'mosaic fleet init'."
+  fi
+}
+
+check_fleet_transport
+
 # Legacy migration surfaces should no longer contain symlink trees.
 legacy_paths=(
   "$HOME/.claude/agent-guides"

packages/mosaic/framework/tools/_scripts/test-fleet-transport-check.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# Covers the #1240 fleet-transport checks in `mosaic-doctor` and in
+# `tools/install.sh`.
+#
+# Both checks answer the same question — "can a seat actually launch on this
+# host?" — from two different places, because the installer has to be able to
+# answer it before the framework's own scripts are guaranteed to be on disk.
+# Two implementations of one rule is exactly the shape that drifts, so this
+# harness drives BOTH, in one file, from the same table of cases.
+#
+# The functions are extracted from the shipped scripts rather than copied here.
+# A test that carries its own copy of the logic is a test that keeps passing
+# after the shipped copy changes — the failure mode this whole change is about.
+# Extraction is by exact function header and a closing brace in column one; if
+# either script is reshaped so that stops matching, the extraction yields
+# nothing and this fails loudly instead of silently measuring an empty string.
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+DOCTOR="$SCRIPT_DIR/mosaic-doctor"
+# framework/tools/_scripts -> framework/tools -> framework -> mosaic -> packages -> repo
+INSTALLER=$(cd -- "$SCRIPT_DIR/../../../../.." && pwd)/tools/install.sh
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+[ -f "$DOCTOR" ] || fail "missing mosaic-doctor at $DOCTOR"
+[ -f "$INSTALLER" ] || fail "missing install.sh at $INSTALLER"
+
+ROOT=$(mktemp -d)
+trap 'rm -rf "$ROOT"' EXIT
+
+# The cases below run with PATH set to a directory that deliberately does not
+# contain a shell, and a PATH assignment on a command also governs how that
+# command is looked up — so bash has to be named absolutely or it becomes the
+# thing that is missing.
+BASH_BIN=$(command -v bash) || fail "host is missing 'bash'"
+
+# A PATH containing exactly the utilities these functions use and nothing else.
+# The absent-transport cases are only meaningful on a PATH where the transport
+# is genuinely unresolvable, and this host (like most) has tmux in /usr/bin —
+# so the system path cannot be part of the path under test.
+FAKE_BIN="$ROOT/bin"
+mkdir -p "$FAKE_BIN"
+for utility in sed head tr awk; do
+  utility_path=$(command -v "$utility") || fail "host is missing '$utility'"
+  ln -s "$utility_path" "$FAKE_BIN/$utility"
+done
+
+if PATH="$FAKE_BIN" command -v tmux >/dev/null 2>&1; then
+  fail "'tmux' is resolvable on the minimal test path; absent-transport cases are not measurable"
+fi
+
+# Extract a function by its exact header, up to a closing brace in column one.
+extract_function() {
+  local source_file="$1"
+  local function_name="$2"
+  local destination="$3"
+
+  awk -v name="$function_name" '
+    $0 == name "() {" { collecting = 1 }
+    collecting { print }
+    collecting && $0 == "}" { exit }
+  ' "$source_file" > "$destination"
+
+  grep -qF "$function_name() {" "$destination" ||
+    fail "could not extract '$function_name' from $source_file — has it been renamed or reshaped?"
+  # An unterminated extraction would be a syntax error the moment it is sourced,
+  # but saying so here names the cause instead of leaving a bash parse error.
+  bash -n "$destination" ||
+    fail "extracted '$function_name' does not parse; the closing brace was probably not found"
+}
+
+extract_function "$DOCTOR" fleet_declared_transport "$ROOT/doctor-declared.sh"
+extract_function "$DOCTOR" check_fleet_transport "$ROOT/doctor-check.sh"
+extract_function "$INSTALLER" check_fleet_transport "$ROOT/installer-check.sh"
+
+# Build a MOSAIC_HOME, optionally with a roster declaring a transport.
+make_home() {
+  local home="$ROOT/$1"
+  local declared="${2-}"
+
+  rm -rf "$home"
+  mkdir -p "$home"
+  if [ -n "$declared" ]; then
+    mkdir -p "$home/fleet"
+    cat > "$home/fleet/roster.yaml" <<EOF
+version: 2
+generation: 1
+transport: $declared
+agents: []
+EOF
+  fi
+  printf '%s\n' "$home"
+}
+
+# Run the doctor's check against a given home and path, capturing which
+# reporter the check chose. The real `pass` prints only under `--verbose` and
+# the real `warn` always prints; these stubs make both unconditional on
+# purpose, because what is under test is the severity the check selects, not
+# whether the default verbosity happens to show it. A check that warned where
+# it should pass would otherwise be invisible here.
+run_doctor_check() {
+  local home="$1"
+  local path="$2"
+
+  MOSAIC_HOME="$home" PATH="$path" "$BASH_BIN" --noprofile --norc -c '
+    set -euo pipefail
+    warn() { echo "[WARN] $*"; }
+    pass() { echo "[OK] $*"; }
+    MOSAIC_HOME="$1"
+    source "$2"
+    source "$3"
+    check_fleet_transport
+  ' _ "$home" "$ROOT/doctor-declared.sh" "$ROOT/doctor-check.sh" 2>&1
+}
+
+run_installer_check() {
+  local home="$1"
+  local path="$2"
+
+  MOSAIC_HOME="$home" PATH="$path" "$BASH_BIN" --noprofile --norc -c '
+    set -euo pipefail
+    warn() { echo "[WARN] $*"; }
+    C="" RESET=""
+    MOSAIC_HOME="$1"
+    source "$2"
+    check_fleet_transport
+  ' _ "$home" "$ROOT/installer-check.sh" 2>&1
+}
+
+# A transport that exists. Named tmux because that is what the default roster
+# declares; the binary never runs, it only has to resolve.
+PRESENT_BIN="$ROOT/present-bin"
+mkdir -p "$PRESENT_BIN"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$PRESENT_BIN/tmux"
+chmod +x "$PRESENT_BIN/tmux"
+PATH_WITH_TMUX="$PRESENT_BIN:$FAKE_BIN"
+
+# ── absent, no roster ────────────────────────────────────────────────────────
+# Nothing has been configured yet, so the honest thing to point at is `init`.
+home=$(make_home no-roster)
+
+output=$(run_doctor_check "$home" "$FAKE_BIN")
+echo "$output" | grep -qF '[WARN]' || fail "doctor did not warn when tmux was absent"
+echo "$output" | grep -qF 'tmux' || fail "doctor warning did not name the transport"
+echo "$output" | grep -qF 'mosaic fleet init' || fail "doctor did not point a rosterless host at init"
+
+output=$(run_installer_check "$home" "$FAKE_BIN")
+echo "$output" | grep -qF '[WARN]' || fail "installer did not warn when tmux was absent"
+echo "$output" | grep -qF 'reports success and no seat comes up' ||
+  fail "installer warning did not say what the missing transport actually breaks"
+
+# ── absent, roster present ───────────────────────────────────────────────────
+# A configured fleet that cannot launch is a stronger statement than a
+# hypothetical one, and the message says so.
+home=$(make_home with-roster tmux)
+
+output=$(run_doctor_check "$home" "$FAKE_BIN")
+echo "$output" | grep -qF '[WARN]' || fail "doctor did not warn with a roster present and tmux absent"
+echo "$output" | grep -qF 'roster' || fail "doctor did not mention the roster it found"
+echo "$output" | grep -qF 'mosaic fleet start' || fail "doctor did not point a configured host at start"
+
+# ── present ──────────────────────────────────────────────────────────────────
+# Silence from the installer, and a pass (not a warning) from the audit.
+for home_name in no-roster with-roster; do
+  home="$ROOT/$home_name"
+
+  output=$(run_doctor_check "$home" "$PATH_WITH_TMUX")
+  if echo "$output" | grep -qF '[WARN]'; then
+    fail "doctor warned about the transport while tmux was present ($home_name)"
+  fi
+  echo "$output" | grep -qF '[OK]' || fail "doctor did not record a pass with tmux present ($home_name)"
+
+  output=$(run_installer_check "$home" "$PATH_WITH_TMUX")
+  if [ -n "$output" ]; then
+    fail "installer was not silent with tmux present ($home_name): $output"
+  fi
+done
+
+# ── the roster declares something other than tmux ────────────────────────────
+# The roster is read, not assumed. A host that declares a different transport
+# is told about the binary it actually needs, and never about tmux — being sent
+# to install the wrong package is worse than no advice at all.
+home=$(make_home other-transport zellij)
+
+output=$(run_doctor_check "$home" "$PATH_WITH_TMUX")
+echo "$output" | grep -qF 'zellij' || fail "doctor ignored the roster's declared transport"
+if echo "$output" | grep -qF 'tmux'; then
+  fail "doctor named tmux for a host whose roster declares zellij"
+fi
+
+output=$(run_installer_check "$home" "$PATH_WITH_TMUX")
+echo "$output" | grep -qF 'zellij' || fail "installer ignored the roster's declared transport"
+if echo "$output" | grep -qF 'tmux'; then
+  fail "installer named tmux for a host whose roster declares zellij"
+fi
+
+# ── a quoted or trailing-comment transport value ─────────────────────────────
+# YAML permits both and neither is exotic; a check that installs `tmux"` or
+# reads `tmux # default` as a binary name would send the operator nowhere.
+home=$(make_home quoted-transport '"tmux"   # the only transport today')
+
+output=$(run_doctor_check "$home" "$PATH_WITH_TMUX")
+echo "$output" | grep -qF '[OK] Fleet transport available: tmux' ||
+  fail "doctor did not parse a quoted/commented transport value: $output"
+
+output=$(run_installer_check "$home" "$PATH_WITH_TMUX")
+if [ -n "$output" ]; then
+  fail "installer did not parse a quoted/commented transport value: $output"
+fi
+
+echo "ok - fleet transport checks (mosaic-doctor + install.sh)"

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

@@ -80,6 +80,26 @@ safe_path "$MOSAIC_HOME" || fail_env unsafe-path MOSAIC_HOME "$MOSAIC_HOME"
 
 FLEET_DIR="$MOSAIC_HOME/fleet"
 AGENT_ENV_DIR="$FLEET_DIR/agents"
+
+# Brain-home split (canon docs/STRUCTURE-CANON.md §2): seat launch envs live
+# under the brain home's fleet/agents when a brain is active; roster, roles
+# baseline, and runtime state (fleet/run) stay under MOSAIC_HOME.
+# Resolution mirrors packages/mosaic/src/fleet/brain-home.ts:
+#   1. MOSAIC_BRAIN_HOME env (explicit, always wins)
+#   2. ~/.mosaic — adopted only when MOSAIC_HOME is the default config home AND
+#      ~/.mosaic/fleet/agents exists
+#   3. MOSAIC_HOME (legacy single-tree)
+BRAIN_HOME="${MOSAIC_BRAIN_HOME:-}"
+if [ -z "$BRAIN_HOME" ]; then
+  BRAIN_HOME="$MOSAIC_HOME"
+  if [ "$(cd "$MOSAIC_HOME" 2>/dev/null && pwd -P)" = "$HOME/.config/mosaic" ] \
+     && [ -d "$HOME/.mosaic/fleet/agents" ]; then
+    BRAIN_HOME="$HOME/.mosaic"
+  fi
+fi
+if [ "$BRAIN_HOME" != "$MOSAIC_HOME" ]; then
+  AGENT_ENV_DIR="$BRAIN_HOME/fleet/agents"
+fi
 assert_managed_directory "$MOSAIC_HOME"
 assert_managed_directory "$FLEET_DIR"
 assert_private_directory "$AGENT_ENV_DIR"
@@ -286,6 +306,36 @@ _build_runtime_bin_prefix() {
 MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
 PANE_PATH=${MOSAIC_RUNTIME_BIN_PREFIX:+${MOSAIC_RUNTIME_BIN_PREFIX}:}/usr/local/bin:/usr/bin:/bin
 
+# #1241. The pane runs `mosaic yolo <runtime>` under PANE_PATH with a cleared
+# environment. A binary missing from *that* path is a pane that dies in under a
+# second, inside a session nobody is attached to, with its diagnostic scrolled
+# into a pane tmux then destroys. Resolve both here, before any effect, where
+# the failure is still attributable to the thing that caused it.
+#
+# `mosaic yolo <runtime>` runs checkRuntime(runtime) and the binary it looks for
+# is named exactly like the runtime, so resolving the runtime name is the same
+# question the pane will ask a moment later — asked while an operator can still
+# see the answer.
+_resolve_in_pane_path() {
+  PATH="$PANE_PATH" command -v -- "$1" 2>/dev/null
+}
+
+# Exit 69 (EX_UNAVAILABLE): the seat cannot be provided. Distinguished from the
+# 64 (EX_USAGE) rejections above, which mean the projection itself was bad —
+# here the data is fine and the host is not ready. Callers tell the individual
+# cases apart by `code=`, the same way fail_env's many codes share exit 64.
+fail_launch() {
+  local code="$1"
+  shift
+  echo "ERROR: agent launch aborted: code=${code} agent=${AGENT_NAME} $*" >&2
+  exit 69
+}
+
+for required_binary in mosaic "$MOSAIC_AGENT_RUNTIME"; do
+  _resolve_in_pane_path "$required_binary" >/dev/null ||
+    fail_launch missing-binary "'${required_binary}' is not on the pane PATH (${PANE_PATH})"
+done
+
 _ensure_claude_workdir_trusted() {
   local workdir="$1"
   local resolved
@@ -384,6 +434,19 @@ if [ -n "$PANE_PID" ]; then
   _start_heartbeat_sidecar "$AGENT_NAME" "$PANE_PID" \
     "$MOSAIC_HEARTBEAT_RUN_DIR" "$MOSAIC_HEARTBEAT_INTERVAL" || \
     echo "WARNING: heartbeat sidecar could not be started for $AGENT_NAME" >&2
+elif _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
+  # #1241. Session present, no pane PID after a second of retries. Whatever this
+  # is, it is not a seat an operator can use, so it is not a success either.
+  fail_launch pane-pid-unresolved \
+    "tmux reports the session but no pane PID after 5 attempts"
 else
-  echo "WARNING: could not resolve pane PID for $AGENT_NAME — heartbeat sidecar not started" >&2
+  # #1241. This branch used to print a WARNING about the heartbeat sidecar and
+  # exit 0. It is not a heartbeat problem: tmux destroys a session when its pane
+  # command exits, so an absent session one second after new-session means the
+  # runtime died on startup. Reporting it as success is what let `fleet start`
+  # return 0 over three dead panes — the launcher knew, and said the wrong thing
+  # at the wrong severity to the wrong layer.
+  fail_launch pane-did-not-survive \
+    "the pane exited immediately and tmux destroyed the session;" \
+    "run 'mosaic yolo ${MOSAIC_AGENT_RUNTIME}' in ${MOSAIC_AGENT_WORKDIR} to see why"
 fi

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

@@ -23,8 +23,26 @@ index=0
 if [ "${args[0]:-}" = -L ]; then index=2; fi
 case "${args[$index]:-}" in
   has-session)
+    # The holder always answers. MOSAIC_TEST_HELD_SESSIONS lets a case add
+    # other targets that should answer too — without it there is no way to
+    # model "tmux still reports the session" for a non-holder agent, and the
+    # launcher's pane-pid-unresolved branch is unreachable from this harness.
+    #
+    # A listed target answers only AFTER new-session, because the launcher asks
+    # this question twice about the same name: once before launching, where a
+    # yes means "already running, nothing to do, exit 0", and once after, where
+    # a yes means "the session survived". A shim that answered yes to both
+    # would short-circuit at the first and never reach the branch under test —
+    # it would look like coverage and measure the idempotency path instead.
     for argument in "${args[@]}"; do
       [ "$argument" = '=_holder:0.0' ] && exit 0
+      case " ${MOSAIC_TEST_HELD_SESSIONS:-} " in
+        *" $argument "*)
+          if tr '\0' '\n' < "${MOSAIC_TEST_TMUX_CALLS:?}" | grep -qxF new-session; then
+            exit 0
+          fi
+          ;;
+      esac
     done
     exit 1
     ;;
@@ -62,6 +80,30 @@ env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
 SHIM
 chmod +x "$FAKE_BIN/mosaic"
 
+# The runtime the rosters below name. The launcher resolves it against PANE_PATH
+# before spawning (#1241), so it has to exist somewhere the pane would find it —
+# not merely on the launcher's own PATH.
+printf '#!/usr/bin/env bash\nexit 0\n' > "$FAKE_BIN/pi"
+chmod +x "$FAKE_BIN/pi"
+
+# PANE_PATH is derived partly from `npm config get prefix`. Left to the real npm
+# it would splice whatever the host has installed into the path under test, and
+# the missing-binary cases below would pass or fail by accident of the machine.
+cat > "$FAKE_BIN/npm" <<'SHIM'
+#!/usr/bin/env bash
+printf '%s\n' "${MOSAIC_TEST_NPM_PREFIX:-/nonexistent}"
+SHIM
+chmod +x "$FAKE_BIN/npm"
+
+# PANE_PATH always ends in the system path. A host that installs these there can
+# not measure the missing-binary cases at all, and a green run would mean
+# nothing — so say so instead of passing.
+for host_binary in mosaic pi; do
+  if PATH=/usr/local/bin:/usr/bin:/bin command -v "$host_binary" >/dev/null 2>&1; then
+    fail "host provides '$host_binary' in the system path; missing-binary cases are not measurable here"
+  fi
+done
+
 write_generated() {
   local home="$1"
   local agent="$2"
@@ -81,6 +123,19 @@ MOSAIC_TMUX_SOCKET=mosaic-test
 EOF
   chmod 600 "$home/fleet/agents/$agent.env.generated"
   mkdir -p "$home/work"
+  install_pane_binaries "$home"
+}
+
+# `$PANE_HOME/.npm-global/bin` is one of the prefixes the launcher folds into
+# PANE_PATH, so this is the pane's own view of "installed", distinct from the
+# launcher's PATH. Tests that need a binary *absent* remove it from here.
+install_pane_binaries() {
+  local pane_home="$1"
+  mkdir -p "$pane_home/.npm-global/bin"
+  local binary
+  for binary in mosaic pi; do
+    ln -sf "$FAKE_BIN/$binary" "$pane_home/.npm-global/bin/$binary"
+  done
 }
 
 run_start() {
@@ -88,6 +143,7 @@ run_start() {
   local agent="$2"
   HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
     MOSAIC_TEST_PANE_PID="${MOSAIC_TEST_PANE_PID:-}" \
+    MOSAIC_TEST_HELD_SESSIONS="${MOSAIC_TEST_HELD_SESSIONS:-}" \
     MOSAIC_TEST_HOME="$home" \
     MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
     MOSAIC_HOME="$home" "$START" "$agent"
@@ -98,7 +154,10 @@ run_start() {
 HOME_VALID="$ROOT/valid"
 AGENT_VALID="coder0"
 write_generated "$HOME_VALID" "$AGENT_VALID"
-run_start "$HOME_VALID" "$AGENT_VALID"
+# A live pane PID is part of what "valid launch" means. Until #1241 this case
+# ran with none, so the suite's one success path was itself a dead pane the
+# launcher reported as fine.
+MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_VALID" "$AGENT_VALID"
 valid_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$valid_args" | grep -qF new-session || fail "valid generated projection did not reach tmux"
 echo "$valid_args" | grep -qF 'mosaic' || fail "fixed mosaic launcher command missing"
@@ -108,6 +167,54 @@ if echo "$valid_args" | grep -qF 'bash -c'; then
   fail "launcher constructed a shell command payload"
 fi
 
+# ── Brain-home split (canon §2) ─────────────────────────────────────────
+# When MOSAIC_HOME is the default config home under $HOME and the host carries
+# $HOME/.mosaic/fleet/agents, seat envs resolve from the brain tree; the config
+# home still owns fleet/run (holder-owner) and remains a managed boundary.
+: > "$TMUX_CALLS"
+HOME_BRAIN="$ROOT/brain-home"
+CONFIG_HOME="$HOME_BRAIN/.config/mosaic"
+BRAIN="$HOME_BRAIN/.mosaic"
+mkdir -p "$CONFIG_HOME/fleet/run" "$BRAIN/fleet/agents" "$HOME_BRAIN/work"
+chmod 700 "$CONFIG_HOME" "$CONFIG_HOME/fleet" "$CONFIG_HOME/fleet/run" \
+  "$BRAIN/fleet/agents" "$HOME_BRAIN/work"
+printf '123e4567-e89b-12d3-a456-426614174000\n' > "$CONFIG_HOME/fleet/run/holder-owner"
+chmod 600 "$CONFIG_HOME/fleet/run/holder-owner"
+cat > "$BRAIN/fleet/agents/coder-brain.env.generated" <<EOF
+MOSAIC_AGENT_NAME=coder-brain
+MOSAIC_AGENT_CLASS=code
+MOSAIC_AGENT_RUNTIME=pi
+MOSAIC_AGENT_MODEL=openai-codex/gpt-5.6-sol
+MOSAIC_AGENT_REASONING=high
+MOSAIC_AGENT_TOOL_POLICY=code
+MOSAIC_AGENT_WORKDIR=$HOME_BRAIN/work
+MOSAIC_TMUX_SOCKET=mosaic-test
+EOF
+chmod 600 "$BRAIN/fleet/agents/coder-brain.env.generated"
+install_pane_binaries "$HOME_BRAIN"
+HOME="$HOME_BRAIN" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
+  MOSAIC_TEST_PANE_PID=$$ MOSAIC_TEST_HOME="$HOME_BRAIN" \
+  MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
+  MOSAIC_HOME="$CONFIG_HOME" "$START" coder-brain
+brain_args=$(tr '\0' '\n' < "$TMUX_CALLS")
+echo "$brain_args" | grep -qF new-session || fail "brain-home generated projection did not reach tmux"
+echo "$brain_args" | grep -qF 'coder-brain' || fail "brain-home agent env was not the launch source"
+[ -f "$BRAIN/fleet/agents/coder-brain.env.generated" ] || fail "brain generated env vanished"
+
+# Negative control: the SAME default-config-home shape but without
+# ~/.mosaic/fleet/agents — the config-home env tree is used directly (legacy).
+: > "$TMUX_CALLS"
+HOME_NOBRAIN="$ROOT/brainless-home"
+CONFIG_HOME_NOBRAIN="$HOME_NOBRAIN/.config/mosaic"
+write_generated "$CONFIG_HOME_NOBRAIN" "coder-legacy"
+install_pane_binaries "$HOME_NOBRAIN"
+HOME="$HOME_NOBRAIN" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
+  MOSAIC_TEST_PANE_PID=$$ MOSAIC_TEST_HOME="$HOME_NOBRAIN" \
+  MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
+  MOSAIC_HOME="$CONFIG_HOME_NOBRAIN" "$START" coder-legacy
+legacy_args=$(tr '\0' '\n' < "$TMUX_CALLS")
+echo "$legacy_args" | grep -qF new-session || fail "legacy single-tree launch regressed"
+
 # The pane must start through an absolute clean-environment boundary. Its
 # runtime command remains an argv vector, but no holder/session environment
 # control variable can pass through the pane command.
@@ -245,6 +352,13 @@ PANE_BASH_ENV="$ROOT/pane-boundary.bash-env"
 printf 'MOSAIC_RUNTIME_BIN=%s\n' "$FAKE_BIN" > \
   "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
 chmod 600 "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
+# This case does not go through run_start, so its pane binaries come from
+# MOSAIC_RUNTIME_BIN=$FAKE_BIN in the env.local written above — not from the
+# symlinks install_pane_binaries planted under the generated home, which this
+# launcher never consults because HOME here is the trusted parent. That is a
+# legitimate resolution path, but it means dropping MOSAIC_RUNTIME_BIN from
+# this case on the belief that the symlinks cover it would break the #1241
+# binary check rather than exercise it.
 LD_PRELOAD='/not/loaded/by-clean-bootstrap.so' \
 BASH_ENV="$PANE_BASH_ENV" \
 MOSAIC_UNTRUSTED_SENTINEL='must-not-reach-pane' \
@@ -258,6 +372,7 @@ PATH="$PANE_STALE_PATH" \
     "MOSAIC_TEST_HOME=$PANE_TRUSTED_HOME" \
     MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
     MOSAIC_TEST_EXECUTE_PANE=1 \
+    "MOSAIC_TEST_PANE_PID=$$" \
     "$START" coder-pane-boundary
 pane_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$pane_args" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
@@ -392,6 +507,75 @@ echo "$interaction_policy_args" | grep -qF 'new-session' && \
 echo "$output" | grep -qF 'operator interaction service requires runtime pi' || \
   fail "interaction pinned-policy check did not follow strict parsing"
 
+# #1241. The pane runs `mosaic yolo <runtime>` against PANE_PATH. A binary
+# missing from that path is a launch failure, and it has to be named before the
+# session is created — after it, the diagnostic dies with the pane.
+assert_missing_pane_binary_rejected() {
+  local binary="$1"
+  local home="$ROOT/missing-$binary"
+  local agent="coder-missing-$binary"
+  write_generated "$home" "$agent"
+  rm -f "$home/.npm-global/bin/$binary"
+
+  : > "$TMUX_CALLS"
+  local output
+  if output=$(MOSAIC_TEST_PANE_PID=$$ run_start "$home" "$agent" 2>&1); then
+    fail "launch succeeded with '$binary' absent from the pane PATH"
+  fi
+  echo "$output" | grep -qF 'code=missing-binary' || fail "missing '$binary' diagnostic missing"
+  echo "$output" | grep -qF "'$binary'" || fail "missing-binary diagnostic did not name $binary"
+  if tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session; then
+    fail "launcher created a session it knew would die ($binary absent)"
+  fi
+}
+
+assert_missing_pane_binary_rejected mosaic
+assert_missing_pane_binary_rejected pi
+
+# #1241. tmux destroys a session when its pane command exits, so no pane PID a
+# second after new-session means the runtime died on startup. This used to be a
+# WARNING about the heartbeat sidecar followed by exit 0 — three layers above it
+# then reported a fleet that was not running.
+: > "$TMUX_CALLS"
+HOME_DEAD_PANE="$ROOT/dead-pane"
+write_generated "$HOME_DEAD_PANE" "coder-dead-pane"
+if output=$(MOSAIC_TEST_PANE_PID='' run_start "$HOME_DEAD_PANE" coder-dead-pane 2>&1); then
+  fail "launcher reported success over a pane that did not survive"
+fi
+echo "$output" | grep -qF 'code=pane-did-not-survive' || fail "dead-pane diagnostic missing"
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "dead pane is still being reported as a heartbeat-sidecar problem"
+fi
+tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session || \
+  fail "dead-pane case did not reach the launch it is measuring"
+
+# #1241, the other way a pane fails. Above, tmux destroyed the session and
+# has-session said so. Here the session is still there and no PID comes back
+# after the retries — a different fault (the pane is alive but unusable, or
+# tmux is answering inconsistently) that an operator has to be told apart from
+# a runtime that died on startup.
+#
+# This case exists because the branch that handles it shipped with nothing able
+# to reach it: the shim answered has-session only for the holder, so every
+# non-holder agent landed in the session-is-gone branch no matter what. A
+# defensive branch nothing exercises is the same shape as the bug this whole
+# change is about, one layer down.
+: > "$TMUX_CALLS"
+HOME_NO_PID="$ROOT/pane-no-pid"
+write_generated "$HOME_NO_PID" "coder-no-pid"
+if output=$(MOSAIC_TEST_PANE_PID='' MOSAIC_TEST_HELD_SESSIONS='=coder-no-pid:0.0' \
+  run_start "$HOME_NO_PID" coder-no-pid 2>&1); then
+  fail "launcher reported success over a session with no resolvable pane PID"
+fi
+echo "$output" | grep -qF 'code=pane-pid-unresolved' || \
+  fail "session-present/no-PID was not reported as pane-pid-unresolved: $output"
+if echo "$output" | grep -qF 'code=pane-did-not-survive'; then
+  fail "a session tmux still reports was diagnosed as a destroyed session"
+fi
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "an unresolvable pane PID is still being reported as a heartbeat-sidecar problem"
+fi
+
 # Exact stop derives the socket exclusively from the validated generated
 # projection and ignores an ambient socket supplied by the caller.
 : > "$TMUX_CALLS"

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

@@ -32,10 +32,6 @@ packages/mosaic/framework/tools/tmux/test-send-message-socket.sh | requires a re
 packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its sibling)
 
 # --- single-suite directories: unmeasured in CI ---
-packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | unmeasured in CI image; stubs tmux via a fake bin dir, likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/glpi/test-list-http-status.sh | unmeasured in CI image; stub-based (#807 regression harness), likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/orchestrator/test-board-roll.sh | unmeasured in CI image; file-fixture based, likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasured in CI image; drives ci-wait.sh against a stub pipeline-status.sh, likely CI-fit; #1017 burndown
 
 # --- naming-boundary files the strict test-*.sh prefix cannot even name ---
 # (#1017: three independent censuses handled the microtest file three different
@@ -43,3 +39,20 @@ packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasu
 # recorded judgement. These lines ARE that judgement, signed.)
 packages/mosaic/framework/tools/orchestrator/smoke-test.sh | behavior smoke checks for coord continue/run workflows, run manually by orchestrator seats; unmeasured in CI; #1017 burndown
 packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh | #973 instrument self-test, run as a precondition of the validate-973 evidence procedure rather than as a standing CI suite; #1017 burndown candidate
+
+# --- tools/fleet: precondition is unsatisfiable in the CI image (#1271) ---
+# Signed by fred (sb-it-1-dt, 2026-08-16) at origin/next 476db12.
+# This suite asserts the launcher's behaviour when `mosaic` and `pi` are MISSING.
+# It shims fakes into $FAKE_BIN, but the constructed PANE_PATH always ends in the
+# real system path, so on a host that installs those binaries the missing-binary
+# cases cannot be measured at all. The suite's own guard (line 103) says so and
+# fails rather than reporting a pass it cannot back. That guard is correct.
+# The error was wiring the suite into CI: #1017 (c56483eb) enumerated it and
+# dropped this exclusion, and the CI image provides `pi` in the system path, so
+# it has failed on every pipeline since. Measured 2026-08-16 across pipelines
+# 2444 (#1256), 2438 (#1240) and 2441 (#1017-quality): exactly one FAIL line in
+# each full log, identical, this assertion; control `zzz-not-present-zzz` -> 0.
+# Burn-down and the full measurement are tracked in #1271; unwired by PR #1270.
+# Because test:framework-shell is one && chain and this sat at position 44 of 48,
+# the four suites after it had not run at all since the merge.
+packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | precondition unsatisfiable in the CI image: asserts missing-binary behaviour, but PANE_PATH always ends in the system path and the image provides `pi` there; guard at line 103 fails by design rather than passing unmeasured. Burn down by controlling the tail of PANE_PATH inside the test. NOT by removing `pi` from the image: the CI image installs @earendil-works/[email protected] deliberately (measured in pipeline 2444's test-step log), and other suites depend on that pin. Burn-down tracked in #1271

packages/mosaic/package.json

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

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { fleetAgentEnvDir, fleetRolesLocalDir } from '../fleet/brain-home.js';
 import type { Command } from 'commander';
 import {
   executeFleetAgentMutation,
@@ -149,9 +150,9 @@ async function executeCommand(
     request,
     mosaicHome,
     rosterPath,
-    agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+    agentEnvDir: fleetAgentEnvDir(mosaicHome),
     rolesDir: join(mosaicHome, 'fleet', 'roles'),
-    overrideDir: join(mosaicHome, 'fleet', 'roles.local'),
+    overrideDir: fleetRolesLocalDir(mosaicHome),
     dryRun: forceDryRun || opts.dryRun === true,
     ...(deps.projectionApplier === undefined ? {} : { projectionApplier: deps.projectionApplier }),
   });

packages/mosaic/src/commands/fleet-migration-command.ts

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { fleetAgentEnvDir, fleetRolesLocalDir } from '../fleet/brain-home.js';
 import type { Command } from 'commander';
 import {
   parseV1MigrationObservations,
@@ -120,11 +121,11 @@ export function registerFleetMigrationCommand(
           observations,
           personaDirs: {
             rolesDir: deps.rolesDir ?? join(mosaicHome, 'fleet', 'roles'),
-            overrideDir: deps.overrideDir ?? join(mosaicHome, 'fleet', 'roles.local'),
+            overrideDir: deps.overrideDir ?? fleetRolesLocalDir(mosaicHome),
           },
           environment: {
             mosaicHome,
-            agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+            agentEnvDir: fleetAgentEnvDir(mosaicHome),
           },
         });
         printJson(preview);

packages/mosaic/src/commands/fleet-personas.ts

@@ -30,19 +30,21 @@ import { lstat, readFile, readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, isAbsolute, join, sep } from 'node:path';
 import type { Command } from 'commander';
+import { fleetRolesLocalDir } from '../fleet/brain-home.js';
 
 function defaultMosaicHome(): string {
   return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 }
 
-/** Baseline persona role contracts (reseeded on update). */
+/** Baseline persona role contracts (reseeded on update; config home — framework). */
 export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
   return join(mosaicHome, 'fleet', 'roles');
 }
 
-/** PRESERVE-protected override layer (survives update; wins on merge). */
+/** PRESERVE-protected override layer (survives update; wins on merge).
+ * Brain home (`~/.mosaic/fleet/roles.local`) when a brain is active. */
 export function defaultOverrideDir(mosaicHome = defaultMosaicHome()): string {
-  return join(mosaicHome, 'fleet', 'roles.local');
+  return fleetRolesLocalDir(mosaicHome);
 }
 
 /**

packages/mosaic/src/commands/fleet-profiles.ts

@@ -25,6 +25,7 @@ import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import type { Command } from 'commander';
 import YAML from 'yaml';
+import { fleetProfilesDir } from '../fleet/brain-home.js';
 import {
   defaultOverrideDir,
   extractClassesFromDir,
@@ -36,9 +37,10 @@ function defaultMosaicHome(): string {
   return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 }
 
-/** Directory holding the seeded profile yaml files. */
+/** Directory holding the seeded profile yaml files — brain home when active
+ * (user working copies, committed), else the config home seed. */
 export function defaultProfilesDir(mosaicHome = defaultMosaicHome()): string {
-  return join(mosaicHome, 'fleet', 'profiles');
+  return fleetProfilesDir(mosaicHome);
 }
 
 /** Directory holding the persona role contracts. */

packages/mosaic/src/commands/fleet-regen-command.ts

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { join, relative, resolve } from 'node:path';
 import type { Command } from 'commander';
 import type { CommandRunner } from './fleet.js';
+import { fleetAgentEnvDir } from '../fleet/brain-home.js';
 import {
   applyPreparedGeneratedAgentEnvironmentProjection,
   prepareGeneratedAgentEnvironmentProjection,
@@ -153,7 +154,7 @@ export async function executeFleetRegen(
   options: FleetRegenOptions,
 ): Promise<FleetRegenResult> {
   const mosaicHome = defaultMosaicHome(deps);
-  const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
+  const agentEnvDir = fleetAgentEnvDir(mosaicHome);
   const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
   const readRoster = deps.readRoster ?? defaultReadRoster(deps, mosaicHome);
   const prepare = deps.prepareProjection ?? prepareGeneratedAgentEnvironmentProjection;

packages/mosaic/src/commands/fleet-roster-v2-dispatch.spec.ts

@@ -0,0 +1,323 @@
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { registerFleetCommand, type CommandResult, type CommandRunner } from './fleet.js';
+
+/**
+ * #1237: the v1-only commands (`ps`, `install`, `install-systemd`, `add`,
+ * `remove`) rejected a roster-v2 fleet outright, so a greenfield v2 box could
+ * never get its units placed. These tests pin the three behaviours that fix
+ * gives it, and the two it deliberately does NOT give it.
+ *
+ * The load-bearing negative is that `install` on v2 writes no generated env:
+ * the reconciler owns that file through projectRosterV2AgentGeneratedEnv, and a
+ * second writer here — necessarily through the v1 mapping — is exactly the
+ * drift the #791 single-SSOT invariant exists to prevent.
+ */
+
+const rosterV2 = `
+version: 2
+generation: 4
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: /srv/mosaic
+  runtime: pi
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: coder0
+    alias: Coder 0
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: high
+    tool_policy: code
+    working_directory: /srv/mosaic
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+  - name: coder1
+    alias: Coder 1
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: medium
+    tool_policy: code
+    working_directory: /srv/other
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+`;
+
+let tempHome: string | undefined;
+const savedHome = process.env.HOME;
+const savedMosaicHome = process.env.MOSAIC_HOME;
+
+afterEach(async (): Promise<void> => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+  if (savedHome === undefined) delete process.env.HOME;
+  else process.env.HOME = savedHome;
+  if (savedMosaicHome === undefined) delete process.env.MOSAIC_HOME;
+  else process.env.MOSAIC_HOME = savedMosaicHome;
+  if (tempHome) await rm(tempHome, { recursive: true, force: true });
+  tempHome = undefined;
+});
+
+/**
+ * A HOME with a roster-v2 fleet and nothing else — the greenfield shape, before
+ * anything has been installed, applied or started.
+ */
+async function v2Home(): Promise<string> {
+  tempHome = await mkdtemp(join(tmpdir(), 'mosaic-fleet-v2-dispatch-'));
+  process.env.HOME = tempHome;
+  delete process.env.MOSAIC_HOME;
+  const mosaicHome = join(tempHome, '.config', 'mosaic');
+  for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
+    await mkdir(join(mosaicHome, directory), { recursive: true, mode: 0o700 });
+  }
+  await writeFile(join(mosaicHome, 'fleet', 'roster.yaml'), rosterV2, { mode: 0o600 });
+  await writeFile(join(mosaicHome, 'fleet', 'roles', 'code.md'), '`class: code`\n\n# code\n', {
+    mode: 0o600,
+  });
+  return mosaicHome;
+}
+
+/**
+ * Stands in for a box where nothing is running: every systemctl and tmux probe
+ * fails the way it does before the holder has ever started. `ps` must survive
+ * this — it is the command an operator reaches for to find out *why* there is
+ * no seat, so it has to report the emptiness rather than fail on it.
+ */
+const greenfieldRunner: CommandRunner = async (command): Promise<CommandResult> => {
+  if (command === 'tmux') {
+    return { stdout: '', stderr: 'no server running on /tmp/tmux-1000/mosaic-fleet', exitCode: 1 };
+  }
+  return { stdout: '', stderr: '', exitCode: 1 };
+};
+
+function program(runner: CommandRunner = greenfieldRunner): Command {
+  const result = new Command();
+  result.exitOverride();
+  registerFleetCommand(result, { runner, frameworkRoot: resolve(process.cwd(), 'framework') });
+  return result;
+}
+
+function capture(): string[] {
+  const lines: string[] = [];
+  vi.spyOn(console, 'log').mockImplementation((value: string): void => {
+    lines.push(value);
+  });
+  return lines;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('mosaic fleet ps — roster v2', (): void => {
+  it('lists every v2 agent on a greenfield box with nothing running, and does not throw', async (): Promise<void> => {
+    await v2Home();
+    const lines = capture();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'ps', '--json']),
+    ).resolves.toBeDefined();
+
+    const rows = JSON.parse(lines.join('\n')) as {
+      name: string;
+      runtime: string;
+      alias?: string;
+      paneAlive: boolean;
+      source: string;
+    }[];
+    expect(rows.map((row) => row.name).sort()).toEqual(['coder0', 'coder1']);
+    // The v2 roster's per-agent fields must survive the read model, not be
+    // flattened into defaults.
+    expect(rows.every((row) => row.runtime === 'pi')).toBe(true);
+    expect(rows.find((row) => row.name === 'coder0')?.alias).toBe('Coder 0');
+    // Nothing is running, and that is a report, not an error.
+    expect(rows.every((row) => row.paneAlive === false)).toBe(true);
+    expect(rows.every((row) => row.source === 'roster')).toBe(true);
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+});
+
+describe('mosaic fleet install — roster v2', (): void => {
+  it('places the tool files and unit templates', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    capture();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']),
+    ).resolves.toBeDefined();
+
+    // Units live in the systemd user dir, not under the Mosaic home.
+    const systemdUserDir = join(tempHome!, '.config', 'systemd', 'user');
+    for (const unit of [
+      'mosaic-tmux-holder.service',
+      '[email protected]',
+      '[email protected]',
+    ]) {
+      expect(await exists(join(systemdUserDir, unit))).toBe(true);
+    }
+    const launcher = join(mosaicHome, 'tools', 'fleet', 'start-agent-session.sh');
+    expect(await exists(launcher)).toBe(true);
+    expect((await stat(launcher)).mode & 0o777).toBe(0o755);
+  });
+
+  it('writes NO generated env — that file belongs to the reconciler (#791)', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    capture();
+
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    const agentDir = join(mosaicHome, 'fleet', 'agents');
+    expect(await readdir(agentDir)).toEqual([]);
+  });
+
+  it('tells the operator which command does own the env', async (): Promise<void> => {
+    await v2Home();
+    const lines = capture();
+
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    expect(lines.join('\n')).toContain('mosaic fleet apply');
+  });
+});
+
+describe('[email protected]', (): void => {
+  const unitPath = resolve(process.cwd(), 'framework', 'systemd', 'user', '[email protected]');
+
+  /** The single `ConditionPathExists=` value declared by the unit template. */
+  async function conditionPath(): Promise<string> {
+    const unit = await readFile(unitPath, 'utf8');
+    const matches = unit.match(/^ConditionPathExists=(.+)$/gm) ?? [];
+    expect(matches).toHaveLength(1);
+    return matches[0]!.slice('ConditionPathExists='.length).trim();
+  }
+
+  it('will not attempt a seat before the reconciler has written its env', async (): Promise<void> => {
+    // The pairing that makes "install writes no env" safe: install enables the
+    // unit (WantedBy=default.target) but does not start it, so without this
+    // condition a reboot between `install` and the first `apply` would run
+    // ExecStart against an absent env file and fail every seat unit.
+    expect(await conditionPath()).toBe('%h/.config/mosaic/fleet/agents/%i.env.generated');
+  });
+
+  /**
+   * The two halves of the guard's *effect*, which no assertion on the literal
+   * string can cover on its own.
+   *
+   * Measured end to end on a real box (canary, 2026-08-16) rather than inferred:
+   * with the condition, `systemctl --user start mosaic-agent@<name>` on an agent
+   * with no generated env returns rc=0, `Result=success`, `ConditionResult=no`,
+   * and journals "skipped, unmet condition check". With the condition removed by
+   * drop-in and nothing else changed, the same start returns rc=1,
+   * `Result=exit-code`, `ExecMainStatus=64`, and the unit enters `failed`.
+   *
+   * systemd is not available in this suite, so these two tests pin the parts
+   * that can drift in code: the condition naming a *different* file than the one
+   * the fleet actually writes, and the launcher quietly becoming tolerant of an
+   * absent env — either of which turns the condition into decoration while the
+   * literal-string assertion above still passes.
+   */
+  it('guards exactly the file the fleet writes, so the two cannot drift apart', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    const rendered = (await conditionPath()).replace('%h', tempHome!).replace('%i', 'coder0');
+
+    // The path an installed fleet actually places for this agent.
+    expect(rendered).toBe(join(mosaicHome, 'fleet', 'agents', 'coder0.env.generated'));
+  });
+
+  it('guards a real failure — the launcher rejects an absent generated env', async (): Promise<void> => {
+    await v2Home();
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    // Exactly what ExecStart runs, against the state the condition exists to
+    // catch: unit enabled, reconciler has not written env yet.
+    const launched = await new Promise<{ code: number | null; stderr: string }>((settle) => {
+      const child = execFile(
+        '/bin/bash',
+        [
+          '--noprofile',
+          '--norc',
+          join(tempHome!, '.config', 'mosaic', 'tools', 'fleet', 'start-agent-session.sh'),
+          'coder0',
+        ],
+        { env: { HOME: tempHome!, MOSAIC_AGENT_NAME: 'coder0', PATH: '/usr/bin:/bin' } },
+        (_error, _stdout, stderr) => {
+          settle({ code: child.exitCode, stderr });
+        },
+      );
+    });
+
+    expect(launched.code).not.toBe(0);
+    expect(launched.stderr).toContain('missing-file');
+  });
+});
+
+describe('mosaic fleet add / remove — roster v2', (): void => {
+  it('add refuses, and names the two-step v2 sequence instead of inventing defaults', async (): Promise<void> => {
+    await v2Home();
+
+    await expect(
+      program().parseAsync([
+        'node',
+        'mosaic',
+        'fleet',
+        'add',
+        'coder2',
+        '--runtime',
+        'pi',
+        '--class',
+        'code',
+      ]),
+    ).rejects.toThrow(/mosaic fleet create[\s\S]*mosaic fleet apply/);
+  });
+
+  it('remove refuses, and names delete plus apply', async (): Promise<void> => {
+    await v2Home();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
+    ).rejects.toThrow(/mosaic fleet delete coder1[\s\S]*mosaic fleet apply/);
+  });
+
+  // Note: this one passes on the unmodified tree too — there `remove` throws in
+  // the v1 parser, before it can touch anything. It is a regression guard on the
+  // ordering of the new guard clause, not evidence that the fix works.
+  it('refuses BEFORE mutating the roster', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
+    const before = await readFile(rosterPath, 'utf8');
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
+    ).rejects.toThrow();
+
+    expect(await readFile(rosterPath, 'utf8')).toBe(before);
+  });
+});

packages/mosaic/src/commands/fleet.ts

@@ -13,6 +13,7 @@ import {
 import { randomUUID } from 'node:crypto';
 import { homedir, hostname, userInfo } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { fleetAgentEnvDir } from '../fleet/brain-home.js';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import * as readline from 'node:readline';
@@ -34,6 +35,7 @@ export {
   resolveInstalledFleetRosterPath,
 } from '../fleet/fleet-roster-v1.js';
 export type { FleetAgent, FleetRoster } from '../fleet/fleet-roster-v1.js';
+import { parseRosterV2 } from '../fleet/roster-v2.js';
 import {
   registerFleetAgentCrudCommands,
   type FleetAgentCrudCommandDeps,
@@ -157,7 +159,7 @@ export function resolveFleetPaths(mosaicHome = defaultMosaicHome()): FleetPaths
     fleetToolsDir: join(mosaicHome, 'tools', 'fleet'),
     tmuxToolsDir: join(mosaicHome, 'tools', 'tmux'),
     systemdUserDir: join(homedir(), '.config', 'systemd', 'user'),
-    agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+    agentEnvDir: fleetAgentEnvDir(mosaicHome),
   };
 }
 
@@ -820,7 +822,7 @@ export function buildEnableLingerCommand(user: string): string[] {
  */
 export async function enableFleetUnits(
   runner: CommandRunner,
-  roster: FleetRoster,
+  roster: { readonly agents: readonly { readonly name: string }[] },
   opts: { enable?: boolean },
 ): Promise<void> {
   if (opts.enable === false) {
@@ -1527,7 +1529,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
       await installFleet(cmd, frameworkRoot);
-      const roster = await loadRosterForCommand(cmd);
+      // Unit enablement needs agent names only, so it reads either version.
+      const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
     });
 
@@ -1537,7 +1540,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
       await installFleet(cmd, frameworkRoot);
-      const roster = await loadRosterForCommand(cmd);
+      // Unit enablement needs agent names only, so it reads either version.
+      const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
     });
 
@@ -1688,7 +1692,9 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .action(async (opts: { json?: boolean }) => {
       const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
       const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
-      const roster = await loadRosterForCommand(cmd);
+      // ps only reads, so it takes the version-agnostic read model rather than
+      // the v1 parser, which rejects a v2 roster outright.
+      const roster = await loadRosterReadModel(cmd);
       const { tenant_id, host } = getDefaultTenantAndHost();
       const nowMs = Date.now();
 
@@ -1908,6 +1914,16 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
           start: boolean;
         },
       ) => {
+        if (await usesRosterV2ControlPlane(cmd)) {
+          // command.error, not a bare throw: this is operator guidance, and a
+          // bare throw reaches the top level uncaught and prints it under a Node
+          // stack trace. Measured on canary — the message is the whole point of
+          // the refusal, so it has to arrive readable.
+          cmd.error(rosterV2MutationGuidance('add', 'create', name), {
+            code: 'fleet.roster-v2',
+            exitCode: 1,
+          });
+        }
         if (!VALID_FLEET_RUNTIMES.includes(opts.runtime)) {
           throw new Error(
             `Invalid runtime "${opts.runtime}". Valid runtimes: ${VALID_FLEET_RUNTIMES.join(', ')}.`,
@@ -1973,6 +1989,12 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Remove an agent from the fleet roster')
     .option('--keep-files', 'Skip deleting env and heartbeat files')
     .action(async (name: string, opts: { keepFiles?: boolean }) => {
+      if (await usesRosterV2ControlPlane(cmd)) {
+        cmd.error(rosterV2MutationGuidance('remove', 'delete', name), {
+          code: 'fleet.roster-v2',
+          exitCode: 1,
+        });
+      }
       const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
       const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
       const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
@@ -2331,7 +2353,9 @@ export function registerFleetAgentCommands(
 async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
   const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
   assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
-  const roster = await loadRosterForCommand(cmd);
+  // Read model first: every file this function places is roster-independent, and
+  // the v1 parser would reject a v2 roster before any of them were written.
+  const roster = await loadRosterReadModel(cmd);
   await ensureFleetHolderIdentity(activePaths.mosaicHome);
   await mkdir(activePaths.fleetToolsDir, { recursive: true });
   await mkdir(activePaths.tmuxToolsDir, { recursive: true });
@@ -2391,16 +2415,30 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
     join(activePaths.systemdUserDir, '[email protected]'),
   );
 
-  for (const agent of roster.agents) {
+  // On roster v2 the reconciler owns the generated env: `apply` writes it and
+  // `regen` rebuilds it, both from projectRosterV2AgentGeneratedEnv. Writing it
+  // here too — necessarily through the v1 mapping — would be the third writer of
+  // one file and would break the #791 single-SSOT invariant. So v2 gets the tool
+  // files and the units, and nothing else.
+  if (roster.version === 2) {
+    console.log(
+      `Installed fleet tools and systemd units for ${roster.agents.length} agent(s). ` +
+        `Generated env is owned by the reconciler on roster v2 — run: mosaic fleet apply --expected-generation <n>`,
+    );
+    return;
+  }
+
+  const v1Roster = await loadRosterForCommand(cmd);
+  for (const agent of v1Roster.agents) {
     await writeAgentEnvironmentProjection({
       mosaicHome: activePaths.mosaicHome,
       agentEnvDir: activePaths.agentEnvDir,
       agentName: agent.name,
-      generated: generateAgentEnvValues(roster, agent),
+      generated: generateAgentEnvValues(v1Roster, agent),
     });
   }
 
-  console.log(`Installed fleet files for ${roster.agents.length} agent(s).`);
+  console.log(`Installed fleet files for ${v1Roster.agents.length} agent(s).`);
 }
 
 async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
@@ -2427,6 +2465,77 @@ async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
   );
 }
 
+/**
+ * `add`/`remove` and `create`/`delete` are not two spellings of one operation.
+ * The v1 pair edits the roster *and* drives systemd; the v2 pair is documented
+ * as changing desired state "without runtime actions", leaving convergence to
+ * `apply`. `add` also collects four fields where a v2 agent requires eleven, so
+ * routing it to `create` would mean inventing provider, alias, reasoning and
+ * tool-policy defaults on the operator's behalf. Refusing with the real command
+ * is honest; silently guessing an agent's provider is not.
+ */
+function rosterV2MutationGuidance(
+  v1Command: 'add' | 'remove',
+  v2Command: 'create' | 'delete',
+  name: string,
+): string {
+  const target = v2Command === 'delete' ? ` ${name}` : '';
+  return (
+    `mosaic fleet ${v1Command} does not operate on a roster-v2 fleet. ` +
+    `Roster v2 separates desired state from convergence:\n` +
+    `  1. mosaic fleet ${v2Command}${target} --expected-generation <current> ` +
+    `${v2Command === 'create' ? "--agent '<json>' " : ''}` +
+    `(edits the roster only)\n` +
+    `  2. mosaic fleet apply --expected-generation <new> (converges systemd and tmux)\n` +
+    `Read the current generation with: mosaic fleet status`
+  );
+}
+
+/**
+ * The read-only fields shared by roster v1 and v2, for the commands that only
+ * ever *read* the roster (`ps`, and unit enablement inside `install`).
+ *
+ * This is deliberately NOT a v2→v1 downshift. A downshifted `FleetRoster` would
+ * be accepted by `generateAgentEnvValues`, and that would make a third writer of
+ * `fleet/agents/<name>.env.generated` — through the v1 mapping — breaking the
+ * #791 single-SSOT invariant that {@link projectRosterV2AgentGeneratedEnv} is
+ * documented to hold. Keeping the read model this small makes that misuse
+ * impossible: there is nothing here to write a roster or an env file back from.
+ */
+interface FleetRosterReadModel {
+  readonly version: 1 | 2;
+  readonly tmux: { readonly socketName: string; readonly holderSession: string };
+  readonly agents: readonly {
+    readonly name: string;
+    readonly alias?: string;
+    readonly runtime: string;
+  }[];
+}
+
+/** Reads either roster version into the shared read-only view. */
+async function loadRosterReadModel(cmd: Command): Promise<FleetRosterReadModel> {
+  const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
+  const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
+  if (!(await usesRosterV2ControlPlane(cmd))) {
+    const v1 = await loadRosterAtPath(cmd, path);
+    return {
+      version: 1,
+      tmux: { socketName: v1.tmux.socketName, holderSession: v1.tmux.holderSession },
+      agents: v1.agents,
+    };
+  }
+  try {
+    const v2 = parseRosterV2(await readFleetRosterText(path), 'yaml');
+    return {
+      version: 2,
+      tmux: { socketName: v2.tmux.socketName, holderSession: v2.tmux.holderSession },
+      agents: v2.agents,
+    };
+  } catch (error) {
+    reportFleetRosterConfigurationError(cmd, error);
+  }
+}
+
 async function loadRosterFromAgentCommand(
   command: Command,
   mosaicHomeOverride?: string,

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

@@ -349,3 +349,90 @@ describe('registerRuntimeLaunchers — claudex (EXPERIMENTAL overlay)', () => {
     expect(mockExit).not.toHaveBeenCalled();
   });
 });
+
+// ─── Seat harness homes (MOSAIC-D-002, brain-home split) ────────────────────
+
+import { activeSeatDir, seatPersonaOverlay } from './launch.js';
+
+describe('activeSeatDir — per-agent harness home resolution', () => {
+  let root: string;
+  const savedAgentName = process.env['MOSAIC_AGENT_NAME'];
+  const savedBrainHome = process.env['MOSAIC_BRAIN_HOME'];
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'mosaic-seat-home-'));
+    delete process.env['MOSAIC_BRAIN_HOME'];
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+    if (savedAgentName === undefined) {
+      delete process.env['MOSAIC_AGENT_NAME'];
+    } else {
+      process.env['MOSAIC_AGENT_NAME'] = savedAgentName;
+    }
+    if (savedBrainHome !== undefined) {
+      process.env['MOSAIC_BRAIN_HOME'] = savedBrainHome;
+    } else {
+      delete process.env['MOSAIC_BRAIN_HOME'];
+    }
+  });
+
+  it('resolves the seat dir when MOSAIC_BRAIN_HOME carries the seat', () => {
+    const seat = join(root, 'brain', 'fleet', 'agents', 'coder0');
+    mkdirSync(seat, { recursive: true });
+    process.env['MOSAIC_AGENT_NAME'] = 'coder0';
+    process.env['MOSAIC_BRAIN_HOME'] = join(root, 'brain');
+
+    expect(activeSeatDir(join(root, 'config', 'mosaic'))).toBe(seat);
+  });
+
+  it('returns undefined without an agent name (bare launches stay shared)', () => {
+    delete process.env['MOSAIC_AGENT_NAME'];
+    expect(activeSeatDir(join(root, 'config', 'mosaic'))).toBeUndefined();
+  });
+
+  it('returns undefined when the seat dir does not exist in the brain', () => {
+    process.env['MOSAIC_AGENT_NAME'] = 'ghost';
+    process.env['MOSAIC_BRAIN_HOME'] = join(root, 'brain');
+    mkdirSync(join(root, 'brain', 'fleet', 'agents'), { recursive: true });
+
+    expect(activeSeatDir(join(root, 'config', 'mosaic'))).toBeUndefined();
+  });
+
+  it.each(['../escape', 'a/b', '.hidden-start', '', 'spaced name'])(
+    'rejects unsafe agent name %j (path traversal cannot leave the seat store)',
+    (name: string) => {
+      process.env['MOSAIC_AGENT_NAME'] = name;
+      process.env['MOSAIC_BRAIN_HOME'] = join(root, 'brain');
+
+      expect(activeSeatDir(join(root, 'config', 'mosaic'))).toBeUndefined();
+    },
+  );
+
+  it('seatPersonaOverlay renders the seat SOUL.md as an overlay block', () => {
+    const seat = join(root, 'brain', 'fleet', 'agents', 'coder0');
+    mkdirSync(seat, { recursive: true });
+    writeFileSync(join(seat, 'SOUL.md'), '# coder0 — code seat persona\n\nShips tested code.\n');
+    process.env['MOSAIC_AGENT_NAME'] = 'coder0';
+    process.env['MOSAIC_BRAIN_HOME'] = join(root, 'brain');
+
+    const overlay = seatPersonaOverlay(join(root, 'config', 'mosaic'));
+    expect(overlay).toContain('## Seat Persona');
+    expect(overlay).toContain('coder0 — code seat persona');
+  });
+
+  it('seatPersonaOverlay is empty when the seat carries no SOUL.md', () => {
+    const seat = join(root, 'brain', 'fleet', 'agents', 'coder0');
+    mkdirSync(seat, { recursive: true });
+    process.env['MOSAIC_AGENT_NAME'] = 'coder0';
+    process.env['MOSAIC_BRAIN_HOME'] = join(root, 'brain');
+
+    expect(seatPersonaOverlay(join(root, 'config', 'mosaic'))).toBe('');
+  });
+
+  it('seatPersonaOverlay is empty when no agent name is set', () => {
+    delete process.env['MOSAIC_AGENT_NAME'];
+    expect(seatPersonaOverlay(join(root, 'config', 'mosaic'))).toBe('');
+  });
+});

packages/mosaic/src/commands/launch.ts

@@ -19,7 +19,7 @@ import {
 import { createHash, randomBytes } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { homedir, hostname } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import type { Command } from 'commander';
 import {
   buildResolvedFleetCommsBlock,
@@ -29,6 +29,7 @@ import {
 import { readRegularFileSecure } from '../fleet/secure-file.js';
 import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
+import { resolveBrainHome } from '../fleet/brain-home.js';
 import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
 import { runLeaseEnforcementDoctorCheck } from './lease-doctor-check.js';
 
@@ -64,9 +65,46 @@ const HARNESS_HOME_ENV: Record<RuntimeName, string> = {
   opencode: 'XDG_CONFIG_HOME',
 };
 
-/** Dedicated mosaic-owned home for a runtime: ~/.config/mosaic/.<runtime> */
+/** Dedicated mosaic-owned home for a runtime: ~/.config/mosaic/.<runtime>.
-function harnessHome(runtime: RuntimeName): string {
+ * With an active brain seat (MOSAIC_AGENT_NAME + seat dir in the brain home)
-  return join(MOSAIC_HOME, `.${runtime}`);
+ * the home is per-agent instead: <brainHome>/fleet/agents/<seat>/.<runtime> —
+ * per-agent sessions, settings, and auth inside the seat dir (canon §2,
+ * MOSAIC-D-002). Seat runtime dirs are dot-named so the brain's ignore policy
+ * (per-seat .pi/.claude/.codex dirs) keeps credential material untracked. */
+const SEAT_AGENT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+export function activeSeatDir(mosaicHome: string = MOSAIC_HOME): string | undefined {
+  const agent = process.env['MOSAIC_AGENT_NAME']?.trim();
+  if (
+    agent === undefined ||
+    agent === '' ||
+    !SEAT_AGENT_NAME_RE.test(agent) ||
+    agent.includes('..')
+  ) {
+    return undefined;
+  }
+  const brain = resolveBrainHome(mosaicHome);
+  if (resolve(brain) === resolve(mosaicHome)) return undefined; // no brain
+  const seat = join(brain, 'fleet', 'agents', agent);
+  return existsSync(seat) ? seat : undefined;
+}
+
+function harnessHome(runtime: RuntimeName, mosaicHome: string = MOSAIC_HOME): string {
+  const seat = activeSeatDir(mosaicHome);
+  if (seat !== undefined) return join(seat, `.${runtime}`);
+  return join(mosaicHome, `.${runtime}`);
+}
+
+/** Seat persona block: with an active brain seat, <seat>/SOUL.md layers
+ * persona on the root generic base (canon invariant; MOSAIC-D-002). The base
+ * SOUL stays load-on-demand — only the seat delta is injected by value.
+ * Empty string when no seat is active or the seat carries no SOUL.md. */
+export function seatPersonaOverlay(mosaicHome: string = MOSAIC_HOME): string {
+  const seatDir = activeSeatDir(mosaicHome);
+  if (seatDir === undefined) return '';
+  const seatSoul = readOptional(join(seatDir, 'SOUL.md'));
+  if (!seatSoul.trim()) return '';
+  return '## Seat Persona\n\n' + seatSoul.trim();
 }
 
 /**
@@ -182,6 +220,8 @@ function recordLaunch(runtime: RuntimeName, cliArgs: string[], yolo: boolean): v
       cli_version: CLI_VERSION,
       config_home: harnessHome(runtime),
       config_home_isolated: true,
+      config_home_kind: activeSeatDir() !== undefined ? 'seat' : 'runtime-shared',
+      agent_name: process.env['MOSAIC_AGENT_NAME']?.trim() || null,
       config_home_env: HARNESS_HOME_ENV[runtime] ?? null,
       argv: redactArgv(cliArgs),
       normative_fragments: normativeFragmentDigests(runtime),
@@ -569,6 +609,11 @@ For required push/merge/issue-close/release actions, execute without routine con
   if (soulLocal.trim()) {
     overlayBlocks.push('## Persona Overlay (SOUL.local.md)\n\n' + soulLocal.trim());
   }
+  // Seat persona (MOSAIC-D-002): per-seat SOUL.md layers on the generic base.
+  const seatPersona = seatPersonaOverlay(mosaicHome);
+  if (seatPersona !== '') {
+    overlayBlocks.push(seatPersona);
+  }
   const standardsLocal = readOptional(join(mosaicHome, 'STANDARDS.local.md'));
   if (standardsLocal.trim()) {
     overlayBlocks.push('## Standards Overlay (STANDARDS.local.md)\n\n' + standardsLocal.trim());

packages/mosaic/src/fleet/brain-home.spec.ts

@@ -0,0 +1,114 @@
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  brainHomeIsActive,
+  fleetAgentEnvDir,
+  fleetProfilesDir,
+  fleetRolesLocalDir,
+  fleetStateDir,
+  resolveBrainHome,
+  type BrainHomeOptions,
+} from './brain-home.js';
+
+describe('fleet brain-home resolution', (): void => {
+  let cleanup: string | undefined;
+
+  const savedBrainEnv = process.env['MOSAIC_BRAIN_HOME'];
+
+  beforeEach((): void => {
+    delete process.env['MOSAIC_BRAIN_HOME'];
+  });
+
+  afterEach(async (): Promise<void> => {
+    if (savedBrainEnv === undefined) {
+      delete process.env['MOSAIC_BRAIN_HOME'];
+    } else {
+      process.env['MOSAIC_BRAIN_HOME'] = savedBrainEnv;
+    }
+    if (cleanup !== undefined) {
+      await rm(cleanup, { recursive: true, force: true });
+      cleanup = undefined;
+    }
+  });
+
+  async function makeTmp(): Promise<string> {
+    const root = await mkdtemp(join(tmpdir(), 'mosaic-brain-home-'));
+    cleanup = root;
+    return root;
+  }
+
+  it('MOSAIC_BRAIN_HOME env wins over every other signal', (): void => {
+    process.env['MOSAIC_BRAIN_HOME'] = '/explicit/brain';
+    expect(resolveBrainHome('/any/mosaic-home')).toBe('/explicit/brain');
+    expect(fleetAgentEnvDir('/any/mosaic-home')).toBe('/explicit/brain/fleet/agents');
+    expect(brainHomeIsActive('/any/mosaic-home')).toBe(true);
+  });
+
+  it('injected envBrainHome wins identically (test seam)', (): void => {
+    const opts: BrainHomeOptions = { envBrainHome: '/injected/brain' };
+    expect(resolveBrainHome('/any/mosaic-home', opts)).toBe('/injected/brain');
+    expect(fleetAgentEnvDir('/any/mosaic-home', opts)).toBe('/injected/brain/fleet/agents');
+  });
+
+  it('a non-default mosaicHome never adopts the canonical brain (hermetic legacy)', (): void => {
+    const mosaicHome = '/tmp/not-the-default-config-home';
+    expect(resolveBrainHome(mosaicHome)).toBe(mosaicHome);
+    expect(brainHomeIsActive(mosaicHome)).toBe(false);
+    expect(fleetAgentEnvDir(mosaicHome)).toBe(join(mosaicHome, 'fleet', 'agents'));
+  });
+
+  it('the default config home adopts the brain when it carries fleet/agents', async (): Promise<void> => {
+    const root = await makeTmp();
+    const brain = join(root, 'brain');
+    await mkdir(join(brain, 'fleet', 'agents'), { recursive: true });
+    const configHome = join(root, 'config', 'mosaic');
+    const opts: BrainHomeOptions = { homes: { brain, configDefault: configHome } };
+
+    expect(resolveBrainHome(configHome, opts)).toBe(brain);
+    expect(fleetAgentEnvDir(configHome, opts)).toBe(join(brain, 'fleet', 'agents'));
+    expect(fleetRolesLocalDir(configHome, opts)).toBe(join(brain, 'fleet', 'roles.local'));
+    expect(fleetProfilesDir(configHome, opts)).toBe(join(brain, 'fleet', 'profiles'));
+    expect(fleetStateDir(configHome, opts)).toBe(join(brain, 'fleet'));
+    expect(brainHomeIsActive(configHome, opts)).toBe(true);
+  });
+
+  it('the default config home stays legacy when no brain exists', async (): Promise<void> => {
+    const root = await makeTmp();
+    const configHome = join(root, 'config', 'mosaic');
+    const opts: BrainHomeOptions = {
+      homes: { brain: join(root, 'brain'), configDefault: configHome },
+    };
+
+    expect(resolveBrainHome(configHome, opts)).toBe(configHome);
+    expect(brainHomeIsActive(configHome, opts)).toBe(false);
+  });
+
+  it('an empty MOSAIC_BRAIN_HOME is ignored, not treated as set', (): void => {
+    process.env['MOSAIC_BRAIN_HOME'] = '   ';
+    expect(resolveBrainHome('/tmp/legacy-home')).toBe('/tmp/legacy-home');
+  });
+
+  it('adoption requires fleet/agents specifically, not any brain content', async (): Promise<void> => {
+    const root = await makeTmp();
+    const brain = join(root, 'brain');
+    await mkdir(join(brain, 'fleet'), { recursive: true }); // fleet without agents
+    const configHome = join(root, 'config', 'mosaic');
+    const opts: BrainHomeOptions = { homes: { brain, configDefault: configHome } };
+
+    expect(resolveBrainHome(configHome, opts)).toBe(configHome);
+  });
+
+  it('real-home control: a host brain is adopted only through the default home', (): void => {
+    // Control on the un-injected path: this host carries ~/.mosaic/fleet/agents,
+    // so the default config home resolves to the brain or legacy — both valid
+    // canonical endpoints — while a non-default home never adopts.
+    const defaultHome = join(homedir(), '.config', 'mosaic');
+    const resolved = resolveBrainHome(defaultHome);
+    expect([defaultHome, join(homedir(), '.mosaic')]).toContain(resolved);
+    expect(resolveBrainHome(join(homedir(), 'elsewhere', 'mosaic'))).toBe(
+      join(homedir(), 'elsewhere', 'mosaic'),
+    );
+  });
+});

packages/mosaic/src/fleet/brain-home.ts

@@ -0,0 +1,76 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+/**
+ * Overridable resolution inputs (tests inject tmp homes; production reads
+ * the environment and the real home directory).
+ */
+export interface BrainHomeOptions {
+  /** Explicit brain home; defaults to `MOSAIC_BRAIN_HOME`. */
+  readonly envBrainHome?: string;
+  /**
+   * Canonical homes used for adoption. Defaults derive from the real
+   * `homedir()`: `{ brain: ~/.mosaic, configDefault: ~/.config/mosaic }`.
+   */
+  readonly homes?: { readonly brain: string; readonly configDefault: string };
+}
+
+/**
+ * Brain-home resolution — the three-tree fleet split (stack canon
+ * `docs/STRUCTURE-CANON.md` §2, first carried by the USC estate brain):
+ *
+ *   config home (~/.config/mosaic)  framework templates + dispatch state:
+ *                                   fleet/roles (baseline), fleet/roster.yaml,
+ *                                   fleet/run (heartbeats), fleet/services
+ *   brain home  (~/.mosaic)         user-owned fleet state, committed:
+ *                                   fleet/agents/<seat>.env.*, fleet/roles.local,
+ *                                   fleet/profiles working copies
+ *
+ * Resolution order:
+ *   1. `MOSAIC_BRAIN_HOME` env (explicit, always wins)
+ *   2. canonical `~/.mosaic` — adopted ONLY when mosaicHome is the real
+ *      default config home AND `~/.mosaic/fleet/agents` exists. Custom
+ *      `--mosaic-home` values (tests, sandboxes, canaries) never trigger
+ *      adoption, keeping them hermetic and deterministic.
+ *   3. mosaicHome itself (legacy single-tree behavior).
+ */
+export function resolveBrainHome(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  const explicit = options.envBrainHome ?? process.env['MOSAIC_BRAIN_HOME'];
+  if (explicit !== undefined && explicit.trim() !== '') {
+    return explicit;
+  }
+  const homes = options.homes ?? {
+    brain: join(homedir(), '.mosaic'),
+    configDefault: join(homedir(), '.config', 'mosaic'),
+  };
+  if (resolve(mosaicHome) !== resolve(homes.configDefault)) {
+    return mosaicHome;
+  }
+  return existsSync(join(homes.brain, 'fleet', 'agents')) ? homes.brain : mosaicHome;
+}
+
+/** True when fleet state resolves somewhere other than the config home. */
+export function brainHomeIsActive(mosaicHome: string, options: BrainHomeOptions = {}): boolean {
+  return resolve(resolveBrainHome(mosaicHome, options)) !== resolve(mosaicHome);
+}
+
+/** Fleet state root (brain home when active, else the config home). */
+export function fleetStateDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(resolveBrainHome(mosaicHome, options), 'fleet');
+}
+
+/** Seat launch envs — `<brainHome>/fleet/agents` when a brain is active. */
+export function fleetAgentEnvDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(fleetStateDir(mosaicHome, options), 'agents');
+}
+
+/** PRESERVE-protected persona override layer — `<brainHome>/fleet/roles.local`. */
+export function fleetRolesLocalDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(fleetStateDir(mosaicHome, options), 'roles.local');
+}
+
+/** System-type profiles (user working copies) — `<brainHome>/fleet/profiles`. */
+export function fleetProfilesDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(fleetStateDir(mosaicHome, options), 'profiles');
+}

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

@@ -3,6 +3,7 @@ import { lstat, open, readFile, unlink, type FileHandle } from 'node:fs/promises
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { fleetAgentEnvDir } from './brain-home.js';
 import {
   applyPreparedAgentEnvironmentProjection,
   prepareAgentEnvironmentProjection,
@@ -617,7 +618,7 @@ function defaultPrepareProjections(
         (agent: FleetRosterV2Agent): Promise<PreparedAgentEnvironmentProjection> =>
           prepareAgentEnvironmentProjection({
             mosaicHome,
-            agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+            agentEnvDir: fleetAgentEnvDir(mosaicHome),
             agentName: agent.name,
             generated: projectRosterV2AgentGeneratedEnv(roster, agent),
           }),

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

@@ -176,6 +176,52 @@ describe('generated fleet agent environment boundary', (): void => {
     expect((await stat(result.generatedPath)).mode & 0o777).toBe(0o600);
   });
 
+  it('brain home: accepts and writes projections under MOSAIC_BRAIN_HOME/fleet/agents', async (): Promise<void> => {
+    const savedBrainHome = process.env['MOSAIC_BRAIN_HOME'];
+    try {
+      cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
+      const mosaicHome = join(cleanup, 'config-home');
+      const brainHome = join(cleanup, 'brain');
+      const agentEnvDir = join(brainHome, 'fleet', 'agents');
+      process.env['MOSAIC_BRAIN_HOME'] = brainHome;
+
+      const result = await writeAgentEnvironmentProjection({
+        mosaicHome,
+        agentEnvDir,
+        agentName: 'coder0',
+        generated: generatedValues,
+      });
+
+      // Projection landed in the brain tree, not under the config home.
+      expect(result.generatedPath).toBe(join(agentEnvDir, 'coder0.env.generated'));
+      expect((await stat(join(brainHome, 'fleet'))).mode & 0o777).toBe(0o700);
+      expect((await stat(agentEnvDir)).mode & 0o777).toBe(0o700);
+      expect((await stat(result.generatedPath)).mode & 0o777).toBe(0o600);
+      await expect(stat(join(mosaicHome, 'fleet'))).rejects.toThrow();
+
+      // A config-home agentEnvDir is now REJECTED while the brain is active —
+      // the boundary must not silently split state across two trees.
+      let rejected: unknown;
+      try {
+        await writeAgentEnvironmentProjection({
+          mosaicHome,
+          agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+          agentName: 'coder1',
+          generated: { ...generatedValues, MOSAIC_AGENT_NAME: 'coder1' },
+        });
+      } catch (caught: unknown) {
+        rejected = caught;
+      }
+      expect(rejected).toBeInstanceOf(AgentEnvBoundaryError);
+    } finally {
+      if (savedBrainHome === undefined) {
+        delete process.env['MOSAIC_BRAIN_HOME'];
+      } else {
+        process.env['MOSAIC_BRAIN_HOME'] = savedBrainHome;
+      }
+    }
+  });
+
   it('regenerates desired keys, relocates safe legacy local data, and quarantines forbidden legacy input', async (): Promise<void> => {
     cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
     const mosaicHome = join(cleanup, 'mosaic');

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

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { fleetAgentEnvDir, resolveBrainHome } from './brain-home.js';
 import { compareCodePoints } from './deterministic-order.js';
 
 export type AgentEnvironmentKind = 'generated' | 'local';
@@ -528,12 +529,15 @@ async function validatePrivateProjectionDirectory(
   mosaicHome: string,
   agentEnvDir: string,
 ): Promise<void> {
-  const fleetDir = join(mosaicHome, 'fleet');
+  // Brain-home split (canon §2): seat envs live under the brain home's
-  const expectedAgentEnvDir = join(fleetDir, 'agents');
+  // fleet/agents when a brain is active; roster + templates stay config-home.
+  const expectedAgentEnvDir = fleetAgentEnvDir(mosaicHome);
   if (resolve(agentEnvDir) !== resolve(expectedAgentEnvDir)) {
     throw new AgentEnvBoundaryError('unsafe-directory', '(directory)', agentEnvDir);
   }
-  await assertManagedDirectoryIfPresent(mosaicHome, false);
+  const stateHome = resolveBrainHome(mosaicHome);
+  const fleetDir = join(stateHome, 'fleet');
+  await assertManagedDirectoryIfPresent(stateHome, false);
   await assertManagedDirectoryIfPresent(fleetDir, false);
   await assertManagedDirectoryIfPresent(agentEnvDir, true);
 }
@@ -543,8 +547,9 @@ async function ensurePrivateProjectionDirectory(
   agentEnvDir: string,
 ): Promise<void> {
   await validatePrivateProjectionDirectory(mosaicHome, agentEnvDir);
-  const fleetDir = join(mosaicHome, 'fleet');
+  const stateHome = resolveBrainHome(mosaicHome);
-  await ensureManagedDirectory(mosaicHome, false);
+  const fleetDir = join(stateHome, 'fleet');
+  await ensureManagedDirectory(stateHome, false);
   await ensureManagedDirectory(fleetDir, false);
   await ensureManagedDirectory(agentEnvDir, true);
 }

packages/mosaic/src/platform/detect.ts

@@ -1,4 +1,3 @@
-import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform } from 'node:os';
 
@@ -22,15 +21,18 @@ export function getShellProfilePath(): string | null {
 
   const shell = detectShell();
   switch (shell) {
+    // Both of these deliberately avoid the interactive-only rc files.
+    // Debian's default .bashrc returns early for non-interactive shells, so a
+    // PATH line appended to it never runs for `bash -lc`, systemd units, or
+    // agent seats — an install could report success and still leave `mosaic`
+    // unreachable. .profile is read by login shells and sources .bashrc for
+    // interactive ones, so one line covers both; .zshenv is zsh's equivalent.
     case 'zsh': {
       const zdotdir = process.env['ZDOTDIR'] ?? home;
-      return join(zdotdir, '.zshrc');
+      return join(zdotdir, '.zshenv');
     }
-    case 'bash': {
+    case 'bash':
-      const bashrc = join(home, '.bashrc');
-      if (existsSync(bashrc)) return bashrc;
       return join(home, '.profile');
-    }
     case 'fish':
       return join(home, '.config', 'fish', 'config.fish');
     default:

scripts/verify-release.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// verify-release.mjs — the ONE canonical terminal verification command
+// (SDLC-D-034, `pnpm verify:release`).
+//
+// Publication (.woodpecker/publish.yml `verify` step) is bound to terminal
+// verification of the exact commit through this command, which is composed
+// from the SAME commands the PR CI pipeline (.woodpecker/ci.yml) runs — CI and
+// publish share one semantic checklist:
+//
+//   stage         | mirrors ci.yml step | commands
+//   --------------|---------------------|------------------------------------------
+//   sanitization  | sanitization        | verify-sanitized.sh, check-resident-
+//                |                     | budget.sh (--self-test + run),
+//                |                     | check-test-enumeration.sh
+//   upgrade-guard | upgrade-guard       | test-upgrade-manifest-guard.sh,
+//                |                     | test-upgrade-rollback.sh,
+//                |                     | test-upgrade-durable-snapshot.sh,
+//                |                     | test-install-migration.sh
+//   typecheck     | typecheck           | pnpm typecheck (runs the checkout
+//                |                     | preflight, then turbo typecheck)
+//   lint          | lint                | pnpm lint
+//   format        | format              | pnpm format:check
+//   test          | test                | pnpm test
+//   build         | publish.yml build   | pnpm build
+//
+// Caller-provided prerequisites (kept at the pipeline level — see the comments
+// in .woodpecker/ci.yml): `bash` + `rsync` for the guard stages, `openssl` and
+// the pinned @earendil-works/pi-coding-agent for the test stage, and — on the
+// postgres path only — the ci-postgres service plus
+// `pnpm --filter @mosaicstack/db run db:migrate` before the test stage.
+//
+// This command works with DATABASE_URL set (CI postgres path) or unset (local
+// PGlite path); it never sets, exports, or requires a database itself.
+//
+// scripts/verify-release.test.mjs enforces that this stage table keeps
+// matching .woodpecker/ci.yml step-for-step, so the two surfaces cannot drift
+// apart silently.
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const STAGES = [
+  {
+    name: 'sanitization',
+    // Mirror of the .woodpecker/ci.yml `sanitization` step (minus its
+    // `apk add` environment prep). Kept as direct command strings here: the
+    // #1017 test-enumeration guard audits these paths through the ci.yml
+    // surface, so indirection from ci.yml into this file is not possible.
+    commands: [
+      'bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh',
+      'bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test',
+      'bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh',
+      'bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh',
+    ],
+  },
+  {
+    name: 'upgrade-guard',
+    // Mirror of the .woodpecker/ci.yml `upgrade-guard` step (minus its
+    // `apk add` environment prep).
+    commands: [
+      'bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh',
+      'bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh',
+      'bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh',
+      'bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh',
+    ],
+  },
+  {
+    // `pnpm typecheck` is `pnpm preflight && turbo run typecheck`, so the
+    // checkout preflight (scripts/preflight.mjs) is part of this stage exactly
+    // as it is part of the ci.yml `typecheck` step.
+    name: 'typecheck',
+    commands: ['pnpm typecheck'],
+  },
+  {
+    name: 'lint',
+    commands: ['pnpm lint'],
+  },
+  {
+    name: 'format',
+    commands: ['pnpm format:check'],
+  },
+  {
+    // Requires `openssl` and the pinned `pi` binary on the pipeline path; see
+    // the caller-provided prerequisites above.
+    name: 'test',
+    commands: ['pnpm test'],
+  },
+  {
+    name: 'build',
+    commands: ['pnpm build'],
+  },
+];
+
+export function stageByName(name) {
+  return STAGES.find((stage) => stage.name === name);
+}
+
+function missingBinaries(bins) {
+  return bins.filter(
+    (bin) => spawnSync('sh', ['-c', `command -v ${bin} >/dev/null 2>&1`]).status !== 0,
+  );
+}
+
+function runCommand(command) {
+  const result = spawnSync(command, { shell: true, stdio: 'inherit' });
+  if (result.error) {
+    console.error(`[verify:release] failed to launch '${command}': ${result.error.message}`);
+    return false;
+  }
+  if (result.status !== 0) {
+    const reason = result.signal ? `terminated by ${result.signal}` : `exited ${result.status}`;
+    console.error(`[verify:release] command '${command}' ${reason}`);
+    return false;
+  }
+  return true;
+}
+
+// Runs the complete mandatory verification set (or, with --stage <name>, the
+// single named stage — used for wiring/smoke-testing, not for gating: only a
+// run of every stage is a terminal verification). Fails fast: the first
+// failing command aborts with a non-zero exit code. Returns the exit code.
+export function verifyRelease({ stages = STAGES } = {}) {
+  const missing = missingBinaries(['bash', 'rsync']);
+  if (missing.length > 0) {
+    console.error(
+      `[verify:release] FATAL: required binaries missing from PATH: ${missing.join(', ')}. ` +
+        'The caller provides them (ci-base bakes bash; pipelines apk add rsync).',
+    );
+    return 1;
+  }
+  for (const stage of stages) {
+    console.log(`\n[verify:release] === stage: ${stage.name} ===`);
+    for (const command of stage.commands) {
+      console.log(`[verify:release] $ ${command}`);
+      if (!runCommand(command)) {
+        console.error(
+          `[verify:release] FATAL: stage '${stage.name}' failed — verification inconclusive`,
+        );
+        return 1;
+      }
+    }
+  }
+  console.log(`\n[verify:release] all ${stages.length} stage(s) passed`);
+  return 0;
+}
+
+function main(argv) {
+  const stageFlagIndex = argv.indexOf('--stage');
+  if (stageFlagIndex !== -1) {
+    const name = argv[stageFlagIndex + 1];
+    const stage = stageByName(name);
+    if (!stage) {
+      console.error(
+        `[verify:release] unknown stage '${name ?? ''}' — expected one of: ${STAGES.map((entry) => entry.name).join(', ')}`,
+      );
+      process.exit(2);
+    }
+    process.exit(verifyRelease({ stages: [stage] }));
+  }
+  process.exit(verifyRelease());
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2));
+}

scripts/verify-release.test.mjs

@@ -0,0 +1,277 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import test from 'node:test';
+
+import { STAGES } from './verify-release.mjs';
+
+// SDLC-D-034 checkout invariant: publication in .woodpecker/publish.yml is
+// bound to exact-commit terminal verification. This suite parses the real
+// pipeline files and fails red when the gate is bypassed, weakened, or drifts
+// out of sync with the canonical `pnpm verify:release` command.
+
+// Reuse the monorepo's existing YAML parser (@mosaicstack/mosaic's direct
+// dependency) instead of adding a root dependency or vendoring a parser.
+const mosaicRequire = createRequire(
+  path.resolve(process.cwd(), 'packages', 'mosaic', 'package.json'),
+);
+const { parse: parseYaml } = mosaicRequire('yaml');
+
+const publishYmlPath = path.join(process.cwd(), '.woodpecker', 'publish.yml');
+const ciYmlPath = path.join(process.cwd(), '.woodpecker', 'ci.yml');
+
+async function readPublishPipeline() {
+  return parseYaml(await readFile(publishYmlPath, 'utf8'));
+}
+
+// A step has an external publication effect when its name starts with
+// `publish` or when any command pushes an image to a registry.
+function pushesImage(step) {
+  return (step.commands ?? []).some((command) =>
+    /(^|\s)(\/kaniko\/executor|docker push)\b|--destination/.test(command),
+  );
+}
+
+function publishEffectSteps(pipeline) {
+  return Object.entries(pipeline.steps ?? {})
+    .filter(([name, step]) => name.startsWith('publish') || pushesImage(step))
+    .map(([name]) => name);
+}
+
+// Transitive closure of a step's depends_on graph.
+function dependencyClosure(pipeline, stepName, seen = new Set()) {
+  const dependencies = pipeline.steps?.[stepName]?.depends_on ?? [];
+  for (const dependency of dependencies) {
+    if (seen.has(dependency)) continue;
+    seen.add(dependency);
+    dependencyClosure(pipeline, dependency, seen);
+  }
+  return seen;
+}
+
+function verifyCommands(pipeline) {
+  const verify = pipeline.steps?.verify;
+  assert.ok(verify, 'publish pipeline must define a `verify` step');
+  assert.ok(Array.isArray(verify.commands), '`verify` step must have commands');
+  return verify.commands;
+}
+
+function assertCommitIdentityAssertion(commands) {
+  const text = commands.join('\n');
+  assert.match(
+    text,
+    /CI_COMMIT_SHA/,
+    '`verify` must compare the provider commit identity (CI_COMMIT_SHA)',
+  );
+  assert.match(text, /git rev-parse HEAD/, '`verify` must compare against git rev-parse HEAD');
+  assert.match(
+    text,
+    /exit 1/,
+    '`verify` must fail closed (exit 1) on identity mismatch or emptiness',
+  );
+}
+
+function assertCanonicalCommand(commands) {
+  assert.ok(
+    commands.some((command) => /^pnpm verify:release\b/.test(command.trim())),
+    '`verify` must run the canonical terminal verification command `pnpm verify:release`',
+  );
+}
+
+function assertPublishGate(pipeline) {
+  assert.ok(pipeline.steps, 'publish pipeline must define steps');
+
+  const commands = verifyCommands(pipeline);
+  assertCommitIdentityAssertion(commands);
+  assertCanonicalCommand(commands);
+
+  const effects = publishEffectSteps(pipeline);
+  assert.ok(effects.length > 0, 'publish pipeline must contain publish effect steps to guard');
+
+  for (const stepName of effects) {
+    const step = pipeline.steps[stepName];
+    assert.ok(
+      Array.isArray(step.depends_on) && step.depends_on.includes('verify'),
+      `publish effect '${stepName}' must depend DIRECTLY on the verify step (SDLC-D-034: transitively through build is not enough)`,
+    );
+    assert.ok(
+      dependencyClosure(pipeline, stepName).has('verify'),
+      `publish effect '${stepName}' must depend on a chain that includes verify`,
+    );
+  }
+  return effects;
+}
+
+test('the publish pipeline gates every publish effect behind exact-commit verification', async () => {
+  const pipeline = await readPublishPipeline();
+  const effects = assertPublishGate(pipeline);
+  assert.deepEqual(effects.sort(), [
+    'build-appservice',
+    'build-gateway',
+    'build-web',
+    'publish-next-npm',
+    'publish-npm',
+  ]);
+});
+
+test('the verify step carries no path/event short-circuit of its own', async () => {
+  const pipeline = await readPublishPipeline();
+  // A `when` filter on `verify` would let a publish effect fire on an event
+  // class that skipped verification — the gate must be unconditional.
+  assert.equal(pipeline.steps.verify.when, undefined);
+});
+
+test('a publish step that bypasses verify fails the gate checker', () => {
+  // Negative fixture: a plausible publish pipeline where `publish-npm` hangs
+  // off `build` only and `build` never chains to `verify` — the exact bypass
+  // class SDLC-D-034 closes. The checker must go red on it.
+  const bypassingPipeline = `
+steps:
+  install:
+    image: node:24-alpine
+    commands:
+      - pnpm install --frozen-lockfile
+  verify:
+    image: node:24-alpine
+    commands:
+      - |
+        if [ -z "$CI_COMMIT_SHA" ] || [ "$CI_COMMIT_SHA" != "$(git rev-parse HEAD)" ]; then
+          echo "identity mismatch" >&2
+          exit 1
+        fi
+      - pnpm verify:release
+    depends_on:
+      - install
+  build:
+    image: node:24-alpine
+    commands:
+      - pnpm build
+    depends_on:
+      - install
+  publish-npm:
+    image: node:24-alpine
+    commands:
+      - pnpm publish
+    depends_on:
+      - build
+`;
+  assert.throws(
+    () => assertPublishGate(parseYaml(bypassingPipeline)),
+    /publish-npm.*DIRECTLY.*verify/s,
+  );
+});
+
+test('a publish step chained to verify only transitively fails the gate checker', () => {
+  // Negative fixture: `build` depends on verify but `publish-npm` does not
+  // carry the direct edge — weaker than SDLC-D-034 requires of the real DAG.
+  const transitiveOnlyPipeline = `
+steps:
+  install:
+    image: node:24-alpine
+    commands:
+      - pnpm install --frozen-lockfile
+  verify:
+    image: node:24-alpine
+    commands:
+      - |
+        if [ -z "$CI_COMMIT_SHA" ] || [ "$CI_COMMIT_SHA" != "$(git rev-parse HEAD)" ]; then
+          echo "identity mismatch" >&2
+          exit 1
+        fi
+      - pnpm verify:release
+    depends_on:
+      - install
+  build:
+    image: node:24-alpine
+    commands:
+      - pnpm build
+    depends_on:
+      - install
+      - verify
+  publish-npm:
+    image: node:24-alpine
+    commands:
+      - pnpm publish
+    depends_on:
+      - build
+`;
+  assert.throws(
+    () => assertPublishGate(parseYaml(transitiveOnlyPipeline)),
+    /publish-npm.*DIRECTLY.*verify/s,
+  );
+});
+
+test('a verify step without the commit-identity assertion fails the gate checker', () => {
+  const noIdentityPipeline = `
+steps:
+  verify:
+    image: node:24-alpine
+    commands:
+      - pnpm verify:release
+  publish-npm:
+    image: node:24-alpine
+    commands:
+      - pnpm publish
+    depends_on:
+      - verify
+`;
+  assert.throws(() => assertPublishGate(parseYaml(noIdentityPipeline)), /CI_COMMIT_SHA/);
+});
+
+test('the canonical verify:release stages mirror the PR CI pipeline one-for-one', async () => {
+  const ci = parseYaml(await readFile(ciYmlPath, 'utf8'));
+  const canonical = Object.fromEntries(STAGES.map((stage) => [stage.name, stage.commands]));
+
+  // The complete mandatory set, in gate order.
+  assert.deepEqual(
+    STAGES.map((stage) => stage.name),
+    ['sanitization', 'upgrade-guard', 'typecheck', 'lint', 'format', 'test', 'build'],
+  );
+
+  // Guard stages: ci.yml commands minus its `apk add` environment prep must be
+  // exactly the canonical stage commands (order included).
+  for (const stageName of ['sanitization', 'upgrade-guard']) {
+    assert.deepEqual(
+      ci.steps[stageName].commands.filter((command) => !command.startsWith('apk add')),
+      canonical[stageName],
+      `canonical '${stageName}' stage must match the ci.yml step`,
+    );
+  }
+
+  // pnpm stages: ci.yml commands minus `corepack enable` must be exactly the
+  // canonical stage commands.
+  for (const stepName of ['typecheck', 'lint', 'format']) {
+    assert.deepEqual(
+      ci.steps[stepName].commands.filter((command) => command !== 'corepack enable'),
+      canonical[stepName],
+      `canonical '${stepName}' stage must match the ci.yml step`,
+    );
+  }
+
+  // The test stage is shared, but ci.yml wraps it in pipeline-level
+  // prerequisites the canonical command expects its caller to provide
+  // (SDLC-D-034): the postgres service + readiness wait + db:migrate, openssl,
+  // and the pinned pi runtime. None of those may be dropped silently.
+  for (const command of canonical.test) {
+    assert.ok(
+      ci.steps.test.commands.includes(command),
+      `ci.yml test step must run the canonical test stage command '${command}'`,
+    );
+  }
+  for (const fragment of [
+    'pg_isready -h ci-postgres',
+    'pnpm --filter @mosaicstack/db run db:migrate',
+    'npm install -g @earendil-works/[email protected]',
+  ]) {
+    assert.ok(
+      ci.steps.test.commands.some((command) => command.includes(fragment)),
+      `ci.yml test step must keep its pipeline-level prerequisite '${fragment}'`,
+    );
+  }
+});
+
+test('the root package.json exposes verify:release as the canonical command', async () => {
+  const packageJson = JSON.parse(await readFile(path.join(process.cwd(), 'package.json'), 'utf8'));
+  assert.match(packageJson.scripts['verify:release'], /scripts\/verify-release\.mjs/);
+});

tools/install.sh

@@ -309,6 +309,124 @@ require_cmd() {
   fi
 }
 
+# True if any shell rc file already puts $1 on PATH.
+#
+# Each file is tested for existence first and grepped one at a time, rather than
+# handed to a single `grep -qs ... "${rc_files[@]}"`. Handing grep a missing file
+# makes the exit status implementation-defined: GNU grep 3.11 returns 0 when -q
+# matched an earlier file, ugrep 7.5 returns 2 for the missing one regardless.
+# On the 2 path the caller reads "not present yet" and appends a duplicate PATH
+# line on every single install.
+path_entry_exists() {
+  local dir="$1" rc_file
+  for rc_file in "$HOME/.profile" "$HOME/.zshenv" "$HOME/.zshrc" "$HOME/.bashrc"; do
+    if [[ -f "$rc_file" ]] && grep -qF "$dir" "$rc_file"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Append `export PATH="$1:$PATH"` to the shell profile so $1 survives this
+# process. An `export` here reaches only the installer; every directory the
+# install leaves behind has to be written down somewhere a later shell reads.
+#
+# Deliberately NOT ~/.bashrc: Debian's default .bashrc returns early for
+# non-interactive shells, so a PATH line appended to the bottom of it is
+# unreachable to `bash -lc`, to systemd units, and to every agent seat — the
+# exact consumers that need these binaries. ~/.profile is read by login shells
+# and Debian's .profile sources .bashrc for interactive ones, so a single line
+# there reaches both. For zsh the always-sourced file is .zshenv, not .zshrc.
+#
+# $1 = directory to add, $2 = label for the comment line.
+# Returns 1 (having warned) if the profile could not be written.
+persist_on_path() {
+  local dir="$1" label="$2" profile
+
+  if path_entry_exists "$dir"; then
+    return 0
+  fi
+
+  if [[ -n "${ZSH_VERSION:-}" ]] || [[ "$(basename "${SHELL:-}")" == "zsh" ]]; then
+    profile="$HOME/.zshenv"
+  else
+    profile="$HOME/.profile"
+  fi
+
+  # Probe writability in a subshell. A redirection failure on a special built-in
+  # aborts the shell it runs in, so it has to be a child; and the redirection on
+  # the subshell is what silences the "Permission denied" the shell would
+  # otherwise print ahead of our own message.
+  if ! ( : >>"$profile" ) 2>/dev/null; then
+    warn "$dir is not on your PATH and $profile could not be written"
+    dim "  Add to your shell rc:  export PATH=\"$dir:\$PATH\""
+    return 1
+  fi
+
+  {
+    echo ""
+    echo "# $label"
+    echo "export PATH=\"$dir:\$PATH\""
+  } >>"$profile"
+  ok "Added $dir to PATH in $profile"
+  return 0
+}
+
+# Persist $PREFIX/bin on PATH instead of only warning about it.
+#
+# The warning it replaces was the last step of an otherwise successful install,
+# so the installer reported success and left `mosaic: command not found` — an
+# unattended install had no operator to read the advice and act on it.
+ensure_prefix_on_path() {
+  if [[ ":$PATH:" == *":$PREFIX/bin:"* ]]; then
+    return
+  fi
+
+  if path_entry_exists "$PREFIX/bin"; then
+    warn "$PREFIX/bin is in your shell profile but not in this shell"
+  elif ! persist_on_path "$PREFIX/bin" "Mosaic CLI"; then
+    return
+  fi
+  dim "  Run:  export PATH=\"$PREFIX/bin:\$PATH\"   (or start a new login shell)"
+}
+
+# Fleet transport binary (#1240).
+#
+# `mosaic fleet --help` reads "Manage the local Mosaic tmux fleet" and every
+# roster the CLI scaffolds sets `transport: tmux`, but nothing in this script
+# provides tmux and, until now, nothing in it mentioned tmux at all. A
+# greenfield host came out of this installer able to install a fleet, start a
+# fleet, and run no seat — the operator's first signal was `mosaic fleet ps`.
+#
+# Not a `require_cmd`: tmux is required by the fleet, not by mosaic. Plenty of
+# hosts install this to run `mosaic claude` and will never scaffold a roster,
+# and failing their install over a binary they do not need would be wrong. It
+# is a warning that names precisely what it blocks.
+#
+# `tools/_scripts/mosaic-doctor` carries a deliberately parallel check, so the
+# same host state gets the same answer from an audit as from an install. They
+# are separate implementations because this one has to work before the
+# framework's scripts are guaranteed to be on disk; keep their wording in step.
+check_fleet_transport() {
+  local transport=tmux
+  local roster="$MOSAIC_HOME/fleet/roster.yaml"
+  local declared=""
+
+  if [[ -f "$roster" ]]; then
+    declared="$(sed -n 's/^[[:space:]]*transport:[[:space:]]*//p' "$roster" | head -1 |
+      tr -d '"'\''' | tr -d '\r' | awk '{print $1}')"
+    [[ -n "$declared" ]] && transport="$declared"
+  fi
+
+  command -v "$transport" &>/dev/null && return 0
+
+  warn "Fleet transport '$transport' is not installed."
+  echo "  The Mosaic fleet runs its agent seats inside $transport. Without it,"
+  echo "  ${C}mosaic fleet start${RESET} reports success and no seat comes up."
+  echo "  Install it before using the fleet, e.g. ${C}sudo apt-get install -y $transport${RESET}"
+  echo "  (this does not affect ${C}mosaic claude${RESET} or the other single-runtime commands)."
+}
+
 installed_cli_version() {
   local json
   json="$(npm ls -g --depth=0 --json --prefix="$PREFIX" 2>/dev/null)" || true
@@ -516,8 +634,175 @@ install_next_cli_from_registry() {
   ok "Installed @next packages: CLI ${installed_cli}, gateway ${installed_gateway}"
 }
 
+# ─── node bootstrap ───────────────────────────────────────────────────────────
+#
+# Nothing on a greenfield host installs Node.js, yet this installer and the CLI
+# it installs both hard-require it. Measured on a clean Debian 13 image: the
+# installer stopped at `require_cmd node` with "Required command not found" and
+# nothing was installed, with no hint of how to proceed.
+#
+# Inlined rather than factored into a sibling file on purpose: this script is
+# fetched standalone by curl and has nothing to source.
+#
+# No-op when a suitable node is already on PATH, so it never fights an
+# operator's nvm/fnm/distro node.
+
+NODE_ROOT="${MOSAIC_NODE_ROOT:-$HOME/.mosaic/node}"
+NODE_BOOTSTRAP_VERSION="${MOSAIC_NODE_VERSION:-v22.23.2}"
+NODE_MIN_MAJOR="${MOSAIC_NODE_MIN_MAJOR:-20}"
+NODE_DIST_BASE="${MOSAIC_NODE_DIST_BASE:-https://nodejs.org/dist}"
+
+# Major version of the node at $1, or empty if it will not run.
+node_major_of() {
+  local candidate="$1" version
+  version="$("$candidate" -e 'process.stdout.write(process.versions.node)' 2>/dev/null)" || return 0
+  printf '%s' "${version%%.*}"
+}
+
+node_is_suitable() {
+  local major
+  major="$(node_major_of "$1")"
+  [[ -n "$major" ]] && [[ "$major" -ge "$NODE_MIN_MAJOR" ]]
+}
+
+install_node() {
+  local node_os node_arch tarball release_url work_dir extracted target node_bin
+
+  case "$(uname -s)" in
+    Linux)  node_os="linux" ;;
+    Darwin) node_os="darwin" ;;
+    *) fail "Unsupported OS '$(uname -s)'. Install Node.js >= $NODE_MIN_MAJOR manually."; return 1 ;;
+  esac
+
+  # Linux here means glibc. Node's official linux-x64 build is dynamically
+  # linked against glibc, so on musl (Alpine) the binary will not exec — but it
+  # fails visibly: node_is_suitable rejects it and ensure_node exits with
+  # "install Node.js manually". No silent breakage, just a wasted download.
+  # A musl host needs the unofficial build, which is out of scope here.
+  case "$(uname -m)" in
+    x86_64|amd64)  node_arch="x64" ;;
+    aarch64|arm64) node_arch="arm64" ;;
+    armv7l)        node_arch="armv7l" ;;
+    *) fail "Unsupported architecture '$(uname -m)'. Install Node.js >= $NODE_MIN_MAJOR manually."; return 1 ;;
+  esac
+
+  # .tar.gz rather than the smaller .tar.xz: gzip is universally present, xz is
+  # not, and a minimal image is exactly the case this exists to handle.
+  tarball="node-${NODE_BOOTSTRAP_VERSION}-${node_os}-${node_arch}.tar.gz"
+  release_url="${NODE_DIST_BASE}/${NODE_BOOTSTRAP_VERSION}"
+
+  work_dir="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-node-XXXXXX")"
+
+  info "Installing Node.js $NODE_BOOTSTRAP_VERSION ($node_os-$node_arch) to $NODE_ROOT…"
+
+  if ! curl -fsSL "${release_url}/${tarball}" -o "$work_dir/$tarball"; then
+    fail "Download failed: ${release_url}/${tarball}"
+    rm -rf "$work_dir"; return 1
+  fi
+
+  # Trust assumption, stated so nobody has to infer it: this verifies INTEGRITY
+  # (the tarball matches the manifest), not AUTHENTICITY (the manifest is
+  # genuinely Node's). The only thing establishing that is TLS to
+  # $NODE_DIST_BASE. Node publishes SHASUMS256.txt.sig signed by its release
+  # keys and we do not check it, which is on par with nvm but means pointing
+  # MOSAIC_NODE_DIST_BASE at an untrusted mirror has no signature backstop.
+  # Tracked as a hardening follow-up (raised by scooby in the #1229 review).
+  if ! curl -fsSL "${release_url}/SHASUMS256.txt" -o "$work_dir/SHASUMS256.txt"; then
+    fail "Could not fetch SHASUMS256.txt; refusing to install an unverified runtime."
+    rm -rf "$work_dir"; return 1
+  fi
+
+  # Keep only our artifact's line, so a missing entry is an error not a pass.
+  if ! grep " ${tarball}\$" "$work_dir/SHASUMS256.txt" >"$work_dir/expected.sha256"; then
+    fail "$tarball has no entry in SHASUMS256.txt; refusing to install."
+    rm -rf "$work_dir"; return 1
+  fi
+
+  if ! (cd "$work_dir" && verify_sha256 expected.sha256); then
+    fail "Checksum mismatch for $tarball; refusing to install."
+    rm -rf "$work_dir"; return 1
+  fi
+  ok "Checksum verified"
+
+  tar xzf "$work_dir/$tarball" -C "$work_dir"
+  extracted="$work_dir/node-${NODE_BOOTSTRAP_VERSION}-${node_os}-${node_arch}"
+  if [[ ! -x "$extracted/bin/node" ]]; then
+    fail "Extracted archive has no bin/node"
+    rm -rf "$work_dir"; return 1
+  fi
+
+  mkdir -p "$NODE_ROOT"
+  target="$NODE_ROOT/$NODE_BOOTSTRAP_VERSION"
+  rm -rf "$target.incoming"
+  mv "$extracted" "$target.incoming"
+  rm -rf "$target"
+  mv "$target.incoming" "$target"
+  ln -sfn "$NODE_BOOTSTRAP_VERSION" "$NODE_ROOT/current"
+  rm -rf "$work_dir"
+
+  node_bin="$NODE_ROOT/current/bin"
+  if ! node_is_suitable "$node_bin/node"; then
+    fail "Installed node at $node_bin/node did not run"
+    return 1
+  fi
+
+  export PATH="$node_bin:$PATH"
+  ok "Node.js $(node -v) installed with npm $(npm -v 2>/dev/null || echo '?')"
+  return 0
+}
+
+# Make the Mosaic-managed Node reachable from the next shell as well as this
+# one. Measured on a greenfield canary run: without this the install finished
+# rc=0, wrote $PREFIX/bin to ~/.profile, and the next login shell found `mosaic`
+# and then died on `env: 'node': No such file or directory` — the CLI is a Node
+# script, so a CLI on PATH without its runtime is a successful install that
+# produces a broken command.
+persist_node_on_path() {
+  persist_on_path "$NODE_ROOT/current/bin" "Mosaic-managed Node.js" || true
+}
+
+ensure_node() {
+  if command -v node &>/dev/null && node_is_suitable node; then
+    return 0
+  fi
+
+  # A previous run may have installed one that is not on this shell's PATH.
+  if node_is_suitable "$NODE_ROOT/current/bin/node"; then
+    export PATH="$NODE_ROOT/current/bin:$PATH"
+    persist_node_on_path
+    return 0
+  fi
+
+  if [[ "${MOSAIC_SKIP_NODE_BOOTSTRAP:-0}" == "1" ]]; then
+    fail "No suitable Node.js and MOSAIC_SKIP_NODE_BOOTSTRAP=1; refusing to download."
+    echo "  Install Node.js >= $NODE_MIN_MAJOR yourself, then re-run this script."
+    exit 1
+  fi
+
+  require_cmd curl
+  require_cmd tar
+
+  # sha256sum on Linux, shasum on macOS. Verification is not optional: without a
+  # checksum this would install an unauthenticated runtime.
+  if command -v sha256sum &>/dev/null; then
+    verify_sha256() { sha256sum -c --status "$1"; }
+  elif command -v shasum &>/dev/null; then
+    verify_sha256() { shasum -a 256 -c --status "$1"; }
+  else
+    fail "sha256sum or shasum required to verify the Node.js download"
+    exit 1
+  fi
+
+  if ! install_node; then
+    fail "Could not bootstrap Node.js. Install Node.js >= $NODE_MIN_MAJOR and re-run."
+    exit 1
+  fi
+  persist_node_on_path
+}
+
 # ─── preflight ────────────────────────────────────────────────────────────────
 
+ensure_node
 require_cmd node
 require_cmd npm
 
@@ -682,11 +967,7 @@ if [[ "$FLAG_CLI" == "true" ]]; then
     ensure_monorepo
     install_cli_from_source
 
-    # PATH check for npm prefix
+    ensure_prefix_on_path
-    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
-      warn "$PREFIX/bin is not on your PATH"
-      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
-    fi
   elif is_next_registry_lane; then
     info "Next mode — trying fast npm @next install from ${REGISTRY}…"
     if install_next_cli_from_registry; then
@@ -699,11 +980,7 @@ if [[ "$FLAG_CLI" == "true" ]]; then
       export MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1
     fi
 
-    # PATH check for npm prefix
+    ensure_prefix_on_path
-    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
-      warn "$PREFIX/bin is not on your PATH"
-      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
-    fi
   else
     if [[ -z "$LATEST" ]]; then
       warn "Could not reach registry at $REGISTRY — skipping npm CLI."
@@ -721,11 +998,7 @@ if [[ "$FLAG_CLI" == "true" ]]; then
       ok "CLI is at or ahead of registry ($CURRENT ≥ $LATEST)."
     fi
 
-    # PATH check for npm prefix
+    ensure_prefix_on_path
-    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
-      warn "$PREFIX/bin is not on your PATH"
-      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
-    fi
   fi
 fi
 
@@ -870,6 +1143,11 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
   ok "Done."
 fi
 
+# Fleet readiness (#1240). Runs in both normal and --check mode: "what is the
+# state of this host" is exactly the question --check is asked, and a host that
+# cannot run a seat should not have to discover it from `fleet ps`.
+check_fleet_transport
+
 } # end main
 
 main "$@"