feat(fleet): enforce generated environment boundary (#772)

docs/SITEMAP.md

@@ -1,5 +1,12 @@
 # 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.

docs/fleet/FLEET-LAUNCH.md

@@ -1,114 +1,77 @@
 # Fleet Launch Runbook
 
-How every Mosaic fleet agent — workers **and** the orchestrator — is launched, and how to
+The local fleet roster is the sole writable desired-state authority for membership and launch policy.
-configure each one. The guiding principle: **one roster-driven launcher**. There is no bespoke
+Generated environment files are rebuildable projections, not an operator-editable command surface.
-per-agent launch script; the roster plus per-agent `.env` files are the single source of launch
-config.
 
-## The launch chain
+## Launch chain
 
-| Layer            | File                                              | Responsibility                                                                                                                                              |
+| Layer               | Responsibility                                                                                                                  |
-| ---------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| 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`. |
+| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
-| session launcher | `tools/fleet/start-agent-session.sh <role>`       | Builds the launch command, opens the tmux pane, wires the heartbeat.                                                                                        |
+| Projection writer   | Renders deterministic `fleet/agents/<name>.env.generated` from the roster.                                                      |
-| launch command   | `mosaic yolo <runtime>` (or a per-agent override) | Replaces the pane's foreground process with the runtime, fully seeded.                                                                                      |
+| Optional local data | Reads a strict, data-only `fleet/agents/<name>.env.local`; it cannot shadow generated keys.                                     |
-| seeding          | `mosaic`'s `composeContract()`                    | Injects the Constitution/USER/TOOLS/runtime contract, `*.local` overlays, **and** the Fleet-Comms cheat-sheet — all via `--append-system-prompt`.           |
+| systemd             | Starts the launcher with `env -i` and fixed bootstrap data. It does not preload either environment file.                        |
+| 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.           |
 
-Per-agent overrides live in `fleet/agents/<role>.env`, generated from `roster.yaml` by
+The launcher never `source`s or `eval`s an environment file and never accepts an environment-supplied
-`generateAgentEnv` (`packages/mosaic/src/commands/fleet.ts`) and consumed by the launcher.
+command. `MOSAIC_AGENT_COMMAND`, command/channel overrides, unknown keys, generated-key shadowing,
+secret-like key names, duplicate keys, comments, quoted/export syntax, and unsafe values are rejected.
 
-## Worker launch path (default)
+## Generated and local files
 
-1. `roster.yaml` carries each agent's `runtime` and optional `model_hint`.
+`<name>.env.generated` is complete, deterministic, and written only by Mosaic. Its ordered keys are:
-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.
 
-That is the whole worker path: roster → `.env` → `mosaic yolo <runtime>` → seeded pane.
+```dotenv
-
+MOSAIC_AGENT_NAME=<roster name>
-## Orchestrator fold (PATH A — ships today)
+MOSAIC_AGENT_CLASS=<roster class>
-
+MOSAIC_AGENT_RUNTIME=<roster runtime>
-The orchestrator is **just another roster agent** launched through the canonical path — not a
+MOSAIC_AGENT_MODEL=<roster model hint>
-snowflake script.
+MOSAIC_AGENT_REASONING=<roster reasoning>
-
+MOSAIC_AGENT_TOOL_POLICY=<roster tool policy>
-| Piece              | Value                               |
+MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
-| ------------------ | ----------------------------------- |
+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>'
 ```
 
-When `MOSAIC_AGENT_COMMAND` is set, `start-agent-session.sh`'s `if [ -z "$MOSAIC_AGENT_COMMAND" ]`
+The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. `mosaic fleet add`
-guard (line ~41) is false, so the line-44 default — **including its hardcoded `yolo`** — is skipped
+rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
-entirely. The override fully controls the runtime and flags. Routing through `mosaic yolo claude`
+The legacy dogfood stub remains an observability-only canary on its separate `mosaic-factory` socket;
-(rather than a raw `claude` invocation) is what gives the orchestrator the same full
+it has no generated-launch adapter and cannot be added through this path.
-`composeContract` seeding + Fleet-Comms cheat-sheet as every worker, with `--channels` and any
-other flags passed straight through to the `claude` binary.
 
-## Launch gotchas
+`<name>.env.local` is optional and may contain only non-secret machine data:
 
-1. **Flag conflict.** `mosaic yolo claude` already injects `--dangerously-skip-permissions`. Do
+- `MOSAIC_RUNTIME_BIN`
-   **not** also pass `--permission-mode bypassPermissions` — the `claude` binary would receive both.
+- `MOSAIC_HEARTBEAT_RUN_DIR`
-   Use `mosaic yolo claude …` alone (yolo covers the unattended posture), **or** non-yolo
+- `MOSAIC_HEARTBEAT_INTERVAL`
-   `mosaic claude --permission-mode bypassPermissions …`. Never mix the two.
+- `MOSAIC_CLAUDE_JSON`
-2. **`MOSAIC_AGENT_NAME` must reach the pane.** The launcher bakes it from the instance name, and
+- `CLAUDE_CONFIG_DIR`
-   `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.
 
-## Why per-agent `.env` survives upgrades (#632)
+Paths must be safe absolute paths and the heartbeat interval must be a positive integer. Projection,
+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.
 
-`install.sh` `PRESERVE_PATHS` includes `fleet/*.yaml`, `fleet/agents`, and `fleet/run`, so
+## Legacy input and diagnostics
-`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.
 
-## Inspecting the comms wiring
+A legacy `<name>.env` is input only during projection generation. Roster-owned keys are regenerated;
+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.
 
-- `mosaic fleet comms-block <role>` prints the Fleet-Comms cheat-sheet a given role receives at
+Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command
-  launch — its `[host:session]` identity, the exact `agent-send.sh` command for each peer, and the
+text, credentials, or other values.
-  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.
 
-## North Star / future direction
+## Launch and stop behavior
 
-**Vision:** a webUI lets the user edit each agent's launch config — switch **harness**
+The launcher obtains the agent's socket only from the validated generated projection. It creates or
-(claude / pi / codex / opencode), toggle **yolo**, pick a **model**, set a **command/channels**
+checks the exact `=<agent-name>` tmux target; it never uses an ambient socket or fuzzy session match.
-override — with no terminal.
+The same strict parser runs before exact-stop behavior. A fresh native Pi heartbeat remains authoritative;
+the shell sidecar only provides fallback state when the native marker is stale or absent.
 
-**Continuity — this is not a new launch path.** It is a data-model + UI-binding layer over the
+`mosaic fleet comms-block <role>` can inspect the role's resolved Fleet-Comms block. It is a read-only
-existing roster-driven launcher. Field-by-field status today:
+inspection tool and fails loudly for an unknown role or missing roster.
 
-| Launch-config field      | Roster-native today? | Mechanism / gap                                                                                                                                          |
+## Current M2 boundary
-| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **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. |
 
-**The arc:**
+FCM-M2-001 supplies generated/local parsing, validation, projection, quarantine, and launch-boundary
-
+evidence only. It does not authorize roster CRUD expansion, reconciliation, lifecycle changes, remote
-- **A** — `.env` `MOSAIC_AGENT_COMMAND` hatch: manual, ships now, kept safe across upgrades by #632.
+or connector mutation, site canaries, or migration. M3 must establish the local reconcile/lifecycle
-- **B** — roster-native launch-config: harness + model are already there; add the **yolo** toggle
+path; M4 separately provides migration preview, canary, and rollback gates.
-  (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.

docs/fleet/reference/generated-env-boundary.md

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

docs/scratchpads/fcm-m2-001-generated-env-boundary.md

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

packages/mosaic/framework/fleet/README.md

@@ -9,7 +9,8 @@ package, normally at:
 ```
 
 The default tmux socket is `mosaic-fleet` so fleet commands do not touch the
-default tmux server.
+default tmux server. The roster is the desired-state authority; generated environment files are
+rebuildable projections, never a second source of configuration.
 
 ## Examples
 
@@ -31,6 +32,17 @@ 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

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

@@ -24,45 +24,56 @@ The agent template calls:
 
 which starts or reuses a tmux session on `MOSAIC_TMUX_SOCKET`.
 
-## Local customization
+## Generated environment and local data
 
-Per-agent overrides live outside the package in:
+The roster-derived projection is written outside the package at:
 
 ```text
-~/.config/mosaic/fleet/agents/<agent>.env
+~/.config/mosaic/fleet/agents/<agent>.env.generated
 ```
 
-Example:
+Systemd does not read either environment file. It starts the launcher with a fixed cleared bootstrap
+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:
 
-```dotenv
+```text
-MOSAIC_TMUX_SOCKET=mosaic-fleet
+~/.config/mosaic/fleet/agents/<agent>.env.local
-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
 
-```bash
+Use the roster and the supported installer; do not pre-create the agent environment directory or
-mkdir -p ~/.config/systemd/user ~/.config/mosaic/tools/fleet ~/.config/mosaic/fleet/agents
+edit a generated projection. `mosaic fleet install` validates the roster, installs the units and
-cp packages/mosaic/framework/systemd/user/mosaic-*.service ~/.config/systemd/user/
+helpers, and writes private roster-derived projections before any service is started.
-cp packages/mosaic/framework/tools/fleet/*.sh ~/.config/mosaic/tools/fleet/
-chmod +x ~/.config/mosaic/tools/fleet/*.sh
-systemctl --user daemon-reload
-systemctl --user start mosaic-tmux-holder.service
-systemctl --user start mosaic-agent@canary.service
-tmux -L mosaic-fleet ls
 
-# For an operator-interaction service, the roster/env identity selects the
+```bash
-# generic unit instance; no service source is renamed for an instance.
+# Create a site-owned canary roster. Inspect an existing roster before using --force.
+mosaic fleet init --profile minimal --write
+mosaic fleet install
+systemctl --user daemon-reload
+mosaic fleet start canary-pi
+tmux -L mosaic-fleet ls
+```
+
+For an operator-interaction service, first put `<agent-name>` in the roster with the pinned Pi
+runtime, model, reasoning, and `operator-interaction` tool policy. Re-run `mosaic fleet install` after
+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
-MOSAIC_AGENT_NAME=<agent-name> \
+~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh <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

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

@@ -7,16 +7,13 @@ 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
-# No default MOSAIC_TMUX_SOCKET: an absent roster socket means the literal
+# Never preload the projection. The launcher starts from a fixed minimal
-# default tmux socket (no -L). The per-agent .env sets it when the roster names
+# environment and strictly validates generated/local data before tmux effects.
-# one; otherwise it stays unset and start-agent-session.sh uses the default socket.
+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
-Environment=MOSAIC_AGENT_NAME=%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
-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

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

@@ -7,11 +7,13 @@ 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
-Environment=MOSAIC_AGENT_NAME=%i
+# The interaction wrapper delegates to the shared strict parser before pinned
-EnvironmentFile=%h/.config/mosaic/fleet/agents/%i.env
+# profile checks; no projection data reaches Bash through systemd.
-ExecStart=/bin/bash %h/.config/mosaic/tools/fleet/start-interaction-service.sh %i
+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
-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'
+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
 
 [Install]
 WantedBy=default.target

packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service

@@ -6,10 +6,11 @@ After=default.target
 [Service]
 Type=oneshot
 RemainAfterExit=yes
-Environment=MOSAIC_TMUX_SOCKET=mosaic-fleet
+# The holder owns the tmux server, so clear loader, shell-control, and stale
-Environment=MOSAIC_TMUX_HOLDER=_holder
+# manager/session variables before the server process starts.
-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"'
+UnsetEnvironment=LD_PRELOAD BASH_ENV ENV
-ExecStop=-/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" kill-server'
+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=-/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

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

@@ -5,6 +5,8 @@ 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
@@ -14,16 +16,40 @@ 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"
-grep -qF 'kill-session -t "=%i"' "$AGENT" || fail "agent stop does not exact-match its session"
+if grep -qE '^Environment(File)?=' "$AGENT" "$INTERACTION"; then
+  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 'EnvironmentFile=%h/.config/mosaic/fleet/agents/%i.env' "$INTERACTION" || fail "interaction service does not require per-agent config"
+grep -qF 'ExecStart=/usr/bin/env -i HOME=%h MOSAIC_AGENT_NAME=%i PATH=/usr/bin:/bin /bin/bash --noprofile --norc' "$INTERACTION" || \
-grep -qF 'start-interaction-service.sh %i' "$INTERACTION" || fail "interaction service does not validate before startup"
+  fail "interaction unit does not clear bootstrap environment before strict parsing"
+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 || {
@@ -32,4 +58,102 @@ 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"

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

@@ -1,39 +1,207 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}}
+# FCM-M2-001 boundary: only a roster-derived .env.generated projection and a
-# Absent socket ⇒ the LITERAL default tmux socket (no -L). The roster's
+# separately parsed data-only .env.local can influence launch. Never source an
-# socket_name is honored when set; absent never silently becomes mosaic-fleet
+# environment file and never accept a command string from either file.
-# (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}
 
-if [ -z "$AGENT_NAME" ]; then
+MODE=launch
-  echo "ERROR: agent name argument or MOSAIC_AGENT_NAME is required" >&2
+case "${1:-}" in
-  exit 64
+  --stop)
-fi
+    MODE=stop
-
+    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" "$@"
@@ -42,140 +210,90 @@ _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
 
-if [ -z "$MOSAIC_AGENT_COMMAND" ]; then
+# Systemd passes HOME as %h, and the installed service fixes MOSAIC_HOME under
-  # Map the roster's per-agent model_hint to `--model` so workers launch on the
+# that home. Derive the pane home from the canonical path when available so an
-  # configured model (e.g. pi on openai-codex/gpt-5.5:high). Omitted when unset.
+# inherited pane/session HOME cannot become runtime authority.
-  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}${MOSAIC_AGENT_REASONING:+ --thinking $MOSAIC_AGENT_REASONING}"
+PANE_HOME=$HOME
-fi
+case "$MOSAIC_HOME" in
+  */.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
+    if [ -n "$npm_prefix" ]; then candidates+=("${npm_prefix}/bin"); fi
-      candidates+=("${npm_prefix}/bin")
-    fi
   fi
+  candidates+=("$PANE_HOME/.npm-global/bin" "$PANE_HOME/.local/bin")
 
-  candidates+=("$HOME/.npm-global/bin")
+  local prefix="" dir
-  candidates+=("$HOME/.local/bin")
-
-  local prefix=""
   for dir in "${candidates[@]}"; do
     [ -d "$dir" ] || continue
-    if [ -z "$prefix" ]; then
+    case ":${prefix}:" in *":${dir}:"*) ;; *) prefix="${prefix:+$prefix:}$dir" ;; esac
-      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"
-  # The path claude keys on is the resolved cwd it is launched in.
+  local resolved
-  local rp
+  resolved=$(cd "$workdir" 2>/dev/null && pwd -P) || resolved="$workdir"
-  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
-  if ! command -v python3 >/dev/null 2>&1; then
+  MOSAIC_CJ="$claude_json" MOSAIC_TRUST_DIR="$resolved" python3 - <<'PY'
-    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"]
@@ -184,22 +302,19 @@ 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)  # atomic
+    os.replace(tmp, cj)
 except Exception:
     try:
         os.unlink(tmp)
@@ -207,56 +322,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
 }
 
-case "$MOSAIC_AGENT_RUNTIME" in
+if [ "$MOSAIC_AGENT_RUNTIME" = claude ]; then
-  claude)
+  _ensure_claude_workdir_trusted "$MOSAIC_AGENT_WORKDIR" || \
-    _ensure_claude_workdir_trusted "$MOSAIC_AGENT_WORKDIR" \
+    echo "WARNING: could not pre-trust workdir for claude agent $AGENT_NAME" >&2
-      || echo "WARNING: could not pre-trust workdir for claude agent $AGENT_NAME" >&2
+fi
-    ;;
-esac
 
-# ── Launch the tmux session (no exec — we continue to wire the heartbeat) ────
+LAUNCH_COMMAND=(mosaic yolo "$MOSAIC_AGENT_RUNTIME")
+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" \
-  bash -c "$PANE_SHELL_SNIPPET"
+  "${LAUNCH_ENV[@]}" "${LAUNCH_COMMAND[@]}"
 
-# ── 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 \
+  PANE_PID=$(_tmux list-panes -t "=${AGENT_NAME}:0.0" -F '#{pane_pid}' 2>/dev/null || true)
-    -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"
+  local agent="$1" pane_pid="$2" run_dir="$3" interval="$4"
-  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; 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=%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_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
@@ -266,7 +381,6 @@ _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

packages/mosaic/framework/tools/fleet/start-interaction-service.sh

@@ -9,11 +9,7 @@ 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"
 
-exec "$(cd -- "$(dirname -- "$0")" && pwd)/start-agent-session.sh" "$AGENT_NAME"
+# The shared launcher strictly validates the generated/local data boundary
+# before it applies this interaction service's pinned profile checks.
+exec "$(cd -- "$(dirname -- "$0")" && pwd)/start-agent-session.sh" --interaction "$AGENT_NAME"

packages/mosaic/framework/tools/fleet/start-tmux-holder.sh

@@ -0,0 +1,64 @@
+#!/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

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

@@ -3,373 +3,410 @@ set -euo pipefail
 
 SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
 START="$SCRIPT_DIR/start-agent-session.sh"
-SOCKET="mosaic-agent-test-$RANDOM-$$"
+INTERACTION_START="$SCRIPT_DIR/start-interaction-service.sh"
-AGENT="agent-$RANDOM"
+ROOT=$(mktemp -d)
-WORKDIR=$(mktemp -d)
+FAKE_BIN=$(mktemp -d)
-
+TMUX_CALLS=$(mktemp)
-# Keep a single cleanup trap that accumulates resources.
+trap 'rm -rf "$ROOT" "$FAKE_BIN" "$TMUX_CALLS"' EXIT
-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
 }
 
-# ── Test 1: basic session creation with workdir check ─────────────────────────
+cat > "$FAKE_BIN/tmux" <<'SHIM'
-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
-# Fake tmux: record new-session args; report has-session as missing.
+set -euo pipefail
-subcmd="\$3"  # argv: tmux -L <socket> <subcmd> ...
+printf '%s\0' "$@" >> "${MOSAIC_TEST_TMUX_CALLS:?}"
-if [ "\$subcmd" = "has-session" ]; then
+args=("$@")
-  exit 1   # session not found → script will attempt new-session
+index=0
-fi
+if [ "${args[0]:-}" = -L ]; then index=2; fi
-if [ "\$subcmd" = "new-session" ]; then
+case "${args[$index]:-}" in
-  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE"
+  has-session)
+    for argument in "${args[@]}"; do
+      [ "$argument" = '=_holder:0.0' ] && exit 0
+    done
+    exit 1
+    ;;
+  show-environment)
+    printf '%s\n' \
+      "HOME=${MOSAIC_TEST_HOME:?}" \
+      '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
-fi
+    ;;
-if [ "\$subcmd" = "list-panes" ]; then
+  list-panes) printf '%s\n' "${MOSAIC_TEST_PANE_PID:-}"; exit 0 ;;
-  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
+  new-session)
-  echo ""
+    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
-fi
+    ;;
-exit 0
+  *) exit 0 ;;
+esac
 SHIM
 chmod +x "$FAKE_BIN/tmux"
 
-SOCKET3="mosaic-agent-test3-$RANDOM-$$"
+cat > "$FAKE_BIN/mosaic" <<'SHIM'
-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
-subcmd="\$3"
+set -euo pipefail
-if [ "\$subcmd" = "has-session" ]; then exit 1; fi
+env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
-if [ "\$subcmd" = "new-session" ]; then
+SHIM
-  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE2"
+chmod +x "$FAKE_BIN/mosaic"
-  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
+
-  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
+# The pane must start through an absolute clean-environment boundary. Its
-  echo ""
+# runtime command remains an argv vector, but no holder/session environment
-  exit 0
+# control variable can pass through the pane command.
+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
-exit 0
+[ ! -s "$TMUX_CALLS" ] || fail "tmux ran before unsafe parent rejection"
-SHIM2
+echo "$output" | grep -qF 'code=unsafe-permissions' || fail "unsafe parent diagnostic missing"
-chmod +x "$FAKE_BIN2/tmux"
 
-SOCKET4="mosaic-agent-test4-$RANDOM-$$"
+: > "$TMUX_CALLS"
-AGENT4="agent4-$RANDOM"
+HOME_SYMLINK_PARENT="$ROOT/symlink-parent"
-WORKDIR4=$(mktemp -d)
+write_generated "$HOME_SYMLINK_PARENT" "coder-symlink-parent"
-CLEANUP_DIRS+=("$WORKDIR4")
+mv "$HOME_SYMLINK_PARENT/fleet/agents" "$HOME_SYMLINK_PARENT/private-agents"
-
+ln -s "$HOME_SYMLINK_PARENT/private-agents" "$HOME_SYMLINK_PARENT/fleet/agents"
-# MOSAIC_RUNTIME_BIN points to a non-existent dir so prefix will be empty;
+if output=$(run_start "$HOME_SYMLINK_PARENT" coder-symlink-parent 2>&1); then
-# .npm-global/bin and .local/bin may or may not exist but we just want exec.
+  fail "generated file under a symlinked parent was accepted"
-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
-if [ "\$subcmd" = "list-panes" ]; then
+[ ! -s "$TMUX_CALLS" ] || fail "tmux ran before symlinked parent rejection"
-  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
+echo "$output" | grep -qF 'code=unsafe-directory' || fail "symlinked parent diagnostic missing"
-  echo ""
-  exit 0
-fi
-exit 0
-SHIM5
-chmod +x "$FAKE_BIN5/tmux"
 
-SOCKET5="mosaic-agent-test5-$RANDOM-$$"
+# Every managed ancestor is a boundary: MOSAIC_HOME, fleet, and agents. A
-AGENT5="agent5-$RANDOM"
+# symlink or group/world-writable ancestor must fail before environment parsing,
-WORKDIR5=$(mktemp -d)
+# workdir creation, or tmux effects. The malformed local input proves parsing
-CLEANUP_DIRS+=("$WORKDIR5")
+# was not reached when the ancestor rejection is reported.
-CLEANUP_SOCKETS+=("$SOCKET5")
+assert_managed_ancestor_rejected() {
+  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"
 
-# FAKE_RUNTIME_BIN5 is deliberately placed on the LAUNCHER PATH so that the
+  case "$ancestor" in
-# old (buggy) code would have skipped it.  The correct code must still include
+    MOSAIC_HOME) node="$home" ;;
-# it in the pane PATH export.
+    MOSAIC_HOME/fleet) node="$home/fleet" ;;
-PATH="$FAKE_BIN5:$FAKE_RUNTIME_BIN5:$PATH" \
+    MOSAIC_HOME/fleet/agents) node="$home/fleet/agents" ;;
-MOSAIC_TMUX_SOCKET="$SOCKET5" \
+    *) fail "unknown managed ancestor: $ancestor" ;;
-MOSAIC_AGENT_WORKDIR="$WORKDIR5" \
+  esac
-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"
 
-all_args5=$(cat "$TMUX_ARGS_FILE5" 2>/dev/null || true)
+  if [ "$hazard" = symlink ]; then
-rm -f "$TMUX_ARGS_FILE5"
+    local target="${node}-target"
-rm -rf "$WORKDIR5"
+    mv "$node" "$target"
+    ln -s "$target" "$node"
+  else
+    chmod 777 "$node"
+  fi
 
-echo "--- test 5: launcher-PATH candidate must still appear in pane export ---"
+  : > "$TMUX_CALLS"
-echo "$all_args5"
+  if output=$(run_start "$home" "$agent" 2>&1); then
-echo "--- end test 5 args ---"
+    fail "${hazard} $ancestor was accepted"
+  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
+}
 
-echo "$all_args5" | grep -qF "export PATH=" || \
+for managed_ancestor in MOSAIC_HOME MOSAIC_HOME/fleet MOSAIC_HOME/fleet/agents; do
-  fail "test5: pane command does not export PATH when candidate is on launcher PATH"
+  assert_managed_ancestor_rejected "$managed_ancestor" symlink
-echo "$all_args5" | grep -qF "$FAKE_RUNTIME_BIN5" || \
+  assert_managed_ancestor_rejected "$managed_ancestor" group-world-writable
-  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
 
-[ -f "$HB_FILE" ] || fail "test6: heartbeat file not written at $HB_FILE within 5s"
+# A local file cannot shadow any roster-derived generated key. Validation must
+# 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
 
-hb_content=$(cat "$HB_FILE")
+# Arbitrary command compatibility is quarantined/rejected as data. Diagnostics
-echo "--- test 6: heartbeat file content ---"
+# may name the key and hash but must never echo the privileged command text.
-echo "$hb_content"
+: > "$TMUX_CALLS"
-echo "--- end test 6 ---"
+HOME_COMMAND="$ROOT/command"
+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
 
-# Verify required fields are present.
+# Group/world-readable local input is not trusted even when its syntax is safe.
-echo "$hb_content" | grep -qE '^ts=[0-9]{4}-[0-9]{2}-[0-9]{2}T' || \
+: > "$TMUX_CALLS"
-  fail "test6: heartbeat ts field missing or malformed"
+HOME_PERMS="$ROOT/perms"
-echo "$hb_content" | grep -qE '^pid=[0-9]+' || \
+write_generated "$HOME_PERMS" "coder3"
-  fail "test6: heartbeat pid field missing or malformed"
+printf 'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n' > "$HOME_PERMS/fleet/agents/coder3.env.local"
-echo "$hb_content" | grep -qF 'status=ok' || \
+chmod 644 "$HOME_PERMS/fleet/agents/coder3.env.local"
-  fail "test6: heartbeat status=ok missing"
+if output=$(run_start "$HOME_PERMS" coder3 2>&1); then
+  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"
 
-# ── Test 7: heartbeat sidecar — targets correct .hb path per agent name ────────
+# A unit/holder-like clean bootstrap must yield a pane with trusted HOME and
-#
+# computed PATH only. The pane command itself must not carry loader, shell
-# Uses the fake-tmux shim approach (like tests 3-5) to capture the sidecar
+# control, arbitrary sentinel, or stale bootstrap variables.
-# invocation without needing a real session.  A fake setsid shim records its
+: > "$TMUX_CALLS"
-# arguments so we can assert the sidecar script targets the expected .hb path
+HOME_PANE_BOUNDARY="$ROOT/pane-boundary/.config/mosaic"
-# and uses the configured interval.
+write_generated "$HOME_PANE_BOUNDARY" "coder-pane-boundary"
+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
 
-FAKE_BIN7=$(mktemp -d)
+after_pane_env=$(printf '%s\n' "$pane_args" | grep -n -m1 -F '/usr/bin/env' | cut -d: -f1)
-FAKE_RUNTIME_BIN7=$(mktemp -d)
+[ -n "$after_pane_env" ] || fail "pane command did not use absolute env"
-SETSID_ARGS_FILE=$(mktemp)
+printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i' || \
-HB_RUN_DIR7=$(mktemp -d)
+  fail "pane command did not clear its environment"
-CLEANUP_DIRS+=("$FAKE_BIN7" "$FAKE_RUNTIME_BIN7" "$HB_RUN_DIR7")
+pane_environment=$(tr '\0' '\n' < "$HOME_PANE_BOUNDARY/fleet/pane-environment")
+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
 
-AGENT7="my-fleet-agent-$RANDOM"
+write_interaction_generated() {
-INTERVAL7="42"
+  local home="$1"
+  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"
+}
 
-# Fake tmux: has-session → not found; new-session → ok; list-panes → known PID.
+run_interaction() {
-cat > "$FAKE_BIN7/tmux" <<SHIM7
+  local home="$1"
-#!/usr/bin/env bash
+  local agent="$2"
-subcmd="\$3"
+  HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
-if [ "\$subcmd" = "has-session" ]; then exit 1; fi
+    MOSAIC_TEST_HOME="$home" \
-if [ "\$subcmd" = "new-session" ]; then exit 0; fi
+    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
-if [ "\$subcmd" = "list-panes" ]; then echo "88888"; exit 0; fi
+    MOSAIC_HOME="$home" "$INTERACTION_START" "$agent"
-exit 0
+}
-SHIM7
-chmod +x "$FAKE_BIN7/tmux"
 
-# Fake setsid: capture the bash -c <script> argument for inspection, then
+write_heartbeat_local() {
-# background an actual bash subshell so disown succeeds in the caller.
+  local home="$1"
-cat > "$FAKE_BIN7/setsid" <<'SETSID_SHIM'
+  local agent="$2"
-#!/usr/bin/env bash
+  mkdir -p "$home/run"
-# argv: setsid bash -c <sidecar_script>
+  cat > "$home/fleet/agents/$agent.env.local" <<EOF
-# Record the full argument list to the capture file, then exit cleanly.
+MOSAIC_HEARTBEAT_RUN_DIR=$home/run
-printf '%s\0' "$@" > __SETSID_ARGS_FILE__
+MOSAIC_HEARTBEAT_INTERVAL=1
-exit 0
+EOF
-SETSID_SHIM
+  chmod 600 "$home/fleet/agents/$agent.env.local"
-# 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"
 
-SOCKET7="mosaic-agent-test7-$RANDOM-$$"
+wait_for_sidecar_status() {
-WORKDIR7=$(mktemp -d)
+  local file="$1"
-CLEANUP_DIRS+=("$WORKDIR7")
+  for _retry in $(seq 1 30); do
+    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"
+}
 
-PATH="$FAKE_BIN7:$PATH" \
+# A fresh Pi-native marker is authoritative: the shell sidecar may start but
-MOSAIC_TMUX_SOCKET="$SOCKET7" \
+# must not overwrite Pi's busy/ok/model heartbeat. It must resume only when
-MOSAIC_AGENT_WORKDIR="$WORKDIR7" \
+# the marker is stale or absent.
-MOSAIC_AGENT_RUNTIME="pi" \
+HOME_NATIVE_FRESH="$ROOT/native-fresh"
-MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN7" \
+write_generated "$HOME_NATIVE_FRESH" "coder-native-fresh"
-MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
+write_heartbeat_local "$HOME_NATIVE_FRESH" "coder-native-fresh"
-MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR7" \
+FRESH_HB="$HOME_NATIVE_FRESH/run/coder-native-fresh.hb"
-MOSAIC_HEARTBEAT_INTERVAL="$INTERVAL7" \
+printf 'ts=native\npid=1\nstatus=busy\nmodel=authoritative-model\n' > "$FRESH_HB"
-  "$START" "$AGENT7"
+touch "$FRESH_HB.native"
+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"
 
-# Give the background setsid shim a moment to finish writing the capture file.
+HOME_NATIVE_STALE="$ROOT/native-stale"
-sleep 0.5
+write_generated "$HOME_NATIVE_STALE" "coder-native-stale"
+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"
 
-setsid_args=$(cat "$SETSID_ARGS_FILE" 2>/dev/null | tr '\0' '\n' || true)
+HOME_NATIVE_ABSENT="$ROOT/native-absent"
-rm -f "$SETSID_ARGS_FILE"
+write_generated "$HOME_NATIVE_ABSENT" "coder-native-absent"
-rm -rf "$WORKDIR7"
+write_heartbeat_local "$HOME_NATIVE_ABSENT" "coder-native-absent"
+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"
 
-echo "--- test 7: captured setsid args ---"
+# The interaction wrapper delegates to the shared strict parser before applying
-echo "$setsid_args"
+# its pinned policy, so malformed projection data wins over profile diagnostics.
-echo "--- end test 7 ---"
+: > "$TMUX_CALLS"
+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"
 
-# The sidecar script (bash -c <script>) must reference the correct .hb path.
+# A syntactically valid but policy-incompatible projection reaches the pinned
-expected_hb="${HB_RUN_DIR7}/${AGENT7}.hb"
+# interaction policy check only after strict parsing and never starts tmux.
-echo "$setsid_args" | grep -qF "$expected_hb" || \
+: > "$TMUX_CALLS"
-  fail "test7: sidecar script does not reference correct .hb path ($expected_hb)"
+HOME_INTERACTION_POLICY="$ROOT/interaction-policy"
+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"
 
-# The sidecar script must use the configured interval.
+# Exact stop derives the socket exclusively from the validated generated
-echo "$setsid_args" | grep -qF "$INTERVAL7" || \
+# projection and ignores an ambient socket supplied by the caller.
-  fail "test7: sidecar script does not reference configured interval ($INTERVAL7)"
+: > "$TMUX_CALLS"
+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"
+echo 'ok - start-agent-session generated environment boundary'

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

@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { chmod, lstat, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { Command } from 'commander';
@@ -284,6 +284,8 @@ 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',
         '',
@@ -325,57 +327,38 @@ describe('fleet roster parsing', () => {
     );
   });
 
-  it('preserves site-owned agent EnvironmentFile overrides while refreshing roster keys', () => {
+  it('rejects legacy command overrides instead of merging them into generated authority', () => {
-    const generated = [
+    const generated = generateAgentEnv(
-      'MOSAIC_AGENT_NAME=coder0',
+      {
-      'MOSAIC_AGENT_RUNTIME=codex',
+        version: 1,
-      'MOSAIC_AGENT_WORKDIR=/srv/new',
+        transport: 'tmux',
-      'MOSAIC_TMUX_SOCKET=mosaic-fleet',
+        tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
-      '',
+        defaults: { workingDirectory: '/srv/new' },
-    ].join('\n');
+        runtimes: {},
-    const existing = [
+        agents: [],
-      'MOSAIC_AGENT_NAME=old-name',
+      },
-      'MOSAIC_AGENT_RUNTIME=old-runtime',
+      { name: 'coder0', className: 'code', runtime: 'codex' },
-      '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(mergeAgentEnv(generated, existing)).toBe(
+    expect((): string => mergeAgentEnv(generated, 'MOSAIC_AGENT_COMMAND=legacy-command\n')).toThrow(
-      [
+      /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('updates (does not duplicate) MOSAIC_AGENT_CLASS on re-launch', () => {
+  it('does not merge a valid local value into the generated projection', () => {
-    const generated = [
+    const generated = generateAgentEnv(
-      'MOSAIC_AGENT_NAME=coder0',
+      {
-      'MOSAIC_AGENT_CLASS=orchestrator',
+        version: 1,
-      'MOSAIC_AGENT_RUNTIME=codex',
+        transport: 'tmux',
-      '',
+        tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
-    ].join('\n');
+        defaults: { workingDirectory: '/srv/new' },
-    const existing = [
+        runtimes: {},
-      'MOSAIC_AGENT_NAME=coder0',
+        agents: [],
-      'MOSAIC_AGENT_CLASS=worker',
+      },
-      'MOSAIC_AGENT_RUNTIME=codex',
+      { name: 'coder0', className: 'code', runtime: 'codex' },
-      '',
+    );
-    ].join('\n');
 
-    const merged = mergeAgentEnv(generated, existing);
+    expect(mergeAgentEnv(generated, 'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\n')).toBe(generated);
-    // 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 () => {
@@ -1129,6 +1112,92 @@ 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) => {
@@ -1687,8 +1756,10 @@ describe('fleet ps — drift detection', () => {
 describe('fleet-polish bundle — boot-survival symmetry', () => {
   async function rosterHome(agents: string): Promise<string> {
     const home = await tempDir();
-    await mkdir(join(home, 'fleet'), { recursive: true });
+    const fleetDir = join(home, 'fleet');
-    await writeFile(join(home, 'fleet', 'roster.yaml'), agents);
+    await mkdir(fleetDir, { recursive: true, mode: 0o700 });
+    await chmod(fleetDir, 0o700);
+    await writeFile(join(fleetDir, 'roster.yaml'), agents);
     return home;
   }
 
@@ -3459,7 +3530,11 @@ describe('fleet add command', () => {
 
   async function makeHome(agents = ['orchestrator']): Promise<string> {
     const dir = await mkdtemp(join(tmpdir(), 'mosaic-fleet-add-'));
-    await mkdir(join(dir, 'fleet', 'agents'), { recursive: true });
+    const fleetDir = join(dir, 'fleet');
+    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}`;
@@ -3493,11 +3568,110 @@ 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(join(home, 'fleet', 'agents', 'coder0.env'), 'utf8');
+    const envContent = await readFile(
+      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[][] = [];
@@ -3659,7 +3833,10 @@ describe('fleet remove command', () => {
       ].join('\n'),
     );
     // Create env and heartbeat files for coder0
-    await writeFile(join(dir, 'fleet', 'agents', 'coder0.env'), 'MOSAIC_AGENT_NAME=coder0\n');
+    await writeFile(
+      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;
   }
@@ -3738,12 +3915,15 @@ describe('fleet remove command', () => {
 
     await program.parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder0', '--keep-files']);
 
-    // Env file should still exist
+    // Generated projection should still exist.
-    const envContent = await readFile(join(home, 'fleet', 'agents', 'coder0.env'), 'utf8');
+    const envContent = await readFile(
+      join(home, 'fleet', 'agents', 'coder0.env.generated'),
+      'utf8',
+    );
     expect(envContent).toContain('MOSAIC_AGENT_NAME=coder0');
   });
 
-  it('env file is removed by default (no --keep-files)', async () => {
+  it('generated projection is removed by default (no --keep-files)', async () => {
     home = await makeHome();
     const runner: CommandRunner = async () => ({ stdout: '', stderr: '', exitCode: 0 });
     const program = new Command();
@@ -3752,7 +3932,9 @@ describe('fleet remove command', () => {
 
     await program.parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder0']);
 
-    await expect(readFile(join(home, 'fleet', 'agents', 'coder0.env'), 'utf8')).rejects.toThrow();
+    await expect(
+      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 () => {

packages/mosaic/src/commands/fleet.ts

@@ -19,6 +19,16 @@ 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';
@@ -509,50 +519,35 @@ export async function generateNorthStarMarkdown(repoRoot?: string): Promise<stri
 }
 
 export function generateAgentEnv(roster: FleetRoster, agent: FleetAgent): string {
-  const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
+  return renderGeneratedAgentEnvironment(generateAgentEnvValues(roster, agent));
-  return [
-    `MOSAIC_AGENT_NAME=${shellEnvValue(agent.name)}`,
-    // Per-agent class → start-agent-session.sh / launcher reads this to inject the
-    // matching persona contract for the agent's class (default `worker`).
-    `MOSAIC_AGENT_CLASS=${shellEnvValue(agent.className)}`,
-    `MOSAIC_AGENT_RUNTIME=${shellEnvValue(agent.runtime)}`,
-    // Per-agent model hint → start-agent-session.sh appends `--model <hint>` to
-    // the `mosaic yolo` launch so workers run on the roster's model (e.g. pi on
-    // 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');
 }
 
+/**
+ * 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 {
-  if (!existingEnv?.trim()) {
+  parseAgentEnvironment(generatedEnv, 'generated');
+  if (existingEnv?.trim()) parseAgentEnvironment(existingEnv, 'local');
   return generatedEnv;
-  }
+}
-  const generatedKeys = new Set(
+
-    generatedEnv
+function generateAgentEnvValues(
-      .split('\n')
+  roster: FleetRoster,
-      .map((line) => line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1])
+  agent: FleetAgent,
-      .filter((key): key is string => key !== undefined),
+): Readonly<Record<string, string>> {
-  );
+  const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
-  const preservedLines = existingEnv.split('\n').filter((line) => {
+  return {
-    if (!line.trim()) {
+    MOSAIC_AGENT_NAME: agent.name,
-      return false;
+    MOSAIC_AGENT_CLASS: agent.className,
-    }
+    MOSAIC_AGENT_RUNTIME: agent.runtime,
-    const key = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1];
+    MOSAIC_AGENT_MODEL: agent.modelHint ?? '',
-    return key === undefined || !generatedKeys.has(key);
+    MOSAIC_AGENT_REASONING: agent.reasoningLevel ?? '',
-  });
+    MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy ?? '',
-  if (preservedLines.length === 0) {
+    MOSAIC_AGENT_WORKDIR: expandHome(workingDirectory),
-    return generatedEnv;
+    MOSAIC_TMUX_SOCKET: roster.tmux.socketName,
-  }
+  };
-  return [generatedEnv.trimEnd(), ...preservedLines, ''].join('\n');
 }
 
 export function buildFleetServiceCommand(action: FleetServiceAction, agentName?: string): string[] {
@@ -1544,8 +1539,12 @@ 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 writeManagedFleetRoster(activePaths.mosaicHome, 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
@@ -1948,15 +1947,17 @@ 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.`);
 
@@ -2037,10 +2038,11 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
       // Write updated roster
       await writeFile(rosterPath, serializeRosterToYaml(updatedRoster));
 
-      // Delete env and heartbeat files (best-effort, non-fatal)
+      // Delete the non-authoritative generated projection and heartbeat files
+      // (best-effort, non-fatal). Operator local/quarantine data is retained.
       if (!opts.keepFiles) {
         try {
-          await unlink(join(activePaths.agentEnvDir, `${name}.env`));
+          await unlink(join(activePaths.agentEnvDir, `${name}.env.generated`));
         } catch {
           // best-effort
         }
@@ -2328,16 +2330,17 @@ 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',
@@ -2347,6 +2350,7 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
   const executableToolPaths = [
     startAgentSessionPath,
     startInteractionServicePath,
+    startTmuxHolderPath,
     printInteractionPolicyPath,
     sendMessagePath,
     agentSendPath,
@@ -2359,6 +2363,10 @@ 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,
@@ -2382,9 +2390,12 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
   );
 
   for (const agent of roster.agents) {
-    const envPath = join(activePaths.agentEnvDir, `${agent.name}.env`);
+    await writeAgentEnvironmentProjection({
-    const existingEnv = (await canRead(envPath)) ? await readFile(envPath, 'utf8') : undefined;
+      mosaicHome: activePaths.mosaicHome,
-    await writeFile(envPath, mergeAgentEnv(generateAgentEnv(roster, agent), existingEnv));
+      agentEnvDir: activePaths.agentEnvDir,
+      agentName: agent.name,
+      generated: generateAgentEnvValues(roster, agent),
+    });
   }
 
   console.log(`Installed fleet files for ${roster.agents.length} agent(s).`);
@@ -2656,19 +2667,6 @@ 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) {
@@ -2770,13 +2768,8 @@ export function countEnhancers(roster: FleetRoster): number {
 }
 
 /** Valid runtime identifiers for fleet agents. */
-export const VALID_FLEET_RUNTIMES: readonly string[] = [
+/** Runtime launchers accepted by `fleet add`; shared with the generated projection validator. */
-  'pi',
+export const VALID_FLEET_RUNTIMES: readonly string[] = GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES;
-  'claude',
-  'codex',
-  'opencode',
-  'dogfood',
-];
 
 /**
  * Add a new agent to a fleet roster (immutable — returns a new FleetRoster).

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

@@ -0,0 +1,279 @@
+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');
+  });
+});

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

@@ -0,0 +1,509 @@
+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);
+}