fix(fleet): close persona resolver authority edges

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
fix(fleet): fail closed on persona overrides
2026-07-14 19:45:05 -05:00 · 2026-07-14 19:15:28 -05:00 · 2026-07-14 19:15:28 -05:00 · 2026-07-14 19:15:28 -05:00 · 2026-07-14 19:15:28 -05:00 · 2026-07-14 19:15:28 -05:00
23 changed files with 785 additions and 2583 deletions
--- a/docs/SITEMAP.md
+++ b/docs/SITEMAP.md
@@ -1,12 +1,5 @@
 # Documentation Sitemap
 ## Fleet configuration management
 - [Generated environment boundary](fleet/reference/generated-env-boundary.md) — roster-derived launch projection, strict local data, legacy quarantine, and downstream interface evidence.
 - [Roster v2 structural contract](fleet/reference/roster-v2-fields.md) — local-tmux schema v2 parsing and structural validation.
 - [Role classes and authority](fleet/reference/role-classes.md) — canonical role resolver and protected authority boundaries.
 - [Executable asset dispositions](fleet/migration/example-profile-disposition.md) — shipped v1 fixture/profile/service validation posture.
 ## Official channel plugins
 - [Channel protocol architecture](architecture/channel-protocol.md) — shared lifecycle, message, stable-route, authorization, and response-target contracts.
--- a/docs/fleet/FLEET-LAUNCH.md
+++ b/docs/fleet/FLEET-LAUNCH.md
@@ -1,77 +1,114 @@
 # Fleet Launch Runbook
-The local fleet roster is the sole writable desired-state authority for membership and launch policy.
+How every Mosaic fleet agent — workers **and** the orchestrator — is launched, and how to
-Generated environment files are rebuildable projections, not an operator-editable command surface.
+configure each one. The guiding principle: **one roster-driven launcher**. There is no bespoke
 per-agent launch script; the roster plus per-agent `.env` files are the single source of launch
 config.
-## Launch chain
+## The launch chain
-| Layer               | Responsibility                                                                                                                  |
+| Layer            | File                                              | Responsibility                                                                                                                                              |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| ---------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
+| systemd unit     | `mosaic-agent@<role>.service`                     | One templated unit per role; `ExecStart` runs the session launcher with the instance name `%i`. Defaults `MOSAIC_AGENT_RUNTIME=pi`, `MOSAIC_AGENT_NAME=%i`. |
-| Projection writer   | Renders deterministic `fleet/agents/<name>.env.generated` from the roster.                                                      |
+| session launcher | `tools/fleet/start-agent-session.sh <role>`       | Builds the launch command, opens the tmux pane, wires the heartbeat.                                                                                        |
-| Optional local data | Reads a strict, data-only `fleet/agents/<name>.env.local`; it cannot shadow generated keys.                                     |
+| launch command   | `mosaic yolo <runtime>` (or a per-agent override) | Replaces the pane's foreground process with the runtime, fully seeded.                                                                                      |
-| systemd             | Starts the launcher with `env -i` and fixed bootstrap data. It does not preload either environment file.                        |
+| seeding          | `mosaic`'s `composeContract()`                    | Injects the Constitution/USER/TOOLS/runtime contract, `*.local` overlays, **and** the Fleet-Comms cheat-sheet — all via `--append-system-prompt`.           |
 | session launcher    | Validates generated and local data before it queries, creates, or stops an exact tmux session.                                  |
 | runtime launch      | Derives the fixed `mosaic yolo <runtime>` argument array from validated roster data, then seeds the runtime contract.           |
-The launcher never `source`s or `eval`s an environment file and never accepts an environment-supplied
+Per-agent overrides live in `fleet/agents/<role>.env`, generated from `roster.yaml` by
-command. `MOSAIC_AGENT_COMMAND`, command/channel overrides, unknown keys, generated-key shadowing,
+`generateAgentEnv` (`packages/mosaic/src/commands/fleet.ts`) and consumed by the launcher.
 secret-like key names, duplicate keys, comments, quoted/export syntax, and unsafe values are rejected.
-## Generated and local files
+## Worker launch path (default)
-`<name>.env.generated` is complete, deterministic, and written only by Mosaic. Its ordered keys are:
+1. `roster.yaml` carries each agent's `runtime` and optional `model_hint`.
 2. `generateAgentEnv` emits `fleet/agents/<role>.env` with `MOSAIC_AGENT_NAME`,
   `MOSAIC_AGENT_RUNTIME`, and `MOSAIC_AGENT_MODEL`.
 3. `start-agent-session.sh` has no `MOSAIC_AGENT_COMMAND` set, so it falls through to the default
   (line ~44):
   ```sh
   MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}"
   ```
 4. The launcher bakes `MOSAIC_AGENT_NAME` into the pane command (line ~118), so `composeContract`
   can inject the Fleet-Comms cheat-sheet for that role.
