docs(ri-050): continuation handoff — state, blocker, mechanics, next actions (#1275)

- PRD section: normative requirements RI-N1..RI-N5 (decisions SDLC-D-034..038)
- docs/release-integrity/TASKS.md: 10-card DAG, pi-glm-5.3 execution note
- scratchpad: mode, constraints, budget

Executed by jarvis (dragon-lin) with local pi workers per Jason's directive.

docs/PRD.md

@@ -115,19 +115,18 @@ gateway-backed agent catalog.
 
 ### Normative requirements
 
-| ID           | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ID           | Requirement                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FCM-REQ-01` | The roster SHALL be the sole writable desired-state source for local fleet membership, launch policy, and persisted lifecycle target. Generated environment files, systemd enablement, tmux sessions, and heartbeat state SHALL be non-authoritative projections.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `FCM-REQ-01` | The roster SHALL be the sole writable desired-state source for local fleet membership, launch policy, and persisted lifecycle target. Generated environment files, systemd enablement, tmux sessions, and heartbeat state SHALL be non-authoritative projections.                                                                                                                                                                                                         |
-| `FCM-REQ-02` | The implementation SHALL provide one executable structural contract for YAML/JSON input and one shared semantic validator. Roster load, profile validation, provision, migration, and apply SHALL reuse the existing baseline-plus-`roles.local` profile/persona resolver; a parallel role resolver is forbidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `FCM-REQ-02` | The implementation SHALL provide one executable structural contract for YAML/JSON input and one shared semantic validator. Roster load, profile validation, provision, migration, and apply SHALL reuse the existing baseline-plus-`roles.local` profile/persona resolver; a parallel role resolver is forbidden.                                                                                                                                                         |
-| `FCM-REQ-03` | The local fleet CLI SHALL expose documented programmatic validate, show, plan, apply/reconcile, create, inspect, update, delete, start, stop, restart, status, verify, and doctor operations with stable JSON and exit-code behavior. Existing `fleet add/remove` compatibility aliases may remain during the stated deprecation window.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `FCM-REQ-03` | The local fleet CLI SHALL expose documented programmatic validate, show, plan, apply/reconcile, create, inspect, update, delete, start, stop, restart, status, verify, and doctor operations with stable JSON and exit-code behavior. Existing `fleet add/remove` compatibility aliases may remain during the stated deprecation window.                                                                                                                                  |
-| `FCM-REQ-04` | A fresh create SHALL persist `enabled:true` and `desired_state:stopped` unless an explicit persisted start is requested. The model SHALL distinguish enabled state, persisted desired state, and observed state. Migration, apply, reboot, and rollback SHALL not start an agent that was observed stopped before cutover.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `FCM-REQ-04` | A fresh create SHALL persist `enabled:true` and `desired_state:stopped` unless an explicit persisted start is requested. The model SHALL distinguish enabled state, persisted desired state, and observed state. Migration, apply, reboot, and rollback SHALL not start an agent that was observed stopped before cutover.                                                                                                                                                |
-| `FCM-REQ-05` | The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash.                                                                                                                                                                                                                                                                                                                                       |
+| `FCM-REQ-05` | The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash.                     |
-| `FCM-REQ-06` | Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `FCM-REQ-06` | Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name.                                                                                                                                    |
-| `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities.                                                                                                                                                                                                                                                                                                                   |
+| `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities. |
-| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note.                                                                                                                                                                                                                                                                                                                                                                  |
+| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note.                                                |
-| `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model.                                                                                                                                                                                              |
-| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence.                                                                                                  |
-| `FCM-REQ-11` | Fleet provisioning SHALL validate the fleet CLI and distinct runtimes requested by the roster against the exact PATH construction used by the runtime pane, through one shared implementation rather than the operator PATH or a parallel PATH model. Name resolution alone is insufficient: a resolved script's shebang interpreter SHALL also be reachable, and Node SHALL execute a side-effect-free version probe when it is that interpreter. `fleet install` and `install-systemd` SHALL fail before installation effects when a required executable is absent or unreachable. `fleet doctor` SHALL emit the same named checks as non-green evidence. Every runtime failure SHALL name the runtime, all requesting roster rows, the pane PATH searched, and an exact install command. |
 
 ### Acceptance criteria
 
@@ -139,7 +138,6 @@ gateway-backed agent catalog.
 6. `AC-FCM-06`: A v1 roster migration previews field-by-field disposition, preserves observed stopped/running state, inventories rather than reconciles remote/schema-only entries, supports a canary and rollback, and classifies every shipped example, profile, and service preset according to the M0 inventory.
 7. `AC-FCM-07`: Required role authority is validated: validator certificate is consumed but does not merge, merge-gate is the sole merge authority, team-leader leases do not change roster/credentials/authority, and interaction/Tess cannot claim orchestration or merge powers.
 8. `AC-FCM-08`: Documentation, examples, migration, troubleshooting, operational recovery, package/update asset drift, schema/example/profile validation, independent code/security review, validator certificate, and terminal-green CI are complete before #758 closes.
-9. `AC-FCM-09`: Red-first isolated tests create (a) a roster whose runtime exists on the operator PATH but is absent from the constructed pane PATH and (b) a greenfield pane where `mosaic` and a runtime resolve as Node-shebang scripts while Node is absent. They prove `fleet install` fails before effects, the launcher creates no doomed session, and `fleet doctor` reports named non-green checks. Diagnostics include the executable or runtime, all requesting rows, searched pane PATH, shebang dependency when present, and exact runtime install command; repeated rows are checked once per distinct runtime/effective pane path. Tests use temporary `--mosaic-home` state and fixture binaries, never host runtime mutation.
 
 ### M0 implementation gate
 
@@ -1370,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/fleet/FLEET-LAUNCH.md

@@ -59,28 +59,6 @@ valid allowed local data can move to `.env.local`; invalid legacy input is priva
 Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command
 text, credentials, or other values.
 
-## Pane executable preflight
-
-The fleet install, install-systemd, and doctor commands plus the session launcher use
-**pane-runtime-path.sh** as the single pane-PATH implementation. Install inspects every distinct
-roster runtime and effective MOSAIC_RUNTIME_BIN pair before creating holder identity, tool,
-projection, or unit files. Doctor reports the same checks as JSON.
-
-A resolved command is not automatically executable. The helper reads a script shebang, unwraps the
-common “/usr/bin/env node” and “/usr/bin/env -S node …” forms, then resolves the declared command
-against the pane PATH. When Node is the declared interpreter, the helper runs the side-effect-free
-“node --version” probe. It does not run “mosaic --version”, whose startup update check can write cache
-state. Native binaries have no PATH-resolved shebang dependency and retain their normal executable
-check. Failures name the executable or runtime, requesting roster rows, searched pane PATH,
-dependency, and runtime install command.
-
-Supported runtime install commands are:
-
-- **Claude:** curl -fsSL https://claude.ai/install.sh | bash
-- **Codex:** npm install -g @openai/codex
-- **OpenCode:** npm install -g opencode-ai
-- **Pi:** npm install -g @earendil-works/pi-coding-agent
-
 ## Launch and stop behavior
 
 The launcher obtains the agent's socket only from the validated generated projection. It creates or

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      |       |
+| RI-2-002 | not-started | 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 | not-started | 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/1256-fleet-runtime-preflight.md

@@ -1,71 +0,0 @@
-# #1256 — Fleet runtime preflight
-
-**Agent:** tiny
-
-**Branch:** `fix/1256-fleet-runtime-preflight` from `origin/next@476db12b92971634b67fd2057b7577ee5894e449`
-
-**Issue:** `mosaicstack/stack#1256` blocker 1
-
-**Adjacent PR:** `#1258` (`fix/1256-fleet-pane-path-node`) owns the bootstrapped-Node candidate and must remain a separate change
-
-**Budget:** 30K-token soft cap; one bounded implementation lane
-
-## Objective
-
-Make fleet provisioning fail before installation effects when the roster names a runtime binary absent from the exact PATH the tmux pane will receive. Make `mosaic fleet doctor` report the same named runtime check. Diagnostics must name the runtime, every requesting roster row, the pane PATH searched, and an exact install command.
-
-For Pi the exact command is:
-
-```text
-npm install -g @earendil-works/pi-coding-agent
-```
-
-## Constraints
-
-- TDD: add the failing behavior test and capture RED before implementation.
-- Runtime resolution uses the launcher's pane-PATH construction; a second PATH model is forbidden.
-- Operator PATH is non-authoritative and must not cause a false pass.
-- Tests use an isolated `--mosaic-home`/temporary HOME and never mutate host runtime binaries.
-- No install, removal, or binary-resolution changes on sb-it-1-dt.
-- PR targets `next` and requires a reviewer other than fred.
-- Commit identity is `tiny <[email protected]>`.
-- #1258's Node candidate is a dependency/adjacent change, never reimplemented here.
-
-## Planned seam
-
-1. Factor the shell pane-path builder/resolver into one sourceable and executable fleet helper.
-2. Have `start-agent-session.sh` source that helper, preserving one definition of the pane PATH.
-3. Have the TypeScript fleet command invoke the same helper under the unit-equivalent clean launcher environment.
-4. Group roster rows by distinct runtime and effective pane PATH, then report requesting row names.
-5. Run the preflight before `installFleet` performs any write.
-6. Add the named result to roster-v2 `fleet doctor` JSON and set a failing exit when a runtime is absent.
-7. Install/copy the helper alongside `start-agent-session.sh` and update framework manifest/docs as required.
-
-This seam overlaps #1258 only at the location of the existing shell function. Development may use #1258 as a local dependency, but the final PR diff must exclude #1258's separately owned Node change after that PR lands or after an agreed rebase order.
-
-## Acceptance evidence
-
-| Requirement | Evidence |
-|---|---|
-| Missing Pi blocks install before effects | isolated CLI test: nonzero + no installed files/runner effects |
-| Operator PATH cannot create false green | test puts Pi only on operator PATH and omits it from constructed pane PATH |
-| Exact pane PATH reused | launcher and CLI call one shared shell helper; contract test exercises both |
-| Actionable diagnosis | runtime + roster rows + searched PATH + exact install command assertions |
-| Distinct runtimes | repeated rows produce one check with all row names |
-| Doctor reports named check | JSON assertion + nonzero exit for missing runtime |
-| Present runtime passes | isolated pane-path fixture with executable binary |
-| No host mutation | tests use temporary HOME/Mosaic home and fixture binaries only |
-| Baseline safety | focused tests, package typecheck/lint/format, full relevant suite, CI |
-
-## Progress log
-
-- 2026-08-16: Dispatch received from fred; issue #1256 and PR #1258 measured.
-- 2026-08-16: Fresh clone created under `~/agent-work/tiny-fleet-runtime-preflight`; local Git identity pinned to tiny so retired global `mos-dt-0` identity cannot win.
-- 2026-08-16: Design inspection found the pane PATH exists only inside `start-agent-session.sh`; the right seam is a shared shell helper rather than a parallel TypeScript reconstruction.
-- 2026-08-16: RED measured on `origin/next@476db12b`: focused `fleet-roster-v2-dispatch.spec.ts` ran 11 tests; the new case failed because install returned success, wrote units for two agents, and emitted no `runtime=pi` diagnosis while Pi existed only on operator PATH.
-- 2026-08-16: Factored pane home/PATH/resolution into sourceable and executable `pane-runtime-path.sh`; install invokes it before the first effect, doctor emits the same named checks, and the launcher sources it.
-- 2026-08-16: Fred/rhodey review exposed the #1241 name-resolution blind spot: `mosaic` can resolve while its `#!/usr/bin/env node` interpreter cannot. Measurement confirmed every supported current Mosaic package shape is a Node-shebang script, but executing `mosaic --version` is not observational because CLI startup runs the cache-writing/network update checker before Commander handles the flag.
-- 2026-08-16: Final executable check reads and unwraps direct and `/usr/bin/env` shebangs (including `env -S`), resolves the declared dependency against pane PATH, and runs only side-effect-free `node --version` when Node is declared. Native binaries do not inherit a permanent Node requirement. Install, doctor, and launcher share this implementation.
-- 2026-08-16: Isolated greenfield fixture places resolved Mosaic and Pi Node-shebang scripts in pane-visible npm-global bin while using an empty system suffix; both checks become `unexecutable` with `dependency=node`, and install leaves holder/tools/units absent. No host binary or HOME is changed.
-- 2026-08-16: GREEN evidence before #1258 rebase: focused install/doctor/preflight suites pass; `fleet.spec.ts` 209/209; full Vitest 87 files / 1,557 tests; launcher shell suite, typecheck, lint, build, and focused format check pass. Full framework-shell reaches an unrelated host-measurement drift in unchanged `invariant_r_unittest.py` (expected Pi 0.84.1, host resolves 0.84.2); no invariant was changed in this lane.
-- 2026-08-16: Merge-order gate remains: `origin/next` is still `476db12b`; #1258 is unmerged at `6dc35e5`. Rebase after it lands, relocate its Node candidate into the helper with explicit provenance, rerun gates, then open the PR to `next` for an independent non-fred review.

docs/scratchpads/ri-050.md

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

packages/mosaic/framework/systemd/user/README.md

@@ -51,12 +51,8 @@ See `docs/fleet/reference/generated-env-boundary.md` for the full contract.
 ## Manual canary sequence
 
 Use the roster and the supported installer; do not pre-create the agent environment directory or
-edit a generated projection. Before it writes any holder identity, tool, projection, or unit file,
+edit a generated projection. `mosaic fleet install` validates the roster, installs the units and
-`mosaic fleet install` validates the fleet CLI and every distinct roster runtime through the exact
+helpers, and writes private roster-derived projections before any service is started.
-pane PATH. The shared helper also unwraps `/usr/bin/env` shebangs, so a resolved Node script with no
-pane-visible Node fails before effects. `mosaic fleet doctor` reports the same named executable
-checks without mutation. After that preflight, install places the units and helpers and writes private
-roster-derived projections before any service starts.
 
 ```bash
 # Create a site-owned canary roster. Inspect an existing roster before using --force.

packages/mosaic/framework/tools/fleet/pane-runtime-path.sh

@@ -1,199 +0,0 @@
-#!/usr/bin/env bash
-# Canonical fleet-pane PATH construction and executable reachability checks.
-#
-# This file is both sourceable by start-agent-session.sh and executable by the
-# fleet CLI preflight. Keep the pane PATH in one implementation: provisioning
-# checks and the eventual pane must answer the same question.
-
-mosaic_fleet_pane_home() {
-  local mosaic_home="$1"
-  local fallback_home="$2"
-  case "$mosaic_home" in
-    */.config/mosaic) printf '%s' "${mosaic_home%/.config/mosaic}" ;;
-    *) printf '%s' "$fallback_home" ;;
-  esac
-}
-
-mosaic_fleet_build_runtime_bin_prefix() {
-  local pane_home="$1"
-  local runtime_bin="${2:-}"
-  local candidates=()
-  if [ -n "$runtime_bin" ]; then candidates+=("$runtime_bin"); fi
-  if command -v npm >/dev/null 2>&1; then
-    local npm_prefix
-    npm_prefix=$(npm config get prefix 2>/dev/null) || true
-    if [ -n "$npm_prefix" ]; then candidates+=("${npm_prefix}/bin"); fi
-  fi
-  candidates+=("$pane_home/.npm-global/bin" "$pane_home/.local/bin")
-
-  local prefix="" dir
-  for dir in "${candidates[@]}"; do
-    [ -d "$dir" ] || continue
-    case ":${prefix}:" in *":${dir}:"*) ;; *) prefix="${prefix:+$prefix:}$dir" ;; esac
-  done
-  printf '%s' "$prefix"
-}
-
-mosaic_fleet_build_pane_path() {
-  local pane_home="$1"
-  local runtime_bin="${2:-}"
-  local system_path="${3:-/usr/local/bin:/usr/bin:/bin}"
-  local prefix
-  prefix=$(mosaic_fleet_build_runtime_bin_prefix "$pane_home" "$runtime_bin")
-  printf '%s' "${prefix:+${prefix}:}${system_path}"
-}
-
-mosaic_fleet_resolve_in_pane_path() {
-  local pane_path="$1"
-  local binary="$2"
-  PATH="$pane_path" command -v -- "$binary" 2>/dev/null
-}
-
-# Sets executable evidence in MOSAIC_FLEET_EXECUTABLE_* and returns nonzero when
-# a resolved script's shebang interpreter cannot run in the pane. Native/ELF
-# binaries have no PATH-resolved interpreter dependency and pass the executable
-# bit check. Node receives an additional side-effect-free `node --version`
-# execution check; invoking `mosaic --version` itself is intentionally avoided
-# because Mosaic performs a cache-writing/network update check at CLI startup.
-mosaic_fleet_check_resolved_executable() {
-  local pane_path="$1"
-  local resolved="$2"
-  MOSAIC_FLEET_EXECUTABLE_DEPENDENCY=""
-  MOSAIC_FLEET_EXECUTABLE_PROBE=""
-  MOSAIC_FLEET_EXECUTABLE_EXIT=""
-  MOSAIC_FLEET_EXECUTABLE_OUTPUT=""
-
-  [ -x "$resolved" ] || {
-    MOSAIC_FLEET_EXECUTABLE_OUTPUT="resolved path is not executable"
-    return 70
-  }
-
-  local magic=""
-  IFS= read -r -n 2 magic < "$resolved" || true
-  [ "$magic" = '#!' ] || return 0
-
-  local shebang
-  IFS= read -r shebang < "$resolved" || true
-  shebang=${shebang%$'\r'}
-  shebang=${shebang#\#!}
-  local parts=()
-  read -r -a parts <<< "$shebang"
-  local interpreter="${parts[0]:-}"
-  [[ "$interpreter" = /* ]] && [ -x "$interpreter" ] || {
-    MOSAIC_FLEET_EXECUTABLE_DEPENDENCY="$interpreter"
-    MOSAIC_FLEET_EXECUTABLE_OUTPUT="shebang interpreter is absent or not executable"
-    return 70
-  }
-
-  local dependency="$interpreter"
-  local dependency_path="$interpreter"
-  if [ "${interpreter##*/}" = env ]; then
-    local index=1
-    if [ "${parts[$index]:-}" = -S ]; then index=$((index + 1)); fi
-    dependency="${parts[$index]:-}"
-    if [ -z "$dependency" ] || [[ "$dependency" = -* ]]; then
-      MOSAIC_FLEET_EXECUTABLE_DEPENDENCY="$dependency"
-      MOSAIC_FLEET_EXECUTABLE_OUTPUT="unsupported env shebang"
-      return 70
-    fi
-  fi
-
-  MOSAIC_FLEET_EXECUTABLE_DEPENDENCY="$dependency"
-  if [ "${dependency##*/}" = node ]; then
-    MOSAIC_FLEET_EXECUTABLE_PROBE="node --version"
-  fi
-  if [ "${interpreter##*/}" = env ]; then
-    if ! dependency_path=$(mosaic_fleet_resolve_in_pane_path "$pane_path" "$dependency"); then
-      MOSAIC_FLEET_EXECUTABLE_OUTPUT="shebang command is not on the pane PATH"
-      return 70
-    fi
-  fi
-
-  if [ "${dependency##*/}" = node ]; then
-    if MOSAIC_FLEET_EXECUTABLE_OUTPUT=$(PATH="$pane_path" "$dependency_path" --version 2>&1); then
-      MOSAIC_FLEET_EXECUTABLE_EXIT=0
-    else
-      MOSAIC_FLEET_EXECUTABLE_EXIT=$?
-      return 70
-    fi
-  fi
-  return 0
-}
-
-mosaic_fleet_runtime_path_main() {
-  local mosaic_home=""
-  local runtime_bin=""
-  local system_path="/usr/local/bin:/usr/bin:/bin"
-  local binary=""
-  local check_executable=0
-
-  while [ "$#" -gt 0 ]; do
-    case "$1" in
-      --mosaic-home)
-        [ "$#" -ge 2 ] || return 64
-        mosaic_home="$2"
-        shift 2
-        ;;
-      --runtime-bin)
-        [ "$#" -ge 2 ] || return 64
-        runtime_bin="$2"
-        shift 2
-        ;;
-      --binary)
-        [ "$#" -ge 2 ] || return 64
-        binary="$2"
-        shift 2
-        ;;
-      --check-executable)
-        check_executable=1
-        shift
-        ;;
-      # Test seam for measuring a greenfield host with no system Node. The
-      # launcher and production CLI omit it and retain the fixed system suffix.
-      --system-path)
-        [ "$#" -ge 2 ] || return 64
-        system_path="$2"
-        shift 2
-        ;;
-      *) return 64 ;;
-    esac
-  done
-
-  [ -n "$mosaic_home" ] && [ -n "$binary" ] || return 64
-  local pane_home pane_path resolved
-  pane_home=$(mosaic_fleet_pane_home "$mosaic_home" "${HOME:-}")
-  # npm config is HOME-sensitive. Pin it to the derived pane home before asking
-  # for its prefix so an operator's unrelated npmrc cannot influence preflight.
-  HOME=$pane_home
-  export HOME
-  pane_path=$(mosaic_fleet_build_pane_path "$pane_home" "$runtime_bin" "$system_path")
-  if ! resolved=$(mosaic_fleet_resolve_in_pane_path "$pane_path" "$binary"); then
-    printf 'pane_path\0%s\0status\0missing\0binary_path\0\0dependency\0\0probe_command\0\0probe_exit\0\0probe_output\0\0' \
-      "$pane_path"
-    return 69
-  fi
-
-  if [ "$check_executable" -eq 1 ]; then
-    if mosaic_fleet_check_resolved_executable "$pane_path" "$resolved"; then
-      printf 'pane_path\0%s\0status\0present\0binary_path\0%s\0dependency\0%s\0probe_command\0%s\0probe_exit\0%s\0probe_output\0%s\0' \
-        "$pane_path" "$resolved" "$MOSAIC_FLEET_EXECUTABLE_DEPENDENCY" \
-        "$MOSAIC_FLEET_EXECUTABLE_PROBE" "$MOSAIC_FLEET_EXECUTABLE_EXIT" \
-        "$MOSAIC_FLEET_EXECUTABLE_OUTPUT"
-      return 0
-    fi
-    printf 'pane_path\0%s\0status\0unexecutable\0binary_path\0%s\0dependency\0%s\0probe_command\0%s\0probe_exit\0%s\0probe_output\0%s\0' \
-      "$pane_path" "$resolved" "$MOSAIC_FLEET_EXECUTABLE_DEPENDENCY" \
-      "$MOSAIC_FLEET_EXECUTABLE_PROBE" "$MOSAIC_FLEET_EXECUTABLE_EXIT" \
-      "$MOSAIC_FLEET_EXECUTABLE_OUTPUT"
-    return 70
-  fi
-
-  printf 'pane_path\0%s\0status\0present\0binary_path\0%s\0dependency\0\0probe_command\0\0probe_exit\0\0probe_output\0\0' \
-    "$pane_path" "$resolved"
-  return 0
-}
-
-if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
-  set -euo pipefail
-  mosaic_fleet_runtime_path_main "$@"
-fi

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

@@ -258,22 +258,46 @@ if _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
 fi
 
 # Systemd passes HOME as %h, and the installed service fixes MOSAIC_HOME under
-# that home. The provisioning preflight executes this same helper under the
+# that home. Derive the pane home from the canonical path when available so an
-# unit's clean launcher environment, so operator PATH cannot produce a false
+# inherited pane/session HOME cannot become runtime authority.
-# green result for a binary the pane will never see.
+PANE_HOME=$HOME
-SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+case "$MOSAIC_HOME" in
-# shellcheck source=pane-runtime-path.sh
+  */.config/mosaic) PANE_HOME=${MOSAIC_HOME%/.config/mosaic} ;;
-. "$SCRIPT_DIR/pane-runtime-path.sh"
+esac
-PANE_HOME=$(mosaic_fleet_pane_home "$MOSAIC_HOME" "$HOME")
-PANE_PATH=$(mosaic_fleet_build_pane_path "$PANE_HOME" "$MOSAIC_RUNTIME_BIN")
 
-# #1241/#1256. The pane runs `mosaic yolo <runtime>` under PANE_PATH with a
+_build_runtime_bin_prefix() {
-# cleared environment. Resolve both names and validate any shebang interpreter
+  local candidates=()
-# here, before an effect, where the failure remains attributable. Name
+  if [ -n "$MOSAIC_RUNTIME_BIN" ]; then candidates+=("$MOSAIC_RUNTIME_BIN"); fi
-# resolution alone is insufficient: an `#!/usr/bin/env node` script resolves
+  if command -v npm >/dev/null 2>&1; then
-# even when the pane cannot execute it because Node is absent.
+    local npm_prefix
+    npm_prefix=$(npm config get prefix 2>/dev/null) || true
+    if [ -n "$npm_prefix" ]; then candidates+=("${npm_prefix}/bin"); fi
+  fi
+  candidates+=("$PANE_HOME/.npm-global/bin" "$PANE_HOME/.local/bin")
+
+  local prefix="" dir
+  for dir in "${candidates[@]}"; do
+    [ -d "$dir" ] || continue
+    case ":${prefix}:" in *":${dir}:"*) ;; *) prefix="${prefix:+$prefix:}$dir" ;; esac
+  done
+  printf '%s' "$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() {
-  mosaic_fleet_resolve_in_pane_path "$PANE_PATH" "$1"
+  PATH="$PANE_PATH" command -v -- "$1" 2>/dev/null
 }
 
 # Exit 69 (EX_UNAVAILABLE): the seat cannot be provided. Distinguished from the
