fix(fleet): preflight pane runtimes before install (#1256 )

Merge pull request 'fix(fleet): tell the operator when the fleet transport is missing (#1240 )' (#1245 ) from fix/1240-fleet-transport-check into next
Reviewed by scooby via git comms (terminal ACK 32d986). Merge directed by Jason 2026-08-16. Conflicts from #1229 and #1252 resolved on the branch by a pi seat; pre-merge gate verified: tools/install.sh=5d28f773, framework/install.sh=1578c33b, test:framework-shell=48 links with both #1252 and #1245 suites present.
2026-08-16 17:41:11 -05:00 · 2026-08-16 18:12:33 +00:00 · 2026-08-16 13:11:31 -05:00 · 2026-08-16 18:06:53 +00:00 · 2026-08-16 18:06:50 +00:00 · 2026-08-16 18:06:35 +00:00
25 changed files with 2689 additions and 80 deletions
@@ -116,7 +116,7 @@ gateway-backed agent catalog.
 ### Normative requirements

 | 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-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.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -127,6 +127,7 @@ gateway-backed agent catalog.
 | `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-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

@@ -138,6 +139,7 @@ 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

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

+# Normalize the ambient umask so directory modes are a property of the installer
+# and not of whatever shell invoked it (#1236). Debian/Ubuntu ship umask 002, so
+# every `mkdir -p` below yielded 0775 — and the fleet env boundary rejects any
+# managed directory with `mode & 0o022`, which made `mosaic fleet init --write`
+# impossible on a stock install of those distros. Fedora/RHEL ship 022 and did
+# not trip it, so the product worked or did not depending on the operator's
+# login shell. 022 is what this script already assumes it produces: see the
+# umask note in make_durable_snapshot, which restores to the ambient value
+# precisely so "every later sync copy and new framework dir" gets 0644/0755.
+# Now that value is 022 rather than whatever was inherited.
+umask 022
+
 # Deliberately parsed from "$@" (a real, explicit, per-invocation argument) —
 # never an environment variable — so this opt-out can never sit silently
 # inherited in a shell profile. See #869 Point-1 C2.
@@ -696,6 +708,52 @@ sync_framework
 mkdir -p "$TARGET_DIR/memory"
 mkdir -p "$TARGET_DIR/credentials"

+# Three directories must be 0700, not merely not-group-writable (#1236).
+# The fleet code guards them with two different masks in two different
+# languages, and the strict one wins:
+#
+#   assertPrivateManagedDirectory (fleet-reconciler.js, `mode & 0o077`)
+#       -> MOSAIC_HOME and MOSAIC_HOME/fleet, checked before the roster lock is
+#          taken, so every mutating `mosaic fleet` command dies at 0755.
+#   assert_private_directory (tools/fleet/start-agent-session.sh, `mode & 077`)
+#       -> MOSAIC_HOME/fleet/agents, checked before a pane is ever spawned.
+#
+# Their laxer siblings (`mode & 0o022`) accept 0755, which is why normalizing
+# the umask above is necessary and not sufficient — a correct umask-022 install
+# still produces 0755 and still cannot run `mosaic fleet init --write`. Say the
+# strict modes outright rather than inferring them from a umask.
+#
+# Only these. The rest of the tree is content, stays 0755, and is only ever
+# reached by the 0o022 checks, which 0755 satisfies.
+chmod 700 "$TARGET_DIR" 2>/dev/null || \
+  warn "Could not set 0700 on $TARGET_DIR — 'mosaic fleet' mutations will fail as unsafe-permissions."
+if [[ -d "$TARGET_DIR/fleet" ]]; then
+  chmod 700 "$TARGET_DIR/fleet" 2>/dev/null || \
+    warn "Could not set 0700 on $TARGET_DIR/fleet — 'mosaic fleet' mutations will fail as unsafe-permissions."
+fi
+# fleet/agents does not exist on a first install — the CLI creates it 0700 on
+# demand. It is chmod'd here for the UPGRADE case: a tree built under umask 002
+# has it at 0775, and the repair sweep below cannot rescue it, because stripping
+# group/other write from 0755 leaves 0750 and `mode & 077` is still non-zero.
+if [[ -d "$TARGET_DIR/fleet/agents" ]]; then
+  chmod 700 "$TARGET_DIR/fleet/agents" 2>/dev/null || \
+    warn "Could not set 0700 on $TARGET_DIR/fleet/agents — agent sessions will fail to start as unsafe-permissions."
+fi
+# credentials/ holds secrets and was never meant to be group-readable either.
+# It is not on the fleet boundary, so a failure here breaks nothing — but it is
+# the one directory where a silently-failed chmod leaves secrets group-readable,
+# which is precisely the failure worth a line in the output.
+chmod 700 "$TARGET_DIR/credentials" 2>/dev/null || \
+  warn "Could not set 0700 on $TARGET_DIR/credentials — stored secrets may be readable by other users on this host."
+
+# Repair an existing tree. The umask above only governs directories this run
+# creates, so a host installed under umask 002 before this fix keeps its 0775
+# dirs through every upgrade and stays broken. Strips group/other WRITE only —
+# never read or execute — so it can repair the boundary violation without
+# changing who can traverse or read anything. Scoped to directories: file modes
+# are the manifest's business, not this fix's.
+find "$TARGET_DIR" -type d -perm /022 -exec chmod go-w {} + 2>/dev/null || true
+
 # Reconcile contract files from defaults/ into the framework root: framework-owned
 # files (CONSTITUTION/AGENTS/STANDARDS) are overwritten every upgrade (a divergent
 # copy is backed up once); user-seeded files (TOOLS) are written on first install only.
@@ -51,8 +51,12 @@ 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. `mosaic fleet install` validates the roster, installs the units and
-helpers, and writes private roster-derived projections before any service is started.
+edit a generated projection. Before it writes any holder identity, tool, projection, or unit file,
+`mosaic fleet install` validates the fleet CLI and every distinct roster runtime through the exact
+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.
@@ -4,6 +4,14 @@ Documentation=https://git.mosaicstack.dev/mosaicstack/stack
 Requires=mosaic-tmux-holder.service
 After=mosaic-tmux-holder.service
 PartOf=mosaic-tmux-holder.service
+# Do not attempt a seat before its generated env exists. `install` enables this
+# unit (WantedBy=default.target) but on a roster-v2 fleet the reconciler owns the
+# generated env, so between `install` and the first `apply`/`regen --write` there
+# is a boot window where ExecStart would run against an absent env file and the
+# launcher would fail the unit. A skipped unit is the honest state for "enabled
+# but not yet configured"; systemd re-evaluates the condition on every start, so
+# the seat comes up on the next start once the reconciler has written env.
+ConditionPathExists=%h/.config/mosaic/fleet/agents/%i.env.generated

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

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

-_build_runtime_bin_prefix() {
-  local candidates=()
-  if [ -n "$MOSAIC_RUNTIME_BIN" ]; then candidates+=("$MOSAIC_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"
+# #1241/#1256. The pane runs `mosaic yolo <runtime>` under PANE_PATH with a
+# cleared environment. Resolve both names and validate any shebang interpreter
+# here, before an effect, where the failure remains attributable. Name
+# resolution alone is insufficient: an `#!/usr/bin/env node` script resolves
+# even when the pane cannot execute it because Node is absent.
+_resolve_in_pane_path() {
+  mosaic_fleet_resolve_in_pane_path "$PANE_PATH" "$1"
 }

-MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
-PANE_PATH=${MOSAIC_RUNTIME_BIN_PREFIX:+${MOSAIC_RUNTIME_BIN_PREFIX}:}/usr/local/bin:/usr/bin:/bin
+# Exit 69 (EX_UNAVAILABLE): the seat cannot be provided. Distinguished from the
+# 64 (EX_USAGE) rejections above, which mean the projection itself was bad —
+# here the data is fine and the host is not ready. Callers tell the individual
+# cases apart by `code=`, the same way fail_env's many codes share exit 64.
+fail_launch() {
+  local code="$1"
+  shift
+  echo "ERROR: agent launch aborted: code=${code} agent=${AGENT_NAME} $*" >&2
+  exit 69
+}
+
+for required_binary in mosaic "$MOSAIC_AGENT_RUNTIME"; do
+  resolved_binary=$(_resolve_in_pane_path "$required_binary") ||
+    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() {
  local workdir="$1"
@@ -384,6 +397,19 @@ if [ -n "$PANE_PID" ]; then
  _start_heartbeat_sidecar "$AGENT_NAME" "$PANE_PID" \
    "$MOSAIC_HEARTBEAT_RUN_DIR" "$MOSAIC_HEARTBEAT_INTERVAL" || \
    echo "WARNING: heartbeat sidecar could not be started for $AGENT_NAME" >&2
+elif _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
+  # #1241. Session present, no pane PID after a second of retries. Whatever this
+  # is, it is not a seat an operator can use, so it is not a success either.
+  fail_launch pane-pid-unresolved \
+    "tmux reports the session but no pane PID after 5 attempts"
 else
-  echo "WARNING: could not resolve pane PID for $AGENT_NAME — heartbeat sidecar not started" >&2
+  # #1241. This branch used to print a WARNING about the heartbeat sidecar and
+  # exit 0. It is not a heartbeat problem: tmux destroys a session when its pane
+  # command exits, so an absent session one second after new-session means the
+  # runtime died on startup. Reporting it as success is what let `fleet start`
+  # return 0 over three dead panes — the launcher knew, and said the wrong thing
+  # at the wrong severity to the wrong layer.
+  fail_launch pane-did-not-survive \
+    "the pane exited immediately and tmux destroyed the session;" \
+    "run 'mosaic yolo ${MOSAIC_AGENT_RUNTIME}' in ${MOSAIC_AGENT_WORKDIR} to see why"
 fi
@@ -23,8 +23,26 @@ index=0
 if [ "${args[0]:-}" = -L ]; then index=2; fi
 case "${args[$index]:-}" in
  has-session)
+    # The holder always answers. MOSAIC_TEST_HELD_SESSIONS lets a case add
+    # other targets that should answer too — without it there is no way to
+    # model "tmux still reports the session" for a non-holder agent, and the
+    # launcher's pane-pid-unresolved branch is unreachable from this harness.
+    #
+    # A listed target answers only AFTER new-session, because the launcher asks
+    # this question twice about the same name: once before launching, where a
+    # yes means "already running, nothing to do, exit 0", and once after, where
+    # a yes means "the session survived". A shim that answered yes to both
+    # would short-circuit at the first and never reach the branch under test —
+    # it would look like coverage and measure the idempotency path instead.
    for argument in "${args[@]}"; do
      [ "$argument" = '=_holder:0.0' ] && exit 0
+      case " ${MOSAIC_TEST_HELD_SESSIONS:-} " in
+        *" $argument "*)
+          if tr '\0' '\n' < "${MOSAIC_TEST_TMUX_CALLS:?}" | grep -qxF new-session; then
+            exit 0
+          fi
+          ;;
+      esac
    done
    exit 1
    ;;
@@ -62,6 +80,30 @@ env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
 SHIM
 chmod +x "$FAKE_BIN/mosaic"

+# The runtime the rosters below name. The launcher resolves it against PANE_PATH
+# before spawning (#1241), so it has to exist somewhere the pane would find it —
+# not merely on the launcher's own PATH.
+printf '#!/usr/bin/env bash\nexit 0\n' > "$FAKE_BIN/pi"
+chmod +x "$FAKE_BIN/pi"
+
+# PANE_PATH is derived partly from `npm config get prefix`. Left to the real npm
+# it would splice whatever the host has installed into the path under test, and
+# the missing-binary cases below would pass or fail by accident of the machine.
+cat > "$FAKE_BIN/npm" <<'SHIM'
+#!/usr/bin/env bash
+printf '%s\n' "${MOSAIC_TEST_NPM_PREFIX:-/nonexistent}"
+SHIM
+chmod +x "$FAKE_BIN/npm"
+
+# PANE_PATH always ends in the system path. A host that installs these there can
+# not measure the missing-binary cases at all, and a green run would mean
+# nothing — so say so instead of passing.
+for host_binary in mosaic pi; do
+  if PATH=/usr/local/bin:/usr/bin:/bin command -v "$host_binary" >/dev/null 2>&1; then
+    fail "host provides '$host_binary' in the system path; missing-binary cases are not measurable here"
+  fi
+done
+
 write_generated() {
  local home="$1"
  local agent="$2"
@@ -81,6 +123,19 @@ MOSAIC_TMUX_SOCKET=mosaic-test
 EOF
  chmod 600 "$home/fleet/agents/$agent.env.generated"
  mkdir -p "$home/work"
+  install_pane_binaries "$home"
+}
+
+# `$PANE_HOME/.npm-global/bin` is one of the prefixes the launcher folds into
+# PANE_PATH, so this is the pane's own view of "installed", distinct from the
+# launcher's PATH. Tests that need a binary *absent* remove it from here.
+install_pane_binaries() {
+  local pane_home="$1"
+  mkdir -p "$pane_home/.npm-global/bin"
+  local binary
+  for binary in mosaic pi; do
+    ln -sf "$FAKE_BIN/$binary" "$pane_home/.npm-global/bin/$binary"
+  done
 }

 run_start() {
@@ -88,6 +143,7 @@ run_start() {
  local agent="$2"
  HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
    MOSAIC_TEST_PANE_PID="${MOSAIC_TEST_PANE_PID:-}" \
+    MOSAIC_TEST_HELD_SESSIONS="${MOSAIC_TEST_HELD_SESSIONS:-}" \
    MOSAIC_TEST_HOME="$home" \
    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
    MOSAIC_HOME="$home" "$START" "$agent"
@@ -98,7 +154,10 @@ run_start() {
 HOME_VALID="$ROOT/valid"
 AGENT_VALID="coder0"
 write_generated "$HOME_VALID" "$AGENT_VALID"
-run_start "$HOME_VALID" "$AGENT_VALID"
+# A live pane PID is part of what "valid launch" means. Until #1241 this case
+# ran with none, so the suite's one success path was itself a dead pane the
+# launcher reported as fine.
+MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_VALID" "$AGENT_VALID"
 valid_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$valid_args" | grep -qF new-session || fail "valid generated projection did not reach tmux"
 echo "$valid_args" | grep -qF 'mosaic' || fail "fixed mosaic launcher command missing"
@@ -245,6 +304,13 @@ PANE_BASH_ENV="$ROOT/pane-boundary.bash-env"
 printf 'MOSAIC_RUNTIME_BIN=%s\n' "$FAKE_BIN" > \
  "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
 chmod 600 "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
+# This case does not go through run_start, so its pane binaries come from
+# MOSAIC_RUNTIME_BIN=$FAKE_BIN in the env.local written above — not from the
+# symlinks install_pane_binaries planted under the generated home, which this
+# launcher never consults because HOME here is the trusted parent. That is a
+# legitimate resolution path, but it means dropping MOSAIC_RUNTIME_BIN from
+# this case on the belief that the symlinks cover it would break the #1241
+# binary check rather than exercise it.
 LD_PRELOAD='/not/loaded/by-clean-bootstrap.so' \
 BASH_ENV="$PANE_BASH_ENV" \
 MOSAIC_UNTRUSTED_SENTINEL='must-not-reach-pane' \
@@ -258,6 +324,7 @@ PATH="$PANE_STALE_PATH" \
    "MOSAIC_TEST_HOME=$PANE_TRUSTED_HOME" \
    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
    MOSAIC_TEST_EXECUTE_PANE=1 \
+    "MOSAIC_TEST_PANE_PID=$$" \
    "$START" coder-pane-boundary
 pane_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$pane_args" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
@@ -392,6 +459,96 @@ echo "$interaction_policy_args" | grep -qF 'new-session' && \
 echo "$output" | grep -qF 'operator interaction service requires runtime pi' || \
  fail "interaction pinned-policy check did not follow strict parsing"

+# #1241. The pane runs `mosaic yolo <runtime>` against PANE_PATH. A binary
+# missing from that path is a launch failure, and it has to be named before the
+# session is created — after it, the diagnostic dies with the pane.
+assert_missing_pane_binary_rejected() {
+  local binary="$1"
+  local home="$ROOT/missing-$binary"
+  local agent="coder-missing-$binary"
+  write_generated "$home" "$agent"
+  rm -f "$home/.npm-global/bin/$binary"
+
+  : > "$TMUX_CALLS"
+  local output
+  if output=$(MOSAIC_TEST_PANE_PID=$$ run_start "$home" "$agent" 2>&1); then
+    fail "launch succeeded with '$binary' absent from the pane PATH"
+  fi
+  echo "$output" | grep -qF 'code=missing-binary' || fail "missing '$binary' diagnostic missing"
+  echo "$output" | grep -qF "'$binary'" || fail "missing-binary diagnostic did not name $binary"
+  if tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session; then
+    fail "launcher created a session it knew would die ($binary absent)"
+  fi
+}
+
+assert_missing_pane_binary_rejected mosaic
+assert_missing_pane_binary_rejected pi
+
+# #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
+# then reported a fleet that was not running.
+: > "$TMUX_CALLS"
+HOME_DEAD_PANE="$ROOT/dead-pane"
+write_generated "$HOME_DEAD_PANE" "coder-dead-pane"
+if output=$(MOSAIC_TEST_PANE_PID='' run_start "$HOME_DEAD_PANE" coder-dead-pane 2>&1); then
+  fail "launcher reported success over a pane that did not survive"
+fi
+echo "$output" | grep -qF 'code=pane-did-not-survive' || fail "dead-pane diagnostic missing"
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "dead pane is still being reported as a heartbeat-sidecar problem"
+fi
+tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session || \
+  fail "dead-pane case did not reach the launch it is measuring"
+
+# #1241, the other way a pane fails. Above, tmux destroyed the session and
+# has-session said so. Here the session is still there and no PID comes back
+# after the retries — a different fault (the pane is alive but unusable, or
+# tmux is answering inconsistently) that an operator has to be told apart from
+# a runtime that died on startup.
+#
+# This case exists because the branch that handles it shipped with nothing able
+# to reach it: the shim answered has-session only for the holder, so every
+# non-holder agent landed in the session-is-gone branch no matter what. A
+# defensive branch nothing exercises is the same shape as the bug this whole
+# change is about, one layer down.
+: > "$TMUX_CALLS"
+HOME_NO_PID="$ROOT/pane-no-pid"
+write_generated "$HOME_NO_PID" "coder-no-pid"
+if output=$(MOSAIC_TEST_PANE_PID='' MOSAIC_TEST_HELD_SESSIONS='=coder-no-pid:0.0' \
+  run_start "$HOME_NO_PID" coder-no-pid 2>&1); then
+  fail "launcher reported success over a session with no resolvable pane PID"
+fi
+echo "$output" | grep -qF 'code=pane-pid-unresolved' || \
+  fail "session-present/no-PID was not reported as pane-pid-unresolved: $output"
+if echo "$output" | grep -qF 'code=pane-did-not-survive'; then
+  fail "a session tmux still reports was diagnosed as a destroyed session"
+fi
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "an unresolvable pane PID is still being reported as a heartbeat-sidecar problem"
+fi
+
 # Exact stop derives the socket exclusively from the validated generated
 # projection and ignores an ambient socket supplied by the caller.
 : > "$TMUX_CALLS"
@@ -25,7 +25,7 @@
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/fleet/test-start-agent-session.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/fleet/test-start-agent-session.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -1,9 +1,13 @@
 import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } 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 = `
@@ -65,12 +69,15 @@ 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',
@@ -83,6 +90,24 @@ 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 => {
@@ -152,13 +177,64 @@ 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> => {
@@ -8,10 +8,18 @@ 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'>;
 }
@@ -71,6 +79,10 @@ 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)
@@ -90,8 +102,31 @@ export async function executeReconcilerCommand(
      ...(deps.reconcileDeps ?? {}),
    },
  });
-  printJson(result);
-  process.exitCode = result.recovery === undefined && result.cleanup === undefined ? 0 : 1;
+  printJson(operation === 'doctor' ? { ...result, checks: runtimeInspection } : result);
+  const executableFailure =
+    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 {
@@ -0,0 +1,429 @@
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { FleetRuntimeProbeRunner } from '../fleet/fleet-runtime-preflight.js';
+import { registerFleetCommand, type CommandResult, type CommandRunner } from './fleet.js';
+
+/**
+ * #1237: the v1-only commands (`ps`, `install`, `install-systemd`, `add`,
+ * `remove`) rejected a roster-v2 fleet outright, so a greenfield v2 box could
+ * never get its units placed. These tests pin the three behaviours that fix
+ * gives it, and the two it deliberately does NOT give it.
+ *
+ * The load-bearing negative is that `install` on v2 writes no generated env:
+ * the reconciler owns that file through projectRosterV2AgentGeneratedEnv, and a
+ * second writer here — necessarily through the v1 mapping — is exactly the
+ * drift the #791 single-SSOT invariant exists to prevent.
+ */
+
+const rosterV2 = `
+version: 2
+generation: 4
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: /srv/mosaic
+  runtime: pi
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: coder0
+    alias: Coder 0
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: high
+    tool_policy: code
+    working_directory: /srv/mosaic
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+  - name: coder1
+    alias: Coder 1
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: medium
+    tool_policy: code
+    working_directory: /srv/other
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+`;
+
+let tempHome: string | undefined;
+const savedHome = process.env.HOME;
+const savedMosaicHome = process.env.MOSAIC_HOME;
+const savedPath = process.env.PATH;
+
+afterEach(async (): Promise<void> => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+  if (savedHome === undefined) delete process.env.HOME;
+  else process.env.HOME = savedHome;
+  if (savedMosaicHome === undefined) delete process.env.MOSAIC_HOME;
+  else process.env.MOSAIC_HOME = savedMosaicHome;
+  if (savedPath === undefined) delete process.env.PATH;
+  else process.env.PATH = savedPath;
+  if (tempHome) await rm(tempHome, { recursive: true, force: true });
+  tempHome = undefined;
+});
+
+/**
+ * A HOME with a roster-v2 fleet and nothing else — the greenfield shape, before
+ * anything has been installed, applied or started.
+ */
+async function v2Home(options: { withPaneRuntime?: boolean } = {}): Promise<string> {
+  tempHome = await mkdtemp(join(tmpdir(), 'mosaic-fleet-v2-dispatch-'));
+  process.env.HOME = tempHome;
+  delete process.env.MOSAIC_HOME;
+  const mosaicHome = join(tempHome, '.config', 'mosaic');
+  for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
+    await mkdir(join(mosaicHome, directory), { recursive: true, mode: 0o700 });
+  }
+  await writeFile(join(mosaicHome, 'fleet', 'roster.yaml'), rosterV2, { mode: 0o600 });
+  await writeFile(join(mosaicHome, 'fleet', 'roles', 'code.md'), '`class: code`\n\n# code\n', {
+    mode: 0o600,
+  });
+  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;
+}
+
+/**
+ * Stands in for a box where nothing is running: every systemctl and tmux probe
+ * fails the way it does before the holder has ever started. `ps` must survive
+ * this — it is the command an operator reaches for to find out *why* there is
+ * no seat, so it has to report the emptiness rather than fail on it.
+ */
+const greenfieldRunner: CommandRunner = async (command): Promise<CommandResult> => {
+  if (command === 'tmux') {
+    return { stdout: '', stderr: 'no server running on /tmp/tmux-1000/mosaic-fleet', exitCode: 1 };
+  }
+  return { stdout: '', stderr: '', exitCode: 1 };
+};
+
+function program(
+  runner: CommandRunner = greenfieldRunner,
+  runtimeProbeRunner?: FleetRuntimeProbeRunner,
+): Command {
+  const result = new Command();
+  result.exitOverride();
+  registerFleetCommand(result, {
+    runner,
+    frameworkRoot: resolve(process.cwd(), 'framework'),
+    ...(runtimeProbeRunner === undefined ? {} : { runtimeProbeRunner }),
+  });
+  return result;
+}
+
+function capture(): string[] {
+  const lines: string[] = [];
+  vi.spyOn(console, 'log').mockImplementation((value: string): void => {
+    lines.push(value);
+  });
+  return lines;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('mosaic fleet ps — roster v2', (): void => {
+  it('lists every v2 agent on a greenfield box with nothing running, and does not throw', async (): Promise<void> => {
+    await v2Home();
+    const lines = capture();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'ps', '--json']),
+    ).resolves.toBeDefined();
+
+    const rows = JSON.parse(lines.join('\n')) as {
+      name: string;
+      runtime: string;
+      alias?: string;
+      paneAlive: boolean;
+      source: string;
+    }[];
+    expect(rows.map((row) => row.name).sort()).toEqual(['coder0', 'coder1']);
+    // The v2 roster's per-agent fields must survive the read model, not be
+    // flattened into defaults.
+    expect(rows.every((row) => row.runtime === 'pi')).toBe(true);
+    expect(rows.find((row) => row.name === 'coder0')?.alias).toBe('Coder 0');
+    // Nothing is running, and that is a report, not an error.
+    expect(rows.every((row) => row.paneAlive === false)).toBe(true);
+    expect(rows.every((row) => row.source === 'roster')).toBe(true);
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+});
+
+describe('mosaic fleet install — roster v2', (): void => {
+  it('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();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']),
+    ).resolves.toBeDefined();
+
+    // Units live in the systemd user dir, not under the Mosaic home.
+    const systemdUserDir = join(tempHome!, '.config', 'systemd', 'user');
+    for (const unit of [
+      'mosaic-tmux-holder.service',
+      '[email protected]',
+      '[email protected]',
+    ]) {
+      expect(await exists(join(systemdUserDir, unit))).toBe(true);
+    }
+    for (const tool of ['start-agent-session.sh', 'pane-runtime-path.sh']) {
+      const toolPath = join(mosaicHome, 'tools', 'fleet', tool);
+      expect(await exists(toolPath)).toBe(true);
+      expect((await stat(toolPath)).mode & 0o777).toBe(0o755);
+    }
+  });
+
+  it('writes NO generated env — that file belongs to the reconciler (#791)', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    capture();
+
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    const agentDir = join(mosaicHome, 'fleet', 'agents');
+    expect(await readdir(agentDir)).toEqual([]);
+  });
+
+  it('tells the operator which command does own the env', async (): Promise<void> => {
+    await v2Home();
+    const lines = capture();
+
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    expect(lines.join('\n')).toContain('mosaic fleet apply');
+  });
+});
+
+describe('[email protected]', (): void => {
+  const unitPath = resolve(process.cwd(), 'framework', 'systemd', 'user', '[email protected]');
+
+  /** The single `ConditionPathExists=` value declared by the unit template. */
+  async function conditionPath(): Promise<string> {
+    const unit = await readFile(unitPath, 'utf8');
+    const matches = unit.match(/^ConditionPathExists=(.+)$/gm) ?? [];
+    expect(matches).toHaveLength(1);
+    return matches[0]!.slice('ConditionPathExists='.length).trim();
+  }
+
+  it('will not attempt a seat before the reconciler has written its env', async (): Promise<void> => {
+    // The pairing that makes "install writes no env" safe: install enables the
+    // unit (WantedBy=default.target) but does not start it, so without this
+    // condition a reboot between `install` and the first `apply` would run
+    // ExecStart against an absent env file and fail every seat unit.
+    expect(await conditionPath()).toBe('%h/.config/mosaic/fleet/agents/%i.env.generated');
+  });
+
+  /**
+   * The two halves of the guard's *effect*, which no assertion on the literal
+   * string can cover on its own.
+   *
+   * Measured end to end on a real box (canary, 2026-08-16) rather than inferred:
+   * with the condition, `systemctl --user start mosaic-agent@<name>` on an agent
+   * with no generated env returns rc=0, `Result=success`, `ConditionResult=no`,
+   * and journals "skipped, unmet condition check". With the condition removed by
+   * drop-in and nothing else changed, the same start returns rc=1,
+   * `Result=exit-code`, `ExecMainStatus=64`, and the unit enters `failed`.
+   *
+   * systemd is not available in this suite, so these two tests pin the parts
+   * that can drift in code: the condition naming a *different* file than the one
+   * the fleet actually writes, and the launcher quietly becoming tolerant of an
+   * absent env — either of which turns the condition into decoration while the
+   * literal-string assertion above still passes.
+   */
+  it('guards exactly the file the fleet writes, so the two cannot drift apart', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    const rendered = (await conditionPath()).replace('%h', tempHome!).replace('%i', 'coder0');
+
+    // The path an installed fleet actually places for this agent.
+    expect(rendered).toBe(join(mosaicHome, 'fleet', 'agents', 'coder0.env.generated'));
+  });
+
+  it('guards a real failure — the launcher rejects an absent generated env', async (): Promise<void> => {
+    await v2Home();
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    // Exactly what ExecStart runs, against the state the condition exists to
+    // catch: unit enabled, reconciler has not written env yet.
+    const launched = await new Promise<{ code: number | null; stderr: string }>((settle) => {
+      const child = execFile(
+        '/bin/bash',
+        [
+          '--noprofile',
+          '--norc',
+          join(tempHome!, '.config', 'mosaic', 'tools', 'fleet', 'start-agent-session.sh'),
+          'coder0',
+        ],
+        { env: { HOME: tempHome!, MOSAIC_AGENT_NAME: 'coder0', PATH: '/usr/bin:/bin' } },
+        (_error, _stdout, stderr) => {
+          settle({ code: child.exitCode, stderr });
+        },
+      );
+    });
+
+    expect(launched.code).not.toBe(0);
+    expect(launched.stderr).toContain('missing-file');
+  });
+});
+
+describe('mosaic fleet add / remove — roster v2', (): void => {
+  it('add refuses, and names the two-step v2 sequence instead of inventing defaults', async (): Promise<void> => {
+    await v2Home();
+
+    await expect(
+      program().parseAsync([
+        'node',
+        'mosaic',
+        'fleet',
+        'add',
+        'coder2',
+        '--runtime',
+        'pi',
+        '--class',
+        'code',
+      ]),
+    ).rejects.toThrow(/mosaic fleet create[\s\S]*mosaic fleet apply/);
+  });
+
+  it('remove refuses, and names delete plus apply', async (): Promise<void> => {
+    await v2Home();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
+    ).rejects.toThrow(/mosaic fleet delete coder1[\s\S]*mosaic fleet apply/);
+  });
+
+  // Note: this one passes on the unmodified tree too — there `remove` throws in
+  // the v1 parser, before it can touch anything. It is a regression guard on the
+  // ordering of the new guard clause, not evidence that the fix works.
+  it('refuses BEFORE mutating the roster', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
+    const before = await readFile(rosterPath, 'utf8');
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
+    ).rejects.toThrow();
+
+    expect(await readFile(rosterPath, 'utf8')).toBe(before);
+  });
+});
@@ -1277,6 +1277,10 @@ 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();
@@ -1315,6 +1319,10 @@ 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');
@@ -34,6 +34,7 @@ export {
  resolveInstalledFleetRosterPath,
 } from '../fleet/fleet-roster-v1.js';
 export type { FleetAgent, FleetRoster } from '../fleet/fleet-roster-v1.js';
+import { parseRosterV2 } from '../fleet/roster-v2.js';
 import {
  registerFleetAgentCrudCommands,
  type FleetAgentCrudCommandDeps,
@@ -59,6 +60,12 @@ 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';
@@ -88,6 +95,8 @@ 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;
  /**
@@ -820,7 +829,7 @@ export function buildEnableLingerCommand(user: string): string[] {
 */
 export async function enableFleetUnits(
  runner: CommandRunner,
-  roster: FleetRoster,
+  roster: { readonly agents: readonly { readonly name: string }[] },
  opts: { enable?: boolean },
 ): Promise<void> {
  if (opts.enable === false) {
@@ -1428,6 +1437,10 @@ 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();
@@ -1526,8 +1539,9 @@ 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);
-      const roster = await loadRosterForCommand(cmd);
+      await installFleet(cmd, frameworkRoot, runtimeProbeRunner);
+      // Unit enablement needs agent names only, so it reads either version.
+      const roster = await loadRosterReadModel(cmd);
      await enableFleetUnits(runner, roster, opts);
    });

@@ -1536,8 +1550,9 @@ 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);
-      const roster = await loadRosterForCommand(cmd);
+      await installFleet(cmd, frameworkRoot, runtimeProbeRunner);
+      // Unit enablement needs agent names only, so it reads either version.
+      const roster = await loadRosterReadModel(cmd);
      await enableFleetUnits(runner, roster, opts);
    });

@@ -1688,7 +1703,9 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
    .action(async (opts: { json?: boolean }) => {
      const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
      const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
-      const roster = await loadRosterForCommand(cmd);
+      // ps only reads, so it takes the version-agnostic read model rather than
+      // the v1 parser, which rejects a v2 roster outright.
+      const roster = await loadRosterReadModel(cmd);
      const { tenant_id, host } = getDefaultTenantAndHost();
      const nowMs = Date.now();

@@ -1908,6 +1925,16 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
          start: boolean;
        },
      ) => {
+        if (await usesRosterV2ControlPlane(cmd)) {
+          // command.error, not a bare throw: this is operator guidance, and a
+          // bare throw reaches the top level uncaught and prints it under a Node
+          // stack trace. Measured on canary — the message is the whole point of
+          // the refusal, so it has to arrive readable.
+          cmd.error(rosterV2MutationGuidance('add', 'create', name), {
+            code: 'fleet.roster-v2',
+            exitCode: 1,
+          });
+        }
        if (!VALID_FLEET_RUNTIMES.includes(opts.runtime)) {
          throw new Error(
            `Invalid runtime "${opts.runtime}". Valid runtimes: ${VALID_FLEET_RUNTIMES.join(', ')}.`,
@@ -1973,6 +2000,12 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
    .description('Remove an agent from the fleet roster')
    .option('--keep-files', 'Skip deleting env and heartbeat files')
    .action(async (name: string, opts: { keepFiles?: boolean }) => {
+      if (await usesRosterV2ControlPlane(cmd)) {
+        cmd.error(rosterV2MutationGuidance('remove', 'delete', name), {
+          code: 'fleet.roster-v2',
+          exitCode: 1,
+        });
+      }
      const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
      const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
      const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
@@ -2063,6 +2096,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
  });
  registerFleetReconcilerCommands(cmd, {
    runner,
+    runtimeProbeRunner,
+    frameworkRoot,
    mosaicHome: deps.mosaicHome,
    reconcileDeps: deps.reconcileDeps,
  });
@@ -2328,16 +2363,68 @@ export function registerFleetAgentCommands(
    });
 }

-async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
+async function installFleet(
+  cmd: Command,
+  frameworkRoot: string,
+  runtimeProbeRunner: FleetRuntimeProbeRunner,
+): Promise<void> {
  const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
  assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
-  const roster = await loadRosterForCommand(cmd);
+  // Read and preflight before the first mkdir/copy/chmod/write. A successful
+  // install must mean every roster runtime is executable in the eventual pane,
+  // 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',
@@ -2351,6 +2438,7 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
  const agentSendPath = join(activePaths.tmuxToolsDir, 'agent-send.sh');
  const executableToolPaths = [
    startAgentSessionPath,
+    paneRuntimePath,
    startInteractionServicePath,
    startTmuxHolderPath,
    printInteractionPolicyPath,
@@ -2361,6 +2449,7 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
    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,
@@ -2391,16 +2480,32 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
    join(activePaths.systemdUserDir, '[email protected]'),
  );

-  for (const agent of roster.agents) {
+  // On roster v2 the reconciler owns the generated env: `apply` writes it and
+  // `regen` rebuilds it, both from projectRosterV2AgentGeneratedEnv. Writing it
+  // here too — necessarily through the v1 mapping — would be the third writer of
+  // one file and would break the #791 single-SSOT invariant. So v2 gets the tool
+  // files and the units, and nothing else.
+  if (roster.version === 2) {
+    console.log(
+      `Installed fleet tools and systemd units for ${roster.agents.length} agent(s). ` +
+        `Generated env is owned by the reconciler on roster v2 — run: mosaic fleet apply --expected-generation <n>`,
+    );
+    return;
+  }
+
+  if (v1Roster === undefined) {
+    throw new Error('Roster version changed while installing fleet files.');
+  }
+  for (const agent of v1Roster.agents) {
    await writeAgentEnvironmentProjection({
      mosaicHome: activePaths.mosaicHome,
      agentEnvDir: activePaths.agentEnvDir,
      agentName: agent.name,
-      generated: generateAgentEnvValues(roster, agent),
+      generated: generateAgentEnvValues(v1Roster, agent),
    });
  }

-  console.log(`Installed fleet files for ${roster.agents.length} agent(s).`);
+  console.log(`Installed fleet files for ${v1Roster.agents.length} agent(s).`);
 }

 async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
@@ -2427,6 +2532,77 @@ async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
  );
 }

+/**
+ * `add`/`remove` and `create`/`delete` are not two spellings of one operation.
+ * The v1 pair edits the roster *and* drives systemd; the v2 pair is documented
+ * as changing desired state "without runtime actions", leaving convergence to
+ * `apply`. `add` also collects four fields where a v2 agent requires eleven, so
+ * routing it to `create` would mean inventing provider, alias, reasoning and
+ * tool-policy defaults on the operator's behalf. Refusing with the real command
+ * is honest; silently guessing an agent's provider is not.
+ */
+function rosterV2MutationGuidance(
+  v1Command: 'add' | 'remove',
+  v2Command: 'create' | 'delete',
+  name: string,
+): string {
+  const target = v2Command === 'delete' ? ` ${name}` : '';
+  return (
+    `mosaic fleet ${v1Command} does not operate on a roster-v2 fleet. ` +
+    `Roster v2 separates desired state from convergence:\n` +
+    `  1. mosaic fleet ${v2Command}${target} --expected-generation <current> ` +
+    `${v2Command === 'create' ? "--agent '<json>' " : ''}` +
+    `(edits the roster only)\n` +
+    `  2. mosaic fleet apply --expected-generation <new> (converges systemd and tmux)\n` +
+    `Read the current generation with: mosaic fleet status`
+  );
+}
+
+/**
+ * The read-only fields shared by roster v1 and v2, for the commands that only
+ * ever *read* the roster (`ps`, and unit enablement inside `install`).
+ *
+ * This is deliberately NOT a v2→v1 downshift. A downshifted `FleetRoster` would
+ * be accepted by `generateAgentEnvValues`, and that would make a third writer of
+ * `fleet/agents/<name>.env.generated` — through the v1 mapping — breaking the
+ * #791 single-SSOT invariant that {@link projectRosterV2AgentGeneratedEnv} is
+ * documented to hold. Keeping the read model this small makes that misuse
+ * impossible: there is nothing here to write a roster or an env file back from.
+ */
+interface FleetRosterReadModel {
+  readonly version: 1 | 2;
+  readonly tmux: { readonly socketName: string; readonly holderSession: string };
+  readonly agents: readonly {
+    readonly name: string;
+    readonly alias?: string;
+    readonly runtime: string;
+  }[];
+}
+
+/** Reads either roster version into the shared read-only view. */
+async function loadRosterReadModel(cmd: Command): Promise<FleetRosterReadModel> {
+  const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
+  const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
+  if (!(await usesRosterV2ControlPlane(cmd))) {
+    const v1 = await loadRosterAtPath(cmd, path);
+    return {
+      version: 1,
+      tmux: { socketName: v1.tmux.socketName, holderSession: v1.tmux.holderSession },
+      agents: v1.agents,
+    };
+  }
+  try {
+    const v2 = parseRosterV2(await readFleetRosterText(path), 'yaml');
+    return {
+      version: 2,
+      tmux: { socketName: v2.tmux.socketName, holderSession: v2.tmux.holderSession },
+      agents: v2.agents,
+    };
+  } catch (error) {
+    reportFleetRosterConfigurationError(cmd, error);
+  }
+}
+
 async function loadRosterFromAgentCommand(
  command: Command,
  mosaicHomeOverride?: string,
@@ -0,0 +1,328 @@
+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');
+  });
+});
@@ -0,0 +1,362 @@
+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);
+}
@@ -25,6 +25,12 @@ 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;
@@ -145,6 +151,23 @@ 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);
@@ -1,4 +1,3 @@
-import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform } from 'node:os';

@@ -22,15 +21,18 @@ export function getShellProfilePath(): string | null {

  const shell = detectShell();
  switch (shell) {
+    // Both of these deliberately avoid the interactive-only rc files.
+    // Debian's default .bashrc returns early for non-interactive shells, so a
+    // PATH line appended to it never runs for `bash -lc`, systemd units, or
+    // agent seats — an install could report success and still leave `mosaic`
+    // unreachable. .profile is read by login shells and sources .bashrc for
+    // interactive ones, so one line covers both; .zshenv is zsh's equivalent.
    case 'zsh': {
      const zdotdir = process.env['ZDOTDIR'] ?? home;
-      return join(zdotdir, '.zshrc');
+      return join(zdotdir, '.zshenv');
    }
-    case 'bash': {
-      const bashrc = join(home, '.bashrc');
-      if (existsSync(bashrc)) return bashrc;
+    case 'bash':
      return join(home, '.profile');
-    }
    case 'fish':
      return join(home, '.config', 'fish', 'config.fish');
    default:
@@ -19,7 +19,7 @@ const RUNTIME_DEFS: Record<
    label: 'Claude Code',
    command: 'claude',
    versionFlag: '--version',
-    installHint: 'npm install -g @anthropic-ai/claude-code',
+    installHint: 'curl -fsSL https://claude.ai/install.sh | bash',
  },
  codex: {
    label: 'Codex',
@@ -31,13 +31,13 @@ const RUNTIME_DEFS: Record<
    label: 'OpenCode',
    command: 'opencode',
    versionFlag: 'version',
-    installHint: 'See https://opencode.ai for install instructions',
+    installHint: 'npm install -g opencode-ai',
  },
  pi: {
    label: 'Pi',
    command: 'pi',
    versionFlag: '--version',
-    installHint: 'curl -fsSL https://pi.dev/install.sh | sh',
+    installHint: 'npm install -g @earendil-works/pi-coding-agent',
  },
 };

@@ -309,6 +309,124 @@ require_cmd() {
  fi
 }

+# True if any shell rc file already puts $1 on PATH.
+#
+# Each file is tested for existence first and grepped one at a time, rather than
+# handed to a single `grep -qs ... "${rc_files[@]}"`. Handing grep a missing file
+# makes the exit status implementation-defined: GNU grep 3.11 returns 0 when -q
+# matched an earlier file, ugrep 7.5 returns 2 for the missing one regardless.
+# On the 2 path the caller reads "not present yet" and appends a duplicate PATH
+# line on every single install.
+path_entry_exists() {
+  local dir="$1" rc_file
+  for rc_file in "$HOME/.profile" "$HOME/.zshenv" "$HOME/.zshrc" "$HOME/.bashrc"; do
+    if [[ -f "$rc_file" ]] && grep -qF "$dir" "$rc_file"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Append `export PATH="$1:$PATH"` to the shell profile so $1 survives this
+# process. An `export` here reaches only the installer; every directory the
+# install leaves behind has to be written down somewhere a later shell reads.
+#
+# Deliberately NOT ~/.bashrc: Debian's default .bashrc returns early for
+# non-interactive shells, so a PATH line appended to the bottom of it is
+# unreachable to `bash -lc`, to systemd units, and to every agent seat — the
+# exact consumers that need these binaries. ~/.profile is read by login shells
+# and Debian's .profile sources .bashrc for interactive ones, so a single line
+# there reaches both. For zsh the always-sourced file is .zshenv, not .zshrc.
+#
+# $1 = directory to add, $2 = label for the comment line.
+# Returns 1 (having warned) if the profile could not be written.
+persist_on_path() {
+  local dir="$1" label="$2" profile
+
+  if path_entry_exists "$dir"; then
+    return 0
+  fi
+
+  if [[ -n "${ZSH_VERSION:-}" ]] || [[ "$(basename "${SHELL:-}")" == "zsh" ]]; then
+    profile="$HOME/.zshenv"
+  else
+    profile="$HOME/.profile"
+  fi
+
+  # Probe writability in a subshell. A redirection failure on a special built-in
+  # aborts the shell it runs in, so it has to be a child; and the redirection on
+  # the subshell is what silences the "Permission denied" the shell would
+  # otherwise print ahead of our own message.
+  if ! ( : >>"$profile" ) 2>/dev/null; then
+    warn "$dir is not on your PATH and $profile could not be written"
+    dim "  Add to your shell rc:  export PATH=\"$dir:\$PATH\""
+    return 1
+  fi
+
+  {
+    echo ""
+    echo "# $label"
+    echo "export PATH=\"$dir:\$PATH\""
+  } >>"$profile"
+  ok "Added $dir to PATH in $profile"
+  return 0
+}
+
+# Persist $PREFIX/bin on PATH instead of only warning about it.
+#
+# The warning it replaces was the last step of an otherwise successful install,
+# so the installer reported success and left `mosaic: command not found` — an
+# unattended install had no operator to read the advice and act on it.
+ensure_prefix_on_path() {
+  if [[ ":$PATH:" == *":$PREFIX/bin:"* ]]; then
+    return
+  fi
+
+  if path_entry_exists "$PREFIX/bin"; then
+    warn "$PREFIX/bin is in your shell profile but not in this shell"
+  elif ! persist_on_path "$PREFIX/bin" "Mosaic CLI"; then
+    return
+  fi
+  dim "  Run:  export PATH=\"$PREFIX/bin:\$PATH\"   (or start a new login shell)"
+}
+
+# Fleet transport binary (#1240).
+#
+# `mosaic fleet --help` reads "Manage the local Mosaic tmux fleet" and every
+# roster the CLI scaffolds sets `transport: tmux`, but nothing in this script
+# provides tmux and, until now, nothing in it mentioned tmux at all. A
+# greenfield host came out of this installer able to install a fleet, start a
+# fleet, and run no seat — the operator's first signal was `mosaic fleet ps`.
+#
+# Not a `require_cmd`: tmux is required by the fleet, not by mosaic. Plenty of
+# hosts install this to run `mosaic claude` and will never scaffold a roster,
+# and failing their install over a binary they do not need would be wrong. It
+# is a warning that names precisely what it blocks.
+#
+# `tools/_scripts/mosaic-doctor` carries a deliberately parallel check, so the
+# same host state gets the same answer from an audit as from an install. They
+# are separate implementations because this one has to work before the
+# framework's scripts are guaranteed to be on disk; keep their wording in step.
+check_fleet_transport() {
+  local transport=tmux
+  local roster="$MOSAIC_HOME/fleet/roster.yaml"
+  local declared=""
+
+  if [[ -f "$roster" ]]; then
+    declared="$(sed -n 's/^[[:space:]]*transport:[[:space:]]*//p' "$roster" | head -1 |
+      tr -d '"'\''' | tr -d '\r' | awk '{print $1}')"
+    [[ -n "$declared" ]] && transport="$declared"
+  fi
+
+  command -v "$transport" &>/dev/null && return 0
+
+  warn "Fleet transport '$transport' is not installed."
+  echo "  The Mosaic fleet runs its agent seats inside $transport. Without it,"
+  echo "  ${C}mosaic fleet start${RESET} reports success and no seat comes up."
+  echo "  Install it before using the fleet, e.g. ${C}sudo apt-get install -y $transport${RESET}"
+  echo "  (this does not affect ${C}mosaic claude${RESET} or the other single-runtime commands)."
+}
+
 installed_cli_version() {
  local json
  json="$(npm ls -g --depth=0 --json --prefix="$PREFIX" 2>/dev/null)" || true
@@ -516,8 +634,175 @@ install_next_cli_from_registry() {
  ok "Installed @next packages: CLI ${installed_cli}, gateway ${installed_gateway}"
 }

+# ─── node bootstrap ───────────────────────────────────────────────────────────
+#
+# Nothing on a greenfield host installs Node.js, yet this installer and the CLI
+# it installs both hard-require it. Measured on a clean Debian 13 image: the
+# installer stopped at `require_cmd node` with "Required command not found" and
+# nothing was installed, with no hint of how to proceed.
+#
+# Inlined rather than factored into a sibling file on purpose: this script is
+# fetched standalone by curl and has nothing to source.
+#
+# No-op when a suitable node is already on PATH, so it never fights an
+# operator's nvm/fnm/distro node.
+
+NODE_ROOT="${MOSAIC_NODE_ROOT:-$HOME/.mosaic/node}"
+NODE_BOOTSTRAP_VERSION="${MOSAIC_NODE_VERSION:-v22.23.2}"
+NODE_MIN_MAJOR="${MOSAIC_NODE_MIN_MAJOR:-20}"
+NODE_DIST_BASE="${MOSAIC_NODE_DIST_BASE:-https://nodejs.org/dist}"
+
+# Major version of the node at $1, or empty if it will not run.
+node_major_of() {
+  local candidate="$1" version
+  version="$("$candidate" -e 'process.stdout.write(process.versions.node)' 2>/dev/null)" || return 0
+  printf '%s' "${version%%.*}"
+}
+
+node_is_suitable() {
+  local major
+  major="$(node_major_of "$1")"
+  [[ -n "$major" ]] && [[ "$major" -ge "$NODE_MIN_MAJOR" ]]
+}
+
+install_node() {
+  local node_os node_arch tarball release_url work_dir extracted target node_bin
+
+  case "$(uname -s)" in
+    Linux)  node_os="linux" ;;
+    Darwin) node_os="darwin" ;;
+    *) fail "Unsupported OS '$(uname -s)'. Install Node.js >= $NODE_MIN_MAJOR manually."; return 1 ;;
+  esac
+
+  # Linux here means glibc. Node's official linux-x64 build is dynamically
+  # linked against glibc, so on musl (Alpine) the binary will not exec — but it
+  # fails visibly: node_is_suitable rejects it and ensure_node exits with
+  # "install Node.js manually". No silent breakage, just a wasted download.
+  # A musl host needs the unofficial build, which is out of scope here.
+  case "$(uname -m)" in
+    x86_64|amd64)  node_arch="x64" ;;
+    aarch64|arm64) node_arch="arm64" ;;
+    armv7l)        node_arch="armv7l" ;;
+    *) fail "Unsupported architecture '$(uname -m)'. Install Node.js >= $NODE_MIN_MAJOR manually."; return 1 ;;
+  esac
+
+  # .tar.gz rather than the smaller .tar.xz: gzip is universally present, xz is
+  # not, and a minimal image is exactly the case this exists to handle.
+  tarball="node-${NODE_BOOTSTRAP_VERSION}-${node_os}-${node_arch}.tar.gz"
+  release_url="${NODE_DIST_BASE}/${NODE_BOOTSTRAP_VERSION}"
+
+  work_dir="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-node-XXXXXX")"
+
+  info "Installing Node.js $NODE_BOOTSTRAP_VERSION ($node_os-$node_arch) to $NODE_ROOT…"
+
+  if ! curl -fsSL "${release_url}/${tarball}" -o "$work_dir/$tarball"; then
+    fail "Download failed: ${release_url}/${tarball}"
+    rm -rf "$work_dir"; return 1
+  fi
+
+  # Trust assumption, stated so nobody has to infer it: this verifies INTEGRITY
+  # (the tarball matches the manifest), not AUTHENTICITY (the manifest is
+  # genuinely Node's). The only thing establishing that is TLS to
+  # $NODE_DIST_BASE. Node publishes SHASUMS256.txt.sig signed by its release
+  # keys and we do not check it, which is on par with nvm but means pointing
+  # MOSAIC_NODE_DIST_BASE at an untrusted mirror has no signature backstop.
+  # Tracked as a hardening follow-up (raised by scooby in the #1229 review).
+  if ! curl -fsSL "${release_url}/SHASUMS256.txt" -o "$work_dir/SHASUMS256.txt"; then
+    fail "Could not fetch SHASUMS256.txt; refusing to install an unverified runtime."
+    rm -rf "$work_dir"; return 1
+  fi
+
+  # Keep only our artifact's line, so a missing entry is an error not a pass.
+  if ! grep " ${tarball}\$" "$work_dir/SHASUMS256.txt" >"$work_dir/expected.sha256"; then
+    fail "$tarball has no entry in SHASUMS256.txt; refusing to install."
+    rm -rf "$work_dir"; return 1
+  fi
+
+  if ! (cd "$work_dir" && verify_sha256 expected.sha256); then
+    fail "Checksum mismatch for $tarball; refusing to install."
+    rm -rf "$work_dir"; return 1
+  fi
+  ok "Checksum verified"
+
+  tar xzf "$work_dir/$tarball" -C "$work_dir"
+  extracted="$work_dir/node-${NODE_BOOTSTRAP_VERSION}-${node_os}-${node_arch}"
+  if [[ ! -x "$extracted/bin/node" ]]; then
+    fail "Extracted archive has no bin/node"
+    rm -rf "$work_dir"; return 1
+  fi
+
+  mkdir -p "$NODE_ROOT"
+  target="$NODE_ROOT/$NODE_BOOTSTRAP_VERSION"
+  rm -rf "$target.incoming"
+  mv "$extracted" "$target.incoming"
+  rm -rf "$target"
+  mv "$target.incoming" "$target"
+  ln -sfn "$NODE_BOOTSTRAP_VERSION" "$NODE_ROOT/current"
+  rm -rf "$work_dir"
+
+  node_bin="$NODE_ROOT/current/bin"
+  if ! node_is_suitable "$node_bin/node"; then
+    fail "Installed node at $node_bin/node did not run"
+    return 1
+  fi
+
+  export PATH="$node_bin:$PATH"
+  ok "Node.js $(node -v) installed with npm $(npm -v 2>/dev/null || echo '?')"
+  return 0
+}
+
+# Make the Mosaic-managed Node reachable from the next shell as well as this
+# one. Measured on a greenfield canary run: without this the install finished
+# rc=0, wrote $PREFIX/bin to ~/.profile, and the next login shell found `mosaic`
+# and then died on `env: 'node': No such file or directory` — the CLI is a Node
+# script, so a CLI on PATH without its runtime is a successful install that
+# produces a broken command.
+persist_node_on_path() {
+  persist_on_path "$NODE_ROOT/current/bin" "Mosaic-managed Node.js" || true
+}
+
+ensure_node() {
+  if command -v node &>/dev/null && node_is_suitable node; then
+    return 0
+  fi
+
+  # A previous run may have installed one that is not on this shell's PATH.
+  if node_is_suitable "$NODE_ROOT/current/bin/node"; then
+    export PATH="$NODE_ROOT/current/bin:$PATH"
+    persist_node_on_path
+    return 0
+  fi
+
+  if [[ "${MOSAIC_SKIP_NODE_BOOTSTRAP:-0}" == "1" ]]; then
+    fail "No suitable Node.js and MOSAIC_SKIP_NODE_BOOTSTRAP=1; refusing to download."
+    echo "  Install Node.js >= $NODE_MIN_MAJOR yourself, then re-run this script."
+    exit 1
+  fi
+
+  require_cmd curl
+  require_cmd tar
+
+  # sha256sum on Linux, shasum on macOS. Verification is not optional: without a
+  # checksum this would install an unauthenticated runtime.
+  if command -v sha256sum &>/dev/null; then
+    verify_sha256() { sha256sum -c --status "$1"; }
+  elif command -v shasum &>/dev/null; then
+    verify_sha256() { shasum -a 256 -c --status "$1"; }
+  else
+    fail "sha256sum or shasum required to verify the Node.js download"
+    exit 1
+  fi
+
+  if ! install_node; then
+    fail "Could not bootstrap Node.js. Install Node.js >= $NODE_MIN_MAJOR and re-run."
+    exit 1
+  fi
+  persist_node_on_path
+}
+
 # ─── preflight ────────────────────────────────────────────────────────────────

+ensure_node
 require_cmd node
 require_cmd npm

@@ -682,11 +967,7 @@ if [[ "$FLAG_CLI" == "true" ]]; then
    ensure_monorepo
    install_cli_from_source

-    # PATH check for npm prefix
-    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
-      warn "$PREFIX/bin is not on your PATH"
-      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
-    fi
+    ensure_prefix_on_path
  elif is_next_registry_lane; then
    info "Next mode — trying fast npm @next install from ${REGISTRY}…"
    if install_next_cli_from_registry; then
@@ -699,11 +980,7 @@ if [[ "$FLAG_CLI" == "true" ]]; then
      export MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1
    fi

-    # PATH check for npm prefix
-    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
-      warn "$PREFIX/bin is not on your PATH"
-      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
-    fi
+    ensure_prefix_on_path
  else
    if [[ -z "$LATEST" ]]; then
      warn "Could not reach registry at $REGISTRY — skipping npm CLI."
@@ -721,11 +998,7 @@ if [[ "$FLAG_CLI" == "true" ]]; then
      ok "CLI is at or ahead of registry ($CURRENT ≥ $LATEST)."
    fi

-    # PATH check for npm prefix
-    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
-      warn "$PREFIX/bin is not on your PATH"
-      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
-    fi
+    ensure_prefix_on_path
  fi
 fi

@@ -870,6 +1143,11 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
  ok "Done."
 fi

+# Fleet readiness (#1240). Runs in both normal and --check mode: "what is the
+# state of this host" is exactly the question --check is asked, and a host that
+# cannot run a seat should not have to discover it from `fleet ps`.
+check_fleet_transport
+
 } # end main

 main "$@"