-```dotenv
+That is the whole worker path: roster → `.env` → `mosaic yolo <runtime>` → seeded pane.
-MOSAIC_AGENT_NAME=<roster name>
+
-MOSAIC_AGENT_CLASS=<roster class>
+## Orchestrator fold (PATH A — ships today)
-MOSAIC_AGENT_RUNTIME=<roster runtime>
+
-MOSAIC_AGENT_MODEL=<roster model hint>
+The orchestrator is **just another roster agent** launched through the canonical path — not a
-MOSAIC_AGENT_REASONING=<roster reasoning>
+snowflake script.
-MOSAIC_AGENT_TOOL_POLICY=<roster tool policy>
+
-MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
+| Piece              | Value                               |
-MOSAIC_TMUX_SOCKET=<roster socket or empty>
+| ------------------ | ----------------------------------- |
 | host-side launcher | `orchestrator-launch.sh`            |
 | systemd unit       | `mosaic-fleet-orchestrator.service` |
 | tmux session       | `orchestrator` (role-named)         |
 Set its launch command via `fleet/agents/orchestrator.env`:
 ```sh
 MOSAIC_AGENT_COMMAND='mosaic yolo claude --channels plugin:discord@<channel>'
 ```
-The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. `mosaic fleet add`
+When `MOSAIC_AGENT_COMMAND` is set, `start-agent-session.sh`'s `if [ -z "$MOSAIC_AGENT_COMMAND" ]`
-rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
+guard (line ~41) is false, so the line-44 default — **including its hardcoded `yolo`** — is skipped
-The legacy dogfood stub remains an observability-only canary on its separate `mosaic-factory` socket;
+entirely. The override fully controls the runtime and flags. Routing through `mosaic yolo claude`
-it has no generated-launch adapter and cannot be added through this path.
+(rather than a raw `claude` invocation) is what gives the orchestrator the same full
 `composeContract` seeding + Fleet-Comms cheat-sheet as every worker, with `--channels` and any
 other flags passed straight through to the `claude` binary.
-`<name>.env.local` is optional and may contain only non-secret machine data:
+## Launch gotchas
- `MOSAIC_RUNTIME_BIN`
+1. **Flag conflict.** `mosaic yolo claude` already injects `--dangerously-skip-permissions`. Do
- `MOSAIC_HEARTBEAT_RUN_DIR`
+   **not** also pass `--permission-mode bypassPermissions` — the `claude` binary would receive both.
- `MOSAIC_HEARTBEAT_INTERVAL`
+   Use `mosaic yolo claude …` alone (yolo covers the unattended posture), **or** non-yolo
- `MOSAIC_CLAUDE_JSON`
+   `mosaic claude --permission-mode bypassPermissions …`. Never mix the two.
- `CLAUDE_CONFIG_DIR`
+2. **`MOSAIC_AGENT_NAME` must reach the pane.** The launcher bakes it from the instance name, and
   `composeContract` gates the Fleet-Comms block on it (`launch.ts`, in `composeContract`) — **and**
   the role must be a member of `roster.yaml`, or the block resolves empty.
 3. **`launchRuntime` guards.** `mosaic yolo claude` runs `checkSoul` / `checkRuntime` /
   `checkSequentialThinking`. The host needs `SOUL.md` and the sequential-thinking MCP, or the
   launch aborts (a raw `claude` invocation skipped these checks). Dry-run the composed command in a
   throwaway tmux session before swapping a live launcher.
-Paths must be safe absolute paths and the heartbeat interval must be a positive integer. Projection,
+## Why per-agent `.env` survives upgrades (#632)
 local, and quarantine files must be private regular files; the managed directories must be real,
 private, non-symlink paths. Violations fail closed before tmux interaction.
-## Legacy input and diagnostics
+`install.sh` `PRESERVE_PATHS` includes `fleet/*.yaml`, `fleet/agents`, and `fleet/run`, so
 `mosaic update`'s framework re-seed **preserves** your roster and per-agent `.env` overrides
 (glob-aware `cp` fallback; matching TS parity in `file-adapter.ts`). Before #632, an auto re-seed
 could wipe them — which is exactly why PATH A's `.env` override is safe to rely on now.
-A legacy `<name>.env` is input only during projection generation. Roster-owned keys are regenerated;
+## Inspecting the comms wiring
 valid allowed local data can move to `.env.local`; invalid legacy input is privately retained at
 `<name>.env.quarantine`. Neither legacy nor quarantine files are launch authority.
-Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command
+- `mosaic fleet comms-block <role>` prints the Fleet-Comms cheat-sheet a given role receives at
-text, credentials, or other values.
+  launch — its `[host:session]` identity, the exact `agent-send.sh` command for each peer, and the
  FLIP / `--verify` conventions. `--host <h>` previews a cross-host view. An unknown role or missing
  roster **fails loud** (stderr + non-zero exit), so a typo is never a silent no-op.
 - Versus `mosaic compose-contract <runtime>`: that emits the **whole** system prompt and reads the
  role from `MOSAIC_AGENT_NAME` (a full-prompt smoke test). `comms-block` is the targeted,
  explicit-arg, comms-only view — e.g. `mosaic fleet comms-block coder0-0` to preview a peer.
-## Launch and stop behavior
+## North Star / future direction
-The launcher obtains the agent's socket only from the validated generated projection. It creates or
+**Vision:** a webUI lets the user edit each agent's launch config — switch **harness**
-checks the exact `=<agent-name>` tmux target; it never uses an ambient socket or fuzzy session match.
+(claude / pi / codex / opencode), toggle **yolo**, pick a **model**, set a **command/channels**
-The same strict parser runs before exact-stop behavior. A fresh native Pi heartbeat remains authoritative;
+override — with no terminal.
 the shell sidecar only provides fallback state when the native marker is stale or absent.
-`mosaic fleet comms-block <role>` can inspect the role's resolved Fleet-Comms block. It is a read-only
+**Continuity — this is not a new launch path.** It is a data-model + UI-binding layer over the
-inspection tool and fails loudly for an unknown role or missing roster.
+existing roster-driven launcher. Field-by-field status today:
-## Current M2 boundary
+| Launch-config field      | Roster-native today? | Mechanism / gap                                                                                                                                          |
 | ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **harness** (`runtime`)  | ✅ end-to-end        | `roster.runtime` → `generateAgentEnv` emits `MOSAIC_AGENT_RUNTIME` → launcher line 44. UI just writes the field.                                         |
 | **model** (`model_hint`) | ✅ end-to-end        | `roster.model_hint` → `MOSAIC_AGENT_MODEL` → launcher line 44 `--model`. UI just writes the field.                                                       |
 | **yolo**                 | ❌ new               | Launcher line 44 **hardcodes** `mosaic yolo`. A non-yolo toggle needs a roster `yolo` field → emit `MOSAIC_AGENT_YOLO` → make line 44 conditional.       |
 | **command / channels**   | ❌ new               | `MOSAIC_AGENT_COMMAND` is **consumed** (launcher line ~12) but `generateAgentEnv` does not emit it. Needs a roster `command`/`channels` field → emitted. |
-FCM-M2-001 supplies generated/local parsing, validation, projection, quarantine, and launch-boundary
+**The arc:**
-evidence only. It does not authorize roster CRUD expansion, reconciliation, lifecycle changes, remote
+
-or connector mutation, site canaries, or migration. M3 must establish the local reconcile/lifecycle
+- **A** — `.env` `MOSAIC_AGENT_COMMAND` hatch: manual, ships now, kept safe across upgrades by #632.
-path; M4 separately provides migration preview, canary, and rollback gates.
+- **B** — roster-native launch-config: harness + model are already there; add the **yolo** toggle
  (line-44 conditional) and **command/channels** emission to complete the data model.
 - **webUI** — binds dropdowns/toggles directly to those four roster fields.
 PATH A's `.env` override is the **manual form** of exactly what PATH B makes roster-native and the
 webUI edits — one continuous arc, not three separate features. PATH B is tracked as #636.
--- a/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md
+++ b/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md
@@ -7,8 +7,7 @@ The v2 compiler may not silently accept an unresolved class. Before M1 exits, ev
 below must be either migrated and executable, retained as an explicitly versioned v1 fixture, or
 retired with a replacement/deprecation note. Class resolution must use the existing
 profile/persona/provision baseline-plus-`roles.local` resolver; this inventory does not create a
-parallel resolver. The current executable implementation and per-artifact outcomes are recorded in
+parallel resolver.
 [the disposition evidence](./migration/example-profile-disposition.md).
 ## Examples
--- a/docs/fleet/migration/example-profile-disposition.md
+++ b/docs/fleet/migration/example-profile-disposition.md
@@ -1,52 +0,0 @@
 # Executable Fleet Example, Profile, and Service-Preset Dispositions
 **Issue:** #758 · **Card:** FCM-M1-003 · **Status:** M1 executable disposition evidence
 This document records the executable disposition for every currently shipped fleet YAML artifact.
 The authoritative baseline classification remains the
 [legacy inventory](../LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md). The executable guard is
 `packages/mosaic/src/fleet/example-profile-dispositions.ts`; its test fails if a shipped YAML
 artifact is added, removed, or left without one of the dispositions below.
 ## Disposition rules
 - **Explicit v1 fixture:** the artifact is loaded through the existing v1 roster parser and must
  declare `version: 1`. It remains a compatibility fixture; it is not silently treated as a v2
  roster or given inferred aliases.
 - **Canonical profile:** the artifact is loaded through `loadProfiles`, which uses the shared
  baseline-plus-`roles.local` persona resolver and rejects unreadable or unresolved classes.
 - **Canonical service policy:** the artifact is loaded through the operator-interaction service
  policy reader and provisioned with a generic supplied identity. It validates its runtime, model,
  reasoning, and legacy tool-policy compatibility without hardcoding a product identity.
 No artifact is retired in this card. A later retirement requires both a replacement link and a
 visible deprecation note; the executable guard must then record the new disposition before the
 artifact can be removed.
 ## Shipped artifacts
 | Artifact                             | Disposition              | Executable path                   | Compatibility notes                                                                              |
 | ------------------------------------ | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
 | `examples/coding.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains approved `implementer` and `reviewer` compatibility inputs.                              |
 | `examples/general.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains unresolved `worker` without an inferred canonical role.                                  |
 | `examples/hybrid.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains `implementer`, `reviewer`, and resolver-dependent `researcher`.                          |
 | `examples/local-canary.yaml`         | Explicit v1 fixture      | v1 roster parser                  | Retains the local-tmux canary topology.                                                          |
 | `examples/minimal.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains `canary` without an inferred canonical role.                                             |
 | `examples/operator-interaction.yaml` | Explicit v1 fixture      | v1 roster parser                  | Keeps Tess only as an example instance name; `operator-interaction` remains compatibility input. |
 | `examples/research.yaml`             | Explicit v1 fixture      | v1 roster parser                  | Retains resolver-dependent `researcher` and `analyst`.                                           |
 | `profiles/business.yaml`             | Canonical profile        | shared profile/persona resolver   | Every referenced business class must resolve to a readable contract.                             |
 | `profiles/marketing.yaml`            | Canonical profile        | shared profile/persona resolver   | Every referenced marketing class must resolve to a readable contract.                            |
 | `profiles/personal-assistant.yaml`   | Canonical profile        | shared profile/persona resolver   | No interaction equivalence is inferred.                                                          |
 | `profiles/research.yaml`             | Canonical profile        | shared profile/persona resolver   | Every research class must resolve to a readable contract.                                        |
 | `profiles/software-delivery.yaml`    | Canonical profile        | shared profile/persona resolver   | Retains the governance profile; authority validation remains FCM-M1-002 evidence.                |
 | `services/operator-interaction.yaml` | Canonical service policy | service-policy reader/provisioner | Generic provisioning supplies the instance name; the policy itself never names Tess.             |
 ## Running the guard
 ```bash
 pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts
 ```
 The guard is intentionally limited to shipped assets and validation. It does not generate
 environment files, mutate a roster, reconcile a fleet, migrate an installed roster, or launch an
 agent.
--- a/docs/fleet/reference/generated-env-boundary.md
+++ b/docs/fleet/reference/generated-env-boundary.md
@@ -1,96 +0,0 @@
 # Fleet Generated Environment Boundary
 **Card:** FCM-M2-001 · **Issue:** #758 · **Status:** unreleased/card-local
 The local fleet roster is the desired-state authority. A launch reads a deterministic,
 roster-derived generated projection and an optional strictly data-only local file; neither file is
 a second roster or a command configuration surface.
 ## Paths and ownership
 For agent `<name>` under `<MOSAIC_HOME>/fleet/agents/`:
 | Path                    | Owner                    | Purpose                                                                                                                      |
 | ----------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
 | `<name>.env.generated`  | Mosaic projection writer | Complete deterministic launch data rendered from the authoritative roster.                                                   |
 | `<name>.env.local`      | Operator                 | Optional, constrained local machine data. It cannot shadow generated keys.                                                   |
 | `<name>.env`            | Legacy input only        | Read once during projection generation, then regenerated/relocated or privately quarantined. It is never a launch authority. |
 | `<name>.env.quarantine` | Mosaic quarantine        | Mode-`0600` private record of forbidden legacy input; it is never read by the launcher.                                      |
 The systemd templates do not load either environment file. They invoke Bash with a fixed, cleared
 bootstrap environment; the launcher reads and validates `.env.generated` and `.env.local` itself before
 it queries, creates, or stops an exact tmux session. It does not `source`, `eval`, or execute an
 environment-supplied command. Exact stop derives its socket from the same validated generated projection,
 not from systemd or ambient environment data.
 All projection, local, and quarantine files must be regular files with no group or world permissions.
 The agent environment directory must also be a real, non-symlink private directory; it is validated
 before either environment file is read or tmux is queried. Unsafe paths, symlinks, or permissions fail
 closed. Diagnostics identify only a rule code, key name, and SHA-256 content hash; they never print
 values, credential material, or command text.
 ## Allowed data
 `.env.generated` is complete and ordered exactly as follows:
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
 MOSAIC_AGENT_CLASS=<roster class>
 MOSAIC_AGENT_RUNTIME=<roster runtime>
 MOSAIC_AGENT_MODEL=<roster model hint>
 MOSAIC_AGENT_REASONING=<roster reasoning>
 MOSAIC_AGENT_TOOL_POLICY=<roster tool policy>
 MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
 The generated launch contract supports only `claude`, `codex`, `opencode`, and `pi`. `fleet add`
 uses that same runtime authority and rejects any other runtime before it writes the roster or changes
 projection, local, or quarantine files. The legacy dogfood stub on its separate `mosaic-factory`
 socket remains an observability canary; it has no generated-launch adapter and cannot be added through
 this projection path.
 `.env.local` may contain only these non-secret data keys:
 - `MOSAIC_RUNTIME_BIN`
 - `MOSAIC_HEARTBEAT_RUN_DIR`
 - `MOSAIC_HEARTBEAT_INTERVAL`
 - `MOSAIC_CLAUDE_JSON`
 - `CLAUDE_CONFIG_DIR`
 Local paths must be safe absolute paths and the interval must be a positive integer. Comments,
 quoted/export syntax, duplicate keys, unknown keys, generated-key shadowing, sensitive key names,
 and `MOSAIC_AGENT_COMMAND` are rejected. The launcher derives the only executable command from the
 validated runtime, model, and reasoning data; no arbitrary command compatibility path exists. When a
 Pi runtime writes a fresh `<name>.hb.native` marker, its native heartbeat remains authoritative; the
 shell sidecar resumes its `status=ok` fallback only after that marker is stale or absent.
 ## Legacy disposition
 During projection generation, legacy roster-derived keys are regenerated from the roster. A valid
 allowed local value is relocated to `.env.local`; forbidden, malformed, duplicate, sensitive, and
 unknown legacy entries cause the legacy file to be moved to `.env.quarantine` and are represented by
 sanitized diagnostics. This is deterministic and idempotent after the legacy file has been consumed.
 ## USC interface packet
 This card does not add a USC site file, write a USC roster, or run a site canary. The following is the
 consolidated downstream interface packet. Status is deliberately separated from checkout presence: no
 product release version has been evidenced for this interface set.
 | Interface               | Canonical public path and version                                                                                                                 | Tracker/release status                                                                                                | Downstream limit                                                                              |
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | M1 structural compiler  | `parseRosterV2` in `packages/mosaic/src/fleet/roster-v2.ts`; schema `docs/fleet/reference/roster-v2.schema.json`; roster `version: 2`             | FCM-M1-001 is recorded done, merged as #764 (`aa5b43b`); no released product version is asserted here.                | Parse YAML/JSON and canonicalize a supplied v2 site roster without writes.                    |
 | M1 semantic resolver    | `validateRosterV2Semantics` in `packages/mosaic/src/fleet/roster-v2.ts`; baseline `framework/fleet/roles/` plus `roles.local/`                    | FCM-M1-002 remains `in-progress` in `docs/TASKS.md`; unreleased.                                                      | Reuse the shared resolver only; no parallel role resolver or lifecycle action.                |
 | M1 disposition evidence | `packages/mosaic/src/fleet/example-profile-dispositions.ts`; `docs/fleet/migration/example-profile-disposition.md`; retained fixture `version: 1` | FCM-M1-003 remains `not-started` in `docs/TASKS.md`; unreleased even though these checkout artifacts are inspectable. | Inspect fixture/profile/service disposition evidence only; it is not migration authorization. |
 | M2 generated boundary   | `packages/mosaic/src/fleet/generated-env-boundary.ts`; generated projection contract in this document                                             | FCM-M2-001 card-local and uncommitted; unreleased.                                                                    | Render/write a roster-derived projection; local input is never authority.                     |
 The canonical source remains `<MOSAIC_HOME>/fleet/roster.yaml` for the current local fleet path.
 Generated environment data is a rebuildable projection, not an operator-editable source of membership,
 runtime policy, or lifecycle state.
 **Corrected downstream gates:** M2 supplies only parse/validation/projection evidence and does not
 permit a USC site canary, reconciliation, or lifecycle mutation. M3 must first define and validate the
 canonical local reconcile/lifecycle path. M4 then supplies preview/migration and its separate
 canary/rollback gates; only after those M3 and M4 gates may a site migration or canary be considered.
 This card authorizes none of those actions.
--- a/docs/scratchpads/758-fcm-m1-003-example-profile-dispositions.md
+++ b/docs/scratchpads/758-fcm-m1-003-example-profile-dispositions.md
@@ -1,37 +0,0 @@
 # FCM-M1-003 — Executable example/profile/service-preset dispositions
 - **Task / issue:** FCM-M1-003 / #758
 - **Branch / base:** `test/758-example-profile-dispositions` from `origin/main` `a5e8e554012f27898e035d2882a8e47e1a02fe97`
 - **Objective:** Make every artifact in the M0 legacy disposition inventory executable evidence: it must validate canonically, be explicitly retained as a v1 fixture, or be retired with a replacement/deprecation link.
 - **Scope:** Validation and explicit version/retirement metadata only for shipped examples, profiles, and the operator-interaction service preset. Reuse the central resolver and existing v2 roster compiler.
 - **Out of scope:** Generated environment boundaries, CRUD, reconciliation/apply, migration, live fleet mutation, and `docs/TASKS.md`.
 - **Budget:** 20K card allocation; use focused package tests before full package validation.
 ## Plan
 1. Inventory exact shipped artifacts and existing compiler/resolver/profile tests.
 2. Add failing behavior tests covering all listed artifacts and their documented disposition.
 3. Implement minimal declarative fixture/disposition validation; do not add a role/class resolver.
 4. Run focused and package quality gates; obtain independent code and security review.
 5. Commit, queue-guard, push, open one `main` PR with `Refs #758`.
 ## Progress
 - Intake complete: verified no branch, worktree, or open PR for this card before creating this isolated worktree.
 - Requirements read: FCM PRD, FCM-M1-003 task row, M0 disposition inventory, delivery/QA/documentation guides.
 - TDD: RED recorded with `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` failing because the new module did not exist; GREEN recorded after the minimal guard implementation. The focused suite now has 4 passing tests, including undeclared-artifact and missing-explicit-v1-version denials.
 - Independent review: initial code review found the service policy path was hardcoded; remediation iterates declared `canonical-service-policy` artifacts. Exact-head code review approved and exact-head security review found no issues.
 ## Risks / decisions
 - The M0 inventory permits unresolved legacy roles only when explicitly v1-versioned or retired. Do not infer aliases beyond the three approved by FCM-M1-002.
 - `docs/TASKS.md` is orchestrator-owned and will not be edited.
 ## Verification evidence
 - Focused TDD guard: `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` — PASS (4 tests).
 - Full package suite: `pnpm --filter @mosaicstack/mosaic test` — PASS (51 files, 742 tests).
 - Static gates: `pnpm --filter @mosaicstack/mosaic typecheck`, `pnpm --filter @mosaicstack/mosaic lint`, and `pnpm format:check` — PASS.
 - Diff gate: `git diff --check` — PASS.
 - Exact-head reviews: `codex-code-review.sh --uncommitted` — APPROVE; `codex-security-review.sh --uncommitted` — no findings.
 - Delivery: committed as `9a9ad1a`, pushed after `ci-queue-wait.sh --purpose push`, and opened PR [#770](https://git.mosaicstack.dev/mosaicstack/stack/pulls/770) to `main` with `Refs #758`. `pr-ci-wait.sh -n 770` reported terminal-green Woodpecker pipeline [#1823](https://ci.mosaicstack.dev/repos/47/pipeline/1823/1).
--- a/docs/scratchpads/fcm-m2-001-generated-env-boundary.md
+++ b/docs/scratchpads/fcm-m2-001-generated-env-boundary.md
@@ -1,110 +0,0 @@
 # FCM-M2-001 — Generated Environment Boundary
 - **Issue/card:** #758 / FCM-M2-001
 - **Branch/base:** `feat/758-generated-env-boundary` from `origin/main` `e9c4aa3e8b3780719cd5a43c0ef3f37fc70de666`
 - **Budget assumption:** 30K-card budget; implement only the deterministic generated/local environment boundary and its launch-chain/docs/tests.
 ## Objective
 Replace the generic fleet agent `.env` authority/merge path with a deterministic roster-derived `<agent>.env.generated` projection and strict, data-only `<agent>.env.local`. The roster remains the desired-state authority. Reject bad input before the launcher creates a tmux session; never print sensitive or privileged-command values.
 ## Scope and non-goals
 - In scope: deterministic render/write, strict generated/local parse rules, legacy `.env` disposition/quarantine, systemd/launcher boundary, permission/path checks, focused fail-closed tests, operator/reference documentation, USC interface evidence.
 - Excluded: roster CRUD/mutation, v2 roster schema changes, lifecycle/reconcile/apply behavior, migration/canary rollout, connectors, remote surfaces, live-fleet actions, and M2-002.
 ## Plan
 1. Add red tests for generated-key shadowing, malformed/duplicate/unknown/command/sensitive input, no-value diagnostics, deterministic/idempotent projection, secure file modes, and legacy disposition.
 2. Implement a pure strict environment contract plus atomic projection/quarantine helper.
 3. Replace the generic `.env` writer/merge path and systemd reference with `.env.generated` + `.env.local` ownership.
 4. Make the shell launcher parse the files without `source`/`eval`, reject unsafe input before tmux creation, and construct only the roster-derived runtime command.
 5. Add operator/reference documentation with the requested USC M1 interface evidence and M2–M4 gate statement.
 6. Run focused/package/root gates and audit the USC interface packet. Per continuation scope, stop before review, commit, push, PR, or live mutation.
 ## Initial evidence
 - No existing owner: target worktree path absent; no target local/remote branch; `pr-list.sh -s open` returned no open PRs.
 - M1 compiler/API/docs and executable disposition evidence are present at the assigned base.
 - Existing launch chain writes `fleet/agents/<agent>.env`, preserves arbitrary legacy lines via `mergeAgentEnv`, sources `MOSAIC_AGENT_COMMAND`, and executes it through `bash -c`; all are M2 remediation targets.
 - `~/.config/mosaic/guides/SECURITY.md` is absent. Read the available security-review role contract and the vault/secrets guide instead.
 ## Verification log
 ### Continuation (2026-07-14)
 - Preserved the inherited 14-file delta; no reset, stash, rebase, roster mutation, lifecycle action,
  live-fleet action, commit, push, or PR action was performed.
 - Focused gates passed:
  - `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` — 1 file, 10 tests passed.
  - `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` — passed.
  - `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` — passed.
  - `pnpm --dir packages/mosaic test -- src/commands/fleet.spec.ts` — 1 file, 192 tests passed.
 - Package gates passed before final documentation/format follow-up:
  - `pnpm --dir packages/mosaic typecheck` — passed.
  - `pnpm --dir packages/mosaic lint` — passed.
  - `pnpm --dir packages/mosaic test` — 52 files, 752 tests passed.
 - `pnpm format:check` initially failed only for the new boundary reference and generated-boundary
  TypeScript files; targeted Prettier normalization was applied. A final `pnpm format:check` passed.
 - USC packet audit: the M1 structural compiler is `parseRosterV2` with roster `version: 2`; the
  semantic resolver is `validateRosterV2Semantics`; disposition artifacts retain `version: 1` fixture
  evidence. `docs/TASKS.md` records M1-001 done, M1-002 in-progress, and M1-003 not-started; no
  product release version is claimed. The packet now distinguishes these statuses from checkout
  artifact presence and states the M2 → M3 → M4 downstream gates.
 ## Review remediation (2026-07-14)
 - **Blocker 1 red-first:** Added a launcher reproducer with a `0777` `fleet/agents` parent and a private generated file. Before implementation, `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` failed: `FAIL: generated file under a world-writable parent was accepted`. The failure occurred after the launch path reached fake tmux, proving the parent was not validated.
 - **Blocker 2 red-first:** Added a `symlink()` projection-directory reproducer that preloads generated/local/quarantine/legacy target files and asserts no target mutation. Before implementation, `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` failed the new test because the existing writer followed the `agentEnvDir` symlink and parsed its target legacy input (`expected /unsafe-directory/i`, received `code=malformed-line`). The initial test-only missing `mkdir` import was corrected before recording this behavior failure.
 - **Blocker 3 red-first:** Added fresh/stale/absent native-heartbeat regression coverage. Before implementation, an isolated fake-tmux launcher reproducer with a fresh `<agent>.hb.native` marker failed `FAIL: fresh native heartbeat was overwritten`; the existing sidecar immediately replaced native `status=busy`/`model` content.
 - **Remediation result:** The launcher now rejects a group/world-accessible or symlinked `fleet/agents` parent before an environment read or tmux call. The projection writer uses `lstat` before chmod/write processing and rejects a symlinked directory without creating generated/local/quarantine files or deleting legacy input. The heartbeat sidecar defers to a fresh non-symlink native marker and falls back when stale/absent. Focused green evidence before independent review: `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` and `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` (11 tests) passed.
 - **Independent-review follow-up red-first:** Codex code review returned one blocker and security review one medium CWE-732 finding: the writer repaired an already `0777` directory with `chmod` before trusting its contents. Added a reproducer with a safe local file beneath an existing `0777` directory. Before the follow-up fix, `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` failed because the promise resolved and wrote `coder0.env.generated` instead of rejecting.
 - **Independent-review remediation:** Existing directories now pass non-following private-directory validation before any read or chmod; only a directory created in this call is normalized to `0700`. The fleet-add test fixture now creates its simulated trusted `fleet/agents` boundary at `0700`; this corrects fixture setup to match the new required contract rather than weakening the rejection assertion. Focused reruns passed: generated-boundary 12 tests, launcher boundary suite, and fleet suite 192 tests.
 - **Final verification before re-review:** Launcher + systemd suites passed; package suite passed (52 files, 754 tests); package lint/typecheck, root typecheck (42 tasks), format check, and diff check passed. The rerun code review still reports a tmux command-arity blocker, and the security rerun reports systemd `EnvironmentFile` pre-validation injection findings for both agent units. These were discovered after the specified three-remediation scope; no additional source changes were made. Independent review therefore remains `REQUEST CHANGES` despite the requested three fixes passing their behavioral suites.
 ## Systemd pre-validation remediation (2026-07-14)
 - **Red-first:** Updated the fleet unit contract to reject any `EnvironmentFile=` projection preload, require a cleared bootstrap environment, and require a validated exact-stop path. Before implementation, `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` failed: `FAIL: agent units must not preload projections before strict parsing`.
 - **Red-first parser/stop coverage:** Added interaction-wrapper and exact-stop cases to the launcher boundary suite. Before implementation, `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` failed: `FAIL: interaction did not use shared strict parser first`, because the interaction wrapper consumed inherited environment before projection validation.
 - **Focused green:** Both unit templates now use `env -i` with fixed `HOME`, agent instance, and PATH; neither has `Environment=`/`EnvironmentFile=`. The interaction wrapper delegates to `start-agent-session.sh --interaction`, so strict generated/local parsing precedes pinned Pi profile checks. `--stop` reuses the strict generated parser before exact `=<agent>` socket/session termination. Passed: systemd unit suite, launcher boundary suite (including malformed interaction, pinned profile, and ambient-socket stop cases), and 210 focused TypeScript tests.
 - **Final verification:** `pnpm --dir packages/mosaic test` passed (52 files, 754 tests); package lint/typecheck, root typecheck (42 tasks), format/diff, and shell syntax checks passed. Security review passed with no findings. Code review repeated the previously refuted tmux argv concern and a pre-existing Claude trust-lock suggestion; per the assigned narrow follow-up, no tmux or unrelated trust-path change was made.
 ## Risks and next review
 - This card is uncommitted and unreleased. The canonical tracker still records its dependencies as
  M1-002 in progress and M1-003 not started; this continuation does not reinterpret those task states.
 - Final post-documentation checks passed: `pnpm --dir packages/mosaic typecheck`,
  `pnpm --dir packages/mosaic lint`, `pnpm --dir packages/mosaic test` (52 files, 752 tests),
  `pnpm typecheck` (42 Turbo tasks), and `pnpm format:check`.
 - Obtain independent code and security review of the complete delta next. Do not run commit, push,
  PR, or live-fleet commands in this continuation.
 ## Fresh-install directory remediation (2026-07-14)
 - **Objective:** Remediate only the fresh-install path where `installFleet` created `fleet/agents`
  with host-umask permissions before the boundary writer correctly rejected it.
 - **Plan:** Add a real `fleet install --no-enable` integration reproducer; prove red; let the
  existing boundary writer own directory creation; run focused and full gates. No commit, push,
  PR, review disposition, or live-fleet action.
 - **Red evidence:** Before the one-line remediation,
  `pnpm --dir packages/mosaic test -- src/commands/fleet.spec.ts` failed the new test with
  `AgentEnvBoundaryError: code=unsafe-permissions` at `ensurePrivateProjectionDirectory`, after
  `installFleet` pre-created the directory.
 - **Change:** Removed only the recursive `mkdir(activePaths.agentEnvDir)` in `installFleet`.
  `writeAgentEnvironmentProjection` remains the sole creator and retains its existing `lstat`,
  private-directory, symlink, and existing-unsafe-directory fail-closed checks.
 - **Focused green:** `pnpm --dir packages/mosaic test -- src/commands/fleet.spec.ts` — 193 tests
  passed. The new integration executes a fresh `fleet install --no-enable`, asserts a real
  non-symlink `0700` directory and a `0600` generated projection. Existing unsafe-directory
  coverage remains in `generated-env-boundary.spec.ts` and asserts no chmod repair/no generated
  file write.
 - **Full gates green:** generated-boundary 12 tests; launcher and systemd suites; package
  typecheck/lint and 52 files / 755 tests; root typecheck (42 tasks), lint, format, diff check,
  and root test (42 tasks) all passed.
 - **Independent review:** The complete inherited uncommitted delta still has Codex `REQUEST CHANGES`
  findings outside this narrow fix (tmux command arity and Claude trust-lock regression), plus a
  security-review medium finding on unvalidated writable ancestor directories. No out-of-scope
  source changes were made.
 - **Risk:** The writer's existing create-then-validate sequence is relied on for the creation
  boundary; a concurrent substitution causes fail-closed validation rather than repair. The
  review findings above remain residual risks for the complete card delta.
--- a/packages/mosaic/framework/fleet/README.md
+++ b/packages/mosaic/framework/fleet/README.md
@@ -9,8 +9,7 @@ package, normally at:
 ```
 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
+default tmux server.
 rebuildable projections, never a second source of configuration.
 ## Examples
@@ -32,17 +31,6 @@ The installed `tools/fleet/print-interaction-effective-policy.sh` prints only
 the resolved name, runtime, model, reasoning, and tool policy. It never reads
 or prints credential variables.
 ## Generated agent environment boundary
 `mosaic fleet install` writes a private deterministic projection at
 `~/.config/mosaic/fleet/agents/<agent>.env.generated`. It may relocate only approved local machine
 data to `<agent>.env.local`; generated keys, arbitrary commands, secret-like keys, duplicate keys,
 unknown keys, and unsafe permissions fail before a tmux session is created. Legacy `.env` input is
 regenerated, relocated, or quarantined and is not a launch authority.
 See [`docs/fleet/reference/generated-env-boundary.md`](../../../../docs/fleet/reference/generated-env-boundary.md)
 for allowed local keys and the USC downstream interface evidence.
 Initialize a roster:
 ```bash
--- a/packages/mosaic/framework/systemd/user/README.md
+++ b/packages/mosaic/framework/systemd/user/README.md
@@ -24,56 +24,45 @@ The agent template calls:
 which starts or reuses a tmux session on `MOSAIC_TMUX_SOCKET`.
-## Generated environment and local data
+## Local customization
-The roster-derived projection is written outside the package at:
+Per-agent overrides live outside the package in:
 ```text
-~/.config/mosaic/fleet/agents/<agent>.env.generated
+~/.config/mosaic/fleet/agents/<agent>.env
 ```
-Systemd does not read either environment file. It starts the launcher with a fixed cleared bootstrap
+Example:
 environment; before it creates, queries, or stops an exact agent tmux session, `start-agent-session.sh`
 strictly parses the generated projection and the optional local data file:
-```text
+```dotenv
-~/.config/mosaic/fleet/agents/<agent>.env.local
+MOSAIC_TMUX_SOCKET=mosaic-fleet
 MOSAIC_AGENT_RUNTIME=claude
 MOSAIC_AGENT_WORKDIR=$HOME/src/your-project
 # Optional escape hatch for PoC/canary agents:
 # MOSAIC_AGENT_COMMAND=mosaic yolo claude
 ```
 The local file may contain only safe machine-specific data (`MOSAIC_RUNTIME_BIN`, heartbeat paths or
 interval, and Claude configuration paths). It cannot override roster-derived keys, carry a command,
 or contain secret-like/unknown keys. Both files must be private regular files. Do not hand-edit the
 generated projection; update the roster and regenerate it instead. A legacy `<agent>.env` is
 consumed only for regeneration, strict relocation, or private quarantine and is never launch input.
 See `docs/fleet/reference/generated-env-boundary.md` for the full contract.
 ## Manual canary sequence
 Use the roster and the supported installer; do not pre-create the agent environment directory or
 edit a generated projection. `mosaic fleet install` validates the roster, installs the units and
 helpers, and writes private roster-derived projections before any service is started.
 ```bash
-# Create a site-owned canary roster. Inspect an existing roster before using --force.
+mkdir -p ~/.config/systemd/user ~/.config/mosaic/tools/fleet ~/.config/mosaic/fleet/agents
-mosaic fleet init --profile minimal --write
+cp packages/mosaic/framework/systemd/user/mosaic-*.service ~/.config/systemd/user/
-mosaic fleet install
+cp packages/mosaic/framework/tools/fleet/*.sh ~/.config/mosaic/tools/fleet/
 chmod +x ~/.config/mosaic/tools/fleet/*.sh
 systemctl --user daemon-reload
-mosaic fleet start canary-pi
+systemctl --user start mosaic-tmux-holder.service
 systemctl --user start mosaic-agent@canary.service
 tmux -L mosaic-fleet ls
 ```
-For an operator-interaction service, first put `<agent-name>` in the roster with the pinned Pi
+# For an operator-interaction service, the roster/env identity selects the
-runtime, model, reasoning, and `operator-interaction` tool policy. Re-run `mosaic fleet install` after
+# generic unit instance; no service source is renamed for an instance.
 that roster change so it writes `<agent-name>.env.generated`; ambient `MOSAIC_AGENT_*` values are not
 launch authority. The generic unit instance uses that generated identity, and no service source is
 renamed for an instance:
 ```bash
 mosaic fleet install
 systemctl --user daemon-reload
 systemctl --user start mosaic-interaction-agent@<agent-name>.service
-~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh <agent-name>
+MOSAIC_AGENT_NAME=<agent-name> \
 MOSAIC_AGENT_RUNTIME=pi \
 MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol \
 MOSAIC_AGENT_REASONING=high \
 MOSAIC_AGENT_TOOL_POLICY=operator-interaction \
  ~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh
 ```
 Do not use `tmux kill-server` without `-L mosaic-fleet`; this pattern is meant
--- a/packages/mosaic/framework/systemd/user/mosaic-agent@.service
+++ b/packages/mosaic/framework/systemd/user/mosaic-agent@.service
@@ -7,13 +7,16 @@ PartOf=mosaic-tmux-holder.service
 [Service]
 Type=oneshot
 # Remove loader and noninteractive-shell controls before ExecStart loads env.
 UnsetEnvironment=LD_PRELOAD BASH_ENV ENV
 RemainAfterExit=yes
-# Never preload the projection. The launcher starts from a fixed minimal
+# No default MOSAIC_TMUX_SOCKET: an absent roster socket means the literal
-# environment and strictly validates generated/local data before tmux effects.
+# default tmux socket (no -L). The per-agent .env sets it when the roster names
-ExecStart=/usr/bin/env -i HOME=%h MOSAIC_AGENT_NAME=%i PATH=/usr/bin:/bin /bin/bash --noprofile --norc %h/.config/mosaic/tools/fleet/start-agent-session.sh %i
+# one; otherwise it stays unset and start-agent-session.sh uses the default socket.
-ExecStop=-/usr/bin/env -i HOME=%h MOSAIC_AGENT_NAME=%i PATH=/usr/bin:/bin /bin/bash --noprofile --norc %h/.config/mosaic/tools/fleet/start-agent-session.sh --stop %i
+Environment=MOSAIC_AGENT_NAME=%i
 Environment=MOSAIC_AGENT_RUNTIME=pi
 Environment=MOSAIC_AGENT_WORKDIR=%h
 EnvironmentFile=-%h/.config/mosaic/fleet/agents/%i.env
 ExecStart=/bin/bash %h/.config/mosaic/tools/fleet/start-agent-session.sh %i
 ExecStop=-/bin/bash -lc 'if [ -n "${MOSAIC_TMUX_SOCKET:-}" ]; then tmux -L "$MOSAIC_TMUX_SOCKET" kill-session -t "=%i"; else tmux kill-session -t "=%i"; fi'
 [Install]
 WantedBy=default.target
--- a/packages/mosaic/framework/systemd/user/mosaic-interaction-agent@.service
+++ b/packages/mosaic/framework/systemd/user/mosaic-interaction-agent@.service
@@ -7,13 +7,11 @@ PartOf=mosaic-tmux-holder.service
 [Service]
 Type=oneshot
 # Remove loader and noninteractive-shell controls before ExecStart loads env.
 UnsetEnvironment=LD_PRELOAD BASH_ENV ENV
 RemainAfterExit=yes
-# The interaction wrapper delegates to the shared strict parser before pinned
+Environment=MOSAIC_AGENT_NAME=%i
-# profile checks; no projection data reaches Bash through systemd.
+EnvironmentFile=%h/.config/mosaic/fleet/agents/%i.env
-ExecStart=/usr/bin/env -i HOME=%h MOSAIC_AGENT_NAME=%i PATH=/usr/bin:/bin /bin/bash --noprofile --norc %h/.config/mosaic/tools/fleet/start-interaction-service.sh %i
+ExecStart=/bin/bash %h/.config/mosaic/tools/fleet/start-interaction-service.sh %i
-ExecStop=-/usr/bin/env -i HOME=%h MOSAIC_AGENT_NAME=%i PATH=/usr/bin:/bin /bin/bash --noprofile --norc %h/.config/mosaic/tools/fleet/start-agent-session.sh --stop %i
+ExecStop=-/bin/bash -lc 'if [ -n "${MOSAIC_TMUX_SOCKET:-}" ]; then tmux -L "$MOSAIC_TMUX_SOCKET" kill-session -t "=%i"; else tmux kill-session -t "=%i"; fi'
 [Install]
 WantedBy=default.target
--- a/packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service
+++ b/packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service
@@ -6,11 +6,10 @@ After=default.target
 [Service]
 Type=oneshot
 RemainAfterExit=yes
-# The holder owns the tmux server, so clear loader, shell-control, and stale
+Environment=MOSAIC_TMUX_SOCKET=mosaic-fleet
-# manager/session variables before the server process starts.
+Environment=MOSAIC_TMUX_HOLDER=_holder
-UnsetEnvironment=LD_PRELOAD BASH_ENV ENV
+ExecStart=/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" has-session -t "=${MOSAIC_TMUX_HOLDER}:0.0" 2>/dev/null || tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$MOSAIC_TMUX_HOLDER" "while true; do sleep 3600; done"'
-ExecStart=/usr/bin/env -i HOME=%h PATH=/usr/bin:/bin MOSAIC_TMUX_SOCKET=mosaic-fleet MOSAIC_TMUX_HOLDER=_holder /bin/bash --noprofile --norc %h/.config/mosaic/tools/fleet/start-tmux-holder.sh
+ExecStop=-/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" kill-server'
 ExecStop=-/usr/bin/env -i HOME=%h PATH=/usr/bin:/bin MOSAIC_TMUX_SOCKET=mosaic-fleet /bin/bash --noprofile --norc -c 'tmux -L "$MOSAIC_TMUX_SOCKET" kill-server'
 [Install]
 WantedBy=default.target
--- a/packages/mosaic/framework/systemd/user/test-fleet-units.sh
+++ b/packages/mosaic/framework/systemd/user/test-fleet-units.sh
@@ -5,8 +5,6 @@ SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
 HOLDER="$SCRIPT_DIR/mosaic-tmux-holder.service"
 AGENT="$SCRIPT_DIR/mosaic-agent@.service"
 INTERACTION="$SCRIPT_DIR/mosaic-interaction-agent@.service"
 HOLDER_START="$SCRIPT_DIR/../../tools/fleet/start-tmux-holder.sh"
 START_AGENT="$SCRIPT_DIR/../../tools/fleet/start-agent-session.sh"
 fail() {
  echo "FAIL: $*" >&2
@@ -16,40 +14,16 @@ fail() {
 [ -f "$HOLDER" ] || fail "missing mosaic-tmux-holder.service"
 [ -f "$AGENT" ] || fail "missing mosaic-agent@.service"
 [ -f "$INTERACTION" ] || fail "missing mosaic-interaction-agent@.service"
 [ -x "$HOLDER_START" ] || fail "missing executable start-tmux-holder.sh"
 [ -x "$START_AGENT" ] || fail "missing executable start-agent-session.sh"
 grep -qF 'ExecStart=' "$HOLDER" || fail "holder has no ExecStart"
 grep -qF 'tmux -L' "$HOLDER" || fail "holder does not use named tmux socket"
 grep -qF '_holder' "$HOLDER" || fail "holder session is not explicit"
 grep -qF 'UnsetEnvironment=LD_PRELOAD BASH_ENV ENV' "$HOLDER" || \
  fail "holder does not remove loader and shell-control variables"
 grep -qF 'ExecStart=/usr/bin/env -i HOME=%h PATH=/usr/bin:/bin MOSAIC_TMUX_SOCKET=mosaic-fleet MOSAIC_TMUX_HOLDER=_holder /bin/bash --noprofile --norc %h/.config/mosaic/tools/fleet/start-tmux-holder.sh' "$HOLDER" || \
  fail "holder does not clear manager environment before starting tmux"
 grep -qF 'ExecStop=-/usr/bin/env -i HOME=%h PATH=/usr/bin:/bin MOSAIC_TMUX_SOCKET=mosaic-fleet /bin/bash --noprofile --norc -c' "$HOLDER" || \
  fail "holder stop does not clear manager environment"
 if grep -qF -- '/bin/bash -lc' "$HOLDER"; then
  fail "holder must not start tmux through a login shell"
 fi
 grep -qF 'Requires=mosaic-tmux-holder.service' "$AGENT" || fail "agent does not require holder"
 grep -qF 'start-agent-session.sh' "$AGENT" || fail "agent unit does not call start-agent-session.sh"
-if grep -qE '^Environment(File)?=' "$AGENT" "$INTERACTION"; then
+grep -qF 'kill-session -t "=%i"' "$AGENT" || fail "agent stop does not exact-match its session"
  fail "agent units must not accept ambient or projection environment before strict parsing"
 fi
 grep -qF 'UnsetEnvironment=LD_PRELOAD BASH_ENV ENV' "$AGENT" || \
  fail "agent unit does not remove loader and shell-control variables"
 grep -qF 'UnsetEnvironment=LD_PRELOAD BASH_ENV ENV' "$INTERACTION" || \
  fail "interaction unit does not remove loader and shell-control variables"
 grep -qF 'ExecStart=/usr/bin/env -i HOME=%h MOSAIC_AGENT_NAME=%i PATH=/usr/bin:/bin /bin/bash --noprofile --norc' "$AGENT" || \
  fail "agent unit does not clear bootstrap environment before strict parsing"
 grep -qF 'start-agent-session.sh --stop %i' "$AGENT" || \
  fail "agent stop does not use the validated exact-stop path"
 grep -qF 'Requires=mosaic-tmux-holder.service' "$INTERACTION" || fail "interaction service does not require holder"
-grep -qF 'ExecStart=/usr/bin/env -i HOME=%h MOSAIC_AGENT_NAME=%i PATH=/usr/bin:/bin /bin/bash --noprofile --norc' "$INTERACTION" || \
+grep -qF 'EnvironmentFile=%h/.config/mosaic/fleet/agents/%i.env' "$INTERACTION" || fail "interaction service does not require per-agent config"
-  fail "interaction unit does not clear bootstrap environment before strict parsing"
+grep -qF 'start-interaction-service.sh %i' "$INTERACTION" || fail "interaction service does not validate before startup"
 grep -qF 'start-interaction-service.sh %i' "$INTERACTION" || fail "interaction service does not use shared strict parsing"
 grep -qF 'start-agent-session.sh --stop %i' "$INTERACTION" || \
  fail "interaction stop does not use the validated exact-stop path"
 if command -v systemd-analyze >/dev/null 2>&1; then
  systemd-analyze verify --user "$HOLDER" "$AGENT" "$INTERACTION" >/tmp/mosaic-fleet-systemd-verify.log 2>&1 || {
@@ -58,102 +32,4 @@ if command -v systemd-analyze >/dev/null 2>&1; then
  }
 fi
 # Real isolated socket regression: a preexisting server with an LD_PRELOAD
 # constructor marker must fail closed, while a fresh named server is created.
 if command -v tmux >/dev/null 2>&1 && command -v cc >/dev/null 2>&1; then
  TEST_ROOT=$(mktemp -d)
  TEST_SOCKET="mosaic-holder-test-$$"
  trap 'tmux -L "$TEST_SOCKET" kill-server >/dev/null 2>&1 || true; rm -rf "$TEST_ROOT"' EXIT
  MARKER="$TEST_ROOT/loader-marker"
  LIBRARY="$TEST_ROOT/marker.so"
  HOLDER_HOME="$TEST_ROOT/holder-home"
  mkdir -p "$HOLDER_HOME/.config/mosaic/fleet/run"
  chmod 700 "$HOLDER_HOME/.config" "$HOLDER_HOME/.config/mosaic" \
    "$HOLDER_HOME/.config/mosaic/fleet" "$HOLDER_HOME/.config/mosaic/fleet/run"
  printf '123e4567-e89b-12d3-a456-426614174000\n' > \
    "$HOLDER_HOME/.config/mosaic/fleet/run/holder-owner"
  chmod 600 "$HOLDER_HOME/.config/mosaic/fleet/run/holder-owner"
  cat > "$TEST_ROOT/marker.c" <<'EOF'
 #include <fcntl.h>
 #include <stdlib.h>
 #include <unistd.h>
 __attribute__((constructor)) static void mark_loader(void) {
  const char *path = getenv("MOSAIC_LOADER_MARKER");
  if (path != NULL) {
    int fd = open(path, O_WRONLY | O_CREAT | O_APPEND, 0600);
    if (fd >= 0) { write(fd, "loaded\\n", 7); close(fd); }
  }
 }
 EOF
  cc -shared -fPIC -o "$LIBRARY" "$TEST_ROOT/marker.c"
  MOSAIC_LOADER_MARKER="$MARKER" LD_PRELOAD="$LIBRARY" \
    tmux -L "$TEST_SOCKET" new-session -d -s _holder 'sleep 60'
  [ -s "$MARKER" ] || fail "contaminated fixture did not execute loader constructor"
  server_pid=$(tmux -L "$TEST_SOCKET" display-message -p '#{pid}')
  : > "$MARKER"
  if /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin \
    MOSAIC_TMUX_SOCKET="$TEST_SOCKET" MOSAIC_TMUX_HOLDER=_holder "$HOLDER_START" \
    >"$TEST_ROOT/holder.out" 2>&1; then
    fail "holder adopted contaminated named server"
  fi
  grep -qF 'global environment does not match the owned-server contract' "$TEST_ROOT/holder.out" || \
    fail "holder did not report contaminated server environment"
  [ "$(tmux -L "$TEST_SOCKET" display-message -p '#{pid}')" = "$server_pid" ] || \
    fail "holder replaced a contaminated server instead of failing closed"
  [ ! -s "$MARKER" ] || fail "holder execution triggered a contaminated loader"
  # Agent validation must reject the same unmanaged server without cleaning its
  # global environment or adding a managed session.
  AGENT_HOME="$HOLDER_HOME/.config/mosaic"
  AGENT_NAME=loader-safe
  AGENT_WORKDIR="$AGENT_HOME/work"
  AGENT_BIN="$TEST_ROOT/agent-bin"
  mkdir -p "$AGENT_HOME/fleet/agents" "$AGENT_WORKDIR" "$AGENT_BIN"
  chmod 700 "$AGENT_HOME/fleet/agents"
  cat > "$AGENT_HOME/fleet/agents/$AGENT_NAME.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$AGENT_NAME
 MOSAIC_AGENT_CLASS=code
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=
 MOSAIC_AGENT_REASONING=
 MOSAIC_AGENT_TOOL_POLICY=code
 MOSAIC_AGENT_WORKDIR=$AGENT_WORKDIR
 MOSAIC_TMUX_SOCKET=$TEST_SOCKET
 EOF
  printf 'MOSAIC_RUNTIME_BIN=%s\n' "$AGENT_BIN" > "$AGENT_HOME/fleet/agents/$AGENT_NAME.env.local"
  chmod 600 "$AGENT_HOME/fleet/agents/$AGENT_NAME.env.generated" \
    "$AGENT_HOME/fleet/agents/$AGENT_NAME.env.local"
  cat > "$AGENT_BIN/mosaic" <<'EOF'
 #!/bin/sh
 sleep 30
 EOF
  chmod 700 "$AGENT_BIN/mosaic"
  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" \
    "$START_AGENT" "$AGENT_NAME" >"$TEST_ROOT/agent.out" 2>&1; then
    fail "agent launcher adopted contaminated named server"
  fi
  [ "$(tmux -L "$TEST_SOCKET" display-message -p '#{pid}')" = "$server_pid" ] || \
    fail "agent launcher changed unmanaged server PID"
  [ "$(tmux -L "$TEST_SOCKET" show-environment -g | sort)" = "$server_environment_before" ] || \
    fail "agent launcher changed unmanaged global environment"
  [ "$(tmux -L "$TEST_SOCKET" list-sessions | sort)" = "$server_sessions_before" ] || \
    fail "agent launcher changed unmanaged sessions"
  tmux -L "$TEST_SOCKET" kill-server
  /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin \
    MOSAIC_TMUX_SOCKET="$TEST_SOCKET" MOSAIC_TMUX_HOLDER=_holder "$HOLDER_START"
  tmux -L "$TEST_SOCKET" has-session -t '=_holder:0.0' || fail "fresh holder was not created"
  if tmux -L "$TEST_SOCKET" show-environment -g LD_PRELOAD 2>/dev/null | grep -q '^LD_PRELOAD='; then
    fail "fresh holder retained LD_PRELOAD"
  fi
  /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin MOSAIC_HOME="$AGENT_HOME" \
    "$START_AGENT" "$AGENT_NAME"
  tmux -L "$TEST_SOCKET" has-session -t "=$AGENT_NAME:0.0" || \
    fail "agent did not launch on a valid owned server"
  tmux -L "$TEST_SOCKET" kill-server
  trap - EXIT
  rm -rf "$TEST_ROOT"
 fi
 echo "ok - fleet systemd unit templates"
--- a/packages/mosaic/framework/tools/fleet/start-agent-session.sh
+++ b/packages/mosaic/framework/tools/fleet/start-agent-session.sh
@@ -1,207 +1,39 @@
 #!/usr/bin/env bash
 set -euo pipefail
-# FCM-M2-001 boundary: only a roster-derived .env.generated projection and a
+AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}}
-# separately parsed data-only .env.local can influence launch. Never source an
+# Absent socket ⇒ the LITERAL default tmux socket (no -L). The roster's
-# environment file and never accept a command string from either file.
+# socket_name is honored when set; absent never silently becomes mosaic-fleet
 # (spawn stays consistent with the onboarding cheat-sheet + fleet ps observe).
 MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-}
 MOSAIC_AGENT_RUNTIME=${MOSAIC_AGENT_RUNTIME:-pi}
 MOSAIC_AGENT_MODEL=${MOSAIC_AGENT_MODEL:-}
 MOSAIC_AGENT_REASONING=${MOSAIC_AGENT_REASONING:-}
 MOSAIC_AGENT_WORKDIR=${MOSAIC_AGENT_WORKDIR:-$HOME}
 MOSAIC_AGENT_COMMAND=${MOSAIC_AGENT_COMMAND:-}
 MOSAIC_HEARTBEAT_RUN_DIR=${MOSAIC_HEARTBEAT_RUN_DIR:-${MOSAIC_HOME:-$HOME/.config/mosaic}/fleet/run}
 MOSAIC_HEARTBEAT_INTERVAL=${MOSAIC_HEARTBEAT_INTERVAL:-15}
-MODE=launch
+if [ -z "$AGENT_NAME" ]; then
-case "${1:-}" in
+  echo "ERROR: agent name argument or MOSAIC_AGENT_NAME is required" >&2
-  --stop)
+  exit 64
-    MODE=stop
+fi
-    AGENT_NAME=${2:-}
+
 case "$MOSAIC_AGENT_REASONING" in
  ''|low|medium|high) ;;
  *)
    echo "ERROR: MOSAIC_AGENT_REASONING must be low, medium, or high" >&2
    exit 64
    ;;
  --interaction)
    MODE=interaction
    AGENT_NAME=${2:-}
    ;;
  *) AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}} ;;
 esac
 MOSAIC_HOME=${MOSAIC_HOME:-$HOME/.config/mosaic}
 fail() {
  echo "ERROR: $*" >&2
  exit 64
 }
 hash_value() {
  printf '%s' "$1" | sha256sum | awk '{print $1}'
 }
 fail_env() {
  local code="$1"
  local key="$2"
  local value="$3"
  echo "ERROR: agent environment rejected: code=${code} key=${key} sha256=$(hash_value "$value")" >&2
  exit 64
 }
 safe_agent_name() {
  [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]*$ ]]
 }
 safe_policy_name() {
  [[ "$1" =~ ^[a-z][a-z0-9-]*$ ]]
 }
 safe_path() {
  [[ "$1" == /* ]] || return 1
  [[ "$1" != *".."* ]] || return 1
  [[ ! "$1" =~ [[:space:]\"\'\`\$\\\;\|\&\<\>\(\)\{\}] ]]
 }
 assert_private_regular_file() {
  local file="$1"
  [ -f "$file" ] && [ ! -L "$file" ] || fail_env unsafe-file '(file)' "$file"
  local mode
  mode=$(stat -c '%a' -- "$file") || fail_env unsafe-file '(file)' "$file"
  (( (8#$mode & 8#077) == 0 )) || fail_env unsafe-permissions '(file)' "$file"
 }
 assert_managed_directory() {
  local directory="$1"
  [ -d "$directory" ] && [ ! -L "$directory" ] || fail_env unsafe-directory '(directory)' "$directory"
  local mode
  mode=$(stat -c '%a' -- "$directory") || fail_env unsafe-directory '(directory)' "$directory"
  (( (8#$mode & 8#022) == 0 )) || fail_env unsafe-permissions '(directory)' "$directory"
 }
 assert_private_directory() {
  local directory="$1"
  assert_managed_directory "$directory"
  local mode
  mode=$(stat -c '%a' -- "$directory") || fail_env unsafe-directory '(directory)' "$directory"
  (( (8#$mode & 8#077) == 0 )) || fail_env unsafe-permissions '(directory)' "$directory"
 }
 [ -n "$AGENT_NAME" ] || fail "agent name argument or MOSAIC_AGENT_NAME is required"
 safe_agent_name "$AGENT_NAME" || fail_env unsafe-agent-name MOSAIC_AGENT_NAME "$AGENT_NAME"
 safe_path "$MOSAIC_HOME" || fail_env unsafe-path MOSAIC_HOME "$MOSAIC_HOME"
 FLEET_DIR="$MOSAIC_HOME/fleet"
 AGENT_ENV_DIR="$FLEET_DIR/agents"
 assert_managed_directory "$MOSAIC_HOME"
 assert_managed_directory "$FLEET_DIR"
 assert_private_directory "$AGENT_ENV_DIR"
 GENERATED_ENV="$AGENT_ENV_DIR/$AGENT_NAME.env.generated"
 LOCAL_ENV="$AGENT_ENV_DIR/$AGENT_NAME.env.local"
 declare -A GENERATED_VALUES=()
 declare -A LOCAL_VALUES=()
 declare -A SEEN_KEYS=()
 is_sensitive_key() {
  [[ "$1" =~ (API[_-]?KEY|AUTH|CREDENTIAL|PASSWORD|PRIVATE|SECRET|TOKEN) ]]
 }
 is_generated_key() {
  case "$1" in
    MOSAIC_AGENT_NAME|MOSAIC_AGENT_CLASS|MOSAIC_AGENT_RUNTIME|MOSAIC_AGENT_MODEL|MOSAIC_AGENT_REASONING|MOSAIC_AGENT_TOOL_POLICY|MOSAIC_AGENT_WORKDIR|MOSAIC_TMUX_SOCKET) return 0 ;;
    *) return 1 ;;
  esac
 }
 is_local_key() {
  case "$1" in
    MOSAIC_RUNTIME_BIN|MOSAIC_HEARTBEAT_RUN_DIR|MOSAIC_HEARTBEAT_INTERVAL|MOSAIC_CLAUDE_JSON|CLAUDE_CONFIG_DIR) return 0 ;;
    *) return 1 ;;
  esac
 }
 validate_generated_value() {
  local key="$1"
  local value="$2"
  case "$key" in
    MOSAIC_AGENT_NAME) safe_agent_name "$value" || fail_env unsafe-agent-name "$key" "$value" ;;
    MOSAIC_AGENT_CLASS) safe_policy_name "$value" || fail_env unsafe-class "$key" "$value" ;;
    MOSAIC_AGENT_RUNTIME)
      case "$value" in claude|codex|opencode|pi) ;; *) fail_env unsupported-runtime "$key" "$value" ;; esac
      ;;
    MOSAIC_AGENT_MODEL) [[ "$value" =~ ^[A-Za-z0-9._/:+-]*$ ]] || fail_env unsafe-model "$key" "$value" ;;
    MOSAIC_AGENT_REASONING)
      case "$value" in ''|low|medium|high) ;; *) fail_env unsupported-reasoning "$key" "$value" ;; esac
      ;;
    MOSAIC_AGENT_TOOL_POLICY) [ -z "$value" ] || safe_policy_name "$value" || fail_env unsafe-tool-policy "$key" "$value" ;;
    MOSAIC_AGENT_WORKDIR) safe_path "$value" || fail_env unsafe-path "$key" "$value" ;;
    MOSAIC_TMUX_SOCKET) [[ "$value" =~ ^[A-Za-z0-9_.-]*$ ]] || fail_env unsafe-socket "$key" "$value" ;;
  esac
 }
 validate_local_value() {
  local key="$1"
  local value="$2"
  if [ "$key" = MOSAIC_HEARTBEAT_INTERVAL ]; then
    [[ "$value" =~ ^[1-9][0-9]*$ ]] || fail_env invalid-interval "$key" "$value"
  else
    safe_path "$value" || fail_env unsafe-path "$key" "$value"
  fi
 }
 load_environment_file() {
  local file="$1"
  local kind="$2"
  [ -e "$file" ] || {
    [ "$kind" = generated ] && fail_env missing-file '(generated)' "$file"
    return 0
  }
  assert_private_regular_file "$file"
  SEEN_KEYS=()
  local line key value
  while IFS= read -r line || [ -n "$line" ]; do
    [ -z "$line" ] && continue
    if [[ ! "$line" =~ ^([A-Z][A-Z0-9_]*)=(.*)$ ]]; then
      fail_env malformed-line '(malformed)' "$line"
    fi
    key=${BASH_REMATCH[1]}
    value=${BASH_REMATCH[2]}
    [ -z "${SEEN_KEYS[$key]+set}" ] || fail_env duplicate-key "$key" "$value"
    SEEN_KEYS[$key]=1
    is_sensitive_key "$key" && fail_env sensitive-key "$key" "$value"
    if [ "$kind" = generated ]; then
      is_generated_key "$key" || fail_env unknown-key "$key" "$value"
      validate_generated_value "$key" "$value"
      GENERATED_VALUES[$key]=$value
    else
      is_generated_key "$key" && fail_env generated-key-shadow "$key" "$value"
      is_local_key "$key" || fail_env unknown-key "$key" "$value"
      validate_local_value "$key" "$value"
      LOCAL_VALUES[$key]=$value
    fi
  done < "$file"
 }
 load_environment_file "$GENERATED_ENV" generated
 for required_key in \
  MOSAIC_AGENT_NAME MOSAIC_AGENT_CLASS MOSAIC_AGENT_RUNTIME MOSAIC_AGENT_MODEL \
  MOSAIC_AGENT_REASONING MOSAIC_AGENT_TOOL_POLICY MOSAIC_AGENT_WORKDIR MOSAIC_TMUX_SOCKET; do
  [ -n "${GENERATED_VALUES[$required_key]+set}" ] || fail_env missing-key "$required_key" ''
 done
 load_environment_file "$LOCAL_ENV" local
 [ "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}" = "$AGENT_NAME" ] || \
  fail_env agent-name-mismatch MOSAIC_AGENT_NAME "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}"
 MOSAIC_TMUX_SOCKET=${GENERATED_VALUES[MOSAIC_TMUX_SOCKET]}
 MOSAIC_AGENT_RUNTIME=${GENERATED_VALUES[MOSAIC_AGENT_RUNTIME]}
 MOSAIC_AGENT_MODEL=${GENERATED_VALUES[MOSAIC_AGENT_MODEL]}
 MOSAIC_AGENT_REASONING=${GENERATED_VALUES[MOSAIC_AGENT_REASONING]}
 MOSAIC_AGENT_WORKDIR=${GENERATED_VALUES[MOSAIC_AGENT_WORKDIR]}
 MOSAIC_AGENT_CLASS=${GENERATED_VALUES[MOSAIC_AGENT_CLASS]}
 MOSAIC_AGENT_TOOL_POLICY=${GENERATED_VALUES[MOSAIC_AGENT_TOOL_POLICY]}
 MOSAIC_RUNTIME_BIN=${LOCAL_VALUES[MOSAIC_RUNTIME_BIN]:-}
 MOSAIC_HEARTBEAT_RUN_DIR=${LOCAL_VALUES[MOSAIC_HEARTBEAT_RUN_DIR]:-$MOSAIC_HOME/fleet/run}
 MOSAIC_HEARTBEAT_INTERVAL=${LOCAL_VALUES[MOSAIC_HEARTBEAT_INTERVAL]:-15}
 MOSAIC_CLAUDE_JSON=${LOCAL_VALUES[MOSAIC_CLAUDE_JSON]:-}
 CLAUDE_CONFIG_DIR=${LOCAL_VALUES[CLAUDE_CONFIG_DIR]:-}
 if ! command -v tmux >/dev/null 2>&1; then
  echo "ERROR: tmux is required" >&2
  exit 69
 fi
 # tmux wrapper: pass -L only when a socket is configured. An absent/empty socket
 # means the default tmux socket (no -L), keeping spawn == observe == cheat-sheet.
 _tmux() {
  if [ -n "$MOSAIC_TMUX_SOCKET" ]; then
    tmux -L "$MOSAIC_TMUX_SOCKET" "$@"
@@ -210,90 +42,140 @@ _tmux() {
  fi
 }
 assert_owned_tmux_server() {
  local owner_file="$MOSAIC_HOME/fleet/run/holder-owner"
  [ -f "$owner_file" ] && [ ! -L "$owner_file" ] || fail "private tmux ownership identity is missing"
  local owner_mode
  owner_mode=$(stat -c '%a' -- "$owner_file") || fail "private tmux ownership identity is unreadable"
  (( (8#$owner_mode & 8#077) == 0 )) || fail "private tmux ownership identity has unsafe permissions"
  local owner
  owner=$(tr -d '\n' < "$owner_file")
  [[ "$owner" =~ ^[a-f0-9-]{36}$ ]] || fail "private tmux ownership identity is malformed"
  _tmux has-session -t '=_holder:0.0' 2>/dev/null || fail "owned tmux holder session is absent"
  local environment expected
  environment=$(_tmux show-environment -g 2>/dev/null) || fail "owned tmux global environment is unreadable"
  expected=$(printf '%s\n' \
    "HOME=$HOME" \
    'PATH=/usr/bin:/bin' \
    "PWD=$HOME" \
    "MOSAIC_FLEET_OWNER=$owner" \
    'MOSAIC_TMUX_HOLDER=_holder' \
    "MOSAIC_TMUX_SOCKET=$MOSAIC_TMUX_SOCKET" | sort)
  [ "$(printf '%s\n' "$environment" | sort)" = "$expected" ] || \
    fail "tmux server ownership or environment validation failed"
 }
 # Validate exact server ownership before querying, cleaning, or creating any
 # managed session. An unmanaged or contaminated named socket is never repaired.
 assert_owned_tmux_server
 if [ "$MODE" = interaction ]; then
  [ "$MOSAIC_AGENT_RUNTIME" = pi ] || fail "operator interaction service requires runtime pi"
  [ "$MOSAIC_AGENT_MODEL" = openai/gpt-5.6-sol ] || \
    fail "operator interaction service requires the pinned model"
  [ "$MOSAIC_AGENT_REASONING" = high ] || \
    fail "operator interaction service requires high reasoning"
  [ "$MOSAIC_AGENT_TOOL_POLICY" = operator-interaction ] || \
    fail "operator interaction service requires the operator-interaction tool policy"
 fi
 if [ "$MODE" = stop ]; then
  _tmux kill-session -t "=${AGENT_NAME}" >/dev/null 2>&1 || true
  exit 0
 fi
 if _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
  echo "Mosaic agent session already running: $AGENT_NAME on socket ${MOSAIC_TMUX_SOCKET:-(default)}"
  exit 0
 fi
-# Systemd passes HOME as %h, and the installed service fixes MOSAIC_HOME under
+if [ -z "$MOSAIC_AGENT_COMMAND" ]; then
-# that home. Derive the pane home from the canonical path when available so an
+  # Map the roster's per-agent model_hint to `--model` so workers launch on the
-# inherited pane/session HOME cannot become runtime authority.
+  # configured model (e.g. pi on openai-codex/gpt-5.5:high). Omitted when unset.
-PANE_HOME=$HOME
+  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}${MOSAIC_AGENT_REASONING:+ --thinking $MOSAIC_AGENT_REASONING}"
-case "$MOSAIC_HOME" in
+fi
  */.config/mosaic) PANE_HOME=${MOSAIC_HOME%/.config/mosaic} ;;
 esac
 # ── Derive a runtime-bin PATH prefix ─────────────────────────────────────────
 # Precedence:
 #   1. $MOSAIC_RUNTIME_BIN (explicit override)
 #   2. $(npm config get prefix)/bin  (if npm is on PATH)
 #   3. Fallbacks: $HOME/.npm-global/bin and $HOME/.local/bin
 #
 # Only directories that already exist are included.  The prefix is baked into
 # the pane command regardless of what the LAUNCHER process's $PATH contains,
 # because the tmux pane inherits the tmux SERVER environment (not this script's
 # environment).  A dir on the launcher's PATH may be absent from the server PATH,
 # so every existing candidate must always be included.  Dedup within the
 # constructed prefix avoids listing the same dir twice.
 _build_runtime_bin_prefix() {
  local candidates=()
-  if [ -n "$MOSAIC_RUNTIME_BIN" ]; then candidates+=("$MOSAIC_RUNTIME_BIN"); fi
+
  if [ -n "${MOSAIC_RUNTIME_BIN:-}" ]; then
    candidates+=("$MOSAIC_RUNTIME_BIN")
  fi
  if command -v npm >/dev/null 2>&1; then
    local npm_prefix
    npm_prefix=$(npm config get prefix 2>/dev/null) || true
-    if [ -n "$npm_prefix" ]; then candidates+=("${npm_prefix}/bin"); fi
+    if [ -n "$npm_prefix" ]; then
      candidates+=("${npm_prefix}/bin")
    fi
  fi
  candidates+=("$PANE_HOME/.npm-global/bin" "$PANE_HOME/.local/bin")
-  local prefix="" dir
+  candidates+=("$HOME/.npm-global/bin")
  candidates+=("$HOME/.local/bin")
  local prefix=""
  for dir in "${candidates[@]}"; do
    [ -d "$dir" ] || continue
-    case ":${prefix}:" in *":${dir}:"*) ;; *) prefix="${prefix:+$prefix:}$dir" ;; esac
+    if [ -z "$prefix" ]; then
      prefix="$dir"
    else
      case ":${prefix}:" in
        *":${dir}:"*) ;;  # already in our prefix — skip
        *) prefix="${prefix}:${dir}" ;;
      esac
    fi
  done
  printf '%s' "$prefix"
 }
 MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
 PANE_PATH=${MOSAIC_RUNTIME_BIN_PREFIX:+${MOSAIC_RUNTIME_BIN_PREFIX}:}/usr/local/bin:/usr/bin:/bin
 # ── Build the pane command ────────────────────────────────────────────────────
 # The pane command must:
 #   - Export the augmented PATH so the runtime binary is found.
 #   - exec the agent command so the runtime is the pane's foreground process
 #     (makes `fleet ps` pane_current_command check reliable; no DRIFT false-positive).
 #
 # Quoting strategy: single-quote the inner shell snippet so that variable
 # references in MOSAIC_AGENT_COMMAND are NOT expanded here — they expand inside
 # the pane shell.  However, MOSAIC_RUNTIME_BIN_PREFIX and PATH must be expanded
 # NOW (in this script) because the pane shell inherits the tmux server
 # environment, not this script's env.
 #
 # We build the snippet as a double-quoted here-string embedded in a printf call
 # to avoid nested quoting problems.
 #
 # MOSAIC_AGENT_NAME must also be exported INTO the pane: panes inherit the tmux
 # server environment (not this script's, and not the systemd unit's), so the
 # name would otherwise be empty in-pane and the runtime's native heartbeat
 # (which gates on MOSAIC_AGENT_NAME) would never fire. %q-quote it so it is a
 # safe single bash token regardless of the name's characters.
 AGENT_NAME_Q=$(printf '%q' "$AGENT_NAME")
 # MOSAIC_AGENT_CLASS must ALSO be exported INTO the pane, for the same reason as
 # MOSAIC_AGENT_NAME above: the pane inherits the tmux SERVER environment (not this
 # script's env, and not the systemd unit's EnvironmentFile), so the per-agent class
 # written to agents/<name>.env would otherwise be invisible in-pane. The launcher
 # composes the persona contract from process.env.MOSAIC_AGENT_CLASS at launch
 # (compose-contract -> readPersonaContractBlock); without this export it sees an
 # undefined class and silently injects NO persona contract. %q-quote it so it is a
 # safe single bash token; an empty/unset class %q-quotes to '' and is a harmless
 # no-op downstream (readPersonaContractBlock returns '' for an empty class).
 AGENT_CLASS_Q=$(printf '%q' "${MOSAIC_AGENT_CLASS:-}")
 AGENT_TOOL_POLICY_Q=$(printf '%q' "${MOSAIC_AGENT_TOOL_POLICY:-}")
 if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then
  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export MOSAIC_AGENT_TOOL_POLICY=${AGENT_TOOL_POLICY_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
 else
  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export MOSAIC_AGENT_TOOL_POLICY=${AGENT_TOOL_POLICY_Q}; exec ${MOSAIC_AGENT_COMMAND}"
 fi
 mkdir -p "$MOSAIC_AGENT_WORKDIR"
 # ── Pre-trust the workdir for the Claude runtime ─────────────────────────────
 # Claude Code shows a one-time "Is this a project you trust?" folder-trust gate
 # the first time it opens a directory. A fleet-launched agent has no human to
 # answer it, so the pane stalls forever at the prompt while its heartbeat keeps
 # reporting "healthy" (the pane process IS alive — it's just blocked).
 #
 # IMPORTANT: --dangerously-skip-permissions does NOT bypass this gate, and
 # neither does `trustedProjectDirectories` in settings.json (verified empirically
 # 2026-06-24). The ONLY thing the gate honors is the per-project record in
 # ~/.claude.json: projects["<dir>"].hasTrustDialogAccepted == true (exactly what
 # answering the prompt writes). So we pre-seed that record here.
 #
 # Idempotent, atomic, best-effort: any failure is non-fatal (the agent still
 # launches — worst case it stalls on the gate, i.e. the pre-fix status quo).
 # Only the claude runtime needs this; codex/pi have no such gate.
 _ensure_claude_workdir_trusted() {
  local workdir="$1"
-  local resolved
+  # The path claude keys on is the resolved cwd it is launched in.
-  resolved=$(cd "$workdir" 2>/dev/null && pwd -P) || resolved="$workdir"
+  local rp
  rp=$(cd "$workdir" 2>/dev/null && pwd -P) || rp="$workdir"
  # ~/.claude.json lives next to the claude config dir; honor CLAUDE_CONFIG_DIR.
  local claude_json="${MOSAIC_CLAUDE_JSON:-${CLAUDE_CONFIG_DIR:+$CLAUDE_CONFIG_DIR/.claude.json}}"
  claude_json="${claude_json:-$HOME/.claude.json}"
-  command -v python3 >/dev/null 2>&1 || return 1
+
-  MOSAIC_CJ="$claude_json" MOSAIC_TRUST_DIR="$resolved" python3 - <<'PY'
+  if ! command -v python3 >/dev/null 2>&1; then
    echo "WARNING: python3 not found; cannot pre-trust '$rp' for claude (agent may stall on the folder-trust gate)" >&2
    return 1
  fi
  # Serialize concurrent agent launches that share ~/.claude.json (flock if available).
  local lock="${claude_json}.mosaic-lock"
  _seed() {
    MOSAIC_CJ="$claude_json" MOSAIC_TRUST_DIR="$rp" python3 - <<'PY'
 import json, os, sys, tempfile
 cj = os.environ["MOSAIC_CJ"]
 d = os.environ["MOSAIC_TRUST_DIR"]
@@ -302,19 +184,22 @@ try:
    if not isinstance(data, dict):
        data = {}
 except Exception:
    # Never corrupt an unreadable/partial file — bail without writing.
    sys.exit(2)
 projects = data.setdefault("projects", {})
 entry = projects.get(d)
 if not isinstance(entry, dict):
    entry = {}
    projects[d] = entry
 if entry.get("hasTrustDialogAccepted") is True:
    sys.exit(0)  # already trusted — nothing to do
 entry["hasTrustDialogAccepted"] = True
 tmp_dir = os.path.dirname(cj) or "."
 fd, tmp = tempfile.mkstemp(dir=tmp_dir, prefix=".claude.json.mosaic.")
 try:
    with os.fdopen(fd, "w") as f:
        json.dump(data, f, indent=2)
-    os.replace(tmp, cj)
+    os.replace(tmp, cj)  # atomic
 except Exception:
    try:
        os.unlink(tmp)
@@ -322,56 +207,56 @@ except Exception:
        pass
    sys.exit(3)
 PY
  }
  if command -v flock >/dev/null 2>&1; then
    ( flock 9; _seed ) 9>"$lock" 2>/dev/null || _seed
  else
    _seed
  fi
 }
-if [ "$MOSAIC_AGENT_RUNTIME" = claude ]; then
+case "$MOSAIC_AGENT_RUNTIME" in
-  _ensure_claude_workdir_trusted "$MOSAIC_AGENT_WORKDIR" || \
+  claude)
-    echo "WARNING: could not pre-trust workdir for claude agent $AGENT_NAME" >&2
+    _ensure_claude_workdir_trusted "$MOSAIC_AGENT_WORKDIR" \
-fi
+      || echo "WARNING: could not pre-trust workdir for claude agent $AGENT_NAME" >&2
    ;;
 esac
