fix(fleet): harden #791 upgrade rollback against find/reset failures

Second- and third-round independent-review reliability fixes on the keep-mode
upgrade rollback path, plus accurate abort messaging. All fixed red-first with
self-verifying controls in the rollback gate.

Round 2 (blockers A/B, should-fix C):
- install.sh: `trap 'restore_snapshot; exit 1' ERR INT TERM` so an INT/TERM
  mid-sync terminates instead of resuming past the interrupt and reporting
  success (a bash signal handler that only returns does not terminate).
- manifest.{ts,sh}: reject a degenerate [framework] section whose entries are
  all empty or bare-dot (`/`, `./`, `.`, `..`) — it passed the non-empty guard
  yet yielded zero usable globs, silently resolving everything to operator.
  Parity via a shared `[^/.]` usable-glob test; TS throws ManifestError.
- finalize.ts: classify the sync-abort message — a ManifestError is a pre-sync
  validation abort ("no files were changed"); any other error may be partial.

Round 3 (blockers D1, D2):
- install.sh: enumerate framework files with a checked temp file (_scan_or_die)
  instead of `< <(find …)` — process substitution discards find's exit status,
  so an EACCES/I/O failure mid-scan would truncate the file list yet leave the
  loop exiting 0, committing a partial upgrade as success (ERR trap never fires).
- install.sh: guard the `rm -rf; mkdir -p` target reset inside restore_snapshot
  — a bare reset failing under set -e exits silently after partial deletion,
  never printing the snapshot-recovery pointer. Now checked like the cp -a
  restore: on failure it preserves the snapshot and tells the operator where.

Tests: rollback gate 14→28 (Parts C/D/E with disabled-guard controls);
new finalize-sync-abort.spec.ts (3). No secret value is ever emitted; snapshots
stay 0700. Gates green: typecheck, lint, format:check, full mosaic vitest 1094,
HARD GATE 193, rollback 28, migration 21.

Refs #791

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.woodpecker/ci.yml

@@ -48,19 +48,15 @@ steps:
   # keep mode is a single cp-based path that must not depend on rsync), and that a
   # corrupt/empty/missing manifest aborts fail-closed leaving operator files
   # untouched (B2/B3). The rollback gate proves a mid-sync failure is rolled back
-  # from the pre-update snapshot (B1). The durable-snapshot gate (#791 PR2) proves
-  # the retained, operator-scoped pre-update backup is taken before any mutation
-  # (0700/0600, secret never logged, retention-pruned) and that the post-sync
-  # verify net restores any operator file a manifest bug lets the sync touch. The
-  # migration matrix pins the v2→v3 contract-file semantics. Pure bash, no
-  # node_modules — runs early alongside sanitization.
+  # from the pre-update snapshot (B1). The migration matrix pins the v2→v3
+  # contract-file semantics. Pure bash, no node_modules — runs early alongside
+  # sanitization.
   upgrade-guard:
     image: *node_image
     commands:
       - apk add --no-cache bash rsync
       - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh
       - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh
-      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh
       - bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
 
   typecheck:

docs/guides/fleet-local-canary.md

@@ -98,39 +98,6 @@ Expected results:
   that means the unit ran, not that an agent pane is live. Treat tmux
   `has-session`, `list-panes`, process tree, and logs as the liveness evidence.
 
-## Recovery — rebuild generated env projections
-
-Each agent's `~/.config/mosaic/fleet/agents/<name>.env.generated` is a
-deterministic projection of `roster.yaml` (the SSOT) that the launcher
-(`start-agent-session.sh`) sources at start. If an upgrade or a manual mistake
-wipes or diverges those projections, rebuild them from the roster with
-`mosaic fleet regen` — do NOT restart the affected unit first.
-
-```bash
-mosaic fleet regen            # dry-run (default): show create/rebuild plan per agent
-mosaic fleet regen --json     # same plan, machine-readable
-mosaic fleet regen --write    # rebuild fleet/agents/<name>.env.generated on disk
-```
-
-`regen` is projection-only and **never restarts an agent** — it has no path to
-systemd lifecycle. It is dry-run by default, deterministic/idempotent, uses the
-same roster→env mapping as `mosaic fleet reconcile`, and emits paths and counts
-only (never the projected `KEY=value` body). After `--write`, verify each unit
-resolves the intended values before restarting one unit at a time. The unit sets
-no `EnvironmentFile=` — `start-agent-session.sh` sources `.env.generated` itself —
-so verify the generated file directly and the launcher path, not a nonexistent
-`EnvironmentFile` property:
-
-```bash
-test -f ~/.config/mosaic/fleet/agents/<name>.env.generated
-systemctl --user cat mosaic-agent@<name> | grep ExecStart
-systemctl --user restart mosaic-agent@<name>
-```
-
-Full recovery runbook and the three-layer #791 protection model (manifest
-ownership → pre-update snapshot/restore → regen): see
-[Upgrade Safety & Recovery](./upgrade-safety-and-recovery.md).
-
 ## Release Preflight
 
 Run this checklist before cutting or dogfooding a fleet release:

docs/guides/upgrade-safety-and-recovery.md

@@ -1,147 +0,0 @@
-# Upgrade Safety & Recovery
-
-How Mosaic protects operator-owned configuration under `~/.config/mosaic` across
-framework upgrades, and how to recover if a projection is ever lost.
-
-A framework upgrade runs `install.sh` in keep-mode (`MOSAIC_INSTALL_MODE=keep`,
-`MOSAIC_SYNC_ONLY=1`) to refresh framework-owned files in place. The incident
-this hardening addresses: an upgrade that silently overwrites or deletes a file
-the operator owns — credentials, personas, a roster, or a generated agent env —
-with no snapshot to fall back to.
-
-Protection is layered. Each layer is independent; a later layer catches what an
-earlier one misses.
-
-## Layer 1 — Manifest-owned sync (prevention)
-
-The single source of truth for ownership is
-[`framework-manifest.txt`](../../packages/mosaic/framework/framework-manifest.txt).
-Both the bash installer and the TypeScript sync path resolve every path against
-this one file (parity is enforced by test), so they can never drift.
-
-- Ownership is **allow-list, deny-wins**: a path is framework-owned only if a
-  `[framework]` glob matches and no `[operator]` carve-out overrides it.
-- **Unknown paths default to operator** (fail-safe): a file the manifest never
-  anticipated is treated as operator-owned and is never pruned.
-- Keep-mode does a non-deleting copy plus an explicit, manifest-scoped prune that
-  only ever iterates framework globs — operator and unknown paths are
-  structurally unreachable by the prune.
-
-Result: a correct upgrade cannot touch operator config at all.
-
-## Layer 2 — Durable pre-update snapshot + verify net (safety + rollback)
-
-Before **any** mutation, the installer snapshots the operator-owned surface that
-exists into:
-
-```
-${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-timestamp>/
-```
-
-- `0700` directories / `0600` files (`umask 077`, scoped and restored),
-  outside `~/.config/mosaic` and outside any repo.
-- **Fail-open**: a snapshot failure warns but never aborts the upgrade it
-  protects.
-- Retention is `MOSAIC_BACKUP_RETENTION` snapshots (default 5).
-
-After the sync, a **verify net** compares each snapshot file against its target
-and restores (with a loud warning) any operator file the upgrade diverged or
-removed — a divergence means a manifest bug slipped through Layer 1.
-
-Inspect and restore snapshots with the CLI:
-
-```bash
-mosaic restore --list                 # dry-run: enumerate snapshots by timestamp
-mosaic restore --from <UTC-timestamp> # restore the operator surface from one snapshot
-mosaic restore --from <ts> --dry-run  # preview a specific restore without writing
-```
-
-`mosaic restore` reports **counts and relative paths only** — it never emits file
-contents, so a secret in `tools/_lib/credentials.json` is never echoed. Restores
-are confirmation-gated (`--yes` or `MOSAIC_ASSUME_YES`) and write each leaf
-atomically with `O_NOFOLLOW` (a symlink swapped in after the snapshot fails
-closed rather than following out of the managed tree).
-
-## Layer 3 — Regeneration from roster SSOT (recovery)
-
-Some operator files are **derived** and do not need a byte-for-byte snapshot to
-recover — they can be rebuilt from their source of truth. The fleet's per-agent
-generated env projections are the prime case:
-
-- `~/.config/mosaic/fleet/agents/<name>.env.generated` is a deterministic
-  projection of `~/.config/mosaic/fleet/roster.yaml`.
-- The launcher (`start-agent-session.sh`, invoked by
-  `mosaic-agent@<name>.service`) sources that generated projection to establish
-  each agent's identity, runtime, model, and working directory. If it is missing
-  or wrong, the agent cannot launch with its intended identity.
-
-`mosaic fleet regen` rebuilds those projections from the roster SSOT:
-
-```bash
-mosaic fleet regen            # dry-run (default): show what would be rebuilt
-mosaic fleet regen --json     # same, machine-readable
-mosaic fleet regen --write    # rebuild the projections on disk
-```
-
-- **Dry-run by default.** Nothing is written until you pass `--write`.
-- **Deterministic and idempotent** — the projection is a pure function of the
-  roster, so repeated `--write` runs produce byte-identical files.
-- **Projection-only. It never restarts an agent.** Recovery order forbids
-  restart-before-verify; `regen` has no path to systemd lifecycle at all.
-- **It rebuilds only `<name>.env.generated`** — it never writes, relocates, or
-  deletes the operator-owned `.env` / `.env.local` surface.
-- It **validates the roster the same way `reconcile` does** (persona resolution
-  and protected-class tool-policy match), so a hand-edited or corrupt roster is
-  rejected rather than projected, and a `--write` takes the shared reconcile
-  lock so it cannot race a concurrent reconcile.
-- Output is **paths and counts only** — the rendered `KEY=value` body is never
-  echoed.
-
-`regen` uses the exact same roster→env mapping as `mosaic fleet reconcile`, so a
-recovered projection matches what a normal reconcile would have written.
-
-## Recovery runbook — wiped `fleet/agents/*.env.generated`
-
-If an upgrade (or a manual mistake) has left an agent without its generated
-projection, **do not restart the unit first** — a launch against a missing
-projection fails closed, and any stale state must be corrected before restart,
-not after.
-
-1. **Prefer a snapshot restore if one exists** (byte-exact operator state):
-
-   ```bash
-   mosaic restore --list
-   mosaic restore --from <UTC-timestamp>
-   ```
-
-2. **Otherwise regenerate the derived projections from the roster SSOT:**
-
-   ```bash
-   mosaic fleet regen            # confirm the plan (create vs rebuild per agent)
-   mosaic fleet regen --write    # rebuild fleet/agents/<name>.env.generated
-   ```
-
-3. **Verify each unit will resolve the intended runtime/workdir _before_ any
-   restart.** The unit sets **no** `EnvironmentFile=` — it launches from a minimal
-   environment and `start-agent-session.sh` sources `.env.generated` itself, so
-   verify the generated file directly and confirm the launcher path:
-
-   ```bash
-   # Confirm fleet/agents/<name>.env.generated exists and carries the intended
-   # MOSAIC_AGENT_* values (name, runtime, model, workdir, socket).
-   test -f ~/.config/mosaic/fleet/agents/<name>.env.generated
-   # Confirm the unit launches the session script that reads it.
-   systemctl --user cat mosaic-agent@<name> | grep ExecStart
-   ```
-
-4. **Only then restart, one unit at a time:**
-
-   ```bash
-   systemctl --user restart mosaic-agent@<name>
-   ```
-
-## See also
-
-- Design: [`docs/design/791-upgrade-config-protection.md`](../design/791-upgrade-config-protection.md)
-- Fleet operations: [`docs/guides/fleet-local-canary.md`](./fleet-local-canary.md)
-- Ownership SSOT: [`packages/mosaic/framework/framework-manifest.txt`](../../packages/mosaic/framework/framework-manifest.txt)

docs/scratchpads/791-upgrade-config-protection.md

@@ -214,316 +214,3 @@ Re-ran codex again; it found two more rollback-path gaps `set -E` cannot catch.
 - Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 · HARD GATE 193/193 ·
   rollback 28/28 (was 14, +14 for D1/D2 with controls) · migration 21/21. shellcheck clean on new lines.
   No --no-verify. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
-
-## Session 3 (2026-07-16) — PR1 MERGED, starting PR2 (durable snapshot + restore + secrev)
-PR1 (#802) squash-merged → main `32a0ffba`; issue #791 stays open (3-PR DAG umbrella). Independent Opus
-adversarial/security review APPROVED at head `af627e75` (Gitea RoR cmt 17892); lead ran rollback 28/28 +
-HARD GATE 193/193 green; CI #1877 green. PR2 UNBLOCKED.
-
-PR2 branch: `feat/791-pr2-snapshot-restore` off `origin/main` 32a0ffba. Same treatment applies:
-tests-first red-first, independent review + durable Gitea Reviewer-of-Record comment BEFORE MS-LEAD runs
-the queue guard/merge. Report PR2 number + exact head when ready. PR body: `Part of #791` (NOT Fixes).
-
-### PR2 scope (ratified §3/§5 of design doc, Mos-approved — do NOT re-litigate)
-- **(a) Durable pre-update snapshot** to `${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-ts>/`
-  — OUTSIDE ~/.config/mosaic and any repo. Perms dir 0700 / files 0600 (umask 077 + explicit chmod).
-  Scope = operator-owned surface that EXISTS (operatorReserved paths), not the framework tree. Taken
-  BEFORE any mutation. Retention N=5 (`MOSAIC_BACKUP_RETENTION`), prune older.
-- **Post-sync verify + selective restore**: diff operator surface vs snapshot; (b) should never touch
-  operator paths, so ANY diff = manifest bug → restore affected paths + warn loudly. (a) catches a (b) miss.
-- **`mosaic restore`** (TS CLI): `--list` (default, dry-run) enumerates snapshots by ts; `--from <ts>`
-  restores over operator surface, confirmation-gated. Counts/paths only.
-- **Secret-safety (secrev)**: snapshot/restore NEVER emit file contents; only paths/counts. Tests assert
-  0700/0600 AND that a secret value seeded in tools/_lib/credentials.json never appears in any output.
-
-### PR2 implementation status (2026-07-16, ready-for-review)
-All three tasks implemented, red-first proven, unit-green:
-- **Task #10 — durable snapshot (install.sh)**: `backup_root()`/`enumerate_operator_files()`/
-  `prune_durable_snapshots()`/`make_durable_snapshot()` wired into keep-mode main() after `manifest_load`,
-  before any mutation. umask 077 + explicit chmod 700/600. UTC ts, collision suffix. FAIL-OPEN (a backup
-  failure never aborts the upgrade it protects). Retention `MOSAIC_BACKUP_RETENTION` (default 5), in-place
-  `sort -r -o` prune (no `mv` — stays inside the rsync-absent coreutils whitelist).
-- **Task #11 — post-sync verify net (install.sh)**: `verify_operator_surface()` runs after sync (trap
-  disarmed), `cmp -s` each snapshot file vs target; restores any diverged/missing operator file + warns
-  loudly (a divergence = manifest bug). VERIFY-NET wired before `cleanup_snapshot`.
-- **Task #12 — `mosaic restore` (TS)**: `src/commands/restore.ts` + co-located spec (19 tests).
-  `--list` default (dry-run enumerate), `--from <ts>` confirmation-gated restore, `--dry-run`, `--yes`/
-  `MOSAIC_ASSUME_YES`. Injectable `confirm` for testability (proceed/decline/env-bypass covered). Restored
-  files forced 0600. Registered in `cli.ts`. Path convention mirrors install.sh `backup_root()`.
-- **CI**: `.woodpecker/ci.yml` upgrade-guard runs the new `test-upgrade-durable-snapshot.sh` gate.
-- **Gates green**: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1241 (+5) ·
-  durable-snapshot 26/26 · manifest-guard 193/193 · rollback 28/28 · migration 21/21.
-  Est. new-code coverage ≈93% (only the interactive readline default + process.exit-on-error uncovered).
-- Regression fixed: PR2's `date`/`sort`/`mv` broke the rsync-absent manifest-guard PATH whitelist →
-  made date/sort fail-open, replaced `mv` with in-place `sort -o`, added `date sort` to the test whitelist
-  + isolated `XDG_STATE_HOME`. All 193 manifest-guard assertions green under restricted PATH.
-- Codex code-review + security-review (secrev) run on the uncommitted diff before commit.
-
-### PR2 review round 1 — findings + remediations (2026-07-16, pre-PR)
-Codex code-review returned **request-changes** (1 blocker + 3 should-fix); Codex security-review returned
-**high** (1 high + 1 medium). Deduped to 5 distinct defects, ALL legitimate, ALL fixed FORWARD, each with
-a red-first regression test whose control neuters exactly the guard under test:
-
-- **A · BLOCKER — verify net undid the legacy bin/ migration (install.sh).** On a pre-v2 install `bin/**`
-  is operator-classified, so the durable snapshot captured it; `run_migrations()` deletes bin/ on purpose,
-  but `verify_operator_surface()` then saw it "missing" and healed it back — the migration would be silently
-  undone forever once the version stamps. **Fix:** `MIGRATION_REMOVED_PATHS[]` recorded by run_migrations
-  (`bin`,`rails`) + `is_migration_removed()` skip in the verify loop (`# MIGRATION-SKIP-GUARD`).
-  **Test:** Part 6 — v1 fixture with bin/; shipped keeps it removed + stamps v3; control (guard stripped)
-  wrongly restores bin/tool.sh.
-- **B · HIGH (CWE-59) — restore/verify wrote secrets THROUGH a symlink (install.sh + restore.ts).** An
-  attacker swapping an operator path (e.g. tools/_lib/credentials.json) for a symlink after the snapshot
-  would make `cp`/`copyFileSync` write the snapshot's secret out through the link. **Fix (bash):** refuse a
-  symlinked ancestor (`has_symlinked_parent`), drop a symlinked leaf before restore
-  (`# SYMLINK-LEAF-GUARD`). **Fix (TS):** reuse audited `secure-file.ts` — `assertCanonicalContainment`
-  + `ensureManagedDirectory` on every dst, open the leaf `O_NOFOLLOW|O_CREAT|O_TRUNC` 0600 (ELOOP =
-  fail-closed). **Tests:** Part 7 (shipped leaves external exfil target untouched, restores a real 0600
-  file; control leaks the secret through the link) + restore.spec symlinked-leaf/ancestor cases (red-first).
-- **C · MEDIUM/should-fix (CWE-22) — `--from` traversal escaped the backup root (restore.ts).**
-  `join(root, from)` accepted `../poison`. **Fix:** validate the selector against
-  `^\d{8}T\d{6}Z(?:-\d+)?$`, build exactly `join(root,'pre-update-'+ts)`, `lstat` (reject symlinked snap
-  dir). **Test:** restore.spec `it.each` of 6 malformed selectors + `--from ../poison` fail-closed (red-first).
-- **D · should-fix — verify `mkdir -p` unguarded under set -e (install.sh).** A parent replaced by a
-  regular file aborted the installer before the recovery pointer printed. **Fix:** guard `mkdir -p`, warn
-  + `continue` on failure (keeps healing remaining files).
-- **E · should-fix — snapshot `umask 077` leaked process-global (install.sh).** Later sync copies/dirs
-  inherited 0600/0700. **Fix:** save `old_umask`, restore on EVERY return path (`# UMASK-RESTORE-NORMAL`).
-  **Test:** Part 8 — synced framework file is 0644 while the secret backup stays 0600; control (restore
-  stripped) makes the synced file 0600.
-
-**Full gate suite re-run after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic
-vitest **1252** · restore.spec **30** · durable-snapshot **41** · manifest-guard 193 · rollback 28 ·
-migration 21. shellcheck clean on all new lines; new test markers mirror the existing `# VERIFY-NET`
-anchor convention. NOTE: codex self-review does NOT satisfy the independent-review gate — an independent
-(author≠reviewer) review + durable Gitea Reviewer-of-Record comment is still required before MS-LEAD merges.
-
-## Session 4 (2026-07-16) — PR2 MERGED, PR3 built (fleet regen — recovery layer)
-PR2 (#811) squash-merged → main `31607a4a`; issue #791 stays open (final PR of the 3-PR DAG). Independent
-exact-head RoR at `d12c5f78` APPROVE (Gitea cmt 17904); #1882 green; busybox-portable Part 7 control fix
-verified in-Alpine. PR3 UNBLOCKED.
-
-PR3 branch: `feat/791-pr3-fleet-regen` off `origin/main` 31607a4. Same discipline: tests-first red-first,
-independent review + durable Gitea RoR BEFORE MS-LEAD runs the queue guard/merge. PR body `Part of #791`.
-
-### PR3 scope (ratified §4/§7 of design doc) — `mosaic fleet regen`
-Projection-only recovery command: rebuilds each `fleet/agents/<name>.env.generated` from `roster.yaml`
-(SSOT). Dry-run default; `--write` applies; `--json` machine output. Structural guarantee: NO code path to
-systemd lifecycle — **never restarts an agent**. Single-SSOT: reuses `projectRosterV2AgentGeneratedEnv`
-(extracted, shared with the reconciler apply path) so regen and reconcile cannot drift. Secrev: paths +
-counts only, never the rendered KEY=value body.
-
-New files: `commands/fleet-regen-command.ts` (+ `.spec.ts`), guide `docs/guides/upgrade-safety-and-recovery.md`
-(three-layer model: PR1 manifest ownership → PR2 snapshot/restore → PR3 regen; do-NOT-restart-before-verify
-runbook), regen reference added to `docs/guides/fleet-local-canary.md`. Wired in `commands/fleet.ts`.
-
-### Independent review (3 reviewers: subagent code-reviewer + codex code-review + codex security) → 4 fixes, red-first
-- **A · BLOCKER (codex) — regen mutated/deleted legacy operator env.** `applyPreparedAgentEnvironmentProjection`
-  also writes `.env.local`/`.env.quarantine` and unlinks legacy `.env`. Violated projection-only contract.
-  **Fix:** NEW generated-only boundary primitives `prepareGeneratedAgentEnvironmentProjection` +
-  `applyPreparedGeneratedAgentEnvironmentProjection` (write ONLY `<name>.env.generated`). regen now has no
-  code path that touches `.env`/`.env.local`/`.env.quarantine`. **Test:** projection-only leaves legacy `.env`
-  verbatim, no local/quarantine fabricated.
-- **B · should-fix (codex + subagent + security) — partial write on mid-loop failure.** Interleaved
-  prepare/apply left earlier agents written when a later agent failed prepare. **Fix:** PREPARE ALL agents
-  before writing ANY (mirrors reconciler `defaultPrepareProjections`). **Test:** 2nd agent's projection
-  pre-seeded 0644 → prepare rejects → coder0 NOT written, exit 1.
-- **C · subagent — semantic-validation bypass.** Default readRoster skipped `validateRosterV2Semantics`, so
-  a tampered protected-class `tool_policy` would be silently projected. **Fix:** default readRoster now runs
-  `validateRosterV2Semantics` (persona resolution + protected-class match), rolesDir/overrideDir defaults
-  mirroring the reconciler. **Test:** merge-gate agent w/ tool_policy=code → fails closed, no write.
-- **D · MEDIUM (codex security, CWE-362) — concurrent-reconcile race.** regen `--write` wrote without the
-  reconcile lock. **Fix:** `--write` acquires `acquirePrivateReconcileLock(mosaicHome)` for the whole
-  read-prepare-apply sequence, released in `finally`; dry-run stays lock-free. **Test:** pre-held lock →
-  regen fails closed, no write.
-
-**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1265**
-(regen spec 13, incl. 4 new red-first regressions). NOTE: codex self-review does NOT satisfy the
-independent-review gate — an independent (author≠reviewer) review + durable Gitea RoR is still required
-before MS-LEAD merges. STOP at PR-open for MS-LEAD's exact-head review; do NOT self-merge.
-
-## Session 5 — PR3 review round 2 (finding L + M1/M2/M3), red-first fixes
-
-Second review pass on the lock-cleanup plumbing surfaced one round-1 residual (L) and three round-2
-findings (M1 blocker, M2/M3 should-fix). All fixed red-first (RED proven per-finding, then GREEN).
-
-- **L · should-fix (codex r1) — mutation-lock release swallowed unlink failures.** regen's
-  `acquirePrivateRosterMutationLock` release copied CRUD's `unlink().catch(()=>{})`, hiding a stale
-  `roster.yaml.mutation.lock`. **Fix:** its release PROPAGATES the unlink fault (finding-J stale-lock
-  warning then fires for this lock too). **Test:** acquire real lock, `rm` it, assert `release()` rejects.
-- **M1 · BLOCKER (codex r2) — replacement-lock race.** The propagating release from L did an
-  UNCONDITIONAL `unlink(lockPath)` without proving ownership. If the lock is cleared + re-created by
-  another writer mid-op, regen deletes the STRANGER's live lock → a third writer enters → mutual
-  exclusion defeated. **Fix (reuse, not reimplement):** generalized the reconciler's ownership-proving
-  lock body into shared `acquirePrivateManagedRosterLock(mosaicHome, lockLeaf, busyMessage, openLock)`;
-  `acquirePrivateReconcileLock` delegates to it (behavior-identical: same leaf/codes/messages), and a NEW
-  hardened `acquirePrivateRosterMutationLock` (now in fleet-reconciler.ts, leaf `roster.yaml.mutation.lock`)
-  records dev/ino + ownership token and RE-PROVES ownership (`assertLockOwnership`) before unlinking —
-  fails closed as `lock-cleanup-failed` if replaced. Removed the crud-based export; reverted
-  `acquireMutationLock` (fleet-agent-crud.ts) to its original inline empty-file/swallowing-release form
-  (CRUD behavior intentionally unchanged). Compatibility: CRUD empty-file `wx` and regen tokened `wx`
-  contend on the same path but never co-own (wx winner owns; loser → concurrent-mutation), so the token
-  is only ever read back by the same regen invocation. **Test:** acquire, `rm`+recreate lock (new inode),
-  assert `release()` rejects AND the replacement survives (not unlinked).
-- **M2 · should-fix (codex r2) — acquire-unwind fault dropped.** The acquire-failure catch discarded
-  `releaseFleetLocks`' return (a possible fault on the already-held first lock). **Fix:** capture and
-  augment — `const releaseFault = await releaseFleetLocks(releases); throw augmentWithLockCleanupFault(error, releaseFault);`
-  (symmetric to finding J). **Test:** mutation lock acquires w/ faulting release + reconcile acquire
-  throws → thrown error mentions stale/lock, nothing written.
-- **M3 · should-fix (codex r2 + subagent REQUEST-CHANGES) — cleanup warning named only reconcile lock.**
-  Finding L made the mutation-lock release fault reachable, so the `cleanup` marker can originate from
-  EITHER lock. **Fix:** `formatFleetRegenReport`'s WARNING now names BOTH `roster.yaml.mutation.lock` and
-  `roster.yaml.reconcile.lock`, matching `augmentWithLockCleanupFault`. **Test:** fault the mutation-lock
-  release specifically → report names both lock files.
-
-**Refactor note (no cycle):** neither fleet-reconciler nor fleet-agent-crud imports the other; regen
-imports lock acquirers from fleet-reconciler and the projection mapping from fleet-reconciler. The two
-reconcile-lock reviewers reconciled: independent reviewer validated acquire-time empty-file compatibility
-(preserved), codex flagged RELEASE-time replacement race (closed by ownership proof) — non-contradictory.
-
-**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1275**
-(regen spec 23, incl. 7 red-first lock regressions E/F/G/K/L/M1/M2/M3). RED proven per-finding by
-temporary revert before re-applying each fix. Independent (author≠reviewer) review of M1/M2/M3 + codex
-code/security re-run in flight. STOP at PR-open for MS-LEAD's exact-head review + durable Gitea RoR; do
-NOT self-merge; #791 umbrella stays OPEN; PR body `Part of #791`.
-
-### Round 3 review (after M1/M2/M3) — independent review PASS + codex residual-TOCTOU disposition
-Three reviewers on the post-M1/M2/M3 head:
-- **Independent (subagent, author≠reviewer) — PASS.** Verified M1/M2/M3 all correctly fixed; "never
-  restarts" is STRUCTURAL (runner never referenced in executable code); no secrets; no deadlock (only
-  regen holds both locks); tests meaningful (assert inode preservation + exact lock-file names). Raised:
-  - **should-fix #1 (fixed, red-first):** generalizing the lock helper left `assertSafeLockLeafIfPresent`/
-    `assertLockOwnership` hardcoding "reconciliation lock" in thrown messages → a MUTATION-lock fault
-    misreported as the reconcile lock, undercutting M3's accurate-diagnosis goal. **Fix:** thread
-    `lockLabel = fleet/<leaf>` through both helpers + the generic lock-io messages, so every fault names
-    the actual lock file. Red-first: strengthened the M1 test to assert `/roster\.yaml\.mutation\.lock/`
-    (RED: got "reconciliation lock"; GREEN after). Also resolves nit #3 (generic-message drift).
-  - **nit #2 (fixed):** `FleetRegenResult.cleanup` JSDoc still said "the shared reconcile lock"; now names
-    both locks (regen holds both).
-  - **nit #4 (fixed):** removed the redundant duplicate `assertLockOwnership` call before unlink
-    (pre-existing in merged main; harmless but dead — dropped since the fn was already being touched).
-- **Codex security — clean (risk: none).** Validates roster semantics, constrains env values, no shell
-  eval, no secret output, generated-only writes, serialized against both locks.
-- **Codex code — request-changes, 1 "blocker": residual check-then-unlink TOCTOU.** Between the final
-  `assertLockOwnership` and the path-based `unlink`, an external actor could vacate our inode and a new
-  writer grab the path, so the unlink deletes the stranger's lock. **Disposition: documented known
-  limitation, NOT fixed in PR3.** Rationale: (1) byte-identical to the MERGED, shipped reconcile-lock
-  release on origin/main (fleet-reconciler.ts L654-659) — not introduced here; (2) UNREACHABLE within the
-  `wx` writer protocol — no Mosaic writer removes a lock it doesn't own (wx fails EEXIST while our inode
-  exists), so only external interference can vacate our inode in the sub-instruction window; (3) the
-  ownership guard DOES close the reachable case (stale-lock reaper/operator cleared our lock + another
-  writer took it BEFORE release began → fail closed, don't delete stranger's lock); (4) the true atomic
-  fix — fd-held advisory lock (flock/lockf) adopted by ALL fleet writers (CRUD + reconcile + regen) — is
-  a cross-cutting mechanism change touching merged CRUD + reconciler, out of scope for a projection-only
-  recovery PR. Documented honestly in the acquirer doc + M1 test comment. **The binding independent
-  review did NOT treat this as a blocker.** Recommendation to MS-LEAD: proceed to PR-open + spin a
-  SEPARATE follow-up issue for the fd-advisory-lock migration; MS-LEAD adjudicates scope at exact-head
-  review (merge authority).
-
-**Gates after round-3 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1275** (regen spec 23). Fresh codex code re-run in flight to confirm no NEW issues from the label fix.
-
----
-
-## Session 6 — Round 4/5 convergence (stranded-lock robustness)
-
-**Two independent reviewers converged on the SAME should-fix** on the init-failure cleanup path,
-strengthening confidence it was real:
-
-- **Codex code-review-5 — 0 blockers, 1 should-fix.** "Stat failure after lock creation strands the new
-  lock." When `handle.stat()` ITSELF fails right after the `wx` create (transient EIO/EBADF), `created`
-  is `undefined`, so `removeOwnedLockLeafBestEffort` had `if (!created) return;` → no cleanup → the
-  just-created `roster.yaml.mutation.lock`/`reconcile.lock` is stranded, permanently blocking future
-  regen + CRUD. (Notably NO blocker, and the TOCTOU is no longer flagged in code-review as of r5.)
-- **Independent delta reviewer (author≠reviewer, pr-review-toolkit) — no blockers, same should-fix.**
-  Independently flagged the identical `!created` gap; validated FIX 1 (label threading — no call site
-  missed, codes unchanged, no test depended on old text) and FIX 2 (dev/ino-guarded cleanup, best-effort,
-  happy-path release reuses captured dev/ino) as correct. Suggested an unconditional best-effort unlink
-  in the `!created` branch; I took the **safer** variant below.
-- **Codex security-review-5 — 0 crit / 0 high / 1 medium.** The single medium is the SAME residual
-  check-then-unlink TOCTOU already dispositioned in round 3 (its own remediation = "migrate every writer
-  to an fd-held advisory lock" = the follow-up issue). No new security finding. No secrets.
-
-**Fix (red-first, safer than an unconditional unlink):** thread the persisted random `token` into
-`removeOwnedLockLeafBestEffort`. Two independent ownership proofs now: primary dev/ino (unchanged), and a
-**fallback** when the post-create stat failed — read the leaf and unlink ONLY if its content equals our
-`randomUUID()` token. Only OUR lock carries that token, so a CRUD (empty) or differently-tokened
-replacement is never deleted. `tokenPersisted` guards passing the token (only after `writeFile` lands).
-Doubly-degenerate case (stat fails AND token write never landed) leaves the lock in place rather than
-risk deleting a stranger's file — requires two independent fs faults on a just-created fd; documented.
-
-- **Red-first proof:** new test `does not strand the lock file when the post-create stat itself fails`
-  injects a real `wx` create + a Proxy handle whose `stat()` rejects (writeFile/close succeed), asserts
-  `exists(lockPath) === false`. RED before fix (`expected true to be false` — lock stranded); GREEN after.
-- **Also fixed (delta nit #3):** `fleet-regen-command.ts` `acquireRosterMutationLock` JSDoc said "CRUD's
-  private lock"; the default is the reconciler's hardened ownership-proving acquirer for the same
-  `fleet/roster.yaml.mutation.lock` path. Corrected.
-- **PR-description note (delta nit #2):** FIX 1 also collapsed a pre-existing duplicate back-to-back
-  `assertLockOwnership` call in the release closure (identical args, no intervening logic) into one — a
-  no-op simplification of merged code, not a behavior change. Called out so a future reader doesn't
-  wonder if the duplicate had a purpose.
-
-**Gates after round-4 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1277** (regen spec now 25: +1 stat-failure stranded-lock regression). Residual TOCTOU still deferred to
-the fd-advisory-lock follow-up issue; MS-LEAD adjudicates scope at exact-head review (merge authority).
-
----
-
-## Session 6 — Round 6 (persona-root wiring)
-
-**Codex code-review-6 — 0 blockers, 1 should-fix (NEW, distinct from the lock work).** "Forward
-configured persona directories to regen." `registerFleetRegenCommand` was registered at
-`fleet.ts:2069` with only `{ runner, mosaicHome }`, discarding `deps.reconcileDeps.rolesDir` /
-`overrideDir`. The regen command ALREADY has those seams (validates roster semantics via
-`validateRosterV2Semantics({ rolesDir, overrideDir })`, defaulting to `<mosaicHome>/fleet/roles{,.local}`),
-but the top-level wiring never forwarded the configured roots. **Impact:** in a deployment with custom
-persona roots, `fleet reconcile` (which honors the overrides) would ACCEPT a roster while `fleet regen`
-REJECTS the same roster (persona resolution against the wrong default dir) — blocking the recovery
-command and violating the documented "resolves personas the SAME way reconcile does" contract.
-
-**Fix (red-first):** forward `rolesDir`/`overrideDir` from `deps.reconcileDeps` into
-`registerFleetRegenCommand` at `fleet.ts:2069`. Red-first test `forwards configured persona roots
-(rolesDir/overrideDir) from reconcileDeps into regen`: seeds personas ONLY under a custom root, leaves
-the default `<home>/fleet/roles` empty, registers with `reconcileDeps: { rolesDir, overrideDir }`, and
-requires `fleet regen` to SUCCEED. RED before fix (`expected 1 not to be 1` — regen validated against the
-empty default and exited 1); GREEN after.
-
-**Codex security-review-6 — 0 crit / 0 high / 1 medium.** Same residual check-then-unlink TOCTOU, now
-noted at BOTH the release closure and the init-cleanup path; remediation = fd-held advisory lock across
-all writers = the SAME deferred follow-up item. No new security finding, no secrets.
-
-**Independent confirmation review of the token-fallback fix (Session 6/round 4) — PASS, no findings.**
-All 7 verification points confirmed; reviewer mechanically reverted `removeOwnedLockLeafBestEffort` to
-the pre-fix `if (!created) return;` and re-ran the new test → RED (`expected true to be false`),
-confirming the test genuinely pins the fix; restored after. No lint/type issues; doc-comment accurate.
-
-**Gates after round-6 fix (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1278** (regen spec now 26: +1 persona-root wiring regression).
-
----
-
-## Session 6 — Round 7 convergence (review CLOSED for PR-open)
-
-- **Codex code-review-7 — 0 blockers, 1 should-fix = the residual TOCTOU** (previously a "blocker" in r3,
-  dropped in r4/r5, now re-surfaced as a should-fix). **Codex security-review-7 — 0 crit / 0 high /
-  1 medium = the SAME residual TOCTOU.** Codex has CONVERGED: the only remaining finding across both
-  streams is that one race, whose own remediation is "fd-held advisory lock shared by all fleet writers"
-  = the deferred follow-up. No new distinct finding; the wiring fix introduced nothing.
-- **Independent confirmation review of the persona-root wiring fix — PASS, no findings.** Reviewer
-  mechanically reverted the two forwarded lines → RED (`Roster v2 agent "coder0" class "code" does not
-  resolve to a readable persona` → exit 1), restored → GREEN (26 regen + 204 fleet tests). Confirmed the
-  optional-chaining fallback preserves default-deployment behavior and no type/lint issue.
-
-**Review disposition for PR-open:** ALL actionable findings fixed red-first across rounds 3–6 (label
-threading, stranded-lock on init failure, stat-failure strand, persona-root wiring). The residual
-check-then-unlink TOCTOU is the ONLY open item and is DEFERRED to a follow-up issue (fd-advisory-lock
-migration across CRUD + reconcile + regen) — byte-identical to merged origin/main's reconcile-lock
-release, unreachable within the `wx` writer protocol (no Mosaic writer removes a lock it doesn't own;
-only external `rm`/a stale-lock reaper can vacate the inode mid-release), and its true fix is a
-cross-cutting mechanism change out of scope for a projection-only recovery PR. Two independent human-agent
-reviews (author≠reviewer) treated it as non-blocking. MS-LEAD adjudicates scope at exact-head review
-(merge authority); recommendation = proceed to PR-open + spin the follow-up issue.
-
-**Final gates (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1278**
-(regen spec 26). No secret values in any snapshot/projection/report output (counts + paths only). Regen
-NEVER issues a lifecycle/restart call (load-bearing recordingRunner gate). STOP at PR-open for MS-LEAD's
-exact-head review + durable Reviewer-of-Record before any merge; do NOT self-merge.

docs/scratchpads/807-glpi-partial-content.md

@@ -1,64 +0,0 @@
-# Issue #807 — GLPI list wrappers accept HTTP 206
-
-- **Branch:** `fix/807-glpi-206`
-- **Task:** Gitea issue #807
-- **Role:** Author-only worker reporting to `mosaic-100`; no self-review or merge
-- **Started:** 2026-07-16
-
-## Objective
-
-Fix the shipped GLPI ticket, computer, and user list wrappers so ranged responses with HTTP 206 Partial Content render successfully while genuine HTTP failures remain non-zero errors.
-
-## Scope
-
-- Modify only the three affected list wrappers and a focused shell regression test.
-- Do not touch `session-init.sh`, `ticket-create.sh`, or `docs/TASKS.md`.
-- Add task-local delivery evidence here as required by the mission protocol.
-
-## Plan
-
-1. Add a deterministic shell harness that copies each wrapper beside stubbed `session-init.sh`, credentials, and `curl` boundaries.
-2. Prove RED against the current 200-only gates: 206 must fail before the implementation change.
-3. Update all three status gates to accept exactly 200 or 206.
-4. Prove GREEN for 206 rendering and genuine 401/500 failures, then run repository quality gates.
-5. Commit with co-author attribution, run the push queue guard, push, and open a PR for independent review and merge by the team lead.
-
-## Budget
-
-- No explicit token cap supplied.
-- Soft estimate: 8K tokens; narrow single-worker execution with no exploratory scope.
-
-## Progress
-
-- [x] Mission, task, PRD, QA, documentation, and code-review guidance loaded.
-- [x] RED regression evidence captured: `test-list-http-status.sh` exited 1; all three wrappers rejected 206 while retaining 401 failures.
-- [x] Implementation complete.
-- [x] Relevant tests and repository gates green.
-- [ ] Commit pushed and PR opened.
-
-## Tests and evidence
-
-- RED (before source fix): `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → exit 1; ticket/computer/user 206 assertions failed, all 401 assertions passed.
-- GREEN: `bash -n packages/mosaic/framework/tools/glpi/{ticket-list.sh,computer-list.sh,user-list.sh,test-list-http-status.sh}` → pass.
-- GREEN: `shellcheck packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → pass.
-- GREEN: `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → 6 assertions pass (206 renders and 401 errors for all three wrappers).
-- GREEN: `pnpm typecheck` → 42/42 tasks pass.
-- GREEN: `pnpm lint` → 23/23 tasks pass.
-- GREEN: `pnpm format:check` → all matched files pass.
-- Setup note: initial gate attempts could not start because the fresh worktree lacked dependencies; `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` restored the locked workspace dependencies without lockfile changes.
-
-## Acceptance criteria mapping
-
-| Criterion | Evidence |
-| --- | --- |
-| HTTP 206 succeeds and renders each ranged list | Focused test's three 206 render assertions pass |
-| Genuine HTTP failures remain non-zero with existing diagnostics | Focused test's three HTTP 401 assertions pass |
-| Only affected list wrappers change | Diff contains the three status predicates plus focused test/evidence; session and create wrappers untouched |
-
-## Documentation decision
-
-No operator/API documentation change is needed: this restores documented list behavior for a healthy GLPI response without changing command syntax, output, configuration, or public contracts. This task scratchpad records delivery evidence.
-
-## Risks / blockers
-
-- Existing dirty `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are runtime-owned and will not be edited or committed.

docs/scratchpads/808-agent-send-sender-identity.md

@@ -1,37 +0,0 @@
-# Issue #808 — agent-send sender identity
-
-## Objective
-
-Fix cross-socket `agent-send.sh` preambles so replies route to the real sender rather than a destination-socket holder session.
-
-## Scope and acceptance criteria
-
-- Prefer exported `MOSAIC_AGENT_NAME` as the authoritative sender session name.
-- If it is unset, query the sender's local/default tmux socket for `#S` without destination `-L` arguments.
-- Preserve `?` when sender identity cannot be determined.
-- Do not alter destination socket dispatch.
-- Add red-first regressions for all three identity paths.
-
-## Plan
-
-1. Extend `agent-send.test.sh` with deterministic fake-tmux coverage.
-2. Run the test against the unpatched implementation and record RED evidence.
-3. Apply the minimal sender lookup fix only.
-4. Run the focused suite and repository quality gates.
-5. Commit, queue-guard, push, and open an author-only PR for independent review.
-
-## Constraints and risks
-
-- Worker lane is author-only: no self-review or merge.
-- `docs/TASKS.md` and mission state are orchestrator-owned and will not be modified.
-- Pre-existing runtime changes under `.mosaic/orchestrator/` are excluded from this work.
-- Budget: no explicit token cap; keep changes limited to the shell tool, sibling regression test, and this scratchpad.
-
-## Evidence
-
-- RED: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` failed on the unpatched implementation with `PASS=12 FAIL=3`; it selected `destination-holder` instead of both `MOSAIC_AGENT_NAME=authoritative-agent` and local session `local-agent`. The genuinely unavailable sender case already exercised and preserved `?`.
-- GREEN: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed with `PASS=15 FAIL=0`; coverage includes env authority, local/default tmux fallback across a destination `-L`, explicit rejection of the destination holder, and `?` fallback.
-- Syntax: `bash -n packages/mosaic/framework/tools/tmux/agent-send.sh packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed.
-- Quality gates: `pnpm typecheck` (42/42 tasks), `pnpm lint` (23/23 tasks), and `pnpm format:check` all passed after installing the frozen lockfile dependencies. The first install attempt failed because pnpm's configured store pointed at `/root`; retrying with the existing user-owned store (`--store-dir /home/hermes/.local/share/pnpm/store`) succeeded without changing tracked dependency files.
-- Documentation: no public API or operator workflow changed; the source comment, regression-test contract, and this implementation record cover the internal bug fix.
-- Independent review: intentionally pending for the reviewer assigned by `mosaic-100`; this author-only lane will not self-review or merge.

docs/scratchpads/ms-792-fleet-enoent-installer.md

@@ -1,36 +0,0 @@
-# ms-792 — Fleet roster error handling and installer heading
-
-## Objective
-
-Make expected missing or malformed fleet roster configuration fail with an actionable message and nonzero exit instead of a raw Node stack trace. Ensure the installer preserves the `@mosaicstack/mosaic` heading.
-
-## Plan
-
-1. Add failing coverage for missing and malformed roster input.
-2. Centralize roster-file read and parse error translation; add the CLI async error boundary.
-3. Sweep fleet command read paths that bypass the roster loader.
-4. Replace the installer heading output with format-safe rendering and test it.
-5. Run focused and repository quality checks; request independent review.
-
-## Progress
-
-- 2026-07-16: Confirmed issue #792 and branch base `9745bc3f`.
-- 2026-07-16: Installed locked workspace dependencies using a worktree-local pnpm store; no `.mosaic/` files were changed intentionally.
-- 2026-07-16: Added a shared roster read/parse guard and routed v1 fleet commands plus v1/v2 selection through Commander’s actionable nonzero error path. V2 command modules already return structured nonzero JSON errors for their guarded reads.
-- 2026-07-16: Replaced installer heading `echo` with format-safe `printf`; added a regression check for the scoped package heading.
-- 2026-07-16: Rebuilt CLI and manually verified `fleet ps` with no roster prints the initialization hint, exits 1, and has no stack trace.
-- 2026-07-17: Rebased #818 onto `origin/main` at `9ddc6fbd` (#791 PR3). The added `fleet regen` command had a canonical roster read in its sibling module; it now uses the same missing-roster guard and Commander exit path. Internal NORTH_STAR, preset, and post-write invariant reads remain intentionally unguarded.
-
-## Verification
-
-- `pnpm --filter @mosaicstack/mosaic test` — PASS (61 files, 1,046 tests; executed outside sandbox because CLI smoke tests spawn Node)
-- `pnpm typecheck` — PASS
-- `pnpm lint` — PASS
-- `pnpm format:check` — PASS
-- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts src/commands/install-heading.spec.ts` — PASS (209 tests)
-- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet-regen-command.spec.ts` — PASS (27 tests, including missing canonical roster)
-- Instrumented Vitest coverage is unavailable because `@vitest/coverage-v8` is not declared in this repository. Each branch added in the roster guard has direct unit coverage.
-
-## Risks / blockers
-
-- Dependency installation is required before executing Vitest, TypeScript, lint, and formatting gates.

packages/mosaic/README.md

@@ -47,61 +47,6 @@ export MOSAIC_ADMIN_PASSWORD="securepass123"
 mosaic gateway install
 ```
 
-## Runtime launchers
-
-```bash
-mosaic claude            # Launch Claude Code with Mosaic injection
-mosaic yolo claude       # …with --dangerously-skip-permissions
-mosaic codex | opencode | pi
-```
-
-### `mosaic claudex` (EXPERIMENTAL)
-
-Runs GPT models **inside the Claude Code harness** by pointing Claude Code at a
-local [`claude-code-proxy`](https://github.com/raine/claude-code-proxy) that
-translates the Anthropic Messages API to a ChatGPT-subscription (Codex OAuth)
-backend. This is **not Anthropic Claude** — model behavior, tool use, and output
-quality may differ. Intended for evaluation, not production delivery.
-
-```bash
-mosaic claudex           # launch (prompts through the proxy readiness gate)
-mosaic yolo claudex      # …with --dangerously-skip-permissions
-mosaic claudex --print "hello"   # trailing args are forwarded to Claude Code
-```
-
-**Prerequisite:** the `claude-code-proxy` binary must be installed and
-authenticated (`claude-code-proxy codex auth …`). `mosaic claudex` runs a
-preflight that verifies the binary, the OAuth state (triggering a device re-auth
-if needed), and a trusted local listener before launching; it **fails closed**
-if the proxy cannot be brought up with a verified identity.
-
-**Isolation (never touches your real Claude state).** claudex always launches
-against an isolated `CLAUDE_CONFIG_DIR` (default `~/.config/mosaic/claudex/home`).
-The ambient `CLAUDE_CONFIG_DIR` is deliberately ignored, and a guard proves the
-resolved dir can never be — or live under — the real `~/.claude`. A claudex
-session therefore cannot mutate your normal Claude Code config.
-
-**No token leakage.** claudex never reads the proxy's credential file. Claude
-Code is handed only `ANTHROPIC_AUTH_TOKEN=unused` pointed at the loopback proxy;
-the entire credential-bearing env family (`ANTHROPIC_*`, `AWS_*`, `GOOGLE_CLOUD_*`,
-`GOOGLE_APPLICATION_CREDENTIALS`, `*_TOKEN`, `*_KEY`, `*_SECRET`, …) is stripped
-from the composed environment. The Bedrock/Vertex routing switches
-(`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, and the `_SKIP_*_AUTH`
-pair) are force-removed regardless of value — otherwise their mere presence
-would route Claude Code to the real Anthropic API via AWS/GCP and bypass the
-proxy. The proxy holds the real OAuth credential.
-
-**Model tiers (override via env).**
-
-| Tier                  | Env var                      | Default        |
-| --------------------- | ---------------------------- | -------------- |
-| primary (opus/sonnet) | `ANTHROPIC_MODEL`            | `gpt-5.6-sol`  |
-| small/fast (haiku)    | `ANTHROPIC_SMALL_FAST_MODEL` | `gpt-5.6-luna` |
-
-Operator-provided values win over the defaults. Additional overrides:
-`MOSAIC_CLAUDEX_CONFIG_DIR` (isolated config dir), `ANTHROPIC_BASE_URL` (proxy
-endpoint).
-
 ## Hooks management
 
 After running `mosaic wizard`, Claude hooks are installed in `~/.claude/hooks-config.json`.

packages/mosaic/framework/install.sh

@@ -109,225 +109,6 @@ restore_snapshot() {
 }
 cleanup_snapshot() { [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] && rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""; }
 
-# ─── durable operator-config snapshot (#791 PR2) ─────────────────────────────
-# A SECOND, independent safety layer, distinct from SNAPSHOT_DIR above:
-#   • SNAPSHOT_DIR is ephemeral (/tmp, deleted on success) and mirrors the WHOLE
-#     target for CRASH rollback if the sync aborts mid-write.
-#   • DURABLE_SNAPSHOT_DIR is RETAINED, holds only the operator-owned surface, and
-#     lives OUTSIDE the framework tree and any repo. It exists for the failure the
-#     crash-rollback cannot see: a sync that finishes "successfully" yet a
-#     manifest/logic bug let it modify an operator file. verify_operator_surface()
-#     (post-sync) heals from it; `mosaic restore` recovers from it days later.
-# Path convention is mirrored in packages/mosaic/src/commands/restore.ts — keep
-# the two in sync (there is no shared code across the bash/TS boundary).
-DURABLE_SNAPSHOT_DIR=""
-backup_root() { printf '%s/mosaic/backups' "${XDG_STATE_HOME:-$HOME/.local/state}"; }
-
-# Relative paths that a migration INTENTIONALLY removes from the target (e.g. the
-# legacy bin/ tree). Such a path is operator-classified by the manifest (unknown⇒
-# operator), so the durable snapshot captures it — but its post-migration absence
-# is correct, NOT a manifest bug. run_migrations() records each removal here so
-# verify_operator_surface() does not "heal" it back and silently undo the
-# migration (which would then be skipped forever once the version is stamped).
-MIGRATION_REMOVED_PATHS=()
-
-# True (0) if $1 (a path relative to TARGET_DIR) equals or lives under a path a
-# migration deliberately removed this run.
-is_migration_removed() {
-  local rel="$1" removed
-  for removed in ${MIGRATION_REMOVED_PATHS[@]+"${MIGRATION_REMOVED_PATHS[@]}"}; do
-    [[ -n "$removed" ]] || continue
-    [[ "$rel" == "$removed" || "$rel" == "$removed"/* ]] && return 0
-  done
-  return 1
-}
-
-# True (0) if any parent directory of $1 (relative to TARGET_DIR) is a symlink.
-# Restoring THROUGH a symlinked ancestor would let cp write snapshot contents —
-# possibly secrets — outside the target (CWE-59), so the verify net refuses it.
-has_symlinked_parent() {
-  local rel="$1" dir p seg
-  dir="$(dirname "$rel")"
-  [[ "$dir" == "." ]] && return 1
-  p="$TARGET_DIR"
-  local IFS='/'
-  for seg in $dir; do
-    [[ -n "$seg" ]] || continue
-    p="$p/$seg"
-    [[ -L "$p" ]] && return 0
-  done
-  return 1
-}
-
-# Emit (NUL-delimited, into file $1) the operator-owned relative paths that exist
-# under TARGET_DIR, classified via the shared manifest (deny-wins; unknown⇒
-# operator). Returns non-zero if the filesystem walk itself failed — we must
-# NEVER snapshot from a truncated scan (a `< <(find …)` process substitution
-# would hide that error; capture-then-check does not — cf. #791 blocker-D1).
-enumerate_operator_files() {
-  local out="$1" scan abs rel
-  scan="$(mktemp)"
-  if ! find "$TARGET_DIR" -type f -print0 > "$scan"; then
-    rm -f "$scan"
-    return 1  # OP-SCAN-GUARD
-  fi
-  : > "$out"
-  while IFS= read -r -d '' abs; do
-    rel="${abs#"$TARGET_DIR"/}"
-    # Not operator config: version marker and any VCS metadata.
-    case "$rel" in .framework-version|.git|.git/*) continue ;; esac
-    manifest_is_framework "$rel" || printf '%s\0' "$rel" >> "$out"
-  done < "$scan"
-  rm -f "$scan"
-}
-
-# Retain only the newest MOSAIC_BACKUP_RETENTION (default 5) snapshots. The
-# pre-update-<UTC-ts> names sort lexicographically = chronologically, so a
-# reverse sort is newest-first. Pruning failures are non-fatal (they only leave
-# extra old backups); the enclosing find's status is still honored, not swallowed.
-prune_durable_snapshots() {
-  local root keep list d i=0
-  root="$(backup_root)"
-  keep="${MOSAIC_BACKUP_RETENTION:-5}"
-  [[ "$keep" =~ ^[0-9]+$ ]] && (( keep >= 1 )) || keep=5
-  list="$(mktemp)"
-  if ! find "$root" -maxdepth 1 -type d -name 'pre-update-*' > "$list"; then
-    rm -f "$list"; return 0
-  fi
-  # Newest-first ordering needs `sort` (`-o` writes back in place — no `mv`
-  # dependency); if it is somehow unavailable, leave the backups untouched rather
-  # than risk pruning in an undefined order.
-  if ! LC_ALL=C sort -r -o "$list" "$list" 2>/dev/null; then
-    rm -f "$list"; return 0
-  fi
-  while IFS= read -r d; do
-    [[ -n "$d" ]] || continue
-    i=$((i + 1))
-    (( i > keep )) && rm -rf "$d"
-  done < "$list"
-  rm -f "$list"
-}
-
-# Take the durable pre-update snapshot BEFORE any mutation. Fail-OPEN: the durable
-# snapshot is a recovery bonus on top of the manifest (which already keeps the
-# sync out of operator paths) and the crash-rollback — so an un-writable backup
-# location warns and continues rather than blocking the upgrade. Everything it
-# creates is private (umask 077 + explicit 0700 dirs / 0600 files): the snapshot
-# mirrors operator config, which may hold secrets, and must never be world-readable.
-make_durable_snapshot() {
-  is_existing_install || return 0
-  local root ts dir list rel src dst count=0 old_umask
-  root="$(backup_root)"
-  # Fail-open if we cannot even stamp a timestamp: the durable snapshot is a
-  # recovery bonus and must never be the thing that aborts an upgrade.
-  ts="$(date -u +%Y%m%dT%H%M%SZ 2>/dev/null || true)"
-  if [[ -z "$ts" ]]; then
-    warn "Durable snapshot skipped: no UTC timestamp available (upgrade continues)."
-    return 0
-  fi
-  # umask 077 makes every dir/file the snapshot creates private from birth (it
-  # mirrors operator config, which may hold secrets). It is PROCESS-global, so we
-  # save and restore it around exactly this block — otherwise every later sync
-  # copy and new framework dir would inherit 0600/0700 instead of 0644/0755.
-  old_umask="$(umask)"
-  umask 077
-  if ! mkdir -p "$root"; then
-    umask "$old_umask"
-    warn "Durable snapshot skipped: cannot create backup dir $root (upgrade continues; operator files remain manifest-protected)."
-    return 0
-  fi
-  chmod 700 "$root" 2>/dev/null || true
-  dir="$root/pre-update-$ts"
-  if [[ -e "$dir" ]]; then           # same-second re-run: disambiguate
-    local n=1; while [[ -e "$dir-$n" ]]; do n=$((n + 1)); done; dir="$dir-$n"
-  fi
-  if ! mkdir -p "$dir"; then
-    umask "$old_umask"
-    warn "Durable snapshot skipped: cannot create $dir (upgrade continues)."
-    return 0
-  fi
-  chmod 700 "$dir"
-  list="$(mktemp)"
-  if ! enumerate_operator_files "$list"; then
-    umask "$old_umask"
-    warn "Durable snapshot skipped: could not enumerate operator files (upgrade continues)."
-    rm -f "$list"; rmdir "$dir" 2>/dev/null || true
-    return 0
-  fi
-  while IFS= read -r -d '' rel; do
-    src="$TARGET_DIR/$rel"; dst="$dir/$rel"
-    [[ -f "$src" ]] || continue
-    mkdir -p "$(dirname "$dst")"
-    if ! cp "$src" "$dst"; then
-      warn "Durable snapshot: could not copy operator file '$rel' (skipped)."
-      continue
-    fi
-    chmod 600 "$dst" 2>/dev/null || true
-    count=$((count + 1))
-  done < "$list"
-  rm -f "$list"
-  # Tighten every dir the copy created (mkdir -p honors umask, but be explicit).
-  find "$dir" -type d -exec chmod 700 {} + 2>/dev/null || true
-  umask "$old_umask"   # UMASK-RESTORE-NORMAL — restore before the upgrade proper resumes (see above)
-  DURABLE_SNAPSHOT_DIR="$dir"
-  ok "Durable pre-update snapshot: $count operator file(s) saved to $dir (recover with: mosaic restore --list)"
-  prune_durable_snapshots
-}
-
-# Post-sync safety net: a keep-mode upgrade must NEVER modify an operator file.
-# Compare every file in the durable snapshot to its current target counterpart;
-# any that changed (or vanished) was touched by a framework bug — restore it from
-# the snapshot and warn loudly. This does NOT abort: the framework itself synced
-# correctly; we only heal the operator collateral. Runs after the restore trap is
-# disarmed so its corrective copies can't spuriously trip a full rollback, and
-# every step is guarded so `set -e` cannot exit silently mid-heal (cf. blocker-D2).
-verify_operator_surface() {
-  [[ -n "$DURABLE_SNAPSHOT_DIR" && -d "$DURABLE_SNAPSHOT_DIR" ]] || return 0
-  local scan snap rel cur healed=0
-  scan="$(mktemp)"
-  if ! find "$DURABLE_SNAPSHOT_DIR" -type f -print0 > "$scan"; then
-    rm -f "$scan"
-    warn "Post-upgrade verify skipped: could not enumerate the pre-update snapshot at $DURABLE_SNAPSHOT_DIR."
-    return 0
-  fi
-  while IFS= read -r -d '' snap; do
-    rel="${snap#"$DURABLE_SNAPSHOT_DIR"/}"
-    cur="$TARGET_DIR/$rel"
-    # A migration may legitimately delete an operator-classified path (e.g. legacy
-    # bin/). Its absence is intended — do not heal it back, or the migration is
-    # silently undone and never re-runs once the version is stamped (#791 PR2).
-    is_migration_removed "$rel" && continue   # MIGRATION-SKIP-GUARD
-    if [[ ! -e "$cur" ]] || ! cmp -s "$snap" "$cur"; then
-      # Never restore THROUGH a symlink: an operator path swapped for a link would
-      # otherwise let cp write snapshot contents (possibly secrets) outside the
-      # target (CWE-59). Refuse a symlinked parent; drop a symlinked leaf and write
-      # a real file in its place.
-      if has_symlinked_parent "$rel"; then
-        warn "Operator path '$rel' has a symlinked parent under $TARGET_DIR; refusing to restore through it (possible tampering) — recover it manually from $DURABLE_SNAPSHOT_DIR."
-        continue
-      fi
-      [[ -L "$cur" ]] && rm -f "$cur"   # SYMLINK-LEAF-GUARD
-      # Guard mkdir too: under set -e (trap already disarmed) a bare failure would
-      # exit the whole installer before the recovery pointer below is emitted.
-      if ! mkdir -p "$(dirname "$cur")"; then
-        warn "Operator file '$rel' was modified by the upgrade but could NOT be auto-restored (parent dir unavailable) — recover it manually from $DURABLE_SNAPSHOT_DIR."
-        continue
-      fi
-      if cp "$snap" "$cur"; then
-        chmod 600 "$cur" 2>/dev/null || true
-        warn "Operator file was modified by the upgrade and has been restored from the pre-update snapshot: $rel"
-        healed=$((healed + 1))
-      else
-        warn "Operator file '$rel' was modified by the upgrade but could NOT be auto-restored — recover it manually from $DURABLE_SNAPSHOT_DIR."
-      fi
-    fi
-  done < "$scan"
-  rm -f "$scan"
-  if (( healed > 0 )); then
-    warn "$healed operator file(s) were unexpectedly changed by this upgrade and were restored from the pre-update snapshot. A keep-mode upgrade must never modify operator files — this indicates a framework manifest bug; please report it (#791)."
-  fi
-}
-
 # Reconcile contract files after sync: framework-owned overwrite (backup-once),
 # user-seeded seed-if-absent.
 reconcile_framework_files() {
@@ -545,10 +326,6 @@ run_migrations() {
   # Remove bin/ directory — all executables now live in the npm CLI.
   # Scripts that were in bin/ are now in tools/_scripts/.
   if [[ "$from_version" -lt 2 ]]; then
-    # bin/ and the rails symlink are operator-classified by the manifest (unknown⇒
-    # operator) and thus captured in the durable snapshot; record them as
-    # intentional removals so the post-sync verify net does not restore them.
-    MIGRATION_REMOVED_PATHS+=("bin" "rails")
     if [[ -d "$TARGET_DIR/bin" ]]; then
       ok "Removing legacy bin/ directory (executables now in npm CLI)"
       rm -rf "$TARGET_DIR/bin"
@@ -606,9 +383,6 @@ fi
 # not for a validation failure that has touched nothing yet (#791 blocker-1).
 if [[ "$INSTALL_MODE" == "keep" ]]; then
   manifest_load
-  # Durable, operator-scoped backup taken BEFORE any mutation (#791 PR2). Kept
-  # outside the framework tree; recovered later via `mosaic restore`. Fail-open.
-  make_durable_snapshot
 fi
 
 # Snapshot before any destructive file operation; restore on interrupt/failure.
@@ -647,10 +421,6 @@ run_migrations
 
 # File-system phase complete and consistent — clear the restore trap.
 trap - ERR INT TERM
-# Post-sync safety net: heal any operator file a manifest bug let the sync touch,
-# using the durable pre-update snapshot (#791 PR2). Runs with the trap disarmed so
-# a corrective copy can't spuriously trigger a full rollback.
-verify_operator_surface   # VERIFY-NET (#791 PR2)
 cleanup_snapshot
 
 # Testability / minimal-install hook: stop after the file-system phase, before any

packages/mosaic/framework/tools/glpi/computer-list.sh

@@ -37,7 +37,7 @@ response=$(curl -sk -w "\n%{http_code}" \
 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')
 
-if [[ "$http_code" != "200" && "$http_code" != "206" ]]; then
+if [[ "$http_code" != "200" ]]; then
   echo "Error: Failed to list computers (HTTP $http_code)" >&2
   exit 1
 fi

packages/mosaic/framework/tools/glpi/test-list-http-status.sh

@@ -1,84 +0,0 @@
-#!/usr/bin/env bash
-# Regression harness for #807: ranged GLPI list requests may return HTTP 206.
-#
-# Each shipped list wrapper must render a healthy 206 response and must retain
-# its non-zero error behavior for a genuine HTTP failure.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/glpi-list-http-status}"
-TOOL_DIR="$WORK_DIR/tools/glpi"
-BIN_DIR="$WORK_DIR/bin"
-
-rm -rf "$WORK_DIR"
-mkdir -p "$TOOL_DIR" "$BIN_DIR" "$WORK_DIR/tools/_lib"
-trap 'rm -rf "$WORK_DIR"' EXIT
-
-for wrapper in ticket-list.sh computer-list.sh user-list.sh; do
-  cp "$SCRIPT_DIR/$wrapper" "$TOOL_DIR/$wrapper"
-done
-
-cat > "$WORK_DIR/tools/_lib/credentials.sh" <<'SH'
-load_credentials() {
-  export GLPI_URL="https://glpi.test/apirest.php"
-  export GLPI_APP_TOKEN="test-app-token"
-}
-SH
-
-cat > "$TOOL_DIR/session-init.sh" <<'SH'
-#!/usr/bin/env bash
-printf '%s\n' 'test-session-token'
-SH
-chmod +x "$TOOL_DIR/session-init.sh"
-
-cat > "$BIN_DIR/curl" <<'SH'
-#!/usr/bin/env bash
-set -euo pipefail
-printf '%s\n' '[{"id":42,"priority":3,"status":1,"name":"Regression fixture","date_mod":"2026-07-16 10:00:00","serial":"SER-42","states_id":1,"realname":"Fixture","firstname":"GLPI","is_active":1}]'
-printf '%s\n' "${GLPI_TEST_HTTP_CODE:?GLPI_TEST_HTTP_CODE is required}"
-SH
-chmod +x "$BIN_DIR/curl"
-
-export MOSAIC_HOME="$WORK_DIR"
-export PATH="$BIN_DIR:$PATH"
-
-wrappers=(ticket-list.sh computer-list.sh user-list.sh)
-resources=(tickets computers users)
-headings=(PRIORITY SERIAL USERNAME)
-fail=0
-
-for index in "${!wrappers[@]}"; do
-  wrapper="${wrappers[$index]}"
-  resource="${resources[$index]}"
-  heading="${headings[$index]}"
-  path="$TOOL_DIR/$wrapper"
-
-  if ! output=$(GLPI_TEST_HTTP_CODE=206 bash "$path" 2>&1); then
-    echo "FAIL: $wrapper rejected healthy HTTP 206" >&2
-    fail=1
-  elif [[ "$output" != *"$heading"* || "$output" != *"Regression fixture"* ]]; then
-    echo "FAIL: $wrapper did not render the HTTP 206 list response" >&2
-    fail=1
-  else
-    echo "PASS: $wrapper renders HTTP 206"
-  fi
-
-  rc=0
-  output=$(GLPI_TEST_HTTP_CODE=401 bash "$path" 2>&1) || rc=$?
-  if [[ "$rc" -eq 0 ]]; then
-    echo "FAIL: $wrapper accepted HTTP 401" >&2
-    fail=1
-  elif [[ "$output" != *"Error: Failed to list $resource (HTTP 401)"* ]]; then
-    echo "FAIL: $wrapper changed the HTTP failure diagnostic" >&2
-    fail=1
-  else
-    echo "PASS: $wrapper rejects HTTP 401"
-  fi
-done
-
-if [[ "$fail" -eq 0 ]]; then
-  echo "ALL PASS: test-list-http-status.sh"
-fi
-
-exit "$fail"

packages/mosaic/framework/tools/glpi/ticket-list.sh

@@ -55,7 +55,7 @@ response=$(curl -sk -w "\n%{http_code}" \
 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')
 
-if [[ "$http_code" != "200" && "$http_code" != "206" ]]; then
+if [[ "$http_code" != "200" ]]; then
   echo "Error: Failed to list tickets (HTTP $http_code)" >&2
   exit 1
 fi

packages/mosaic/framework/tools/glpi/user-list.sh

@@ -37,7 +37,7 @@ response=$(curl -sk -w "\n%{http_code}" \
 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')
 
-if [[ "$http_code" != "200" && "$http_code" != "206" ]]; then
+if [[ "$http_code" != "200" ]]; then
   echo "Error: Failed to list users (HTTP $http_code)" >&2
   exit 1
 fi

packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh

@@ -1,313 +0,0 @@
-#!/usr/bin/env bash
-# test-upgrade-durable-snapshot.sh — the #791 PR2 regression gate.
-#
-# PR1 gave keep-mode upgrades two protections: the manifest (a keep-sync only
-# ever writes framework-owned paths — operator config is structurally untouched)
-# and an EPHEMERAL /tmp snapshot that rolls the whole target back if the sync
-# CRASHES mid-write. PR2 adds a third, independent layer for the case neither
-# covers: a "successful" upgrade that a manifest/logic bug silently let touch an
-# operator file. That layer is a DURABLE, operator-scoped pre-update snapshot:
-#
-#   Part 1 (scope):      before any mutation, the installer copies exactly the
-#                        operator-owned files that exist into a retained backup
-#                        under $XDG_STATE_HOME/mosaic/backups/pre-update-<ts>/ —
-#                        framework files are NOT captured.
-#   Part 2 (perms):      the backup root, snapshot dir and every nested dir are
-#                        0700; every backed-up file is 0600 (never world-readable,
-#                        even though operator config may hold secrets).
-#   Part 3 (no leak):    a secret seeded into credentials.json is copied into the
-#                        snapshot (proving coverage) but its value never appears
-#                        on stdout/stderr — the snapshot reports counts/paths only.
-#   Part 4 (retention):  only the newest MOSAIC_BACKUP_RETENTION snapshots survive;
-#                        older ones are pruned.
-#   Part 5 (verify net): if the upgrade DID modify an operator file (injected here
-#                        with a cp shim that scribbles on SOUL.md while a framework
-#                        file is copied), the post-sync verify restores that file
-#                        from the durable snapshot and warns loudly. The control —
-#                        the same installer with the verify call stripped — leaves
-#                        the corruption in place, proving the net is load-bearing.
-#
-# Usage:  bash test-upgrade-durable-snapshot.sh
-set -uo pipefail
-
-FW="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"   # packages/mosaic/framework
-INSTALL="$FW/install.sh"
-ORIG_PATH="$PATH"
-FRAMEWORK_VERSION="$(grep -m1 '^FRAMEWORK_VERSION=' "$INSTALL" | cut -d= -f2)"
-
-# Control installers must live INSIDE $FW: install.sh derives SOURCE_DIR from its
-# own path and sources tools/_lib/manifest.sh relative to it, so a copy anywhere
-# else aborts before the sync. Each control is a shipped installer with one guard
-# line stripped (keyed off a `# <MARKER>` anchor), proving that guard load-bearing.
-# All controls share the .install-*.tmp.sh glob so one trap sweeps them on exit.
-VERIFYCTRL="$FW/.install-verifynet-control.tmp.sh"
-rm -f "$FW"/.install-*.tmp.sh
-trap 'rm -f "$FW"/.install-*.tmp.sh' EXIT
-
-# mk_control <marker-regex> <name> — echo a control installer path ($FW-local) that
-# is $INSTALL with every line matching /<marker-regex>/ deleted.
-mk_control() {
-  local path="$FW/.install-$2.tmp.sh"
-  sed "/$1/d" "$INSTALL" > "$path"
-  printf '%s' "$path"
-}
-
-pass=0; fail=0
-chk() { if eval "$2"; then echo "  ✓ $1"; pass=$((pass + 1)); else echo "  ✗ $1"; fail=$((fail + 1)); fi; }
-
-SECRET='SUPER-SECRET-TOKEN-do-not-log-pr2'
-SOUL_ORIG='# persona'
-# A framework file the sync copies (source ships it; the seeded target omits it,
-# so the bytes differ and cp is attempted). The Part-5 shim keys off this path.
-POISON_REL='guides/E2E-DELIVERY.md'
-
-# Seed a recognized keep-mode install holding four operator-owned files across
-# the identity file, an operator subtree, memory, and the credentials carve-out.
-seed_home() {
-  local H="$1"
-  mkdir -p "$H/agents" "$H/tools/_lib" "$H/memory"
-  printf '%s\n' "$SOUL_ORIG" > "$H/SOUL.md"    # recognized install → keep mode
-  printf 'MODEL=opus\n'      > "$H/agents/coder0.conf"
-  printf '# operator memory\n' > "$H/memory/note.md"
-  printf 'TOKEN=%s\n' "$SECRET" > "$H/tools/_lib/credentials.json"
-  echo 3 > "$H/.framework-version"
-  # Deliberately NO guides/E2E-DELIVERY.md so the sync copies it (framework file,
-  # bytes differ) — that copy is where the Part-5 corruption shim fires.
-}
-
-# A pre-v2 (legacy) keep-mode install: SOUL.md marks it recognized, and a bin/
-# tree with NO .framework-version makes installed_framework_version() report 1, so
-# the v1→v2 migration (which deletes bin/) runs. bin/ is unknown⇒operator, so the
-# durable snapshot captures it — the verify net must NOT heal the intended removal.
-seed_home_v1() {
-  local H="$1"
-  mkdir -p "$H/agents" "$H/tools/_lib" "$H/memory" "$H/bin"
-  printf '%s\n' "$SOUL_ORIG" > "$H/SOUL.md"
-  printf 'TOKEN=%s\n' "$SECRET" > "$H/tools/_lib/credentials.json"
-  printf '#!/bin/sh\necho legacy\n' > "$H/bin/tool.sh"; chmod +x "$H/bin/tool.sh"
-  # Deliberately NO .framework-version and NO guides/E2E-DELIVERY.md (see seed_home).
-}
-
-# A cp shim that, while the framework POISON file is being copied during sync,
-# swaps the operator credentials file for a symlink pointing at an attacker-
-# readable file OUTSIDE the target — simulating post-snapshot tampering (CWE-59).
-# The durable snapshot already holds the real credentials (it is taken before any
-# sync), so the verify net must restore a REAL file in place WITHOUT following the
-# link (which would write the snapshot's secret out through it). $EXFIL_TARGET is
-# expanded at shim-write time from the caller's environment.
-#
-# PORTABILITY (why this shim, not the real `cp`): the CWE-59 leak this exercises is
-# `cp` writing THROUGH a symlinked destination. GNU/BSD cp — what a real operator
-# runs `mosaic update` under — follows the dest symlink and leaks. busybox cp (the
-# Alpine CI image) REPLACES a symlinked dest instead of following it, so under the
-# CI harness the leak vector simply does not exist and the negative control could
-# never reproduce it. This shim therefore emulates the real-target GNU cp behavior
-# PORTABLY: when the destination is a symlink it writes the source bytes through the
-# link via redirection (which follows symlinks on every coreutils, busybox included);
-# otherwise it delegates to the host's real cp unchanged. Both the shipped-case and
-# the negative control run through this identical shim, so the ONLY difference
-# between them remains the SYMLINK-LEAF-GUARD — the control stays load-bearing and
-# non-tautological. It does NOT touch install.sh (approved) or the real assertions:
-# with the guard present the symlinked leaf is dropped BEFORE this cp runs, so the
-# dest is a real file and the delegate path is taken exactly as on a GNU host.
-make_symlink_leaf_shim() {
-  local dir="$1" home="$2"
-  cat > "$dir/cp" <<SHIM
-#!/usr/bin/env bash
-dest="\${@: -1}"
-src="\${@:(-2):1}"
-case "\$dest" in
-  */$POISON_REL)
-    rm -f "$home/tools/_lib/credentials.json"
-    ln -s "$EXFIL_TARGET" "$home/tools/_lib/credentials.json"
-    ;;
-esac
-# Coreutils-agnostic emulation of GNU cp's follow-through-dest-symlink behavior.
-if [[ -L "\$dest" && -f "\$src" ]]; then
-  cat "\$src" > "\$dest"
-  exit \$?
-fi
-exec env PATH="$ORIG_PATH" cp "\$@"
-SHIM
-  chmod +x "$dir/cp"
-}
-
-# A cp shim that, while the framework POISON file is being copied during sync,
-# also appends garbage to the operator SOUL.md — simulating a manifest bug that
-# writes outside the framework lane. The framework copy itself still succeeds
-# (real cp runs), so the sync completes 0 and the post-sync verify is what must
-# catch and undo the operator-file damage. The snapshot's own cp only ever
-# targets operator files (never guides/…), so it is never corrupted by this shim.
-make_corrupt_shim() {
-  local dir="$1" home="$2"
-  cat > "$dir/cp" <<SHIM
-#!/usr/bin/env bash
-dest="\${@: -1}"
-case "\$dest" in
-  */$POISON_REL) printf 'CORRUPTION-mid-sync\n' >> "$home/SOUL.md" 2>/dev/null || true ;;
-esac
-exec env PATH="$ORIG_PATH" cp "\$@"
-SHIM
-  chmod +x "$dir/cp"
-}
-
-# Run one keep-mode, sync-only upgrade with $XDG_STATE_HOME redirected to a
-# throwaway dir (so the real ~/.local/state is never touched). Optional args:
-#   $2 shim-maker (default none), $3 MOSAIC_BACKUP_RETENTION (default unset).
-# Echoes: "<exit>\t<out>\t<state-dir>\t<home>".
-#   $4 seeder (default seed_home) — swap in seed_home_v1 for the migration case.
-run_snap() {
-  local installer="$1" shim_maker="${2:-}" retention="${3:-}" seeder="${4:-seed_home}" H STATE OUT SHIM rc pathpre
-  H=$(mktemp -d); STATE=$(mktemp -d); OUT=$(mktemp); pathpre="$ORIG_PATH"
-  "$seeder" "$H"
-  if [[ -n "$shim_maker" ]]; then
-    SHIM=$(mktemp -d); "$shim_maker" "$SHIM" "$H"; pathpre="$SHIM:$ORIG_PATH"
-  fi
-  set +e
-  env PATH="$pathpre" XDG_STATE_HOME="$STATE" \
-      ${retention:+MOSAIC_BACKUP_RETENTION="$retention"} \
-      MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 \
-      bash "$installer" >"$OUT" 2>&1
-  rc=$?
-  set -e 2>/dev/null || true
-  [[ -n "$shim_maker" ]] && rm -rf "$SHIM"
-  printf '%s\t%s\t%s\t%s\n' "$rc" "$OUT" "$STATE" "$H"
-}
-
-# Resolve the single pre-update-* snapshot dir under a state dir (newest if many).
-snap_dir() {
-  find "$1/mosaic/backups" -maxdepth 1 -type d -name 'pre-update-*' 2>/dev/null \
-    | LC_ALL=C sort -r | head -1
-}
-
-echo "── Part 1/2/3: durable snapshot scope, perms, no-leak ──────────────────"
-IFS=$'\t' read -r rc OUT STATE H < <(run_snap "$INSTALL")
-SNAP="$(snap_dir "$STATE")"
-
-chk "upgrade succeeds"                        "[ '$rc' -eq 0 ]"
-chk "exactly one pre-update snapshot created" "[ \$(find '$STATE/mosaic/backups' -maxdepth 1 -type d -name 'pre-update-*' | wc -l) -eq 1 ]"
-chk "snapshot: SOUL.md captured"              "[ -f '$SNAP/SOUL.md' ]"
-chk "snapshot: operator subtree captured"     "[ -f '$SNAP/agents/coder0.conf' ]"
-chk "snapshot: memory captured"               "[ -f '$SNAP/memory/note.md' ]"
-chk "snapshot: credentials carve-out captured" "[ -f '$SNAP/tools/_lib/credentials.json' ]"
-chk "snapshot: SOUL.md bytes preserved"       "[ \"\$(cat '$SNAP/SOUL.md')\" = '$SOUL_ORIG' ]"
-chk "snapshot: framework file NOT captured"   "[ ! -e '$SNAP/CONSTITUTION.md' ] && [ ! -e '$SNAP/$POISON_REL' ]"
-
-# Part 2 — permissions (0700 dirs, 0600 files); never world-readable.
-chk "perms: backup root is 0700"              "[ \$(stat -c '%a' '$STATE/mosaic/backups') -eq 700 ]"
-chk "perms: snapshot dir is 0700"             "[ \$(stat -c '%a' '$SNAP') -eq 700 ]"
-chk "perms: nested dir is 0700"               "[ \$(stat -c '%a' '$SNAP/agents') -eq 700 ]"
-chk "perms: credentials backup is 0600"       "[ \$(stat -c '%a' '$SNAP/tools/_lib/credentials.json') -eq 600 ]"
-chk "perms: SOUL.md backup is 0600"           "[ \$(stat -c '%a' '$SNAP/SOUL.md') -eq 600 ]"
-
-# Part 3 — the secret is backed up but never emitted to stdout/stderr.
-chk "no-leak: secret IS in the backup file"   "grep -q '$SECRET' '$SNAP/tools/_lib/credentials.json'"
-chk "no-leak: secret NOT on stdout/stderr"    "! grep -q '$SECRET' '$OUT'"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-echo "── Part 4: retention prune (MOSAIC_BACKUP_RETENTION) ───────────────────"
-# Pre-seed four dated snapshots, then take one real snapshot with retention=2:
-# only the two newest (the fresh real one + the newest pre-seeded) must survive.
-IFS=$'\t' read -r rc OUT STATE H < <(
-  H=$(mktemp -d); STATE=$(mktemp -d); OUT=$(mktemp)
-  seed_home "$H"
-  mkdir -p "$STATE/mosaic/backups"
-  for ts in 20200101T000000Z 20210101T000000Z 20220101T000000Z 20230101T000000Z; do
-    mkdir -p "$STATE/mosaic/backups/pre-update-$ts"
-  done
-  set +e
-  env PATH="$ORIG_PATH" XDG_STATE_HOME="$STATE" MOSAIC_BACKUP_RETENTION=2 \
-      MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 \
-      bash "$INSTALL" >"$OUT" 2>&1
-  rc=$?
-  set -e 2>/dev/null || true
-  printf '%s\t%s\t%s\t%s\n' "$rc" "$OUT" "$STATE" "$H"
-)
-chk "retention: upgrade succeeds"             "[ '$rc' -eq 0 ]"
-chk "retention: pruned to exactly 2 snapshots" "[ \$(find '$STATE/mosaic/backups' -maxdepth 1 -type d -name 'pre-update-*' | wc -l) -eq 2 ]"
-chk "retention: newest pre-seeded survives"   "[ -d '$STATE/mosaic/backups/pre-update-20230101T000000Z' ]"
-chk "retention: oldest pre-seeded pruned"     "[ ! -d '$STATE/mosaic/backups/pre-update-20200101T000000Z' ]"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-echo "── Part 5: post-sync verify restores an operator file (+ control) ──────"
-# Shipped installer: the cp shim corrupts SOUL.md mid-sync; verify must restore it.
-IFS=$'\t' read -r rc OUT STATE H < <(run_snap "$INSTALL" make_corrupt_shim)
-chk "verify: upgrade still succeeds"          "[ '$rc' -eq 0 ]"
-chk "verify: SOUL.md restored to original"    "[ \"\$(cat '$H/SOUL.md')\" = '$SOUL_ORIG' ]"
-chk "verify: no corruption remains in SOUL.md" "! grep -q 'CORRUPTION-mid-sync' '$H/SOUL.md'"
-chk "verify: loud restore warning emitted"    "grep -qi 'restored from the pre-update snapshot' '$OUT'"
-chk "verify: secret still not leaked"         "! grep -q '$SECRET' '$OUT'"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-# Control: strip the verify call → the corruption must SURVIVE (net is load-bearing).
-sed '/# VERIFY-NET/d' "$INSTALL" > "$VERIFYCTRL"
-IFS=$'\t' read -r rc OUT STATE H < <(run_snap "$VERIFYCTRL" make_corrupt_shim)
-chk "control: SOUL.md corruption survives"    "grep -q 'CORRUPTION-mid-sync' '$H/SOUL.md'"
-chk "control: no restore warning emitted"     "! grep -qi 'restored from the pre-update snapshot' '$OUT'"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-echo "── Part 6: verify net honors an intentional migration removal (+ control) ─"
-# BLOCKER regression: on a pre-v2 install, bin/ is operator-classified so the durable
-# snapshot captures it — but the v1→v2 migration deletes bin/ ON PURPOSE. The verify
-# net must SKIP that removal (is_migration_removed), or it heals bin/ back and the
-# migration is silently undone forever once the version is stamped.
-IFS=$'\t' read -r rc OUT STATE H < <(run_snap "$INSTALL" "" "" seed_home_v1)
-chk "migration: upgrade succeeds"                 "[ '$rc' -eq 0 ]"
-chk "migration: legacy bin/ stays removed"        "[ ! -e '$H/bin' ]"
-chk "migration: operator SOUL.md untouched"       "[ \"\$(cat '$H/SOUL.md')\" = '$SOUL_ORIG' ]"
-chk "migration: version stamped to $FRAMEWORK_VERSION" "[ \"\$(cat '$H/.framework-version')\" = '$FRAMEWORK_VERSION' ]"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-# Control: strip the MIGRATION-SKIP-GUARD → the verify net restores bin/ from the
-# snapshot, silently undoing the migration (proves the guard is load-bearing).
-MIGCTRL="$(mk_control 'MIGRATION-SKIP-GUARD' migration-control)"
-IFS=$'\t' read -r rc OUT STATE H < <(run_snap "$MIGCTRL" "" "" seed_home_v1)
-chk "control: bin/ wrongly restored by verify"    "[ -e '$H/bin/tool.sh' ]"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-echo "── Part 7: verify net never restores a secret through a symlink (+ control) ─"
-# HIGH (CWE-59) regression: an attacker who swaps an operator file for a symlink
-# AFTER the durable snapshot must not cause the verify net's restore to write the
-# snapshot's secret out THROUGH that link. The shipped net drops a symlinked leaf and
-# writes a real file in its place, leaving the external target untouched.
-EXFIL_DIR=$(mktemp -d); EXFIL_TARGET="$EXFIL_DIR/stolen"
-printf 'ATTACKER-PLACEHOLDER\n' > "$EXFIL_TARGET"
-IFS=$'\t' read -r rc OUT STATE H < <(run_snap "$INSTALL" make_symlink_leaf_shim)
-chk "symlink-leaf: upgrade succeeds"              "[ '$rc' -eq 0 ]"
-chk "symlink-leaf: secret NOT written through link" "! grep -q '$SECRET' '$EXFIL_TARGET'"
-chk "symlink-leaf: credentials.json is a real file" "[ -f '$H/tools/_lib/credentials.json' ] && [ ! -L '$H/tools/_lib/credentials.json' ]"
-chk "symlink-leaf: credentials.json restored intact" "grep -q '$SECRET' '$H/tools/_lib/credentials.json'"
-chk "symlink-leaf: secret not leaked to stdout/stderr" "! grep -q '$SECRET' '$OUT'"
-rm -rf "$STATE" "$H" "$EXFIL_DIR"; rm -f "$OUT"
-
-# Control: strip the SYMLINK-LEAF-GUARD → cp follows the swapped-in link and writes
-# the snapshot secret out through it (proves the guard is load-bearing).
-EXFIL_DIR=$(mktemp -d); EXFIL_TARGET="$EXFIL_DIR/stolen"
-printf 'ATTACKER-PLACEHOLDER\n' > "$EXFIL_TARGET"
-LEAFCTRL="$(mk_control 'SYMLINK-LEAF-GUARD' symlinkleaf-control)"
-IFS=$'\t' read -r rc OUT STATE H < <(run_snap "$LEAFCTRL" make_symlink_leaf_shim)
-chk "control: secret leaked through the symlink"  "grep -q '$SECRET' '$EXFIL_TARGET'"
-rm -rf "$STATE" "$H" "$EXFIL_DIR"; rm -f "$OUT"
-
-echo "── Part 8: snapshot umask 077 does not leak into synced files (+ control) ──"
-# SHOULD-FIX regression: umask 077 is process-global. Scoped to the snapshot it keeps
-# backups 0600; leaked past it, every later cp/mkdir inherits 0600/0700. A freshly-
-# synced framework file must be 0644 (per the ambient 022 umask) while the backup of
-# a secret stays 0600.
-IFS=$'\t' read -r rc OUT STATE H < <(umask 022; run_snap "$INSTALL")
-SNAP="$(snap_dir "$STATE")"
-chk "umask: upgrade succeeds"                     "[ '$rc' -eq 0 ]"
-chk "umask: synced framework file is 0644"        "[ \$(stat -c '%a' '$H/$POISON_REL') -eq 644 ]"
-chk "umask: backup of a secret stays 0600"        "[ \$(stat -c '%a' '$SNAP/tools/_lib/credentials.json') -eq 600 ]"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-# Control: strip the UMASK-RESTORE-NORMAL line → umask 077 leaks past the snapshot,
-# so the newly-synced framework file is created 0600 (proves the restore matters).
-UMASKCTRL="$(mk_control 'UMASK-RESTORE-NORMAL' umask-control)"
-IFS=$'\t' read -r rc OUT STATE H < <(umask 022; run_snap "$UMASKCTRL")
-chk "control: leaked umask makes synced file 0600" "[ \$(stat -c '%a' '$H/$POISON_REL') -eq 600 ]"
-rm -rf "$STATE" "$H"; rm -f "$OUT"
-
-echo ""
-echo "RESULT: $pass passed, $fail failed"
-[ "$fail" -eq 0 ]

packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh

@@ -29,13 +29,6 @@ INSTALL="$FW/install.sh"
 pass=0; fail=0
 chk() { if eval "$2"; then echo "  ✓ $1"; pass=$((pass + 1)); else echo "  ✗ $1"; fail=$((fail + 1)); fi; }
 
-# Redirect the #791 PR2 durable pre-update snapshot ($XDG_STATE_HOME/mosaic/backups)
-# into a throwaway so a keep-mode upgrade under test never writes into the real
-# ~/.local/state. This test asserts operator-surface fidelity, not backup content.
-export XDG_STATE_HOME
-XDG_STATE_HOME="$(mktemp -d)"
-trap 'rm -rf "$XDG_STATE_HOME"' EXIT
-
 SECRET='SUPER-SECRET-TOKEN-do-not-log-3f9a'
 
 # Seed a throwaway MOSAIC_HOME with an operator sentinel per ownership class.
@@ -213,7 +206,7 @@ fi
 #    does not silently depend on rsync being installed. (Provide the coreutils the
 #    installer needs on the stripped PATH.)
 FBIN=$(mktemp -d)
-for t in bash cp find mktemp rm mkdir chmod cmp sed grep cat dirname basename stat sha256sum awk tr date sort; do
+for t in bash cp find mktemp rm mkdir chmod cmp sed grep cat dirname basename stat sha256sum awk tr; do
   p=$(command -v "$t" 2>/dev/null) && ln -s "$p" "$FBIN/$t"
 done
 run_matrix "rsync-absent" env "PATH=$FBIN"

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -122,11 +122,12 @@ fi
 
 # Source label: this agent's host:session (auto-detected, overridable).
 if [ -z "$SRC_LABEL" ]; then
-  src_host=$(hostname -s 2>/dev/null || echo "?")
-  src_sess=${MOSAIC_AGENT_NAME:-}
-  if [ -z "$src_sess" ]; then
-    src_sess=$(tmux display-message -p '#S' 2>/dev/null || echo "?")
+  tmux_cmd=(tmux)
+  if [ -n "$SOCKET_NAME" ]; then
+    tmux_cmd+=(-L "$SOCKET_NAME")
   fi
+  src_host=$(hostname -s 2>/dev/null || echo "?")
+  src_sess=$("${tmux_cmd[@]}" display-message -p '#S' 2>/dev/null || echo "?")
   SRC_LABEL="${src_host}:${src_sess}"
 fi
 

packages/mosaic/framework/tools/tmux/agent-send.test.sh

@@ -14,9 +14,6 @@
 #   5. invalid class => exit 3, nothing sent.
 #   6. --class with no value => exit 3.
 #   7. the documented consumer regex parses producer output for every class.
-#   8. MOSAIC_AGENT_NAME is authoritative for sender identity.
-#   9. sender fallback queries local tmux, never the destination -L socket.
-#  10. an undeterminable sender is stamped as "?".
 set -uo pipefail
 
 HERE=$(cd -- "$(dirname -- "$0")" && pwd)
@@ -24,45 +21,22 @@ TOOL="$HERE/agent-send.sh"
 
 # Capture stub: stands in for send-message.sh. Decodes -b and prints the payload.
 STUB=$(mktemp)
-FAKE_BIN=$(mktemp -d)
-trap 'rm -f "$STUB"; rm -rf "$FAKE_BIN"' EXIT
+trap 'rm -f "$STUB"' EXIT
 cat >"$STUB" <<'STUB_EOF'
 #!/usr/bin/env bash
 set -uo pipefail
 b64=""
-while getopts "L:t:b:r:v" o; do case "$o" in b) b64=$OPTARG ;; *) : ;; esac; done
+while getopts "t:b:r:v" o; do case "$o" in b) b64=$OPTARG ;; *) : ;; esac; done
 printf '%s' "$b64" | base64 -d
 STUB_EOF
 chmod +x "$STUB"
 
-# Fake tmux distinguishes the sender's default socket from a destination socket.
-cat >"$FAKE_BIN/tmux" <<'TMUX_EOF'
-#!/usr/bin/env bash
-set -uo pipefail
-case "${FAKE_TMUX_MODE:-sessions}" in
-  unavailable) exit 1 ;;
-  sessions)
-    if [ "${1:-}" = "-L" ]; then
-      printf '%s\n' 'destination-holder'
-    else
-      printf '%s\n' 'local-agent'
-    fi
-    ;;
-esac
-TMUX_EOF
-chmod +x "$FAKE_BIN/tmux"
-
 PASS=0; FAIL=0
 ok()   { PASS=$((PASS+1)); printf 'ok   %s\n' "$1"; }
 no()   { FAIL=$((FAIL+1)); printf 'FAIL %s\n   %s\n' "$1" "$2"; }
 
 # Run the tool with the stub injected; echoes captured payload on stdout.
 run() { AGENT_SEND_SENDER="$STUB" bash "$TOOL" -S a:src -n dsthost "$@"; }
-run_auto() {
-  env -u MOSAIC_AGENT_NAME \
-    AGENT_SEND_SENDER="$STUB" PATH="$FAKE_BIN:$PATH" \
-    bash "$TOOL" -n dsthost "$@"
-}
 
 # Documented consumer grammar — the daemon will mirror exactly this.
 GRAMMAR='^\[(\S+) -> (\S+) class=(terminal-log|actionable|human|reaction)\] (.*)$'
@@ -118,30 +92,6 @@ classic=$(run -s mos -m "plain body")
 [[ "$classic" =~ $GRAMMAR_NOCLASS ]] && [ "${BASH_REMATCH[3]}" = "plain body" ] \
   && ok "grammar (no-class) parses classic line" || no "grammar (no-class) parses classic line" "line=[$classic]"
 
-# 8. Exported pane identity wins even when dispatch targets another tmux socket.
-src_host=$(hostname -s)
-got=$(MOSAIC_AGENT_NAME=authoritative-agent FAKE_TMUX_MODE=sessions \
-  AGENT_SEND_SENDER="$STUB" PATH="$FAKE_BIN:$PATH" \
-  bash "$TOOL" -L destination-socket -n dsthost -s mos -m "env identity")
-want="[$src_host:authoritative-agent -> dsthost:mos] env identity"
-[ "$got" = "$want" ] && ok "MOSAIC_AGENT_NAME is authoritative across sockets" \
-  || no "MOSAIC_AGENT_NAME is authoritative across sockets" "got=[$got] want=[$want]"
-
-# 9. Without the env identity, self-lookup uses local tmux, not destination -L.
-got=$(FAKE_TMUX_MODE=sessions run_auto -L destination-socket -s mos -m "local fallback")
-want="[$src_host:local-agent -> dsthost:mos] local fallback"
-[ "$got" = "$want" ] && ok "cross-socket fallback uses local sender session" \
-  || no "cross-socket fallback uses local sender session" "got=[$got] want=[$want]"
-[[ "$got" != *":destination-holder ->"* ]] \
-  && ok "cross-socket fallback rejects destination holder identity" \
-  || no "cross-socket fallback rejects destination holder identity" "got=[$got]"
-
-# 10. If neither env nor local tmux identifies the sender, preserve '?'.
-got=$(FAKE_TMUX_MODE=unavailable run_auto -L destination-socket -s mos -m "unknown fallback")
-want="[$src_host:? -> dsthost:mos] unknown fallback"
-[ "$got" = "$want" ] && ok "unknown sender falls back to ?" \
-  || no "unknown sender falls back to ?" "got=[$got] want=[$want]"
-
 echo "---"
 echo "PASS=$PASS FAIL=$FAIL"
 [ "$FAIL" -eq 0 ]

packages/mosaic/src/cli.ts

@@ -17,7 +17,6 @@ import { registerConfigCommand } from './commands/config.js';
 import { registerFleetCommand } from './commands/fleet.js';
 import { registerMissionCommand } from './commands/mission.js';
 import { registerUninstallCommand } from './commands/uninstall.js';
-import { registerRestoreCommand } from './commands/restore.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerAuthCommand } from './commands/auth.js';
@@ -407,10 +406,6 @@ registerStorageCommand(program);
 
 registerUninstallCommand(program);
 
-// ─── restore ─────────────────────────────────────────────────────────────────
-
-registerRestoreCommand(program);
-
 // ─── telemetry ───────────────────────────────────────────────────────────────
 
 registerTelemetryCommand(program);

packages/mosaic/src/commands/claudex-proxy.spec.ts

@@ -1,862 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import {
-  CLAUDEX_PROXY_HOST,
-  CLAUDEX_PROXY_PORT,
-  CLAUDEX_PROXY_URL,
-  CLAUDEX_PROXY_BINARY,
-  CLAUDEX_HEALTH_PATH,
-  CLAUDEX_HEALTH_URL,
-  buildAuthStatusArgs,
-  buildDeviceAuthArgs,
-  buildServeArgs,
-  parseAuthStatus,
-  checkProxyBinary,
-  checkAuthStatus,
-  runDeviceReauth,
-  probeLiveness,
-  buildSystemdUnitContent,
-  systemdUnitPath,
-  installSystemdUnit,
-  startNohupProxy,
-  verifyListenerIdentity,
-  runProxyPreflight,
-  ensureProxyRunning,
-  type AuthStatus,
-  type ProxyRunResult,
-  type SpawnedChild,
-  type ListenerIdentity,
-} from './claudex-proxy.js';
-
-/**
- * P1 — Proxy preflight + lifecycle helpers for `mosaic yolo claudex`.
- *
- * Security-relevant invariants exercised here:
- *  - Liveness probe hits the proxy's dedicated `GET /healthz` and treats only a
- *    2xx as "alive" — a *proxy-specific* health contract, not arbitrary HTTP on
- *    the port (CWE-345: a local port-squatter must not be trusted as the proxy).
- *    This also honors spec gotcha #1 (never `curl -f` the root, which returns
- *    non-2xx): `/healthz` returns 2xx when the proxy is up, so a healthy proxy is
- *    never mistaken for dead and no duplicate proxy is spawned.
- *  - Auth-status parsing NEVER surfaces OAuth token material — only a coarse
- *    state + optional expiry — even if a token-shaped string appears in output.
- *  - The systemd unit's ExecStart never interpolates an unvalidated path
- *    (CWE-74: a CR/LF in the path could inject arbitrary systemd directives).
- *  - The nohup fallback captures spawn's *async* error event instead of crashing.
- */
-
-describe('claudex-proxy constants', () => {
-  it('pins the proxy endpoint to loopback :18765 (spec table)', () => {
-    expect(CLAUDEX_PROXY_HOST).toBe('127.0.0.1');
-    expect(CLAUDEX_PROXY_PORT).toBe(18765);
-    expect(CLAUDEX_PROXY_URL).toBe('http://127.0.0.1:18765');
-    expect(CLAUDEX_PROXY_BINARY).toBe('claude-code-proxy');
-  });
-
-  it('exposes the dedicated /healthz liveness endpoint (not the root path)', () => {
-    expect(CLAUDEX_HEALTH_PATH).toBe('/healthz');
-    expect(CLAUDEX_HEALTH_URL).toBe('http://127.0.0.1:18765/healthz');
-  });
-
-  it('builds the documented codex subcommand argv', () => {
-    expect(buildAuthStatusArgs()).toEqual(['codex', 'auth', 'status']);
-    expect(buildDeviceAuthArgs()).toEqual(['codex', 'auth', 'device']);
-    expect(buildServeArgs()).toEqual(['serve', '--no-monitor']);
-  });
-});
-
-describe('parseAuthStatus', () => {
-  it('reports valid on exit 0 with an authenticated marker', () => {
-    const s = parseAuthStatus({
-      status: 0,
-      stdout: 'Authenticated as user; token valid',
-      stderr: '',
-    });
-    expect(s.state).toBe('valid');
-  });
-
-  it('reports expired when output mentions expiry', () => {
-    const s = parseAuthStatus({ status: 0, stdout: 'Token expired 2 days ago', stderr: '' });
-    expect(s.state).toBe('expired');
-  });
-
-  it('reports unauthenticated when output says not logged in', () => {
-    const s = parseAuthStatus({
-      status: 1,
-      stdout: '',
-      stderr: 'not authenticated: run codex auth device',
-    });
-    expect(s.state).toBe('unauthenticated');
-  });
-
-  it('reports unknown on an unrecognized non-zero exit', () => {
-    const s = parseAuthStatus({ status: 2, stdout: 'weird', stderr: '' });
-    expect(s.state).toBe('unknown');
-  });
-
-  it('does NOT trust a signal-terminated check (status null) even with an auth-looking line', () => {
-    // status: null means the process was killed by a signal — an INCOMPLETE
-    // check. An auth-looking line that happened to be flushed must not be read
-    // as valid, or preflight passes on a check that never finished.
-    const s = parseAuthStatus({ status: null, stdout: 'Authenticated', stderr: '' });
-    expect(s.state).toBe('unknown');
-  });
-
-  it('extracts a best-effort expiry in days when present', () => {
-    const s = parseAuthStatus({
-      status: 0,
-      stdout: 'Authenticated; expires in 9 days',
-      stderr: '',
-    });
-    expect(s.state).toBe('valid');
-    expect(s.expiresInDays).toBe(9);
-  });
-
-  it('treats a clean exit 0 with no explicit markers as valid', () => {
-    const s = parseAuthStatus({ status: 0, stdout: 'Session active for account foo', stderr: '' });
-    expect(s.state).toBe('valid');
-    expect(s.expiresInDays).toBeUndefined();
-  });
-
-  it('NEVER retains token-shaped material from output', () => {
-    const leaky = 'Authenticated. access_token=sk-abc123SECRETdeadbeef refresh_token=rt-9999';
-    const s: AuthStatus = parseAuthStatus({ status: 0, stdout: leaky, stderr: '' });
-    const serialized = JSON.stringify(s);
-    expect(serialized).not.toContain('sk-abc123SECRETdeadbeef');
-    expect(serialized).not.toContain('rt-9999');
-    expect(serialized).not.toContain('access_token');
-    expect(serialized).not.toContain('refresh_token');
-  });
-});
-
-describe('checkAuthStatus', () => {
-  it('runs the status subcommand and parses the result', () => {
-    const run = vi.fn(
-      (_cmd: string, _args: string[]): ProxyRunResult => ({
-        status: 0,
-        stdout: 'Authenticated; expires in 7 days',
-        stderr: '',
-      }),
-    );
-    const s = checkAuthStatus(run);
-    expect(run).toHaveBeenCalledWith(CLAUDEX_PROXY_BINARY, ['codex', 'auth', 'status']);
-    expect(s.state).toBe('valid');
-    expect(s.expiresInDays).toBe(7);
-  });
-
-  it('surfaces unknown when the default runner cannot find the binary', () => {
-    // Exercises the default spawnSync path against an absent binary: no throw,
-    // status is non-zero/null → unknown. Deterministic on a box without the proxy.
-    const s = checkAuthStatus();
-    expect(['unknown', 'unauthenticated', 'valid', 'expired']).toContain(s.state);
-  });
-});
-
-describe('runDeviceReauth', () => {
-  it('spawns the device flow with inherited stdio (never captures the code/token)', () => {
-    const calls: Array<{ cmd: string; args: string[]; opts: { stdio: string } }> = [];
-    const status = runDeviceReauth((cmd, args, opts) => {
-      calls.push({ cmd, args, opts });
-      return { status: 0 };
-    });
-    expect(status).toBe(0);
-    expect(calls).toHaveLength(1);
-    expect(calls[0]!.cmd).toBe(CLAUDEX_PROXY_BINARY);
-    expect(calls[0]!.args).toEqual(['codex', 'auth', 'device']);
-    // stdio 'inherit' is the security-critical bit: the device code streams to
-    // the user's TTY; the launcher never pipes/captures it.
-    expect(calls[0]!.opts.stdio).toBe('inherit');
-  });
-
-  it('returns 1 when the child yields no status (absent binary)', () => {
-    const status = runDeviceReauth(() => ({ status: null }));
-    expect(status).toBe(1);
-  });
-});
-
-describe('checkProxyBinary', () => {
-  it('resolves via the default `which` path (proxy absent → null)', () => {
-    // Covers the default resolver; on CI/dev the proxy is not installed.
-    const r = checkProxyBinary();
-    expect(typeof r.present).toBe('boolean');
-    if (!r.present) expect(r.path).toBeNull();
-  });
-
-  it('reports present with the resolved path', () => {
-    const r = checkProxyBinary(() => '/home/u/.local/bin/claude-code-proxy');
-    expect(r.present).toBe(true);
-    expect(r.path).toBe('/home/u/.local/bin/claude-code-proxy');
-  });
-
-  it('reports absent when the resolver finds nothing', () => {
-    const r = checkProxyBinary(() => null);
-    expect(r.present).toBe(false);
-    expect(r.path).toBeNull();
-  });
-});
-
-describe('probeLiveness (proxy-specific /healthz, not arbitrary HTTP)', () => {
-  it('defaults to probing the /healthz endpoint, never the root path', async () => {
-    const seen: string[] = [];
-    await probeLiveness(undefined, async (u) => {
-      seen.push(u);
-      return { status: 200 };
-    });
-    expect(seen[0]).toBe(CLAUDEX_HEALTH_URL);
-    expect(seen[0]).toContain('/healthz');
-  });
-
-  it('treats a 200 on /healthz as alive', async () => {
-    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 200 }));
-    expect(live).toBe(true);
-  });
-
-  it('treats a 204 on /healthz as alive', async () => {
-    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 204 }));
-    expect(live).toBe(true);
-  });
-
-  it('treats a 404 as DEAD — does not trust an arbitrary responder on the port (CWE-345)', async () => {
-    // The whole point: a random local process squatting :18765 will not honor the
-    // proxy's /healthz contract, so a non-2xx there must not be mistaken for the proxy.
-    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 404 }));
-    expect(live).toBe(false);
-  });
-
-  it('treats a 500 as DEAD (unhealthy / not the proxy health contract)', async () => {
-    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 500 }));
-    expect(live).toBe(false);
-  });
-
-  it('treats a missing status as dead', async () => {
-    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({}));
-    expect(live).toBe(false);
-  });
-
-  it('treats a connection failure (reject) as dead', async () => {
-    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => {
-      throw new Error('ECONNREFUSED');
-    });
-    expect(live).toBe(false);
-  });
-
-  it('treats a timeout as dead', async () => {
-    const never = () => new Promise<{ status?: number }>(() => {});
-    const live = await probeLiveness(CLAUDEX_HEALTH_URL, never, 20);
-    expect(live).toBe(false);
-  });
-});
-
-describe('buildSystemdUnitContent', () => {
-  it('emits a user unit that execs the given binary with serve args', () => {
-    const unit = buildSystemdUnitContent('/home/u/.local/bin/claude-code-proxy');
-    expect(unit).toContain('[Unit]');
-    expect(unit).toContain('[Service]');
-    expect(unit).toContain('[Install]');
-    expect(unit).toContain('/home/u/.local/bin/claude-code-proxy serve --no-monitor');
-    expect(unit).toContain('WantedBy=default.target');
-  });
-
-  it('never embeds credential material', () => {
-    const unit = buildSystemdUnitContent('/home/u/.local/bin/claude-code-proxy');
-    expect(unit).not.toMatch(/token/i);
-    expect(unit).not.toMatch(/auth\.json/i);
-  });
-
-  it('rejects a path containing a newline (CWE-74 systemd directive injection)', () => {
-    // A raw newline in ExecStart would let an attacker append arbitrary unit
-    // directives — e.g. `ExecStartPost=curl evil`. Must be rejected outright.
-    expect(() =>
-      buildSystemdUnitContent('/bin/claude-code-proxy\nExecStartPost=/bin/rm -rf /'),
-    ).toThrow();
-  });
-
-  it('rejects a path containing a carriage return', () => {
-    expect(() => buildSystemdUnitContent('/bin/claude-code-proxy\rmalicious')).toThrow();
-  });
-
-  it('rejects a path with other control characters', () => {
-    expect(() => buildSystemdUnitContent('/bin/claude-code-proxy\x00nul')).toThrow();
-  });
-
-  it('rejects a non-absolute path', () => {
-    expect(() => buildSystemdUnitContent('claude-code-proxy')).toThrow();
-    expect(() => buildSystemdUnitContent('')).toThrow();
-  });
-
-  it('systemd-quotes a path that contains spaces', () => {
-    const unit = buildSystemdUnitContent('/home/u/my apps/claude-code-proxy');
-    expect(unit).toContain('ExecStart="/home/u/my apps/claude-code-proxy" serve --no-monitor');
-  });
-
-  it('escapes embedded quotes and backslashes when quoting', () => {
-    const unit = buildSystemdUnitContent('/home/u/we"ird\\dir/claude-code-proxy');
-    // No unescaped closing quote can terminate the token early.
-    expect(unit).toContain('ExecStart="/home/u/we\\"ird\\\\dir/claude-code-proxy" serve');
-  });
-
-  it('leaves a clean absolute path unquoted (no needless churn)', () => {
-    const unit = buildSystemdUnitContent('/home/u/.local/bin/claude-code-proxy');
-    expect(unit).toContain('ExecStart=/home/u/.local/bin/claude-code-proxy serve --no-monitor');
-  });
-});
-
-describe('systemdUnitPath', () => {
-  it('targets the systemd --user unit dir', () => {
-    expect(systemdUnitPath('/home/u')).toBe(
-      '/home/u/.config/systemd/user/claude-code-proxy.service',
-    );
-  });
-});
-
-describe('installSystemdUnit', () => {
-  it('writes the unit and returns true when daemon-reload succeeds', () => {
-    let written: { path: string; content: string } | null = null;
-    const ok = installSystemdUnit('/bin/claude-code-proxy', {
-      home: '/home/u',
-      writeUnit: (path, content) => {
-        written = { path, content };
-      },
-      run: () => ({ status: 0, stdout: '', stderr: '' }),
-    });
-    expect(ok).toBe(true);
-    expect(written).not.toBeNull();
-    expect(written!.path).toBe('/home/u/.config/systemd/user/claude-code-proxy.service');
-    expect(written!.content).toContain('ExecStart=/bin/claude-code-proxy serve --no-monitor');
-  });
-
-  it('returns false when daemon-reload fails (systemd --user unavailable)', () => {
-    const ok = installSystemdUnit('/bin/claude-code-proxy', {
-      home: '/home/u',
-      writeUnit: () => {},
-      run: () => ({ status: 1, stdout: '', stderr: 'Failed to connect to bus' }),
-    });
-    expect(ok).toBe(false);
-  });
-
-  it('returns false when writing the unit throws', () => {
-    const ok = installSystemdUnit('/bin/claude-code-proxy', {
-      home: '/home/u',
-      writeUnit: () => {
-        throw new Error('EACCES');
-      },
-      run: () => ({ status: 0, stdout: '', stderr: '' }),
-    });
-    expect(ok).toBe(false);
-  });
-
-  it('refuses to write a unit for an injection-bearing path (never writes a poisoned unit)', () => {
-    const writeUnit = vi.fn();
-    const ok = installSystemdUnit('/bin/claude-code-proxy\nExecStartPost=/bin/rm -rf /', {
-      home: '/home/u',
-      writeUnit,
-      run: () => ({ status: 0, stdout: '', stderr: '' }),
-    });
-    expect(ok).toBe(false);
-    // The poisoned unit content is never even produced, so nothing is written.
-    expect(writeUnit).not.toHaveBeenCalled();
-  });
-
-  it('writes to a real temp dir via the default writer', () => {
-    const home = mkdtempSync(join(tmpdir(), 'claudex-unit-'));
-    try {
-      const ok = installSystemdUnit('/bin/claude-code-proxy', {
-        home,
-        run: () => ({ status: 0, stdout: '', stderr: '' }),
-      });
-      expect(ok).toBe(true);
-      const written = readFileSync(systemdUnitPath(home), 'utf8');
-      expect(written).toContain('[Service]');
-    } finally {
-      rmSync(home, { recursive: true, force: true });
-    }
-  });
-});
-
-describe('runProxyPreflight', () => {
-  const trustedListener = () => 'ok' as const;
-
-  it('is ok when binary present, auth valid, proxy live, and listener identity-verified', async () => {
-    const report = await runProxyPreflight({
-      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
-      checkAuth: () => ({ state: 'valid' }),
-      probe: async () => true,
-      verifyListener: trustedListener,
-    });
-    expect(report.ok).toBe(true);
-    expect(report.listenerVerdict).toBe('ok');
-    expect(report.problems).toEqual([]);
-  });
-
-  it('flags a missing binary', async () => {
-    const report = await runProxyPreflight({
-      checkBinary: () => ({ present: false, path: null }),
-      checkAuth: () => ({ state: 'valid' }),
-      probe: async () => true,
-      verifyListener: trustedListener,
-    });
-    expect(report.ok).toBe(false);
-    expect(report.problems.some((p) => /binary/i.test(p))).toBe(true);
-  });
-
-  it('flags expired auth (re-auth needed)', async () => {
-    const report = await runProxyPreflight({
-      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
-      checkAuth: () => ({ state: 'expired' }),
-      probe: async () => true,
-      verifyListener: trustedListener,
-    });
-    expect(report.ok).toBe(false);
-    expect(report.needsReauth).toBe(true);
-    expect(report.problems.some((p) => /auth/i.test(p))).toBe(true);
-  });
-
-  it('flags a dead proxy', async () => {
-    const report = await runProxyPreflight({
-      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
-      checkAuth: () => ({ state: 'valid' }),
-      probe: async () => false,
-      verifyListener: trustedListener,
-    });
-    expect(report.ok).toBe(false);
-    expect(report.live).toBe(false);
-  });
-
-  it('flags an unknown auth state without marking it for re-auth', async () => {
-    const report = await runProxyPreflight({
-      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
-      checkAuth: () => ({ state: 'unknown' }),
-      probe: async () => true,
-      verifyListener: trustedListener,
-    });
-    expect(report.ok).toBe(false);
-    expect(report.needsReauth).toBe(false);
-    expect(report.problems.some((p) => /could not determine/i.test(p))).toBe(true);
-  });
-
-  it('does NOT pass preflight when the live responder fails identity verification (F2b)', async () => {
-    // A squatter answering /healthz-2xx must not yield ok:true just because the
-    // binary is installed and OAuth is valid — the identity gate holds here too.
-    for (const verdict of ['foreign-user', 'wrong-exe', 'unknown'] as const) {
-      const report = await runProxyPreflight({
-        checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
-        checkAuth: () => ({ state: 'valid' }),
-        probe: async () => true,
-        verifyListener: () => verdict,
-      });
-      expect(report.ok).toBe(false);
-      expect(report.live).toBe(true);
-      expect(report.listenerVerdict).toBe(verdict);
-      expect(report.problems.some((p) => /identity could not be verified/i.test(p))).toBe(true);
-      // The identity problem is non-sensitive: port + verdict only, no token.
-      expect(JSON.stringify(report)).not.toMatch(/token|sk-|auth\.json/i);
-    }
-  });
-
-  it('does not verify listener identity when the proxy is dead (no listener to trust)', async () => {
-    const verifyListener = vi.fn(() => 'ok' as const);
-    const report = await runProxyPreflight({
-      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
-      checkAuth: () => ({ state: 'valid' }),
-      probe: async () => false,
-      verifyListener,
-    });
-    expect(verifyListener).not.toHaveBeenCalled();
-    expect(report.listenerVerdict).toBe('unknown');
-    expect(report.ok).toBe(false);
-  });
-
-  it('does not leak token material for any auth state', async () => {
-    const report = await runProxyPreflight({
-      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
-      checkAuth: () => ({ state: 'expired' }),
-      probe: async () => false,
-      verifyListener: trustedListener,
-    });
-    expect(JSON.stringify(report)).not.toMatch(/token|sk-|auth\.json/i);
-  });
-
-  it('runs end-to-end with all real defaults (no proxy installed → not ok)', async () => {
-    // Exercises the default checkBinary/checkAuth/probe closures against a box
-    // with no proxy: absent binary, spawnSync status, real loopback probe that
-    // fast-fails with ECONNREFUSED. Asserts shape only (never token material).
-    const report = await runProxyPreflight();
-    expect(typeof report.ok).toBe('boolean');
-    expect(Array.isArray(report.problems)).toBe(true);
-    expect(['valid', 'expired', 'unauthenticated', 'unknown']).toContain(report.auth.state);
-    expect(JSON.stringify(report)).not.toMatch(/access_token|refresh_token|sk-/i);
-  });
-});
-
-/**
- * A minimal fake ChildProcess for the nohup-fallback tests: records once()
- * handlers so a test can drive the async 'spawn'/'error' events, and tracks
- * whether the 'error' listener was already attached at the moment unref() ran
- * (the security-critical ordering from finding #1).
- */
-function fakeChild() {
-  const handlers: Record<string, (arg?: unknown) => void> = {};
-  const state = { unreffed: false, errorHandlerAtUnref: false };
-  const child = {
-    once(event: string, listener: (arg?: unknown) => void) {
-      handlers[event] = listener;
-      return child;
-    },
-    unref() {
-      state.unreffed = true;
-      state.errorHandlerAtUnref = typeof handlers.error === 'function';
-    },
-    emit(event: string, arg?: unknown) {
-      handlers[event]?.(arg);
-    },
-  };
-  return {
-    child: child as unknown as SpawnedChild & { emit(e: string, a?: unknown): void },
-    state,
-  };
-}
-
-describe('startNohupProxy (finding #1 — async spawn error must not crash)', () => {
-  it('resolves status 0 only after a confirmed spawn, and unrefs the child', async () => {
-    const { child, state } = fakeChild();
-    const spawnImpl = vi.fn((_cmd: string, _args: string[]) => {
-      queueMicrotask(() => child.emit('spawn'));
-      return child;
-    });
-    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
-    expect(r.status).toBe(0);
-    expect(state.unreffed).toBe(true);
-    // The error listener MUST be registered before unref(), so an ENOENT that
-    // arrives asynchronously can never become an unhandled 'error' crash.
-    expect(state.errorHandlerAtUnref).toBe(true);
-    expect(spawnImpl).toHaveBeenCalledWith('/bin/claude-code-proxy', ['serve', '--no-monitor'], {
-      detached: true,
-      stdio: 'ignore',
-    });
-  });
-
-  it('captures an async spawn error (ENOENT) as a failed start instead of crashing', async () => {
-    const { child, state } = fakeChild();
-    const spawnImpl = () => {
-      queueMicrotask(() => child.emit('error', new Error('spawn claude-code-proxy ENOENT')));
-      return child;
-    };
-    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
-    expect(r.status).toBe(1);
-    expect(r.stderr).toContain('ENOENT');
-    expect(state.unreffed).toBe(false); // never unref a child that failed to start
-  });
-
-  it('captures a synchronous spawn throw as a failed start', async () => {
-    const spawnImpl = () => {
-      throw new Error('EACCES');
-    };
-    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
-    expect(r.status).toBe(1);
-    expect(r.stderr).toContain('EACCES');
-  });
-
-  it('ignores a late error after a successful spawn (settles once)', async () => {
-    const { child } = fakeChild();
-    const spawnImpl = () => {
-      queueMicrotask(() => {
-        child.emit('spawn');
-        child.emit('error', new Error('late boom'));
-      });
-      return child;
-    };
-    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
-    expect(r.status).toBe(0); // first settle wins; the late error cannot flip it
-  });
-});
-
-describe('verifyListenerIdentity (finding #2 — OS-level listener identity, CWE-345)', () => {
-  const me: ListenerIdentity = {
-    pid: 4242,
-    uid: 1000,
-    exePath: '/home/me/.local/bin/claude-code-proxy',
-  };
-  // Identity canonicalize for tests: fake paths don't exist on disk, so we map
-  // each path to itself and exercise symlink resolution explicitly where needed.
-  const idc = (p: string) => p;
-
-  it('accepts a listener owned by the current uid whose exe is the expected proxy path', () => {
-    const verdict = verifyListenerIdentity({
-      identify: () => me,
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('ok');
-  });
-
-  it('resolves symlinks on BOTH sides before comparing (canonical match → ok)', () => {
-    // The listener exe and our resolved binary reach the same real file via
-    // different symlink paths — a canonical comparison must accept it.
-    const canon: Record<string, string> = {
-      '/var/run/proxy.link': '/opt/proxy/bin/claude-code-proxy',
-      '/home/me/.local/bin/claude-code-proxy': '/opt/proxy/bin/claude-code-proxy',
-    };
-    const verdict = verifyListenerIdentity({
-      identify: () => ({ ...me, exePath: '/var/run/proxy.link' }),
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: (p) => canon[p] ?? null,
-    });
-    expect(verdict).toBe('ok');
-  });
-
-  it('does NOT trust a same-uid process at the WRONG path with the right basename (F2a)', () => {
-    // The squatter vector on a shared-uid host: right basename, wrong path. The
-    // basename must NEVER be a trust signal when an expected exact path resolved.
-    const verdict = verifyListenerIdentity({
-      identify: () => ({ ...me, exePath: '/tmp/claude-code-proxy' }),
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('wrong-exe');
-  });
-
-  it('fails closed (unknown) when our own proxy binary path cannot be resolved (F2a)', () => {
-    // No expected path → we cannot assert identity → refuse to trust (no basename
-    // acceptance). Previously this returned `ok` by basename; that was a bypass.
-    const verdict = verifyListenerIdentity({
-      identify: () => me,
-      currentUid: () => 1000,
-      expectedExe: () => null,
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('unknown');
-  });
-
-  it('fails closed (unknown) when a path cannot be canonicalized (F2a)', () => {
-    const verdict = verifyListenerIdentity({
-      identify: () => me,
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: () => null, // e.g. binary deleted out from under the listener
-    });
-    expect(verdict).toBe('unknown');
-  });
-
-  it('rejects a listener owned by a DIFFERENT uid (foreign-user) — fail closed', () => {
-    const verdict = verifyListenerIdentity({
-      identify: () => ({ ...me, uid: 0 }),
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('foreign-user');
-  });
-
-  it('rejects a same-user listener whose exe is NOT the proxy (wrong-exe)', () => {
-    const verdict = verifyListenerIdentity({
-      identify: () => ({ ...me, exePath: '/usr/bin/nc' }),
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('wrong-exe');
-  });
-
-  it('returns unknown (fail closed) when the listener cannot be identified', () => {
-    const verdict = verifyListenerIdentity({
-      identify: () => null,
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('unknown');
-  });
-
-  it('returns unknown when the current uid is unavailable (non-posix)', () => {
-    const verdict = verifyListenerIdentity({
-      identify: () => me,
-      currentUid: () => -1,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('unknown');
-  });
-
-  it('returns unknown when the listener exe path cannot be read', () => {
-    const verdict = verifyListenerIdentity({
-      identify: () => ({ ...me, exePath: null }),
-      currentUid: () => 1000,
-      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
-      canonicalize: idc,
-    });
-    expect(verdict).toBe('unknown');
-  });
-
-  it('runs with real defaults without throwing (identity may be unresolved → verdict)', () => {
-    const verdict = verifyListenerIdentity();
-    expect(['ok', 'foreign-user', 'wrong-exe', 'unknown']).toContain(verdict);
-  });
-});
-
-describe('ensureProxyRunning', () => {
-  const ok: ProxyRunResult = { status: 0, stdout: '', stderr: '' };
-  const nohupOk = async (): Promise<ProxyRunResult> => ok;
-  const trusted = () => 'ok' as const;
-
-  it('is a no-op when the proxy is already live AND identity-verified', async () => {
-    const startSystemd = vi.fn(() => ok);
-    const startNohup = vi.fn(nohupOk);
-    const r = await ensureProxyRunning({
-      probe: async () => true,
-      verifyListener: trusted,
-      startSystemd,
-      startNohup,
-      waitMs: async () => {},
-    });
-    expect(r.method).toBe('already');
-    expect(r.live).toBe(true);
-    expect(startSystemd).not.toHaveBeenCalled();
-    expect(startNohup).not.toHaveBeenCalled();
-  });
-
-  it('fails closed as untrusted when a responder holds :18765 but identity is NOT ours', async () => {
-    // A foreign process answers /healthz but the listener is not our proxy
-    // (foreign uid / wrong exe / unidentifiable). We must NOT trust it and must
-    // NOT start a second proxy (the port is already taken) — fail closed.
-    const startSystemd = vi.fn(() => ok);
-    const startNohup = vi.fn(nohupOk);
-    const r = await ensureProxyRunning({
-      probe: async () => true,
-      verifyListener: () => 'foreign-user',
-      startSystemd,
-      startNohup,
-      waitMs: async () => {},
-    });
-    expect(r.method).toBe('untrusted');
-    expect(r.live).toBe(false);
-    expect(startSystemd).not.toHaveBeenCalled();
-    expect(startNohup).not.toHaveBeenCalled();
-  });
-
-  it('starts via systemd when available and then becomes trusted-live', async () => {
-    let calls = 0;
-    const r = await ensureProxyRunning({
-      probe: async () => calls++ > 0, // dead first, live after start
-      verifyListener: trusted,
-      startSystemd: () => ok,
-      startNohup: async () => {
-        throw new Error('should not fall back');
-      },
-      waitMs: async () => {},
-    });
-    expect(r.method).toBe('systemd');
-    expect(r.live).toBe(true);
-  });
-
-  it('waits past a slow systemd bind before giving up (finding #2 — no duplicate proxy)', async () => {
-    // systemd `start` returns 0 (job accepted) but the socket only binds on the
-    // 4th probe — still well within the startup deadline. nohup must NOT run,
-    // or two proxies would contend for :18765.
-    let probes = 0;
-    const startNohup = vi.fn(nohupOk);
-    const r = await ensureProxyRunning({
-      probe: async () => probes++ >= 3,
-      verifyListener: trusted,
-      startSystemd: () => ok,
-      startNohup,
-      waitMs: async () => {},
-      settleMs: 10,
-      startupDeadlineMs: 200,
-    });
-    expect(r.method).toBe('systemd');
-    expect(r.live).toBe(true);
-    expect(startNohup).not.toHaveBeenCalled();
-  });
-
-  it('does NOT fall back to nohup after systemd accepts but never binds (finding #1 — dup-proxy race)', async () => {
-    // systemctl start exit 0 means the job was ACCEPTED, not bound. If it binds
-    // just after our deadline (or systemd restarts it), a nohup fallback would
-    // create a SECOND proxy contending for :18765. Once systemd has accepted the
-    // job we never spawn nohup — we report a managed-service startup failure.
-    const startNohup = vi.fn(nohupOk);
-    const r = await ensureProxyRunning({
-      probe: async () => false, // never becomes live within the deadline
-      verifyListener: trusted,
-      startSystemd: () => ok,
-      startNohup,
-      waitMs: async () => {},
-      settleMs: 10,
-      startupDeadlineMs: 30,
-    });
-    expect(startNohup).not.toHaveBeenCalled();
-    expect(r.method).toBe('failed');
-    expect(r.live).toBe(false);
-  });
-
-  it('does NOT trust a systemd-started responder whose identity cannot be verified', async () => {
-    // Dead at first (so we reach the systemd start), then the socket binds — but
-    // identity never verifies (e.g. a squatter beat systemd to the port). A live
-    // responder that fails identity must never be reported as a successful start.
-    let calls = 0;
-    const startNohup = vi.fn(nohupOk);
-    const r = await ensureProxyRunning({
-      probe: async () => calls++ > 0,
-      verifyListener: () => 'wrong-exe',
-      startSystemd: () => ok,
-      startNohup,
-      waitMs: async () => {},
-      settleMs: 10,
-      startupDeadlineMs: 30,
-    });
-    expect(startNohup).not.toHaveBeenCalled();
-    expect(r.method).toBe('failed');
-    expect(r.live).toBe(false);
-  });
-
-  it('falls back to nohup only when systemd start FAILS outright (not accepted)', async () => {
-    let calls = 0;
-    const r = await ensureProxyRunning({
-      // A failed systemd start skips its post-start poll, so probes are:
-      // #0 initial (dead), #1 after nohup (live). nohup fallback is reachable
-      // ONLY because systemd never accepted the job (status 1).
-      probe: async () => calls++ > 0,
-      verifyListener: trusted,
-      startSystemd: () => ({ status: 1, stdout: '', stderr: 'no systemd' }),
-      startNohup: nohupOk,
-      waitMs: async () => {},
-      settleMs: 10,
-      startupDeadlineMs: 30,
-    });
-    expect(r.method).toBe('nohup');
-    expect(r.live).toBe(true);
-  });
-
-  it('does NOT trust a nohup-started responder whose identity cannot be verified', async () => {
-    let calls = 0;
-    const r = await ensureProxyRunning({
-      probe: async () => calls++ > 0,
-      verifyListener: () => 'unknown',
-      startSystemd: () => ({ status: 1, stdout: '', stderr: 'no systemd' }),
-      startNohup: nohupOk,
-      waitMs: async () => {},
-      settleMs: 10,
-      startupDeadlineMs: 30,
-    });
-    expect(r.method).toBe('failed');
-    expect(r.live).toBe(false);
-  });
-
-  it('reports failed when nothing brings the proxy up', async () => {
-    const r = await ensureProxyRunning({
-      probe: async () => false,
-      verifyListener: trusted,
-      startSystemd: () => ({ status: 1, stdout: '', stderr: '' }),
-      startNohup: async () => ({ status: 1, stdout: '', stderr: '' }),
-      waitMs: async () => {},
-      settleMs: 10,
-      startupDeadlineMs: 30,
-    });
-    expect(r.method).toBe('failed');
-    expect(r.live).toBe(false);
-  });
-});

packages/mosaic/src/commands/claudex-proxy.ts

@@ -1,700 +0,0 @@
-/**
- * Claudex proxy preflight + lifecycle (P1 of `mosaic yolo claudex`).
- *
- * `raine/claude-code-proxy` runs a local server on 127.0.0.1:18765 that speaks
- * the Anthropic Messages API and translates to the ChatGPT/Codex backend using
- * ChatGPT-subscription OAuth. This module owns the *preflight* and *lifecycle*
- * concerns for the launcher: is the binary present, is OAuth valid, is the proxy
- * listening, and — if not — bring it up (systemd user unit preferred, nohup
- * fallback).
- *
- * Design: every function is pure or dependency-injected so the launch path is
- * fully unit-testable without touching a real process, socket, or the OAuth
- * token. Nothing here reads `~/.config/claude-code-proxy/codex/auth.json`; the
- * proxy holds the real credential and Claude Code only ever sees
- * `ANTHROPIC_AUTH_TOKEN=unused`. Parsed auth status is deliberately coarse
- * (state + optional expiry) so no token material can be retained or surfaced.
- */
-
-import { execFileSync, spawn, spawnSync } from 'node:child_process';
-import { mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-
-// ─── Endpoint / command constants (spec table) ──────────────────────────────
-
-export const CLAUDEX_PROXY_HOST = '127.0.0.1';
-export const CLAUDEX_PROXY_PORT = 18765;
-export const CLAUDEX_PROXY_URL = `http://${CLAUDEX_PROXY_HOST}:${CLAUDEX_PROXY_PORT}`;
-export const CLAUDEX_PROXY_BINARY = 'claude-code-proxy';
-export const CLAUDEX_SYSTEMD_UNIT = 'claude-code-proxy.service';
-
-/**
- * The proxy's dedicated liveness endpoint. We probe this — NOT the root path —
- * for two reasons: (1) the root returns non-2xx (spec gotcha #1), which is why
- * the original `curl -f` check spawned duplicate proxies; `/healthz` returns 2xx
- * when the proxy is healthy. (2) It is a *proxy-specific* contract, so a 2xx here
- * is a much stronger signal that the responder on :18765 is actually our proxy
- * and not some other local process squatting the port (CWE-345).
- */
-export const CLAUDEX_HEALTH_PATH = '/healthz';
-export const CLAUDEX_HEALTH_URL = `${CLAUDEX_PROXY_URL}${CLAUDEX_HEALTH_PATH}`;
-
-/** argv for `claude-code-proxy codex auth status`. */
-export function buildAuthStatusArgs(): string[] {
-  return ['codex', 'auth', 'status'];
-}
-
-/** argv for `claude-code-proxy codex auth device` (device-code re-auth flow). */
-export function buildDeviceAuthArgs(): string[] {
-  return ['codex', 'auth', 'device'];
-}
-
-/** argv for `claude-code-proxy serve --no-monitor`. */
-export function buildServeArgs(): string[] {
-  return ['serve', '--no-monitor'];
-}
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-export type AuthState = 'valid' | 'expired' | 'unauthenticated' | 'unknown';
-
-/**
- * Coarse OAuth status. Intentionally carries NO token material — only a state
- * and an optional best-effort expiry-in-days for user-facing messaging.
- */
-export interface AuthStatus {
-  state: AuthState;
-  expiresInDays?: number;
-}
-
-export interface ProxyRunResult {
-  status: number | null;
-  stdout: string;
-  stderr: string;
-}
-
-/** Runs a command synchronously and returns its captured result. */
-export type CommandRunner = (cmd: string, args: string[]) => ProxyRunResult;
-
-/** Minimal fetch shape used for the liveness probe (any HTTP response = alive). */
-export type FetchLike = (
-  url: string,
-  init?: { signal?: AbortSignal },
-) => Promise<{ status?: number }>;
-
-// ─── Binary presence ─────────────────────────────────────────────────────────
-
-function defaultWhich(cmd: string): string | null {
-  try {
-    return execFileSync('which', [cmd], { encoding: 'utf8' }).trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-export function checkProxyBinary(resolve: (cmd: string) => string | null = defaultWhich): {
-  present: boolean;
-  path: string | null;
-} {
-  const path = resolve(CLAUDEX_PROXY_BINARY);
-  return { present: path !== null && path !== '', path: path || null };
-}
-
-// ─── Auth status ─────────────────────────────────────────────────────────────
-
-/**
- * Parse `claude-code-proxy codex auth status` output into a coarse state.
- *
- * The proxy's exact wording is not contractually pinned, so this matches
- * tolerantly on well-known markers and falls back on the exit code. It never
- * copies the raw output onto the result — only a state and an optional expiry —
- * so token-shaped strings in the output cannot leak downstream.
- */
-export function parseAuthStatus(result: ProxyRunResult): AuthStatus {
-  const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
-
-  const expired = /\bexpired\b|token has expired|expires?d? \d+ days? ago/.test(text);
-  const unauth =
-    /not authenticated|not logged in|no (?:auth|credentials|token)|please (?:log ?in|authenticate)|run .*auth device/.test(
-      text,
-    );
-  const authed = /\bauthenticated\b|logged in|token valid|valid until|expires? in/.test(text);
-
-  let state: AuthState;
-  if (expired) {
-    state = 'expired';
-  } else if (unauth) {
-    state = 'unauthenticated';
-  } else if (authed && result.status === 0) {
-    // A `null` status means the check was killed by a signal — an INCOMPLETE
-    // run. We require a clean exit 0 for `valid`; a partially-flushed auth line
-    // from a signal-terminated check must never be trusted (finding #3).
-    state = 'valid';
-  } else if (result.status === 0) {
-    state = 'valid';
-  } else {
-    state = 'unknown';
-  }
-
-  const status: AuthStatus = { state };
-  const days = /expires? in (\d+) days?/.exec(text);
-  if (state === 'valid' && days) {
-    status.expiresInDays = Number(days[1]);
-  }
-  return status;
-}
-
-function defaultRun(cmd: string, args: string[]): ProxyRunResult {
-  const r = spawnSync(cmd, args, { encoding: 'utf8' });
-  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
-}
-
-export function checkAuthStatus(run: CommandRunner = defaultRun): AuthStatus {
-  return parseAuthStatus(run(CLAUDEX_PROXY_BINARY, buildAuthStatusArgs()));
-}
-
-/** Spawn shape for the interactive device re-auth flow. */
-export type InheritSpawn = (
-  cmd: string,
-  args: string[],
-  opts: { stdio: 'inherit' },
-) => { status: number | null };
-
-function defaultInheritSpawn(cmd: string, args: string[], opts: { stdio: 'inherit' }) {
-  return spawnSync(cmd, args, opts);
-}
-
-/**
- * Run the device-code re-auth flow (`claude-code-proxy codex auth device`).
- *
- * Deliberately `stdio: 'inherit'` so the device code the proxy prints goes
- * straight to the user's terminal — the launcher NEVER captures, stores, or logs
- * it, and never observes the resulting OAuth token (the proxy persists that to
- * its own config). Returns the child's exit status; 1 on an absent binary.
- */
-export function runDeviceReauth(spawnImpl: InheritSpawn = defaultInheritSpawn): number {
-  const r = spawnImpl(CLAUDEX_PROXY_BINARY, buildDeviceAuthArgs(), { stdio: 'inherit' });
-  return r.status ?? 1;
-}
-
-// ─── Liveness (probe the proxy-specific /healthz; require 2xx) ────────────────
-
-/**
- * Probe the proxy for liveness by hitting its dedicated `GET /healthz` endpoint
- * and requiring a 2xx response.
- *
- * This is a LIVENESS check only — it answers "is a healthy proxy responding?",
- * not "is that responder actually ours?". Requiring a 2xx on the proxy's own
- * `/healthz` contract (rather than "any HTTP response = alive") resolves spec
- * gotcha #1: the root path returns non-2xx, but `/healthz` returns 2xx when
- * healthy, so a live proxy is never mistaken for dead and no duplicate proxy is
- * spawned.
- *
- * Residual risk (CWE-345): the proxy binds loopback with NO client
- * authentication, so on a shared host a local process could occupy :18765 and
- * serve a 2xx here. A 2xx therefore does NOT by itself establish that the
- * listener is our proxy. Identity is verified SEPARATELY and at every trust
- * point by {@link verifyListenerIdentity} (OS-level uid + executable check),
- * which fails closed when identity can't be established. See
- * {@link ensureProxyRunning}. (Broader multi-user hardening — a persistent
- * warning when a foreign listener is seen — is tracked for a later phase.)
- */
-export async function probeLiveness(
-  url: string = CLAUDEX_HEALTH_URL,
-  fetchImpl: FetchLike = fetch as unknown as FetchLike,
-  timeoutMs = 1500,
-): Promise<boolean> {
-  const controller = new AbortController();
-  let timer: ReturnType<typeof setTimeout> | undefined;
-
-  // Bound the probe with our own timeout race rather than trusting the fetch
-  // implementation to honor the abort signal — a hung socket (or a fetch that
-  // ignores the signal) must never wedge the launcher. We still abort() so a
-  // signal-aware fetch tears the request down promptly.
-  const timeout = new Promise<boolean>((resolve) => {
-    timer = setTimeout(() => {
-      controller.abort();
-      resolve(false);
-    }, timeoutMs);
-  });
-
-  const probe = fetchImpl(url, { signal: controller.signal })
-    .then((res) => typeof res.status === 'number' && res.status >= 200 && res.status < 300)
-    .catch(() => false); // connection refused / aborted → dead
-
-  try {
-    return await Promise.race([probe, timeout]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-
-// ─── Listener identity (OS-level, CWE-345 mitigation) ─────────────────────────
-
-/**
- * The result of verifying who actually owns the :18765 listener.
- *  - `ok`           — same-user process running the expected proxy binary.
- *  - `foreign-user` — a process owned by a DIFFERENT uid holds the port.
- *  - `wrong-exe`    — same-user, but the executable is not the proxy.
- *  - `unknown`      — identity could not be established (fail closed).
- */
-export type ListenerVerdict = 'ok' | 'foreign-user' | 'wrong-exe' | 'unknown';
-
-/** OS-level identity of the process bound to the proxy port. */
-export interface ListenerIdentity {
-  pid: number;
-  uid: number;
-  /** Absolute path of the process executable, or null if unreadable. */
-  exePath: string | null;
-}
-
-export interface VerifyListenerDeps {
-  /** Resolve the process bound to the proxy port (null → unidentifiable). */
-  identify?: () => ListenerIdentity | null;
-  /** The current process uid (-1 when unavailable, e.g. non-posix). */
-  currentUid?: () => number;
-  /** The expected proxy executable path (null when it can't be resolved). */
-  expectedExe?: () => string | null;
-  /** Canonicalize a path (resolve symlinks); null when it can't be resolved. */
-  canonicalize?: (p: string) => string | null;
-}
-
-/** Resolve a path through symlinks to its canonical form; null on any failure. */
-function defaultCanonicalize(p: string): string | null {
-  try {
-    return realpathSync(p);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Identify the process listening on the proxy port via `ss` + `/proc`. Every
- * failure path returns null so the caller fails closed. Reads no credential
- * material — only pid/uid/exe path of the listener.
- */
-function defaultIdentifyListener(port: number = CLAUDEX_PROXY_PORT): ListenerIdentity | null {
-  try {
-    const out = execFileSync('ss', ['-H', '-ltnp', `sport = :${port}`], { encoding: 'utf8' });
-    const pidMatch = /pid=(\d+)/.exec(out);
-    if (!pidMatch) return null;
-    const pid = Number(pidMatch[1]);
-    if (!Number.isInteger(pid) || pid <= 0) return null;
-
-    const status = readFileSync(`/proc/${pid}/status`, 'utf8');
-    const uidLine = /^Uid:\s*(\d+)/m.exec(status);
-    if (!uidLine) return null;
-    const uid = Number(uidLine[1]);
-
-    let exePath: string | null = null;
-    try {
-      exePath = readlinkSync(`/proc/${pid}/exe`);
-    } catch {
-      exePath = null;
-    }
-    return { pid, uid, exePath };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Verify that the process owning :18765 is genuinely OUR proxy before trusting
- * it. The proxy binds loopback with NO client authentication, so on a shared
- * host any local process could squat the port and a liveness 2xx alone does not
- * prove identity (CWE-345). We FAIL CLOSED (`unknown`) whenever identity cannot
- * be established. This needs no upstream shared-secret/unix-socket support from
- * `claude-code-proxy`.
- *
- * The executable path is the trust boundary that matters: on a shared-uid host
- * (every agent session runs as the same operator) same-uid is NOT sufficient, so
- * we require an EXACT canonical-path match against our resolved proxy binary and
- * canonicalize both sides for symlinks. There is deliberately NO basename
- * fallback — a same-uid process running `/tmp/claude-code-proxy` (right name,
- * wrong path) must never be trusted. If our own binary path can't be resolved,
- * or either path can't be canonicalized, we fail closed rather than downgrade to
- * a weaker check.
- */
-export function verifyListenerIdentity(deps: VerifyListenerDeps = {}): ListenerVerdict {
-  const identify = deps.identify ?? (() => defaultIdentifyListener());
-  const currentUid =
-    deps.currentUid ?? (() => (typeof process.getuid === 'function' ? process.getuid() : -1));
-  const expectedExe = deps.expectedExe ?? (() => checkProxyBinary().path);
-  const canonicalize = deps.canonicalize ?? defaultCanonicalize;
-
-  const id = identify();
-  if (!id) return 'unknown'; // can't see the listener → don't trust it
-  const uid = currentUid();
-  if (uid < 0) return 'unknown'; // can't establish our own identity → fail closed
-  if (id.uid !== uid) return 'foreign-user'; // someone else's process holds the port
-  if (!id.exePath) return 'unknown'; // can't confirm the executable → fail closed
-
-  const expected = expectedExe();
-  if (!expected) return 'unknown'; // can't resolve our own binary → fail closed
-  const expectedReal = canonicalize(expected);
-  const actualReal = canonicalize(id.exePath);
-  if (!expectedReal || !actualReal) return 'unknown'; // uncanonicalizable → fail closed
-  return actualReal === expectedReal ? 'ok' : 'wrong-exe';
-}
-
-// ─── systemd user unit ───────────────────────────────────────────────────────
-
-export function systemdUnitPath(home: string = homedir()): string {
-  return join(home, '.config', 'systemd', 'user', CLAUDEX_SYSTEMD_UNIT);
-}
-
-/**
- * Validate a path destined for a systemd `ExecStart=` line. A raw newline (or
- * other control character) in the path would let an attacker inject arbitrary
- * unit directives (e.g. an extra `ExecStartPost=`), a CWE-74 command injection.
- * We require a plain absolute path and reject any control character outright.
- */
-function validateExecPath(binaryPath: string): string {
-  if (typeof binaryPath !== 'string' || binaryPath.length === 0) {
-    throw new Error('systemd ExecStart: binary path is empty');
-  }
-  if (!binaryPath.startsWith('/')) {
-    throw new Error(
-      `systemd ExecStart: binary path must be absolute: ${JSON.stringify(binaryPath)}`,
-    );
-  }
-
-  if (/[\x00-\x1f\x7f]/.test(binaryPath)) {
-    throw new Error('systemd ExecStart: binary path contains control characters');
-  }
-  return binaryPath;
-}
-
-/**
- * Encode a validated path for a systemd `ExecStart=` token. systemd only needs
- * quoting when the token carries whitespace or quote/backslash characters; a
- * clean path is emitted verbatim. When quoting, we escape backslashes and double
- * quotes per systemd's C-style rules so the token cannot be terminated early.
- */
-function systemdQuoteExec(path: string): string {
-  if (!/[\s"'\\]/.test(path)) {
-    return path;
-  }
-  const escaped = path.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-  return `"${escaped}"`;
-}
-
-/**
- * Render the `claude-code-proxy.service` user unit. Contains no credential
- * material — the proxy reads its own OAuth token from its config dir at runtime.
- * The binary path is validated (absolute, no control characters) and systemd-
- * quoted so it cannot inject unit directives.
- */
-export function buildSystemdUnitContent(binaryPath: string): string {
-  const exec = `${systemdQuoteExec(validateExecPath(binaryPath))} ${buildServeArgs().join(' ')}`;
-  return [
-    '[Unit]',
-    'Description=claude-code-proxy (Anthropic->Codex translation proxy for mosaic claudex)',
-    'After=network-online.target',
-    'Wants=network-online.target',
-    '',
-    '[Service]',
-    'Type=simple',
-    `ExecStart=${exec}`,
-    'Restart=on-failure',
-    'RestartSec=2',
-    '',
-    '[Install]',
-    'WantedBy=default.target',
-    '',
-  ].join('\n');
-}
-
-/**
- * Write the user unit and reload the systemd --user daemon. Returns false when
- * systemd --user is unavailable (the caller then falls back to nohup).
- */
-export function installSystemdUnit(
-  binaryPath: string,
-  deps: {
-    home?: string;
-    writeUnit?: (path: string, content: string) => void;
-    run?: CommandRunner;
-  } = {},
-): boolean {
-  const home = deps.home ?? homedir();
-  const write =
-    deps.writeUnit ??
-    ((path: string, content: string) => {
-      mkdirSync(dirname(path), { recursive: true });
-      writeFileSync(path, content);
-    });
-  const run = deps.run ?? defaultRun;
-
-  try {
-    write(systemdUnitPath(home), buildSystemdUnitContent(binaryPath));
-    const reload = run('systemctl', ['--user', 'daemon-reload']);
-    return reload.status === 0;
-  } catch {
-    return false;
-  }
-}
-
-// ─── Preflight report ────────────────────────────────────────────────────────
-
-export interface PreflightReport {
-  binaryPresent: boolean;
-  binaryPath: string | null;
-  auth: AuthStatus;
-  live: boolean;
-  /** OS-level identity verdict for the :18765 listener (`unknown` when dead). */
-  listenerVerdict: ListenerVerdict;
-  needsReauth: boolean;
-  ok: boolean;
-  problems: string[];
-}
-
-export interface PreflightDeps {
-  checkBinary?: () => { present: boolean; path: string | null };
-  checkAuth?: () => AuthStatus;
-  probe?: () => Promise<boolean>;
-  verifyListener?: () => ListenerVerdict;
-}
-
-/**
- * Compose the preflight checks into a single structured report. `ok` is true
- * only when the binary is present, OAuth is valid, the proxy responds, AND the
- * responding listener's OS-level identity verifies as our proxy.
- *
- * The identity gate lives here too, not only in {@link ensureProxyRunning}: any
- * consumer of this report (notably the phase-2 launch path) would otherwise
- * treat a `/healthz`-2xx squatter as healthy and route Claude traffic to it
- * (CWE-345). A liveness 2xx is necessary but not sufficient — a live responder
- * that fails identity fails the preflight.
- */
-export async function runProxyPreflight(deps: PreflightDeps = {}): Promise<PreflightReport> {
-  const checkBinary = deps.checkBinary ?? (() => checkProxyBinary());
-  const checkAuth = deps.checkAuth ?? (() => checkAuthStatus());
-  const probe = deps.probe ?? (() => probeLiveness());
-  const verifyListener = deps.verifyListener ?? (() => verifyListenerIdentity());
-
-  const bin = checkBinary();
-  const auth = checkAuth();
-  const live = await probe();
-  // Only meaningful when something is actually responding; a dead port has no
-  // listener identity to establish.
-  const listenerVerdict: ListenerVerdict = live ? verifyListener() : 'unknown';
-
-  const problems: string[] = [];
-  if (!bin.present) {
-    problems.push(
-      `claude-code-proxy binary not found in PATH. Install it before launching claudex.`,
-    );
-  }
-  const needsReauth = auth.state === 'expired' || auth.state === 'unauthenticated';
-  if (needsReauth) {
-    problems.push(
-      `claude-code-proxy OAuth is ${auth.state}. Re-auth with: ${CLAUDEX_PROXY_BINARY} ${buildDeviceAuthArgs().join(' ')}`,
-    );
-  } else if (auth.state === 'unknown') {
-    problems.push('Could not determine claude-code-proxy OAuth status.');
-  }
-  if (!live) {
-    problems.push(`No proxy responding on ${CLAUDEX_PROXY_URL}.`);
-  } else if (listenerVerdict !== 'ok') {
-    // Non-sensitive: names the port and the verdict only — never any listener
-    // command line, token, or other process detail.
-    problems.push(
-      `A process is listening on ${CLAUDEX_PROXY_URL} but its identity could not be verified as ${CLAUDEX_PROXY_BINARY} (${listenerVerdict}). Refusing to trust it.`,
-    );
-  }
-
-  const ok = bin.present && auth.state === 'valid' && live && listenerVerdict === 'ok';
-  return {
-    binaryPresent: bin.present,
-    binaryPath: bin.path,
-    auth,
-    live,
-    listenerVerdict,
-    needsReauth,
-    ok,
-    problems,
-  };
-}
-
-// ─── Lifecycle: ensure the proxy is running ──────────────────────────────────
-
-export type ProxyStartMethod = 'already' | 'systemd' | 'nohup' | 'untrusted' | 'failed';
-
-export interface EnsureProxyResult {
-  live: boolean;
-  method: ProxyStartMethod;
-}
-
-/** Minimal spawned-child shape used by the nohup fallback (testable seam). */
-export interface SpawnedChild {
-  once(event: string, listener: (arg?: unknown) => void): unknown;
-  unref(): void;
-}
-
-/** Spawn shape for the detached fallback process. */
-export type SpawnLike = (
-  cmd: string,
-  args: string[],
-  opts: { detached: boolean; stdio: 'ignore' },
-) => SpawnedChild;
-
-export interface StartNohupDeps {
-  resolveBin?: () => string;
-  spawnImpl?: SpawnLike;
-}
-
-/**
- * Start the proxy as a detached background process (the fallback when no systemd
- * user unit is available).
- *
- * `spawn()` reports launch failures (ENOENT/EACCES) ASYNCHRONOUSLY via the
- * child's `error` event, which a `try/catch` cannot see. If left unhandled that
- * event throws and crashes the launcher. So we: (1) attach the `error` listener
- * BEFORE `unref()`, capturing a failed launch as a non-zero result instead of a
- * crash; and (2) resolve success only after the child's `spawn` event fires —
- * never optimistically before the process is known to have started.
- */
-export function startNohupProxy(deps: StartNohupDeps = {}): Promise<ProxyRunResult> {
-  const resolveBin = deps.resolveBin ?? (() => checkProxyBinary().path ?? CLAUDEX_PROXY_BINARY);
-  const spawnImpl =
-    deps.spawnImpl ?? ((cmd, args, opts) => spawn(cmd, args, opts) as unknown as SpawnedChild);
-
-  return new Promise<ProxyRunResult>((resolve) => {
-    let settled = false;
-    const finish = (r: ProxyRunResult) => {
-      if (!settled) {
-        settled = true;
-        resolve(r);
-      }
-    };
-
-    let child: SpawnedChild;
-    try {
-      child = spawnImpl(resolveBin(), buildServeArgs(), { detached: true, stdio: 'ignore' });
-    } catch (err) {
-      finish({ status: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) });
-      return;
-    }
-
-    // Register error handling BEFORE unref so an async spawn failure is caught.
-    child.once('error', (err) => {
-      finish({
-        status: 1,
-        stdout: '',
-        stderr: err instanceof Error ? err.message : String(err),
-      });
-    });
-    child.once('spawn', () => {
-      child.unref();
-      finish({ status: 0, stdout: '', stderr: '' });
-    });
-  });
-}
-
-export interface EnsureProxyDeps {
-  probe?: () => Promise<boolean>;
-  /** OS-level identity check for the process holding the proxy port. */
-  verifyListener?: () => ListenerVerdict;
-  startSystemd?: () => ProxyRunResult;
-  startNohup?: () => Promise<ProxyRunResult>;
-  waitMs?: (ms: number) => Promise<void>;
-  /** Interval between liveness polls while waiting for a start to bind. */
-  settleMs?: number;
-  /** Total budget to wait for a started proxy to bind its socket. */
-  startupDeadlineMs?: number;
-}
-
-function defaultWait(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function defaultStartSystemd(): ProxyRunResult {
-  return defaultRun('systemctl', ['--user', 'start', CLAUDEX_SYSTEMD_UNIT]);
-}
-
-/**
- * Poll for a TRUSTED-live proxy up to a bounded startup deadline. A start command
- * returning 0 only means the job was ACCEPTED, not that the socket is bound — so
- * we keep probing at `intervalMs` until either the deadline elapses or the port
- * both responds AND passes the OS-level identity check. Liveness alone is not
- * enough: a responder that fails identity (a squatter) must never be trusted.
- */
-async function waitForTrusted(
-  probe: () => Promise<boolean>,
-  verifyListener: () => ListenerVerdict,
-  waitMs: (ms: number) => Promise<void>,
-  intervalMs: number,
-  deadlineMs: number,
-): Promise<boolean> {
-  let elapsed = 0;
-  while (elapsed < deadlineMs) {
-    await waitMs(intervalMs);
-    elapsed += intervalMs;
-    if ((await probe()) && verifyListener() === 'ok') {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Ensure a proxy is listening. No-op when already live. Otherwise prefer the
- * systemd user unit, then fall back to a detached background process.
- *
- * Every trust point is gated on OS-level listener identity, not just liveness:
- * the proxy has no client authentication, so on a shared host a local process
- * could squat :18765 and a 2xx `/healthz` alone would not prove it is our proxy
- * (CWE-345, finding #2). We only trust a responder whose owning process is the
- * current uid running the expected proxy binary; otherwise we fail closed.
- *
- * If a responder is already present but its identity does NOT verify, we return
- * `untrusted` WITHOUT starting anything — the port is taken, so spawning would
- * only create contention, and we must never route Claude traffic through an
- * unverified listener.
- *
- * After a start command is accepted we poll to a bounded startup deadline before
- * giving up: `systemctl start` exit 0 means the job was accepted, not that the
- * socket bound within one probe interval. Critically, once systemd ACCEPTS the
- * job we do NOT fall back to nohup even if it never becomes trusted-live in the
- * deadline (finding #1): the accepted unit may bind late or be restarted by
- * systemd, and a second proxy would then contend for :18765 — the very
- * duplicate-proxy outcome this function exists to prevent. nohup is reachable
- * only when systemd never accepted the job at all.
- */
-export async function ensureProxyRunning(deps: EnsureProxyDeps = {}): Promise<EnsureProxyResult> {
-  const probe = deps.probe ?? (() => probeLiveness());
-  const verifyListener = deps.verifyListener ?? (() => verifyListenerIdentity());
-  const startSystemd = deps.startSystemd ?? defaultStartSystemd;
-  const startNohup = deps.startNohup ?? (() => startNohupProxy());
-  const waitMs = deps.waitMs ?? defaultWait;
-  const settleMs = deps.settleMs ?? 500;
-  const startupDeadlineMs = deps.startupDeadlineMs ?? 5000;
-
-  if (await probe()) {
-    // Something answers on :18765 — trust it ONLY if it is provably our proxy.
-    return verifyListener() === 'ok'
-      ? { live: true, method: 'already' }
-      : { live: false, method: 'untrusted' };
-  }
-
-  const systemd = startSystemd();
-  if (systemd.status === 0) {
-    // systemd accepted the job. Wait for a trusted-live bind, but never fall
-    // back to nohup afterward — that would risk a duplicate proxy (finding #1).
-    if (await waitForTrusted(probe, verifyListener, waitMs, settleMs, startupDeadlineMs)) {
-      return { live: true, method: 'systemd' };
-    }
-    return { live: false, method: 'failed' };
-  }
-
-  const nohup = await startNohup();
-  if (nohup.status === 0) {
-    if (await waitForTrusted(probe, verifyListener, waitMs, settleMs, startupDeadlineMs)) {
-      return { live: true, method: 'nohup' };
-    }
-  }
-
-  return { live: false, method: 'failed' };
-}

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

@@ -1,732 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { mkdtempSync, mkdirSync, symlinkSync, rmSync, lstatSync, writeFileSync } from 'node:fs';
-import { tmpdir, homedir } from 'node:os';
-import { join } from 'node:path';
-import {
-  CLAUDEX_CONFIG_DIR_ENV,
-  CLAUDEX_DEFAULT_PRIMARY_MODEL,
-  CLAUDEX_DEFAULT_SMALL_FAST_MODEL,
-  CLAUDEX_CREDENTIAL_ENV_RE,
-  defaultClaudexConfigDir,
-  assertIsolatedConfigDir,
-  resolveClaudexConfigDir,
-  resolveClaudexModels,
-  buildClaudexEnv,
-  buildClaudexBanner,
-  buildClaudexContractNote,
-  runClaudexProxyGate,
-  launchClaudex,
-  type ClaudexHarnessAdapter,
-} from './claudex.js';
-import { CLAUDEX_PROXY_URL, type PreflightReport } from './claudex-proxy.js';
-
-// ─── helpers ─────────────────────────────────────────────────────────────────
-
-function makeReport(overrides: Partial<PreflightReport> = {}): PreflightReport {
-  return {
-    binaryPresent: true,
-    binaryPath: '/usr/bin/claude-code-proxy',
-    auth: { state: 'valid' },
-    live: true,
-    listenerVerdict: 'ok',
-    needsReauth: false,
-    ok: true,
-    problems: [],
-    ...overrides,
-  };
-}
-
-function okAdapter(overrides: Partial<ClaudexHarnessAdapter> = {}): ClaudexHarnessAdapter {
-  return {
-    harnessPreflight: () => {},
-    composePrompt: () => '# Composed Claude contract',
-    exec: () => {},
-    ...overrides,
-  };
-}
-
-// Identity canonicalizer + no-op FS deps so config-dir logic is tested purely.
-const idCanon = (p: string): string => p;
-const noFsDeps = { canonicalize: idCanon, mkdir: () => {}, isSymlink: () => false };
-
-// ─── isolated config dir (HARD SECURITY REQ 1 — provable isolation) ───────────
-
-describe('defaultClaudexConfigDir', () => {
-  it('is namespaced under the mosaic home, never ~/.claude', () => {
-    const dir = defaultClaudexConfigDir('/home/agent/.config/mosaic');
-    expect(dir).toBe(join('/home/agent/.config/mosaic', 'claudex', 'home'));
-    expect(dir).not.toBe(join(homedir(), '.claude'));
-  });
-});
-
-describe('assertIsolatedConfigDir — the isolation guard is provable', () => {
-  const realClaude = '/home/agent/.claude';
-
-  it('accepts a dir that does not resolve to ~/.claude', () => {
-    const safe = '/home/agent/.config/mosaic/claudex/home';
-    expect(
-      assertIsolatedConfigDir(safe, { realClaudeDir: realClaude, canonicalize: idCanon }),
-    ).toBe(safe);
-  });
-
-  it('REJECTS a candidate that is literally ~/.claude', () => {
-    expect(() =>
-      assertIsolatedConfigDir(realClaude, { realClaudeDir: realClaude, canonicalize: idCanon }),
-    ).toThrow(/refusing/i);
-  });
-
-  it('REJECTS a descendant of ~/.claude (would pollute the real tree)', () => {
-    expect(() =>
-      assertIsolatedConfigDir('/home/agent/.claude/projects/x', {
-        realClaudeDir: realClaude,
-        canonicalize: idCanon,
-      }),
-    ).toThrow(/refusing/i);
-  });
-
-  it('REJECTS a candidate that canonically resolves to ~/.claude (symlink, both sides canonicalized)', () => {
-    const canon = (p: string): string => (p === '/home/agent/link' ? realClaude : p);
-    expect(() =>
-      assertIsolatedConfigDir('/home/agent/link', {
-        realClaudeDir: realClaude,
-        canonicalize: canon,
-      }),
-    ).toThrow(/refusing/i);
-  });
-
-  it('canonicalizes the ~/.claude side too (real dir itself may be a symlink)', () => {
-    // realClaudeDir is a symlink whose canonical target equals the candidate's target.
-    const canon = (p: string): string =>
-      p === '/home/agent/.claude' || p === '/home/agent/link' ? '/canonical/claude' : p;
-    expect(() =>
-      assertIsolatedConfigDir('/home/agent/link', {
-        realClaudeDir: realClaude,
-        canonicalize: canon,
-      }),
-    ).toThrow(/refusing/i);
-  });
-
-  it('REJECTS an empty or whitespace candidate (fail closed)', () => {
-    expect(() =>
-      assertIsolatedConfigDir('', { realClaudeDir: realClaude, canonicalize: idCanon }),
-    ).toThrow();
-    expect(() =>
-      assertIsolatedConfigDir('   ', { realClaudeDir: realClaude, canonicalize: idCanon }),
-    ).toThrow();
-  });
-
-  it('REJECTS a relative candidate (must be absolute)', () => {
-    expect(() =>
-      assertIsolatedConfigDir('relative/dir', { realClaudeDir: realClaude, canonicalize: idCanon }),
-    ).toThrow(/absolute/i);
-  });
-});
-
-describe('resolveClaudexConfigDir', () => {
-  it('uses the namespaced default and never the ambient CLAUDE_CONFIG_DIR', () => {
-    // Ambient CLAUDE_CONFIG_DIR is deliberately ignored (it could be ~/.claude).
-    const env = { CLAUDE_CONFIG_DIR: join(homedir(), '.claude') };
-    const dir = resolveClaudexConfigDir(env, {
-      mosaicHome: '/home/agent/.config/mosaic',
-      realClaudeDir: '/home/agent/.claude',
-      ...noFsDeps,
-    });
-    expect(dir).toBe(join('/home/agent/.config/mosaic', 'claudex', 'home'));
-  });
-
-  it('honors the dedicated override env when it is safe', () => {
-    const env = { [CLAUDEX_CONFIG_DIR_ENV]: '/home/agent/custom-claudex' };
-    const dir = resolveClaudexConfigDir(env, {
-      mosaicHome: '/home/agent/.config/mosaic',
-      realClaudeDir: '/home/agent/.claude',
-      ...noFsDeps,
-    });
-    expect(dir).toBe('/home/agent/custom-claudex');
-  });
-
-  it('REJECTS a dedicated override that points at ~/.claude (before creating anything)', () => {
-    const mkdir = vi.fn();
-    const env = { [CLAUDEX_CONFIG_DIR_ENV]: '/home/agent/.claude' };
-    expect(() =>
-      resolveClaudexConfigDir(env, {
-        mosaicHome: '/home/agent/.config/mosaic',
-        realClaudeDir: '/home/agent/.claude',
-        canonicalize: idCanon,
-        mkdir,
-        isSymlink: () => false,
-      }),
-    ).toThrow(/refusing/i);
-    expect(mkdir).not.toHaveBeenCalled();
-  });
-
-  it('TOCTOU: REJECTS when the created target is itself a symlink (pre-created race)', () => {
-    const env = {};
-    expect(() =>
-      resolveClaudexConfigDir(env, {
-        mosaicHome: '/home/agent/.config/mosaic',
-        realClaudeDir: '/home/agent/.claude',
-        canonicalize: idCanon,
-        mkdir: () => {},
-        isSymlink: () => true, // the just-ensured dir is a symlink → fail closed
-      }),
-    ).toThrow(/refusing|symlink/i);
-  });
-
-  it('real-FS: creates the isolated dir 0700 and returns its canonical path', () => {
-    const root = mkdtempSync(join(tmpdir(), 'claudex-cfg-'));
-    try {
-      const mosaicHome = join(root, '.config', 'mosaic');
-      const dir = resolveClaudexConfigDir({}, { mosaicHome, realClaudeDir: join(root, '.claude') });
-      expect(dir).toBe(join(mosaicHome, 'claudex', 'home'));
-      const st = lstatSync(dir);
-      expect(st.isDirectory()).toBe(true);
-      // 0700 (owner-only) — mask off the type bits.
-      expect(st.mode & 0o777).toBe(0o700);
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  it('real-FS: catches an override whose ancestor symlinks into ~/.claude', () => {
-    const root = mkdtempSync(join(tmpdir(), 'claudex-cfg-'));
-    try {
-      const realClaudeDir = join(root, 'dot-claude');
-      mkdirSync(realClaudeDir, { recursive: true });
-      const link = join(root, 'link'); // link -> dot-claude
-      symlinkSync(realClaudeDir, link, 'dir');
-      const override = join(link, 'sub'); // resolves under ~/.claude
-      expect(() =>
-        resolveClaudexConfigDir(
-          { [CLAUDEX_CONFIG_DIR_ENV]: override },
-          { mosaicHome: join(root, '.config', 'mosaic'), realClaudeDir },
-        ),
-      ).toThrow(/refusing/i);
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  it('FAIL CLOSED: default canonicalizer rethrows a non-ENOENT error (ELOOP) instead of a literal fallback', () => {
-    // A symlink loop makes realpathSync throw ELOOP. The guard must NOT swallow
-    // it as "does not exist yet, keep walking up" and return a literal path —
-    // it must fail closed. (REQ 1: fails CLOSED on any uncertainty.)
-    const root = mkdtempSync(join(tmpdir(), 'claudex-loop-'));
-    try {
-      const a = join(root, 'a');
-      const b = join(root, 'b');
-      symlinkSync(b, a, 'dir'); // a -> b
-      symlinkSync(a, b, 'dir'); // b -> a  (loop)
-      const looped = join(a, 'home'); // canonicalizing this hits ELOOP
-      // No canonicalize dep → the real defaultCanonicalizeIntended runs.
-      expect(() =>
-        assertIsolatedConfigDir(looped, { realClaudeDir: join(root, '.claude') }),
-      ).toThrow();
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  it('FAIL CLOSED: default isSymlink rethrows a non-ENOENT error (ENOTDIR) rather than reporting "not a symlink"', () => {
-    // A candidate whose parent is a regular FILE makes lstat throw ENOTDIR.
-    // The post-create symlink check must fail closed, not treat it as safe.
-    const root = mkdtempSync(join(tmpdir(), 'claudex-notdir-'));
-    try {
-      const file = join(root, 'afile');
-      writeFileSync(file, 'x');
-      const candidate = join(file, 'child'); // parent is a file → ENOTDIR on lstat
-      expect(() =>
-        // Bypass the guard/mkdir side-effects; only the default isSymlink runs live.
-        resolveClaudexConfigDir(
-          { [CLAUDEX_CONFIG_DIR_ENV]: candidate },
-          {
-            realClaudeDir: join(root, '.claude'),
-            canonicalize: idCanon,
-            mkdir: () => {},
-            // isSymlink omitted → real defaultIsSymlink runs on the ENOTDIR path.
-          },
-        ),
-      ).toThrow();
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  it('FAIL CLOSED: an injected canonicalize throwing EACCES is not swallowed', () => {
-    const eacces = Object.assign(new Error('permission denied'), { code: 'EACCES' });
-    expect(() =>
-      resolveClaudexConfigDir(
-        { [CLAUDEX_CONFIG_DIR_ENV]: '/home/agent/custom-claudex' },
-        {
-          realClaudeDir: '/home/agent/.claude',
-          canonicalize: () => {
-            throw eacces;
-          },
-          mkdir: () => {},
-          isSymlink: () => false,
-        },
-      ),
-    ).toThrow(/permission denied/);
-  });
-});
-
-// ─── model-tier map (P3) ──────────────────────────────────────────────────────
-
-describe('resolveClaudexModels', () => {
-  it('defaults primary=sol / smallFast=luna', () => {
-    expect(resolveClaudexModels({})).toEqual({
-      primary: CLAUDEX_DEFAULT_PRIMARY_MODEL,
-      smallFast: CLAUDEX_DEFAULT_SMALL_FAST_MODEL,
-    });
-    expect(CLAUDEX_DEFAULT_PRIMARY_MODEL).toBe('gpt-5.6-sol');
-    expect(CLAUDEX_DEFAULT_SMALL_FAST_MODEL).toBe('gpt-5.6-luna');
-  });
-
-  it('env-provided values WIN over defaults', () => {
-    expect(
-      resolveClaudexModels({ ANTHROPIC_MODEL: 'gpt-x', ANTHROPIC_SMALL_FAST_MODEL: 'gpt-y' }),
-    ).toEqual({ primary: 'gpt-x', smallFast: 'gpt-y' });
-  });
-
-  it('ignores blank env values (falls back to defaults)', () => {
-    expect(
-      resolveClaudexModels({ ANTHROPIC_MODEL: '   ', ANTHROPIC_SMALL_FAST_MODEL: '' }),
-    ).toEqual({
-      primary: CLAUDEX_DEFAULT_PRIMARY_MODEL,
-      smallFast: CLAUDEX_DEFAULT_SMALL_FAST_MODEL,
-    });
-  });
-});
-
-// ─── env injection (HARD SECURITY REQ 2 — zero token leakage) ─────────────────
-
-describe('buildClaudexEnv — zero token leakage', () => {
-  const models = { primary: 'gpt-5.6-sol', smallFast: 'gpt-5.6-luna' };
-  const configDir = '/home/agent/.config/mosaic/claudex/home';
-
-  it('sets only ANTHROPIC_AUTH_TOKEN=unused and points at the loopback proxy', () => {
-    const env = buildClaudexEnv({}, { configDir, models });
-    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
-    expect(env.ANTHROPIC_BASE_URL).toBe(CLAUDEX_PROXY_URL);
-    expect(env.CLAUDE_CONFIG_DIR).toBe(configDir);
-    expect(env.ANTHROPIC_MODEL).toBe('gpt-5.6-sol');
-    expect(env.ANTHROPIC_SMALL_FAST_MODEL).toBe('gpt-5.6-luna');
-  });
-
-  it('OVERWRITES an inherited real auth token with the literal "unused"', () => {
-    const env = buildClaudexEnv(
-      { ANTHROPIC_AUTH_TOKEN: 'sk-ant-realsecret-should-never-flow' },
-      { configDir, models },
-    );
-    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
-  });
-
-  it('DELETES ANTHROPIC_API_KEY so no real Anthropic key reaches the local proxy', () => {
-    const env = buildClaudexEnv(
-      { ANTHROPIC_API_KEY: 'sk-ant-api03-realkey' },
-      { configDir, models },
-    );
-    expect('ANTHROPIC_API_KEY' in env).toBe(false);
-    expect(env.ANTHROPIC_API_KEY).toBeUndefined();
-  });
-
-  it('sweeps the WHOLE credential-bearing env family (token/api-key/secret/oauth), not just two', () => {
-    const env = buildClaudexEnv(
-      {
-        ANTHROPIC_API_KEY: 'sk-ant-api03-leak',
-        CLAUDE_CODE_OAUTH_TOKEN: 'oauth-leak',
-        SOME_SERVICE_TOKEN: 'tok-leak',
-        VENDOR_API_KEY: 'key-leak',
-        DB_SECRET: 'secret-leak',
-        HARMLESS: 'kept',
-        PATH: '/usr/bin',
-      },
-      { configDir, models },
-    );
-    expect(env.ANTHROPIC_API_KEY).toBeUndefined();
-    expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBeUndefined();
-    expect(env.SOME_SERVICE_TOKEN).toBeUndefined();
-    expect(env.VENDOR_API_KEY).toBeUndefined();
-    expect(env.DB_SECRET).toBeUndefined();
-    // Non-credential vars the harness needs are preserved.
-    expect(env.HARMLESS).toBe('kept');
-    expect(env.PATH).toBe('/usr/bin');
-  });
-
-  it('neutralizes Bedrock/Vertex provider switches so Claude cannot bypass the proxy (REQ 2)', () => {
-    // CLAUDE_CODE_USE_BEDROCK / _USE_VERTEX are ROUTING switches: their mere
-    // presence makes Claude Code route to AWS Bedrock / GCP Vertex against the
-    // ambient cloud credential chain — reaching the real Anthropic API and
-    // bypassing ANTHROPIC_BASE_URL (the loopback proxy) entirely. They MUST be
-    // gone from the composed env regardless of the launching env.
-    const env = buildClaudexEnv(
-      {
-        CLAUDE_CODE_USE_BEDROCK: '1',
-        CLAUDE_CODE_USE_VERTEX: '1',
-        CLAUDE_CODE_SKIP_BEDROCK_AUTH: '1',
-        CLAUDE_CODE_SKIP_VERTEX_AUTH: '1',
-        AWS_ACCESS_KEY_ID: 'AKIAREAL',
-        AWS_SECRET_ACCESS_KEY: 'realsecret',
-        AWS_SESSION_TOKEN: 'realsession',
-        AWS_BEARER_TOKEN_BEDROCK: 'bearer-bedrock-real',
-        AWS_REGION: 'us-east-1',
-        GOOGLE_APPLICATION_CREDENTIALS: '/home/agent/gcp.json',
-        GOOGLE_CLOUD_ACCESS_TOKEN: 'gcp-token-real',
-        PATH: '/usr/bin',
-      },
-      { configDir, models },
-    );
-    // Routing switches gone by construction.
-    expect('CLAUDE_CODE_USE_BEDROCK' in env).toBe(false);
-    expect('CLAUDE_CODE_USE_VERTEX' in env).toBe(false);
-    expect('CLAUDE_CODE_SKIP_BEDROCK_AUTH' in env).toBe(false);
-    expect('CLAUDE_CODE_SKIP_VERTEX_AUTH' in env).toBe(false);
-    // Cloud credentials swept — none of the Claude-capable creds survive.
-    expect(env.AWS_ACCESS_KEY_ID).toBeUndefined();
-    expect(env.AWS_SECRET_ACCESS_KEY).toBeUndefined();
-    expect(env.AWS_SESSION_TOKEN).toBeUndefined();
-    expect(env.AWS_BEARER_TOKEN_BEDROCK).toBeUndefined();
-    expect(env.AWS_REGION).toBeUndefined();
-    expect(env.GOOGLE_APPLICATION_CREDENTIALS).toBeUndefined();
-    expect(env.GOOGLE_CLOUD_ACCESS_TOKEN).toBeUndefined();
-    // The proxy routing is still the only path.
-    expect(env.ANTHROPIC_BASE_URL).toBe(CLAUDEX_PROXY_URL);
-    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
-    expect(env.PATH).toBe('/usr/bin');
-  });
-
-  it('closes the mid-string _KEY / _SECRET gap (STRIPE_SECRET_KEY, SSH_PRIVATE_KEY)', () => {
-    const env = buildClaudexEnv(
-      {
-        STRIPE_SECRET_KEY: 'sk-live-real',
-        SSH_PRIVATE_KEY: '-----BEGIN OPENSSH PRIVATE KEY-----',
-        HARMLESS: 'kept',
-      },
-      { configDir, models },
-    );
-    expect(env.STRIPE_SECRET_KEY).toBeUndefined();
-    expect(env.SSH_PRIVATE_KEY).toBeUndefined();
-    expect(env.HARMLESS).toBe('kept');
-  });
-
-  it('no credential-NAMED key in the composed env carries a real-looking value', () => {
-    const env = buildClaudexEnv(
-      {
-        ANTHROPIC_API_KEY: 'sk-ant-api03-leak',
-        ANTHROPIC_AUTH_TOKEN: 'access_token_leak',
-        SOME_JWT_TOKEN: 'eyJhbGciOiJIUzI1NiJ9.payload.sig',
-        REFRESH_SECRET: 'refresh_token_value',
-      },
-      { configDir, models },
-    );
-    for (const [name, value] of Object.entries(env)) {
-      if (CLAUDEX_CREDENTIAL_ENV_RE.test(name)) {
-        // Any surviving credential-named var must carry only a safe sentinel value.
-        expect(value).not.toMatch(/sk-(ant|proj)-/);
-        expect(value).not.toMatch(/access_token|refresh_token/);
-        expect(value).not.toMatch(/eyJ[A-Za-z0-9_-]+\./); // JWT
-      }
-    }
-  });
-
-  it('honors a caller-provided baseUrl override (loopback default otherwise)', () => {
-    const env = buildClaudexEnv({}, { configDir, models, baseUrl: 'http://127.0.0.1:9999' });
-    expect(env.ANTHROPIC_BASE_URL).toBe('http://127.0.0.1:9999');
-  });
-
-  it('returns a fresh object without mutating the base env', () => {
-    const base = { EXISTING: 'kept' };
-    const env = buildClaudexEnv(base, { configDir, models });
-    expect(env.EXISTING).toBe('kept');
-    expect(base).not.toHaveProperty('ANTHROPIC_AUTH_TOKEN');
-  });
-});
-
-// ─── EXPERIMENTAL classification (P4) ─────────────────────────────────────────
-
-describe('buildClaudexBanner / buildClaudexContractNote', () => {
-  const models = { primary: 'gpt-5.6-sol', smallFast: 'gpt-5.6-luna' };
-
-  it('banner marks EXPERIMENTAL and names the models + proxy', () => {
-    const banner = buildClaudexBanner(models);
-    expect(banner).toMatch(/EXPERIMENTAL/);
-    expect(banner).toMatch(/gpt-5\.6-sol/);
-    expect(banner).toMatch(/gpt-5\.6-luna/);
-    expect(banner).toMatch(/claude-code-proxy/);
-    expect(banner).not.toMatch(/unused/); // no token material in the banner
-  });
-
-  it('contract note classifies the runtime as EXPERIMENTAL GPT-via-proxy', () => {
-    const note = buildClaudexContractNote(models);
-    expect(note).toMatch(/EXPERIMENTAL/);
-    expect(note).toMatch(/gpt-5\.6-sol/);
-    expect(note).toMatch(/not.*Anthropic/i);
-  });
-});
-
-// ─── proxy gate ───────────────────────────────────────────────────────────────
-
-describe('runClaudexProxyGate', () => {
-  it('is ok when the first preflight already passes', async () => {
-    const preflight = vi.fn().mockResolvedValue(makeReport());
-    const ensureProxy = vi.fn();
-    const reauth = vi.fn();
-    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth });
-    expect(gate.ok).toBe(true);
-    expect(ensureProxy).not.toHaveBeenCalled();
-    expect(reauth).not.toHaveBeenCalled();
-  });
-
-  it('fails fast when the binary is missing (no reauth, no start)', async () => {
-    const preflight = vi
-      .fn()
-      .mockResolvedValue(
-        makeReport({ binaryPresent: false, ok: false, problems: ['binary not found'] }),
-      );
-    const ensureProxy = vi.fn();
-    const reauth = vi.fn();
-    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth });
-    expect(gate.ok).toBe(false);
-    expect(reauth).not.toHaveBeenCalled();
-    expect(ensureProxy).not.toHaveBeenCalled();
-  });
-
-  it('runs device reauth then re-preflights when OAuth needs it', async () => {
-    const preflight = vi
-      .fn()
-      .mockResolvedValueOnce(
-        makeReport({
-          auth: { state: 'expired' },
-          needsReauth: true,
-          ok: false,
-          problems: ['expired'],
-        }),
-      )
-      .mockResolvedValueOnce(makeReport());
-    const reauth = vi.fn().mockReturnValue(0);
-    const gate = await runClaudexProxyGate({ preflight, reauth, ensureProxy: vi.fn() });
-    expect(reauth).toHaveBeenCalledTimes(1);
-    expect(preflight).toHaveBeenCalledTimes(2);
-    expect(gate.ok).toBe(true);
-  });
-
-  it('does NOT reauth when auth is already valid', async () => {
-    const preflight = vi.fn().mockResolvedValue(makeReport());
-    const reauth = vi.fn();
-    await runClaudexProxyGate({ preflight, reauth, ensureProxy: vi.fn() });
-    expect(reauth).not.toHaveBeenCalled();
-  });
-
-  it('aborts when device reauth fails', async () => {
-    const preflight = vi.fn().mockResolvedValue(
-      makeReport({
-        auth: { state: 'unauthenticated' },
-        needsReauth: true,
-        ok: false,
-        problems: ['unauth'],
-      }),
-    );
-    const reauth = vi.fn().mockReturnValue(1);
-    const gate = await runClaudexProxyGate({ preflight, reauth, ensureProxy: vi.fn() });
-    expect(gate.ok).toBe(false);
-    expect(gate.problems.join(' ')).toMatch(/re-auth/i);
-  });
-
-  it('starts the proxy then re-preflights when nothing is live', async () => {
-    const preflight = vi
-      .fn()
-      .mockResolvedValueOnce(
-        makeReport({ live: false, listenerVerdict: 'unknown', ok: false, problems: ['dead'] }),
-      )
-      .mockResolvedValueOnce(makeReport());
-    const ensureProxy = vi.fn().mockResolvedValue({ live: true, method: 'systemd' });
-    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth: vi.fn() });
-    expect(ensureProxy).toHaveBeenCalledTimes(1);
-    expect(gate.ok).toBe(true);
-  });
-
-  it('aborts (non-sensitive) when the proxy cannot come up trusted', async () => {
-    const preflight = vi
-      .fn()
-      .mockResolvedValue(
-        makeReport({ live: false, listenerVerdict: 'unknown', ok: false, problems: ['dead'] }),
-      );
-    const ensureProxy = vi.fn().mockResolvedValue({ live: false, method: 'untrusted' });
-    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth: vi.fn() });
-    expect(gate.ok).toBe(false);
-    expect(gate.problems.join(' ')).toMatch(/untrusted/);
-    // Non-sensitive: no token material in surfaced problems.
-    expect(gate.problems.join(' ')).not.toMatch(/access_token|refresh_token|sk-/);
-  });
-});
-
-// ─── launch orchestration (fail-closed ordering) ──────────────────────────────
-
-describe('launchClaudex', () => {
-  const baseDeps = {
-    baseEnv: {},
-    proxyGate: () => Promise.resolve({ ok: true, report: makeReport(), problems: [] }),
-    resolveConfigDir: () => '/home/agent/.config/mosaic/claudex/home',
-    log: () => {},
-    errorLog: () => {},
-    fail: (() => {
-      throw new Error('exit');
-    }) as (code: number) => never,
-  };
-
-  it('yolo=true passes --dangerously-skip-permissions + injected env to claude', async () => {
-    const exec = vi.fn();
-    await launchClaudex(['--print', 'hi'], true, okAdapter({ exec }), baseDeps);
-    expect(exec).toHaveBeenCalledTimes(1);
-    const [cmd, args, env] = exec.mock.calls[0]!;
-    expect(cmd).toBe('claude');
-    expect(args[0]).toBe('--dangerously-skip-permissions');
-    expect(args).toContain('--append-system-prompt');
-    expect(args).toContain('--print');
-    expect(args).toContain('hi');
-    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
-    expect(env.ANTHROPIC_BASE_URL).toBe(CLAUDEX_PROXY_URL);
-    expect(env.CLAUDE_CONFIG_DIR).toBe('/home/agent/.config/mosaic/claudex/home');
-    expect(env.ANTHROPIC_MODEL).toBe('gpt-5.6-sol');
-  });
-
-  it('non-yolo omits --dangerously-skip-permissions but still injects the proxy env', async () => {
-    const exec = vi.fn();
-    await launchClaudex([], false, okAdapter({ exec }), baseDeps);
-    const [, args, env] = exec.mock.calls[0]!;
-    expect(args).not.toContain('--dangerously-skip-permissions');
-    expect(args[0]).toBe('--append-system-prompt');
-    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
-  });
-
-  it('appends the EXPERIMENTAL contract note to the composed prompt', async () => {
-    const exec = vi.fn();
-    await launchClaudex([], true, okAdapter({ exec, composePrompt: () => '# BASE' }), baseDeps);
-    const args = exec.mock.calls[0]![1] as string[];
-    const promptIdx = args.indexOf('--append-system-prompt') + 1;
-    expect(args[promptIdx]).toContain('# BASE');
-    expect(args[promptIdx]).toMatch(/EXPERIMENTAL/);
-  });
-
-  it('runs the harness preflight BEFORE the proxy gate and exec', async () => {
-    const order: string[] = [];
-    const adapter = okAdapter({
-      harnessPreflight: () => order.push('preflight'),
-      exec: () => order.push('exec'),
-    });
-    await launchClaudex([], true, adapter, {
-      ...baseDeps,
-      proxyGate: () => {
-        order.push('gate');
-        return Promise.resolve({ ok: true, report: makeReport(), problems: [] });
-      },
-    });
-    expect(order).toEqual(['preflight', 'gate', 'exec']);
-  });
-
-  it('FAIL CLOSED: exits WITHOUT exec when the proxy gate fails', async () => {
-    const exec = vi.fn();
-    const errors: string[] = [];
-    await expect(
-      launchClaudex([], true, okAdapter({ exec }), {
-        ...baseDeps,
-        proxyGate: () =>
-          Promise.resolve({ ok: false, report: makeReport({ ok: false }), problems: ['no proxy'] }),
-        errorLog: (m: string) => errors.push(m),
-      }),
-    ).rejects.toThrow('exit');
-    expect(exec).not.toHaveBeenCalled();
-    expect(errors.join('\n')).toMatch(/no proxy/);
-  });
-
-  it('FAIL CLOSED: exits WITHOUT exec when the config-dir guard throws', async () => {
-    const exec = vi.fn();
-    await expect(
-      launchClaudex([], true, okAdapter({ exec }), {
-        ...baseDeps,
-        resolveConfigDir: () => {
-          throw new Error('refusing to use ~/.claude');
-        },
-      }),
-    ).rejects.toThrow('exit');
-    expect(exec).not.toHaveBeenCalled();
-  });
-
-  it('FAIL CLOSED: reports a non-Error throw via String() and still aborts', async () => {
-    const exec = vi.fn();
-    const errors: string[] = [];
-    await expect(
-      launchClaudex([], true, okAdapter({ exec }), {
-        ...baseDeps,
-        resolveConfigDir: () => {
-          // A non-Error throw exercises the String(err) branch of the catch.
-          throw { toString: () => 'string-shaped failure' };
-        },
-        errorLog: (m: string) => errors.push(m),
-      }),
-    ).rejects.toThrow('exit');
-    expect(exec).not.toHaveBeenCalled();
-    expect(errors.join('\n')).toMatch(/string-shaped failure/);
-  });
-});
-
-// ─── production DI defaults (fallback-branch coverage; no real proxy touched) ──
-
-describe('production dependency defaults', () => {
-  it('assertIsolatedConfigDir defaults realClaudeDir to ~/.claude', () => {
-    const safe = join(tmpdir(), 'mosaic-claudex-default-real', 'home');
-    // Only canonicalize injected; realClaudeDir falls back to ~/.claude.
-    expect(assertIsolatedConfigDir(safe, { canonicalize: idCanon })).toBe(safe);
-  });
-
-  it('assertIsolatedConfigDir default canonicalizer resolves a non-existent path', () => {
-    // No canonicalize dep → exercises the real realpath-longest-ancestor walk
-    // (including the not-yet-existing tail), on a path safely outside ~/.claude.
-    const safe = join(tmpdir(), 'mosaic-claudex-canon', 'nested', 'home');
-    expect(assertIsolatedConfigDir(safe)).toContain('mosaic-claudex-canon');
-  });
-
-  it('resolveClaudexConfigDir defaults mosaicHome when not injected', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'claudex-cfg-'));
-    try {
-      const target = join(dir, 'home');
-      // Override env points elsewhere; mosaicHome dep omitted → MOSAIC_HOME default path is exercised.
-      const out = resolveClaudexConfigDir(
-        { [CLAUDEX_CONFIG_DIR_ENV]: target },
-        { canonicalize: idCanon },
-      );
-      expect(out).toBe(target);
-      expect(lstatSync(target).isDirectory()).toBe(true);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('runClaudexProxyGate defaults ensureProxy/reauth/log without invoking them on a missing binary', async () => {
-    // Only preflight injected; binary missing → returns before the default
-    // ensureProxy/reauth thunks could ever reach the real proxy.
-    const preflight = vi
-      .fn()
-      .mockResolvedValue(makeReport({ binaryPresent: false, ok: false, problems: ['missing'] }));
-    const gate = await runClaudexProxyGate({ preflight });
-    expect(gate.ok).toBe(false);
-  });
-
-  it('launchClaudex defaults log/errorLog/fail/baseEnv/models/buildEnv on the success path', async () => {
-    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    try {
-      const exec = vi.fn();
-      // Inject only the boundaries that would touch the real proxy/FS; let the
-      // rest default. Success path never calls fail/errorLog.
-      await launchClaudex([], true, okAdapter({ exec }), {
-        proxyGate: () => Promise.resolve({ ok: true, report: makeReport(), problems: [] }),
-        resolveConfigDir: () => join(tmpdir(), 'claudex-default-launch'),
-      });
-      expect(exec).toHaveBeenCalledTimes(1);
-      const [, , env] = exec.mock.calls[0]!;
-      expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
-      expect(env.ANTHROPIC_MODEL).toBe(CLAUDEX_DEFAULT_PRIMARY_MODEL);
-    } finally {
-      logSpy.mockRestore();
-    }
-  });
-});

packages/mosaic/src/commands/claudex.ts

@@ -1,464 +0,0 @@
-/**
- * Claudex launch composition (P2–P4 of `mosaic yolo claudex`).
- *
- * Builds the isolated launch environment for running GPT models inside the
- * Claude Code harness via `raine/claude-code-proxy` (ChatGPT-subscription OAuth).
- * PR-1 (`claudex-proxy.ts`) owns the proxy preflight/lifecycle; this module owns
- * the *composition* the launcher hands to Claude Code:
- *
- *   P2  isolated CLAUDE_CONFIG_DIR (provably never the real ~/.claude) + env
- *       injection that leaks ZERO token material;
- *   P3  the model-tier map (primary → gpt-5.6-sol, small/fast → gpt-5.6-luna,
- *       operator env values win);
- *   P4  the EXPERIMENTAL classification banner + composed-contract note.
- *
- * Two hard security invariants (secrev-enforced):
- *   REQ 1 — Provable isolation. {@link assertIsolatedConfigDir} makes the
- *           CLAUDE_CONFIG_DIR seam incapable of resolving to `~/.claude` (or any
- *           descendant of it); it canonicalizes both sides, rejects descendants,
- *           and — after ensuring the dir — re-checks and rejects a symlinked
- *           target (TOCTOU). Fails CLOSED on any uncertainty.
- *   REQ 2 — Zero token leakage. This module never reads the proxy's
- *           `auth.json`; {@link buildClaudexEnv} strips the ENTIRE
- *           credential-bearing env family and hands Claude Code only
- *           `ANTHROPIC_AUTH_TOKEN=unused`. The proxy holds the real credential.
- *
- * Every side-effecting boundary is dependency-injected so the launch path is
- * unit-testable without spawning Claude Code or touching a real config dir.
- */
-
-import { lstatSync, mkdirSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import {
-  CLAUDEX_PROXY_URL,
-  ensureProxyRunning,
-  runDeviceReauth,
-  runProxyPreflight,
-  type EnsureProxyResult,
-  type PreflightReport,
-} from './claudex-proxy.js';
-
-const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
-
-// ─── Isolated CLAUDE_CONFIG_DIR (HARD SECURITY REQ 1) ─────────────────────────
-
-/** Dedicated override env for the isolated config dir. The ambient
- * `CLAUDE_CONFIG_DIR` is deliberately NOT honored — it may already point at the
- * real `~/.claude` of the launching session. */
-export const CLAUDEX_CONFIG_DIR_ENV = 'MOSAIC_CLAUDEX_CONFIG_DIR';
-
-/** The default isolated config dir — structurally under the mosaic home, so it
- * can never equal `~/.claude`. */
-export function defaultClaudexConfigDir(mosaicHome: string = MOSAIC_HOME): string {
-  return join(mosaicHome, 'claudex', 'home');
-}
-
-export interface ConfigDirDeps {
-  /** The real Claude state dir to protect (default `~/.claude`). */
-  realClaudeDir?: string;
-  /** Resolve a path to canonical form, resolving symlinks on the longest
-   * existing ancestor (so a not-yet-created dir still canonicalizes). */
-  canonicalize?: (p: string) => string;
-  /** Ensure the isolated dir exists (mkdir -p, owner-only 0700). */
-  mkdir?: (p: string) => void;
-  /** Whether a path is itself a symlink (lstat). */
-  isSymlink?: (p: string) => boolean;
-}
-
-/** Resolve a path to canonical form, resolving symlinks on the LONGEST EXISTING
- * ancestor and re-appending the not-yet-existing tail. A symlinked ancestor that
- * points into `~/.claude` is therefore caught even before the leaf exists. */
-function defaultCanonicalizeIntended(p: string): string {
-  const abs = resolve(p);
-  let existing = abs;
-  const tail: string[] = [];
-  // Walk up until we hit an existing ancestor (or the filesystem root).
-  for (;;) {
-    try {
-      const real = realpathSync(existing);
-      return tail.length > 0 ? join(real, ...tail) : real;
-    } catch (err) {
-      // ONLY a genuine "does not exist yet" (ENOENT) justifies walking up to an
-      // existing ancestor. Any other errno (ELOOP, EACCES, ENOTDIR, …) means we
-      // cannot establish the canonical form — fail CLOSED rather than fall back
-      // to a possibly-wrong literal path.
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
-      const parent = dirname(existing);
-      if (parent === existing) return abs; // reached root without an existing prefix
-      tail.unshift(existing.slice(parent.length + 1));
-      existing = parent;
-    }
-  }
-}
-
-function defaultMkdir(p: string): void {
-  mkdirSync(p, { recursive: true, mode: 0o700 });
-}
-
-function defaultIsSymlink(p: string): boolean {
-  try {
-    return lstatSync(p).isSymbolicLink();
-  } catch (err) {
-    // A missing path is genuinely "not a symlink"; anything else (EACCES, ELOOP,
-    // ENOTDIR, …) is uncertainty the guard must not swallow — fail CLOSED.
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return false;
-    throw err;
-  }
-}
-
-/** True when `child` is `parent` itself or a descendant of it (path-wise). */
-function isWithin(child: string, parent: string): boolean {
-  if (child === parent) return true;
-  const rel = relative(parent, child);
-  return rel.length > 0 && !rel.startsWith('..') && !isAbsolute(rel);
-}
-
-/**
- * Guard: prove that `candidate` is a legitimate ISOLATED config dir and can
- * never be, resolve to, or live under the real `~/.claude`. Canonicalizes BOTH
- * sides (either may be a symlink), rejects `~/.claude` and any descendant, and
- * fails CLOSED (throws) on an empty/relative candidate. Returns the canonical
- * isolated path on success.
- */
-export function assertIsolatedConfigDir(candidate: string, deps: ConfigDirDeps = {}): string {
-  const canonicalize = deps.canonicalize ?? defaultCanonicalizeIntended;
-  const realClaudeDir = deps.realClaudeDir ?? join(homedir(), '.claude');
-
-  if (typeof candidate !== 'string' || candidate.trim() === '') {
-    throw new Error('claudex: isolated CLAUDE_CONFIG_DIR must be a non-empty path (fail closed).');
-  }
-  if (!isAbsolute(candidate)) {
-    throw new Error(
-      `claudex: isolated CLAUDE_CONFIG_DIR must be an absolute path: ${JSON.stringify(candidate)}`,
-    );
-  }
-
-  const canonCandidate = canonicalize(candidate);
-  const canonReal = canonicalize(realClaudeDir);
-
-  // Compare canonical forms AND raw resolved forms — belt and suspenders so a
-  // canonicalizer that no-ops on a nonexistent real dir still catches the literal.
-  if (isWithin(canonCandidate, canonReal) || isWithin(resolve(candidate), resolve(realClaudeDir))) {
-    throw new Error(
-      `claudex: refusing to use the real Claude config dir (or a descendant of it) as the ` +
-        `isolated CLAUDE_CONFIG_DIR. Resolved to ${JSON.stringify(canonCandidate)}.`,
-    );
-  }
-
-  return canonCandidate;
-}
-
-/**
- * Resolve the isolated CLAUDE_CONFIG_DIR: pick the dedicated override or the
- * namespaced default, run the pre-create guard, ensure the dir (0700), then
- * RE-CHECK after creation — reject a symlinked target and re-run the guard on
- * the now-existing (fully canonicalizable) path. This closes the pre-created
- * symlink race (TOCTOU). Every failure throws (fail closed).
- */
-export function resolveClaudexConfigDir(
-  env: NodeJS.ProcessEnv = process.env,
-  deps: ConfigDirDeps & { mosaicHome?: string } = {},
-): string {
-  const mosaicHome = deps.mosaicHome ?? MOSAIC_HOME;
-  const mkdir = deps.mkdir ?? defaultMkdir;
-  const isSymlink = deps.isSymlink ?? defaultIsSymlink;
-
-  const override = env[CLAUDEX_CONFIG_DIR_ENV]?.trim();
-  const candidate =
-    override && override.length > 0 ? override : defaultClaudexConfigDir(mosaicHome);
-
-  // Pre-create guard (before touching the filesystem).
-  assertIsolatedConfigDir(candidate, deps);
-
-  // Ensure the dir, then re-verify against the post-create reality.
-  mkdir(candidate);
-  if (isSymlink(candidate)) {
-    throw new Error(
-      'claudex: refusing to use the isolated CLAUDE_CONFIG_DIR — the target is a symlink ' +
-        '(possible pre-created race). Fail closed.',
-    );
-  }
-  // Re-run the guard now that the leaf exists so canonicalization reflects any
-  // symlinked ancestor introduced between the pre-check and mkdir.
-  return assertIsolatedConfigDir(candidate, deps);
-}
-
-// ─── Model-tier map (P3) ──────────────────────────────────────────────────────
-
-export const CLAUDEX_DEFAULT_PRIMARY_MODEL = 'gpt-5.6-sol';
-export const CLAUDEX_DEFAULT_SMALL_FAST_MODEL = 'gpt-5.6-luna';
-
-export interface ClaudexModels {
-  /** Primary tier (opus/sonnet) → ANTHROPIC_MODEL. */
-  primary: string;
-  /** Small/fast tier (haiku) → ANTHROPIC_SMALL_FAST_MODEL. */
-  smallFast: string;
-}
-
-/** Resolve the model-tier map. Operator-provided env values WIN over defaults;
- * blank values fall back to the defaults. */
-export function resolveClaudexModels(env: NodeJS.ProcessEnv = process.env): ClaudexModels {
-  const primary = env['ANTHROPIC_MODEL']?.trim() || CLAUDEX_DEFAULT_PRIMARY_MODEL;
-  const smallFast = env['ANTHROPIC_SMALL_FAST_MODEL']?.trim() || CLAUDEX_DEFAULT_SMALL_FAST_MODEL;
-  return { primary, smallFast };
-}
-
-// ─── Env injection (HARD SECURITY REQ 2 — zero token leakage) ─────────────────
-
-/**
- * Names of env vars considered credential-bearing. The whole family is stripped
- * from the composed env so no real Anthropic key, OAuth token, or third-party /
- * cloud credential can reach the local proxy or be used by Claude Code to bypass
- * it. We then re-add ONLY the safe claudex vars (`ANTHROPIC_MODEL`,
- * `_SMALL_FAST_MODEL`, `_BASE_URL`, `_AUTH_TOKEN=unused`). A name-pattern sweep
- * can't miss a specific var a short denylist forgot, while still preserving the
- * arbitrary non-credential env the harness/MCP/hooks require (PATH, HOME, XDG,
- * terminal, proxies, …), which a strict allowlist would fragilely drop.
- *
- * The cloud-provider families (`AWS_*`, `GOOGLE_APPLICATION_CREDENTIALS`,
- * `GOOGLE_CLOUD_*`, `GCP_*`) are included because Claude Code can route to the
- * real Anthropic API via AWS Bedrock / GCP Vertex using the ambient cloud
- * credential chain — a Claude-capable credential that must never survive into a
- * claudex launch. `_KEY$` / `_SECRET` (not just the `_API_KEY$` tail) close the
- * mid-string gap (`STRIPE_SECRET_KEY`, `SSH_PRIVATE_KEY`, `AWS_SECRET_ACCESS_KEY`).
- */
-export const CLAUDEX_CREDENTIAL_ENV_RE =
-  /^ANTHROPIC_|^CLAUDE_CODE_OAUTH|^AWS_|^GOOGLE_APPLICATION_CREDENTIALS$|^GOOGLE_CLOUD_|^GCP_|_API_?KEY$|_KEY$|_TOKEN$|_SECRET/i;
-
-/**
- * Provider ROUTING switches whose mere PRESENCE (independent of any credential)
- * makes Claude Code bypass `ANTHROPIC_BASE_URL` (the loopback proxy) and talk to
- * the real Anthropic API via Bedrock/Vertex. A name-pattern is the wrong model
- * for a boolean switch, so these are force-deleted by exact name — REGARDLESS of
- * value — after the credential sweep. (REQ 2: isolation must hold for any
- * launching env, including a Bedrock/Vertex-configured enterprise host.)
- */
-export const CLAUDEX_FORCED_UNSET_ENV = [
-  'CLAUDE_CODE_USE_BEDROCK',
-  'CLAUDE_CODE_USE_VERTEX',
-  'CLAUDE_CODE_SKIP_BEDROCK_AUTH',
-  'CLAUDE_CODE_SKIP_VERTEX_AUTH',
-] as const;
-
-export interface BuildClaudexEnvOptions {
-  configDir: string;
-  models: ClaudexModels;
-  /** Override the proxy base URL (defaults to the PR-1 loopback constant). */
-  baseUrl?: string;
-}
-
-/**
- * Compose the launch env for Claude Code. Returns a FRESH object (never mutates
- * the base env). Strips the entire credential-bearing family AND force-deletes
- * the Bedrock/Vertex routing switches (REQ 2), then sets the isolated config dir
- * and the proxy routing. Claude Code sees only `ANTHROPIC_AUTH_TOKEN=unused`
- * pointed at the loopback proxy; the proxy holds the real OAuth credential, which
- * this module never reads.
- */
-export function buildClaudexEnv(
-  baseEnv: NodeJS.ProcessEnv,
-  opts: BuildClaudexEnvOptions,
-): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = {};
-  for (const [name, value] of Object.entries(baseEnv)) {
-    if (CLAUDEX_CREDENTIAL_ENV_RE.test(name)) continue; // drop the whole credential family
-    env[name] = value;
-  }
-
-  // Force-delete routing switches by exact name — their presence (not their
-  // value) is what would route Claude Code off the proxy to the real API.
-  for (const name of CLAUDEX_FORCED_UNSET_ENV) delete env[name];
-
-  env['CLAUDE_CONFIG_DIR'] = opts.configDir;
-  env['ANTHROPIC_BASE_URL'] = opts.baseUrl ?? CLAUDEX_PROXY_URL;
-  env['ANTHROPIC_AUTH_TOKEN'] = 'unused';
-  env['ANTHROPIC_MODEL'] = opts.models.primary;
-  env['ANTHROPIC_SMALL_FAST_MODEL'] = opts.models.smallFast;
-  return env;
-}
-
-// ─── EXPERIMENTAL classification (P4) ─────────────────────────────────────────
-
-/** Console banner shown at launch. Contains no token material by construction. */
-export function buildClaudexBanner(models: ClaudexModels): string {
-  return [
-    '',
-    '  ┌─────────────────────────────────────────────────────────────────────┐',
-    '  │  ⚠  EXPERIMENTAL — mosaic claudex                                     │',
-    '  └─────────────────────────────────────────────────────────────────────┘',
-    `  Running GPT models inside the Claude Code harness via claude-code-proxy`,
-    `  (ChatGPT-subscription OAuth). This is NOT Anthropic Claude.`,
-    `    primary    : ${models.primary}`,
-    `    small/fast : ${models.smallFast}`,
-    `  Model behavior, tool use, and output quality may differ from Claude.`,
-    '',
-  ].join('\n');
-}
-
-/** Markdown note appended to the composed runtime contract so the model itself
- * knows it is running the EXPERIMENTAL GPT-via-proxy configuration. */
-export function buildClaudexContractNote(models: ClaudexModels): string {
-  return [
-    '# EXPERIMENTAL Runtime — claudex (GPT via claude-code-proxy)',
-    '',
-    'You are running in Mosaic **claudex** mode: the Claude Code harness is wired to',
-    'GPT models through a local `claude-code-proxy` (ChatGPT-subscription OAuth). This',
-    "runtime is NOT Anthropic's Claude API and is not Claude.",
-    '',
-    `- Primary model: \`${models.primary}\``,
-    `- Small/fast model: \`${models.smallFast}\``,
-    '',
-    'Some Claude-specific harness assumptions may not hold under GPT models — verify',
-    'tool output carefully. This classification is EXPERIMENTAL and is not intended for',
-    'production delivery without explicit operator sign-off.',
-  ].join('\n');
-}
-
-// ─── Proxy gate ───────────────────────────────────────────────────────────────
-
-export interface ProxyGateResult {
-  ok: boolean;
-  report: PreflightReport;
-  /** Non-sensitive problems suitable for surfacing to the operator. */
-  problems: string[];
-}
-
-export interface ProxyGateDeps {
-  preflight?: () => Promise<PreflightReport>;
-  ensureProxy?: () => Promise<EnsureProxyResult>;
-  reauth?: () => number;
-  log?: (message: string) => void;
-}
-
-/**
- * Run the proxy readiness gate: preflight → (device reauth if OAuth needs it) →
- * (start the proxy if nothing trusted is live) → re-preflight. Returns `ok` only
- * when the final preflight passes (binary present, OAuth valid, a TRUSTED-live
- * listener — identity verified by PR-1's `verifyListenerIdentity`). All surfaced
- * problems are non-sensitive (port + verdict only; never a token).
- */
-export async function runClaudexProxyGate(deps: ProxyGateDeps = {}): Promise<ProxyGateResult> {
-  const preflight = deps.preflight ?? (() => runProxyPreflight());
-  const ensureProxy = deps.ensureProxy ?? (() => ensureProxyRunning());
-  const reauth = deps.reauth ?? (() => runDeviceReauth());
-  const log = deps.log ?? (() => {});
-
-  let report = await preflight();
-
-  // A missing binary is unrecoverable here — don't attempt reauth or a start.
-  if (!report.binaryPresent) {
-    return { ok: false, report, problems: report.problems };
-  }
-
-  if (report.needsReauth) {
-    log('claudex: claude-code-proxy OAuth needs re-authentication — starting device flow…');
-    const code = reauth();
-    if (code !== 0) {
-      return {
-        ok: false,
-        report,
-        problems: [...report.problems, 'claudex: device re-authentication did not complete.'],
-      };
-    }
-    report = await preflight();
-  }
-
-  if (!report.live) {
-    log('claudex: no trusted claude-code-proxy responding — starting it…');
-    const started = await ensureProxy();
-    if (!started.live) {
-      return {
-        ok: false,
-        report,
-        problems: [
-          ...report.problems,
-          `claudex: could not bring up a trusted claude-code-proxy (${started.method}).`,
-        ],
-      };
-    }
-    report = await preflight();
-  }
-
-  return { ok: report.ok, report, problems: report.problems };
-}
-
-// ─── Launch orchestration ─────────────────────────────────────────────────────
-
-/**
- * The launch.ts-provided seam. Keeps `claudex.ts` free of a circular import back
- * into `launch.ts` while letting the orchestration reuse the harness preflight,
- * the composed runtime contract, and the process-replacing exec.
- */
-export interface ClaudexHarnessAdapter {
-  /** Runs the Claude-harness preflight (mosaic home, SOUL, `claude` on PATH,
-   * sequential-thinking). May terminate the process on a hard failure. */
-  harnessPreflight: () => void;
-  /** Compose the full Claude runtime contract (== `composeContract('claude')`). */
-  composePrompt: () => string;
-  /** Replace the current process with `claude` using the composed env. */
-  exec: (cmd: string, args: string[], env: NodeJS.ProcessEnv) => void;
-}
-
-export interface LaunchClaudexDeps {
-  baseEnv?: NodeJS.ProcessEnv;
-  proxyGate?: () => Promise<ProxyGateResult>;
-  resolveConfigDir?: () => string;
-  models?: () => ClaudexModels;
-  buildEnv?: (base: NodeJS.ProcessEnv, opts: BuildClaudexEnvOptions) => NodeJS.ProcessEnv;
-  log?: (message: string) => void;
-  errorLog?: (message: string) => void;
-  fail?: (code: number) => never;
-}
-
-/**
- * Orchestrate a `mosaic [yolo] claudex` launch. Runs the harness preflight, the
- * proxy gate, composes the isolated env (REQ 1 + REQ 2), appends the EXPERIMENTAL
- * note, and exec's Claude Code. FAIL CLOSED: on any gate failure or guard throw
- * it reports non-sensitive detail and exits WITHOUT reaching exec.
- */
-export async function launchClaudex(
-  args: string[],
-  yolo: boolean,
-  adapter: ClaudexHarnessAdapter,
-  deps: LaunchClaudexDeps = {},
-): Promise<void> {
-  const log = deps.log ?? ((m: string) => console.log(m));
-  const errorLog = deps.errorLog ?? ((m: string) => console.error(m));
-  const fail = deps.fail ?? ((code: number) => process.exit(code));
-  const baseEnv = deps.baseEnv ?? process.env;
-  const proxyGate = deps.proxyGate ?? (() => runClaudexProxyGate({ log }));
-  const resolveConfigDir = deps.resolveConfigDir ?? (() => resolveClaudexConfigDir(baseEnv));
-  const models = deps.models ?? (() => resolveClaudexModels(baseEnv));
-  const buildEnv = deps.buildEnv ?? buildClaudexEnv;
-
-  try {
-    // Harness readiness first (claude on PATH, mosaic home, sequential-thinking).
-    adapter.harnessPreflight();
-
-    // Proxy readiness (binary, OAuth, trusted-live listener).
-    const gate = await proxyGate();
-    if (!gate.ok) {
-      errorLog('[mosaic] claudex preflight failed:');
-      for (const problem of gate.problems) errorLog(`  - ${problem}`);
-      return fail(1);
-    }
-
-    // Compose the isolated launch env (guard throws → caught below, fail closed).
-    const resolvedModels = models();
-    const configDir = resolveConfigDir();
-    const env = buildEnv(baseEnv, { configDir, models: resolvedModels });
-    const prompt = `${adapter.composePrompt()}\n\n${buildClaudexContractNote(resolvedModels)}`;
-
-    log(buildClaudexBanner(resolvedModels));
-
-    const cliArgs = yolo ? ['--dangerously-skip-permissions'] : [];
-    cliArgs.push('--append-system-prompt', prompt, ...args);
-    adapter.exec('claude', cliArgs, env);
-  } catch (err) {
-    errorLog(
-      `[mosaic] claudex launch aborted: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    return fail(1);
-  }
-}

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

@@ -1,896 +0,0 @@
-import { chmod, mkdir, mkdtemp, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { Command } from 'commander';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { registerFleetCommand, type CommandResult, type FleetCommandDeps } from './fleet.js';
-import { executeFleetRegen, formatFleetRegenReport } from './fleet-regen-command.js';
-import {
-  acquirePrivateRosterMutationLock,
-  projectRosterV2AgentGeneratedEnv,
-} from '../fleet/fleet-reconciler.js';
-import { applyPreparedGeneratedAgentEnvironmentProjection } from '../fleet/generated-env-boundary.js';
-import { parseRosterV2 } from '../fleet/roster-v2.js';
-
-// A two-agent roster-v2 SSOT. `mosaic fleet regen` must rebuild each agent's
-// `fleet/agents/<name>.env.generated` projection from exactly this source and
-// nothing else — deterministically, without ever touching agent lifecycle.
-const rosterYaml = `
-version: 2
-generation: 7
-transport: tmux
-tmux:
-  socket_name: mosaic-fleet
-  holder_session: _holder
-defaults:
-  working_directory: /srv/mosaic
-  runtime: pi
-runtimes:
-  pi:
-    reset_command: /new
-agents:
-  - name: coder0
-    alias: Coder 0
-    class: code
-    runtime: pi
-    provider: openai
-    model: gpt-5.6-sol
-    reasoning: high
-    tool_policy: code
-    working_directory: /srv/mosaic
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: true
-  - name: coder1
-    alias: Coder 1
-    class: code
-    runtime: pi
-    provider: openai
-    model: gpt-5.6-sol
-    reasoning: medium
-    tool_policy: code
-    working_directory: /srv/other
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: true
-`;
-
-let cleanup: string | undefined;
-
-afterEach(async (): Promise<void> => {
-  vi.restoreAllMocks();
-  process.exitCode = undefined;
-  if (cleanup) await rm(cleanup, { recursive: true, force: true });
-  cleanup = undefined;
-});
-
-async function fleetHome(withRoster = rosterYaml): Promise<string> {
-  cleanup = await mkdtemp(join(tmpdir(), 'mosaic-fleet-regen-command-'));
-  for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
-    await mkdir(join(cleanup, directory), { recursive: true, mode: 0o700 });
-    await chmod(join(cleanup, directory), 0o700);
-  }
-  await chmod(cleanup, 0o700);
-  await writeFile(join(cleanup, 'fleet', 'roster.yaml'), withRoster, { mode: 0o600 });
-  // Semantic roster validation (matching `fleet reconcile`) resolves each agent
-  // class to a persona; seed the classes the fixtures reference.
-  for (const klass of ['code', 'merge-gate']) {
-    await writeFile(
-      join(cleanup, 'fleet', 'roles', `${klass}.md`),
-      `\`class: ${klass}\`\n\n# ${klass} persona\n`,
-      { mode: 0o600 },
-    );
-  }
-  return cleanup;
-}
-
-/**
- * A runner spy that records EVERY invocation. `regen` is projection-only and
- * must never issue a lifecycle/restart call, so a non-empty call log is a
- * hard failure — this is the load-bearing "never restarts" gate.
- */
-function recordingRunner(
-  calls: string[][],
-): (command: string, args: string[]) => Promise<CommandResult> {
-  return async (command: string, args: string[]): Promise<CommandResult> => {
-    calls.push([command, ...args]);
-    return { stdout: '', stderr: '', exitCode: 0 };
-  };
-}
-
-function program(mosaicHome: string, runner: FleetCommandDeps['runner']): Command {
-  const result = new Command();
-  result.exitOverride();
-  registerFleetCommand(result, { mosaicHome, runner });
-  return result;
-}
-
-function capture(): string[] {
-  const lines: string[] = [];
-  vi.spyOn(console, 'log').mockImplementation((value: string): void => {
-    lines.push(value);
-  });
-  return lines;
-}
-
-async function exists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-describe('projectRosterV2AgentGeneratedEnv', (): void => {
-  it('maps a roster-v2 agent to exactly the eight generated projection keys', (): void => {
-    const roster = parseRosterV2(rosterYaml, 'yaml');
-    const agent = roster.agents.find((candidate) => candidate.name === 'coder0');
-    expect(agent).toBeDefined();
-    const values = projectRosterV2AgentGeneratedEnv(roster, agent!);
-    expect(values).toEqual({
-      MOSAIC_AGENT_NAME: 'coder0',
-      MOSAIC_AGENT_CLASS: 'code',
-      MOSAIC_AGENT_RUNTIME: 'pi',
-      MOSAIC_AGENT_MODEL: 'gpt-5.6-sol',
-      MOSAIC_AGENT_REASONING: 'high',
-      MOSAIC_AGENT_TOOL_POLICY: 'code',
-      MOSAIC_AGENT_WORKDIR: '/srv/mosaic',
-      MOSAIC_TMUX_SOCKET: 'mosaic-fleet',
-    });
-  });
-});
-
-describe('mosaic fleet regen', (): void => {
-  it('reports a missing canonical roster with the shared initialization hint', async (): Promise<void> => {
-    const home = await mkdtemp(join(tmpdir(), 'mosaic-fleet-regen-missing-roster-'));
-    cleanup = home;
-
-    await expect(
-      program(home, recordingRunner([])).parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']),
-    ).rejects.toThrow(
-      `No fleet roster found at ${join(home, 'fleet', 'roster.yaml')}. Run \`mosaic fleet init\``,
-    );
-  });
-
-  it('is dry-run by default: reports the plan and writes nothing', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const lines = capture();
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--json',
-    ]);
-
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(result).toMatchObject({
-      mode: 'dry-run',
-      generation: 7,
-      agentCount: 2,
-      written: 0,
-    });
-    expect(result.agents.map((agent: { name: string }) => agent.name)).toEqual([
-      'coder0',
-      'coder1',
-    ]);
-    expect(
-      result.agents.every((agent: { disposition: string }) => agent.disposition === 'create'),
-    ).toBe(true);
-    // Nothing on disk.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(false);
-    // No lifecycle/restart call — ever.
-    expect(calls).toEqual([]);
-  });
-
-  it('forwards configured persona roots (rolesDir/overrideDir) from reconcileDeps into regen', async (): Promise<void> => {
-    // Codex r6: regen must resolve personas the SAME way reconcile does. If the
-    // top-level registration drops reconcileDeps.rolesDir/overrideDir, a deployment
-    // with custom persona roots gets reconcile ACCEPTING a roster while regen
-    // REJECTS it (validating against the wrong default `<home>/fleet/roles`),
-    // blocking the recovery command. Pin the wiring: seed personas ONLY under the
-    // custom roots, leave the default roles dir empty, require regen to succeed.
-    const home = await mkdtemp(join(tmpdir(), 'mosaic-fleet-regen-wiring-'));
-    cleanup = home;
-    for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
-      await mkdir(join(home, directory), { recursive: true, mode: 0o700 });
-      await chmod(join(home, directory), 0o700);
-    }
-    await chmod(home, 0o700);
-    await writeFile(join(home, 'fleet', 'roster.yaml'), rosterYaml, { mode: 0o600 });
-    // Personas live ONLY under the configured roots — the default `fleet/roles`
-    // stays empty, so broken wiring fails persona resolution.
-    const customRoles = join(home, 'custom-roles');
-    const customOverride = join(home, 'custom-roles.local');
-    await mkdir(customRoles, { recursive: true, mode: 0o700 });
-    await mkdir(customOverride, { recursive: true, mode: 0o700 });
-    for (const klass of ['code', 'merge-gate']) {
-      await writeFile(join(customRoles, `${klass}.md`), `\`class: ${klass}\`\n\n# ${klass}\n`, {
-        mode: 0o600,
-      });
-    }
-
-    const command = new Command();
-    command.exitOverride();
-    registerFleetCommand(command, {
-      mosaicHome: home,
-      runner: recordingRunner([]),
-      reconcileDeps: { rolesDir: customRoles, overrideDir: customOverride },
-    });
-    const lines = capture();
-
-    await command.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']);
-
-    // Regen validated against the CONFIGURED roots → success. Broken wiring
-    // resolves against the empty default and fails (exitCode 1, no JSON result).
-    expect(process.exitCode).not.toBe(1);
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(result).toMatchObject({ mode: 'dry-run', agentCount: 2 });
-  });
-
-  it('--write rebuilds each generated projection from the roster SSOT', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const lines = capture();
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(result).toMatchObject({ mode: 'write', written: 2, agentCount: 2 });
-
-    const coder0 = await readFile(join(home, 'fleet', 'agents', 'coder0.env.generated'), 'utf8');
-    expect(coder0).toContain('MOSAIC_AGENT_NAME=coder0');
-    expect(coder0).toContain('MOSAIC_AGENT_WORKDIR=/srv/mosaic');
-    expect(coder0).toContain('MOSAIC_TMUX_SOCKET=mosaic-fleet');
-    const coder1 = await readFile(join(home, 'fleet', 'agents', 'coder1.env.generated'), 'utf8');
-    expect(coder1).toContain('MOSAIC_AGENT_NAME=coder1');
-    expect(coder1).toContain('MOSAIC_AGENT_WORKDIR=/srv/other');
-    // No lifecycle/restart call — ever.
-    expect(calls).toEqual([]);
-  });
-
-  it('is deterministic and idempotent across repeated --write runs', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const path = join(home, 'fleet', 'agents', 'coder0.env.generated');
-
-    const cli = program(home, recordingRunner(calls));
-    capture();
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-    const first = await readFile(path, 'utf8');
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-    const second = await readFile(path, 'utf8');
-
-    expect(second).toBe(first);
-    expect(calls).toEqual([]);
-  });
-
-  it('reports rebuild disposition once the generated projection already exists', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const cli = program(home, recordingRunner(calls));
-    const lines = capture();
-
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-    lines.length = 0;
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']);
-
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(
-      result.agents.every((agent: { disposition: string }) => agent.disposition === 'rebuild'),
-    ).toBe(true);
-    expect(result.written).toBe(0);
-    expect(calls).toEqual([]);
-  });
-
-  it('never issues a lifecycle/restart call in either mode', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const cli = program(home, recordingRunner(calls));
-    capture();
-
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']);
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-
-    // Structural guarantee: regen has no path to systemctl/tmux at all.
-    expect(calls).toEqual([]);
-    const systemctlCalls = calls.filter(([command]) => command === 'systemctl');
-    expect(systemctlCalls).toEqual([]);
-  });
-
-  it('human-readable --write output prints the do-not-restart recovery runbook', async (): Promise<void> => {
-    const home = await fleetHome();
-    const lines = capture();
-
-    await program(home, recordingRunner([])).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-    ]);
-
-    const output = lines.join('\n');
-    expect(output).toMatch(/do not restart|before.*restart/i);
-    expect(output).toMatch(/env\.generated/);
-    // The unit has no EnvironmentFile= directive, so the runbook must NOT tell the
-    // operator to verify one — verify the launcher/generated file instead.
-    expect(output).not.toContain('EnvironmentFile');
-    expect(output).toMatch(/systemctl --user cat mosaic-agent@<name>/);
-    expect(output).toMatch(/restart/i);
-  });
-
-  it('emits paths and counts only — never the projected env body (secrev)', async (): Promise<void> => {
-    const home = await fleetHome();
-    const lines = capture();
-
-    await program(home, recordingRunner([])).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-    ]);
-
-    const output = lines.join('\n');
-    // Relative paths + counts are fine; the rendered projection body (KEY=value
-    // lines) must never be echoed to stdout.
-    expect(output).toContain('coder0.env.generated');
-    expect(output).not.toMatch(/^MOSAIC_AGENT_\w+=/m);
-    expect(output).not.toContain('MOSAIC_TMUX_SOCKET=mosaic-fleet');
-  });
-
-  it('is projection-only: leaves legacy .env untouched and writes no .env.local/.env.quarantine', async (): Promise<void> => {
-    // Recovery contract: regen rebuilds ONLY <name>.env.generated. It must never
-    // relocate, quarantine, or unlink the operator-owned legacy .env surface — the
-    // full reconciler apply path does, so regen must NOT use it.
-    const home = await fleetHome();
-    const legacyPath = join(home, 'fleet', 'agents', 'coder0.env');
-    await writeFile(legacyPath, 'MOSAIC_RUNTIME_BIN=/usr/bin/pi\n', { mode: 0o600 });
-    capture();
-
-    await program(home, recordingRunner([])).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    // Generated projection rebuilt...
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(true);
-    // ...but the operator's legacy .env is preserved verbatim, and no local/quarantine
-    // files were fabricated from it.
-    expect(await readFile(legacyPath, 'utf8')).toBe('MOSAIC_RUNTIME_BIN=/usr/bin/pi\n');
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.local'))).toBe(false);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.quarantine'))).toBe(false);
-  });
-
-  it('prepares every agent before writing any: a later prepare failure leaves nothing written', async (): Promise<void> => {
-    // Fail-closed across agents. Pre-seed coder1's projection with world-readable
-    // perms so its prepare rejects; coder0 (valid) must NOT be written because
-    // preparation is fully completed before the first apply.
-    const home = await fleetHome();
-    const coder1Path = join(home, 'fleet', 'agents', 'coder1.env.generated');
-    await writeFile(coder1Path, 'MOSAIC_AGENT_NAME=coder1\n', { mode: 0o644 });
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    // coder0 is valid but must remain unwritten — no partial rebuild.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('fails closed on a semantically invalid roster (protected-class tool-policy mismatch)', async (): Promise<void> => {
-    // A hand-edited roster giving a protected class a weaker tool_policy is rejected
-    // by reconcile/plan/verify; regen must enforce the SAME gate, not silently
-    // project the downgraded policy into <name>.env.generated.
-    const home = await fleetHome(`
-version: 2
-generation: 3
-transport: tmux
-tmux:
-  socket_name: mosaic-fleet
-  holder_session: _holder
-defaults:
-  working_directory: /srv/mosaic
-  runtime: pi
-runtimes:
-  pi:
-    reset_command: /new
-agents:
-  - name: gate0
-    alias: Gate 0
-    class: merge-gate
-    runtime: pi
-    provider: openai
-    model: gpt-5.6-sol
-    reasoning: high
-    tool_policy: code
-    working_directory: /srv/mosaic
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: true
-`);
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'gate0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('refuses to write while a concurrent reconcile holds the mutation lock', async (): Promise<void> => {
-    // regen --write mutates the same projections as reconcile; it must take the
-    // shared reconcile lock so a concurrent reconcile cannot race a stale write.
-    const home = await fleetHome();
-    await writeFile(join(home, 'fleet', 'roster.yaml.reconcile.lock'), 'held\n', { mode: 0o600 });
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('fails closed (non-zero, no writes) on an invalid roster', async (): Promise<void> => {
-    // roster-v2 requires >= 1 agent; a malformed roster must abort regen without
-    // writing any projection and without touching lifecycle.
-    const home = await fleetHome('version: 2\ngeneration: 1\n');
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('rejects a non-canonical --roster path (canonical roster only)', async (): Promise<void> => {
-    // `fleet` exposes a global `--roster`; reconcile rejects a non-canonical value
-    // rather than silently reading the canonical roster. regen must enforce the
-    // SAME guard so `--roster /elsewhere regen --write` cannot mislead the operator.
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      '--roster',
-      join(home, 'other', 'roster.yaml'),
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(errors.join('')).toMatch(/canonical roster/i);
-    // No projection written against a misdirected roster path.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('reports an incomplete rebuild when a later projection write fails mid-loop', async (): Promise<void> => {
-    // Fault injected on the SECOND apply: coder0 is already replaced on disk, so a
-    // bare throw would hide the partial state. regen must surface which agents were
-    // rebuilt and which failed, with a verify-before-restart recovery instruction.
-    const home = await fleetHome();
-    const realApply = applyPreparedGeneratedAgentEnvironmentProjection;
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        applyProjection: async (prepared): Promise<string> => {
-          if (prepared.generatedPath.endsWith('coder1.env.generated')) {
-            throw new Error('simulated ENOSPC on coder1');
-          }
-          return realApply(prepared);
-        },
-      },
-      { write: true },
-    );
-
-    // coder0 written before the fault; coder1 not.
-    expect(result.written).toBe(1);
-    expect(result.incomplete).toMatchObject({
-      code: 'projection-apply-failed',
-      failedAgent: 'coder1',
-      writtenAgents: ['coder0'],
-    });
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(true);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(false);
-
-    // The human report names the failed agent and directs a verify-before-restart
-    // recovery — not a bare success runbook.
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toMatch(/incomplete/i);
-    expect(report).toContain('coder1');
-    expect(report).toMatch(/verify|re-run|retry/i);
-    // Structural: still no lifecycle call anywhere on the failure path.
-    expect(report).not.toMatch(/systemctl --user restart mosaic-agent@<name>\n.*\n/);
-  });
-
-  it('refuses to write while agent CRUD holds the roster mutation lock', async (): Promise<void> => {
-    // regen --write overwrites the SAME generated projections that `fleet agent
-    // create/update/delete` writes under roster.yaml.mutation.lock. If regen only
-    // took the reconcile lock it could read a stale roster and overwrite a just-
-    // committed projection. It must also take the mutation lock and fail closed.
-    const home = await fleetHome();
-    await writeFile(join(home, 'fleet', 'roster.yaml.mutation.lock'), 'crud\n', { mode: 0o600 });
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    // No projection written against a roster a concurrent CRUD is mutating.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('surfaces BOTH the roster failure and a stale-lock warning on a double fault', async (): Promise<void> => {
-    // Worst case with nothing written: run() fails (invalid roster, fail-closed) AND
-    // a lock release faults. The operator must be told the lock may be stale, not
-    // just the roster error — otherwise the next regen/reconcile is silently blocked.
-    const home = await fleetHome('version: 2\ngeneration: 1\n');
-    const throwingRelease =
-      () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-        throw new Error('simulated lock unlink fault');
-      };
-    await expect(
-      executeFleetRegen(
-        {
-          runner: recordingRunner([]),
-          mosaicHome: home,
-          acquireReconcileLock: throwingRelease,
-          acquireRosterMutationLock: throwingRelease,
-        },
-        { write: true },
-      ),
-    ).rejects.toThrow(/stale|inspect|lock/i);
-    // Nothing written on the fail-closed path.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-  });
-
-  it('propagates a roster-mutation-lock release failure instead of silently keeping a stale lock', async (): Promise<void> => {
-    // Finding L: the real `acquirePrivateRosterMutationLock` release must SURFACE an
-    // unlink failure, not swallow it. If it swallowed (like the CRUD-internal
-    // acquireMutationLock does), a stale roster.yaml.mutation.lock left after a
-    // successful regen would block later regen/agent CRUD while the command reported
-    // success — and the finding-J stale-lock warning would never fire for this lock.
-    const home = await fleetHome();
-    const release = await acquirePrivateRosterMutationLock(home)();
-    // Simulate the lock vanishing (or being unremovable) before release runs: the
-    // underlying unlink then faults. A swallowing release would resolve and hide it.
-    await rm(join(home, 'fleet', 'roster.yaml.mutation.lock'));
-    await expect(release()).rejects.toThrow();
-  });
-
-  it('preserves a complete rebuild result and flags lock-cleanup when release faults', async (): Promise<void> => {
-    // A lock-release fault after a successful write must NOT discard the fact that
-    // projections are now live — the operator needs to know the write happened and
-    // that the shared lock may be stale, not just a bare "regen failed".
-    const home = await fleetHome();
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        acquireReconcileLock:
-          () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-            throw new Error('simulated lock unlink fault');
-          },
-      },
-      { write: true },
-    );
-
-    expect(result.written).toBe(2);
-    expect(result.incomplete).toBeUndefined();
-    expect(result.cleanup).toMatchObject({
-      code: 'lock-cleanup-failed',
-      action: 'inspect-lock-before-retry',
-    });
-    // Projections are genuinely on disk despite the release fault.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(true);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(true);
-
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toMatch(/lock/i);
-    expect(report).toMatch(/stale|inspect|clear/i);
-  });
-
-  it('preserves a partial rebuild AND flags lock-cleanup when both apply and release fault', async (): Promise<void> => {
-    // Worst case: a mid-loop apply fault leaves a partial rebuild, then the release
-    // also faults. Both recovery states must survive so the operator sees exactly
-    // which projections are live and that the lock may be stale.
-    const home = await fleetHome();
-    const realApply = applyPreparedGeneratedAgentEnvironmentProjection;
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        applyProjection: async (prepared): Promise<string> => {
-          if (prepared.generatedPath.endsWith('coder1.env.generated')) {
-            throw new Error('simulated ENOSPC on coder1');
-          }
-          return realApply(prepared);
-        },
-        acquireReconcileLock:
-          () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-            throw new Error('simulated lock unlink fault');
-          },
-      },
-      { write: true },
-    );
-
-    expect(result.written).toBe(1);
-    expect(result.incomplete).toMatchObject({
-      code: 'projection-apply-failed',
-      failedAgent: 'coder1',
-      writtenAgents: ['coder0'],
-    });
-    expect(result.cleanup).toMatchObject({ code: 'lock-cleanup-failed' });
-
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toMatch(/incomplete/i);
-    expect(report).toMatch(/lock/i);
-  });
-
-  it('fails closed without deleting a REPLACEMENT roster-mutation lock it no longer owns', async (): Promise<void> => {
-    // Finding M1 (replacement-lock race): after this invocation created its lock, the
-    // lock is cleared and re-created by ANOTHER writer (new inode + foreign token)
-    // BEFORE release runs. The release must PROVE ownership (device/inode + token) and
-    // refuse to unlink the stranger's live lock — otherwise it deletes it, a third
-    // writer enters concurrently, and mutual exclusion over the projections is broken.
-    // This pins the REACHABLE window (replaced-before-release); the residual sub-window
-    // between the final check and the path `unlink` is unreachable within the `wx`
-    // writer protocol and matches the merged reconcile lock — see the acquirer doc.
-    const home = await fleetHome();
-    const lockPath = join(home, 'fleet', 'roster.yaml.mutation.lock');
-    const release = await acquirePrivateRosterMutationLock(home)();
-    // A different writer replaces the lock: same path, NEW inode, foreign content.
-    await rm(lockPath);
-    await writeFile(lockPath, 'a-different-writer\n', { mode: 0o600 });
-    const replacement = await stat(lockPath);
-    // Release must reject (it no longer owns this file) AND the diagnosis must name
-    // the MUTATION lock specifically — a fault on this shared helper must not be
-    // mislabeled as the reconcile lock (that would defeat the M3 accurate-diagnosis
-    // goal, since regen serializes on both) ...
-    await expect(release()).rejects.toThrow(/roster\.yaml\.mutation\.lock/);
-    // ... and MUST NOT have unlinked the stranger's live lock.
-    expect(await exists(lockPath)).toBe(true);
-    expect((await stat(lockPath)).ino).toBe(replacement.ino);
-  });
-
-  it('does not strand the lock file when initialization fails after creating it', async (): Promise<void> => {
-    // Codex r4: if writeFile/stat/close/ownership-check throws AFTER the `wx` create
-    // succeeds, the just-created lock must NOT be left behind — a stranded lock would
-    // permanently block future regen AND agent CRUD (both contend on this path). The
-    // cleanup is dev/ino-guarded (never deletes a replacement) and best-effort (never
-    // masks the initialization error).
-    const home = await fleetHome();
-    const lockPath = join(home, 'fleet', 'roster.yaml.mutation.lock');
-    // Inject an opener that performs the REAL `wx` create (so the lock file really
-    // lands on disk) but whose handle faults on the token write — a post-create
-    // initialization failure.
-    const faultingOpen = (async (
-      path: Parameters<typeof open>[0],
-      flags: Parameters<typeof open>[1],
-      mode: Parameters<typeof open>[2],
-    ) => {
-      const handle = await open(path, flags, mode);
-      return new Proxy(handle, {
-        get(target, prop, receiver): unknown {
-          if (prop === 'writeFile') {
-            return async (): Promise<never> => {
-              throw new Error('simulated ENOSPC on token write');
-            };
-          }
-          const value = Reflect.get(target, prop, receiver);
-          return typeof value === 'function' ? value.bind(target) : value;
-        },
-      });
-    }) as typeof open;
-
-    await expect(acquirePrivateRosterMutationLock(home, faultingOpen)()).rejects.toThrow(
-      /mutation\.lock/,
-    );
-    // The lock we created must have been cleaned up — not stranded on disk.
-    expect(await exists(lockPath)).toBe(false);
-  });
-
-  it('does not strand the lock file when the post-create stat itself fails', async (): Promise<void> => {
-    // Codex r5: the narrower sub-path where `handle.stat()` ITSELF rejects right after
-    // the `wx` create succeeds (transient EIO/EBADF). device/inode identity is then
-    // unavailable, so the init-failure cleanup cannot prove ownership by dev/ino — yet
-    // the lock must STILL not be stranded, because a stranded lock permanently blocks
-    // future regen AND agent CRUD. The token we persisted before the failure uniquely
-    // identifies OUR lock, so cleanup falls back to matching it.
-    const home = await fleetHome();
-    const lockPath = join(home, 'fleet', 'roster.yaml.mutation.lock');
-    // Real `wx` create (lock really lands on disk); the token write SUCCEEDS so our
-    // random token is persisted, then `stat()` faults — a post-create init failure.
-    const faultingStatOpen = (async (
-      path: Parameters<typeof open>[0],
-      flags: Parameters<typeof open>[1],
-      mode: Parameters<typeof open>[2],
-    ) => {
-      const handle = await open(path, flags, mode);
-      return new Proxy(handle, {
-        get(target, prop, receiver): unknown {
-          if (prop === 'stat') {
-            return async (): Promise<never> => {
-              throw new Error('simulated EIO on post-create stat');
-            };
-          }
-          const value = Reflect.get(target, prop, receiver);
-          return typeof value === 'function' ? value.bind(target) : value;
-        },
-      });
-    }) as typeof open;
-
-    await expect(acquirePrivateRosterMutationLock(home, faultingStatOpen)()).rejects.toThrow(
-      /mutation\.lock/,
-    );
-    // Even without dev/ino, the token-based fallback must have removed our lock.
-    expect(await exists(lockPath)).toBe(false);
-  });
-
-  it('surfaces a lock-cleanup fault when unwinding after a later lock acquire fails', async (): Promise<void> => {
-    // Finding M2: the FIRST lock is taken, the SECOND lock's acquire throws, and
-    // unwinding the first lock's release ALSO faults. The acquire-unwind path must
-    // surface both — the already-taken lock may now be stale and silently block the
-    // next regen/reconcile — not just re-throw the acquire error and drop the fault.
-    const home = await fleetHome();
-    await expect(
-      executeFleetRegen(
-        {
-          runner: recordingRunner([]),
-          mosaicHome: home,
-          // Mutation lock (acquired first) succeeds, but its RELEASE faults on unwind.
-          acquireRosterMutationLock:
-            () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-              throw new Error('simulated mutation-lock unlink fault');
-            },
-          // Reconcile lock (acquired second) ACQUIRE fails, triggering the unwind.
-          acquireReconcileLock: () => async (): Promise<() => Promise<void>> => {
-            throw new Error('simulated reconcile acquire failure');
-          },
-        },
-        { write: true },
-      ),
-    ).rejects.toThrow(/stale|inspect|lock/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-  });
-
-  it('names BOTH fleet locks in the stale-lock warning (cleanup can come from either)', async (): Promise<void> => {
-    // Finding M3: finding L made the roster MUTATION lock's release fault reachable, so
-    // the cleanup marker can now originate from either lock. The human report must not
-    // claim only the reconcile lock is stale — it must name both candidate lock files
-    // so the operator inspects the right one.
-    const home = await fleetHome();
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        // Fault the MUTATION lock's release specifically (reconcile lock is real).
-        acquireRosterMutationLock:
-          () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-            throw new Error('simulated mutation-lock unlink fault');
-          },
-      },
-      { write: true },
-    );
-
-    expect(result.written).toBe(2);
-    expect(result.cleanup).toMatchObject({ code: 'lock-cleanup-failed' });
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toContain('roster.yaml.mutation.lock');
-    expect(report).toContain('roster.yaml.reconcile.lock');
-  });
-});

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

@@ -1,446 +0,0 @@
-import { stat } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join, relative, resolve } from 'node:path';
-import type { Command } from 'commander';
-import type { CommandRunner } from './fleet.js';
-import {
-  applyPreparedGeneratedAgentEnvironmentProjection,
-  prepareGeneratedAgentEnvironmentProjection,
-  type PreparedGeneratedAgentEnvironmentProjection,
-} from '../fleet/generated-env-boundary.js';
-import {
-  acquirePrivateReconcileLock,
-  acquirePrivateRosterMutationLock,
-  projectRosterV2AgentGeneratedEnv,
-} from '../fleet/fleet-reconciler.js';
-import {
-  parseRosterV2,
-  validateRosterV2Semantics,
-  type FleetRosterV2,
-} from '../fleet/roster-v2.js';
-import { FleetRosterConfigurationError, readFleetRosterText } from '../fleet/fleet-roster-v1.js';
-
-/**
- * `mosaic fleet regen` — recovery-framed regeneration of the roster-derived
- * agent env projections (`fleet/agents/<name>.env.generated`) from the roster
- * SSOT. It is the recovery layer of #791: when a wiped/diverged operator surface
- * has cost an agent its generated projection, regen rebuilds it deterministically
- * from `roster.yaml` so the launcher can source the intended identity again.
- *
- * It is intentionally a THIN projection-only wrapper over the same mapping the
- * reconciler apply path uses ({@link projectRosterV2AgentGeneratedEnv}), and it
- * has NO code path to systemd lifecycle: regen never starts, stops, or restarts
- * an agent. Recovery order forbids restart-before-verify, so the operator must
- * verify each rebuilt projection resolves before restarting anything.
- */
-export interface FleetRegenAgentPlan {
-  readonly name: string;
-  /** Generated-projection path, relative to the Mosaic home (never absolute in output). */
-  readonly path: string;
-  /** `create` when the projection is currently absent, `rebuild` when it already exists. */
-  readonly disposition: 'create' | 'rebuild';
-}
-
-/**
- * Present ONLY when a `--write` projection apply failed partway through the
- * fleet. Every prior agent was already validated and prepared, so `writtenAgents`
- * are byte-complete on disk; `failedAgent` is where the write faulted. The
- * command surfaces this instead of a bare throw so the operator can finish the
- * rebuild and verify every projection before restarting any unit.
- */
-export interface FleetRegenIncomplete {
-  readonly code: 'projection-apply-failed';
-  /** The agent whose generated-projection write faulted. */
-  readonly failedAgent: string;
-  /** Agents whose projections were fully written before the fault (in apply order). */
-  readonly writtenAgents: readonly string[];
-}
-
-export interface FleetRegenResult {
-  readonly mode: 'dry-run' | 'write';
-  /** Roster path, relative to the Mosaic home. */
-  readonly rosterPath: string;
-  readonly generation: number;
-  readonly agentCount: number;
-  /** Count of projections written to disk (always 0 in dry-run). */
-  readonly written: number;
-  readonly agents: readonly FleetRegenAgentPlan[];
-  /** Set ONLY when a `--write` apply faulted mid-fleet — a partial rebuild. */
-  readonly incomplete?: FleetRegenIncomplete;
-  /**
-   * Set ONLY when a shared fleet lock could not be released after a write completed
-   * (or partially completed) — EITHER `roster.yaml.mutation.lock` or
-   * `roster.yaml.reconcile.lock`, since regen holds both. The projections in this
-   * result are real; the lock file may be stale and must be inspected before the
-   * next mutation. Independent of {@link incomplete} — both can be present at once.
-   */
-  readonly cleanup?: {
-    readonly code: 'lock-cleanup-failed';
-    readonly action: 'inspect-lock-before-retry';
-  };
-}
-
-export interface FleetRegenDeps {
-  /**
-   * Present ONLY so an accidental future lifecycle wiring is caught by the
-   * "never restarts" test — regen is contractually forbidden to invoke it.
-   */
-  readonly runner: CommandRunner;
-  readonly mosaicHome?: string;
-  /** Persona roots for semantic roster validation (defaults mirror the reconciler). */
-  readonly rolesDir?: string;
-  readonly overrideDir?: string;
-  /** Test seam: canonical roster reader. Defaults to parse + semantic validation. */
-  readonly readRoster?: (rosterPath: string) => Promise<FleetRosterV2>;
-  /**
-   * Test seam: generated-only projection validator. Defaults to the audited
-   * boundary helper that validates ONLY `<name>.env.generated`.
-   */
-  readonly prepareProjection?: typeof prepareGeneratedAgentEnvironmentProjection;
-  /** Test seam: generated-only projection writer. Defaults to the audited boundary helper. */
-  readonly applyProjection?: typeof applyPreparedGeneratedAgentEnvironmentProjection;
-  /**
-   * Test seam: acquire the shared reconcile lock before a `--write`. Defaults to
-   * the reconciler's private lock so regen and reconcile are mutually exclusive
-   * and a concurrent reconcile cannot race a stale projection write.
-   */
-  readonly acquireReconcileLock?: (mosaicHome: string) => () => Promise<() => Promise<void>>;
-  /**
-   * Test seam: acquire the shared roster mutation lock before a `--write`.
-   * Defaults to the reconciler's hardened, ownership-proving acquirer for the
-   * same `fleet/roster.yaml.mutation.lock` path that CRUD contends on, so regen
-   * serializes against agent create/update/delete — both rewrite the same
-   * generated projections, so without this a concurrent CRUD could race a stale
-   * projection write.
-   */
-  readonly acquireRosterMutationLock?: (mosaicHome: string) => () => Promise<() => Promise<void>>;
-  /** Test seam: existence probe for create/rebuild disposition. */
-  readonly fileExists?: (path: string) => Promise<boolean>;
-}
-
-interface FleetRegenOptions {
-  readonly write?: boolean;
-}
-
-function defaultMosaicHome(deps: FleetRegenDeps): string {
-  return deps.mosaicHome ?? process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
-}
-
-async function defaultFileExists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Projection-only regeneration core. Deterministic and side-effect-free in
- * dry-run; in `--write` it rebuilds each generated projection through the
- * audited generated-only boundary writer and NOTHING else — it never writes
- * `.env.local`/`.env.quarantine`, never unlinks the legacy `.env`, and never
- * touches `deps.runner`.
- *
- * Fail-closed by construction: the roster is validated (structural + semantic)
- * and EVERY agent's projection is prepared before ANY is written, so a single
- * invalid agent (or a semantically rejected roster) leaves the whole surface
- * untouched. In `--write` mode the read-prepare-apply sequence runs under the
- * shared reconcile lock so a concurrent reconcile cannot race a stale write.
- */
-export async function executeFleetRegen(
-  deps: FleetRegenDeps,
-  options: FleetRegenOptions,
-): Promise<FleetRegenResult> {
-  const mosaicHome = defaultMosaicHome(deps);
-  const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
-  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
-  const readRoster = deps.readRoster ?? defaultReadRoster(deps, mosaicHome);
-  const prepare = deps.prepareProjection ?? prepareGeneratedAgentEnvironmentProjection;
-  const apply = deps.applyProjection ?? applyPreparedGeneratedAgentEnvironmentProjection;
-  const fileExists = deps.fileExists ?? defaultFileExists;
-  const acquireReconcileLock = deps.acquireReconcileLock ?? acquirePrivateReconcileLock;
-  const acquireRosterMutationLock =
-    deps.acquireRosterMutationLock ?? acquirePrivateRosterMutationLock;
-  const write = options.write === true;
-
-  const run = async (): Promise<FleetRegenResult> => {
-    const roster = await readRoster(rosterPath);
-
-    // Prepare (validate) every agent BEFORE any write, so a later failure never
-    // leaves an earlier projection partially rebuilt.
-    const prepared: (PreparedGeneratedAgentEnvironmentProjection & {
-      readonly name: string;
-      readonly disposition: 'create' | 'rebuild';
-    })[] = [];
-    for (const agent of roster.agents) {
-      const projection = await prepare({
-        mosaicHome,
-        agentEnvDir,
-        agentName: agent.name,
-        generated: projectRosterV2AgentGeneratedEnv(roster, agent),
-      });
-      const disposition = (await fileExists(projection.generatedPath)) ? 'rebuild' : 'create';
-      prepared.push({ ...projection, name: agent.name, disposition });
-    }
-
-    // Every projection is already validated (prepared); an apply here can only
-    // fault on the underlying I/O (ENOSPC, EIO, a race outside the lock). If a
-    // later write faults, earlier agents are already replaced on disk, so we
-    // stop and report the partial state rather than throwing a bare error that
-    // hides which projections are now live.
-    let written = 0;
-    let incomplete: FleetRegenIncomplete | undefined;
-    if (write) {
-      for (const projection of prepared) {
-        try {
-          await apply(projection);
-        } catch {
-          incomplete = {
-            code: 'projection-apply-failed',
-            failedAgent: projection.name,
-            writtenAgents: prepared.slice(0, written).map((entry) => entry.name),
-          };
-          break;
-        }
-        written += 1;
-      }
-    }
-
-    return {
-      mode: write ? 'write' : 'dry-run',
-      rosterPath: relative(mosaicHome, rosterPath),
-      generation: roster.generation,
-      agentCount: roster.agents.length,
-      written,
-      agents: prepared.map((projection) => ({
-        name: projection.name,
-        path: relative(mosaicHome, projection.generatedPath),
-        disposition: projection.disposition,
-      })),
-      ...(incomplete ? { incomplete } : {}),
-    };
-  };
-
-  // Dry-run is preview-only and never mutates, so it stays lock-free (usable even
-  // while a reconcile or CRUD holds a lock). A `--write` must serialize against
-  // BOTH roster writers of the same generated projections: agent CRUD (roster
-  // mutation lock) and reconcile (reconcile lock). Acquire in a fixed order — the
-  // locks are non-blocking (they throw on contention rather than wait), so no
-  // deadlock is possible — and fail closed if either is already held.
-  if (!write) return run();
-
-  const releases: (() => Promise<void>)[] = [];
-  try {
-    releases.push(await acquireRosterMutationLock(mosaicHome)());
-    releases.push(await acquireReconcileLock(mosaicHome)());
-  } catch (error: unknown) {
-    // A later acquire failed; unwind any lock already taken (reverse order). If
-    // that unwind ALSO faults, surface both — the already-taken lock may now be
-    // stale and silently block the next regen/reconcile — rather than dropping it.
-    const releaseFault = await releaseFleetLocks(releases);
-    throw augmentWithLockCleanupFault(error, releaseFault);
-  }
-
-  let result: FleetRegenResult | undefined;
-  let primaryError: unknown;
-  try {
-    result = await run();
-  } catch (error: unknown) {
-    primaryError = error;
-  }
-
-  // Release both locks (reverse acquire order), continuing past a fault so neither
-  // leaks. A release fault must never discard a completed (or partial) rebuild —
-  // the projections are already on disk — and must not be silently hidden even
-  // when the run itself failed with nothing written.
-  const releaseFault = await releaseFleetLocks(releases);
-  if (result) {
-    return releaseFault === undefined
-      ? result
-      : {
-          ...result,
-          cleanup: { code: 'lock-cleanup-failed', action: 'inspect-lock-before-retry' },
-        };
-  }
-  // result is undefined ⇒ run() threw ⇒ primaryError is set.
-  throw augmentWithLockCleanupFault(primaryError, releaseFault);
-}
-
-/**
- * Releases held locks in reverse acquire order, continuing past a fault so a
- * single failed release never leaks the others. Returns the first fault seen (or
- * undefined when every release succeeded).
- */
-async function releaseFleetLocks(releases: readonly (() => Promise<void>)[]): Promise<unknown> {
-  let firstFault: unknown;
-  for (const release of [...releases].reverse()) {
-    try {
-      await release();
-    } catch (error: unknown) {
-      if (firstFault === undefined) firstFault = error;
-    }
-  }
-  return firstFault;
-}
-
-/**
- * When a run failed with nothing written AND lock cleanup also faulted, surface
- * both: the operator needs to know the lock may be stale (else the next
- * regen/reconcile is silently blocked), not just the original run error.
- */
-function augmentWithLockCleanupFault(primaryError: unknown, releaseFault: unknown): unknown {
-  if (releaseFault === undefined) return primaryError;
-  const base = primaryError instanceof Error ? primaryError.message : String(primaryError);
-  return new Error(
-    `${base} (additionally, a fleet lock could not be released — ` +
-      'fleet/roster.yaml.mutation.lock or roster.yaml.reconcile.lock may be stale; ' +
-      'inspect and clear it before retry)',
-  );
-}
-
-function defaultReadRoster(
-  deps: FleetRegenDeps,
-  mosaicHome: string,
-): (rosterPath: string) => Promise<FleetRosterV2> {
-  return async (rosterPath: string): Promise<FleetRosterV2> => {
-    const roster = parseRosterV2(await readFleetRosterText(rosterPath), 'yaml');
-    // Enforce the SAME semantic gate as reconcile/plan/verify (persona resolution
-    // + protected-class tool-policy match) so regen cannot project a roster the
-    // rest of the fleet surface would reject.
-    await validateRosterV2Semantics(roster, {
-      rolesDir: deps.rolesDir ?? join(mosaicHome, 'fleet', 'roles'),
-      overrideDir: deps.overrideDir ?? join(mosaicHome, 'fleet', 'roles.local'),
-    });
-    return roster;
-  };
-}
-
-/**
- * Human-readable report — paths and counts ONLY. The rendered projection body
- * (KEY=value lines) is never echoed (secrev). In `--write` mode it prints the
- * recovery runbook: verify each projection resolves BEFORE any restart.
- */
-export function formatFleetRegenReport(result: FleetRegenResult): string[] {
-  const lines: string[] = [];
-  const header =
-    result.mode === 'dry-run'
-      ? 'mosaic fleet regen — dry run (no changes written)'
-      : 'mosaic fleet regen — wrote roster-derived projections';
-  lines.push(header);
-  lines.push(
-    `roster: ${result.rosterPath} (generation ${result.generation}, ${result.agentCount} agent(s))`,
-  );
-  for (const agent of result.agents) {
-    lines.push(`  ${agent.name}  ${agent.path}  [${agent.disposition}]`);
-  }
-
-  if (result.mode === 'dry-run') {
-    lines.push(
-      `Plan: would write ${result.agentCount} generated projection(s). ` +
-        `Re-run with --write to apply. regen never restarts agents.`,
-    );
-    return lines;
-  }
-
-  if (result.incomplete) {
-    const { failedAgent, writtenAgents } = result.incomplete;
-    lines.push(
-      `INCOMPLETE: rebuild stopped at agent ${failedAgent} — its projection write faulted.`,
-    );
-    lines.push(
-      `Rebuilt before the fault: ${writtenAgents.length} projection(s)` +
-        (writtenAgents.length > 0 ? ` (${writtenAgents.join(', ')})` : '') +
-        `; ${result.agentCount - writtenAgents.length} not written.`,
-    );
-    lines.push(
-      'Recover: re-run `mosaic fleet regen --write` to finish, then VERIFY every ' +
-        "agent's fleet/agents/<name>.env.generated resolves BEFORE restarting any " +
-        'unit. regen never restarts agents.',
-    );
-  } else {
-    lines.push(`Wrote ${result.written} generated projection(s).`);
-    lines.push('Next steps — DO NOT restart agents before verifying:');
-    lines.push(
-      "  1. Confirm each agent's fleet/agents/<name>.env.generated exists and carries " +
-        'the intended MOSAIC_AGENT_* values.',
-    );
-    // The unit sets NO EnvironmentFile= — it launches from a minimal env and the
-    // launcher (start-agent-session.sh) sources .env.generated itself. Verify the
-    // launcher path, not a nonexistent EnvironmentFile property.
-    lines.push(
-      '  2. Confirm the unit launches from it: `systemctl --user cat mosaic-agent@<name>` ' +
-        'shows ExecStart running start-agent-session.sh, which reads .env.generated.',
-    );
-    lines.push(
-      '  3. Only then restart one unit at a time: systemctl --user restart mosaic-agent@<name>.',
-    );
-  }
-
-  if (result.cleanup) {
-    lines.push(
-      'WARNING: a fleet lock could not be released — ' +
-        'fleet/roster.yaml.mutation.lock or fleet/roster.yaml.reconcile.lock may be ' +
-        'stale; inspect and clear it before the next reconcile or regen.',
-    );
-  }
-  return lines;
-}
-
-function resolveRegenMosaicHome(fleetCommand: Command, deps: FleetRegenDeps): string {
-  const options = fleetCommand.optsWithGlobals<{ mosaicHome?: string }>();
-  return options.mosaicHome ?? defaultMosaicHome(deps);
-}
-
-/**
- * regen reads the roster SSOT at `<mosaicHome>/fleet/roster.yaml` and ignores the
- * `fleet --roster <path>` global. If an operator passes a non-canonical `--roster`
- * they must NOT be silently served the canonical file — mirror reconcile's guard
- * and reject, so `mosaic fleet --roster /elsewhere regen --write` fails closed.
- */
-function assertRegenCanonicalRoster(fleetCommand: Command, mosaicHome: string): void {
-  const options = fleetCommand.optsWithGlobals<{ roster?: string }>();
-  const canonical = join(mosaicHome, 'fleet', 'roster.yaml');
-  if (options.roster !== undefined && resolve(options.roster) !== resolve(canonical)) {
-    throw new Error(
-      'Roster-v2 regeneration requires the canonical roster path (fleet/roster.yaml).',
-    );
-  }
-}
-
-/** Registers the recovery-framed `mosaic fleet regen` command. */
-export function registerFleetRegenCommand(fleetCommand: Command, deps: FleetRegenDeps): void {
-  fleetCommand
-    .command('regen')
-    .description(
-      'Regenerate roster-derived agent env projections (dry-run default, --write to apply; never restarts)',
-    )
-    .option('--write', 'Write the regenerated projections to disk (default: dry-run)')
-    .option('--json', 'Emit the plan/result as JSON')
-    .action(async (opts: { write?: boolean; json?: boolean }): Promise<void> => {
-      const mosaicHome = resolveRegenMosaicHome(fleetCommand, deps);
-      try {
-        assertRegenCanonicalRoster(fleetCommand, mosaicHome);
-        const result = await executeFleetRegen(
-          { ...deps, mosaicHome },
-          { write: opts.write === true },
-        );
-        if (opts.json === true) {
-          console.log(JSON.stringify(result));
-        } else {
-          for (const line of formatFleetRegenReport(result)) console.log(line);
-        }
-        // A partial rebuild or a stale-lock cleanup state is a non-zero outcome:
-        // the operator must finish/verify (and clear the lock) before restarting.
-        if (result.incomplete || result.cleanup) process.exitCode = 1;
-      } catch (error: unknown) {
-        if (error instanceof FleetRosterConfigurationError) {
-          fleetCommand.error(error.message, { code: 'fleet.roster', exitCode: 1 });
-          return;
-        }
-        process.exitCode = 1;
-        const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`mosaic fleet regen failed: ${message}\n`);
-      }
-    });
-}

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

@@ -60,7 +60,6 @@ import {
   type SleepFn,
 } from './fleet.js';
 import { registerAgentCommand } from './agent.js';
-import { parseFleetRosterDocument, readFleetRosterText } from '../fleet/fleet-roster-v1.js';
 
 function buildProgram(): Command {
   const program = new Command();
@@ -98,7 +97,6 @@ describe('registerFleetCommand', () => {
       'provision',
       'ps',
       'reconcile',
-      'regen',
       'remove',
       'restart',
       'start',
@@ -167,55 +165,6 @@ describe('registerFleetCommand', () => {
   });
 });
 
-describe('fleet roster configuration failures', () => {
-  it('reports a missing roster with an actionable initialization hint', async () => {
-    const home = await tempDir();
-    try {
-      const program = buildProgram();
-
-      await expect(
-        program.parseAsync(['node', 'mosaic', 'fleet', '--mosaic-home', home, 'ps']),
-      ).rejects.toThrow(
-        `No fleet roster found at ${join(home, 'fleet', 'roster.json')}. Run \`mosaic fleet init\``,
-      );
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-
-  it('reports a malformed roster with the path and repair hint', async () => {
-    const home = await tempDir();
-    const rosterPath = join(home, 'fleet', 'roster.json');
-    try {
-      await mkdir(dirname(rosterPath), { recursive: true });
-      await writeFile(rosterPath, '{not valid json');
-
-      await expect(loadFleetRoster(rosterPath)).rejects.toThrow(
-        `Fleet roster at ${rosterPath} is invalid. Fix the file or run \`mosaic fleet init --force\``,
-      );
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-
-  it('reports an unreadable roster without exposing the filesystem error', async () => {
-    const home = await tempDir();
-    try {
-      await expect(readFleetRosterText(home)).rejects.toThrow(
-        `Could not read fleet roster at ${home}. Check the file exists and is readable.`,
-      );
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-
-  it('reports a malformed roster while selecting the v1/v2 command path', () => {
-    expect(() => parseFleetRosterDocument('version: [', '/srv/mosaic/fleet/roster.yaml')).toThrow(
-      'Fleet roster at /srv/mosaic/fleet/roster.yaml is invalid. Fix the file or run `mosaic fleet init --force`.',
-    );
-  });
-});
-
 describe('fleet roster parsing', () => {
   let cleanup: string | undefined;
 

packages/mosaic/src/commands/fleet.ts

@@ -19,11 +19,8 @@ import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
 import {
-  FleetRosterConfigurationError,
   getRosterAgent,
   loadFleetRoster,
-  parseFleetRosterDocument,
-  readFleetRosterText,
   resolveInstalledFleetRosterPath,
   type FleetAgent,
   type FleetRoster,
@@ -47,7 +44,6 @@ import {
   registerFleetReconcilerCommands,
   type FleetReconcilerCommandDeps,
 } from './fleet-reconciler-command.js';
-import { registerFleetRegenCommand } from './fleet-regen-command.js';
 import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
 import {
   applyPreparedAgentEnvironmentProjection,
@@ -1916,7 +1912,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
         const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
         const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
         const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-        const roster = await loadRosterAtPath(cmd, rosterPath);
+        const roster = await loadFleetRoster(rosterPath);
 
         const newAgent: FleetAgent = {
           name,
@@ -1976,7 +1972,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
       const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
       const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
       const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-      const roster = await loadRosterAtPath(cmd, rosterPath);
+      const roster = await loadFleetRoster(rosterPath);
 
       // Guard: throws if removing leaves 0 orchestrators or agent not in roster
       const updatedRoster = removeAgentFromRoster(roster, name);
@@ -2067,18 +2063,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     reconcileDeps: deps.reconcileDeps,
   });
 
-  // Recovery (#791 PR3): rebuild roster-derived env projections from the roster
-  // SSOT. Projection-only and preview-first — never issues a lifecycle restart.
-  registerFleetRegenCommand(cmd, {
-    runner,
-    mosaicHome: deps.mosaicHome,
-    // Resolve personas the SAME way reconcile does: forward any configured roots
-    // so a custom-persona-root deployment cannot have reconcile accept a roster
-    // that regen then rejects against the default `<mosaicHome>/fleet/roles`.
-    rolesDir: deps.reconcileDeps?.rolesDir,
-    overrideDir: deps.reconcileDeps?.overrideDir,
-  });
-
   return cmd;
 }
 
@@ -2405,19 +2389,14 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
 
 async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
   const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
-  return loadRosterAtPath(cmd, await resolveRosterPath(opts.mosaicHome, opts.roster));
+  return loadFleetRoster(await resolveRosterPath(opts.mosaicHome, opts.roster));
 }
 
 /** Routes only a v2 roster to the M3 desired-state control plane; v1 aliases stay compatible. */
 async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
   const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
   const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
-  let parsed: unknown;
-  try {
-    parsed = parseFleetRosterDocument(await readFleetRosterText(path), path);
-  } catch (error) {
-    reportFleetRosterConfigurationError(cmd, error);
-  }
+  const parsed: unknown = YAML.parse(await readFile(path, 'utf8'));
   return (
     typeof parsed === 'object' &&
     parsed !== null &&
@@ -2433,22 +2412,7 @@ async function loadRosterFromAgentCommand(
 ): Promise<FleetRoster> {
   const opts = command.optsWithGlobals<{ mosaicHome?: string; roster?: string }>();
   const mosaicHome = opts.mosaicHome ?? mosaicHomeOverride ?? defaultMosaicHome();
-  return loadRosterAtPath(command, await resolveRosterPath(mosaicHome, opts.roster));
-}
-
-async function loadRosterAtPath(command: Command, path: string): Promise<FleetRoster> {
-  try {
-    return await loadFleetRoster(path);
-  } catch (error) {
-    reportFleetRosterConfigurationError(command, error);
-  }
-}
-
-function reportFleetRosterConfigurationError(command: Command, error: unknown): never {
-  if (error instanceof FleetRosterConfigurationError) {
-    command.error(error.message, { code: 'fleet.roster', exitCode: 1 });
-  }
-  throw error;
+  return loadFleetRoster(await resolveRosterPath(mosaicHome, opts.roster));
 }
 
 function resolveMosaicHomeFromCommand(command: Command, override?: string): string {

packages/mosaic/src/commands/install-heading.spec.ts

@@ -1,17 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-
-const INSTALLER_PATH = fileURLToPath(new URL('../../../../tools/install.sh', import.meta.url));
-
-describe('installer CLI package heading', () => {
-  it('renders the scoped package name intact', async () => {
-    const installer = await readFile(INSTALLER_PATH, 'utf8');
-    const step = installer.match(/^step\(\)\s*\{.*\}$/m)?.[0];
-
-    expect(step).toBeDefined();
-
-    expect(step).toContain('printf \'\\n%s%s%s\\n\' "$BOLD" "$*" "$RESET"');
-    expect(installer).toContain('step "@mosaicstack/mosaic (npm package)"');
-  });
-});

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

@@ -9,7 +9,6 @@ import {
   piForceSkillNames,
   registerRuntimeLaunchers,
   type RuntimeLaunchHandler,
-  type ClaudexLaunchHandler,
 } from './launch.js';
 
 /**
@@ -32,16 +31,6 @@ function buildProgram(handler: RuntimeLaunchHandler): Command {
   return program;
 }
 
-function buildProgramWithClaudex(
-  handler: RuntimeLaunchHandler,
-  claudexHandler: ClaudexLaunchHandler,
-): Command {
-  const program = new Command();
-  program.exitOverride();
-  registerRuntimeLaunchers(program, handler, claudexHandler);
-  return program;
-}
-
 const fakeSkills = ['--skill', '/skills/test-driven-development', '--skill', '/skills/pdf'];
 const fakeForced = ['--skill', '/skills/mosaic-tools'];
 
@@ -291,61 +280,3 @@ describe('registerRuntimeLaunchers — yolo <runtime>', () => {
     expect(mockExit).toHaveBeenCalledWith(1);
   });
 });
-
-describe('registerRuntimeLaunchers — claudex (EXPERIMENTAL overlay)', () => {
-  let mockExit: MockInstance<typeof process.exit>;
-  let mockError: MockInstance<typeof console.error>;
-
-  beforeEach(() => {
-    mockExit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
-    mockError = vi.spyOn(console, 'error').mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    mockExit.mockRestore();
-    mockError.mockRestore();
-  });
-
-  it('dispatches `claudex` to the claudex handler (yolo=false), not the runtime handler', () => {
-    const handler = vi.fn();
-    const claudex = vi.fn();
-    const program = buildProgramWithClaudex(handler, claudex);
-    program.parse(['node', 'mosaic', 'claudex']);
-
-    expect(claudex).toHaveBeenCalledTimes(1);
-    expect(claudex).toHaveBeenCalledWith([], false);
-    expect(handler).not.toHaveBeenCalled();
-  });
-
-  it('forwards excess args after `claudex`', () => {
-    const handler = vi.fn();
-    const claudex = vi.fn();
-    const program = buildProgramWithClaudex(handler, claudex);
-    program.parse(['node', 'mosaic', 'claudex', '--print', 'hi']);
-
-    expect(claudex).toHaveBeenCalledWith(['--print', 'hi'], false);
-  });
-
-  it('dispatches `yolo claudex` with yolo=true and slices off the runtime name (#454)', () => {
-    const handler = vi.fn();
-    const claudex = vi.fn();
-    const program = buildProgramWithClaudex(handler, claudex);
-    program.parse(['node', 'mosaic', 'yolo', 'claudex']);
-
-    expect(claudex).toHaveBeenCalledTimes(1);
-    // extraArgs must be empty — the positional 'claudex' must not leak through.
-    expect(claudex).toHaveBeenCalledWith([], true);
-    expect(handler).not.toHaveBeenCalled();
-    expect(mockExit).not.toHaveBeenCalled();
-  });
-
-  it('forwards true excess args after `yolo claudex`', () => {
-    const handler = vi.fn();
-    const claudex = vi.fn();
-    const program = buildProgramWithClaudex(handler, claudex);
-    program.parse(['node', 'mosaic', 'yolo', 'claudex', '--model', 'gpt-5.6-sol']);
-
-    expect(claudex).toHaveBeenCalledWith(['--model', 'gpt-5.6-sol'], true);
-    expect(mockExit).not.toHaveBeenCalled();
-  });
-});

packages/mosaic/src/commands/launch.ts

@@ -27,7 +27,6 @@ import {
 import { readRegularFileSecure } from '../fleet/secure-file.js';
 import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
-import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
 
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 const MAX_INSTALLED_TOOLS_BYTES = 256 * 1024;
@@ -807,12 +806,12 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
 }
 
 /** exec into the runtime, replacing the current process. */
-function execRuntime(cmd: string, args: string[], env: NodeJS.ProcessEnv = process.env): void {
+function execRuntime(cmd: string, args: string[]): void {
   try {
     // Use execFileSync with inherited stdio to replace the process
     const result = spawnSync(cmd, args, {
       stdio: 'inherit',
-      env,
+      env: process.env,
     });
     process.exit(result.status ?? 0);
   } catch (err) {
@@ -821,29 +820,6 @@ function execRuntime(cmd: string, args: string[], env: NodeJS.ProcessEnv = proce
   }
 }
 
-/**
- * Production glue for `mosaic [yolo] claudex` (EXPERIMENTAL — GPT models inside
- * the Claude Code harness via claude-code-proxy). Assembles the real harness
- * adapter and delegates the security-critical composition + fail-closed
- * orchestration to `launchClaudex` in `claudex.ts`. Kept thin so the tested
- * logic lives in the DI module, not here.
- */
-function launchClaudexProduction(args: string[], yolo: boolean): void {
-  writeSessionLock('claude');
-  const adapter: ClaudexHarnessAdapter = {
-    harnessPreflight: () => {
-      checkMosaicHome();
-      checkFile(join(MOSAIC_HOME, 'AGENTS.md'), 'AGENTS.md');
-      checkSoul();
-      checkRuntime('claude');
-      checkSequentialThinking('claude');
-    },
-    composePrompt: () => buildRuntimePrompt('claude'),
-    exec: (cmd, cmdArgs, env) => execRuntime(cmd, cmdArgs, env),
-  };
-  void launchClaudex(args, yolo, adapter);
-}
-
 // ─── Framework script/tool delegation ───────────────────────────────────────
 
 function delegateToScript(scriptPath: string, args: string[], env?: Record<string, string>): never {
@@ -1058,25 +1034,12 @@ export type RuntimeLaunchHandler = (
   yolo: boolean,
 ) => void;
 
-/**
- * Handler invoked for `claudex` / `yolo claudex`. Kept separate from
- * `RuntimeLaunchHandler` because claudex is an EXPERIMENTAL harness overlay
- * (GPT-via-proxy), not one of the first-class runtimes. Exposed + injectable so
- * the commander wiring can be exercised without composing a real launch.
- */
-export type ClaudexLaunchHandler = (extraArgs: string[], yolo: boolean) => void;
-
 /**
  * Wire `<runtime>` and `yolo <runtime>` subcommands onto `program` using a
  * pluggable launch handler. Separated from `registerLaunchCommands` so tests
  * can inject a spy and verify argument forwarding.
  */
-export function registerRuntimeLaunchers(
-  program: Command,
-  handler: RuntimeLaunchHandler,
-  claudexHandler: ClaudexLaunchHandler = (extraArgs, yolo) =>
-    launchClaudexProduction(extraArgs, yolo),
-): void {
+export function registerRuntimeLaunchers(program: Command, handler: RuntimeLaunchHandler): void {
   for (const runtime of ['claude', 'codex', 'opencode', 'pi'] as const) {
     program
       .command(runtime)
@@ -1088,37 +1051,16 @@ export function registerRuntimeLaunchers(
       });
   }
 
-  // claudex — EXPERIMENTAL: GPT models inside the Claude Code harness via
-  // claude-code-proxy (ChatGPT-subscription OAuth). Isolated CLAUDE_CONFIG_DIR
-  // + zero-token-leak env injection live in claudex.ts.
-  program
-    .command('claudex')
-    .description('EXPERIMENTAL: launch Claude Code harness against GPT via claude-code-proxy')
-    .allowUnknownOption(true)
-    .allowExcessArguments(true)
-    .action((_opts: unknown, cmd: Command) => {
-      claudexHandler(cmd.args, false);
-    });
-
   program
     .command('yolo <runtime>')
-    .description(
-      'Launch a runtime in dangerous-permissions mode (claude|codex|opencode|pi|claudex)',
-    )
+    .description('Launch a runtime in dangerous-permissions mode (claude|codex|opencode|pi)')
     .allowUnknownOption(true)
     .allowExcessArguments(true)
     .action((runtime: string, _opts: unknown, cmd: Command) => {
-      // claudex is an EXPERIMENTAL overlay, not a RuntimeName — dispatch it
-      // before the runtime allowlist check. Slice off the positional runtime
-      // name for the same reason as below (#454).
-      if (runtime === 'claudex') {
-        claudexHandler(cmd.args.slice(1), true);
-        return;
-      }
       const valid: RuntimeName[] = ['claude', 'codex', 'opencode', 'pi'];
       if (!valid.includes(runtime as RuntimeName)) {
         console.error(
-          `[mosaic] ERROR: Unsupported yolo runtime '${runtime}'. Use: ${valid.join('|')}|claudex`,
+          `[mosaic] ERROR: Unsupported yolo runtime '${runtime}'. Use: ${valid.join('|')}`,
         );
         process.exit(1);
       }

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

@@ -1,466 +0,0 @@
-/**
- * Tests for `mosaic restore` (#791 PR2 Task 12).
- *
- * The durable pre-update snapshot (install.sh: make_durable_snapshot) writes the
- * operator-owned surface to $XDG_STATE_HOME/mosaic/backups/pre-update-<ts>/ with
- * 0700 dirs / 0600 files. `mosaic restore` is the recovery counterpart:
- *   • --list (default)   enumerate snapshots by timestamp — dry-run, never mutates.
- *   • --from <ts>        restore that snapshot over MOSAIC_HOME, confirmation-gated.
- * It reports counts and relative paths ONLY — a snapshot may contain secrets
- * (credentials.json), so no file content is ever printed (secrev invariant).
- */
-
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import {
-  mkdtempSync,
-  rmSync,
-  mkdirSync,
-  writeFileSync,
-  readFileSync,
-  statSync,
-  lstatSync,
-  symlinkSync,
-} from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir, homedir } from 'node:os';
-import { Command } from 'commander';
-import {
-  resolveBackupRoot,
-  listSnapshots,
-  resolveSnapshotDir,
-  planRestore,
-  applyRestore,
-  runRestore,
-  registerRestoreCommand,
-} from './restore.js';
-
-const SECRET = 'SUPER-SECRET-TOKEN-do-not-log-restore';
-
-function seedSnapshot(root: string, ts: string, files: Record<string, string>): string {
-  const dir = join(root, `pre-update-${ts}`);
-  for (const [rel, content] of Object.entries(files)) {
-    const abs = join(dir, rel);
-    mkdirSync(join(abs, '..'), { recursive: true });
-    writeFileSync(abs, content);
-  }
-  return dir;
-}
-
-describe('mosaic restore (#791 PR2)', () => {
-  let tmp: string;
-  let backups: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), 'mosaic-restore-'));
-    backups = join(tmp, 'state', 'mosaic', 'backups');
-    mkdirSync(backups, { recursive: true });
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  describe('resolveBackupRoot', () => {
-    it('honors XDG_STATE_HOME', () => {
-      expect(resolveBackupRoot({ XDG_STATE_HOME: '/x/state' })).toBe('/x/state/mosaic/backups');
-    });
-    it('falls back to ~/.local/state', () => {
-      expect(resolveBackupRoot({})).toBe(join(homedir(), '.local', 'state', 'mosaic', 'backups'));
-    });
-  });
-
-  describe('listSnapshots', () => {
-    it('returns [] when the backup root does not exist', () => {
-      expect(listSnapshots(join(tmp, 'nope'))).toEqual([]);
-    });
-
-    it('lists pre-update snapshots newest-first with file counts, ignoring other dirs', () => {
-      seedSnapshot(backups, '20240101T000000Z', { 'SOUL.md': 'a' });
-      seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'b', 'agents/x.conf': 'c' });
-      mkdirSync(join(backups, 'unrelated-dir'), { recursive: true });
-
-      const snaps = listSnapshots(backups);
-      expect(snaps.map((s) => s.timestamp)).toEqual(['20260101T000000Z', '20240101T000000Z']);
-      expect(snaps[0]!.fileCount).toBe(2);
-      expect(snaps[1]!.fileCount).toBe(1);
-    });
-  });
-
-  describe('resolveSnapshotDir', () => {
-    it('resolves by bare timestamp and by full pre-update-<ts> name', () => {
-      const dir = seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'a' });
-      expect(resolveSnapshotDir(backups, '20260101T000000Z')).toBe(dir);
-      expect(resolveSnapshotDir(backups, 'pre-update-20260101T000000Z')).toBe(dir);
-    });
-    it('returns undefined for an unknown timestamp', () => {
-      expect(resolveSnapshotDir(backups, '19990101T000000Z')).toBeUndefined();
-    });
-  });
-
-  describe('planRestore', () => {
-    it('walks nested dirs and returns every relative file path', () => {
-      const dir = seedSnapshot(backups, '20260101T000000Z', {
-        'SOUL.md': 'a',
-        'agents/x.conf': 'b',
-        'tools/_lib/credentials.json': 'c',
-      });
-      expect(planRestore(dir).sort()).toEqual(
-        ['SOUL.md', 'agents/x.conf', 'tools/_lib/credentials.json'].sort(),
-      );
-    });
-  });
-
-  describe('applyRestore', () => {
-    it('restores byte-exact content, creates parent dirs, and sets 0600', () => {
-      const dir = seedSnapshot(backups, '20260101T000000Z', {
-        'SOUL.md': 'original-soul',
-        'tools/_lib/credentials.json': `TOKEN=${SECRET}\n`,
-      });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      // A diverged operator file that restore must overwrite.
-      writeFileSync(join(home, 'SOUL.md'), 'CORRUPTED');
-
-      const n = applyRestore(dir, home, planRestore(dir));
-      expect(n).toBe(2);
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('original-soul');
-      expect(readFileSync(join(home, 'tools/_lib/credentials.json'), 'utf8')).toBe(
-        `TOKEN=${SECRET}\n`,
-      );
-      expect(statSync(join(home, 'SOUL.md')).mode & 0o777).toBe(0o600);
-      expect(statSync(join(home, 'tools/_lib/credentials.json')).mode & 0o777).toBe(0o600);
-    });
-  });
-
-  describe('runRestore', () => {
-    it('--list prints timestamps and counts, mutating nothing', async () => {
-      seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'a', 'agents/x.conf': 'b' });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-      const code = await runRestore({
-        list: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-
-      expect(code).toBe(0);
-      const out = log.mock.calls.flat().join('\n');
-      expect(out).toContain('20260101T000000Z');
-      expect(out).toMatch(/2\b/); // the file count is surfaced
-      log.mockRestore();
-    });
-
-    it('--from restores the snapshot over MOSAIC_HOME byte-exact (yes bypasses prompt)', async () => {
-      seedSnapshot(backups, '20260101T000000Z', {
-        'SOUL.md': 'restored-soul',
-        'tools/_lib/credentials.json': `TOKEN=${SECRET}\n`,
-      });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      writeFileSync(join(home, 'SOUL.md'), 'STALE');
-
-      const code = await runRestore({
-        from: '20260101T000000Z',
-        yes: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-
-      expect(code).toBe(0);
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('restored-soul');
-      expect(readFileSync(join(home, 'tools/_lib/credentials.json'), 'utf8')).toBe(
-        `TOKEN=${SECRET}\n`,
-      );
-    });
-
-    it('--from with an unknown timestamp fails without mutating', async () => {
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      writeFileSync(join(home, 'SOUL.md'), 'KEEP');
-      const err = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-      const code = await runRestore({
-        from: '19990101T000000Z',
-        yes: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-
-      expect(code).toBe(1);
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('KEEP');
-      err.mockRestore();
-    });
-
-    it('--dry-run with --from reports the plan but mutates nothing', async () => {
-      seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'snap' });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      writeFileSync(join(home, 'SOUL.md'), 'UNCHANGED');
-      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-      const code = await runRestore({
-        from: '20260101T000000Z',
-        dryRun: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-
-      expect(code).toBe(0);
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('UNCHANGED');
-      log.mockRestore();
-    });
-
-    it('--from prompts and applies the restore when the operator confirms', async () => {
-      seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'confirmed-soul' });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      writeFileSync(join(home, 'SOUL.md'), 'STALE');
-      vi.spyOn(console, 'log').mockImplementation(() => {});
-      const confirm = vi.fn().mockResolvedValue(true);
-
-      const code = await runRestore({
-        from: '20260101T000000Z',
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-        confirm,
-      });
-
-      expect(code).toBe(0);
-      expect(confirm).toHaveBeenCalledOnce();
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('confirmed-soul');
-    });
-
-    it('--from aborts without mutating when the operator declines', async () => {
-      seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'snap' });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      writeFileSync(join(home, 'SOUL.md'), 'KEEP');
-      vi.spyOn(console, 'log').mockImplementation(() => {});
-      const confirm = vi.fn().mockResolvedValue(false);
-
-      const code = await runRestore({
-        from: '20260101T000000Z',
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-        confirm,
-      });
-
-      expect(code).toBe(0);
-      expect(confirm).toHaveBeenCalledOnce();
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('KEEP');
-    });
-
-    it('MOSAIC_ASSUME_YES=1 bypasses the confirmation prompt', async () => {
-      seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'env-yes' });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      writeFileSync(join(home, 'SOUL.md'), 'STALE');
-      vi.spyOn(console, 'log').mockImplementation(() => {});
-      const confirm = vi.fn().mockResolvedValue(false);
-
-      const code = await runRestore({
-        from: '20260101T000000Z',
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state'), MOSAIC_ASSUME_YES: '1' },
-        confirm,
-      });
-
-      expect(code).toBe(0);
-      expect(confirm).not.toHaveBeenCalled();
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('env-yes');
-    });
-
-    it('--list reports gracefully when no snapshots exist', async () => {
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-      const code = await runRestore({
-        list: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'empty-state') },
-      });
-
-      expect(code).toBe(0);
-      expect(log.mock.calls.flat().join('\n')).toMatch(/No pre-update snapshots/);
-    });
-
-    it('never prints a secret value found inside a backed-up file', async () => {
-      seedSnapshot(backups, '20260101T000000Z', {
-        'tools/_lib/credentials.json': `TOKEN=${SECRET}\n`,
-      });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const err = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-      await runRestore({
-        list: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-      await runRestore({
-        from: '20260101T000000Z',
-        yes: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-
-      const all = [...log.mock.calls, ...err.mock.calls].flat().join('\n');
-      expect(all).not.toContain(SECRET);
-      log.mockRestore();
-      err.mockRestore();
-    });
-  });
-
-  // Regression coverage for the codex code+security review of PR2 (#791):
-  // CWE-22 traversal via --from, and CWE-59 symlink write-through in applyRestore.
-  describe('security hardening', () => {
-    it.each([
-      '../../etc',
-      'pre-update-/../../tmp/poison',
-      'pre-update-../evil',
-      '20260101T000000Z/../../../tmp',
-      'not-a-timestamp',
-      '2026-01-01',
-    ])('resolveSnapshotDir rejects traversal / malformed selector %j', (bad) => {
-      // Even if a matching directory exists on disk, a non-timestamp selector
-      // must not resolve — the only accepted shape is <8>T<6>Z[-n].
-      expect(resolveSnapshotDir(backups, bad)).toBeUndefined();
-    });
-
-    it('runRestore --from a traversal selector fails closed without copying', async () => {
-      // Plant a real dir one level ABOVE the backup root. The naive resolver
-      // `join(root, from)` with `from='../poison'` would reach it (backups is
-      // .../mosaic/backups, so `../poison` == .../mosaic/poison) and import it.
-      const outside = join(tmp, 'state', 'mosaic', 'poison');
-      mkdirSync(outside, { recursive: true });
-      writeFileSync(join(outside, 'x'), 'attacker');
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      const err = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-      const code = await runRestore({
-        from: '../poison',
-        yes: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-
-      expect(code).toBe(1);
-      expect(statSync(home).isDirectory()).toBe(true);
-      // Nothing from `outside` was imported.
-      expect(() => statSync(join(home, 'x'))).toThrow();
-      err.mockRestore();
-    });
-
-    it('applyRestore refuses to write a secret through a symlinked leaf (CWE-59)', () => {
-      const dir = seedSnapshot(backups, '20260101T000000Z', {
-        'tools/_lib/credentials.json': `TOKEN=${SECRET}\n`,
-      });
-      const home = join(tmp, 'home');
-      mkdirSync(join(home, 'tools', '_lib'), { recursive: true });
-      // Attacker points the operator credentials file at a file they can read.
-      const exfil = join(tmp, 'exfil-target');
-      writeFileSync(exfil, 'original-attacker-content');
-      symlinkSync(exfil, join(home, 'tools', '_lib', 'credentials.json'));
-
-      expect(() => applyRestore(dir, home, planRestore(dir))).toThrow();
-      // The secret was NOT written through the link into the attacker's file.
-      expect(readFileSync(exfil, 'utf8')).toBe('original-attacker-content');
-    });
-
-    it('applyRestore refuses to write through a symlinked ancestor (CWE-59)', () => {
-      const dir = seedSnapshot(backups, '20260101T000000Z', {
-        'tools/_lib/credentials.json': `TOKEN=${SECRET}\n`,
-      });
-      const home = join(tmp, 'home');
-      mkdirSync(join(home, 'tools'), { recursive: true });
-      // Attacker replaces the `tools/_lib` ancestor with a symlink out of the root.
-      const exfilDir = join(tmp, 'exfil-dir');
-      mkdirSync(exfilDir, { recursive: true });
-      symlinkSync(exfilDir, join(home, 'tools', '_lib'));
-
-      expect(() => applyRestore(dir, home, planRestore(dir))).toThrow();
-      // Nothing was written into the attacker-controlled directory.
-      expect(() => statSync(join(exfilDir, 'credentials.json'))).toThrow();
-    });
-
-    it('runRestore surfaces a symlink violation as exit 1 without leaking the secret', async () => {
-      seedSnapshot(backups, '20260101T000000Z', {
-        'tools/_lib/credentials.json': `TOKEN=${SECRET}\n`,
-      });
-      const home = join(tmp, 'home');
-      mkdirSync(join(home, 'tools', '_lib'), { recursive: true });
-      const exfil = join(tmp, 'exfil-target');
-      writeFileSync(exfil, 'attacker');
-      symlinkSync(exfil, join(home, 'tools', '_lib', 'credentials.json'));
-      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const err = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-      const code = await runRestore({
-        from: '20260101T000000Z',
-        yes: true,
-        mosaicHome: home,
-        env: { XDG_STATE_HOME: join(tmp, 'state') },
-      });
-
-      expect(code).toBe(1);
-      expect(readFileSync(exfil, 'utf8')).toBe('attacker');
-      const all = [...log.mock.calls, ...err.mock.calls].flat().join('\n');
-      expect(all).not.toContain(SECRET);
-      log.mockRestore();
-      err.mockRestore();
-    });
-
-    it('applyRestore replaces a diverged regular file in place with 0600 (not a symlink)', () => {
-      const dir = seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'restored' });
-      const home = join(tmp, 'home');
-      mkdirSync(home, { recursive: true });
-      writeFileSync(join(home, 'SOUL.md'), 'stale');
-
-      const n = applyRestore(dir, home, planRestore(dir));
-      expect(n).toBe(1);
-      expect(lstatSync(join(home, 'SOUL.md')).isSymbolicLink()).toBe(false);
-      expect(readFileSync(join(home, 'SOUL.md'), 'utf8')).toBe('restored');
-      expect(statSync(join(home, 'SOUL.md')).mode & 0o777).toBe(0o600);
-    });
-  });
-
-  describe('registerRestoreCommand', () => {
-    it('registers `restore` with the expected flags', () => {
-      const program = new Command();
-      program.exitOverride();
-      registerRestoreCommand(program);
-      const cmd = program.commands.find((c) => c.name() === 'restore');
-      expect(cmd).toBeDefined();
-      const longs = cmd!.options.map((o) => o.long);
-      expect(longs).toEqual(
-        expect.arrayContaining(['--list', '--from', '--dry-run', '--yes', '--mosaic-home']),
-      );
-    });
-
-    it('runs the list action end-to-end via the parsed command', async () => {
-      seedSnapshot(backups, '20260101T000000Z', { 'SOUL.md': 'a' });
-      const prevXdg = process.env['XDG_STATE_HOME'];
-      process.env['XDG_STATE_HOME'] = join(tmp, 'state');
-      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-      try {
-        const program = new Command();
-        program.exitOverride();
-        registerRestoreCommand(program);
-        await program.parseAsync(['restore', '--list', '--mosaic-home', join(tmp, 'home')], {
-          from: 'user',
-        });
-        expect(log.mock.calls.flat().join('\n')).toContain('20260101T000000Z');
-      } finally {
-        log.mockRestore();
-        if (prevXdg === undefined) delete process.env['XDG_STATE_HOME'];
-        else process.env['XDG_STATE_HOME'] = prevXdg;
-      }
-    });
-  });
-});

packages/mosaic/src/commands/restore.ts

@@ -1,313 +0,0 @@
-/**
- * restore.ts — top-level `mosaic restore` command (#791 PR2 Task 12)
- *
- * Recovery counterpart to the durable pre-update snapshot taken by install.sh
- * (make_durable_snapshot). Before a keep-mode upgrade mutates anything, the
- * installer copies the operator-owned surface to
- *   $XDG_STATE_HOME/mosaic/backups/pre-update-<UTC-ts>/   (0700 dirs / 0600 files)
- * This command lets the operator inspect and roll back to those snapshots:
- *
- *   mosaic restore                 # == --list: enumerate snapshots (dry-run)
- *   mosaic restore --list
- *   mosaic restore --from <ts>     # restore that snapshot over MOSAIC_HOME
- *   mosaic restore --from <ts> --dry-run
- *
- * SECREV INVARIANT: a snapshot may contain secrets (e.g. tools/_lib/credentials.json).
- * This command reports counts and RELATIVE PATHS only — it never reads a backed-up
- * file into any logged string. Restored files are written back 0600 (owner-only),
- * matching the snapshot's own private posture. The path convention here mirrors
- * install.sh `backup_root()`; keep the two in sync (no shared code across the boundary).
- */
-
-import {
-  existsSync,
-  readdirSync,
-  statSync,
-  lstatSync,
-  readFileSync,
-  openSync,
-  writeSync,
-  fchmodSync,
-  closeSync,
-  constants,
-} from 'node:fs';
-import { createInterface } from 'node:readline';
-import { homedir } from 'node:os';
-import { join, dirname, relative } from 'node:path';
-import type { Command } from 'commander';
-import { DEFAULT_MOSAIC_HOME } from '../constants.js';
-import { assertCanonicalContainment, ensureManagedDirectory } from '../fleet/secure-file.js';
-
-// ─── types ───────────────────────────────────────────────────────────────────
-
-export interface SnapshotInfo {
-  /** The UTC stamp after the `pre-update-` prefix, e.g. "20260716T232225Z". */
-  readonly timestamp: string;
-  /** Absolute path to the snapshot directory. */
-  readonly dir: string;
-  /** Number of files captured in the snapshot. */
-  readonly fileCount: number;
-}
-
-export interface RestoreOptions {
-  list?: boolean;
-  from?: string;
-  dryRun?: boolean;
-  yes?: boolean;
-  mosaicHome: string;
-  /** Environment source (injectable for tests); defaults to process.env. */
-  env?: NodeJS.ProcessEnv;
-  /**
-   * Confirmation gate (injectable for tests); defaults to an interactive
-   * readline prompt. Returns true to proceed with the overwrite.
-   */
-  confirm?: (question: string) => Promise<boolean>;
-}
-
-const SNAPSHOT_PREFIX = 'pre-update-';
-
-/**
- * The exact shape install.sh `make_durable_snapshot()` stamps: `<8>T<6>Z` UTC,
- * with an optional `-<n>` same-second collision suffix. `--from` is matched
- * against this — nothing containing a path separator or `..` can pass, so a
- * selector can never escape the backup root (CWE-22).
- */
-const SNAPSHOT_TS_RE = /^\d{8}T\d{6}Z(?:-\d+)?$/;
-
-// ─── pure helpers ─────────────────────────────────────────────────────────────
-
-/** Resolve the durable-snapshot root, mirroring install.sh `backup_root()`. */
-export function resolveBackupRoot(env: NodeJS.ProcessEnv = process.env): string {
-  const stateHome = env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
-  return join(stateHome, 'mosaic', 'backups');
-}
-
-/** Recursively collect every file under `dir` as a path relative to `dir`. */
-export function planRestore(dir: string): string[] {
-  const out: string[] = [];
-  const walk = (cur: string): void => {
-    for (const entry of readdirSync(cur, { withFileTypes: true })) {
-      const abs = join(cur, entry.name);
-      if (entry.isDirectory()) {
-        walk(abs);
-      } else if (entry.isFile()) {
-        out.push(relative(dir, abs));
-      }
-    }
-  };
-  if (existsSync(dir)) walk(dir);
-  return out;
-}
-
-/** Enumerate snapshots newest-first (the `pre-update-<ts>` names sort chronologically). */
-export function listSnapshots(root: string): SnapshotInfo[] {
-  if (!existsSync(root)) return [];
-  let entries: string[];
-  try {
-    entries = readdirSync(root);
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((name) => name.startsWith(SNAPSHOT_PREFIX))
-    .map((name) => join(root, name))
-    .filter((dir) => {
-      try {
-        return statSync(dir).isDirectory();
-      } catch {
-        return false;
-      }
-    })
-    .sort()
-    .reverse()
-    .map((dir) => ({
-      timestamp: dir.split('/').at(-1)!.slice(SNAPSHOT_PREFIX.length),
-      dir,
-      fileCount: planRestore(dir).length,
-    }));
-}
-
-/**
- * Resolve a snapshot dir from a `--from` selector. Accepts ONLY a strict
- * generated identifier — a bare `<ts>` or the full `pre-update-<ts>` name — and
- * builds exactly `join(root, 'pre-update-' + ts)`. A selector containing `/`,
- * `..`, or anything but the timestamp shape is rejected (returns undefined), so
- * `--from` can never traverse outside the backup root (CWE-22). The resolved dir
- * must be a real, non-symlink directory (lstat, not stat), so a symlinked
- * snapshot entry can't redirect the restore either.
- */
-export function resolveSnapshotDir(root: string, from: string): string | undefined {
-  const ts = from.startsWith(SNAPSHOT_PREFIX) ? from.slice(SNAPSHOT_PREFIX.length) : from;
-  if (!SNAPSHOT_TS_RE.test(ts)) return undefined;
-  const dir = join(root, `${SNAPSHOT_PREFIX}${ts}`);
-  try {
-    if (lstatSync(dir).isDirectory()) return dir;
-  } catch {
-    /* absent or inaccessible */
-  }
-  return undefined;
-}
-
-/**
- * Copy each `relPaths` entry from the snapshot back into `mosaicHome`, forcing
- * 0600 on the restored file (owner-only — the operator surface may hold secrets).
- * Returns the number of files restored. Never reads a file's content into a
- * logged string.
- *
- * SYMLINK-SAFE (CWE-59): a snapshot may hold secrets, so we must never let a
- * tampered destination redirect the write. Every destination path is contained
- * within `mosaicHome` (assertCanonicalContainment) and every ancestor is proven
- * to be a real, non-symlink directory (ensureManagedDirectory) before we write.
- * The leaf itself is opened O_NOFOLLOW, so if it was swapped for a symlink the
- * open fails closed (ELOOP) rather than writing the secret through the link.
- */
-export function applyRestore(
-  snapDir: string,
-  mosaicHome: string,
-  relPaths: readonly string[],
-): number {
-  let restored = 0;
-  for (const rel of relPaths) {
-    const src = join(snapDir, rel);
-    const dst = join(mosaicHome, rel);
-    // Fail closed if the target path escapes the managed root or any ancestor is
-    // a symlink; create missing ancestors as private (0700) real directories.
-    assertCanonicalContainment(mosaicHome, dst);
-    ensureManagedDirectory(mosaicHome, dirname(dst));
-    // O_NOFOLLOW: refuse to follow a symlink at the leaf (secret exfil guard).
-    // O_CREAT|O_TRUNC: create a fresh 0600 file, or overwrite a diverged real one.
-    const fd = openSync(
-      dst,
-      constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW,
-      0o600,
-    );
-    try {
-      fchmodSync(fd, 0o600); // enforce 0600 even when the file pre-existed
-      writeSync(fd, readFileSync(src));
-    } finally {
-      closeSync(fd);
-    }
-    restored += 1;
-  }
-  return restored;
-}
-
-// ─── orchestration ────────────────────────────────────────────────────────────
-
-async function promptConfirm(question: string): Promise<boolean> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    return await new Promise<boolean>((resolve) => {
-      rl.question(`${question} [y/N] `, (ans) => resolve(ans.trim().toLowerCase() === 'y'));
-    });
-  } finally {
-    rl.close();
-  }
-}
-
-/**
- * Run `mosaic restore`. Returns a process exit code (0 ok, 1 error) rather than
- * calling process.exit, so it stays unit-testable.
- */
-export async function runRestore(opts: RestoreOptions): Promise<number> {
-  const env = opts.env ?? process.env;
-  const root = resolveBackupRoot(env);
-
-  // Default action (and explicit --list): enumerate, never mutate.
-  if (opts.list || !opts.from) {
-    const snaps = listSnapshots(root);
-    if (snaps.length === 0) {
-      console.log(`No pre-update snapshots found under ${root}.`);
-      return 0;
-    }
-    console.log(`Pre-update snapshots under ${root} (newest first):\n`);
-    for (const s of snaps) {
-      console.log(`  ${s.timestamp}  —  ${s.fileCount} file(s)`);
-    }
-    console.log(`\nRestore one with:  mosaic restore --from <timestamp>`);
-    return 0;
-  }
-
-  // --from <ts>: restore over the operator surface.
-  const snapDir = resolveSnapshotDir(root, opts.from);
-  if (!snapDir) {
-    console.error(`No snapshot matching '${opts.from}' under ${root}.`);
-    console.error(`Run 'mosaic restore --list' to see available timestamps.`);
-    return 1;
-  }
-
-  const relPaths = planRestore(snapDir);
-  const ts = snapDir.split('/').at(-1)!.slice(SNAPSHOT_PREFIX.length);
-
-  if (opts.dryRun) {
-    console.log(
-      `[dry-run] Would restore ${relPaths.length} file(s) from snapshot ${ts} into ${opts.mosaicHome}:`,
-    );
-    for (const rel of relPaths) console.log(`  ${rel}`);
-    console.log('[dry-run] No changes made.');
-    return 0;
-  }
-
-  const assumeYes = opts.yes || env['MOSAIC_ASSUME_YES'] === '1';
-  if (!assumeYes) {
-    console.log(
-      `About to restore ${relPaths.length} operator file(s) from snapshot ${ts} into ${opts.mosaicHome}.`,
-    );
-    console.log('This OVERWRITES those files with their pre-update contents.');
-    const ok = await (opts.confirm ?? promptConfirm)('Proceed?');
-    if (!ok) {
-      console.log('Restore cancelled. No changes made.');
-      return 0;
-    }
-  }
-
-  let n: number;
-  try {
-    n = applyRestore(snapDir, opts.mosaicHome, relPaths);
-  } catch (err) {
-    // A containment/symlink violation is a fail-closed security stop, not a
-    // routine error — surface it without leaking file contents and abort.
-    console.error(
-      `Restore aborted: a destination path under ${opts.mosaicHome} is unsafe to write ` +
-        `(symlink or escapes the managed root). No files were restored. (${(err as Error).message})`,
-    );
-    return 1;
-  }
-  console.log(`Restored ${n} operator file(s) from snapshot ${ts} into ${opts.mosaicHome}.`);
-  return 0;
-}
-
-// ─── commander registration ───────────────────────────────────────────────────
-
-export function registerRestoreCommand(program: Command): void {
-  program
-    .command('restore')
-    .description('List or restore durable pre-update snapshots of your operator config (#791)')
-    .option('--list', 'List available snapshots by timestamp (default action)')
-    .option('--from <timestamp>', 'Restore the snapshot with this timestamp over MOSAIC_HOME')
-    .option('--dry-run', 'With --from: show what would be restored without changing anything')
-    .option('--yes, -y', 'Skip the confirmation prompt (also: MOSAIC_ASSUME_YES=1)')
-    .option(
-      '--mosaic-home <path>',
-      'Override MOSAIC_HOME directory',
-      process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME,
-    )
-    .action(
-      async (opts: {
-        list?: boolean;
-        from?: string;
-        dryRun?: boolean;
-        yes?: boolean;
-        mosaicHome: string;
-      }) => {
-        const code = await runRestore({
-          list: opts.list,
-          from: opts.from,
-          dryRun: opts.dryRun,
-          yes: opts.yes,
-          mosaicHome: opts.mosaicHome,
-        });
-        if (code !== 0) process.exit(code);
-      },
-    );
-}

packages/mosaic/src/fleet/fleet-agent-crud.ts

@@ -381,22 +381,6 @@ function isMissingFile(error: unknown): boolean {
   return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
 
-/**
- * Non-blocking acquire of the roster mutation lock: an exclusive `wx` create that
- * throws `concurrent-mutation` (never waits) if the lock is already held. The
- * on-disk format is an empty private file. CRUD releases in a plain `finally` with
- * no result-preservation logic, so a release fault here must not override the
- * mutation result — the release swallows unlink failures by design.
- *
- * The recovery-framed `fleet regen` contends on this exact same lock file, but it
- * does so through the hardened, ownership-proving acquirer in the reconciler
- * (`acquirePrivateRosterMutationLock`), not this one: whoever wins the `wx` create
- * owns the file (the loser always gets `concurrent-mutation`), so the reconciler's
- * ownership token is only ever written and read back by the same regen invocation,
- * never by this empty-file writer. The two acquirers stay mutually compatible at
- * the `wx`-contention layer while regen additionally proves ownership before it
- * unlinks — a guarantee CRUD does not need because it releases unconditionally.
- */
 async function acquireMutationLock(lockPath: string): Promise<() => Promise<void>> {
   try {
     const handle = await open(lockPath, 'wx', 0o600);

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

@@ -584,29 +584,6 @@ function defaultValidateRoster(
   };
 }
 
-/**
- * The single roster-v2 → generated-projection mapping. Both the reconciler's
- * apply path ({@link defaultPrepareProjections}) and the recovery-framed
- * `mosaic fleet regen` command derive their generated env from THIS one
- * function, so the two paths can never drift (the #791 single-SSOT invariant).
- * Pure: no IO, no clock — a deterministic function of the roster alone.
- */
-export function projectRosterV2AgentGeneratedEnv(
-  roster: FleetRosterV2,
-  agent: FleetRosterV2Agent,
-): Readonly<Record<string, string>> {
-  return {
-    MOSAIC_AGENT_NAME: agent.name,
-    MOSAIC_AGENT_CLASS: agent.className,
-    MOSAIC_AGENT_RUNTIME: agent.runtime,
-    MOSAIC_AGENT_MODEL: agent.model,
-    MOSAIC_AGENT_REASONING: agent.reasoning,
-    MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy,
-    MOSAIC_AGENT_WORKDIR: agent.workingDirectory,
-    MOSAIC_TMUX_SOCKET: roster.tmux.socketName,
-  };
-}
-
 function defaultPrepareProjections(
   request: FleetReconcileRequest,
 ): (roster: FleetRosterV2) => Promise<readonly PreparedAgentEnvironmentProjection[]> {
@@ -619,7 +596,16 @@ function defaultPrepareProjections(
             mosaicHome,
             agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
             agentName: agent.name,
-            generated: projectRosterV2AgentGeneratedEnv(roster, agent),
+            generated: {
+              MOSAIC_AGENT_NAME: agent.name,
+              MOSAIC_AGENT_CLASS: agent.className,
+              MOSAIC_AGENT_RUNTIME: agent.runtime,
+              MOSAIC_AGENT_MODEL: agent.model,
+              MOSAIC_AGENT_REASONING: agent.reasoning,
+              MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy,
+              MOSAIC_AGENT_WORKDIR: agent.workingDirectory,
+              MOSAIC_TMUX_SOCKET: roster.tmux.socketName,
+            },
           }),
       ),
     );
@@ -634,193 +620,62 @@ function mosaicHomeFor(deps: FleetReconcileDeps): string {
   return deps.mosaicHome ?? join(homedir(), '.config', 'mosaic');
 }
 
-/** Acquires the private reconcile lock only after proving the canonical managed path. */
+/** Acquires a private lock only after proving the canonical managed path. */
 export function acquirePrivateReconcileLock(
   mosaicHome: string,
   openLock: typeof open = open,
-): () => Promise<() => Promise<void>> {
-  return acquirePrivateManagedRosterLock(
-    mosaicHome,
-    'roster.yaml.reconcile.lock',
-    'Another roster reconciliation is in progress.',
-    openLock,
-  );
-}
-
-/**
- * Acquires the private roster MUTATION lock (`roster.yaml.mutation.lock`) with the
- * exact same ownership-proof discipline as the reconcile lock. Exposed so the
- * recovery-framed `mosaic fleet regen` can serialize its projection rewrites
- * against agent CRUD — which holds this very lock while it rewrites the roster and
- * the same derived projections — reusing this hardened acquirer rather than
- * reimplementing it.
- *
- * The release PROVES ownership (device/inode + token) before unlinking, so a lock
- * that was already cleared and replaced by the time release runs is never deleted
- * out from under the new owner (it fails closed as `lock-cleanup-failed` instead),
- * and that cleanup fault is propagated to the caller rather than silently dropped.
- * CRUD contends on the identical path with a plain empty-file `wx` create; the two
- * never co-own it (whoever wins `wx` owns it; the loser gets `concurrent-mutation`),
- * so the token this writes is only ever read back by the same regen invocation that
- * wrote it.
- *
- * SCOPE of the guarantee (matches the merged reconcile lock exactly — see
- * {@link acquirePrivateManagedRosterLock}): the ownership proof closes the
- * *reachable* window — a stale-lock reaper or operator cleared our lock and another
- * writer took it BEFORE our release began — not the residual sub-instruction window
- * between the final check and the path-based `unlink`. Closing that residual fully
- * requires an fd-held advisory lock adopted by every fleet writer (CRUD, reconcile,
- * regen), which is a cross-cutting mechanism change out of scope for this
- * projection-only recovery command; it is unreachable within the `wx` writer
- * protocol regardless (no Mosaic writer removes a lock it does not own, so only
- * external interference can vacate our inode mid-release).
- */
-export function acquirePrivateRosterMutationLock(
-  mosaicHome: string,
-  openLock: typeof open = open,
-): () => Promise<() => Promise<void>> {
-  return acquirePrivateManagedRosterLock(
-    mosaicHome,
-    'roster.yaml.mutation.lock',
-    'Another roster mutation is in progress.',
-    openLock,
-  );
-}
-
-/**
- * Shared body for the ownership-proving managed roster locks. Acquires `lockLeaf`
- * under `<mosaicHome>/fleet` with a private `wx` create, writes an ownership token,
- * and returns a release that re-proves device/inode + token before unlinking so it
- * can never remove a lock it no longer owns. Non-blocking: throws `concurrent-mutation`
- * (with `busyMessage`) on contention rather than waiting.
- */
-function acquirePrivateManagedRosterLock(
-  mosaicHome: string,
-  lockLeaf: string,
-  busyMessage: string,
-  openLock: typeof open,
 ): () => Promise<() => Promise<void>> {
   const fleetDir = join(mosaicHome, 'fleet');
-  const lockPath = join(fleetDir, lockLeaf);
-  // The message-producing helpers below serve BOTH managed locks, so every fault
-  // names the actual lock file (`fleet/<leaf>`) — an operator needs to know WHICH
-  // lock is stale, not a hardcoded "reconciliation lock".
-  const lockLabel = `fleet/${lockLeaf}`;
+  const lockPath = join(fleetDir, 'roster.yaml.reconcile.lock');
   return async (): Promise<() => Promise<void>> => {
     await assertPrivateManagedDirectory(mosaicHome);
     await assertPrivateManagedDirectory(fleetDir);
-    await assertSafeLockLeafIfPresent(lockPath, lockLabel);
+    await assertSafeLockLeafIfPresent(lockPath);
 
     let handle: FileHandle;
     try {
       handle = await openLock(lockPath, 'wx', 0o600);
     } catch (error: unknown) {
       if (isCode(error, 'EEXIST')) {
-        await assertSafeLockLeafIfPresent(lockPath, lockLabel);
-        throw new FleetReconcileError('concurrent-mutation', busyMessage);
+        await assertSafeLockLeafIfPresent(lockPath);
+        throw new FleetReconcileError(
+          'concurrent-mutation',
+          'Another roster reconciliation is in progress.',
+        );
       }
-      throw new FleetReconcileError('lock-io-failed', `The ${lockLabel} lock cannot be created.`);
+      throw new FleetReconcileError('lock-io-failed', 'The reconciliation lock cannot be created.');
     }
 
-    // Identity of the lock WE exclusively created (the `wx` create guaranteed it is
-    // ours). Captured up front so both the release closure and the init-failure
-    // cleanup below can prove ownership by device/inode before touching the file.
-    const created = await handle.stat().catch((): undefined => undefined);
-
     const token = randomUUID();
-    let tokenPersisted = false;
     try {
       await handle.writeFile(`${token}\n`, 'utf8');
-      tokenPersisted = true;
+      const opened = await handle.stat();
       await handle.close();
-      if (!created)
-        throw new FleetReconcileError(
-          'lock-io-failed',
-          `The ${lockLabel} lock cannot be initialized.`,
-        );
-      await assertLockOwnership(
-        lockPath,
-        created.dev,
-        created.ino,
-        token,
-        'unsafe-lock',
-        lockLabel,
-      );
+      await assertLockOwnership(lockPath, opened.dev, opened.ino, token, 'unsafe-lock');
       return async (): Promise<void> => {
         try {
-          await assertLockOwnership(
-            lockPath,
-            created.dev,
-            created.ino,
-            token,
-            'lock-cleanup-failed',
-            lockLabel,
-          );
+          await assertLockOwnership(lockPath, opened.dev, opened.ino, token, 'lock-cleanup-failed');
+          await assertLockOwnership(lockPath, opened.dev, opened.ino, token, 'lock-cleanup-failed');
           await unlink(lockPath);
         } catch (error: unknown) {
           if (error instanceof FleetReconcileError) throw error;
-          throw new FleetReconcileError('lock-cleanup-failed', `The ${lockLabel} cleanup failed.`);
+          throw new FleetReconcileError(
+            'lock-cleanup-failed',
+            'The reconciliation lock cleanup failed.',
+          );
         }
       };
     } catch (error: unknown) {
       await handle.close().catch((): void => {});
-      // Best-effort: remove the lock THIS invocation created so a transient init
-      // fault does not strand a lock that would block future regen and agent CRUD.
-      // dev/ino-guarded so it can never delete a replacement; swallowed so cleanup
-      // failure never masks the initialization error being surfaced. The token is
-      // passed only once persisted, so the fallback path (when the post-create stat
-      // failed and dev/ino is unavailable) can still prove ownership by content.
-      await removeOwnedLockLeafBestEffort(lockPath, created, tokenPersisted ? token : undefined);
       if (error instanceof FleetReconcileError) throw error;
       throw new FleetReconcileError(
         'lock-io-failed',
-        `The ${lockLabel} lock cannot be initialized.`,
+        'The reconciliation lock cannot be initialized.',
       );
     }
   };
 }
 
-/**
- * Best-effort removal of a managed lock leaf THIS process created, used only on the
- * initialization-failure path. Two independent ownership proofs, so a lock that was
- * already replaced is never deleted:
- *
- *   - primary: the captured device/inode of the file we exclusively `wx`-created; or
- *   - fallback: when the post-create stat itself failed (dev/ino unavailable), the
- *     random `ownershipToken` we persisted — only OUR lock carries it, so a CRUD
- *     (empty) or a differently-tokened replacement is never removed.
- *
- * Every fault is swallowed because the caller is already surfacing the initialization
- * error and a leftover lock is recoverable via the documented runbook. If BOTH proofs
- * are unavailable (stat failed AND the token write never landed) the lock is left in
- * place rather than risk deleting another writer's file — a doubly-degenerate case
- * requiring two independent fs faults on a just-created fd.
- */
-async function removeOwnedLockLeafBestEffort(
-  lockPath: string,
-  created: { dev: number; ino: number } | undefined,
-  ownershipToken: string | undefined,
-): Promise<void> {
-  try {
-    const current = await lstat(lockPath);
-    if (!current.isFile() || current.isSymbolicLink()) return;
-    if (created) {
-      if (current.dev === created.dev && current.ino === created.ino) {
-        await unlink(lockPath);
-      }
-      return;
-    }
-    if (ownershipToken !== undefined) {
-      const contents = await readFile(lockPath, 'utf8');
-      if (contents.trim() === ownershipToken) {
-        await unlink(lockPath);
-      }
-    }
-  } catch {
-    // Swallowed: leftover lock is recoverable; do not mask the init error.
-  }
-}
-
 async function assertPrivateManagedDirectory(path: string): Promise<void> {
   try {
     const metadata = await lstat(path);
@@ -836,16 +691,16 @@ async function assertPrivateManagedDirectory(path: string): Promise<void> {
   }
 }
 
-async function assertSafeLockLeafIfPresent(lockPath: string, lockLabel: string): Promise<void> {
+async function assertSafeLockLeafIfPresent(lockPath: string): Promise<void> {
   try {
     const metadata = await lstat(lockPath);
     if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o077) !== 0) {
-      throw new FleetReconcileError('unsafe-lock', `The ${lockLabel} lock path is unsafe.`);
+      throw new FleetReconcileError('unsafe-lock', 'The reconciliation lock path is unsafe.');
     }
   } catch (error: unknown) {
     if (isCode(error, 'ENOENT')) return;
     if (error instanceof FleetReconcileError) throw error;
-    throw new FleetReconcileError('unsafe-lock', `The ${lockLabel} lock path is unavailable.`);
+    throw new FleetReconcileError('unsafe-lock', 'The reconciliation lock path is unavailable.');
   }
 }
 
@@ -855,7 +710,6 @@ async function assertLockOwnership(
   inode: number,
   token: string,
   failureCode: 'unsafe-lock' | 'lock-cleanup-failed',
-  lockLabel: string,
 ): Promise<void> {
   try {
     const metadata = await lstat(lockPath);
@@ -866,21 +720,24 @@ async function assertLockOwnership(
       metadata.dev !== device ||
       metadata.ino !== inode
     ) {
-      throw new FleetReconcileError(failureCode, `The ${lockLabel} ownership changed.`);
+      throw new FleetReconcileError(failureCode, 'The reconciliation lock ownership changed.');
     }
     const handle = await open(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
       const opened = await handle.stat();
       const contents = await handle.readFile({ encoding: 'utf8' });
       if (opened.dev !== device || opened.ino !== inode || contents !== `${token}\n`) {
-        throw new FleetReconcileError(failureCode, `The ${lockLabel} ownership changed.`);
+        throw new FleetReconcileError(failureCode, 'The reconciliation lock ownership changed.');
       }
     } finally {
       await handle.close();
     }
   } catch (error: unknown) {
     if (error instanceof FleetReconcileError) throw error;
-    throw new FleetReconcileError(failureCode, `The ${lockLabel} ownership cannot be proven.`);
+    throw new FleetReconcileError(
+      failureCode,
+      'The reconciliation lock ownership cannot be proven.',
+    );
   }
 }
 

packages/mosaic/src/fleet/fleet-roster-v1.ts

@@ -104,10 +104,6 @@ export interface FleetRoster {
 
 export type FleetRosterInputFormat = 'yaml' | 'json';
 
-export class FleetRosterConfigurationError extends Error {
-  override name = 'FleetRosterConfigurationError';
-}
-
 export function resolveInstalledFleetRosterPath(mosaicHome: string): string {
   const yamlPath = join(mosaicHome, 'fleet', 'roster.yaml');
   try {
@@ -142,52 +138,8 @@ export function parseFleetRosterV1(
 }
 
 export async function loadFleetRoster(path: string): Promise<FleetRoster> {
-  const source = await readFleetRosterText(path);
-  try {
-    return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
-  } catch (error) {
-    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
-    throw error;
-  }
-}
-
-/** Read an operator-owned roster with errors that say how to recover. */
-export async function readFleetRosterText(path: string): Promise<string> {
-  try {
-    return await readFile(path, 'utf8');
-  } catch (error) {
-    if (isNodeErrorCode(error, 'ENOENT')) {
-      throw new FleetRosterConfigurationError(
-        `No fleet roster found at ${path}. Run \`mosaic fleet init\` to create one.`,
-      );
-    }
-    throw new FleetRosterConfigurationError(
-      `Could not read fleet roster at ${path}. Check the file exists and is readable.`,
-    );
-  }
-}
-
-/** Parse a roster document needed only to select the v1/v2 command path. */
-export function parseFleetRosterDocument(source: string, path: string): unknown {
-  try {
-    return YAML.parse(source);
-  } catch (error) {
-    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
-    throw error;
-  }
-}
-
-function invalidFleetRosterError(path: string): FleetRosterConfigurationError {
-  return new FleetRosterConfigurationError(
-    `Fleet roster at ${path} is invalid. Fix the file or run \`mosaic fleet init --force\`.`,
-  );
-}
-
-function isRosterParserError(error: unknown): boolean {
-  return (
-    error instanceof SyntaxError ||
-    (error instanceof Error && (error.name === 'YAMLParseError' || error.name === 'YAMLWarning'))
-  );
+  const source = await readFile(path, 'utf8');
+  return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
 }
 
 export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {

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

@@ -204,53 +204,6 @@ export async function prepareAgentEnvironmentProjection(
   };
 }
 
-/** A generated-only projection validated without touching any legacy/local/quarantine file. */
-export interface PreparedGeneratedAgentEnvironmentProjection {
-  readonly mosaicHome: string;
-  readonly agentEnvDir: string;
-  readonly generatedPath: string;
-  readonly generated: string;
-}
-
-/**
- * Validates ONLY the roster-derived generated projection for a recovery rebuild.
- * Unlike {@link prepareAgentEnvironmentProjection}, this never reads, classifies,
- * relocates, or quarantines the legacy `.env` / `.env.local` operator surface — it
- * exists so `mosaic fleet regen` has no code path that can mutate anything except
- * `<name>.env.generated`. The existing generated file, if present, must already be
- * a private regular file.
- */
-export async function prepareGeneratedAgentEnvironmentProjection(
-  options: AgentEnvironmentProjectionOptions,
-): Promise<PreparedGeneratedAgentEnvironmentProjection> {
-  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 generated = renderGeneratedAgentEnvironment(options.generated);
-  await assertPrivateRegularFileIfPresent(generatedPath);
-  return {
-    mosaicHome: options.mosaicHome,
-    agentEnvDir: options.agentEnvDir,
-    generatedPath,
-    generated,
-  };
-}
-
-/**
- * Applies a generated-only projection: writes ONLY `<name>.env.generated` atomically
- * and touches nothing else. It never writes `.env.local`/`.env.quarantine` and never
- * unlinks the legacy `.env` — the projection-only recovery guarantee is structural.
- */
-export async function applyPreparedGeneratedAgentEnvironmentProjection(
-  prepared: PreparedGeneratedAgentEnvironmentProjection,
-): Promise<string> {
-  await ensurePrivateProjectionDirectory(prepared.mosaicHome, prepared.agentEnvDir);
-  await writePrivateAtomically(prepared.generatedPath, prepared.generated);
-  return prepared.generatedPath;
-}
-
 /**
  * Validates only the exact generated projection eligible for a roster delete.
  * Local overrides, legacy input, and quarantine records are operator-retained and

tools/install.sh

@@ -212,7 +212,7 @@ ok()    { echo "${G}✔${RESET}  $*"; }
 warn()  { echo "${Y}⚠${RESET}  $*"; }
 fail()  { echo "${R}✖${RESET}  $*" >&2; }
 dim()   { echo "${DIM}$*${RESET}"; }
-step()  { printf '\n%s%s%s\n' "$BOLD" "$*" "$RESET"; }
+step()  { echo ""; echo "${BOLD}$*${RESET}"; }
 
 # ─── helpers ──────────────────────────────────────────────────────────────────