@@ -288,15 +312,8 @@ fail_launch() {
 }
 
 for required_binary in mosaic "$MOSAIC_AGENT_RUNTIME"; do
-  resolved_binary=$(_resolve_in_pane_path "$required_binary") ||
+  _resolve_in_pane_path "$required_binary" >/dev/null ||
     fail_launch missing-binary "'${required_binary}' is not on the pane PATH (${PANE_PATH})"
-  if mosaic_fleet_check_resolved_executable "$PANE_PATH" "$resolved_binary"; then
-    continue
-  else
-    executable_exit=$?
-  fi
-  fail_launch unexecutable-binary \
-    "'${required_binary}' resolves to '${resolved_binary}' but dependency '${MOSAIC_FLEET_EXECUTABLE_DEPENDENCY:-unknown}' is not executable on the pane PATH (${PANE_PATH}); check_exit=${executable_exit} detail=${MOSAIC_FLEET_EXECUTABLE_OUTPUT:-unavailable}"
 done
 
 _ensure_claude_workdir_trusted() {

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

@@ -484,27 +484,6 @@ assert_missing_pane_binary_rejected() {
 assert_missing_pane_binary_rejected mosaic
 assert_missing_pane_binary_rejected pi
 
-# #1256. Name resolution is not executable reachability. A script can resolve
-# while its /usr/bin/env shebang command is absent from PANE_PATH; reject that
-# before tmux creates the doomed session.
-: > "$TMUX_CALLS"
-HOME_UNEXECUTABLE="$ROOT/unexecutable-shebang"
-write_generated "$HOME_UNEXECUTABLE" "coder-unexecutable"
-rm -f "$HOME_UNEXECUTABLE/.npm-global/bin/mosaic"
-printf '#!/usr/bin/env mosaic-test-absent-interpreter\n' > \
-  "$HOME_UNEXECUTABLE/.npm-global/bin/mosaic"
-chmod +x "$HOME_UNEXECUTABLE/.npm-global/bin/mosaic"
-if output=$(MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_UNEXECUTABLE" coder-unexecutable 2>&1); then
-  fail "launcher accepted a resolved mosaic script with an absent shebang command"
-fi
-echo "$output" | grep -qF 'code=unexecutable-binary' || \
-  fail "unexecutable shebang diagnostic missing: $output"
-echo "$output" | grep -qF 'mosaic-test-absent-interpreter' || \
-  fail "unexecutable shebang diagnostic did not name the missing dependency"
-if tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session; then
-  fail "launcher created a session after its shebang dependency check failed"
-fi
-
 # #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

packages/mosaic/src/commands/fleet-reconciler-command.spec.ts

@@ -1,13 +1,9 @@
 import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { Command } from 'commander';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { type FleetReconcileDeps } from '../fleet/fleet-reconciler.js';
-import {
-  type FleetRuntimeProbeResult,
-  type FleetRuntimeProbeRunner,
-} from '../fleet/fleet-runtime-preflight.js';
 import { registerFleetCommand, type CommandResult, type FleetCommandDeps } from './fleet.js';
 
 const roster = `
@@ -69,15 +65,12 @@ function program(
   mosaicHome: string,
   runner: FleetCommandDeps['runner'],
   reconcileOverrides: Partial<FleetReconcileDeps> = {},
-  runtimeProbeRunner: FleetRuntimeProbeRunner = runtimeProbe('present'),
 ): Command {
   const result = new Command();
   result.exitOverride();
   registerFleetCommand(result, {
     mosaicHome,
     runner,
-    frameworkRoot: resolve(process.cwd(), 'framework'),
-    runtimeProbeRunner,
     reconcileDeps: {
       homeDirectory: '/home/mosaic',
       readHolderIdentity: async () => '11111111-1111-4111-8111-111111111111',
@@ -90,24 +83,6 @@ function program(
   return result;
 }
 
-function runtimeProbe(status: 'present' | 'missing'): FleetRuntimeProbeRunner {
-  return async (_command, args): Promise<FleetRuntimeProbeResult> => {
-    const binaryFlag = args.indexOf('--binary');
-    const binary = binaryFlag >= 0 ? args[binaryFlag + 1] : undefined;
-    const effectiveStatus = binary === 'mosaic' ? 'present' : status;
-    return {
-      stdout:
-        `pane_path\u0000/fixture/runtime-bin:/usr/bin:/bin\u0000status\u0000${effectiveStatus}\u0000` +
-        `binary_path\u0000${effectiveStatus === 'present' ? `/fixture/runtime-bin/${binary ?? 'unknown'}` : ''}\u0000` +
-        `dependency\u0000${effectiveStatus === 'present' ? 'node' : ''}\u0000` +
-        `probe_command\u0000${effectiveStatus === 'present' ? 'node --version' : ''}\u0000` +
-        `probe_exit\u0000${effectiveStatus === 'present' ? '0' : ''}\u0000probe_output\u0000\u0000`,
-      stderr: '',
-      exitCode: effectiveStatus === 'present' ? 0 : 69,
-    };
-  };
-}
-
 function capture(): string[] {
   const lines: string[] = [];
   vi.spyOn(console, 'log').mockImplementation((value: string): void => {
@@ -177,64 +152,13 @@ describe('mosaic fleet reconciler commands', (): void => {
 
     expect(lines.map((line: string): unknown => JSON.parse(line))).toMatchObject([
       { applied: false, lifecycle: 'not-applied' },
-      {
+      { applied: false, lifecycle: 'not-applied' },
-        applied: false,
-        lifecycle: 'not-applied',
-        checks: {
-          fleetCliExecutable: [
-            {
-              check: 'fleet-cli-executable',
-              status: 'ok',
-              requestedBy: ['coder0'],
-              dependency: 'node',
-              probeCommand: 'node --version',
-            },
-          ],
-          fleetRuntimeAvailability: [
-            {
-              check: 'fleet-runtime-available',
-              runtime: 'pi',
-              status: 'ok',
-              requestedBy: ['coder0'],
-            },
-          ],
-        },
-      },
     ]);
     expect(
       calls.every((call: string[]): boolean => call[0] !== 'systemctl' || call[2] === 'show'),
     ).toBe(true);
   });
 
-  it('reports a missing roster runtime as a named non-green doctor check', async (): Promise<void> => {
-    const home = await fleetHome();
-    const lines = capture();
-
-    await program(home, ownedRunner([]), {}, runtimeProbe('missing')).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'doctor',
-    ]);
-
-    expect(JSON.parse(lines.pop() ?? '')).toMatchObject({
-      applied: false,
-      checks: {
-        fleetRuntimeAvailability: [
-          {
-            check: 'fleet-runtime-available',
-            runtime: 'pi',
-            status: 'missing',
-            requestedBy: ['coder0'],
-            panePath: '/fixture/runtime-bin:/usr/bin:/bin',
-            installCommand: 'npm install -g @earendil-works/pi-coding-agent',
-          },
-        ],
-      },
-    });
-    expect(process.exitCode).toBe(1);
-  });
-
   it.each(['start', 'stop', 'restart'] as const)(
     'uses exact roster-owned systemd targeting for %s',
     async (operation: 'start' | 'stop' | 'restart'): Promise<void> => {

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

@@ -8,18 +8,10 @@ import {
   type FleetReconcileCommand,
   type FleetReconcileDeps,
 } from '../fleet/fleet-reconciler.js';
-import {
-  inspectFleetRuntimeAvailability,
-  type FleetRuntimeInspection,
-  type FleetRuntimePreflightCheck,
-  type FleetRuntimeProbeRunner,
-} from '../fleet/fleet-runtime-preflight.js';
 import { parseRosterV2 } from '../fleet/roster-v2.js';
 
 export interface FleetReconcilerCommandDeps {
   readonly runner: CommandRunner;
-  readonly runtimeProbeRunner?: FleetRuntimeProbeRunner;
-  readonly frameworkRoot?: string;
   readonly mosaicHome?: string;
   readonly reconcileDeps?: Omit<FleetReconcileDeps, 'runner' | 'mosaicHome'>;
 }
@@ -79,10 +71,6 @@ export async function executeReconcilerCommand(
   const mosaicHome = resolveMosaicHome(fleetCommand, deps);
   const rosterPath = resolveRosterPath(fleetCommand, mosaicHome);
   const roster = parseRosterV2(await readFile(rosterPath, 'utf8'), 'yaml');
-  const runtimeInspection =
-    operation === 'doctor'
-      ? await inspectRuntimeAvailability(roster.agents, mosaicHome, deps)
-      : undefined;
   const mutating = operation === 'apply' || operation === 'reconcile' || isLifecycle(operation);
   const expectedGeneration = mutating
     ? parseExpectedGeneration(opts.expectedGeneration)
@@ -102,31 +90,8 @@ export async function executeReconcilerCommand(
       ...(deps.reconcileDeps ?? {}),
     },
   });
-  printJson(operation === 'doctor' ? { ...result, checks: runtimeInspection } : result);
+  printJson(result);
-  const executableFailure =
+  process.exitCode = result.recovery === undefined && result.cleanup === undefined ? 0 : 1;
-    runtimeInspection !== undefined &&
-    [...runtimeInspection.fleetCliExecutable, ...runtimeInspection.fleetRuntimeAvailability].some(
-      (check: FleetRuntimePreflightCheck): boolean => check.status !== 'ok',
-    );
-  process.exitCode =
-    result.recovery === undefined && result.cleanup === undefined && !executableFailure ? 0 : 1;
-}
-
-async function inspectRuntimeAvailability(
-  agents: readonly { readonly name: string; readonly runtime: string }[],
-  mosaicHome: string,
-  deps: FleetReconcilerCommandDeps,
-): Promise<FleetRuntimeInspection> {
-  if (deps.frameworkRoot === undefined || deps.runtimeProbeRunner === undefined) {
-    throw new Error('Fleet doctor runtime preflight dependencies are unavailable.');
-  }
-  return inspectFleetRuntimeAvailability({
-    mosaicHome,
-    agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
-    helperPath: join(deps.frameworkRoot, 'tools', 'fleet', 'pane-runtime-path.sh'),
-    agents,
-    runner: deps.runtimeProbeRunner,
-  });
 }
 
 function isLifecycle(operation: FleetReconcileCommand): boolean {

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

@@ -4,7 +4,6 @@ import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { Command } from 'commander';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import type { FleetRuntimeProbeRunner } from '../fleet/fleet-runtime-preflight.js';
 import { registerFleetCommand, type CommandResult, type CommandRunner } from './fleet.js';
 
 /**
@@ -70,7 +69,6 @@ agents:
 let tempHome: string | undefined;
 const savedHome = process.env.HOME;
 const savedMosaicHome = process.env.MOSAIC_HOME;
-const savedPath = process.env.PATH;
 
 afterEach(async (): Promise<void> => {
   vi.restoreAllMocks();
@@ -79,8 +77,6 @@ afterEach(async (): Promise<void> => {
   else process.env.HOME = savedHome;
   if (savedMosaicHome === undefined) delete process.env.MOSAIC_HOME;
   else process.env.MOSAIC_HOME = savedMosaicHome;
-  if (savedPath === undefined) delete process.env.PATH;
-  else process.env.PATH = savedPath;
   if (tempHome) await rm(tempHome, { recursive: true, force: true });
   tempHome = undefined;
 });
@@ -89,7 +85,7 @@ afterEach(async (): Promise<void> => {
  * A HOME with a roster-v2 fleet and nothing else — the greenfield shape, before
  * anything has been installed, applied or started.
  */
-async function v2Home(options: { withPaneRuntime?: boolean } = {}): Promise<string> {
+async function v2Home(): Promise<string> {
   tempHome = await mkdtemp(join(tmpdir(), 'mosaic-fleet-v2-dispatch-'));
   process.env.HOME = tempHome;
   delete process.env.MOSAIC_HOME;
@@ -101,12 +97,6 @@ async function v2Home(options: { withPaneRuntime?: boolean } = {}): Promise<stri
   await writeFile(join(mosaicHome, 'fleet', 'roles', 'code.md'), '`class: code`\n\n# code\n', {
     mode: 0o600,
   });
-  const runtimeDir = join(tempHome, '.npm-global', 'bin');
-  await mkdir(runtimeDir, { recursive: true });
-  await writeFile(join(runtimeDir, 'mosaic'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
-  if (options.withPaneRuntime !== false) {
-    await writeFile(join(runtimeDir, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
-  }
   return mosaicHome;
 }
 
@@ -123,17 +113,10 @@ const greenfieldRunner: CommandRunner = async (command): Promise<CommandResult>
   return { stdout: '', stderr: '', exitCode: 1 };
 };
 
-function program(
+function program(runner: CommandRunner = greenfieldRunner): Command {
-  runner: CommandRunner = greenfieldRunner,
-  runtimeProbeRunner?: FleetRuntimeProbeRunner,
-): Command {
   const result = new Command();
   result.exitOverride();
-  registerFleetCommand(result, {
+  registerFleetCommand(result, { runner, frameworkRoot: resolve(process.cwd(), 'framework') });
-    runner,
-    frameworkRoot: resolve(process.cwd(), 'framework'),
-    ...(runtimeProbeRunner === undefined ? {} : { runtimeProbeRunner }),
-  });
   return result;
 }
 
@@ -183,93 +166,6 @@ describe('mosaic fleet ps — roster v2', (): void => {
 });
 
 describe('mosaic fleet install — roster v2', (): void => {
-  it('rejects a roster runtime missing from the pane PATH before installing any files', async (): Promise<void> => {
-    const mosaicHome = await v2Home({ withPaneRuntime: false });
-    const operatorBin = join(tempHome!, 'operator-bin');
-    await mkdir(operatorBin, { recursive: true });
-    await writeFile(join(operatorBin, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
-    process.env.PATH = `${operatorBin}:${savedPath ?? '/usr/bin:/bin'}`;
-
-    let message = '';
-    try {
-      await program().parseAsync([
-        'node',
-        'mosaic',
-        'fleet',
-        '--mosaic-home',
-        mosaicHome,
-        'install',
-        '--no-enable',
-      ]);
-    } catch (error: unknown) {
-      message = error instanceof Error ? error.message : String(error);
-    }
-
-    expect(message).toContain('runtime=pi');
-    expect(message).toContain('requested_by=coder0,coder1');
-    expect(message).toContain('pane_path=');
-    expect(message).toContain('npm install -g @earendil-works/pi-coding-agent');
-    expect(message).not.toContain(operatorBin);
-    expect(
-      await exists(join(tempHome!, '.config', 'systemd', 'user', '[email protected]')),
-    ).toBe(false);
-    expect(await exists(join(mosaicHome, 'fleet', 'holder.id'))).toBe(false);
-    expect(await exists(join(mosaicHome, 'tools'))).toBe(false);
-  });
-
-  it('rejects resolved Node-shebang commands when Node is absent from the pane PATH', async (): Promise<void> => {
-    const mosaicHome = await v2Home();
-    const runtimeDir = join(tempHome!, '.npm-global', 'bin');
-    const nodeScript = '#!/usr/bin/env node\nconsole.log("should-not-run");\n';
-    await writeFile(join(runtimeDir, 'mosaic'), nodeScript, { mode: 0o755 });
-    await writeFile(join(runtimeDir, 'pi'), nodeScript, { mode: 0o755 });
-    await writeFile(join(tempHome!, '.npmrc'), `prefix=${join(tempHome!, 'absent-prefix')}\n`);
-    const isolatedSystemPath = join(tempHome!, 'system-bin');
-    await mkdir(isolatedSystemPath, { recursive: true });
-    const isolatedProbeRunner: FleetRuntimeProbeRunner = async (
-      command,
-      args,
-    ): Promise<CommandResult> =>
-      new Promise((settle) => {
-        const child = execFile(
-          command,
-          [...args, '--system-path', isolatedSystemPath],
-          { encoding: 'utf8' },
-          (error, stdout, stderr) => {
-            settle({
-              stdout,
-              stderr,
-              exitCode: child.exitCode ?? (error === null ? 0 : 1),
-            });
-          },
-        );
-      });
-
-    let message = '';
-    try {
-      await program(greenfieldRunner, isolatedProbeRunner).parseAsync([
-        'node',
-        'mosaic',
-        'fleet',
-        '--mosaic-home',
-        mosaicHome,
-        'install',
-        '--no-enable',
-      ]);
-    } catch (error: unknown) {
-      message = error instanceof Error ? error.message : String(error);
-    }
-
-    expect(message).toContain('check=fleet-cli-executable');
-    expect(message).toContain('binary=mosaic');
-    expect(message).toContain('dependency=node');
-    expect(message).toContain('check=fleet-runtime-available');
-    expect(message).toContain('runtime=pi');
-    expect(message).not.toContain('/usr/bin');
-    expect(await exists(join(mosaicHome, 'fleet', 'holder.id'))).toBe(false);
-    expect(await exists(join(mosaicHome, 'tools'))).toBe(false);
-  });
-
   it('places the tool files and unit templates', async (): Promise<void> => {
     const mosaicHome = await v2Home();
     capture();
@@ -287,11 +183,9 @@ describe('mosaic fleet install — roster v2', (): void => {
     ]) {
       expect(await exists(join(systemdUserDir, unit))).toBe(true);
     }
-    for (const tool of ['start-agent-session.sh', 'pane-runtime-path.sh']) {
+    const launcher = join(mosaicHome, 'tools', 'fleet', 'start-agent-session.sh');
-      const toolPath = join(mosaicHome, 'tools', 'fleet', tool);
+    expect(await exists(launcher)).toBe(true);
-      expect(await exists(toolPath)).toBe(true);
+    expect((await stat(launcher)).mode & 0o777).toBe(0o755);
-      expect((await stat(toolPath)).mode & 0o777).toBe(0o755);
-    }
   });
 
   it('writes NO generated env — that file belongs to the reconciler (#791)', async (): Promise<void> => {

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

@@ -1277,10 +1277,6 @@ describe('fleet command construction', () => {
     const home = await tempDir();
     process.env.HOME = home;
     delete process.env.MOSAIC_HOME;
-    const runtimeDir = join(home, '.npm-global', 'bin');
-    await mkdir(runtimeDir, { recursive: true });
-    await writeFile(join(runtimeDir, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
-    await writeFile(join(runtimeDir, 'mosaic'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
     const mosaicHome = join(home, '.config', 'mosaic');
     const program = new Command();
     program.exitOverride();
@@ -1319,10 +1315,6 @@ describe('fleet command construction', () => {
     const originalHome = process.env.HOME;
     const home = await tempDir();
     process.env.HOME = home;
-    const runtimeDir = join(home, '.npm-global', 'bin');
-    await mkdir(runtimeDir, { recursive: true });
-    await writeFile(join(runtimeDir, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
-    await writeFile(join(runtimeDir, 'mosaic'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
     const mosaicHome = join(home, '.config', 'mosaic');
     const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
     const fleetDir = join(mosaicHome, 'fleet');

packages/mosaic/src/commands/fleet.ts

@@ -60,12 +60,6 @@ import {
   writeAgentEnvironmentProjection,
   writeManagedFleetRoster,
 } from '../fleet/generated-env-boundary.js';
-import {
-  assertFleetRuntimeAvailability,
-  FleetRuntimePreflightError,
-  inspectFleetRuntimeAvailability,
-  type FleetRuntimeProbeRunner,
-} from '../fleet/fleet-runtime-preflight.js';
 import { registerFleetBacklogCommand } from './fleet-backlog.js';
 import { registerFleetPersonaCommand } from './fleet-personas.js';
 import { registerFleetProfileCommand } from './fleet-profiles.js';
@@ -95,8 +89,6 @@ export type SleepFn = (ms: number) => Promise<void>;
 
 export interface FleetCommandDeps {
   runner?: CommandRunner;
-  /** Executes the pane-PATH helper under a clean launcher environment. */
-  runtimeProbeRunner?: FleetRuntimeProbeRunner;
   /** Injectable interactive runner for commands needing inherited TTY (e.g., `tmux attach`). */
   interactiveRunner?: InteractiveRunner;
   /**
@@ -1437,10 +1429,6 @@ export function isSendAccepted(capturedOutput: string): SendVerifyResult {
 
 export function registerFleetCommand(program: Command, deps: FleetCommandDeps = {}): Command {
   const runner = deps.runner ?? runCommand;
-  const runtimeProbeRunner: FleetRuntimeProbeRunner =
-    deps.runtimeProbeRunner ??
-    (async (command: string, args: readonly string[]): Promise<CommandResult> =>
-      runCommand(command, [...args]));
   const sleepFn = deps.sleepFn ?? defaultSleep;
   const paths = resolveFleetPaths(deps.mosaicHome);
   const frameworkRoot = deps.frameworkRoot ?? resolveFrameworkRoot();
@@ -1539,7 +1527,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot, runtimeProbeRunner);
+      await installFleet(cmd, frameworkRoot);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -1550,7 +1538,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot, runtimeProbeRunner);
+      await installFleet(cmd, frameworkRoot);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -2096,8 +2084,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
   });
   registerFleetReconcilerCommands(cmd, {
     runner,
-    runtimeProbeRunner,
-    frameworkRoot,
     mosaicHome: deps.mosaicHome,
     reconcileDeps: deps.reconcileDeps,
   });
@@ -2363,68 +2349,18 @@ export function registerFleetAgentCommands(
     });
 }
 
-async function installFleet(
+async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
-  cmd: Command,
-  frameworkRoot: string,
-  runtimeProbeRunner: FleetRuntimeProbeRunner,
-): Promise<void> {
   const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
   assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
-  // Read and preflight before the first mkdir/copy/chmod/write. A successful
+  // Read model first: every file this function places is roster-independent, and
-  // install must mean every roster runtime is executable in the eventual pane,
+  // the v1 parser would reject a v2 roster before any of them were written.
-  // not merely visible to the operator who invoked this command.
   const roster = await loadRosterReadModel(cmd);
-  const v1Roster = roster.version === 1 ? await loadRosterForCommand(cmd) : undefined;
-  const preflightV1Projections =
-    v1Roster === undefined
-      ? []
-      : await Promise.all(
-          v1Roster.agents.map((agent: FleetAgent) =>
-            prepareAgentEnvironmentProjection({
-              mosaicHome: activePaths.mosaicHome,
-              agentEnvDir: activePaths.agentEnvDir,
-              agentName: agent.name,
-              generated: generateAgentEnvValues(v1Roster, agent),
-            }),
-          ),
-        );
-  const preflightAgents =
-    v1Roster === undefined
-      ? roster.agents
-      : v1Roster.agents.map((agent: FleetAgent, index: number) => {
-          const prepared = preflightV1Projections[index];
-          if (prepared === undefined) {
-            throw new Error(`Missing prepared environment projection for ${agent.name}.`);
-          }
-          const local = parseAgentEnvironment(prepared.local, 'local');
-          return {
-            name: agent.name,
-            runtime: agent.runtime,
-            runtimeBin: local['MOSAIC_RUNTIME_BIN'] ?? '',
-          };
-        });
-  const runtimeInspection = await inspectFleetRuntimeAvailability({
-    mosaicHome: activePaths.mosaicHome,
-    agentEnvDir: activePaths.agentEnvDir,
-    helperPath: join(frameworkRoot, 'tools', 'fleet', 'pane-runtime-path.sh'),
-    agents: preflightAgents,
-    runner: runtimeProbeRunner,
-  });
-  try {
-    assertFleetRuntimeAvailability(runtimeInspection);
-  } catch (error: unknown) {
-    if (error instanceof FleetRuntimePreflightError) {
-      cmd.error(error.message, { code: 'fleet.runtime-preflight', exitCode: 1 });
-    }
-    throw error;
-  }
   await ensureFleetHolderIdentity(activePaths.mosaicHome);
   await mkdir(activePaths.fleetToolsDir, { recursive: true });
   await mkdir(activePaths.tmuxToolsDir, { recursive: true });
   await mkdir(activePaths.systemdUserDir, { recursive: true });
 
   const startAgentSessionPath = join(activePaths.fleetToolsDir, 'start-agent-session.sh');
-  const paneRuntimePath = join(activePaths.fleetToolsDir, 'pane-runtime-path.sh');
   const startInteractionServicePath = join(
     activePaths.fleetToolsDir,
     'start-interaction-service.sh',
@@ -2438,7 +2374,6 @@ async function installFleet(
   const agentSendPath = join(activePaths.tmuxToolsDir, 'agent-send.sh');
   const executableToolPaths = [
     startAgentSessionPath,
-    paneRuntimePath,
     startInteractionServicePath,
     startTmuxHolderPath,
     printInteractionPolicyPath,
@@ -2449,7 +2384,6 @@ async function installFleet(
     join(frameworkRoot, 'tools', 'fleet', 'start-agent-session.sh'),
     startAgentSessionPath,
   );
-  await copyFile(join(frameworkRoot, 'tools', 'fleet', 'pane-runtime-path.sh'), paneRuntimePath);
   await copyFile(
     join(frameworkRoot, 'tools', 'fleet', 'start-interaction-service.sh'),
     startInteractionServicePath,
@@ -2493,9 +2427,7 @@ async function installFleet(
     return;
   }
 
-  if (v1Roster === undefined) {
+  const v1Roster = await loadRosterForCommand(cmd);
-    throw new Error('Roster version changed while installing fleet files.');
-  }
   for (const agent of v1Roster.agents) {
     await writeAgentEnvironmentProjection({
       mosaicHome: activePaths.mosaicHome,

packages/mosaic/src/fleet/fleet-runtime-preflight.spec.ts

@@ -1,328 +0,0 @@
-import { spawn } from 'node:child_process';
-import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
-import {
-  inspectFleetRuntimeAvailability,
-  type FleetRuntimeProbeResult,
-  type FleetRuntimeProbeRunner,
-} from './fleet-runtime-preflight.js';
-
-const helperPath = resolve(process.cwd(), 'framework', 'tools', 'fleet', 'pane-runtime-path.sh');
-let cleanup: string | undefined;
-
-afterEach(async (): Promise<void> => {
-  if (cleanup !== undefined) await rm(cleanup, { recursive: true, force: true });
-  cleanup = undefined;
-});
-
-interface FleetFixture {
-  readonly root: string;
-  readonly mosaicHome: string;
-  readonly agentEnvDir: string;
-  readonly runtimeDir: string;
-}
-
-async function fleetHome(): Promise<FleetFixture> {
-  const root = await mkdtemp(join(tmpdir(), 'mosaic-fleet-runtime-preflight-'));
-  cleanup = root;
-  const mosaicHome = join(root, '.config', 'mosaic');
-  const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
-  const runtimeDir = join(root, '.npm-global', 'bin');
-  await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
-  await mkdir(runtimeDir, { recursive: true });
-  for (const directory of [mosaicHome, join(mosaicHome, 'fleet'), agentEnvDir]) {
-    await chmod(directory, 0o700);
-  }
-  await writeExecutable(runtimeDir, 'mosaic', '#!/bin/sh\nexit 0\n');
-  return { root, mosaicHome, agentEnvDir, runtimeDir };
-}
-
-async function writeExecutable(directory: string, name: string, content: string): Promise<void> {
-  await mkdir(directory, { recursive: true });
-  await writeFile(join(directory, name), content, { mode: 0o755 });
-}
-
-const processRunner: FleetRuntimeProbeRunner = async (
-  command: string,
-  args: readonly string[],
-): Promise<FleetRuntimeProbeResult> =>
-  new Promise((settle) => {
-    const child = spawn(command, [...args], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.setEncoding('utf8');
-    child.stderr.setEncoding('utf8');
-    child.stdout.on('data', (chunk: string): void => {
-      stdout += chunk;
-    });
-    child.stderr.on('data', (chunk: string): void => {
-      stderr += chunk;
-    });
-    child.on('error', (error: Error): void => {
-      settle({ stdout, stderr: `${stderr}${error.message}`, exitCode: 127 });
-    });
-    child.on('close', (code: number | null): void => {
-      settle({ stdout, stderr, exitCode: code ?? 1 });
-    });
-  });
-
-describe('fleet runtime preflight', (): void => {
-  it('executes one distinct pane runtime and aggregates every requesting roster row', async (): Promise<void> => {
-    const fixture = await fleetHome();
-    await writeExecutable(fixture.runtimeDir, 'pi', '#!/bin/sh\nexit 0\n');
-    let probes = 0;
-
-    const inspection = await inspectFleetRuntimeAvailability({
-      mosaicHome: fixture.mosaicHome,
-      agentEnvDir: fixture.agentEnvDir,
-      helperPath,
-      agents: [
-        { name: 'coder1', runtime: 'pi' },
-        { name: 'coder0', runtime: 'pi' },
-      ],
-      runner: async (command, args): Promise<FleetRuntimeProbeResult> => {
-        probes += 1;
-        return processRunner(command, args);
-      },
-    });
-
-    expect(probes).toBe(2);
-    expect(inspection.fleetCliExecutable).toEqual([
-      expect.objectContaining({
-        check: 'fleet-cli-executable',
-        status: 'ok',
-        requestedBy: ['coder0', 'coder1'],
-        binaryPath: join(fixture.runtimeDir, 'mosaic'),
-        dependency: '/bin/sh',
-      }),
-    ]);
-    expect(inspection.fleetRuntimeAvailability).toEqual([
-      expect.objectContaining({
-        check: 'fleet-runtime-available',
-        runtime: 'pi',
-        status: 'ok',
-        requestedBy: ['coder0', 'coder1'],
-        binaryPath: join(fixture.runtimeDir, 'pi'),
-        dependency: '/bin/sh',
-        installCommand: 'npm install -g @earendil-works/pi-coding-agent',
-      }),
-    ]);
-    expect(inspection.fleetRuntimeAvailability[0]?.panePath).toContain(fixture.runtimeDir);
-  });
-
-  it('returns an actionable non-green check when the pane PATH lacks the runtime', async (): Promise<void> => {
-    const fixture = await fleetHome();
-
-    const inspection = await inspectFleetRuntimeAvailability({
-      mosaicHome: fixture.mosaicHome,
-      agentEnvDir: fixture.agentEnvDir,
-      helperPath,
-      agents: [{ name: 'coder0', runtime: 'pi' }],
-      runner: processRunner,
-    });
-
-    expect(inspection.fleetCliExecutable[0]?.status).toBe('ok');
-    expect(inspection.fleetRuntimeAvailability).toEqual([
-      expect.objectContaining({
-        check: 'fleet-runtime-available',
-        runtime: 'pi',
-        status: 'missing',
-        requestedBy: ['coder0'],
-        installCommand: 'npm install -g @earendil-works/pi-coding-agent',
-      }),
-    ]);
-    expect(inspection.fleetRuntimeAvailability[0]?.panePath).not.toContain(
-      process.env['PATH'] ?? 'operator-path-absent',
-    );
-  });
-
-  it('executes the side-effect-free Node version probe for Node-shebang commands', async (): Promise<void> => {
-    const fixture = await fleetHome();
-    const nodeScript = '#!/usr/bin/env node\nconsole.log("should-not-run");\n';
-    await writeExecutable(fixture.runtimeDir, 'mosaic', nodeScript);
-    await writeExecutable(fixture.runtimeDir, 'pi', nodeScript);
-    await writeExecutable(
-      fixture.runtimeDir,
-      'node',
-      '#!/bin/sh\n[ "$1" = --version ] || exit 9\nprintf "v-fixture-node\\n"\n',
-    );
-
-    const inspection = await inspectFleetRuntimeAvailability({
-      mosaicHome: fixture.mosaicHome,
-      agentEnvDir: fixture.agentEnvDir,
-      helperPath,
-      agents: [{ name: 'coder0', runtime: 'pi' }],
-      runner: processRunner,
-    });
-
-    for (const check of [
-      ...inspection.fleetCliExecutable,
-      ...inspection.fleetRuntimeAvailability,
-    ]) {
-      expect(check).toMatchObject({
-        status: 'ok',
-        dependency: 'node',
-        probeCommand: 'node --version',
-        probeExit: 0,
-        probeOutput: 'v-fixture-node',
-      });
-    }
-  });
-
-  it('reddens when resolved Node-shebang commands cannot execute without pane Node', async (): Promise<void> => {
-    const fixture = await fleetHome();
-    const isolatedSystemPath = join(fixture.root, 'system-bin');
-    await mkdir(isolatedSystemPath, { recursive: true });
-    await writeFile(
-      join(fixture.root, '.npmrc'),
-      `prefix=${join(fixture.root, 'absent-prefix')}\n`,
-    );
-    const nodeScript = '#!/usr/bin/env node\nconsole.log("should-not-run");\n';
-    await writeExecutable(fixture.runtimeDir, 'mosaic', nodeScript);
-    await writeExecutable(fixture.runtimeDir, 'pi', nodeScript);
-
-    const inspection = await inspectFleetRuntimeAvailability({
-      mosaicHome: fixture.mosaicHome,
-      agentEnvDir: fixture.agentEnvDir,
-      helperPath,
-      agents: [{ name: 'coder0', runtime: 'pi' }],
-      runner: processRunner,
-      systemPath: isolatedSystemPath,
-    });
-
-    expect(inspection.fleetCliExecutable).toEqual([
-      expect.objectContaining({
-        check: 'fleet-cli-executable',
-        status: 'unexecutable',
-        binaryPath: join(fixture.runtimeDir, 'mosaic'),
-        dependency: 'node',
-        probeCommand: 'node --version',
-      }),
-    ]);
-    expect(inspection.fleetRuntimeAvailability).toEqual([
-      expect.objectContaining({
-        check: 'fleet-runtime-available',
-        runtime: 'pi',
-        status: 'unexecutable',
-        binaryPath: join(fixture.runtimeDir, 'pi'),
-        dependency: 'node',
-        probeCommand: 'node --version',
-      }),
-    ]);
-    expect(inspection.fleetCliExecutable[0]?.probeOutput).toBe(
-      'shebang command is not on the pane PATH',
-    );
-    expect(inspection.fleetCliExecutable[0]?.panePath).not.toContain('/usr/bin');
-  });
-
-  it('keeps distinct effective local runtime-bin paths as distinct checks', async (): Promise<void> => {
-    const fixture = await fleetHome();
-    const firstBin = join(fixture.root, 'first-bin');
-    const secondBin = join(fixture.root, 'second-bin');
-    for (const override of [
-      { agent: 'coder0', runtimeBin: firstBin },
-      { agent: 'coder1', runtimeBin: secondBin },
-    ]) {
-      await writeExecutable(override.runtimeBin, 'pi', '#!/bin/sh\nexit 0\n');
-      await writeFile(
-        join(fixture.agentEnvDir, `${override.agent}.env.local`),
-        `MOSAIC_RUNTIME_BIN=${override.runtimeBin}\n`,
-        { mode: 0o600 },
-      );
-    }
-
-    const inspection = await inspectFleetRuntimeAvailability({
-      mosaicHome: fixture.mosaicHome,
-      agentEnvDir: fixture.agentEnvDir,
-      helperPath,
-      agents: [
-        { name: 'coder0', runtime: 'pi' },
-        { name: 'coder1', runtime: 'pi' },
-      ],
-      runner: processRunner,
-    });
-
-    expect(inspection.fleetCliExecutable).toHaveLength(2);
-    expect(inspection.fleetRuntimeAvailability).toHaveLength(2);
-    expect(inspection.fleetRuntimeAvailability.map((check) => check.requestedBy)).toEqual([
-      ['coder0'],
-      ['coder1'],
-    ]);
-    expect(inspection.fleetRuntimeAvailability.map((check) => check.binaryPath)).toEqual([
-      join(firstBin, 'pi'),
-      join(secondBin, 'pi'),
-    ]);
-  });
-
-  it('reports each distinct roster runtime with its exact install command', async (): Promise<void> => {
-    const fixture = await fleetHome();
-    let probes = 0;
-
-    const inspection = await inspectFleetRuntimeAvailability({
-      mosaicHome: fixture.mosaicHome,
-      agentEnvDir: fixture.agentEnvDir,
-      helperPath,
-      agents: [
-        { name: 'pi-seat', runtime: 'pi' },
-        { name: 'claude-seat', runtime: 'claude' },
-        { name: 'codex-seat', runtime: 'codex' },
-        { name: 'opencode-seat', runtime: 'opencode' },
-      ],
-      runner: async (): Promise<FleetRuntimeProbeResult> => {
-        probes += 1;
-        return {
-          stdout:
-            'pane_path\u0000/fixture/bin:/usr/bin:/bin\u0000status\u0000missing\u0000' +
-            'binary_path\u0000\u0000probe_exit\u0000\u0000probe_output\u0000\u0000',
-          stderr: '',
-          exitCode: 69,
-        };
-      },
-    });
-
-    expect(probes).toBe(5);
-    expect(
-      inspection.fleetRuntimeAvailability.map((check) => ({
-        runtime: check.runtime,
-        installCommand: check.installCommand,
-      })),
-    ).toEqual([
-      {
-        runtime: 'claude',
-        installCommand: 'curl -fsSL https://claude.ai/install.sh | bash',
-      },
-      {
-        runtime: 'codex',
-        installCommand: 'npm install -g @openai/codex',
-      },
-      {
-        runtime: 'opencode',
-        installCommand: 'npm install -g opencode-ai',
-      },
-      {
-        runtime: 'pi',
-        installCommand: 'npm install -g @earendil-works/pi-coding-agent',
-      },
-    ]);
-  });
-
-  it('fails closed when the shared helper returns malformed evidence', async (): Promise<void> => {
-    const fixture = await fleetHome();
-
-    await expect(
-      inspectFleetRuntimeAvailability({
-        mosaicHome: fixture.mosaicHome,
-        agentEnvDir: fixture.agentEnvDir,
-        helperPath,
-        agents: [{ name: 'coder0', runtime: 'pi' }],
-        runner: async (): Promise<FleetRuntimeProbeResult> => ({
-          stdout: 'not-a-field-protocol',
-          stderr: '',
-          exitCode: 0,
-        }),
-      }),
-    ).rejects.toThrow('malformed field output');
-  });
-});

packages/mosaic/src/fleet/fleet-runtime-preflight.ts

@@ -1,362 +0,0 @@
-import { homedir } from 'node:os';
-import { getInstallInstructions } from '../runtime/detector.js';
-import type { RuntimeName } from '../types.js';
-import { compareCodePoints } from './deterministic-order.js';
-import {
-  GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES,
-  readAgentLocalEnvironment,
-} from './generated-env-boundary.js';
-
-const RUNTIME_SET = new Set<string>(GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES);
-
-export interface FleetRuntimeRequestedAgent {
-  readonly name: string;
-  readonly runtime: string;
-  /** Planned effective local override, when provisioning has already prepared it. */
-  readonly runtimeBin?: string;
-}
-
-export interface FleetRuntimeProbeResult {
-  readonly stdout: string;
-  readonly stderr: string;
-  readonly exitCode: number;
-}
-
-export type FleetRuntimeProbeRunner = (
-  command: string,
-  args: readonly string[],
-) => Promise<FleetRuntimeProbeResult>;
-
-export interface FleetRuntimePreflightOptions {
-  readonly mosaicHome: string;
-  readonly agentEnvDir: string;
-  readonly helperPath: string;
-  readonly agents: readonly FleetRuntimeRequestedAgent[];
-  readonly runner: FleetRuntimeProbeRunner;
-  /** Test-only system suffix; production and the launcher use the helper default. */
-  readonly systemPath?: string;
-}
-
-export type FleetExecutableStatus = 'ok' | 'missing' | 'unexecutable';
-
-interface FleetExecutableEvidence {
-  readonly status: FleetExecutableStatus;
-  readonly panePath: string;
-  readonly binaryPath?: string;
-  readonly dependency?: string;
-  readonly probeCommand?: string;
-  readonly probeExit?: number;
-  readonly probeOutput?: string;
-}
-
-export interface FleetCliExecutableCheck extends FleetExecutableEvidence {
-  readonly check: 'fleet-cli-executable';
-  readonly binary: 'mosaic';
-  readonly requestedBy: readonly string[];
-}
-
-export interface FleetRuntimeCheck extends FleetExecutableEvidence {
-  readonly check: 'fleet-runtime-available';
-  readonly runtime: RuntimeName;
-  readonly requestedBy: readonly string[];
-  readonly installCommand: string;
-}
-
-export type FleetRuntimePreflightCheck = FleetCliExecutableCheck | FleetRuntimeCheck;
-
-export interface FleetRuntimeInspection {
-  readonly fleetCliExecutable: readonly FleetCliExecutableCheck[];
-  readonly fleetRuntimeAvailability: readonly FleetRuntimeCheck[];
-}
-
-interface EffectiveAgent {
-  readonly name: string;
-  readonly runtime: RuntimeName;
-  readonly runtimeBin: string;
-}
-
-interface PaneProbeGroup {
-  readonly runtimeBin: string;
-  readonly requestedBy: string[];
-}
-
-interface RuntimeProbeGroup extends PaneProbeGroup {
-  readonly runtime: RuntimeName;
-}
-
-interface BinaryProbeRequest {
-  readonly binary: string;
-  readonly runtimeBin: string;
-}
-
-export class FleetRuntimePreflightError extends Error {
-  readonly checks: readonly FleetRuntimePreflightCheck[];
-
-  constructor(checks: readonly FleetRuntimePreflightCheck[]) {
-    super(formatFleetRuntimePreflightError(checks));
-    this.name = FleetRuntimePreflightError.name;
-    this.checks = checks;
-  }
-}
-
-export class FleetRuntimeProbeError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = FleetRuntimeProbeError.name;
-  }
-}
-
-/**
- * Proves the fleet CLI and every distinct runtime/effective-bin pair resolve
- * with an executable shebang interpreter through the eventual pane PATH. The
- * helper runs under the unit's clean launcher environment, so operator PATH can
- * neither create a false green nor provide a hidden interpreter.
- */
-export async function inspectFleetRuntimeAvailability(
-  options: FleetRuntimePreflightOptions,
-): Promise<FleetRuntimeInspection> {
-  const agents = await resolveEffectiveAgents(options);
-  const paneGroups = groupPaneRequests(agents);
-  const runtimeGroups = groupRuntimeRequests(agents);
-
-  const fleetCliExecutable: FleetCliExecutableCheck[] = [];
-  for (const group of paneGroups) {
-    const evidence = await probeBinary(options, {
-      binary: 'mosaic',
-      runtimeBin: group.runtimeBin,
-    });
-    fleetCliExecutable.push({
-      check: 'fleet-cli-executable',
-      binary: 'mosaic',
-      requestedBy: sortedRequestedBy(group.requestedBy),
-      ...evidence,
-    });
-  }
-
-  const fleetRuntimeAvailability: FleetRuntimeCheck[] = [];
-  for (const group of runtimeGroups) {
-    const evidence = await probeBinary(options, {
-      binary: group.runtime,
-      runtimeBin: group.runtimeBin,
-    });
-    fleetRuntimeAvailability.push({
-      check: 'fleet-runtime-available',
-      runtime: group.runtime,
-      requestedBy: sortedRequestedBy(group.requestedBy),
-      installCommand: getInstallInstructions(group.runtime),
-      ...evidence,
-    });
-  }
-
-  return Object.freeze({
-    fleetCliExecutable: Object.freeze(fleetCliExecutable),
-    fleetRuntimeAvailability: Object.freeze(fleetRuntimeAvailability),
-  });
-}
-
-export function assertFleetRuntimeAvailability(inspection: FleetRuntimeInspection): void {
-  const checks: FleetRuntimePreflightCheck[] = [
-    ...inspection.fleetCliExecutable,
-    ...inspection.fleetRuntimeAvailability,
-  ];
-  const failures = checks.filter(
-    (check: FleetRuntimePreflightCheck): boolean => check.status !== 'ok',
-  );
-  if (failures.length > 0) throw new FleetRuntimePreflightError(failures);
-}
-
-export function formatFleetRuntimePreflightError(
-  checks: readonly FleetRuntimePreflightCheck[],
-): string {
-  const lines = ['Fleet runtime preflight failed:'];
-  for (const check of checks) {
-    const dependency = check.dependency === undefined ? '' : ` dependency=${check.dependency}`;
-    const probe = check.probeCommand === undefined ? '' : ` dependency_probe=${check.probeCommand}`;
-    const execution =
-      check.status === 'unexecutable'
-        ? ` probe_exit=${check.probeExit?.toString() ?? 'not-run'} ` +
-          `probe_output=${JSON.stringify(check.probeOutput ?? '')}`
-        : '';
-    if (check.check === 'fleet-cli-executable') {
-      lines.push(
-        `check=${check.check} binary=${check.binary} ` +
-          `requested_by=${check.requestedBy.join(',')} pane_path=${check.panePath}` +
-          `${dependency}${probe}${execution} ` +
-          'action=repair the Mosaic installation until its pane dependencies resolve',
-      );
-      continue;
-    }
-    lines.push(
-      `check=${check.check} runtime=${check.runtime} ` +
-        `requested_by=${check.requestedBy.join(',')} pane_path=${check.panePath}` +
-        `${dependency}${probe}${execution} install_command=${check.installCommand}`,
-    );
-  }
-  return lines.join('\n');
-}
-
-async function resolveEffectiveAgents(
-  options: FleetRuntimePreflightOptions,
-): Promise<readonly EffectiveAgent[]> {
-  const agents: EffectiveAgent[] = [];
-  for (const agent of options.agents) {
-    if (!isRuntimeName(agent.runtime)) {
-      throw new FleetRuntimeProbeError(`Unsupported fleet runtime: ${agent.runtime}`);
-    }
-    const runtimeBin =
-      agent.runtimeBin ??
-      (
-        await readAgentLocalEnvironment({
-          mosaicHome: options.mosaicHome,
-          agentEnvDir: options.agentEnvDir,
-          agentName: agent.name,
-        })
-      )['MOSAIC_RUNTIME_BIN'] ??
-      '';
-    agents.push({ name: agent.name, runtime: agent.runtime, runtimeBin });
-  }
-  return agents;
-}
-
-function groupPaneRequests(agents: readonly EffectiveAgent[]): readonly PaneProbeGroup[] {
-  const groups = new Map<string, PaneProbeGroup>();
-  for (const agent of agents) {
-    const current = groups.get(agent.runtimeBin);
-    if (current === undefined) {
-      groups.set(agent.runtimeBin, { runtimeBin: agent.runtimeBin, requestedBy: [agent.name] });
-    } else {
-      current.requestedBy.push(agent.name);
-    }
-  }
-  return [...groups.values()].sort((left, right): number =>
-    compareCodePoints(left.runtimeBin, right.runtimeBin),
-  );
-}
-
-function groupRuntimeRequests(agents: readonly EffectiveAgent[]): readonly RuntimeProbeGroup[] {
-  const groups = new Map<string, RuntimeProbeGroup>();
-  for (const agent of agents) {
-    const key = JSON.stringify([agent.runtime, agent.runtimeBin]);
-    const current = groups.get(key);
-    if (current === undefined) {
-      groups.set(key, {
-        runtime: agent.runtime,
-        runtimeBin: agent.runtimeBin,
-        requestedBy: [agent.name],
-      });
-    } else {
-      current.requestedBy.push(agent.name);
-    }
-  }
-  return [...groups.values()].sort((left, right): number =>
-    compareCodePoints(
-      `${left.runtime}\u0000${left.runtimeBin}`,
-      `${right.runtime}\u0000${right.runtimeBin}`,
-    ),
-  );
-}
-
-async function probeBinary(
-  options: FleetRuntimePreflightOptions,
-  probe: BinaryProbeRequest,
-): Promise<FleetExecutableEvidence> {
-  const args = [
-    '-i',
-    `HOME=${process.env['HOME'] ?? homedir()}`,
-    'PATH=/usr/bin:/bin',
-    `MOSAIC_HOME=${options.mosaicHome}`,
-    '/bin/bash',
-    '--noprofile',
-    '--norc',
-    options.helperPath,
-    '--mosaic-home',
-    options.mosaicHome,
-    '--binary',
-    probe.binary,
-    '--check-executable',
-  ];
-  if (probe.runtimeBin !== '') args.push('--runtime-bin', probe.runtimeBin);
-  if (options.systemPath !== undefined) args.push('--system-path', options.systemPath);
-
-  const result = await options.runner('/usr/bin/env', args);
-  const fields = parseNulFields(result.stdout);
-  const panePath = requiredField(fields, 'pane_path');
-  const status = requiredField(fields, 'status');
-  if (result.exitCode === 0 && status === 'present') {
-    return executableEvidence('ok', panePath, fields);
-  }
-  if (result.exitCode === 69 && status === 'missing') {
-    return { status: 'missing', panePath };
-  }
-  if (result.exitCode === 70 && status === 'unexecutable') {
-    return executableEvidence('unexecutable', panePath, fields);
-  }
-  throw new FleetRuntimeProbeError(
-    `Fleet executable probe failed: binary=${probe.binary} exit=${result.exitCode.toString()} ` +
-      `stderr=${JSON.stringify(result.stderr.trim())}`,
-  );
-}
-
-function executableEvidence(
-  status: 'ok' | 'unexecutable',
-  panePath: string,
-  fields: ReadonlyMap<string, string>,
-): FleetExecutableEvidence {
-  const dependency = requiredField(fields, 'dependency');
-  const probeCommand = requiredField(fields, 'probe_command');
-  const probeExit = requiredField(fields, 'probe_exit');
-  const probeOutput = requiredField(fields, 'probe_output');
-  return {
-    status,
-    panePath,
-    binaryPath: requiredField(fields, 'binary_path'),
-    ...(dependency === '' ? {} : { dependency }),
-    ...(probeCommand === '' ? {} : { probeCommand }),
-    ...(probeExit === '' ? {} : { probeExit: parseProbeExit(probeExit) }),
-    ...(probeOutput === '' ? {} : { probeOutput }),
-  };
-}
-
-function sortedRequestedBy(requestedBy: readonly string[]): readonly string[] {
-  return Object.freeze(
-    [...requestedBy].sort((left: string, right: string): number => compareCodePoints(left, right)),
-  );
-}
-
-function parseNulFields(source: string): ReadonlyMap<string, string> {
-  const parts = source.split('\u0000');
-  if (parts.at(-1) === '') parts.pop();
-  if (parts.length % 2 !== 0) {
-    throw new FleetRuntimeProbeError('Fleet runtime probe returned malformed field output.');
-  }
-  const fields = new Map<string, string>();
-  for (let index = 0; index < parts.length; index += 2) {
-    const key = parts[index];
-    const value = parts[index + 1];
-    if (key === undefined || value === undefined || key === '' || fields.has(key)) {
-      throw new FleetRuntimeProbeError('Fleet runtime probe returned malformed field output.');
-    }
-    fields.set(key, value);
-  }
-  return fields;
-}
-
-function requiredField(fields: ReadonlyMap<string, string>, key: string): string {
-  const value = fields.get(key);
-  if (value === undefined) {
-    throw new FleetRuntimeProbeError(`Fleet runtime probe omitted ${key}.`);
-  }
-  return value;
-}
-
-function parseProbeExit(value: string): number {
-  const exitCode = Number(value);
-  if (!Number.isSafeInteger(exitCode) || exitCode < 0) {
-    throw new FleetRuntimeProbeError('Fleet runtime probe returned an invalid execution status.');
-  }
-  return exitCode;
-}
-
-function isRuntimeName(value: string): value is RuntimeName {
-  return RUNTIME_SET.has(value);
-}

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

@@ -25,12 +25,6 @@ export interface AgentGeneratedProjectionDeletionOptions {
   readonly agentName: string;
 }
 
-export interface AgentLocalEnvironmentReadOptions {
-  readonly mosaicHome: string;
-  readonly agentEnvDir: string;
-  readonly agentName: string;
-}
-
 export interface AgentEnvironmentProjectionResult {
   readonly generatedPath: string;
   readonly localPath: string;
@@ -151,23 +145,6 @@ export function parseAgentEnvironment(
   return Object.freeze(values);
 }
 
-/**
- * Reads one agent's optional local overrides through the same path, file-type,
- * permission, key, and value boundary used by projection/launch handling.
- */
-export async function readAgentLocalEnvironment(
-  options: AgentLocalEnvironmentReadOptions,
-): Promise<Readonly<Record<string, string>>> {
-  if (!AGENT_NAME.test(options.agentName)) {
-    throw new AgentEnvBoundaryError('unsafe-agent-name', 'MOSAIC_AGENT_NAME', options.agentName);
-  }
-  await validatePrivateProjectionDirectory(options.mosaicHome, options.agentEnvDir);
-  const source = await readOptionalPrivateFile(
-    join(options.agentEnvDir, `${options.agentName}.env.local`),
-  );
-  return source === undefined ? Object.freeze({}) : parseAgentEnvironment(source, 'local');
-}
-
 /** Renders the roster-derived generated projection in a stable, complete key order. */
 export function renderGeneratedAgentEnvironment(values: Readonly<Record<string, string>>): string {
   const normalized = normalizeGeneratedValues(values);

packages/mosaic/src/runtime/detector.ts

@@ -19,7 +19,7 @@ const RUNTIME_DEFS: Record<
     label: 'Claude Code',
     command: 'claude',
     versionFlag: '--version',
-    installHint: 'curl -fsSL https://claude.ai/install.sh | bash',
+    installHint: 'npm install -g @anthropic-ai/claude-code',
   },
   codex: {
     label: 'Codex',
@@ -31,13 +31,13 @@ const RUNTIME_DEFS: Record<
     label: 'OpenCode',
     command: 'opencode',
     versionFlag: 'version',
-    installHint: 'npm install -g opencode-ai',
+    installHint: 'See https://opencode.ai for install instructions',
   },
   pi: {
     label: 'Pi',
     command: 'pi',
     versionFlag: '--version',
-    installHint: 'npm install -g @earendil-works/pi-coding-agent',
+    installHint: 'curl -fsSL https://pi.dev/install.sh | sh',
   },
 };