-LAUNCH_COMMAND=(mosaic yolo "$MOSAIC_AGENT_RUNTIME")
+# ── Launch the tmux session (no exec — we continue to wire the heartbeat) ────
 if [ -n "$MOSAIC_AGENT_MODEL" ]; then LAUNCH_COMMAND+=(--model "$MOSAIC_AGENT_MODEL"); fi
 if [ -n "$MOSAIC_AGENT_REASONING" ]; then LAUNCH_COMMAND+=(--thinking "$MOSAIC_AGENT_REASONING"); fi
 # The tmux holder owns a named server. Explicitly clear the pane environment
 # so server/session variables cannot cross the launch boundary; retain only
 # trusted bootstrap, generated, and approved local data as argv assignments.
 LAUNCH_ENV=(
  /usr/bin/env
  -i
  "HOME=$PANE_HOME"
  "PATH=$PANE_PATH"
  "MOSAIC_HOME=$MOSAIC_HOME"
  "MOSAIC_AGENT_NAME=$AGENT_NAME"
  "MOSAIC_AGENT_CLASS=$MOSAIC_AGENT_CLASS"
  "MOSAIC_AGENT_RUNTIME=$MOSAIC_AGENT_RUNTIME"
  "MOSAIC_AGENT_MODEL=$MOSAIC_AGENT_MODEL"
  "MOSAIC_AGENT_REASONING=$MOSAIC_AGENT_REASONING"
  "MOSAIC_AGENT_TOOL_POLICY=$MOSAIC_AGENT_TOOL_POLICY"
  "MOSAIC_AGENT_WORKDIR=$MOSAIC_AGENT_WORKDIR"
  "MOSAIC_TMUX_SOCKET=$MOSAIC_TMUX_SOCKET"
  "MOSAIC_HEARTBEAT_RUN_DIR=$MOSAIC_HEARTBEAT_RUN_DIR"
 )
 mkdir -p "$MOSAIC_AGENT_WORKDIR"
 _tmux new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" \
-  "${LAUNCH_ENV[@]}" "${LAUNCH_COMMAND[@]}"
+  bash -c "$PANE_SHELL_SNIPPET"
 # ── Resolve the pane PID (retry briefly to let the session initialise) ────────
 PANE_PID=""
 for _retry in 1 2 3 4 5; do
