feat(doctor): brain-home fleet-state check (#1298 follow-up, canon §6)

mosaic-doctor now reports which tree fleet state resolves from and warns on the drift a launch would hit at runtime: - stale MOSAIC_BRAIN_HOME (no fleet/agents under it) - symlinked brain/agents paths (managed-directory boundary) - group/world-readable agents dir (0700 projection boundary) - split state: env files in BOTH config-home and brain trees Resolution mirrors brain-home.ts (#1298): MOSAIC_BRAIN_HOME wins; canonical ~/.mosaic adopted only at the default config home; else legacy. test-brain-home-check.sh: extraction-style harness (test-fleet-transport discipline — functions pulled from the shipped script, never copied), 8 cases covering every branch; wired into test:framework-shell and covered by the enumeration guard (population 53, all present). Live-run verified on dragon-lin: caught two real drifts — agents dir 755 (fixed locally) and pre-cutover split state (expected, tracked in mosaic-brain fleet/SEAT-CUTOVER.md).
feat(fleet): brain-home split — fleet state under ~/.mosaic, templates stay config-home (#1298 )
2026-08-17 22:34:22 -05:00 · 2026-08-18 03:23:15 +00:00 · 2026-08-17 20:44:59 +00:00 · 2026-08-16 18:03:02 -05:00 · 2026-08-16 17:58:49 -05:00 · 2026-08-16 18:12:33 +00:00
26 changed files with 1573 additions and 49 deletions
@@ -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');
+  });
+});
@@ -12,6 +12,33 @@ The default tmux socket is `mosaic-fleet` so fleet commands do not touch the
 default tmux server. The roster is the desired-state authority; generated environment files are
 rebuildable projections, never a second source of configuration.

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

 - `examples/minimal.yaml` starts one local canary slot.