-  PANE_PID=$(_tmux list-panes -t "=${AGENT_NAME}:0.0" -F '#{pane_pid}' 2>/dev/null || true)
+  PANE_PID=$(_tmux list-panes \
    -t "=${AGENT_NAME}:0.0" -F '#{pane_pid}' 2>/dev/null || true)
  [ -n "$PANE_PID" ] && break
  sleep 0.2
 done
 # ── Spawn the heartbeat sidecar (detached, best-effort) ──────────────────────
 # The sidecar writes ~/.config/mosaic/fleet/run/<AGENT>.hb atomically while the
 # pane process is alive, then exits so the file goes stale (fleet ps shows stale
 # then PANE=dead).  It is runtime-agnostic: it only cares about the pane PID.
 _start_heartbeat_sidecar() {
-  local agent="$1" pane_pid="$2" run_dir="$3" interval="$4"
+  local agent="$1"
  local pane_pid="$2"
  local run_dir="$3"
  local interval="$4"
  local hb_file="${run_dir}/${agent}.hb"
  mkdir -p "$run_dir"
  # Write the sidecar as a self-contained bash one-liner so it carries no
  # references to any variables from this script's environment.
  local sidecar_script
  sidecar_script=$(printf \
-    'hb=%q; pid=%q; iv=%q; native="$hb.native"; mkdir -p "$(dirname "$hb")"; while kill -0 "$pid" 2>/dev/null; do now=$(date +%%s); marker=$(stat -c %%Y -- "$native" 2>/dev/null || true); if [ -z "$marker" ] || [ -L "$native" ] || (( now - marker > iv * 2 + 1 )); then tmp="$hb.tmp.$$"; printf "ts=%%s\npid=%%s\nstatus=ok\n" "$(date +%%Y-%%m-%%dT%%H:%%M:%%S%%z)" "$pid" > "$tmp" && mv "$tmp" "$hb"; fi; sleep "$iv"; done' \
+    'hb=%q; pid=%q; iv=%q; mkdir -p "$(dirname "$hb")"; while kill -0 "$pid" 2>/dev/null; do nat="$hb.native"; if [ -f "$nat" ] && [ "$(( $(date +%%s) - $(stat -c %%Y "$nat" 2>/dev/null || echo 0) ))" -lt "$(( iv * 2 ))" ]; then sleep "$iv"; continue; fi; tmp="$hb.tmp.$$"; printf "ts=%%s\npid=%%s\nstatus=ok\n" "$(date +%%Y-%%m-%%dT%%H:%%M:%%S%%z)" "$pid" > "$tmp" && mv "$tmp" "$hb"; sleep "$iv"; done' \
    "$hb_file" "$pane_pid" "$interval")
  # setsid + disown ensures the sidecar survives this script exiting.
  # stderr/stdout go to /dev/null; failures are non-fatal.
  if command -v setsid >/dev/null 2>&1; then
    setsid bash -c "$sidecar_script" </dev/null >/dev/null 2>&1 &
  else
@@ -381,6 +266,7 @@ _start_heartbeat_sidecar() {
 }
 if [ -n "$PANE_PID" ]; then
  # Guard: do not let sidecar startup failures abort the launcher (set -e).
  _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
--- a/packages/mosaic/framework/tools/fleet/start-interaction-service.sh
+++ b/packages/mosaic/framework/tools/fleet/start-interaction-service.sh
@@ -9,7 +9,11 @@ fail() {
 }
 [ -n "$AGENT_NAME" ] || fail "agent name argument is required"
 [[ "$AGENT_NAME" =~ ^[A-Za-z0-9_.-]+$ ]] || fail "agent name contains unsupported characters"
 [ "${MOSAIC_AGENT_NAME:-}" = "$AGENT_NAME" ] || fail "configured agent name must exactly match the service instance"
 [ "${MOSAIC_AGENT_RUNTIME:-}" = "pi" ] || fail "operator interaction service requires runtime pi"
 [ "${MOSAIC_AGENT_MODEL:-}" = "openai/gpt-5.6-sol" ] || fail "operator interaction service requires the pinned model"
 [ "${MOSAIC_AGENT_REASONING:-}" = "high" ] || fail "operator interaction service requires high reasoning"
 [ "${MOSAIC_AGENT_TOOL_POLICY:-}" = "operator-interaction" ] || fail "operator interaction service requires the operator-interaction tool policy"
-# The shared launcher strictly validates the generated/local data boundary
+exec "$(cd -- "$(dirname -- "$0")" && pwd)/start-agent-session.sh" "$AGENT_NAME"
 # before it applies this interaction service's pinned profile checks.
 exec "$(cd -- "$(dirname -- "$0")" && pwd)/start-agent-session.sh" --interaction "$AGENT_NAME"
--- a/packages/mosaic/framework/tools/fleet/start-tmux-holder.sh
+++ b/packages/mosaic/framework/tools/fleet/start-tmux-holder.sh
@@ -1,64 +0,0 @@
 #!/usr/bin/env bash
 set -euo pipefail
 # A holder may create only the configured named socket. Existing servers are
 # accepted only when their private install-derived ownership identity, exact
 # holder session, and complete approved global environment all match.
 MOSAIC_HOME=${MOSAIC_HOME:-$HOME/.config/mosaic}
 MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-mosaic-fleet}
 MOSAIC_TMUX_HOLDER=${MOSAIC_TMUX_HOLDER:-_holder}
 OWNER_FILE="$MOSAIC_HOME/fleet/run/holder-owner"
 TMUX_BIN=/usr/bin/tmux
 fail() {
  echo "ERROR: refusing unmanaged Mosaic tmux server on socket ${MOSAIC_TMUX_SOCKET}: $1" >&2
  exit 64
 }
 [ -x "$TMUX_BIN" ] || fail "tmux binary is unavailable"
 [ -f "$OWNER_FILE" ] && [ ! -L "$OWNER_FILE" ] || fail "private ownership identity is missing"
 owner_mode=$(stat -c '%a' -- "$OWNER_FILE") || fail "private ownership identity is unreadable"
 (( (8#$owner_mode & 8#077) == 0 )) || fail "private ownership identity has unsafe permissions"
 MOSAIC_FLEET_OWNER=$(tr -d '\n' < "$OWNER_FILE")
 [[ "$MOSAIC_FLEET_OWNER" =~ ^[a-f0-9-]{36}$ ]] || fail "private ownership identity is malformed"
 _tmux() {
  "$TMUX_BIN" -L "$MOSAIC_TMUX_SOCKET" "$@"
 }
 server_running() {
  _tmux list-sessions >/dev/null 2>&1
 }
 assert_owned_server() {
  _tmux has-session -t "=${MOSAIC_TMUX_HOLDER}:0.0" 2>/dev/null || fail "exact holder session is absent"
  local environment
  environment=$(_tmux show-environment -g 2>/dev/null) || fail "global environment is unreadable"
  local expected
  expected=$(printf '%s\n' \
    "HOME=$HOME" \
    'PATH=/usr/bin:/bin' \
    "PWD=$HOME" \
    "MOSAIC_FLEET_OWNER=$MOSAIC_FLEET_OWNER" \
    "MOSAIC_TMUX_HOLDER=$MOSAIC_TMUX_HOLDER" \
    "MOSAIC_TMUX_SOCKET=$MOSAIC_TMUX_SOCKET" | sort)
  [ "$(printf '%s\n' "$environment" | sort)" = "$expected" ] || \
    fail "global environment does not match the owned-server contract"
 }
 if server_running; then
  assert_owned_server
 else
  cd "$HOME" || fail "trusted home is unavailable"
  # Start the tmux server itself under the approved environment. The holder pane
  # receives the same closed environment rather than arbitrary server globals.
  /usr/bin/env -i \
    "HOME=$HOME" \
    PATH=/usr/bin:/bin \
    "MOSAIC_FLEET_OWNER=$MOSAIC_FLEET_OWNER" \
    "MOSAIC_TMUX_HOLDER=$MOSAIC_TMUX_HOLDER" \
    "MOSAIC_TMUX_SOCKET=$MOSAIC_TMUX_SOCKET" \
    "$TMUX_BIN" -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$MOSAIC_TMUX_HOLDER" \
    /usr/bin/env -i "HOME=$HOME" PATH=/usr/bin:/bin /bin/sh -c 'while true; do sleep 3600; done'
 fi
--- a/packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
+++ b/packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
@@ -3,410 +3,373 @@ set -euo pipefail
 SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
 START="$SCRIPT_DIR/start-agent-session.sh"
-INTERACTION_START="$SCRIPT_DIR/start-interaction-service.sh"
+SOCKET="mosaic-agent-test-$RANDOM-$$"
-ROOT=$(mktemp -d)
+AGENT="agent-$RANDOM"
-FAKE_BIN=$(mktemp -d)
+WORKDIR=$(mktemp -d)
-TMUX_CALLS=$(mktemp)
+
-trap 'rm -rf "$ROOT" "$FAKE_BIN" "$TMUX_CALLS"' EXIT
+# Keep a single cleanup trap that accumulates resources.
 CLEANUP_DIRS=("$WORKDIR")
 CLEANUP_SOCKETS=("$SOCKET")
 trap '_cleanup' EXIT
 _cleanup() {
  for s in "${CLEANUP_SOCKETS[@]:-}"; do
    tmux -L "$s" kill-server >/dev/null 2>&1 || true
  done
  for d in "${CLEANUP_DIRS[@]:-}"; do
    rm -rf "$d"
  done
 }
 fail() {
  echo "FAIL: $*" >&2
  exit 1
 }
-cat > "$FAKE_BIN/tmux" <<'SHIM'
+# ── Test 1: basic session creation with workdir check ─────────────────────────
 MOSAIC_TMUX_SOCKET="$SOCKET" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR" \
 MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
  "$START" "$AGENT"
 tmux -L "$SOCKET" has-session -t "=$AGENT:0.0" || fail "agent session was not created"
 # Retry: pane_current_path briefly reflects the tmux server's cwd until the pane
 # process establishes its own cwd (the -c start dir). Poll until it settles.
 actual_dir=""
 for _ in $(seq 1 30); do
  actual_dir=$(tmux -L "$SOCKET" display-message -p -t "=$AGENT:0.0" '#{pane_current_path}')
  [ "$actual_dir" = "$WORKDIR" ] && break
  sleep 0.1
 done
 [ "$actual_dir" = "$WORKDIR" ] || fail "agent workdir mismatch: $actual_dir (expected $WORKDIR)"
 # ── Test 2: idempotency (duplicate start prints 'already running') ─────────────
 MOSAIC_TMUX_SOCKET="$SOCKET" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR" \
 MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
  "$START" "$AGENT" >/tmp/mosaic-start-agent-idempotent.out
 grep -qF 'already running' /tmp/mosaic-start-agent-idempotent.out || fail "duplicate start was not idempotent"
 # ── Test 3: runtime-bin PATH prefix is baked into the pane command ────────────
 #
 # We capture the command the script would hand to tmux by injecting a fake
 # 'tmux' shim into PATH.  The shim:
 #   - Intercepts 'new-session' calls and records its arguments to a file.
 #   - For 'has-session' calls, exits 1 (session does not exist) so the script
 #     proceeds to launch instead of printing "already running".
 #   - For 'list-panes' calls, returns empty so PANE_PID stays unset and the
 #     heartbeat sidecar is NOT spawned (heartbeat is not the focus of this test;
 #     test 6 and 7 cover that path).  This prevents any real-filesystem side
 #     effects or leaked background processes.
 #   - For all other subcommands, exits 0.
 #
 # Assertions:
 #   a) 'export PATH=' with the synthetic MOSAIC_RUNTIME_BIN prefix appears.
 #   b) 'exec' appears so the runtime replaces the wrapper shell.
 #   c) MOSAIC_AGENT_COMMAND with flags is forwarded intact.
 FAKE_BIN=$(mktemp -d)
 FAKE_RUNTIME_BIN=$(mktemp -d)
 TMUX_ARGS_FILE=$(mktemp)
 HB_RUN_DIR3=$(mktemp -d)
 CLEANUP_DIRS+=("$FAKE_BIN" "$FAKE_RUNTIME_BIN" "$HB_RUN_DIR3")
 # Write the fake tmux shim (uses only positional args, no sourced vars).
 cat > "$FAKE_BIN/tmux" <<SHIM
 #!/usr/bin/env bash
-set -euo pipefail
+# Fake tmux: record new-session args; report has-session as missing.
-printf '%s\0' "$@" >> "${MOSAIC_TEST_TMUX_CALLS:?}"
+subcmd="\$3"  # argv: tmux -L <socket> <subcmd> ...
-args=("$@")
+if [ "\$subcmd" = "has-session" ]; then
-index=0
+  exit 1   # session not found → script will attempt new-session
-if [ "${args[0]:-}" = -L ]; then index=2; fi
+fi
-case "${args[$index]:-}" in
+if [ "\$subcmd" = "new-session" ]; then
-  has-session)
+  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE"
-    for argument in "${args[@]}"; do
+  exit 0
-      [ "$argument" = '=_holder:0.0' ] && exit 0
+fi
-    done
+if [ "\$subcmd" = "list-panes" ]; then
-    exit 1
+  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
-    ;;
+  echo ""
-  show-environment)
+  exit 0
-    printf '%s\n' \
+fi
-      "HOME=${MOSAIC_TEST_HOME:?}" \
+exit 0
      'PATH=/usr/bin:/bin' \
      "PWD=${MOSAIC_TEST_HOME:?}" \
      "MOSAIC_FLEET_OWNER=${MOSAIC_TEST_FLEET_OWNER:?}" \
      'MOSAIC_TMUX_HOLDER=_holder' \
      'MOSAIC_TMUX_SOCKET=mosaic-test'
    exit 0
    ;;
  list-panes) printf '%s\n' "${MOSAIC_TEST_PANE_PID:-}"; exit 0 ;;
  new-session)
    if [ "${MOSAIC_TEST_EXECUTE_PANE:-}" = 1 ]; then
      for ((index = 0; index < ${#args[@]}; index++)); do
        if [ "${args[$index]}" = /usr/bin/env ]; then
          "${args[@]:$index}"
          break
        fi
      done
    fi
    exit 0
    ;;
  *) exit 0 ;;
 esac
 SHIM
 chmod +x "$FAKE_BIN/tmux"
-cat > "$FAKE_BIN/mosaic" <<'SHIM'
+SOCKET3="mosaic-agent-test3-$RANDOM-$$"
 AGENT3="agent3-$RANDOM"
 WORKDIR3=$(mktemp -d)
 CLEANUP_DIRS+=("$WORKDIR3")
 PATH="$FAKE_BIN:$PATH" \
 MOSAIC_TMUX_SOCKET="$SOCKET3" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR3" \
 MOSAIC_AGENT_RUNTIME="pi" \
 MOSAIC_AGENT_CLASS="code" \
 MOSAIC_AGENT_TOOL_POLICY="operator-interaction" \
 MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN" \
 MOSAIC_AGENT_COMMAND="mosaic yolo pi --model openai-codex/gpt-5.5:high" \
 MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR3" \
  "$START" "$AGENT3"
 all_args=$(cat "$TMUX_ARGS_FILE" 2>/dev/null || true)
 rm -f "$TMUX_ARGS_FILE"
 echo "--- captured tmux new-session args ---"
 echo "$all_args"
 echo "--- end args ---"
 # a) PATH prefix containing FAKE_RUNTIME_BIN must appear.
 echo "$all_args" | grep -qF "export PATH=" || fail "pane command does not export PATH"
 echo "$all_args" | grep -qF "$FAKE_RUNTIME_BIN" || fail "pane command does not include MOSAIC_RUNTIME_BIN in PATH prefix"
 # b) exec must appear so the runtime replaces the wrapper shell.
 echo "$all_args" | grep -qF "exec " || fail "pane command does not use exec"
 # c) Full MOSAIC_AGENT_COMMAND (with flags) must be forwarded.
 echo "$all_args" | grep -qF "mosaic yolo pi --model openai-codex/gpt-5.5:high" || \
  fail "pane command does not forward MOSAIC_AGENT_COMMAND with flags intact"
 # d) MOSAIC_AGENT_NAME and the per-agent MOSAIC_AGENT_CLASS must BOTH be exported
 #    INTO the pane. The pane inherits the tmux SERVER environment (not this
 #    script's env, nor the systemd unit's EnvironmentFile), so any per-agent var
 #    the launcher needs in-pane must be re-exported in the snippet. CLASS is
 #    load-bearing: the launcher composes the persona contract from
 #    process.env.MOSAIC_AGENT_CLASS, so a missing export silently drops the
 #    persona (regression guard for the A3a pane-propagation gap).
 echo "$all_args" | grep -qF "export MOSAIC_AGENT_NAME=" || \
  fail "pane command does not export MOSAIC_AGENT_NAME into the pane"
 echo "$all_args" | grep -qF "export MOSAIC_AGENT_CLASS=code" || \
  fail "pane command does not export MOSAIC_AGENT_CLASS into the pane (persona would silently drop)"
 echo "$all_args" | grep -qF "export MOSAIC_AGENT_TOOL_POLICY=operator-interaction" || \
  fail "pane command does not export MOSAIC_AGENT_TOOL_POLICY into the pane"
 # ── Test 4: when no extra runtime-bin dirs exist, exec still appears ───────────
 TMUX_ARGS_FILE2=$(mktemp)
 FAKE_BIN2=$(mktemp -d)
 HB_RUN_DIR4=$(mktemp -d)
 CLEANUP_DIRS+=("$FAKE_BIN2" "$HB_RUN_DIR4")
 cat > "$FAKE_BIN2/tmux" <<SHIM2
 #!/usr/bin/env bash
-set -euo pipefail
+subcmd="\$3"
-env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
+if [ "\$subcmd" = "has-session" ]; then exit 1; fi
-SHIM
+if [ "\$subcmd" = "new-session" ]; then
-chmod +x "$FAKE_BIN/mosaic"
+  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE2"
-
+  exit 0
 write_generated() {
  local home="$1"
  local agent="$2"
  mkdir -p "$home/fleet/agents" "$home/fleet/run"
  chmod 700 "$home" "$home/fleet" "$home/fleet/agents" "$home/fleet/run"
  printf '123e4567-e89b-12d3-a456-426614174000\n' > "$home/fleet/run/holder-owner"
  chmod 600 "$home/fleet/run/holder-owner"
  cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
 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/work
 MOSAIC_TMUX_SOCKET=mosaic-test
 EOF
  chmod 600 "$home/fleet/agents/$agent.env.generated"
  mkdir -p "$home/work"
 }
 run_start() {
  local home="$1"
  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_HOME="$home" \
    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
    MOSAIC_HOME="$home" "$START" "$agent"
 }
 # Valid generated data launches only the fixed runtime argument array. It never
 # reads an agent-command string or constructs a bash -c pane payload.
 HOME_VALID="$ROOT/valid"
 AGENT_VALID="coder0"
 write_generated "$HOME_VALID" "$AGENT_VALID"
 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"
 echo "$valid_args" | grep -qF 'yolo' || fail "fixed yolo launcher command missing"
 echo "$valid_args" | grep -qF 'pi' || fail "roster runtime missing"
 if echo "$valid_args" | grep -qF 'bash -c'; then
  fail "launcher constructed a shell command payload"
 fi
-
+if [ "\$subcmd" = "list-panes" ]; then
-# The pane must start through an absolute clean-environment boundary. Its
+  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
-# runtime command remains an argv vector, but no holder/session environment
+  echo ""
-# control variable can pass through the pane command.
+  exit 0
 echo "$valid_args" | grep -qxF '/usr/bin/env' || fail "pane does not use absolute env"
 echo "$valid_args" | grep -qxF -- '-i' || fail "pane environment is not cleared"
 # The generated-file parent is a security boundary too: even a private regular
 # file is untrusted if its parent can be replaced or written by another user.
 # Validation must happen before fake tmux receives even a has-session call.
 : > "$TMUX_CALLS"
 HOME_UNSAFE_PARENT="$ROOT/unsafe-parent"
 write_generated "$HOME_UNSAFE_PARENT" "coder-parent"
 chmod 777 "$HOME_UNSAFE_PARENT/fleet/agents"
 if output=$(run_start "$HOME_UNSAFE_PARENT" coder-parent 2>&1); then
  fail "generated file under a world-writable parent was accepted"
 fi
-[ ! -s "$TMUX_CALLS" ] || fail "tmux ran before unsafe parent rejection"
+exit 0
-echo "$output" | grep -qF 'code=unsafe-permissions' || fail "unsafe parent diagnostic missing"
+SHIM2
 chmod +x "$FAKE_BIN2/tmux"
-: > "$TMUX_CALLS"
+SOCKET4="mosaic-agent-test4-$RANDOM-$$"
-HOME_SYMLINK_PARENT="$ROOT/symlink-parent"
+AGENT4="agent4-$RANDOM"
-write_generated "$HOME_SYMLINK_PARENT" "coder-symlink-parent"
+WORKDIR4=$(mktemp -d)
-mv "$HOME_SYMLINK_PARENT/fleet/agents" "$HOME_SYMLINK_PARENT/private-agents"
+CLEANUP_DIRS+=("$WORKDIR4")
-ln -s "$HOME_SYMLINK_PARENT/private-agents" "$HOME_SYMLINK_PARENT/fleet/agents"
+
-if output=$(run_start "$HOME_SYMLINK_PARENT" coder-symlink-parent 2>&1); then
+# MOSAIC_RUNTIME_BIN points to a non-existent dir so prefix will be empty;
-  fail "generated file under a symlinked parent was accepted"
+# .npm-global/bin and .local/bin may or may not exist but we just want exec.
 PATH="$FAKE_BIN2:$PATH" \
 MOSAIC_TMUX_SOCKET="$SOCKET4" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR4" \
 MOSAIC_AGENT_RUNTIME="pi" \
 MOSAIC_RUNTIME_BIN="/nonexistent-dir-$$" \
 MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
 MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR4" \
  "$START" "$AGENT4"
 all_args4=$(cat "$TMUX_ARGS_FILE2" 2>/dev/null || true)
 rm -f "$TMUX_ARGS_FILE2"
 rm -rf "$WORKDIR4"
 echo "$all_args4" | grep -qF "exec " || fail "pane command (no prefix dirs) does not use exec"
 echo "$all_args4" | grep -qF "mosaic yolo pi" || fail "pane command does not include agent command when no prefix"
 # ── Test 5: candidate dir already in LAUNCHER $PATH is still baked into pane ──
 #
 # Regression guard for the bug where _build_runtime_bin_prefix() used to skip
 # a candidate because it was already present in the launcher process's $PATH.
 # That check was wrong: the pane inherits the tmux SERVER environment, not the
 # launcher's env.  Even if a dir is on the launcher's PATH it must always be
 # baked into the pane's PATH export.
 #
 # We prove this by setting PATH to include FAKE_RUNTIME_BIN5 (the candidate),
 # then asserting the generated new-session command still exports it.
 TMUX_ARGS_FILE5=$(mktemp)
 FAKE_BIN5=$(mktemp -d)
 FAKE_RUNTIME_BIN5=$(mktemp -d)  # this dir IS on the launcher's PATH below
 HB_RUN_DIR5=$(mktemp -d)
 CLEANUP_DIRS+=("$FAKE_BIN5" "$FAKE_RUNTIME_BIN5" "$HB_RUN_DIR5")
 cat > "$FAKE_BIN5/tmux" <<SHIM5
 #!/usr/bin/env bash
 subcmd="\$3"
 if [ "\$subcmd" = "has-session" ]; then exit 1; fi
 if [ "\$subcmd" = "new-session" ]; then
  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE5"
  exit 0
 fi
-[ ! -s "$TMUX_CALLS" ] || fail "tmux ran before symlinked parent rejection"
+if [ "\$subcmd" = "list-panes" ]; then
-echo "$output" | grep -qF 'code=unsafe-directory' || fail "symlinked parent diagnostic missing"
+  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
  echo ""
  exit 0
 fi
 exit 0
 SHIM5
 chmod +x "$FAKE_BIN5/tmux"
-# Every managed ancestor is a boundary: MOSAIC_HOME, fleet, and agents. A
+SOCKET5="mosaic-agent-test5-$RANDOM-$$"
-# symlink or group/world-writable ancestor must fail before environment parsing,
+AGENT5="agent5-$RANDOM"
-# workdir creation, or tmux effects. The malformed local input proves parsing
+WORKDIR5=$(mktemp -d)
-# was not reached when the ancestor rejection is reported.
+CLEANUP_DIRS+=("$WORKDIR5")
-assert_managed_ancestor_rejected() {
+CLEANUP_SOCKETS+=("$SOCKET5")
  local ancestor="$1"
  local hazard="$2"
  local home="$ROOT/managed-${ancestor//\//-}-${hazard}"
  local agent="coder-managed-${ancestor//\//-}-${hazard}"
  local node
  write_generated "$home" "$agent"
  printf 'MOSAIC_AGENT_COMMAND=must-not-be-parsed\n' > "$home/fleet/agents/$agent.env.local"
  chmod 600 "$home/fleet/agents/$agent.env.local"
  rm -rf "$home/work"
-  case "$ancestor" in
+# FAKE_RUNTIME_BIN5 is deliberately placed on the LAUNCHER PATH so that the
-    MOSAIC_HOME) node="$home" ;;
+# old (buggy) code would have skipped it.  The correct code must still include
-    MOSAIC_HOME/fleet) node="$home/fleet" ;;
+# it in the pane PATH export.
-    MOSAIC_HOME/fleet/agents) node="$home/fleet/agents" ;;
+PATH="$FAKE_BIN5:$FAKE_RUNTIME_BIN5:$PATH" \
-    *) fail "unknown managed ancestor: $ancestor" ;;
+MOSAIC_TMUX_SOCKET="$SOCKET5" \
-  esac
+MOSAIC_AGENT_WORKDIR="$WORKDIR5" \
 MOSAIC_AGENT_RUNTIME="pi" \
 MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN5" \
 MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
 MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR5" \
  "$START" "$AGENT5"
-  if [ "$hazard" = symlink ]; then
+all_args5=$(cat "$TMUX_ARGS_FILE5" 2>/dev/null || true)
-    local target="${node}-target"
+rm -f "$TMUX_ARGS_FILE5"
-    mv "$node" "$target"
+rm -rf "$WORKDIR5"
    ln -s "$target" "$node"
  else
    chmod 777 "$node"
  fi
-  : > "$TMUX_CALLS"
+echo "--- test 5: launcher-PATH candidate must still appear in pane export ---"
-  if output=$(run_start "$home" "$agent" 2>&1); then
+echo "$all_args5"
-    fail "${hazard} $ancestor was accepted"
+echo "--- end test 5 args ---"
  fi
  [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before $hazard $ancestor rejection"
  [ ! -e "$home/work" ] || fail "workdir was created before $hazard $ancestor rejection"
  echo "$output" | grep -qF "code=unsafe-" || fail "managed ancestor diagnostic missing"
  if echo "$output" | grep -qF 'key=MOSAIC_AGENT_COMMAND'; then
    fail "environment parsing ran before $hazard $ancestor rejection"
  fi
 }
-for managed_ancestor in MOSAIC_HOME MOSAIC_HOME/fleet MOSAIC_HOME/fleet/agents; do
+echo "$all_args5" | grep -qF "export PATH=" || \
-  assert_managed_ancestor_rejected "$managed_ancestor" symlink
+  fail "test5: pane command does not export PATH when candidate is on launcher PATH"
-  assert_managed_ancestor_rejected "$managed_ancestor" group-world-writable
+echo "$all_args5" | grep -qF "$FAKE_RUNTIME_BIN5" || \
  fail "test5: candidate dir (already on launcher PATH) was NOT baked into pane PATH — regression"
 # ── Test 6: heartbeat sidecar — pane PID resolved + .hb file written ──────────
 #
 # Uses a real tmux session (same socket as test 1 which already has $AGENT) so
 # list-panes returns a real pane PID.  We override MOSAIC_HEARTBEAT_RUN_DIR to
 # a temp dir and set a 1-second interval, then wait up to 3 s for the .hb file
 # to appear and check its content.
 HB_RUN_DIR=$(mktemp -d)
 CLEANUP_DIRS+=("$HB_RUN_DIR")
 # Re-use the session+agent created in Test 1 (still alive on $SOCKET / $AGENT).
 # We need to invoke the script for a NEW agent on the same socket to exercise
 # the heartbeat path with a real pane PID.
 AGENT6="agent6-$RANDOM"
 MOSAIC_TMUX_SOCKET="$SOCKET" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR" \
 MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
 MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR" \
 MOSAIC_HEARTBEAT_INTERVAL="1" \
  "$START" "$AGENT6"
 HB_FILE="$HB_RUN_DIR/${AGENT6}.hb"
 # Wait up to 5 seconds for the heartbeat file to appear.
 _waited=0
 until [ -f "$HB_FILE" ] || [ "$_waited" -ge 5 ]; do
  sleep 0.5
  _waited=$((_waited + 1))
 done
-# A local file cannot shadow any roster-derived generated key. Validation must
+[ -f "$HB_FILE" ] || fail "test6: heartbeat file not written at $HB_FILE within 5s"
 # happen before fake tmux receives even a has-session call.
 : > "$TMUX_CALLS"
 HOME_SHADOW="$ROOT/shadow"
 write_generated "$HOME_SHADOW" "coder1"
 printf 'MOSAIC_AGENT_RUNTIME=codex\n' > "$HOME_SHADOW/fleet/agents/coder1.env.local"
 chmod 600 "$HOME_SHADOW/fleet/agents/coder1.env.local"
 if output=$(run_start "$HOME_SHADOW" coder1 2>&1); then
  fail "generated-key shadow was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before generated-key shadow rejection"
 echo "$output" | grep -qF 'key=MOSAIC_AGENT_RUNTIME' || fail "shadow diagnostic omitted key"
 echo "$output" | grep -qF 'sha256=' || fail "shadow diagnostic omitted hash"
 if echo "$output" | grep -qF 'codex'; then
  fail "shadow diagnostic leaked value"
 fi
-# Arbitrary command compatibility is quarantined/rejected as data. Diagnostics
+hb_content=$(cat "$HB_FILE")
-# may name the key and hash but must never echo the privileged command text.
+echo "--- test 6: heartbeat file content ---"
-: > "$TMUX_CALLS"
+echo "$hb_content"
-HOME_COMMAND="$ROOT/command"
+echo "--- end test 6 ---"
 write_generated "$HOME_COMMAND" "coder2"
 COMMAND_VALUE='mosaic yolo codex --dangerous'
 printf 'MOSAIC_AGENT_COMMAND=%s\n' "$COMMAND_VALUE" > "$HOME_COMMAND/fleet/agents/coder2.env.local"
 chmod 600 "$HOME_COMMAND/fleet/agents/coder2.env.local"
 if output=$(run_start "$HOME_COMMAND" coder2 2>&1); then
  fail "arbitrary command override was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before command rejection"
 echo "$output" | grep -qF 'key=MOSAIC_AGENT_COMMAND' || fail "command diagnostic omitted key"
 echo "$output" | grep -qF 'sha256=' || fail "command diagnostic omitted hash"
 if echo "$output" | grep -qF "$COMMAND_VALUE"; then
  fail "command diagnostic leaked command value"
 fi
-# Group/world-readable local input is not trusted even when its syntax is safe.
+# Verify required fields are present.
-: > "$TMUX_CALLS"
+echo "$hb_content" | grep -qE '^ts=[0-9]{4}-[0-9]{2}-[0-9]{2}T' || \
-HOME_PERMS="$ROOT/perms"
+  fail "test6: heartbeat ts field missing or malformed"
-write_generated "$HOME_PERMS" "coder3"
+echo "$hb_content" | grep -qE '^pid=[0-9]+' || \
-printf 'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n' > "$HOME_PERMS/fleet/agents/coder3.env.local"
+  fail "test6: heartbeat pid field missing or malformed"
-chmod 644 "$HOME_PERMS/fleet/agents/coder3.env.local"
+echo "$hb_content" | grep -qF 'status=ok' || \
-if output=$(run_start "$HOME_PERMS" coder3 2>&1); then
+  fail "test6: heartbeat status=ok missing"
  fail "world-readable local input was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before permissions rejection"
 echo "$output" | grep -qF 'code=unsafe-permissions' || fail "permission diagnostic missing"
-# A unit/holder-like clean bootstrap must yield a pane with trusted HOME and
+# ── Test 7: heartbeat sidecar — targets correct .hb path per agent name ────────
-# computed PATH only. The pane command itself must not carry loader, shell
+#
-# control, arbitrary sentinel, or stale bootstrap variables.
+# Uses the fake-tmux shim approach (like tests 3-5) to capture the sidecar
-: > "$TMUX_CALLS"
+# invocation without needing a real session.  A fake setsid shim records its
-HOME_PANE_BOUNDARY="$ROOT/pane-boundary/.config/mosaic"
+# arguments so we can assert the sidecar script targets the expected .hb path
-write_generated "$HOME_PANE_BOUNDARY" "coder-pane-boundary"
+# and uses the configured interval.
 PANE_TRUSTED_HOME="${HOME_PANE_BOUNDARY%/.config/mosaic}"
 PANE_STALE_HOME="$ROOT/stale-home"
 PANE_STALE_PATH="$ROOT/stale-bin"
 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"
 LD_PRELOAD='/not/loaded/by-clean-bootstrap.so' \
 BASH_ENV="$PANE_BASH_ENV" \
 MOSAIC_UNTRUSTED_SENTINEL='must-not-reach-pane' \
 HOME="$PANE_STALE_HOME" \
 PATH="$PANE_STALE_PATH" \
  /usr/bin/env -i \
    "HOME=$PANE_TRUSTED_HOME" \
    "PATH=$FAKE_BIN:/usr/bin:/bin" \
    "MOSAIC_HOME=$HOME_PANE_BOUNDARY" \
    "MOSAIC_TEST_TMUX_CALLS=$TMUX_CALLS" \
    "MOSAIC_TEST_HOME=$PANE_TRUSTED_HOME" \
    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
    MOSAIC_TEST_EXECUTE_PANE=1 \
    "$START" coder-pane-boundary
 pane_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$pane_args" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
  fail "pane did not restore trusted HOME"
 echo "$pane_args" | grep -qF "HOME=$PANE_STALE_HOME" && \
  fail "pane inherited stale HOME"
 echo "$pane_args" | grep -qF "$PANE_STALE_PATH" && fail "pane inherited stale PATH"
 for blocked in LD_PRELOAD= BASH_ENV= MOSAIC_UNTRUSTED_SENTINEL=; do
  echo "$pane_args" | grep -qF "$blocked" && fail "pane inherited $blocked"
 done
-after_pane_env=$(printf '%s\n' "$pane_args" | grep -n -m1 -F '/usr/bin/env' | cut -d: -f1)
+FAKE_BIN7=$(mktemp -d)
-[ -n "$after_pane_env" ] || fail "pane command did not use absolute env"
+FAKE_RUNTIME_BIN7=$(mktemp -d)
-printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i' || \
+SETSID_ARGS_FILE=$(mktemp)
-  fail "pane command did not clear its environment"
+HB_RUN_DIR7=$(mktemp -d)
-pane_environment=$(tr '\0' '\n' < "$HOME_PANE_BOUNDARY/fleet/pane-environment")
+CLEANUP_DIRS+=("$FAKE_BIN7" "$FAKE_RUNTIME_BIN7" "$HB_RUN_DIR7")
 echo "$pane_environment" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
  fail "runtime pane did not receive trusted HOME"
 echo "$pane_environment" | grep -qF "$PANE_STALE_PATH" && fail "runtime pane received stale PATH"
 for blocked in LD_PRELOAD= BASH_ENV= MOSAIC_UNTRUSTED_SENTINEL=; do
  echo "$pane_environment" | grep -qF "$blocked" && fail "runtime pane received $blocked"
 done
-write_interaction_generated() {
+AGENT7="my-fleet-agent-$RANDOM"
-  local home="$1"
+INTERVAL7="42"
  local agent="$2"
  mkdir -p "$home/fleet/agents" "$home/fleet/run" "$home/work"
  chmod 700 "$home" "$home/fleet" "$home/fleet/agents" "$home/fleet/run"
  printf '123e4567-e89b-12d3-a456-426614174000\n' > "$home/fleet/run/holder-owner"
  chmod 600 "$home/fleet/run/holder-owner"
  cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
 MOSAIC_AGENT_CLASS=operator-interaction
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol
 MOSAIC_AGENT_REASONING=high
 MOSAIC_AGENT_TOOL_POLICY=operator-interaction
 MOSAIC_AGENT_WORKDIR=$home/work
 MOSAIC_TMUX_SOCKET=mosaic-test
 EOF
  chmod 600 "$home/fleet/agents/$agent.env.generated"
 }
-run_interaction() {
+# Fake tmux: has-session → not found; new-session → ok; list-panes → known PID.
-  local home="$1"
+cat > "$FAKE_BIN7/tmux" <<SHIM7
-  local agent="$2"
+#!/usr/bin/env bash
-  HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
+subcmd="\$3"
-    MOSAIC_TEST_HOME="$home" \
+if [ "\$subcmd" = "has-session" ]; then exit 1; fi
-    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
+if [ "\$subcmd" = "new-session" ]; then exit 0; fi
-    MOSAIC_HOME="$home" "$INTERACTION_START" "$agent"
+if [ "\$subcmd" = "list-panes" ]; then echo "88888"; exit 0; fi
-}
+exit 0
 SHIM7
 chmod +x "$FAKE_BIN7/tmux"
-write_heartbeat_local() {
+# Fake setsid: capture the bash -c <script> argument for inspection, then
-  local home="$1"
+# background an actual bash subshell so disown succeeds in the caller.
-  local agent="$2"
+cat > "$FAKE_BIN7/setsid" <<'SETSID_SHIM'
-  mkdir -p "$home/run"
+#!/usr/bin/env bash
-  cat > "$home/fleet/agents/$agent.env.local" <<EOF
+# argv: setsid bash -c <sidecar_script>
-MOSAIC_HEARTBEAT_RUN_DIR=$home/run
+# Record the full argument list to the capture file, then exit cleanly.
-MOSAIC_HEARTBEAT_INTERVAL=1
+printf '%s\0' "$@" > __SETSID_ARGS_FILE__
-EOF
+exit 0
-  chmod 600 "$home/fleet/agents/$agent.env.local"
+SETSID_SHIM
-}
+# Patch the placeholder with the real capture-file path (avoids heredoc expansion issues).
 sed -i "s|__SETSID_ARGS_FILE__|${SETSID_ARGS_FILE}|g" "$FAKE_BIN7/setsid"
 chmod +x "$FAKE_BIN7/setsid"