@@ -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.
@@ -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,118 @@ 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}"
+}
+
+# Brain-home fleet-state resolution (#1298; canon STRUCTURE-CANON §2).
+#
+# Seat launch envs, roles.local overrides, and profile working copies resolve
+# from the brain home when one is active; roster, baseline roles, run/, and
+# services stay under MOSAIC_HOME. This check surfaces which tree fleet state
+# resolves from and the drift a launch would otherwise hit at runtime:
+#
+# - a stale MOSAIC_BRAIN_HOME pointing at a directory with no fleet/agents is a
+#   misconfiguration the resolver honors (explicit wins) — warn, don't pass;
+# - a symlinked brain or agents dir defeats the managed-directory boundary;
+# - a group/world-readable agents dir violates the 0700 projection boundary;
+# - env files left in the config-home tree while a brain is active are split
+#   state — the write path rejects NEW split writes, but nothing would ever
+#   tell the operator the old files are stranded.
+resolve_brain_home() {
+  local explicit="${MOSAIC_BRAIN_HOME:-}"
+  if [[ -n "$(printf '%s' "$explicit" | tr -d '[:space:]')" ]]; then
+    printf '%s' "$explicit"
+    return
+  fi
+  if [[ "$(cd "$MOSAIC_HOME" 2>/dev/null && pwd -P)" == "$HOME/.config/mosaic" \
+     && -d "$HOME/.mosaic/fleet/agents" ]]; then
+    printf '%s' "$HOME/.mosaic"
+    return
+  fi
+  printf '%s' "$MOSAIC_HOME"
+}
+
+check_brain_home() {
+  local brain agents mode
+  brain="$(resolve_brain_home)"
+
+  if [[ "$brain" == "$MOSAIC_HOME" ]]; then
+    pass "Fleet state home: $MOSAIC_HOME (legacy single-tree; no brain adopted)"
+    return
+  fi
+
+  agents="$brain/fleet/agents"
+  if [[ ! -d "$agents" ]]; then
+    warn "Brain home '$brain' has no fleet/agents — seat envs will not resolve from it. Point MOSAIC_BRAIN_HOME at a brain carrying fleet/agents, or unset it."
+    return
+  fi
+  if [[ -L "$brain" || -L "$agents" ]]; then
+    warn "Brain fleet-state path resolves through a symlink ($brain) — the managed-directory boundary requires regular directories."
+    return
+  fi
+
+  mode="$(stat -c '%a' -- "$agents" 2>/dev/null)" || mode=""
+  if [[ -n "$mode" ]] && (( (8#$mode & 8#077) != 0 )); then
+    warn "Brain agents dir '$agents' is group/world-accessible (mode $mode) — the projection boundary requires 0700."
+    return
+  fi
+
+  if [[ -d "$MOSAIC_HOME/fleet/agents" ]] \
+     && ls "$MOSAIC_HOME/fleet/agents/"*.env* >/dev/null 2>&1; then
+    warn "Fleet env files exist in BOTH trees — brain '$brain' is active but '$MOSAIC_HOME/fleet/agents' still carries env files (split state). Migrate them (mosaic fleet regen) and remove the config-home copies."
+    return
+  fi
+
+  pass "Fleet state home: $brain (brain active); roster + templates: $MOSAIC_HOME"
+}
+
+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
+
+check_brain_home
+
 # Legacy migration surfaces should no longer contain symlink trees.
 legacy_paths=(
  "$HOME/.claude/agent-guides"
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Covers the brain-home fleet-state check in `mosaic-doctor` (#1298 follow-up).
+#
+# The functions are extracted from the shipped script rather than copied here
+# (same discipline as test-fleet-transport-check.sh): a test that carries its
+# own copy of the logic keeps passing after the shipped copy changes.
+# Extraction is by exact function header and a closing brace in column one.
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname "$0")" && pwd)
+DOCTOR="$SCRIPT_DIR/mosaic-doctor"
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+[ -f "$DOCTOR" ] || fail "missing mosaic-doctor at $DOCTOR"
+
+extract_function() {
+  local name="$1"
+  local extracted
+  extracted=$(sed -n "/^${name}() {/,/^}/p" "$DOCTOR")
+  [ -n "$extracted" ] || fail "could not extract ${name}() from mosaic-doctor — script reshaped?"
+  printf '%s\n' "$extracted"
+}
+
+for fn in resolve_brain_home check_brain_home; do
+  extract_function "$fn" >/dev/null
+done
+
+warn_count=0
+warn() { warn_count=$((warn_count + 1)); echo "[WARN] $*"; }
+pass() { echo "[OK] $*"; return 0; }
+
+eval "$(extract_function resolve_brain_home)"
+eval "$(extract_function check_brain_home)"
+
+ROOT=$(mktemp -d)
+trap 'rm -rf "$ROOT"' EXIT
+
+run_case() {
+  # label, expect (ok|warn), then env assignments as arguments.
+  # The check runs under `env` in a subshell, so its warn() also prints a
+  # sentinel the parent counts — a subshell counter would never be visible.
+  local label="$1" expect="$2"
+  shift 2
+  local out warns
+  out=$(env "$@" bash -c "warn() { echo \"[WARN] \$*\"; }; pass() { echo \"[OK] \$*\"; return 0; }; $(extract_function resolve_brain_home); $(extract_function check_brain_home); check_brain_home" 2>&1)
+  warns=$(printf '%s\n' "$out" | grep -c '^\[WARN\]' || true)
+  if [[ "$expect" == ok && "$warns" -eq 0 ]]; then
+    echo "ok - $label"
+  elif [[ "$expect" == warn && "$warns" -gt 0 ]]; then
+    echo "ok - $label (warned)"
+  else
+    echo "output: $out" >&2
+    fail "$label: expected $expect (warns=$warns)"
+  fi
+}
+
+# ── legacy: no brain, custom home never adopts ─────────────────────────────
+mkdir -p "$ROOT/legacy-mosaic/fleet/agents"
+run_case "custom home without brain stays legacy" ok \
+  MOSAIC_HOME="$ROOT/legacy-mosaic" HOME="$ROOT"
+
+# ── healthy brain at the default config home ───────────────────────────────
+mkdir -p "$ROOT/home/.config/mosaic" "$ROOT/home/.mosaic/fleet/agents"
+chmod 700 "$ROOT/home/.mosaic/fleet/agents"
+run_case "default home adopts healthy brain" ok \
+  MOSAIC_HOME="$ROOT/home/.config/mosaic" HOME="$ROOT/home"
+
+# ── explicit MOSAIC_BRAIN_HOME to a brain without fleet/agents → warn ──────
+mkdir -p "$ROOT/brain-noagents/fleet" "$ROOT/config"
+run_case "explicit brain without agents warns" warn \
+  MOSAIC_HOME="$ROOT/config" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-noagents"
+
+# ── explicit MOSAIC_BRAIN_HOME to a healthy brain → ok ─────────────────────
+mkdir -p "$ROOT/brain-ok/fleet/agents" "$ROOT/config2"
+chmod 700 "$ROOT/brain-ok/fleet/agents"
+run_case "explicit healthy brain passes" ok \
+  MOSAIC_HOME="$ROOT/config2" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-ok"
+
+# ── group-readable agents dir → warn (0700 boundary) ───────────────────────
+mkdir -p "$ROOT/brain-loose/fleet/agents" "$ROOT/config3"
+chmod 750 "$ROOT/brain-loose/fleet/agents"
+run_case "group-readable brain agents warns" warn \
+  MOSAIC_HOME="$ROOT/config3" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-loose"
+
+# ── symlinked agents dir → warn (managed-directory boundary) ───────────────
+mkdir -p "$ROOT/brain-link/real-agents" "$ROOT/brain-link/fleet" "$ROOT/config4"
+ln -s "$ROOT/brain-link/real-agents" "$ROOT/brain-link/fleet/agents"
+run_case "symlinked brain agents warns" warn \
+  MOSAIC_HOME="$ROOT/config4" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-link"
+
+# ── split state: envs in BOTH trees → warn ─────────────────────────────────
+mkdir -p "$ROOT/brain-split/fleet/agents" "$ROOT/config5/fleet/agents"
+chmod 700 "$ROOT/brain-split/fleet/agents" "$ROOT/config5/fleet/agents"
+touch "$ROOT/config5/fleet/agents/coder0.env.generated"
+run_case "env files in both trees warns (split state)" warn \
+  MOSAIC_HOME="$ROOT/config5" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-split"
+
+# ── config-home agents dir WITHOUT env files alongside a brain → ok ────────
+mkdir -p "$ROOT/brain-clean/fleet/agents" "$ROOT/config6/fleet/agents"
+chmod 700 "$ROOT/brain-clean/fleet/agents" "$ROOT/config6/fleet/agents"
+run_case "empty config-home agents dir alongside brain passes" ok \
+  MOSAIC_HOME="$ROOT/config6" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-clean"
+
+echo "ok - mosaic-doctor brain-home check"
@@ -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)"
@@ -80,6 +80,26 @@ safe_path "$MOSAIC_HOME" || fail_env unsafe-path MOSAIC_HOME "$MOSAIC_HOME"

 FLEET_DIR="$MOSAIC_HOME/fleet"
 AGENT_ENV_DIR="$FLEET_DIR/agents"
+
+# Brain-home split (canon docs/STRUCTURE-CANON.md §2): seat launch envs live
+# under the brain home's fleet/agents when a brain is active; roster, roles
+# baseline, and runtime state (fleet/run) stay under MOSAIC_HOME.
+# Resolution mirrors packages/mosaic/src/fleet/brain-home.ts:
+#   1. MOSAIC_BRAIN_HOME env (explicit, always wins)
+#   2. ~/.mosaic — adopted only when MOSAIC_HOME is the default config home AND
+#      ~/.mosaic/fleet/agents exists
+#   3. MOSAIC_HOME (legacy single-tree)
+BRAIN_HOME="${MOSAIC_BRAIN_HOME:-}"
+if [ -z "$BRAIN_HOME" ]; then
+  BRAIN_HOME="$MOSAIC_HOME"
+  if [ "$(cd "$MOSAIC_HOME" 2>/dev/null && pwd -P)" = "$HOME/.config/mosaic" ] \
+     && [ -d "$HOME/.mosaic/fleet/agents" ]; then
+    BRAIN_HOME="$HOME/.mosaic"
+  fi
+fi
+if [ "$BRAIN_HOME" != "$MOSAIC_HOME" ]; then
+  AGENT_ENV_DIR="$BRAIN_HOME/fleet/agents"
+fi
 assert_managed_directory "$MOSAIC_HOME"
 assert_managed_directory "$FLEET_DIR"
 assert_private_directory "$AGENT_ENV_DIR"
@@ -286,6 +306,36 @@ _build_runtime_bin_prefix() {
 MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
 PANE_PATH=${MOSAIC_RUNTIME_BIN_PREFIX:+${MOSAIC_RUNTIME_BIN_PREFIX}:}/usr/local/bin:/usr/bin:/bin

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

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

 run_start() {
@@ -88,6 +143,7 @@ run_start() {
  local agent="$2"
  HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
    MOSAIC_TEST_PANE_PID="${MOSAIC_TEST_PANE_PID:-}" \
+    MOSAIC_TEST_HELD_SESSIONS="${MOSAIC_TEST_HELD_SESSIONS:-}" \
    MOSAIC_TEST_HOME="$home" \
    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
    MOSAIC_HOME="$home" "$START" "$agent"
@@ -98,7 +154,10 @@ run_start() {
 HOME_VALID="$ROOT/valid"
 AGENT_VALID="coder0"
 write_generated "$HOME_VALID" "$AGENT_VALID"
-run_start "$HOME_VALID" "$AGENT_VALID"
+# A live pane PID is part of what "valid launch" means. Until #1241 this case
+# ran with none, so the suite's one success path was itself a dead pane the
+# launcher reported as fine.
+MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_VALID" "$AGENT_VALID"
 valid_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$valid_args" | grep -qF new-session || fail "valid generated projection did not reach tmux"
 echo "$valid_args" | grep -qF 'mosaic' || fail "fixed mosaic launcher command missing"
@@ -108,6 +167,54 @@ if echo "$valid_args" | grep -qF 'bash -c'; then
  fail "launcher constructed a shell command payload"
 fi

+# ── Brain-home split (canon §2) ─────────────────────────────────────────
+# When MOSAIC_HOME is the default config home under $HOME and the host carries
+# $HOME/.mosaic/fleet/agents, seat envs resolve from the brain tree; the config
+# home still owns fleet/run (holder-owner) and remains a managed boundary.
+: > "$TMUX_CALLS"
+HOME_BRAIN="$ROOT/brain-home"
+CONFIG_HOME="$HOME_BRAIN/.config/mosaic"
+BRAIN="$HOME_BRAIN/.mosaic"
+mkdir -p "$CONFIG_HOME/fleet/run" "$BRAIN/fleet/agents" "$HOME_BRAIN/work"
+chmod 700 "$CONFIG_HOME" "$CONFIG_HOME/fleet" "$CONFIG_HOME/fleet/run" \
+  "$BRAIN/fleet/agents" "$HOME_BRAIN/work"
+printf '123e4567-e89b-12d3-a456-426614174000\n' > "$CONFIG_HOME/fleet/run/holder-owner"
+chmod 600 "$CONFIG_HOME/fleet/run/holder-owner"
+cat > "$BRAIN/fleet/agents/coder-brain.env.generated" <<EOF
+MOSAIC_AGENT_NAME=coder-brain
+MOSAIC_AGENT_CLASS=code
+MOSAIC_AGENT_RUNTIME=pi
+MOSAIC_AGENT_MODEL=openai-codex/gpt-5.6-sol
+MOSAIC_AGENT_REASONING=high
+MOSAIC_AGENT_TOOL_POLICY=code
+MOSAIC_AGENT_WORKDIR=$HOME_BRAIN/work
+MOSAIC_TMUX_SOCKET=mosaic-test
+EOF
+chmod 600 "$BRAIN/fleet/agents/coder-brain.env.generated"
+install_pane_binaries "$HOME_BRAIN"
+HOME="$HOME_BRAIN" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
+  MOSAIC_TEST_PANE_PID=$$ MOSAIC_TEST_HOME="$HOME_BRAIN" \
+  MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
+  MOSAIC_HOME="$CONFIG_HOME" "$START" coder-brain
+brain_args=$(tr '\0' '\n' < "$TMUX_CALLS")
+echo "$brain_args" | grep -qF new-session || fail "brain-home generated projection did not reach tmux"
+echo "$brain_args" | grep -qF 'coder-brain' || fail "brain-home agent env was not the launch source"
+[ -f "$BRAIN/fleet/agents/coder-brain.env.generated" ] || fail "brain generated env vanished"
+
+# Negative control: the SAME default-config-home shape but without
+# ~/.mosaic/fleet/agents — the config-home env tree is used directly (legacy).
+: > "$TMUX_CALLS"
+HOME_NOBRAIN="$ROOT/brainless-home"
+CONFIG_HOME_NOBRAIN="$HOME_NOBRAIN/.config/mosaic"
+write_generated "$CONFIG_HOME_NOBRAIN" "coder-legacy"
+install_pane_binaries "$HOME_NOBRAIN"
+HOME="$HOME_NOBRAIN" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
+  MOSAIC_TEST_PANE_PID=$$ MOSAIC_TEST_HOME="$HOME_NOBRAIN" \
+  MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
+  MOSAIC_HOME="$CONFIG_HOME_NOBRAIN" "$START" coder-legacy
+legacy_args=$(tr '\0' '\n' < "$TMUX_CALLS")
+echo "$legacy_args" | grep -qF new-session || fail "legacy single-tree launch regressed"
+
 # The pane must start through an absolute clean-environment boundary. Its
 # runtime command remains an argv vector, but no holder/session environment
 # control variable can pass through the pane command.
@@ -245,6 +352,13 @@ PANE_BASH_ENV="$ROOT/pane-boundary.bash-env"
 printf 'MOSAIC_RUNTIME_BIN=%s\n' "$FAKE_BIN" > \
  "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
 chmod 600 "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
+# This case does not go through run_start, so its pane binaries come from
+# MOSAIC_RUNTIME_BIN=$FAKE_BIN in the env.local written above — not from the
+# symlinks install_pane_binaries planted under the generated home, which this
+# launcher never consults because HOME here is the trusted parent. That is a
+# legitimate resolution path, but it means dropping MOSAIC_RUNTIME_BIN from
+# this case on the belief that the symlinks cover it would break the #1241
+# binary check rather than exercise it.
 LD_PRELOAD='/not/loaded/by-clean-bootstrap.so' \
 BASH_ENV="$PANE_BASH_ENV" \
 MOSAIC_UNTRUSTED_SENTINEL='must-not-reach-pane' \
@@ -258,6 +372,7 @@ PATH="$PANE_STALE_PATH" \
    "MOSAIC_TEST_HOME=$PANE_TRUSTED_HOME" \
    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
    MOSAIC_TEST_EXECUTE_PANE=1 \
+    "MOSAIC_TEST_PANE_PID=$$" \
    "$START" coder-pane-boundary
 pane_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$pane_args" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
@@ -392,6 +507,75 @@ echo "$interaction_policy_args" | grep -qF 'new-session' && \
 echo "$output" | grep -qF 'operator interaction service requires runtime pi' || \
  fail "interaction pinned-policy check did not follow strict parsing"

+# #1241. The pane runs `mosaic yolo <runtime>` against PANE_PATH. A binary
+# missing from that path is a launch failure, and it has to be named before the
+# session is created — after it, the diagnostic dies with the pane.
+assert_missing_pane_binary_rejected() {
+  local binary="$1"
+  local home="$ROOT/missing-$binary"
+  local agent="coder-missing-$binary"
+  write_generated "$home" "$agent"
+  rm -f "$home/.npm-global/bin/$binary"
+
+  : > "$TMUX_CALLS"
+  local output
+  if output=$(MOSAIC_TEST_PANE_PID=$$ run_start "$home" "$agent" 2>&1); then
+    fail "launch succeeded with '$binary' absent from the pane PATH"
+  fi
+  echo "$output" | grep -qF 'code=missing-binary' || fail "missing '$binary' diagnostic missing"
+  echo "$output" | grep -qF "'$binary'" || fail "missing-binary diagnostic did not name $binary"
+  if tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session; then
+    fail "launcher created a session it knew would die ($binary absent)"
+  fi
+}
+
+assert_missing_pane_binary_rejected mosaic
+assert_missing_pane_binary_rejected pi
+
+# #1241. tmux destroys a session when its pane command exits, so no pane PID a
+# second after new-session means the runtime died on startup. This used to be a
+# WARNING about the heartbeat sidecar followed by exit 0 — three layers above it
+# then reported a fleet that was not running.
+: > "$TMUX_CALLS"
+HOME_DEAD_PANE="$ROOT/dead-pane"
+write_generated "$HOME_DEAD_PANE" "coder-dead-pane"
+if output=$(MOSAIC_TEST_PANE_PID='' run_start "$HOME_DEAD_PANE" coder-dead-pane 2>&1); then
+  fail "launcher reported success over a pane that did not survive"
+fi
+echo "$output" | grep -qF 'code=pane-did-not-survive' || fail "dead-pane diagnostic missing"
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "dead pane is still being reported as a heartbeat-sidecar problem"
+fi
+tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session || \
+  fail "dead-pane case did not reach the launch it is measuring"
+
+# #1241, the other way a pane fails. Above, tmux destroyed the session and
+# has-session said so. Here the session is still there and no PID comes back
+# after the retries — a different fault (the pane is alive but unusable, or
+# tmux is answering inconsistently) that an operator has to be told apart from
+# a runtime that died on startup.
+#
+# This case exists because the branch that handles it shipped with nothing able
+# to reach it: the shim answered has-session only for the holder, so every
+# non-holder agent landed in the session-is-gone branch no matter what. A
+# defensive branch nothing exercises is the same shape as the bug this whole
+# change is about, one layer down.
+: > "$TMUX_CALLS"
+HOME_NO_PID="$ROOT/pane-no-pid"
+write_generated "$HOME_NO_PID" "coder-no-pid"
+if output=$(MOSAIC_TEST_PANE_PID='' MOSAIC_TEST_HELD_SESSIONS='=coder-no-pid:0.0' \
+  run_start "$HOME_NO_PID" coder-no-pid 2>&1); then
+  fail "launcher reported success over a session with no resolvable pane PID"
+fi
+echo "$output" | grep -qF 'code=pane-pid-unresolved' || \
+  fail "session-present/no-PID was not reported as pane-pid-unresolved: $output"
+if echo "$output" | grep -qF 'code=pane-did-not-survive'; then
+  fail "a session tmux still reports was diagnosed as a destroyed session"
+fi
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "an unresolvable pane PID is still being reported as a heartbeat-sidecar problem"
+fi
+
 # Exact stop derives the socket exclusively from the validated generated
 # projection and ignores an ambient socket supplied by the caller.
 : > "$TMUX_CALLS"
@@ -32,10 +32,6 @@ packages/mosaic/framework/tools/tmux/test-send-message-socket.sh | requires a re
 packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its sibling)

 # --- single-suite directories: unmeasured in CI ---
-packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | unmeasured in CI image; stubs tmux via a fake bin dir, likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/glpi/test-list-http-status.sh | unmeasured in CI image; stub-based (#807 regression harness), likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/orchestrator/test-board-roll.sh | unmeasured in CI image; file-fixture based, likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasured in CI image; drives ci-wait.sh against a stub pipeline-status.sh, likely CI-fit; #1017 burndown

 # --- naming-boundary files the strict test-*.sh prefix cannot even name ---
 # (#1017: three independent censuses handled the microtest file three different
@@ -43,3 +39,20 @@ packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasu
 # recorded judgement. These lines ARE that judgement, signed.)
 packages/mosaic/framework/tools/orchestrator/smoke-test.sh | behavior smoke checks for coord continue/run workflows, run manually by orchestrator seats; unmeasured in CI; #1017 burndown
 packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh | #973 instrument self-test, run as a precondition of the validate-973 evidence procedure rather than as a standing CI suite; #1017 burndown candidate
+
+# --- tools/fleet: precondition is unsatisfiable in the CI image (#1271) ---
+# Signed by fred (sb-it-1-dt, 2026-08-16) at origin/next 476db12.
+# This suite asserts the launcher's behaviour when `mosaic` and `pi` are MISSING.
+# It shims fakes into $FAKE_BIN, but the constructed PANE_PATH always ends in the
+# real system path, so on a host that installs those binaries the missing-binary
+# cases cannot be measured at all. The suite's own guard (line 103) says so and
+# fails rather than reporting a pass it cannot back. That guard is correct.
+# The error was wiring the suite into CI: #1017 (c56483eb) enumerated it and
+# dropped this exclusion, and the CI image provides `pi` in the system path, so
+# it has failed on every pipeline since. Measured 2026-08-16 across pipelines
+# 2444 (#1256), 2438 (#1240) and 2441 (#1017-quality): exactly one FAIL line in
+# each full log, identical, this assertion; control `zzz-not-present-zzz` -> 0.
+# Burn-down and the full measurement are tracked in #1271; unwired by PR #1270.
+# Because test:framework-shell is one && chain and this sat at position 44 of 48,
+# the four suites after it had not run at all since the merge.
+packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | precondition unsatisfiable in the CI image: asserts missing-binary behaviour, but PANE_PATH always ends in the system path and the image provides `pi` there; guard at line 103 fails by design rather than passing unmeasured. Burn down by controlling the tail of PANE_PATH inside the test. NOT by removing `pi` from the image: the CI image installs @earendil-works/[email protected] deliberately (measured in pipeline 2444's test-step log), and other suites depend on that pin. Burn-down tracked in #1271
@@ -25,7 +25,7 @@
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { fleetAgentEnvDir, fleetRolesLocalDir } from '../fleet/brain-home.js';
 import type { Command } from 'commander';
 import {
  executeFleetAgentMutation,
@@ -149,9 +150,9 @@ async function executeCommand(
    request,
    mosaicHome,
    rosterPath,
-    agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+    agentEnvDir: fleetAgentEnvDir(mosaicHome),
    rolesDir: join(mosaicHome, 'fleet', 'roles'),
-    overrideDir: join(mosaicHome, 'fleet', 'roles.local'),
+    overrideDir: fleetRolesLocalDir(mosaicHome),
    dryRun: forceDryRun || opts.dryRun === true,
    ...(deps.projectionApplier === undefined ? {} : { projectionApplier: deps.projectionApplier }),
  });
@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { fleetAgentEnvDir, fleetRolesLocalDir } from '../fleet/brain-home.js';
 import type { Command } from 'commander';
 import {
  parseV1MigrationObservations,
@@ -120,11 +121,11 @@ export function registerFleetMigrationCommand(
          observations,
          personaDirs: {
            rolesDir: deps.rolesDir ?? join(mosaicHome, 'fleet', 'roles'),
-            overrideDir: deps.overrideDir ?? join(mosaicHome, 'fleet', 'roles.local'),
+            overrideDir: deps.overrideDir ?? fleetRolesLocalDir(mosaicHome),
          },
          environment: {
            mosaicHome,
-            agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+            agentEnvDir: fleetAgentEnvDir(mosaicHome),
          },
        });
        printJson(preview);
@@ -30,19 +30,21 @@ import { lstat, readFile, readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, isAbsolute, join, sep } from 'node:path';
 import type { Command } from 'commander';
+import { fleetRolesLocalDir } from '../fleet/brain-home.js';

 function defaultMosaicHome(): string {
  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 }

-/** Baseline persona role contracts (reseeded on update). */
+/** Baseline persona role contracts (reseeded on update; config home — framework). */
 export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
  return join(mosaicHome, 'fleet', 'roles');
 }

-/** PRESERVE-protected override layer (survives update; wins on merge). */
+/** PRESERVE-protected override layer (survives update; wins on merge).
+ * Brain home (`~/.mosaic/fleet/roles.local`) when a brain is active. */
 export function defaultOverrideDir(mosaicHome = defaultMosaicHome()): string {
-  return join(mosaicHome, 'fleet', 'roles.local');
+  return fleetRolesLocalDir(mosaicHome);
 }

 /**
@@ -25,6 +25,7 @@ import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import type { Command } from 'commander';
 import YAML from 'yaml';
+import { fleetProfilesDir } from '../fleet/brain-home.js';
 import {
  defaultOverrideDir,
  extractClassesFromDir,
@@ -36,9 +37,10 @@ function defaultMosaicHome(): string {
  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 }

-/** Directory holding the seeded profile yaml files. */
+/** Directory holding the seeded profile yaml files — brain home when active
+ * (user working copies, committed), else the config home seed. */
 export function defaultProfilesDir(mosaicHome = defaultMosaicHome()): string {
-  return join(mosaicHome, 'fleet', 'profiles');
+  return fleetProfilesDir(mosaicHome);
 }

 /** Directory holding the persona role contracts. */
@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { join, relative, resolve } from 'node:path';
 import type { Command } from 'commander';
 import type { CommandRunner } from './fleet.js';
+import { fleetAgentEnvDir } from '../fleet/brain-home.js';
 import {
  applyPreparedGeneratedAgentEnvironmentProjection,
  prepareGeneratedAgentEnvironmentProjection,
@@ -153,7 +154,7 @@ export async function executeFleetRegen(
  options: FleetRegenOptions,
 ): Promise<FleetRegenResult> {
  const mosaicHome = defaultMosaicHome(deps);
-  const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
+  const agentEnvDir = fleetAgentEnvDir(mosaicHome);
  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
  const readRoster = deps.readRoster ?? defaultReadRoster(deps, mosaicHome);
  const prepare = deps.prepareProjection ?? prepareGeneratedAgentEnvironmentProjection;
@@ -13,6 +13,7 @@ import {
 import { randomUUID } from 'node:crypto';
 import { homedir, hostname, userInfo } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { fleetAgentEnvDir } from '../fleet/brain-home.js';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import * as readline from 'node:readline';
@@ -158,7 +159,7 @@ export function resolveFleetPaths(mosaicHome = defaultMosaicHome()): FleetPaths
    fleetToolsDir: join(mosaicHome, 'tools', 'fleet'),
    tmuxToolsDir: join(mosaicHome, 'tools', 'tmux'),
    systemdUserDir: join(homedir(), '.config', 'systemd', 'user'),
-    agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+    agentEnvDir: fleetAgentEnvDir(mosaicHome),
  };
 }

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

@@ -64,9 +65,46 @@ const HARNESS_HOME_ENV: Record<RuntimeName, string> = {
  opencode: 'XDG_CONFIG_HOME',
 };

-/** Dedicated mosaic-owned home for a runtime: ~/.config/mosaic/.<runtime> */
-function harnessHome(runtime: RuntimeName): string {
-  return join(MOSAIC_HOME, `.${runtime}`);
+/** Dedicated mosaic-owned home for a runtime: ~/.config/mosaic/.<runtime>.
+ * With an active brain seat (MOSAIC_AGENT_NAME + seat dir in the brain home)
+ * the home is per-agent instead: <brainHome>/fleet/agents/<seat>/.<runtime> —
+ * per-agent sessions, settings, and auth inside the seat dir (canon §2,
+ * MOSAIC-D-002). Seat runtime dirs are dot-named so the brain's ignore policy
+ * (per-seat .pi/.claude/.codex dirs) keeps credential material untracked. */
+const SEAT_AGENT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+export function activeSeatDir(mosaicHome: string = MOSAIC_HOME): string | undefined {
+  const agent = process.env['MOSAIC_AGENT_NAME']?.trim();
+  if (
+    agent === undefined ||
+    agent === '' ||
+    !SEAT_AGENT_NAME_RE.test(agent) ||
+    agent.includes('..')
+  ) {
+    return undefined;
+  }
+  const brain = resolveBrainHome(mosaicHome);
+  if (resolve(brain) === resolve(mosaicHome)) return undefined; // no brain
+  const seat = join(brain, 'fleet', 'agents', agent);
+  return existsSync(seat) ? seat : undefined;
+}
+
+function harnessHome(runtime: RuntimeName, mosaicHome: string = MOSAIC_HOME): string {
+  const seat = activeSeatDir(mosaicHome);
+  if (seat !== undefined) return join(seat, `.${runtime}`);
+  return join(mosaicHome, `.${runtime}`);
+}
+
+/** Seat persona block: with an active brain seat, <seat>/SOUL.md layers
+ * persona on the root generic base (canon invariant; MOSAIC-D-002). The base
+ * SOUL stays load-on-demand — only the seat delta is injected by value.
+ * Empty string when no seat is active or the seat carries no SOUL.md. */
+export function seatPersonaOverlay(mosaicHome: string = MOSAIC_HOME): string {
+  const seatDir = activeSeatDir(mosaicHome);
+  if (seatDir === undefined) return '';
+  const seatSoul = readOptional(join(seatDir, 'SOUL.md'));
+  if (!seatSoul.trim()) return '';
+  return '## Seat Persona\n\n' + seatSoul.trim();
 }

 /**
@@ -182,6 +220,8 @@ function recordLaunch(runtime: RuntimeName, cliArgs: string[], yolo: boolean): v
      cli_version: CLI_VERSION,
      config_home: harnessHome(runtime),
      config_home_isolated: true,
+      config_home_kind: activeSeatDir() !== undefined ? 'seat' : 'runtime-shared',
+      agent_name: process.env['MOSAIC_AGENT_NAME']?.trim() || null,
      config_home_env: HARNESS_HOME_ENV[runtime] ?? null,
      argv: redactArgv(cliArgs),
      normative_fragments: normativeFragmentDigests(runtime),
@@ -569,6 +609,11 @@ For required push/merge/issue-close/release actions, execute without routine con
  if (soulLocal.trim()) {
    overlayBlocks.push('## Persona Overlay (SOUL.local.md)\n\n' + soulLocal.trim());
  }
+  // Seat persona (MOSAIC-D-002): per-seat SOUL.md layers on the generic base.
+  const seatPersona = seatPersonaOverlay(mosaicHome);
+  if (seatPersona !== '') {
+    overlayBlocks.push(seatPersona);
+  }
  const standardsLocal = readOptional(join(mosaicHome, 'STANDARDS.local.md'));
  if (standardsLocal.trim()) {
    overlayBlocks.push('## Standards Overlay (STANDARDS.local.md)\n\n' + standardsLocal.trim());
@@ -0,0 +1,114 @@
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  brainHomeIsActive,
+  fleetAgentEnvDir,
+  fleetProfilesDir,
+  fleetRolesLocalDir,
+  fleetStateDir,
+  resolveBrainHome,
+  type BrainHomeOptions,
+} from './brain-home.js';
+
+describe('fleet brain-home resolution', (): void => {
+  let cleanup: string | undefined;
+
+  const savedBrainEnv = process.env['MOSAIC_BRAIN_HOME'];
+
+  beforeEach((): void => {
+    delete process.env['MOSAIC_BRAIN_HOME'];
+  });
+
+  afterEach(async (): Promise<void> => {
+    if (savedBrainEnv === undefined) {
+      delete process.env['MOSAIC_BRAIN_HOME'];
+    } else {
+      process.env['MOSAIC_BRAIN_HOME'] = savedBrainEnv;
+    }
+    if (cleanup !== undefined) {
+      await rm(cleanup, { recursive: true, force: true });
+      cleanup = undefined;
+    }
+  });
+
+  async function makeTmp(): Promise<string> {
+    const root = await mkdtemp(join(tmpdir(), 'mosaic-brain-home-'));
+    cleanup = root;
+    return root;
+  }
+
+  it('MOSAIC_BRAIN_HOME env wins over every other signal', (): void => {
+    process.env['MOSAIC_BRAIN_HOME'] = '/explicit/brain';
+    expect(resolveBrainHome('/any/mosaic-home')).toBe('/explicit/brain');
+    expect(fleetAgentEnvDir('/any/mosaic-home')).toBe('/explicit/brain/fleet/agents');
+    expect(brainHomeIsActive('/any/mosaic-home')).toBe(true);
+  });
+
+  it('injected envBrainHome wins identically (test seam)', (): void => {
+    const opts: BrainHomeOptions = { envBrainHome: '/injected/brain' };
+    expect(resolveBrainHome('/any/mosaic-home', opts)).toBe('/injected/brain');
+    expect(fleetAgentEnvDir('/any/mosaic-home', opts)).toBe('/injected/brain/fleet/agents');
+  });
+
+  it('a non-default mosaicHome never adopts the canonical brain (hermetic legacy)', (): void => {
+    const mosaicHome = '/tmp/not-the-default-config-home';
+    expect(resolveBrainHome(mosaicHome)).toBe(mosaicHome);
+    expect(brainHomeIsActive(mosaicHome)).toBe(false);
+    expect(fleetAgentEnvDir(mosaicHome)).toBe(join(mosaicHome, 'fleet', 'agents'));
+  });
+
+  it('the default config home adopts the brain when it carries fleet/agents', async (): Promise<void> => {
+    const root = await makeTmp();
+    const brain = join(root, 'brain');
+    await mkdir(join(brain, 'fleet', 'agents'), { recursive: true });
+    const configHome = join(root, 'config', 'mosaic');
+    const opts: BrainHomeOptions = { homes: { brain, configDefault: configHome } };
+
+    expect(resolveBrainHome(configHome, opts)).toBe(brain);
+    expect(fleetAgentEnvDir(configHome, opts)).toBe(join(brain, 'fleet', 'agents'));
+    expect(fleetRolesLocalDir(configHome, opts)).toBe(join(brain, 'fleet', 'roles.local'));
+    expect(fleetProfilesDir(configHome, opts)).toBe(join(brain, 'fleet', 'profiles'));
+    expect(fleetStateDir(configHome, opts)).toBe(join(brain, 'fleet'));
+    expect(brainHomeIsActive(configHome, opts)).toBe(true);
+  });
+
+  it('the default config home stays legacy when no brain exists', async (): Promise<void> => {
+    const root = await makeTmp();
+    const configHome = join(root, 'config', 'mosaic');
+    const opts: BrainHomeOptions = {
+      homes: { brain: join(root, 'brain'), configDefault: configHome },
+    };
+
+    expect(resolveBrainHome(configHome, opts)).toBe(configHome);
+    expect(brainHomeIsActive(configHome, opts)).toBe(false);
+  });
+
+  it('an empty MOSAIC_BRAIN_HOME is ignored, not treated as set', (): void => {
+    process.env['MOSAIC_BRAIN_HOME'] = '   ';
+    expect(resolveBrainHome('/tmp/legacy-home')).toBe('/tmp/legacy-home');
+  });
+
+  it('adoption requires fleet/agents specifically, not any brain content', async (): Promise<void> => {
+    const root = await makeTmp();
+    const brain = join(root, 'brain');
+    await mkdir(join(brain, 'fleet'), { recursive: true }); // fleet without agents
+    const configHome = join(root, 'config', 'mosaic');
+    const opts: BrainHomeOptions = { homes: { brain, configDefault: configHome } };
+
+    expect(resolveBrainHome(configHome, opts)).toBe(configHome);
+  });
+
+  it('real-home control: a host brain is adopted only through the default home', (): void => {
+    // Control on the un-injected path: this host carries ~/.mosaic/fleet/agents,
+    // so the default config home resolves to the brain or legacy — both valid
+    // canonical endpoints — while a non-default home never adopts.
+    const defaultHome = join(homedir(), '.config', 'mosaic');
+    const resolved = resolveBrainHome(defaultHome);
+    expect([defaultHome, join(homedir(), '.mosaic')]).toContain(resolved);
+    expect(resolveBrainHome(join(homedir(), 'elsewhere', 'mosaic'))).toBe(
+      join(homedir(), 'elsewhere', 'mosaic'),
+    );
+  });
+});
@@ -0,0 +1,76 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+/**
+ * Overridable resolution inputs (tests inject tmp homes; production reads
+ * the environment and the real home directory).
+ */
+export interface BrainHomeOptions {
+  /** Explicit brain home; defaults to `MOSAIC_BRAIN_HOME`. */
+  readonly envBrainHome?: string;
+  /**
+   * Canonical homes used for adoption. Defaults derive from the real
+   * `homedir()`: `{ brain: ~/.mosaic, configDefault: ~/.config/mosaic }`.
+   */
+  readonly homes?: { readonly brain: string; readonly configDefault: string };
+}
+
+/**
+ * Brain-home resolution — the three-tree fleet split (stack canon
+ * `docs/STRUCTURE-CANON.md` §2, first carried by the USC estate brain):
+ *
+ *   config home (~/.config/mosaic)  framework templates + dispatch state:
+ *                                   fleet/roles (baseline), fleet/roster.yaml,
+ *                                   fleet/run (heartbeats), fleet/services
+ *   brain home  (~/.mosaic)         user-owned fleet state, committed:
+ *                                   fleet/agents/<seat>.env.*, fleet/roles.local,
+ *                                   fleet/profiles working copies
+ *
+ * Resolution order:
+ *   1. `MOSAIC_BRAIN_HOME` env (explicit, always wins)
+ *   2. canonical `~/.mosaic` — adopted ONLY when mosaicHome is the real
+ *      default config home AND `~/.mosaic/fleet/agents` exists. Custom
+ *      `--mosaic-home` values (tests, sandboxes, canaries) never trigger
+ *      adoption, keeping them hermetic and deterministic.
+ *   3. mosaicHome itself (legacy single-tree behavior).
+ */
+export function resolveBrainHome(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  const explicit = options.envBrainHome ?? process.env['MOSAIC_BRAIN_HOME'];
+  if (explicit !== undefined && explicit.trim() !== '') {
+    return explicit;
+  }
+  const homes = options.homes ?? {
+    brain: join(homedir(), '.mosaic'),
+    configDefault: join(homedir(), '.config', 'mosaic'),
+  };
+  if (resolve(mosaicHome) !== resolve(homes.configDefault)) {
+    return mosaicHome;
+  }
+  return existsSync(join(homes.brain, 'fleet', 'agents')) ? homes.brain : mosaicHome;
+}
+
+/** True when fleet state resolves somewhere other than the config home. */
+export function brainHomeIsActive(mosaicHome: string, options: BrainHomeOptions = {}): boolean {
+  return resolve(resolveBrainHome(mosaicHome, options)) !== resolve(mosaicHome);
+}
+
+/** Fleet state root (brain home when active, else the config home). */
+export function fleetStateDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(resolveBrainHome(mosaicHome, options), 'fleet');
+}
+
+/** Seat launch envs — `<brainHome>/fleet/agents` when a brain is active. */
+export function fleetAgentEnvDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(fleetStateDir(mosaicHome, options), 'agents');
+}
+
+/** PRESERVE-protected persona override layer — `<brainHome>/fleet/roles.local`. */
+export function fleetRolesLocalDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(fleetStateDir(mosaicHome, options), 'roles.local');
+}
+
+/** System-type profiles (user working copies) — `<brainHome>/fleet/profiles`. */
+export function fleetProfilesDir(mosaicHome: string, options: BrainHomeOptions = {}): string {
+  return join(fleetStateDir(mosaicHome, options), 'profiles');
+}
@@ -3,6 +3,7 @@ import { lstat, open, readFile, unlink, type FileHandle } from 'node:fs/promises
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { fleetAgentEnvDir } from './brain-home.js';
 import {
  applyPreparedAgentEnvironmentProjection,
  prepareAgentEnvironmentProjection,
@@ -617,7 +618,7 @@ function defaultPrepareProjections(
        (agent: FleetRosterV2Agent): Promise<PreparedAgentEnvironmentProjection> =>
          prepareAgentEnvironmentProjection({
            mosaicHome,
-            agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+            agentEnvDir: fleetAgentEnvDir(mosaicHome),
            agentName: agent.name,
            generated: projectRosterV2AgentGeneratedEnv(roster, agent),
          }),
@@ -176,6 +176,52 @@ describe('generated fleet agent environment boundary', (): void => {
    expect((await stat(result.generatedPath)).mode & 0o777).toBe(0o600);
  });

+  it('brain home: accepts and writes projections under MOSAIC_BRAIN_HOME/fleet/agents', async (): Promise<void> => {
+    const savedBrainHome = process.env['MOSAIC_BRAIN_HOME'];
+    try {
+      cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
+      const mosaicHome = join(cleanup, 'config-home');
+      const brainHome = join(cleanup, 'brain');
+      const agentEnvDir = join(brainHome, 'fleet', 'agents');
+      process.env['MOSAIC_BRAIN_HOME'] = brainHome;
+
+      const result = await writeAgentEnvironmentProjection({
+        mosaicHome,
+        agentEnvDir,
+        agentName: 'coder0',
+        generated: generatedValues,
+      });
+
+      // Projection landed in the brain tree, not under the config home.
+      expect(result.generatedPath).toBe(join(agentEnvDir, 'coder0.env.generated'));
+      expect((await stat(join(brainHome, 'fleet'))).mode & 0o777).toBe(0o700);
+      expect((await stat(agentEnvDir)).mode & 0o777).toBe(0o700);
+      expect((await stat(result.generatedPath)).mode & 0o777).toBe(0o600);
+      await expect(stat(join(mosaicHome, 'fleet'))).rejects.toThrow();
+
+      // A config-home agentEnvDir is now REJECTED while the brain is active —
+      // the boundary must not silently split state across two trees.
+      let rejected: unknown;
+      try {
+        await writeAgentEnvironmentProjection({
+          mosaicHome,
+          agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+          agentName: 'coder1',
+          generated: { ...generatedValues, MOSAIC_AGENT_NAME: 'coder1' },
+        });
+      } catch (caught: unknown) {
+        rejected = caught;
+      }
+      expect(rejected).toBeInstanceOf(AgentEnvBoundaryError);
+    } finally {
+      if (savedBrainHome === undefined) {
+        delete process.env['MOSAIC_BRAIN_HOME'];
+      } else {
+        process.env['MOSAIC_BRAIN_HOME'] = savedBrainHome;
+      }
+    }
+  });
+
  it('regenerates desired keys, relocates safe legacy local data, and quarantines forbidden legacy input', async (): Promise<void> => {
    cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
    const mosaicHome = join(cleanup, 'mosaic');
@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { fleetAgentEnvDir, resolveBrainHome } from './brain-home.js';
 import { compareCodePoints } from './deterministic-order.js';

 export type AgentEnvironmentKind = 'generated' | 'local';
@@ -528,12 +529,15 @@ async function validatePrivateProjectionDirectory(
  mosaicHome: string,
  agentEnvDir: string,
 ): Promise<void> {
-  const fleetDir = join(mosaicHome, 'fleet');
-  const expectedAgentEnvDir = join(fleetDir, 'agents');
+  // Brain-home split (canon §2): seat envs live under the brain home's
+  // fleet/agents when a brain is active; roster + templates stay config-home.
+  const expectedAgentEnvDir = fleetAgentEnvDir(mosaicHome);
  if (resolve(agentEnvDir) !== resolve(expectedAgentEnvDir)) {
    throw new AgentEnvBoundaryError('unsafe-directory', '(directory)', agentEnvDir);
  }
-  await assertManagedDirectoryIfPresent(mosaicHome, false);
+  const stateHome = resolveBrainHome(mosaicHome);
+  const fleetDir = join(stateHome, 'fleet');
+  await assertManagedDirectoryIfPresent(stateHome, false);
  await assertManagedDirectoryIfPresent(fleetDir, false);
  await assertManagedDirectoryIfPresent(agentEnvDir, true);
 }
@@ -543,8 +547,9 @@ async function ensurePrivateProjectionDirectory(
  agentEnvDir: string,
 ): Promise<void> {
  await validatePrivateProjectionDirectory(mosaicHome, agentEnvDir);
-  const fleetDir = join(mosaicHome, 'fleet');
-  await ensureManagedDirectory(mosaicHome, false);
+  const stateHome = resolveBrainHome(mosaicHome);
+  const fleetDir = join(stateHome, 'fleet');
+  await ensureManagedDirectory(stateHome, false);
  await ensureManagedDirectory(fleetDir, false);
  await ensureManagedDirectory(agentEnvDir, true);
 }
@@ -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:
@@ -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 "$@"