-wait_for_sidecar_status() {
+SOCKET7="mosaic-agent-test7-$RANDOM-$$"
-  local file="$1"
+WORKDIR7=$(mktemp -d)
-  for _retry in $(seq 1 30); do
+CLEANUP_DIRS+=("$WORKDIR7")
    grep -qF 'status=ok' "$file" 2>/dev/null && return 0
    sleep 0.1
  done
  fail "heartbeat sidecar did not resume after native marker became stale or absent"
 }
-# A fresh Pi-native marker is authoritative: the shell sidecar may start but
+PATH="$FAKE_BIN7:$PATH" \
-# must not overwrite Pi's busy/ok/model heartbeat. It must resume only when
+MOSAIC_TMUX_SOCKET="$SOCKET7" \
-# the marker is stale or absent.
+MOSAIC_AGENT_WORKDIR="$WORKDIR7" \
-HOME_NATIVE_FRESH="$ROOT/native-fresh"
+MOSAIC_AGENT_RUNTIME="pi" \
-write_generated "$HOME_NATIVE_FRESH" "coder-native-fresh"
+MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN7" \
-write_heartbeat_local "$HOME_NATIVE_FRESH" "coder-native-fresh"
+MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
-FRESH_HB="$HOME_NATIVE_FRESH/run/coder-native-fresh.hb"
+MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR7" \
-printf 'ts=native\npid=1\nstatus=busy\nmodel=authoritative-model\n' > "$FRESH_HB"
+MOSAIC_HEARTBEAT_INTERVAL="$INTERVAL7" \
-touch "$FRESH_HB.native"
+  "$START" "$AGENT7"
 MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_FRESH" coder-native-fresh
 sleep 0.3
 fresh_content=$(cat "$FRESH_HB")
 [ "$fresh_content" = 'ts=native
 pid=1
 status=busy
 model=authoritative-model' ] || fail "fresh native heartbeat was overwritten"
-HOME_NATIVE_STALE="$ROOT/native-stale"
+# Give the background setsid shim a moment to finish writing the capture file.
-write_generated "$HOME_NATIVE_STALE" "coder-native-stale"
+sleep 0.5
 write_heartbeat_local "$HOME_NATIVE_STALE" "coder-native-stale"
 STALE_HB="$HOME_NATIVE_STALE/run/coder-native-stale.hb"
 printf 'ts=native\npid=1\nstatus=busy\nmodel=stale-model\n' > "$STALE_HB"
 touch -d '10 seconds ago' "$STALE_HB.native"
 MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_STALE" coder-native-stale
 wait_for_sidecar_status "$STALE_HB"
-HOME_NATIVE_ABSENT="$ROOT/native-absent"
+setsid_args=$(cat "$SETSID_ARGS_FILE" 2>/dev/null | tr '\0' '\n' || true)
-write_generated "$HOME_NATIVE_ABSENT" "coder-native-absent"
+rm -f "$SETSID_ARGS_FILE"
-write_heartbeat_local "$HOME_NATIVE_ABSENT" "coder-native-absent"
+rm -rf "$WORKDIR7"
 ABSENT_HB="$HOME_NATIVE_ABSENT/run/coder-native-absent.hb"
 printf 'ts=native\npid=1\nstatus=busy\nmodel=absent-model\n' > "$ABSENT_HB"
 MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_ABSENT" coder-native-absent
 wait_for_sidecar_status "$ABSENT_HB"
-# The interaction wrapper delegates to the shared strict parser before applying
+echo "--- test 7: captured setsid args ---"
-# its pinned policy, so malformed projection data wins over profile diagnostics.
+echo "$setsid_args"
-: > "$TMUX_CALLS"
+echo "--- end test 7 ---"
 HOME_INTERACTION_MALFORMED="$ROOT/interaction-malformed"
 write_interaction_generated "$HOME_INTERACTION_MALFORMED" "interaction-malformed"
 printf 'UNTRUSTED_BOOTSTRAP=value\n' >> "$HOME_INTERACTION_MALFORMED/fleet/agents/interaction-malformed.env.generated"
 if output=$(run_interaction "$HOME_INTERACTION_MALFORMED" interaction-malformed 2>&1); then
  fail "interaction wrapper accepted malformed generated data"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before interaction strict-parser rejection"
 echo "$output" | grep -qF 'code=unknown-key' || fail "interaction did not use shared strict parser first"
-# A syntactically valid but policy-incompatible projection reaches the pinned
+# The sidecar script (bash -c <script>) must reference the correct .hb path.
-# interaction policy check only after strict parsing and never starts tmux.
+expected_hb="${HB_RUN_DIR7}/${AGENT7}.hb"
-: > "$TMUX_CALLS"
+echo "$setsid_args" | grep -qF "$expected_hb" || \
-HOME_INTERACTION_POLICY="$ROOT/interaction-policy"
+  fail "test7: sidecar script does not reference correct .hb path ($expected_hb)"
 write_interaction_generated "$HOME_INTERACTION_POLICY" "interaction-policy"
 perl -0pi -e 's/MOSAIC_AGENT_RUNTIME=pi/MOSAIC_AGENT_RUNTIME=codex/' \
  "$HOME_INTERACTION_POLICY/fleet/agents/interaction-policy.env.generated"
 if output=$(run_interaction "$HOME_INTERACTION_POLICY" interaction-policy 2>&1); then
  fail "interaction wrapper accepted a policy-incompatible projection"
 fi
 interaction_policy_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$interaction_policy_args" | grep -qF 'new-session' && \
  fail "interaction pinned-policy rejection created a tmux session"
 echo "$output" | grep -qF 'operator interaction service requires runtime pi' || \
  fail "interaction pinned-policy check did not follow strict parsing"
-# Exact stop derives the socket exclusively from the validated generated
+# The sidecar script must use the configured interval.
-# projection and ignores an ambient socket supplied by the caller.
+echo "$setsid_args" | grep -qF "$INTERVAL7" || \
-: > "$TMUX_CALLS"
+  fail "test7: sidecar script does not reference configured interval ($INTERVAL7)"
 HOME_STOP="$ROOT/stop"
 write_generated "$HOME_STOP" "coder-stop"
 HOME="$HOME_STOP" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
  MOSAIC_TEST_HOME="$HOME_STOP" \
  MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
  MOSAIC_HOME="$HOME_STOP" MOSAIC_TMUX_SOCKET=ambient-socket "$START" --stop coder-stop
 stop_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$stop_args" | grep -qxF 'mosaic-test' || fail "exact stop did not use the validated generated socket"
 echo "$stop_args" | grep -qxF 'kill-session' || fail "exact stop did not request session termination"
 echo "$stop_args" | grep -qxF '=coder-stop' || fail "exact stop did not exact-match the generated agent name"
 if echo "$stop_args" | grep -qF 'ambient-socket'; then
  fail "exact stop trusted an ambient socket"
 fi
-echo 'ok - start-agent-session generated environment boundary'
+echo "ok - start-agent-session"
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -1,4 +1,4 @@
-import { chmod, lstat, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { Command } from 'commander';
@@ -284,8 +284,6 @@ describe('fleet roster parsing', () => {
        'MOSAIC_AGENT_CLASS=implementer',
        'MOSAIC_AGENT_RUNTIME=codex',
        'MOSAIC_AGENT_MODEL=',
        'MOSAIC_AGENT_REASONING=',
        'MOSAIC_AGENT_TOOL_POLICY=',
        'MOSAIC_AGENT_WORKDIR=/srv/mosaic',
        'MOSAIC_TMUX_SOCKET=mosaic-fleet',
        '',
@@ -327,38 +325,57 @@ describe('fleet roster parsing', () => {
    );
  });
-  it('rejects legacy command overrides instead of merging them into generated authority', () => {
+  it('preserves site-owned agent EnvironmentFile overrides while refreshing roster keys', () => {
-    const generated = generateAgentEnv(
+    const generated = [
-      {
+      'MOSAIC_AGENT_NAME=coder0',
-        version: 1,
+      'MOSAIC_AGENT_RUNTIME=codex',
-        transport: 'tmux',
+      'MOSAIC_AGENT_WORKDIR=/srv/new',
-        tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
+      'MOSAIC_TMUX_SOCKET=mosaic-fleet',
-        defaults: { workingDirectory: '/srv/new' },
+      '',
-        runtimes: {},
+    ].join('\n');
-        agents: [],
+    const existing = [
-      },
+      'MOSAIC_AGENT_NAME=old-name',
-      { name: 'coder0', className: 'code', runtime: 'codex' },
+      'MOSAIC_AGENT_RUNTIME=old-runtime',
-    );
+      'MOSAIC_AGENT_WORKDIR=/srv/old',
      'MOSAIC_TMUX_SOCKET=old-socket',
      'MOSAIC_AGENT_COMMAND=/home/jarvis/.config/mosaic/fleet/canary.sh',
      '# site note',
      '',
    ].join('\n');
-    expect((): string => mergeAgentEnv(generated, 'MOSAIC_AGENT_COMMAND=legacy-command\n')).toThrow(
+    expect(mergeAgentEnv(generated, existing)).toBe(
-      /MOSAIC_AGENT_COMMAND/,
+      [
        'MOSAIC_AGENT_NAME=coder0',
        'MOSAIC_AGENT_RUNTIME=codex',
        'MOSAIC_AGENT_WORKDIR=/srv/new',
        'MOSAIC_TMUX_SOCKET=mosaic-fleet',
        'MOSAIC_AGENT_COMMAND=/home/jarvis/.config/mosaic/fleet/canary.sh',
        '# site note',
        '',
      ].join('\n'),
    );
  });
-  it('does not merge a valid local value into the generated projection', () => {
+  it('updates (does not duplicate) MOSAIC_AGENT_CLASS on re-launch', () => {
-    const generated = generateAgentEnv(
+    const generated = [
-      {
+      'MOSAIC_AGENT_NAME=coder0',
-        version: 1,
+      'MOSAIC_AGENT_CLASS=orchestrator',
-        transport: 'tmux',
+      'MOSAIC_AGENT_RUNTIME=codex',
-        tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
+      '',
-        defaults: { workingDirectory: '/srv/new' },
+    ].join('\n');
-        runtimes: {},
+    const existing = [
-        agents: [],
+      'MOSAIC_AGENT_NAME=coder0',
-      },
+      'MOSAIC_AGENT_CLASS=worker',
-      { name: 'coder0', className: 'code', runtime: 'codex' },
+      'MOSAIC_AGENT_RUNTIME=codex',
-    );
+      '',
    ].join('\n');
-    expect(mergeAgentEnv(generated, 'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n')).toBe(generated);
+    const merged = mergeAgentEnv(generated, existing);
    // mergeAgentEnv keys by VAR name, so the regenerated CLASS wins and there is
    // exactly one MOSAIC_AGENT_CLASS line (no stale worker value left behind).
    expect(merged).toContain('MOSAIC_AGENT_CLASS=orchestrator');
    expect(merged).not.toContain('MOSAIC_AGENT_CLASS=worker');
    expect(merged.match(/^MOSAIC_AGENT_CLASS=/gm)).toHaveLength(1);
  });
  it('rejects unknown roster fields instead of silently defaulting', async () => {
@@ -1112,92 +1129,6 @@ describe('fleet command construction', () => {
    }
  });
  it('creates private managed directories and roster/projection files through fresh init and install under umask 022', async () => {
    const originalHome = process.env.HOME;
    const originalMosaicHome = process.env.MOSAIC_HOME;
    const originalUmask = process.umask(0o022);
    const home = await tempDir();
    process.env.HOME = home;
    delete process.env.MOSAIC_HOME;
    const mosaicHome = join(home, '.config', 'mosaic');
    const program = new Command();
    program.exitOverride();
    registerFleetCommand(program, { frameworkRoot: resolve(process.cwd(), 'framework') });
    try {
      await expect(
        program.parseAsync(['node', 'mosaic', 'fleet', 'init', '--profile', 'minimal', '--write']),
      ).resolves.toBeDefined();
      await expect(
        program.parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']),
      ).resolves.toBeDefined();
      for (const path of [
        mosaicHome,
        join(mosaicHome, 'fleet'),
        join(mosaicHome, 'fleet', 'agents'),
      ]) {
        expect((await stat(path)).mode & 0o777).toBe(0o700);
      }
      expect((await stat(join(mosaicHome, 'fleet', 'roster.yaml'))).mode & 0o777).toBe(0o600);
      expect(
        (await stat(join(mosaicHome, 'fleet', 'agents', 'canary-pi.env.generated'))).mode & 0o777,
      ).toBe(0o600);
    } finally {
      process.umask(originalUmask);
      if (originalHome === undefined) delete process.env.HOME;
      else process.env.HOME = originalHome;
      if (originalMosaicHome === undefined) delete process.env.MOSAIC_HOME;
      else process.env.MOSAIC_HOME = originalMosaicHome;
      await rm(home, { recursive: true, force: true });
    }
  });
  it('creates a private real projection directory and private generated files on fresh install', async () => {
    const originalHome = process.env.HOME;
    const home = await tempDir();
    process.env.HOME = home;
    const mosaicHome = join(home, '.config', 'mosaic');
    const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
    const fleetDir = join(mosaicHome, 'fleet');
    await mkdir(fleetDir, { recursive: true, mode: 0o700 });
    await chmod(mosaicHome, 0o700);
    await chmod(fleetDir, 0o700);
    await writeFile(
      join(mosaicHome, 'fleet', 'roster.yaml'),
      [
        'version: 1',
        'transport: tmux',
        'agents:',
        '  - name: coder0',
        '    runtime: pi',
        '    class: code',
      ].join('\n'),
    );
    const program = new Command();
    program.exitOverride();
    registerFleetCommand(program, {
      frameworkRoot: resolve(process.cwd(), 'framework'),
      mosaicHome,
    });
    try {
      await expect(
        program.parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']),
      ).resolves.toBeDefined();
      const directoryMetadata = await lstat(agentEnvDir);
      expect(directoryMetadata.isDirectory()).toBe(true);
      expect(directoryMetadata.isSymbolicLink()).toBe(false);
      expect(directoryMetadata.mode & 0o777).toBe(0o700);
      expect((await stat(join(agentEnvDir, 'coder0.env.generated'))).mode & 0o777).toBe(0o600);
    } finally {
      if (originalHome === undefined) delete process.env.HOME;
      else process.env.HOME = originalHome;
      await rm(home, { recursive: true, force: true });
    }
  });
  it.each(['start', 'stop', 'restart', 'status'] as const)(
    'rejects single-agent %s for agents outside the roster',
    async (action) => {
@@ -1756,10 +1687,8 @@ describe('fleet ps — drift detection', () => {
 describe('fleet-polish bundle — boot-survival symmetry', () => {
  async function rosterHome(agents: string): Promise<string> {
    const home = await tempDir();
-    const fleetDir = join(home, 'fleet');
+    await mkdir(join(home, 'fleet'), { recursive: true });
-    await mkdir(fleetDir, { recursive: true, mode: 0o700 });
+    await writeFile(join(home, 'fleet', 'roster.yaml'), agents);
    await chmod(fleetDir, 0o700);
    await writeFile(join(fleetDir, 'roster.yaml'), agents);
    return home;
  }
@@ -3530,11 +3459,7 @@ describe('fleet add command', () => {
  async function makeHome(agents = ['orchestrator']): Promise<string> {
    const dir = await mkdtemp(join(tmpdir(), 'mosaic-fleet-add-'));
-    const fleetDir = join(dir, 'fleet');
+    await mkdir(join(dir, 'fleet', 'agents'), { recursive: true });
    const agentEnvDir = join(fleetDir, 'agents');
    await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
    await chmod(fleetDir, 0o700);
    await chmod(agentEnvDir, 0o700);
    const agentLines = agents.map((name) => {
      const cls = name === 'orchestrator' ? 'orchestrator' : 'worker';
      return `  - name: ${name}\n    runtime: claude\n    class: ${cls}`;
@@ -3568,110 +3493,11 @@ describe('fleet add command', () => {
    const roster = await loadFleetRoster(join(home, 'fleet', 'roster.yaml'));
    expect(roster.agents.map((a) => a.name)).toContain('coder0');
-    const envContent = await readFile(
+    const envContent = await readFile(join(home, 'fleet', 'agents', 'coder0.env'), 'utf8');
      join(home, 'fleet', 'agents', 'coder0.env.generated'),
      'utf8',
    );
    expect(envContent).toContain('MOSAIC_AGENT_NAME=coder0');
    expect(envContent).toContain('MOSAIC_AGENT_RUNTIME=codex');
  });
  it('rejects an unprojectable dogfood runtime without mutating roster or projection state', async () => {
    home = await makeHome();
    const rosterPath = join(home, 'fleet', 'roster.yaml');
    const agentEnvDir = join(home, 'fleet', 'agents');
    const trackedPaths = [
      rosterPath,
      join(agentEnvDir, 'dogfood.env.generated'),
      join(agentEnvDir, 'dogfood.env.local'),
      join(agentEnvDir, 'dogfood.env.quarantine'),
    ];
    await writeFile(trackedPaths[1]!, 'generated-before\n');
    await writeFile(trackedPaths[2]!, 'MOSAIC_RUNTIME_BIN=/safe/runtime\n');
    await writeFile(trackedPaths[3]!, 'quarantine-before\n');
    const beforeState = new Map<string, Buffer>();
    for (const path of trackedPaths) beforeState.set(path, await readFile(path));
    const calls: string[][] = [];
    const runner: CommandRunner = async (command, args) => {
      calls.push([command, ...args]);
      return { stdout: '', stderr: '', exitCode: 0 };
    };
    const program = new Command();
    program.exitOverride();
    registerFleetCommand(program, { runner, mosaicHome: home });
    await expect(
      program.parseAsync([
        'node',
        'mosaic',
        'fleet',
        'add',
        'dogfood',
        '--runtime',
        'dogfood',
        '--class',
        'worker',
        '--no-start',
      ]),
    ).rejects.toThrow(/runtime/i);
    for (const path of trackedPaths) {
      expect(await readFile(path)).toEqual(beforeState.get(path));
    }
    expect(calls).toEqual([]);
  });
  it('rejects supported add with a deterministic quarantine conflict before roster persistence', async () => {
    home = await makeHome();
    const rosterPath = join(home, 'fleet', 'roster.yaml');
    const agentEnvDir = join(home, 'fleet', 'agents');
    const trackedPaths = [
      rosterPath,
      join(agentEnvDir, 'coder1.env.generated'),
      join(agentEnvDir, 'coder1.env.local'),
      join(agentEnvDir, 'coder1.env'),
      join(agentEnvDir, 'coder1.env.quarantine'),
    ];
    await writeFile(trackedPaths[1]!, 'generated-before\n', { mode: 0o600 });
    await writeFile(trackedPaths[2]!, 'MOSAIC_RUNTIME_BIN=/safe/runtime\n', { mode: 0o600 });
    await writeFile(trackedPaths[3]!, 'MOSAIC_AGENT_COMMAND=must-be-quarantined\n', {
      mode: 0o600,
    });
    await writeFile(trackedPaths[4]!, 'quarantine-before\n', { mode: 0o600 });
    const beforeState = new Map<string, Buffer>();
    for (const path of trackedPaths) beforeState.set(path, await readFile(path));
    const calls: string[][] = [];
    const runner: CommandRunner = async (command, args) => {
      calls.push([command, ...args]);
      return { stdout: '', stderr: '', exitCode: 0 };
    };
    const program = new Command();
    program.exitOverride();
    registerFleetCommand(program, { runner, mosaicHome: home });
    await expect(
      program.parseAsync([
        'node',
        'mosaic',
        'fleet',
        'add',
        'coder1',
        '--runtime',
        'codex',
        '--class',
        'worker',
        '--no-start',
      ]),
    ).rejects.toThrow('quarantine-exists');
    for (const path of trackedPaths) {
      expect(await readFile(path)).toEqual(beforeState.get(path));
    }
    expect(calls).toEqual([]);
  });
  it('--no-start skips the start command', async () => {
    home = await makeHome();
    const calls: string[][] = [];
@@ -3833,10 +3659,7 @@ describe('fleet remove command', () => {
      ].join('\n'),
    );
    // Create env and heartbeat files for coder0
-    await writeFile(
+    await writeFile(join(dir, 'fleet', 'agents', 'coder0.env'), 'MOSAIC_AGENT_NAME=coder0\n');
      join(dir, 'fleet', 'agents', 'coder0.env.generated'),
      'MOSAIC_AGENT_NAME=coder0\n',
    );
    await writeFile(join(dir, 'fleet', 'run', 'coder0.hb'), 'ts=2026-01-01T00:00:00.000Z\n');
    return dir;
  }
@@ -3915,15 +3738,12 @@ describe('fleet remove command', () => {
    await program.parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder0', '--keep-files']);
-    // Generated projection should still exist.
+    // Env file should still exist
-    const envContent = await readFile(
+    const envContent = await readFile(join(home, 'fleet', 'agents', 'coder0.env'), 'utf8');
      join(home, 'fleet', 'agents', 'coder0.env.generated'),
      'utf8',
    );
    expect(envContent).toContain('MOSAIC_AGENT_NAME=coder0');
  });
-  it('generated projection is removed by default (no --keep-files)', async () => {
+  it('env file is removed by default (no --keep-files)', async () => {
    home = await makeHome();
    const runner: CommandRunner = async () => ({ stdout: '', stderr: '', exitCode: 0 });
    const program = new Command();
@@ -3932,9 +3752,7 @@ describe('fleet remove command', () => {
    await program.parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder0']);
-    await expect(
+    await expect(readFile(join(home, 'fleet', 'agents', 'coder0.env'), 'utf8')).rejects.toThrow();
      readFile(join(home, 'fleet', 'agents', 'coder0.env.generated'), 'utf8'),
    ).rejects.toThrow();
  });
  it('removing the sole orchestrator throws with a clear error about the guard', async () => {
--- a/packages/mosaic/src/commands/fleet.ts
+++ b/packages/mosaic/src/commands/fleet.ts
@@ -19,16 +19,6 @@ import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
 import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
 import {
  applyPreparedAgentEnvironmentProjection,
  ensureFleetHolderIdentity,
  GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES,
  parseAgentEnvironment,
  prepareAgentEnvironmentProjection,
  renderGeneratedAgentEnvironment,
  writeAgentEnvironmentProjection,
  writeManagedFleetRoster,
 } from '../fleet/generated-env-boundary.js';
 import { registerFleetBacklogCommand } from './fleet-backlog.js';
 import { registerFleetPersonaCommand } from './fleet-personas.js';
 import { registerFleetProfileCommand } from './fleet-profiles.js';
@@ -519,35 +509,50 @@ export async function generateNorthStarMarkdown(repoRoot?: string): Promise<stri
 }
 export function generateAgentEnv(roster: FleetRoster, agent: FleetAgent): string {
  return renderGeneratedAgentEnvironment(generateAgentEnvValues(roster, agent));
 }
 /**
 * Compatibility shim for callers that previously merged site-owned data into a
 * generated file. Local data is validated but never appended to the generated
 * projection, preventing a local override from becoming hidden authority.
 */
 export function mergeAgentEnv(generatedEnv: string, existingEnv?: string): string {
  parseAgentEnvironment(generatedEnv, 'generated');
  if (existingEnv?.trim()) parseAgentEnvironment(existingEnv, 'local');
  return generatedEnv;
 }
 function generateAgentEnvValues(
  roster: FleetRoster,
  agent: FleetAgent,
 ): Readonly<Record<string, string>> {
  const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
-  return {
+  return [
-    MOSAIC_AGENT_NAME: agent.name,
+    `MOSAIC_AGENT_NAME=${shellEnvValue(agent.name)}`,
-    MOSAIC_AGENT_CLASS: agent.className,
+    // Per-agent class → start-agent-session.sh / launcher reads this to inject the
-    MOSAIC_AGENT_RUNTIME: agent.runtime,
+    // matching persona contract for the agent's class (default `worker`).
-    MOSAIC_AGENT_MODEL: agent.modelHint ?? '',
+    `MOSAIC_AGENT_CLASS=${shellEnvValue(agent.className)}`,
-    MOSAIC_AGENT_REASONING: agent.reasoningLevel ?? '',
+    `MOSAIC_AGENT_RUNTIME=${shellEnvValue(agent.runtime)}`,
-    MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy ?? '',
+    // Per-agent model hint → start-agent-session.sh appends `--model <hint>` to
-    MOSAIC_AGENT_WORKDIR: expandHome(workingDirectory),
+    // the `mosaic yolo` launch so workers run on the roster's model (e.g. pi on
-    MOSAIC_TMUX_SOCKET: roster.tmux.socketName,
+    // openai-codex/gpt-5.5:high). Empty when the agent declares no model_hint.
-  };
+    `MOSAIC_AGENT_MODEL=${shellEnvValue(agent.modelHint ?? '')}`,
    ...(agent.reasoningLevel !== undefined
      ? [`MOSAIC_AGENT_REASONING=${shellEnvValue(agent.reasoningLevel)}`]
      : []),
    ...(agent.toolPolicy !== undefined
      ? [`MOSAIC_AGENT_TOOL_POLICY=${shellEnvValue(agent.toolPolicy)}`]
      : []),
    `MOSAIC_AGENT_WORKDIR=${shellEnvValue(expandHome(workingDirectory))}`,
    `MOSAIC_TMUX_SOCKET=${shellEnvValue(roster.tmux.socketName)}`,
    '',
  ].join('\n');
 }
 export function mergeAgentEnv(generatedEnv: string, existingEnv?: string): string {
  if (!existingEnv?.trim()) {
    return generatedEnv;
  }
  const generatedKeys = new Set(
    generatedEnv
      .split('\n')
      .map((line) => line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1])
      .filter((key): key is string => key !== undefined),
  );
  const preservedLines = existingEnv.split('\n').filter((line) => {
    if (!line.trim()) {
      return false;
    }
    const key = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1];
    return key === undefined || !generatedKeys.has(key);
  });
  if (preservedLines.length === 0) {
    return generatedEnv;
  }
  return [generatedEnv.trimEnd(), ...preservedLines, ''].join('\n');
 }
 export function buildFleetServiceCommand(action: FleetServiceAction, agentName?: string): string[] {
@@ -1539,12 +1544,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
          `Fleet roster already exists: ${destination}. Re-run with --force to overwrite.`,
        );
      }
-      if (resolve(destination) === resolve(activePaths.rosterPath)) {
+      await mkdir(dirname(destination), { recursive: true });
-        await writeManagedFleetRoster(activePaths.mosaicHome, destination, content);
+      await writeFile(destination, content);
      } else {
        await mkdir(dirname(destination), { recursive: true });
        await writeFile(destination, content);
      }
      // Guarantee the two-agent floor: exactly one orchestrator AND at least
      // one enhancer for every profile except the sanctioned no-orchestrator
@@ -1947,17 +1948,15 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
        };
        const updatedRoster = addAgentToRoster(roster, newAgent);
        const generated = generateAgentEnvValues(updatedRoster, newAgent);
        // Preflight every deterministic projection, local, legacy, quarantine,
        // and managed-directory condition before roster authority changes.
        const preparedProjection = await prepareAgentEnvironmentProjection({
          mosaicHome: activePaths.mosaicHome,
          agentEnvDir: activePaths.agentEnvDir,
          agentName: name,
          generated,
        });
        await writeFile(rosterPath, serializeRosterToYaml(updatedRoster));
-        await applyPreparedAgentEnvironmentProjection(preparedProjection);
+
        const envPath = join(activePaths.agentEnvDir, `${name}.env`);
        const existingEnv = (await canRead(envPath)) ? await readFile(envPath, 'utf8') : undefined;
        await mkdir(activePaths.agentEnvDir, { recursive: true });
        await writeFile(
          envPath,
          mergeAgentEnv(generateAgentEnv(updatedRoster, newAgent), existingEnv),
        );
        console.log(`Added ${name} (${opts.runtime}/${opts.class}) to the fleet.`);
@@ -2038,11 +2037,10 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
      // Write updated roster
      await writeFile(rosterPath, serializeRosterToYaml(updatedRoster));
-      // Delete the non-authoritative generated projection and heartbeat files
+      // Delete env and heartbeat files (best-effort, non-fatal)
      // (best-effort, non-fatal). Operator local/quarantine data is retained.
      if (!opts.keepFiles) {
        try {
-          await unlink(join(activePaths.agentEnvDir, `${name}.env.generated`));
+          await unlink(join(activePaths.agentEnvDir, `${name}.env`));
        } catch {
          // best-effort
        }
@@ -2330,17 +2328,16 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
  const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
  assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
  const roster = await loadRosterForCommand(cmd);
  await ensureFleetHolderIdentity(activePaths.mosaicHome);
  await mkdir(activePaths.fleetToolsDir, { recursive: true });
  await mkdir(activePaths.tmuxToolsDir, { recursive: true });
  await mkdir(activePaths.systemdUserDir, { recursive: true });
  await mkdir(activePaths.agentEnvDir, { recursive: true });
  const startAgentSessionPath = join(activePaths.fleetToolsDir, 'start-agent-session.sh');
  const startInteractionServicePath = join(
    activePaths.fleetToolsDir,
    'start-interaction-service.sh',
  );
  const startTmuxHolderPath = join(activePaths.fleetToolsDir, 'start-tmux-holder.sh');
  const printInteractionPolicyPath = join(
    activePaths.fleetToolsDir,
    'print-interaction-effective-policy.sh',
@@ -2350,7 +2347,6 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
  const executableToolPaths = [
    startAgentSessionPath,
    startInteractionServicePath,
    startTmuxHolderPath,
    printInteractionPolicyPath,
    sendMessagePath,
    agentSendPath,
@@ -2363,10 +2359,6 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
    join(frameworkRoot, 'tools', 'fleet', 'start-interaction-service.sh'),
    startInteractionServicePath,
  );
  await copyFile(
    join(frameworkRoot, 'tools', 'fleet', 'start-tmux-holder.sh'),
    startTmuxHolderPath,
  );
  await copyFile(
    join(frameworkRoot, 'tools', 'fleet', 'print-interaction-effective-policy.sh'),
    printInteractionPolicyPath,
@@ -2390,12 +2382,9 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
  );
  for (const agent of roster.agents) {
-    await writeAgentEnvironmentProjection({
+    const envPath = join(activePaths.agentEnvDir, `${agent.name}.env`);
-      mosaicHome: activePaths.mosaicHome,
+    const existingEnv = (await canRead(envPath)) ? await readFile(envPath, 'utf8') : undefined;
-      agentEnvDir: activePaths.agentEnvDir,
+    await writeFile(envPath, mergeAgentEnv(generateAgentEnv(roster, agent), existingEnv));
      agentName: agent.name,
      generated: generateAgentEnvValues(roster, agent),
    });
  }
  console.log(`Installed fleet files for ${roster.agents.length} agent(s).`);
@@ -2667,6 +2656,19 @@ function expandHome(path: string): string {
  return path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
 }
 function shellEnvValue(value: string): string {
  // Empty ⇒ a bare `VAR=` (unambiguous empty in a systemd EnvironmentFile and
  // when shell-sourced). Quoting it as '' risks a literal two-char value (e.g.
  // a tmux socket named "''"), which would defeat the default-socket behavior.
  if (value === '') {
    return '';
  }
  if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) {
    return value;
  }
  return `'${value.replaceAll("'", "'\"'\"'")}'`;
 }
 async function stopFleetBestEffort(runner: CommandRunner, agentNames: string[]): Promise<void> {
  const failures: string[] = [];
  for (const agentName of agentNames) {
@@ -2768,8 +2770,13 @@ export function countEnhancers(roster: FleetRoster): number {
 }
 /** Valid runtime identifiers for fleet agents. */
-/** Runtime launchers accepted by `fleet add`; shared with the generated projection validator. */
+export const VALID_FLEET_RUNTIMES: readonly string[] = [
-export const VALID_FLEET_RUNTIMES: readonly string[] = GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES;
+  'pi',
  'claude',
  'codex',
  'opencode',
  'dogfood',
 ];
 /**
 * Add a new agent to a fleet roster (immutable — returns a new FleetRoster).
--- a/packages/mosaic/src/fleet/example-profile-dispositions.spec.ts
+++ b/packages/mosaic/src/fleet/example-profile-dispositions.spec.ts
@@ -1,90 +0,0 @@
 import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
  SHIPPED_FLEET_ARTIFACT_DISPOSITIONS,
  validateShippedFleetArtifactDispositions,
 } from './example-profile-dispositions.js';
 const frameworkFleet = resolve(
  dirname(fileURLToPath(import.meta.url)),
  '..',
  '..',
  'framework',
  'fleet',
 );
 const EXPECTED_DISPOSITIONS = [
  'examples/coding.yaml:v1-fixture',
  'examples/general.yaml:v1-fixture',
  'examples/hybrid.yaml:v1-fixture',
  'examples/local-canary.yaml:v1-fixture',
  'examples/minimal.yaml:v1-fixture',
  'examples/operator-interaction.yaml:v1-fixture',
  'examples/research.yaml:v1-fixture',
  'profiles/business.yaml:canonical-profile',
  'profiles/marketing.yaml:canonical-profile',
  'profiles/personal-assistant.yaml:canonical-profile',
  'profiles/research.yaml:canonical-profile',
  'profiles/software-delivery.yaml:canonical-profile',
  'services/operator-interaction.yaml:canonical-service-policy',
 ];
 const declared = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.map(
  ({ path, disposition }): string => `${path}:${disposition}`,
 );
 describe('shipped fleet example/profile/service disposition validation', (): void => {
  it('enumerates every inventory artifact with an explicit executable disposition', (): void => {
    expect(declared).toEqual(EXPECTED_DISPOSITIONS);
  });
  it('validates every shipped artifact through its declared v1 or canonical path', async (): Promise<void> => {
    const results = await validateShippedFleetArtifactDispositions({ frameworkFleet });
    expect(results.map(({ path, disposition }): string => `${path}:${disposition}`)).toEqual(
      EXPECTED_DISPOSITIONS,
    );
    expect(results.filter(({ disposition }): boolean => disposition === 'v1-fixture')).toHaveLength(
      7,
    );
    expect(
      results.filter(({ disposition }): boolean => disposition === 'canonical-profile'),
    ).toHaveLength(5);
    expect(
      results.find(({ path }): boolean => path === 'services/operator-interaction.yaml'),
    ).toMatchObject({
      disposition: 'canonical-service-policy',
    });
  });
  let temporaryFleet: string | undefined;
  afterEach(async (): Promise<void> => {
    if (temporaryFleet) await rm(temporaryFleet, { recursive: true, force: true });
    temporaryFleet = undefined;
  });
  it('fails closed when a shipped artifact lacks a declared disposition', async (): Promise<void> => {
    temporaryFleet = await mkdtemp(join(tmpdir(), 'mosaic-dispositions-'));
    await cp(frameworkFleet, temporaryFleet, { recursive: true });
    await writeFile(join(temporaryFleet, 'examples', 'undeclared.yaml'), 'version: 1\n');
    await expect(
      validateShippedFleetArtifactDispositions({ frameworkFleet: temporaryFleet }),
    ).rejects.toThrow(/undeclared shipped fleet artifact.*examples\/undeclared.yaml/i);
  });
  it('rejects a v1 fixture when its explicit version declaration is removed', async (): Promise<void> => {
    temporaryFleet = await mkdtemp(join(tmpdir(), 'mosaic-dispositions-'));
    await cp(frameworkFleet, temporaryFleet, { recursive: true });
    const fixturePath = join(temporaryFleet, 'examples', 'coding.yaml');
    const fixture = await readFile(fixturePath, 'utf8');
    await writeFile(fixturePath, fixture.replace(/^version: 1\n/, ''));
    await expect(
      validateShippedFleetArtifactDispositions({ frameworkFleet: temporaryFleet }),
    ).rejects.toThrow(/Fleet roster version must be 1/);
  });
 });
--- a/packages/mosaic/src/fleet/example-profile-dispositions.ts
+++ b/packages/mosaic/src/fleet/example-profile-dispositions.ts
@@ -1,121 +0,0 @@
 import { readdir } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { loadFleetRoster } from '../commands/fleet.js';
 import { loadProfiles } from '../commands/fleet-profiles.js';
 import {
  provisionInteractionService,
  readInteractionServiceProfile,
 } from './interaction-service-profile.js';
 export type FleetArtifactDisposition =
  | 'v1-fixture'
  | 'canonical-profile'
  | 'canonical-service-policy';
 export interface ShippedFleetArtifactDisposition {
  readonly path: string;
  readonly disposition: FleetArtifactDisposition;
 }
 export interface ValidateShippedFleetArtifactDispositionsOptions {
  readonly frameworkFleet: string;
  readonly rolesDir?: string;
  readonly overrideDir?: string;
 }
 /**
 * The M0 inventory in executable form. Every shipped fleet YAML asset is either
 * a deliberately retained v1 fixture or validated through its canonical loader.
 */
 export const SHIPPED_FLEET_ARTIFACT_DISPOSITIONS: readonly ShippedFleetArtifactDisposition[] = [
  { path: 'examples/coding.yaml', disposition: 'v1-fixture' },
  { path: 'examples/general.yaml', disposition: 'v1-fixture' },
  { path: 'examples/hybrid.yaml', disposition: 'v1-fixture' },
  { path: 'examples/local-canary.yaml', disposition: 'v1-fixture' },
  { path: 'examples/minimal.yaml', disposition: 'v1-fixture' },
  { path: 'examples/operator-interaction.yaml', disposition: 'v1-fixture' },
  { path: 'examples/research.yaml', disposition: 'v1-fixture' },
  { path: 'profiles/business.yaml', disposition: 'canonical-profile' },
  { path: 'profiles/marketing.yaml', disposition: 'canonical-profile' },
  { path: 'profiles/personal-assistant.yaml', disposition: 'canonical-profile' },
  { path: 'profiles/research.yaml', disposition: 'canonical-profile' },
  { path: 'profiles/software-delivery.yaml', disposition: 'canonical-profile' },
  { path: 'services/operator-interaction.yaml', disposition: 'canonical-service-policy' },
 ];
 /**
 * Fail closed when a fleet YAML asset is added or removed without a disposition.
 * This keeps legacy v1 compatibility explicit instead of silently accepting new
 * unresolved classes outside the shared resolver.
 */
 export async function validateShippedFleetArtifactDispositions(
  options: ValidateShippedFleetArtifactDispositionsOptions,
 ): Promise<readonly ShippedFleetArtifactDisposition[]> {
  await assertEveryShippedArtifactIsDeclared(options.frameworkFleet);
  const examples = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
    ({ disposition }): boolean => disposition === 'v1-fixture',
  );
  for (const artifact of examples) {
    const roster = await loadFleetRoster(join(options.frameworkFleet, artifact.path));
    if (roster.version !== 1) {
      throw new Error(`v1 fixture ${artifact.path} must declare version: 1`);
    }
  }
  const profilesDir = join(options.frameworkFleet, 'profiles');
  const profiles = await loadProfiles({
    profilesDir,
    rolesDir: options.rolesDir ?? join(options.frameworkFleet, 'roles'),
    overrideDir: options.overrideDir ?? join(options.frameworkFleet, 'roles.local'),
  });
  const declaredProfiles = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
    ({ disposition }): boolean => disposition === 'canonical-profile',
  ).map(({ path }): string => basename(path, '.yaml'));
  const resolvedProfiles = new Set(profiles.map(({ id }): string => id));
  for (const profileId of declaredProfiles) {
    if (!resolvedProfiles.has(profileId)) {
      throw new Error(`declared canonical profile ${profileId} did not resolve`);
    }
  }
  const servicePolicies = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
    ({ disposition }): boolean => disposition === 'canonical-service-policy',
  );
  for (const artifact of servicePolicies) {
    const serviceProfile = await readInteractionServiceProfile(
      join(options.frameworkFleet, artifact.path),
    );
    provisionInteractionService(serviceProfile, { agentName: 'interaction-example' });
  }
  return SHIPPED_FLEET_ARTIFACT_DISPOSITIONS;
 }
 async function assertEveryShippedArtifactIsDeclared(frameworkFleet: string): Promise<void> {
  const declared = new Set(SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.map(({ path }): string => path));
  const shipped = await listShippedFleetArtifactPaths(frameworkFleet);
  for (const path of shipped) {
    if (!declared.has(path)) {
      throw new Error(`undeclared shipped fleet artifact: ${path}`);
    }
  }
  for (const path of declared) {
    if (!shipped.has(path)) {
      throw new Error(`declared shipped fleet artifact is missing: ${path}`);
    }
  }
 }
 async function listShippedFleetArtifactPaths(frameworkFleet: string): Promise<Set<string>> {
  const directories = ['examples', 'profiles', 'services'];
  const paths = new Set<string>();
  for (const directory of directories) {
    const files = await readdir(join(frameworkFleet, directory));
    for (const file of files) {
      if (file.endsWith('.yaml') || file.endsWith('.yml')) paths.add(`${directory}/${file}`);
    }
  }
  return paths;
 }
--- a/packages/mosaic/src/fleet/generated-env-boundary.spec.ts
+++ b/packages/mosaic/src/fleet/generated-env-boundary.spec.ts
@@ -1,279 +0,0 @@
 import {
  chmod,
  mkdir,
  mkdtemp,
  readFile,
  rename,
  rm,
  stat,
  symlink,
  writeFile,
 } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
  AgentEnvBoundaryError,
  parseAgentEnvironment,
  renderGeneratedAgentEnvironment,
  writeAgentEnvironmentProjection,
 } from './generated-env-boundary.js';
 const generatedValues = {
  MOSAIC_AGENT_NAME: 'coder0',
  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: '/srv/mosaic',
  MOSAIC_TMUX_SOCKET: 'mosaic-fleet',
 };
 describe('generated fleet agent environment boundary', (): void => {
  let cleanup: string | undefined;
  afterEach(async (): Promise<void> => {
    if (cleanup) {
      await rm(cleanup, { recursive: true, force: true });
      cleanup = undefined;
    }
  });
  it('renders a deterministic complete generated projection', (): void => {
    expect(renderGeneratedAgentEnvironment(generatedValues)).toBe(
      [
        'MOSAIC_AGENT_NAME=coder0',
        '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=/srv/mosaic',
        'MOSAIC_TMUX_SOCKET=mosaic-fleet',
        '',
      ].join('\n'),
    );
  });
  it.each([
    ['generated-key shadowing', 'MOSAIC_AGENT_RUNTIME=codex\n'],
    ['unknown key', 'UNRELATED_SETTING=value\n'],
    ['arbitrary command', 'MOSAIC_AGENT_COMMAND=mosaic yolo codex\n'],
    ['sensitive key', 'MOSAIC_AGENT_TOKEN=do-not-log-me\n'],
    ['malformed syntax', 'export MOSAIC_RUNTIME_BIN=/opt/bin\n'],
    ['duplicate keys', 'MOSAIC_RUNTIME_BIN=/opt/bin\nMOSAIC_RUNTIME_BIN=/other/bin\n'],
  ])('rejects local %s without echoing values', (_name: string, source: string): void => {
    let error: unknown;
    try {
      parseAgentEnvironment(source, 'local');
    } catch (caught: unknown) {
      error = caught;
    }
    expect(error).toBeInstanceOf(AgentEnvBoundaryError);
    expect(String(error)).not.toContain('mosaic yolo codex');
    expect(String(error)).not.toContain('do-not-log-me');
    expect(String(error)).toMatch(/key=.*sha256=/);
  });
  it('rejects unsafe generated paths before any launch consumer can use them', (): void => {
    expect((): void => {
      renderGeneratedAgentEnvironment({
        ...generatedValues,
        MOSAIC_AGENT_WORKDIR: '../outside',
      });
    }).toThrow(AgentEnvBoundaryError);
  });
  it('creates missing managed directories privately before writing a projection', async (): Promise<void> => {
    cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
    const mosaicHome = join(cleanup, 'mosaic');
    const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
    const result = await writeAgentEnvironmentProjection({
      mosaicHome,
      agentEnvDir,
      agentName: 'coder0',
      generated: generatedValues,
    });
    for (const directory of [mosaicHome, join(mosaicHome, 'fleet'), agentEnvDir]) {
      expect((await stat(directory)).mode & 0o777).toBe(0o700);
    }
    expect((await stat(result.generatedPath)).mode & 0o777).toBe(0o600);
  });
  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');
    const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
    await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
    await writeFile(
      join(agentEnvDir, 'coder0.env'),
      [
        'MOSAIC_AGENT_NAME=stale-name',
        'MOSAIC_AGENT_RUNTIME=codex',
        'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin',
        'MOSAIC_AGENT_COMMAND=mosaic yolo codex --dangerous',
        '',
      ].join('\n'),
      { mode: 0o600 },
    );
    const result = await writeAgentEnvironmentProjection({
      mosaicHome,
      agentEnvDir,
      agentName: 'coder0',
      generated: generatedValues,
    });
    expect(await readFile(result.generatedPath, 'utf8')).toBe(
      renderGeneratedAgentEnvironment(generatedValues),
    );
    expect(await readFile(result.localPath, 'utf8')).toBe('MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n');
    const quarantine = await readFile(result.quarantinePath!, 'utf8');
    expect(quarantine).toContain('MOSAIC_AGENT_COMMAND=mosaic yolo codex --dangerous');
    await expect(readFile(join(agentEnvDir, 'coder0.env'), 'utf8')).rejects.toThrow();
    expect((await stat(result.generatedPath)).mode & 0o077).toBe(0);
    expect((await stat(result.localPath)).mode & 0o077).toBe(0);
    expect(result.diagnostics).toEqual([expect.objectContaining({ key: 'MOSAIC_AGENT_COMMAND' })]);
    expect(JSON.stringify(result.diagnostics)).not.toContain('mosaic yolo codex --dangerous');
  });
  it('fails closed on an existing local override with unsafe permissions', async (): Promise<void> => {
    cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
    const mosaicHome = join(cleanup, 'mosaic');
    const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
    await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
    const localPath = join(agentEnvDir, 'coder0.env.local');
    await writeFile(localPath, 'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n', { mode: 0o600 });
    await chmod(localPath, 0o644);
    await expect(
      writeAgentEnvironmentProjection({
        mosaicHome,
        agentEnvDir,
        agentName: 'coder0',
        generated: generatedValues,
      }),
    ).rejects.toThrow(/permissions/i);
  });
  it('rejects an existing group/world-accessible projection directory before reading it', async (): Promise<void> => {
    cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
    const mosaicHome = join(cleanup, 'mosaic');
    const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
    const localPath = join(agentEnvDir, 'coder0.env.local');
    const generatedPath = join(agentEnvDir, 'coder0.env.generated');
    await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
    await writeFile(localPath, 'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n', { mode: 0o600 });
    await chmod(agentEnvDir, 0o777);
    await expect(
      writeAgentEnvironmentProjection({
        mosaicHome,
        agentEnvDir,
        agentName: 'coder0',
        generated: generatedValues,
      }),
    ).rejects.toThrow(/unsafe-permissions/i);
    await expect(readFile(localPath, 'utf8')).resolves.toBe('MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n');
    await expect(readFile(generatedPath, 'utf8')).rejects.toThrow();
  });
  it.each([
    ['MOSAIC_HOME', 'symlink'],
    ['MOSAIC_HOME/fleet', 'symlink'],
    ['MOSAIC_HOME/fleet/agents', 'symlink'],
    ['MOSAIC_HOME', 'group/world-writable'],
    ['MOSAIC_HOME/fleet', 'group/world-writable'],
    ['MOSAIC_HOME/fleet/agents', 'group/world-writable'],
  ])(
    'rejects a %s %s managed ancestor before any projection mutation',
    async (ancestor: string, hazard: string): Promise<void> => {
      cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
      const mosaicHome = join(cleanup, 'mosaic');
      const fleetDir = join(mosaicHome, 'fleet');
      const agentEnvDir = join(fleetDir, 'agents');
      const generatedPath = join(agentEnvDir, 'coder0.env.generated');
      const localPath = join(agentEnvDir, 'coder0.env.local');
      const legacyPath = join(agentEnvDir, 'coder0.env');
      const quarantinePath = join(agentEnvDir, 'coder0.env.quarantine');
      const managedPaths: Record<string, string> = {
        MOSAIC_HOME: mosaicHome,
        'MOSAIC_HOME/fleet': fleetDir,
        'MOSAIC_HOME/fleet/agents': agentEnvDir,
      };
      const unsafePath = managedPaths[ancestor];
      if (unsafePath === undefined) throw new Error(`Unknown managed ancestor: ${ancestor}`);
      await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
      await chmod(mosaicHome, 0o700);
      await chmod(fleetDir, 0o700);
      await chmod(agentEnvDir, 0o700);
      await writeFile(generatedPath, 'generated-before\n', { mode: 0o600 });
      await writeFile(localPath, 'MOSAIC_RUNTIME_BIN=/safe/runtime\n', { mode: 0o600 });
      await writeFile(legacyPath, 'MOSAIC_AGENT_COMMAND=legacy-command\n', { mode: 0o600 });
      if (hazard === 'symlink') {
        const targetPath = `${unsafePath}-target`;
        await rename(unsafePath, targetPath);
        await symlink(targetPath, unsafePath, 'dir');
      } else {
        await chmod(unsafePath, 0o777);
      }
      await expect(
        writeAgentEnvironmentProjection({
          mosaicHome,
          agentEnvDir,
          agentName: 'coder0',
          generated: generatedValues,
        }),
      ).rejects.toThrow(/unsafe-(directory|permissions)/i);
      await expect(readFile(generatedPath, 'utf8')).resolves.toBe('generated-before\n');
      await expect(readFile(localPath, 'utf8')).resolves.toBe('MOSAIC_RUNTIME_BIN=/safe/runtime\n');
      await expect(readFile(legacyPath, 'utf8')).resolves.toBe(
        'MOSAIC_AGENT_COMMAND=legacy-command\n',
      );
      await expect(readFile(quarantinePath, 'utf8')).rejects.toThrow();
    },
  );
  it('rejects a symlinked projection directory without mutating its target', async (): Promise<void> => {
    cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
    const mosaicHome = join(cleanup, 'mosaic');
    const targetDirectory = join(cleanup, 'target');
    const linkedDirectory = join(mosaicHome, 'fleet', 'agents');
    const legacyPath = join(targetDirectory, 'coder0.env');
    const generatedPath = join(targetDirectory, 'coder0.env.generated');
    const localPath = join(targetDirectory, 'coder0.env.local');
    const quarantinePath = join(targetDirectory, 'coder0.env.quarantine');
    await mkdir(join(mosaicHome, 'fleet'), { recursive: true, mode: 0o700 });
    await mkdir(targetDirectory, { mode: 0o700 });
    await writeFile(legacyPath, 'MOSAIC_AGENT_COMMAND=legacy-command\n', { mode: 0o600 });
    await writeFile(generatedPath, 'generated-before\n', { mode: 0o600 });
    await writeFile(localPath, 'local-before\n', { mode: 0o600 });
    await writeFile(quarantinePath, 'quarantine-before\n', { mode: 0o600 });
    await symlink(targetDirectory, linkedDirectory, 'dir');
    await expect(
      writeAgentEnvironmentProjection({
        mosaicHome,
        agentEnvDir: linkedDirectory,
        agentName: 'coder0',
        generated: generatedValues,
      }),
    ).rejects.toThrow(/unsafe-directory/i);
    await expect(readFile(legacyPath, 'utf8')).resolves.toBe(
      'MOSAIC_AGENT_COMMAND=legacy-command\n',
    );
    await expect(readFile(generatedPath, 'utf8')).resolves.toBe('generated-before\n');
    await expect(readFile(localPath, 'utf8')).resolves.toBe('local-before\n');
    await expect(readFile(quarantinePath, 'utf8')).resolves.toBe('quarantine-before\n');
  });
 });
--- a/packages/mosaic/src/fleet/generated-env-boundary.ts
+++ b/packages/mosaic/src/fleet/generated-env-boundary.ts
@@ -1,509 +0,0 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 export type AgentEnvironmentKind = 'generated' | 'local';
 export interface AgentEnvironmentDiagnostic {
  readonly code: string;
  readonly key: string;
  readonly sha256: string;
 }
 export interface AgentEnvironmentProjectionOptions {
  readonly mosaicHome: string;
  readonly agentEnvDir: string;
  readonly agentName: string;
  readonly generated: Readonly<Record<string, string>>;
 }
 export interface AgentEnvironmentProjectionResult {
  readonly generatedPath: string;
  readonly localPath: string;
  readonly quarantinePath?: string;
  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
 /** A projection fully validated without changing managed files. */
 export interface PreparedAgentEnvironmentProjection {
  readonly mosaicHome: string;
  readonly agentEnvDir: string;
  readonly generatedPath: string;
  readonly localPath: string;
  readonly legacyPath: string;
  readonly generated: string;
  readonly local: string;
  readonly legacy?: string;
  readonly quarantinePath?: string;
  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
 export class AgentEnvBoundaryError extends Error {
  readonly diagnostic: AgentEnvironmentDiagnostic;
  constructor(code: string, key: string, value: string) {
    const diagnostic: AgentEnvironmentDiagnostic = {
      code,
      key,
      sha256: hashValue(value),
    };
    super(`Agent environment rejected: code=${code} key=${key} sha256=${diagnostic.sha256}`);
    this.name = 'AgentEnvBoundaryError';
    this.diagnostic = diagnostic;
  }
 }
 export const GENERATED_AGENT_ENV_KEYS = [
  'MOSAIC_AGENT_NAME',
  'MOSAIC_AGENT_CLASS',
  'MOSAIC_AGENT_RUNTIME',
  'MOSAIC_AGENT_MODEL',
  'MOSAIC_AGENT_REASONING',
  'MOSAIC_AGENT_TOOL_POLICY',
  'MOSAIC_AGENT_WORKDIR',
  'MOSAIC_TMUX_SOCKET',
 ] as const;
 export const LOCAL_AGENT_ENV_KEYS = [
  'MOSAIC_RUNTIME_BIN',
  'MOSAIC_HEARTBEAT_RUN_DIR',
  'MOSAIC_HEARTBEAT_INTERVAL',
  'MOSAIC_CLAUDE_JSON',
  'CLAUDE_CONFIG_DIR',
 ] as const;
 const GENERATED_KEY_SET = new Set<string>(GENERATED_AGENT_ENV_KEYS);
 const LOCAL_KEY_SET = new Set<string>(LOCAL_AGENT_ENV_KEYS);
 const SENSITIVE_KEY = /(?:API[_-]?KEY|AUTH|CREDENTIAL|PASSWORD|PRIVATE|SECRET|TOKEN)/i;
 const AGENT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 const POLICY_NAME = /^[a-z][a-z0-9-]*$/;
 const TMUX_SOCKET = /^[A-Za-z0-9_.-]*$/;
 const MODEL = /^[A-Za-z0-9._/:+-]*$/;
 /** Runtime launchers supported by the generated environment contract. */
 export const GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES = [
  'claude',
  'codex',
  'opencode',
  'pi',
 ] as const;
 const SUPPORTED_RUNTIMES = new Set<string>(GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES);
 const REASONING = new Set(['', 'low', 'medium', 'high']);
 /** Parses a strict data-only generated or local environment file without shell evaluation. */
 export function parseAgentEnvironment(
  source: string,
  kind: AgentEnvironmentKind,
 ): Readonly<Record<string, string>> {
  const values: Record<string, string> = {};
  const seen = new Set<string>();
  for (const line of source.split('\n')) {
    if (line === '') continue;
    const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);
    if (!match) throw new AgentEnvBoundaryError('malformed-line', '(malformed)', line);
    const [, key, value] = match;
    if (key === undefined || value === undefined) {
      throw new AgentEnvBoundaryError('malformed-line', '(malformed)', line);
    }
    if (seen.has(key)) throw new AgentEnvBoundaryError('duplicate-key', key, value);
    seen.add(key);
    if (SENSITIVE_KEY.test(key)) throw new AgentEnvBoundaryError('sensitive-key', key, value);
    if (containsShellSyntax(value)) throw new AgentEnvBoundaryError('unsafe-value', key, value);
    if (kind === 'generated') {
      if (!GENERATED_KEY_SET.has(key)) throw new AgentEnvBoundaryError('unknown-key', key, value);
    } else {
      if (GENERATED_KEY_SET.has(key))
        throw new AgentEnvBoundaryError('generated-key-shadow', key, value);
      if (!LOCAL_KEY_SET.has(key)) throw new AgentEnvBoundaryError('unknown-key', key, value);
    }
    values[key] = value;
  }
  if (kind === 'generated') assertGeneratedValues(values);
  else assertLocalValues(values);
  return Object.freeze(values);
 }
 /** Renders the roster-derived generated projection in a stable, complete key order. */
 export function renderGeneratedAgentEnvironment(values: Readonly<Record<string, string>>): string {
  const normalized = normalizeGeneratedValues(values);
  return `${GENERATED_AGENT_ENV_KEYS.map((key): string => `${key}=${normalized[key]}`).join('\n')}\n`;
 }
 /** Validates all deterministic projection inputs and target state without mutation. */
 export async function prepareAgentEnvironmentProjection(
  options: AgentEnvironmentProjectionOptions,
 ): Promise<PreparedAgentEnvironmentProjection> {
  if (!AGENT_NAME.test(options.agentName)) {
    throw new AgentEnvBoundaryError('unsafe-agent-name', 'MOSAIC_AGENT_NAME', options.agentName);
  }
  await validatePrivateProjectionDirectory(options.mosaicHome, options.agentEnvDir);
  const generatedPath = join(options.agentEnvDir, `${options.agentName}.env.generated`);
  const localPath = join(options.agentEnvDir, `${options.agentName}.env.local`);
  const legacyPath = join(options.agentEnvDir, `${options.agentName}.env`);
  const generated = renderGeneratedAgentEnvironment(options.generated);
  await assertPrivateRegularFileIfPresent(generatedPath);
  const currentLocal = await readOptionalPrivateFile(localPath);
  const parsedLocal =
    currentLocal === undefined ? {} : parseAgentEnvironment(currentLocal, 'local');
  const legacy = await readOptionalPrivateFile(legacyPath);
  const legacyDisposition =
    legacy === undefined ? emptyLegacyDisposition() : classifyLegacyEnvironment(legacy);
  for (const [key, value] of Object.entries(legacyDisposition.localValues)) {
    if (parsedLocal[key] !== undefined && parsedLocal[key] !== value) {
      throw new AgentEnvBoundaryError('legacy-local-conflict', key, value);
    }
  }
  const local = renderLocalAgentEnvironment({ ...legacyDisposition.localValues, ...parsedLocal });
  const quarantinePath = legacyDisposition.diagnostics.length
    ? join(options.agentEnvDir, `${options.agentName}.env.quarantine`)
    : undefined;
  if (quarantinePath !== undefined) {
    const existingQuarantine = await readOptionalPrivateFile(quarantinePath);
    if (existingQuarantine !== undefined) {
      throw new AgentEnvBoundaryError('quarantine-exists', '(quarantine)', existingQuarantine);
    }
  }
  return {
    mosaicHome: options.mosaicHome,
    agentEnvDir: options.agentEnvDir,
    generatedPath,
    localPath,
    legacyPath,
    generated,
    local,
    ...(legacy === undefined ? {} : { legacy }),
    ...(quarantinePath === undefined ? {} : { quarantinePath }),
    diagnostics: legacyDisposition.diagnostics,
  };
 }
 /** Applies a previously prepared deterministic projection. */
 export async function applyPreparedAgentEnvironmentProjection(
  prepared: PreparedAgentEnvironmentProjection,
 ): Promise<AgentEnvironmentProjectionResult> {
  await ensurePrivateProjectionDirectory(prepared.mosaicHome, prepared.agentEnvDir);
  await writePrivateAtomically(prepared.generatedPath, prepared.generated);
  if (prepared.local !== '') await writePrivateAtomically(prepared.localPath, prepared.local);
  if (prepared.quarantinePath !== undefined && prepared.legacy !== undefined) {
    await writePrivateAtomically(prepared.quarantinePath, prepared.legacy);
  }
  if (prepared.legacy !== undefined) await unlink(prepared.legacyPath);
  return {
    generatedPath: prepared.generatedPath,
    localPath: prepared.localPath,
    ...(prepared.quarantinePath === undefined ? {} : { quarantinePath: prepared.quarantinePath }),
    diagnostics: prepared.diagnostics,
  };
 }
 /** Writes deterministic projection files and explicitly removes legacy `.env` authority. */
 export async function writeAgentEnvironmentProjection(
  options: AgentEnvironmentProjectionOptions,
 ): Promise<AgentEnvironmentProjectionResult> {
  return applyPreparedAgentEnvironmentProjection(await prepareAgentEnvironmentProjection(options));
 }
 /** Creates the canonical managed roster path with private fresh-chain permissions. */
 export async function writeManagedFleetRoster(
  mosaicHome: string,
  rosterPath: string,
  content: string,
 ): Promise<void> {
  const fleetDir = join(mosaicHome, 'fleet');
  const expectedRosterPath = join(fleetDir, 'roster.yaml');
  if (resolve(rosterPath) !== resolve(expectedRosterPath)) {
    throw new AgentEnvBoundaryError('unsafe-file', '(roster)', rosterPath);
  }
  await ensureManagedDirectory(mosaicHome, false);
  await ensureManagedDirectory(fleetDir, false);
  await writePrivateAtomically(rosterPath, content);
 }
 /** Ensures the private install-derived identity used to own a named tmux server. */
 export async function ensureFleetHolderIdentity(mosaicHome: string): Promise<string> {
  const fleetDir = join(mosaicHome, 'fleet');
  const runDir = join(fleetDir, 'run');
  const identityPath = join(runDir, 'holder-owner');
  await ensureManagedDirectory(mosaicHome, false);
  await ensureManagedDirectory(fleetDir, false);
  await ensureManagedDirectory(runDir, true);
  const existing = await readOptionalPrivateFile(identityPath);
  if (existing !== undefined) {
    const identity = existing.trim();
    if (!/^[a-f0-9-]{36}$/.test(identity)) {
      throw new AgentEnvBoundaryError('unsafe-owner-identity', '(holder-owner)', existing);
    }
    return identity;
  }
  const identity = randomUUID();
  await writePrivateAtomically(identityPath, `${identity}\n`);
  return identity;
 }
 function normalizeGeneratedValues(
  values: Readonly<Record<string, string>>,
 ): Readonly<Record<string, string>> {
  const normalized: Record<string, string> = {};
  for (const key of GENERATED_AGENT_ENV_KEYS) {
    const value = values[key];
    if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
    normalized[key] = value;
  }
  for (const [key, value] of Object.entries(values)) {
    if (!GENERATED_KEY_SET.has(key)) throw new AgentEnvBoundaryError('unknown-key', key, value);
  }
  assertGeneratedValues(normalized);
  return Object.freeze(normalized);
 }
 function renderLocalAgentEnvironment(values: Readonly<Record<string, string>>): string {
  if (Object.keys(values).length === 0) return '';
  const parsed = parseAgentEnvironment(
    Object.entries(values)
      .sort(([left], [right]): number => left.localeCompare(right))
      .map(([key, value]): string => `${key}=${value}`)
      .join('\n'),
    'local',
  );
  return `${Object.entries(parsed)
    .sort(([left], [right]): number => left.localeCompare(right))
    .map(([key, value]): string => `${key}=${value}`)
    .join('\n')}\n`;
 }
 function assertGeneratedValues(values: Readonly<Record<string, string>>): void {
  for (const key of GENERATED_AGENT_ENV_KEYS) {
    const value = values[key];
    if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
  }
  const name = requiredGeneratedValue(values, 'MOSAIC_AGENT_NAME');
  const className = requiredGeneratedValue(values, 'MOSAIC_AGENT_CLASS');
  const runtime = requiredGeneratedValue(values, 'MOSAIC_AGENT_RUNTIME');
  const model = requiredGeneratedValue(values, 'MOSAIC_AGENT_MODEL');
  const reasoning = requiredGeneratedValue(values, 'MOSAIC_AGENT_REASONING');
  const toolPolicy = requiredGeneratedValue(values, 'MOSAIC_AGENT_TOOL_POLICY');
  const workingDirectory = requiredGeneratedValue(values, 'MOSAIC_AGENT_WORKDIR');
  const socket = requiredGeneratedValue(values, 'MOSAIC_TMUX_SOCKET');
  if (!AGENT_NAME.test(name))
    throw new AgentEnvBoundaryError('unsafe-agent-name', 'MOSAIC_AGENT_NAME', name);
  if (!POLICY_NAME.test(className)) {
    throw new AgentEnvBoundaryError('unsafe-class', 'MOSAIC_AGENT_CLASS', className);
  }
  if (!SUPPORTED_RUNTIMES.has(runtime)) {
    throw new AgentEnvBoundaryError('unsupported-runtime', 'MOSAIC_AGENT_RUNTIME', runtime);
  }
  if (!MODEL.test(model))
    throw new AgentEnvBoundaryError('unsafe-model', 'MOSAIC_AGENT_MODEL', model);
  if (!REASONING.has(reasoning)) {
    throw new AgentEnvBoundaryError('unsupported-reasoning', 'MOSAIC_AGENT_REASONING', reasoning);
  }
  if (toolPolicy !== '' && !POLICY_NAME.test(toolPolicy)) {
    throw new AgentEnvBoundaryError('unsafe-tool-policy', 'MOSAIC_AGENT_TOOL_POLICY', toolPolicy);
  }
  if (!isSafeAbsolutePath(workingDirectory)) {
    throw new AgentEnvBoundaryError('unsafe-path', 'MOSAIC_AGENT_WORKDIR', workingDirectory);
  }
  if (!TMUX_SOCKET.test(socket)) {
    throw new AgentEnvBoundaryError('unsafe-socket', 'MOSAIC_TMUX_SOCKET', socket);
  }
 }
 function requiredGeneratedValue(values: Readonly<Record<string, string>>, key: string): string {
  const value = values[key];
  if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
  return value;
 }
 function assertLocalValues(values: Readonly<Record<string, string>>): void {
  for (const [key, value] of Object.entries(values)) {
    if (key === 'MOSAIC_HEARTBEAT_INTERVAL') {
      if (!/^[1-9][0-9]*$/.test(value)) {
        throw new AgentEnvBoundaryError('invalid-interval', key, value);
      }
      continue;
    }
    if (!isSafeAbsolutePath(value)) throw new AgentEnvBoundaryError('unsafe-path', key, value);
  }
 }
 function isSafeAbsolutePath(value: string): boolean {
  return (
    value.startsWith('/') && !value.split('/').includes('..') && !/[\s"'`$\\;&|<>(){}]/.test(value)
  );
 }
 function containsShellSyntax(value: string): boolean {
  return /["'`$\\;&|<>(){}]/.test(value);
 }
 interface LegacyDisposition {
  readonly localValues: Readonly<Record<string, string>>;
  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
 function emptyLegacyDisposition(): LegacyDisposition {
  return { localValues: {}, diagnostics: [] };
 }
 function classifyLegacyEnvironment(source: string): LegacyDisposition {
  const localValues: Record<string, string> = {};
  const diagnostics: AgentEnvironmentDiagnostic[] = [];
  const seen = new Set<string>();
  for (const line of source.split('\n')) {
    if (line === '') continue;
    const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);
    if (!match || match[1] === undefined || match[2] === undefined) {
      diagnostics.push(diagnostic('malformed-line', '(malformed)', line));
      continue;
    }
    const [, key, value] = match;
    if (seen.has(key)) {
      diagnostics.push(diagnostic('duplicate-key', key, value));
      continue;
    }
    seen.add(key);
    if (GENERATED_KEY_SET.has(key)) continue;
    try {
      parseAgentEnvironment(`${key}=${value}\n`, 'local');
      localValues[key] = value;
    } catch (error: unknown) {
      if (error instanceof AgentEnvBoundaryError) diagnostics.push(error.diagnostic);
      else throw error;
    }
  }
  return { localValues: Object.freeze(localValues), diagnostics: Object.freeze(diagnostics) };
 }
 function diagnostic(code: string, key: string, value: string): AgentEnvironmentDiagnostic {
  return { code, key, sha256: hashValue(value) };
 }
 function hashValue(value: string): string {
  return createHash('sha256').update(value).digest('hex');
 }
 async function readOptionalPrivateFile(path: string): Promise<string | undefined> {
  try {
    await assertPrivateRegularFile(path);
    return await readFile(path, 'utf8');
  } catch (error: unknown) {
    if (isMissingFile(error)) return undefined;
    throw error;
  }
 }
 function isMissingFile(error: unknown): boolean {
  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
 async function validatePrivateProjectionDirectory(
  mosaicHome: string,
  agentEnvDir: string,
 ): Promise<void> {
  const fleetDir = join(mosaicHome, 'fleet');
  const expectedAgentEnvDir = join(fleetDir, 'agents');
  if (resolve(agentEnvDir) !== resolve(expectedAgentEnvDir)) {
    throw new AgentEnvBoundaryError('unsafe-directory', '(directory)', agentEnvDir);
  }
  await assertManagedDirectoryIfPresent(mosaicHome, false);
  await assertManagedDirectoryIfPresent(fleetDir, false);
  await assertManagedDirectoryIfPresent(agentEnvDir, true);
 }
 async function ensurePrivateProjectionDirectory(
  mosaicHome: string,
  agentEnvDir: string,
 ): Promise<void> {
  await validatePrivateProjectionDirectory(mosaicHome, agentEnvDir);
  const fleetDir = join(mosaicHome, 'fleet');
  await ensureManagedDirectory(mosaicHome, false);
  await ensureManagedDirectory(fleetDir, false);
  await ensureManagedDirectory(agentEnvDir, true);
 }
 async function ensureManagedDirectory(path: string, privateDirectory: boolean): Promise<void> {
  let created = false;
  try {
    await lstat(path);
  } catch (error: unknown) {
    if (!isMissingFile(error)) throw error;
    try {
      await mkdir(path, { recursive: true, mode: 0o700 });
      created = true;
    } catch (mkdirError: unknown) {
      if (!isAlreadyExists(mkdirError)) throw mkdirError;
    }
  }
  await assertManagedDirectory(path, privateDirectory);
  if (created) {
    await chmod(path, 0o700);
    await assertManagedDirectory(path, privateDirectory);
  }
 }
 function isAlreadyExists(error: unknown): boolean {
  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST';
 }
 async function assertManagedDirectoryIfPresent(
  path: string,
  privateDirectory: boolean,
 ): Promise<void> {
  try {
    await assertManagedDirectory(path, privateDirectory);
  } catch (error: unknown) {
    if (isMissingFile(error)) return;
    throw error;
  }
 }
 async function assertManagedDirectory(path: string, privateDirectory: boolean): Promise<void> {
  const metadata = await lstat(path);
  if (!metadata.isDirectory()) {
    throw new AgentEnvBoundaryError('unsafe-directory', '(directory)', path);
  }
  if ((metadata.mode & 0o022) !== 0 || (privateDirectory && (metadata.mode & 0o077) !== 0)) {
    throw new AgentEnvBoundaryError('unsafe-permissions', '(directory)', path);
  }
 }
 async function assertPrivateRegularFileIfPresent(path: string): Promise<void> {
  try {
    await assertPrivateRegularFile(path);
  } catch (error: unknown) {
    if (isMissingFile(error)) return;
    throw error;
  }
 }
 async function assertPrivateRegularFile(path: string): Promise<void> {
  const metadata = await lstat(path);
  if (!metadata.isFile()) throw new AgentEnvBoundaryError('unsafe-file', '(file)', path);
  if ((metadata.mode & 0o077) !== 0) {
    throw new AgentEnvBoundaryError('unsafe-permissions', '(file)', path);
  }
 }
 async function writePrivateAtomically(path: string, content: string): Promise<void> {
  try {
    await assertPrivateRegularFile(path);
  } catch (error: unknown) {
    if (!isMissingFile(error)) throw error;
  }
  const temporaryPath = join(dirname(path), `.${randomUUID()}.tmp`);
  await writeFile(temporaryPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
  await rename(temporaryPath, path);
 }
Author	SHA1	Message	Date
Jarvis	ace73f1e03	fix(fleet): close persona resolver authority edges All checks were successful ci/woodpecker/pr/ci Pipeline was successful Details Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-14 19:45:05 -05:00
Jarvis	4d990eee7c	fix(fleet): fail closed on persona overrides All checks were successful ci/woodpecker/pr/ci Pipeline was successful Details Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-14 19:15:28 -05:00
Jarvis	ed940f15f3	test(fleet): make unreadable persona fixture deterministic Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-14 19:15:28 -05:00
Jarvis	a262f63d3d	chore(docs): normalize fleet task table Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-14 19:15:28 -05:00
Jarvis	5aef8ed690	feat(fleet): add shared role semantics Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-14 19:15:28 -05:00
Jarvis	1865f73718	chore(orchestrator): reassign FCM-M1-002 to fresh worker Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-14 19:15:28 -05:00
Jarvis	13684d452e	chore(orchestrator): start FCM-M1-002 shared role resolution Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-14 19:15:28 -05:00