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

@@ -42,6 +42,23 @@ steps:
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
 
+  # Blocking gate (#791): a framework upgrade must never write or delete an
+  # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
+  # survives a keep-mode reseed byte-identical (with rsync present AND absent —
+  # 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 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-install-migration.sh
+
   typecheck:
     image: *node_image
     commands:
@@ -50,6 +67,7 @@ steps:
     depends_on:
       - install
       - sanitization
+      - upgrade-guard
 
   # lint, format, and test are independent — run in parallel after typecheck
   lint:

docs/PRD.md

@@ -125,6 +125,76 @@ are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
 
 ---
 
+## Exact Cross-Harness Fleet Communications Contract (#766)
+
+### Problem and objective
+
+Fleet runtime contracts currently combine exact peer rows with generic operational metavariables and
+independently parsed roster data. Non-Claude harnesses can mistake those metavariables for values to
+infer, producing incorrect host, session, socket, or helper targets. The objective is one
+roster-resolved communications contract that every supported harness receives unchanged.
+
+### Normative requirements
+
+1. `FCOM-REQ-01`: Fleet commands and runtime composition SHALL use one shared v1 roster structural
+   resolver. A second lenient communications parser is forbidden.
+2. `FCOM-REQ-02`: The composed contract SHALL render the local roster member's authoritative host,
+   exact agent/session name, resolved tmux socket, exact helper path, and deterministic communications
+   generation.
+3. `FCOM-REQ-03`: Every known peer SHALL have one exact executable command. Same-host commands SHALL
+   omit `-H`; cross-host commands SHALL use only that peer's explicit roster `ssh` target; the one
+   supported fleet-wide named socket SHALL use `-L` with its exact value. A per-agent socket declaration
+   must equal that fleet-wide value; unsupported independent sockets and missing cross-host SSH data SHALL
+   fail closed.
+4. `FCOM-REQ-04`: Operational fleet examples SHALL not contain unresolved host, session, socket, or
+   helper-path metavariables. Agents SHALL select an exact rendered peer row and SHALL NOT infer,
+   substitute, or fuzzy-match targeting values.
+5. `FCOM-REQ-05`: An unknown local member or requested peer SHALL fail closed with exact-name discovery
+   guidance. Runtime composition SHALL not silently omit a requested fleet member's communications
+   contract.
+6. `FCOM-REQ-06`: Claude Code, Codex, OpenCode, and Pi SHALL receive equivalent authoritative
+   communications data through the common runtime composer.
+7. `FCOM-REQ-07`: Tests SHALL prove the contract from framework-source `TOOLS.md`, through a fresh
+   installed `TOOLS.md`, to final runtime composition and helper executability. User-owned installed
+   `TOOLS.md` content SHALL remain preserved.
+8. `FCOM-REQ-08`: Stale installed or active composed context SHALL be reported with deterministic
+   generation/repair/relaunch guidance. Currency requires the expected source and installed contract
+   marker/version plus bounded byte equality. The supported current-version repair SHALL run independently
+   of package updates, preserve divergent `TOOLS.md` bytes in a digest-qualified no-clobber backup, restore
+   a regular executable helper without following symlinks, and be idempotent. Detection and reporting SHALL
+   NOT rewrite active context, restart a session, or mutate a live fleet.
+9. `FCOM-REQ-09`: The shared resolver SHALL preserve and strictly validate every schema-supported v1
+   connector kind (`tmux`, `discord`, and `matrix`) from YAML and JSON. Every accepted snake/camel alias
+   pair SHALL reject differing dual declarations and accept identical declarations. JSON roster fallback
+   SHALL occur only when `roster.yaml` is absent; all other YAML access failures SHALL fail closed.
+10. `FCOM-REQ-10`: The communications generation SHALL cover the complete canonical rendered semantic
+    contract, including identity, role/class, resolved host/socket/helper, peer metadata, and exact commands.
+    Installed helpers SHALL be validated with no-follow filesystem inspection as regular executable files.
+    Keep-mode reseed and relaunch discovery SHALL preserve and support both YAML and JSON rosters.
+
+### Acceptance criteria
+
+1. `AC-FCOM-01`: Contract fixtures contain no unresolved operational targeting metavariables; local
+   identity contains exact host/session/socket/helper values.
+2. `AC-FCOM-02`: Same-host, cross-host, named-socket, literal-default-socket, and missing-SSH tests prove
+   exact targeting and fail-closed behavior.
+3. `AC-FCOM-03`: Unknown identities and peers report known exact names plus an exact self-scoped
+   discovery command; no fuzzy session selection is emitted.
+4. `AC-FCOM-04`: Four-harness tests prove byte-equal authoritative communications sections.
+5. `AC-FCOM-05`: Source, fresh-install, preserved-custom-install, stale-installed, composed-generation,
+   helper executable, agent-send socket isolation, and exact-target tests pass.
+6. `AC-FCOM-06`: Documentation defines non-mutating stale-context detection and operator-authorized,
+   exact-agent relaunch; no implementation path performs automatic session mutation.
+7. `AC-FCOM-07`: YAML and JSON fixtures cover every connector kind; all snake/camel aliases cover
+   identical acceptance and conflicting rejection; non-`ENOENT` YAML failures do not fall back.
+8. `AC-FCOM-08`: Missing, directory, symlink, and non-executable installed helpers fail closed. Explicit
+   current-version repair proves partial-deletion recovery, digest-qualified backup collision safety,
+   symlink-target safety, and repeated-run idempotence.
+9. `AC-FCOM-09`: Markerless-equal and wrong-version source/installed contracts are stale, and a rendered
+   role/class change produces a different communications generation.
+
+---
+
 ## KBN-101 Database Runtime/Migration Role Split (#771)
 
 ### Problem and objective

docs/TASKS.md

@@ -52,20 +52,20 @@ Active workstream is **W1 — Federation v1**. Workers should:
 > the repository quality gates, independent code and security review, terminal-green CI, and
 > the applicable acceptance evidence before merge. Issue #758 remains open until M5 closes.
 
-| id         | status      | description                                                                                                                                                            | issue | agent         | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                                    |
-| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| FCM-M0-001 | done        | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet        | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5                                           |
-| FCM-M1-001 | done        | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | coder0        | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation                       |
-| FCM-M1-002 | in-progress | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | Started 2026-07-14 from `aa5b43b`; one shared resolver only; validator certificate-only; merge-gate sole merge authority |
-| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex         | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | Every shipped artifact must validate, be versioned v1, or be retired with replacement                                    |
-| FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex         | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | No arbitrary command compatibility path; diagnostics expose key names/hashes only                                        |
-| FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex         | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | Fresh create persists stopped unless explicit persisted start                                                            |
-| FCM-M3-001 | not-started | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex         | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | Exact systemd/tmux ownership; remote/schema-only entries are inventory only                                              |
-| FCM-M3-002 | not-started | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet        | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Proves stopped-state preservation and zero fuzzy destructive targeting                                                   |
-| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | Preview first; no unreviewed lifecycle inference                                                                         |
-| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | Never starts a previously stopped agent or kills an unproven unmanaged session                                           |
-| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Must close every checklist item or record an approved deferral                                                           |
-| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI         |
+| id         | status      | description                                                                                                                                                            | issue | agent         | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                            |
+| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
+| FCM-M0-001 | done        | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet        | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5                                   |
+| FCM-M1-001 | done        | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | coder0        | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation               |
+| FCM-M1-002 | done        | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | #768 squash `a5e8e55`; shared resolver and canonical authority/alias validation delivered                        |
+| FCM-M1-003 | done        | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex         | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | #770 squash `e9c4aa3`; shipped artifact disposition validation delivered                                         |
+| FCM-M2-001 | done        | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex         | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | #772 squash `191efae`; generated/local boundary and private quarantine delivered                                 |
+| FCM-M2-002 | done        | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex         | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | #773 squash `bc5e736`; generation-guarded atomic CRUD and recovery contracts delivered                           |
+| FCM-M3-001 | done        | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex         | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | #785 squash `4990905`; exact roster-owned systemd/tmux reconcile and lifecycle contracts delivered               |
+| FCM-M3-002 | in-progress | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet        | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Canonical v2 named-socket + legacy-v1 default-server boundaries; fake adapters/temp fixtures only                |
+| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | Preview first; no unreviewed lifecycle inference                                                                 |
+| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | Never starts a previously stopped agent or kills an unproven unmanaged session                                   |
+| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Must close every checklist item or record an approved deferral                                                   |
+| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI |
 
 ## Thin-core prompt diet (#528) — feat/contract-thin-core
 

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

@@ -0,0 +1,290 @@
+# Design — #791: Framework upgrades must not destroy operator-owned config under `~/.config/mosaic`
+
+- **Issue:** mosaicstack/stack#791
+- **Branch:** `feat/791-upgrade-config-protection` (off `origin/main` `9745bc3f`)
+- **Author:** ms-791 worker lane
+- **Status:** Phase 1 — DESIGN, awaiting MS-LEAD confirmation before implementation
+- **Ratified scope (Mos-approved, not re-litigated):** deliver **(b) strict ownership separation [PRIMARY]** + **(a) transactional pre-update snapshot [safety net]** + **(d) regeneration-from-SSOT [recovery]**. **(c) periodic backup timer is DEFERRED** — noted as future work only.
+
+---
+
+## 1. Current updater behavior + exact wipe mechanism (evidence)
+
+### 1.1 What runs on `mosaic update`
+
+`mosaic update` re-seeds the framework by invoking the **bash installer** in sync-only, keep mode:
+
+- `packages/mosaic/src/runtime/update-checker.ts:509` `buildReseedCommand()` returns
+  `bash <frameworkRoot>/install.sh` with env `MOSAIC_SYNC_ONLY=1`, `MOSAIC_INSTALL_MODE=keep`,
+  `MOSAIC_HOME=<mosaicHome>`.
+- The same `install.sh` is the direct/`tools/install.sh` upgrade path and the framework-vN migration path.
+
+So the destructive surface is **`packages/mosaic/framework/install.sh`**.
+
+### 1.2 The wipe
+
+`sync_framework()` (`install.sh:177`) performs, in `keep` mode:
+
+```
+rsync -a --delete --exclude .git --exclude .framework-version --exclude '*.pre-constitution.bak' \
+      [--exclude "/$path" for each PRESERVE_PATHS entry] SOURCE_DIR/ TARGET_DIR/
+```
+
+- `install.sh:199` — `rsync -a --delete`. **`--delete` prunes every path in `~/.config/mosaic`
+  that is NOT present in the shipped framework source**, unless excluded.
+- `install.sh:47` — `PRESERVE_PATHS` is the **only** thing standing between `--delete` and operator
+  data. It is a _denylist of exclusions_:
+  ```
+  PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md"
+    "memory" "sources" "credentials" "fleet/roster.yaml" "fleet/roster.json" "fleet/agents"
+    "fleet/run" "fleet/backlog" "fleet/roles.local")
+  ```
+- The cp-fallback (no rsync) is equally destructive: `install.sh:223`
+  `find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ... -exec rm -rf {} +` then re-copies source, restoring
+  only PRESERVE_PATHS globs.
+
+**Root-cause model:** _"Everything under `~/.config/mosaic` is framework-owned and pruneable UNLESS
+explicitly preserved."_ Any operator path the list forgets is destroyed on the next upgrade.
+
+### 1.3 The exact operator paths wiped
+
+Cross-referencing the issue's operator-owned list against `PRESERVE_PATHS`:
+
+| Operator path (issue #791)                                        | In PRESERVE_PATHS?                      | Fate on `mosaic update` |
+| ----------------------------------------------------------------- | --------------------------------------- | ----------------------- |
+| `agents/*.conf` (per-agent runtime)                               | **NO**                                  | **WIPED**               |
+| `policy/*.md` (operator overlays)                                 | **NO**                                  | **WIPED**               |
+| `*.local.md` (SOUL/USER/STANDARDS)                                | **NO**                                  | **WIPED**               |
+| harvester / SOP artifacts + timers                                | **NO**                                  | **WIPED**               |
+| `tools/_lib/credentials.json`                                     | **NO** (`credentials/` dir ≠ this path) | **WIPED**               |
+| `fleet/agents/*.env`                                              | yes (`fleet/agents`, added by #631)     | survives                |
+| `memory/`, `fleet/roster.*`, `fleet/backlog`, `fleet/roles.local` | yes                                     | survives                |
+
+The `fleet/agents`, `memory`, `fleet/backlog` entries were **retro-added after prior incidents**
+(#631). This whack-a-mole is the structural signature of a denylist.
+
+**Stale-comment evidence:** `update-checker.ts:492` claims the reseed preserves
+"`SOUL/USER/*.local/credentials`" — but `PRESERVE_PATHS` contains **no `*.local` entry**. The code
+documents protection it does not deliver.
+
+### 1.4 Second code path (TS) — already non-destructive, but drifted
+
+`FileConfigAdapter.syncFramework()` (`packages/mosaic/src/config/file-adapter.ts:157`) →
+`syncDirectory()` (`packages/mosaic/src/platform/file-ops.ts:66`) is a **copy-overlay**: it copies
+source over target and skips preserved paths, but **never deletes** target paths absent from source
+(`file-ops.ts:77-109`). It is used by the wizard/init flow, not `mosaic update`.
+
+Two problems remain:
+
+1. Its `preservePaths` (`file-adapter.ts:164-185`) has **already diverged** from `install.sh` — it is
+   **missing `fleet/backlog` and `fleet/roles.local`**. Two hand-maintained denylists, drifted. This
+   is direct evidence for a single shared SSOT manifest.
+2. Even non-destructive, it will happily _overwrite_ an operator file that collides with a
+   framework-shipped path unless that path is on its (incomplete) preserve list.
+
+### 1.5 Existing snapshot is inadequate for rollback
+
+`make_snapshot()`/`restore_snapshot()` (`install.sh:76-87`) copy `TARGET_DIR` to `mktemp -d` under
+`/tmp`, restore **only on `ERR/INT/TERM` trap**, and are **deleted on success** (`cleanup_snapshot`,
+`install.sh:345`). Consequences: ephemeral `/tmp`, no retention, no post-success rollback, and **no
+`mosaic restore`**. It is crash-safety only, not the transactional safety net #791 requires.
+
+---
+
+## 2. Fix (b) — Strict ownership separation [PRIMARY / root cause]
+
+### 2.1 Ownership model (invert to allow-list)
+
+Replace _"framework-owned unless preserved"_ with _"operator-owned unless framework-owned"_, resolved
+**per target path** with operator carve-outs winning inside shared framework subtrees.
+
+Two declared lists, one SSOT data file shipped in the framework
+(`framework/framework-manifest.json`), consumed by **both** bash and TS:
+
+- **`framework` globs** — paths the updater is entitled to create / overwrite / prune. Authored to
+  match exactly what the framework ships in `packages/mosaic/framework/` (e.g. `CONSTITUTION.md`,
+  `AGENTS.md`, `STANDARDS.md`, `TOOLS.md`, `guides/**`, `constitution/**`, `templates/**`, `tools/**`,
+  `skills/**`, `mcp/**`, `defaults/**`, `fleet/examples/**`, `fleet/roles/**`, `fleet/profiles/**`,
+  `fleet/roster.schema.json`).
+- **`operatorReserved` globs** — NEVER written or pruned, even nested inside a `framework` subtree;
+  these **win** over `framework` (deny-wins / most-specific-wins). At minimum:
+  `agents/**`, `policy/**`, `memory/**`, `sources/**`, `credentials/**`, `*.local.md`,
+  `tools/_lib/credentials.json`, `fleet/roster.yaml`, `fleet/roster.json`, `fleet/agents/**`,
+  `fleet/run/**`, `fleet/backlog/**`, `fleet/roles.local/**`, plus operator harvester/SOP artifacts.
+
+### 2.2 Ownership resolution for a target path `P`
+
+1. `P` matches `operatorReserved` → **operator-owned**: updater MUST NOT write, MUST NOT delete.
+2. else `P` matches `framework` → **framework-owned**: may overwrite; may prune **only if absent from
+   the current SOURCE** (a genuinely retired framework file).
+3. else (matches neither) → **UNKNOWN ⇒ operator-owned by default (fail-safe)**: never delete.
+
+Rule 3 is the actual root-cause fix: an operator path the manifest authors forget is still protected,
+because _unknown defaults to operator_. A denylist can never provide this guarantee.
+
+### 2.3 Sync mechanism change (the mechanically-critical part)
+
+`--delete` cannot express "prune only framework-owned" without re-enumerating every operator path
+(the denylist trap). So:
+
+1. **Drop `--delete` from the bulk sync.** Copy `SOURCE → TARGET` non-destructively (writes/overwrites
+   all framework files; deletes nothing). rsync without `--delete`, or the existing overlay copy.
+2. **Explicit manifest-scoped prune pass.** Iterate the **`framework` manifest** (not the whole tree);
+   for each framework path present in `TARGET` but **absent in `SOURCE`**, delete it — after
+   re-checking it does not match `operatorReserved`. Because the prune iterates only declared
+   framework globs, operator/unknown paths are **structurally unreachable** by deletion.
+
+This is implemented in both bash `sync_framework()` and TS `syncFramework()` from the shared manifest.
+A pure **prune-planner** function (TS) computes the delete-set from
+`(manifest, sourceListing, targetListing)` so the invariant is unit-testable in isolation.
+`PRESERVE_PATHS` becomes redundant (kept as a defense-in-depth alias mapping to `operatorReserved`, or
+removed) — either way the two lists stop drifting because they read one file.
+
+### 2.4 HARD GATE test — "upgrade touches no path outside the manifest"
+
+Filesystem-observation test in the existing `test-install-migration.sh` harness pattern (mktemp
+`MOSAIC_HOME`, `MOSAIC_SYNC_ONLY=1`), plus TS specs:
+
+1. Seed a throwaway `TARGET` with a realistic operator mix — one sentinel per operator class:
+   `agents/x.conf`, `policy/p.md`, `SOUL.local.md`, `memory/m.md`,
+   `tools/_lib/credentials.json` (with a secret value), `fleet/agents/a.env`, `fleet/roster.yaml`,
+   `harvester/sop.md`, **and a deliberately-unanticipated `unknown-operator-dir/x`**.
+2. Record hash+mtime of every sentinel.
+3. Run the upgrade from a `SOURCE` containing none of those operator paths.
+4. **Assert:** every sentinel exists, byte-identical, **mtime unchanged** (not even rewritten). The
+   `unknown-operator-dir` surviving proves the fail-safe default — a denylist could not pass this case.
+5. **Positive controls:** framework files WERE updated; a retired framework file WAS pruned.
+6. **Property test** (TS prune-planner): for fuzzed operator paths, `deleteSet ⊆ {matches framework ∧
+in target ∧ not in source}` and `deleteSet ∩ operatorReserved = ∅`.
+
+---
+
+## 3. Fix (a) — Transactional pre-update snapshot [safety net]
+
+- **Destination:** `${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-ts>/`.
+  **Outside `~/.config/mosaic`** (so no future sync can sweep it) and outside any repo.
+- **Perms:** dir `0700`, files `0600` — enforced with `umask 077` around the copy **and** explicit
+  `chmod`. Never world-readable.
+- **Scope:** the operator-owned surface (`operatorReserved` paths that exist) — bounded; does not copy
+  the framework tree.
+- **Timing:** taken before ANY mutation in the upgrade flow.
+- **Post-sync verify + selective restore:** after sync, diff the operator surface against the snapshot;
+  since (b) should never touch operator paths, any diff means a manifest bug — restore the affected
+  paths from the snapshot and warn loudly. This is precisely (a) catching a miss in (b).
+- **Retention:** keep N most-recent (default 5; `MOSAIC_BACKUP_RETENTION` override); prune older.
+- **`mosaic restore`:** `--list` (default, dry-run) enumerates snapshots by timestamp;
+  `--from <ts>` restores that snapshot over the operator surface, confirmation-gated. Reports
+  counts/paths only.
+- **Secret-safety:** snapshot copy and restore never emit file **contents**; only paths/counts.
+  Tests assert `0700/0600` and that no secret value appears in stdout/stderr.
+
+---
+
+## 4. Fix (d) — Regeneration-from-SSOT [recovery]
+
+The incident's live blast radius: `fleet/agents/*.env` (systemd `EnvironmentFile` sources) gone →
+`mosaic-agent@<name>` boots **unit defaults** on restart (because `EnvironmentFile=-...` is
+absent-tolerant) → **silent identity/runtime/workdir downgrade**.
+
+The SSOT for those `.env` files is the roster. The reconciler **already** separates a
+`regenerate-projections-from-roster` projection phase from lifecycle
+(`packages/mosaic/src/fleet/fleet-reconciler.ts:93,234`; env rendering in
+`generated-env-boundary.ts:149-264`).
+
+**`mosaic fleet regen`** is therefore a **thin recovery-framed wrapper over the existing projection
+phase** — it does NOT reimplement fleet logic and does NOT preempt in-flight FCM cards (M4/M5):
+
+- Regenerates derivable config (per-agent `*.env.generated`, unit files) from roster SSOT.
+- **Preview-first:** dry-run default; `--write` to apply. Idempotent.
+- **Never restarts agents** (the recovery order forbids restart-before-verify).
+- Prints the runbook's next step (verify `EnvironmentFile` resolves, THEN restart).
+
+Alternatively documentable as `install.sh --relink` per the issue; `mosaic fleet regen` is preferred
+because it reuses the merged reconciler plumbing.
+
+---
+
+## 5. Secret-safety approach (secrev surface)
+
+- Snapshots/backups: `0700`/`0600`, outside any repo, never world-readable. (§3)
+- No secret **value** ever emitted to logs/stdout/stderr by snapshot, restore, sync, or regen —
+  paths/counts only. Adversarial test: a secret value placed in `tools/_lib/credentials.json` must
+  never appear in installer or command output.
+- `tools/_lib/credentials.json` is an explicit `operatorReserved` carve-out inside the framework-owned
+  `tools/**` subtree — it is never overwritten or pruned.
+- The HARD GATE test doubles as a secret-safety test (asserts the credentials sentinel is untouched).
+
+---
+
+## 6. Test plan (TDD, tests-first, ≥85% on new code, co-located `*.spec.ts`)
+
+1. **Manifest SSOT parity** — bash and TS resolve identical framework/operator sets from the one file;
+   a test fails if either path hard-codes a divergent list.
+2. **Manifest completeness** — every path shipped in `framework/` is covered by a `framework` glob (so
+   a new shipped file cannot silently fall outside the manifest and become un-prunable/undeclared).
+3. **HARD GATE** — upgrade touches nothing outside the manifest, incl. the unanticipated-path case
+   (§2.4).
+4. **Prune-planner** unit + property tests (§2.4.6).
+5. **Snapshot** — perms `0700/0600`, correct destination, retention prune, secret value absent from
+   output.
+6. **Restore** — `--list` / `--from` round-trip restores operator surface byte-exact; confirmation
+   gate; no secret leakage.
+7. **Regen** — roster→env projection deterministic + idempotent; dry-run makes no writes; `--write`
+   restores `*.env`; **never** issues a lifecycle/restart call.
+8. **Cross-path regression** — TS `syncFramework` and bash `install.sh` agree on a shared fixture
+   (closes the current #631-style drift).
+
+Gates before every push: `pnpm typecheck && pnpm lint && pnpm format:check` + mosaic package tests
+green. Never `--no-verify`.
+
+---
+
+## 7. web1 recovery runbook (operator-agnostic; web1 specifics live in the issue as evidence only)
+
+For a currently-wiped fleet EnvironmentFile state — **do NOT service-restart while
+`fleet/agents/*.env` is absent** (a restart boots unit defaults and silently downgrades identity):
+
+1. **Regenerate:** `mosaic fleet regen --write` — rebuild `~/.config/mosaic/fleet/agents/*.env` from
+   roster SSOT.
+2. **Verify each unit resolves to the intended runtime/workdir** _before_ any restart:
+   `systemctl --user show mosaic-agent@<name> -p EnvironmentFile` and confirm the generated env exists
+   and carries the intended `MOSAIC_AGENT_*` runtime/workdir values.
+3. **Only then** `systemctl --user restart mosaic-agent@<name>`, one unit at a time.
+
+If config (not just fleet env) was lost, `mosaic restore --list` → `mosaic restore --from <ts>` before
+step 1.
+
+---
+
+## 8. Proposed PR split (reviewable; DAG-ordered)
+
+| PR  | Scope                                                                                                                                                    | Depends | Review focus               |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------- |
+| PR1 | **PRIMARY** — shared `framework-manifest.json` + ownership resolver + non-deleting sync + scoped prune (bash + TS) + **HARD GATE** + prune-planner tests | —       | correctness (root fix)     |
+| PR2 | **Safety net** — pre-update snapshot (`~/.local/state`, 0700/0600, retention) + post-sync verify/restore + `mosaic restore`                              | PR1     | **secrev** (backup/secret) |
+| PR3 | **Recovery** — `mosaic fleet regen` (projection-only, preview-first, no restart) + docs (upgrade-safety + recovery runbook)                              | PR1     | correctness + docs         |
+
+Rationale: PR1 closes the failure class on its own; if PR2/PR3 slip, the class stays fixed. Each PR is
+one reviewable unit with its own tests ≥85%. Independent review (author≠reviewer) on all; **secrev** on
+PR2 (and PR1's secret-sentinel assertions).
+
+## 9. Deferred (noted per scope)
+
+**(c) periodic backup timer** — a systemd user timer snapshotting operator dirs on a cadence
+(defense-in-depth for non-upgrade losses). Explicitly **out of scope now**; future phase.
+
+## 10. Constraints honored
+
+- **Framework-PR firewall:** manifest + logic are operator-agnostic; no SOUL/USER/operator specifics
+  in framework code; web1 details are issue evidence only.
+- **Capacity-fill:** must not preempt M5-001 or #790; `fleet regen` reuses merged FCM-M3 plumbing and
+  does not overlap FCM-M4/M5 migration cards.
+- **Delivery gates:** TDD tests-first, ≥85% new-code coverage, trunk-based squash PRs, independent
+  review + secrev, completion = merged PR + descendant-main green + #791 closed.
+
+---
+
+**Requesting MS-LEAD confirmation of:** (1) the manifest allow-list + non-deleting-sync + scoped-prune
+approach as the (b) root-cause fix; (2) snapshot destination/retention + `mosaic restore` UX;
+(3) `mosaic fleet regen` as a projection-only wrapper; (4) the 3-PR split. Implementation begins only
+on your confirmation.

docs/fleet/FLEET-LAUNCH.md

@@ -66,8 +66,12 @@ checks the exact `=<agent-name>` tmux target; it never uses an ambient socket or
 The same strict parser runs before exact-stop behavior. A fresh native Pi heartbeat remains authoritative;
 the shell sidecar only provides fallback state when the native marker is stale or absent.
 
-`mosaic fleet comms-block <role>` can inspect the role's resolved Fleet-Comms block. It is a read-only
-inspection tool and fails loudly for an unknown role or missing roster.
+`mosaic agent comms-block <exact-member>` can inspect that exact roster member's resolved Fleet-Comms
+block. It is a read-only inspection tool and fails loudly for an unknown exact member or missing roster.
+On Linux, the installed roster, TOOLS contract, and executable helper are opened through a held
+descriptor chain rooted at `/`; every managed path component uses no-follow traversal, and content plus
+execute validation stay bound to the same opened file. Systems without Linux `/proc/self/fd` support
+fail closed rather than falling back to pathname revalidation.
 
 ## Current M2 boundary
 

docs/fleet/migration/example-profile-disposition.md

@@ -41,10 +41,27 @@ artifact can be removed.
 | `profiles/software-delivery.yaml`    | Canonical profile        | shared profile/persona resolver   | Retains the governance profile; authority validation remains FCM-M1-002 evidence.                |
 | `services/operator-interaction.yaml` | Canonical service policy | service-policy reader/provisioner | Generic provisioning supplies the instance name; the policy itself never names Tess.             |
 
+## M4 migration-preview evidence
+
+FCM-M4-001 layers an executable migration posture over the same 13-entry M1 inventory without
+changing the retained artifact classification:
+
+- every `v1-fixture` is previewed only with explicit class and lifecycle evidence;
+- every `canonical-profile` remains validated by the shared baseline-plus-`roles.local` resolver;
+- the canonical service policy remains generic and uses only the approved tool-policy alias.
+
+`validateShippedFleetMigrationDispositions` first runs the existing executable M1 guard, then requires
+explicit decisions and lifecycle observations and executes `previewV1ToV2Migration` for every shipped
+v1 fixture. `collectShippedFleetMigrationDispositions` derives the 13-entry posture directly from
+`SHIPPED_FLEET_ARTIFACT_DISPOSITIONS`, so additions or removals continue to fail the M1 guard rather
+than creating a second artifact list. None of these dispositions claims a cutover, canary, or
+rollback; those gates belong to FCM-M4-002. See [v1-to-v2 preview](./v1-to-v2.md).
+
 ## Running the guard
 
 ```bash
-pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts
+pnpm --filter @mosaicstack/mosaic test -- v1-v2-migration.spec.ts \
+  -t "validates all 13 shipped artifacts and executes ready previews for every v1 fixture"
 ```
 
 The guard is intentionally limited to shipped assets and validation. It does not generate

docs/fleet/migration/v1-to-v2.md

@@ -0,0 +1,86 @@
+# Previewing a Fleet Roster v1-to-v2 Migration
+
+**Issue:** #758 · **Card:** FCM-M4-001 · **Effect boundary:** preview only
+
+`mosaic fleet migrate-v1 preview` inventories a v1 roster and emits a canonical v2 candidate plus
+recovery evidence. It does not write a roster, apply environment projections, invoke systemd or
+`tmux`, contact connectors or remote hosts, launch an agent, run a canary, or execute rollback.
+FCM-M4-002 owns reversible cutover and rollback.
+
+## Inputs
+
+```bash
+mosaic fleet migrate-v1 preview \
+  --source roster-v1.yaml \
+  --decisions migration-decisions.json \
+  --observations reviewed-observations.json
+```
+
+The command emits one JSON object and exits nonzero when the preview is blocked, including when any of
+`--source`, `--decisions`, or `--observations` is omitted, passed without a path value, or passed an empty
+path value. These request-shape failures are reported before any input file is read. Decision and
+observation JSON is validated fail-closed: unknown fields, malformed values, and records for non-local
+agents are rejected. Decisions must supply a positive v2 `generation`, a reviewed `fleetHost` whenever
+v1 agents include `host` or `ssh`, explicit `defaultRuntime`, and per-local-agent provider, model,
+reasoning, enabled state, and launch policy. The v1 source remains authoritative for socket semantics:
+a supported declared socket field, including an explicit empty value for the default tmux server, is
+preserved; if both supported root aliases are absent, the production v1 default is the literal empty socket.
+A matching `socketName` decision is accepted and an incompatible decision blocks, but a decision never
+supplies or repairs a missing source socket. If v1 omitted `tool_policy`, decisions must supply an
+explicit replacement; it is never derived from `class`. `model_hint` is never split or treated as
+authority.
+
+Observations are separate reviewed evidence keyed by local agent name:
+
+```json
+{
+  "coder0": { "systemd": "inactive", "tmux": "missing" }
+}
+```
+
+Only `active` plus `present` maps to `running`; only `inactive` plus `missing` maps to `stopped`.
+Missing, extra, unknown, or contradictory evidence blocks output. An observed-running agent cannot
+be marked disabled. Observed-stopped agents always remain stopped.
+
+## Field disposition
+
+| v1 field                                                                 | v2 disposition                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`, `transport`, `tmux`, `defaults`, `runtimes`                   | Inventoried and structurally compiled; omitted runtimes retain v1 built-in defaults, while each explicitly declared runtime without a reset field follows the production v1 `/clear` fallback; present-empty holder/work-directory/reset values block                                                                             |
+| agent `name`, `alias`, `runtime`, working directory, persona/reset flags | Copied or explicitly defaulted only when absent; present-empty alias/work-directory values block for explicit disposition. Canonical `~`/`~/...` values stay unchanged in roster evidence and traversal-free forms expand only at the shared production environment-projection boundary before unchanged absolute-path validation |
+| `provider`, `model_hint`, `reasoning_level`                              | Explicit provider/model/reasoning decisions; no model-hint inference                                                                                                                                                                                                                                                              |
+| `class`, `tool_policy`                                                   | Only approved aliases canonicalize automatically; other classes require explicit preserve/replace disposition and shared-resolver validation                                                                                                                                                                                      |
+| `kickstart_template`                                                     | No v2 field; explicit inventory-only disposition required                                                                                                                                                                                                                                                                         |
+| agent `host`, `ssh`                                                      | `host != fleetHost` is demonstrably remote and inventory-only; `host == fleetHost` stays local; SSH targets with or without an explicit user must agree with `host`; ssh-only, missing fleet-host evidence, or contradictory targets block                                                                                        |
+| agent `socket`                                                           | Same-host candidate only when it matches the canonical fleet socket; conflicts block for explicit future disposition                                                                                                                                                                                                              |
+| root `connector`                                                         | Inventory-only; never contacted or reconciled                                                                                                                                                                                                                                                                                     |
+| unknown fields or snake/camel synonym collisions                         | Inventoried and block readiness                                                                                                                                                                                                                                                                                                   |
+| `.env.generated`                                                         | Rebuild from canonical roster data                                                                                                                                                                                                                                                                                                |
+| no legacy `.env`                                                         | `absent`; no legacy action required                                                                                                                                                                                                                                                                                               |
+| legacy `.env` containing generated keys only                             | `regenerate-only`; replace later from canonical roster data                                                                                                                                                                                                                                                                       |
+| legacy `.env` containing strict local keys                               | `relocate-local`; preserve those keys in `.env.local` during a later reviewed cutover                                                                                                                                                                                                                                             |
+| legacy `.env` containing forbidden/unsafe/sensitive/malformed keys       | `quarantine`; private input only, with diagnostics limited to code, key, and SHA-256                                                                                                                                                                                                                                              |
+
+The only automatic aliases are `implementer → code`, `reviewer → review`, and
+`operator-interaction → interaction`. Similar or domain-specific names are never inferred. Automatic
+classes do not accept competing disposition records. Semantic validation delegates to the existing
+baseline-plus-`roles.local` resolver after the candidate is compiled by the existing v2 compiler.
+
+## Evidence and recovery boundary
+
+Ready output includes source and candidate SHA-256 identities, value-free field inventory, excluded
+remote/connector entries, explicit environment dispositions with sanitized diagnostics, and the lifecycle
+evidence used for each local candidate. Canonical lifecycle and remote-exclusion evidence ordering compares
+Unicode code points directly and does not depend on source-agent order or process locale. Source field
+inventory remains position-addressed evidence of the exact input. Recovery is marked non-executable and
+assigns the executable gate to FCM-M4-002.
+
+Before any later cutover, preserve these artifacts:
+
+1. authoritative v1 roster backup;
+2. agent environment backup, including `.env.local` and private quarantine inputs;
+3. reviewed lifecycle observations;
+4. canonical candidate v2 roster and its SHA-256.
+
+See [backup and restore](../operations/backup-restore.md). Preview output is migration-readiness
+evidence, not proof that migration, canary, or rollback occurred.

docs/fleet/operations/backup-restore.md

@@ -0,0 +1,40 @@
+# Fleet Configuration Backup and Restore Boundary
+
+**Issue:** #758 · **Card:** FCM-M4-001
+
+This page defines evidence that must exist before a roster v1-to-v2 cutover. FCM-M4-001 lists these
+prerequisites in non-executable recovery evidence but does not validate that backups exist and performs
+no backup, migration, canary, or restore. FCM-M4-002 owns the executable reversible canary and rollback
+gates.
+
+## Preserve before cutover
+
+- The authoritative v1 roster, byte-for-byte, with a SHA-256 identity.
+- Existing per-agent legacy `.env`, strict `.env.local`, and quarantine files under private
+  permissions.
+- Reviewed per-local-agent systemd and exact-socket tmux observations.
+- The canonical v2 candidate and its SHA-256 identity.
+- Inventory-only remote agents and connector configuration as evidence, not local control-plane input.
+
+`.env.generated` is a rebuildable projection and is not restored as authority. It must be regenerated
+from the selected authoritative roster. `.env.local` is operator-owned strict data and must not be
+overwritten or absorbed into generated output. Quarantined source remains private evidence; public
+diagnostics expose only rule code, key name, and SHA-256.
+
+## Restore requirements
+
+A later rollback implementation must restore the authoritative roster and operator-owned environment
+files, regenerate managed projections, and preserve each reviewed pre-cutover stopped/running state.
+It must never start an agent observed stopped and must never reconcile an inventory-only remote or
+connector entry.
+
+The preview evidence deliberately records:
+
+- `executable: false`;
+- required backup artifacts;
+- source and candidate identities;
+- lifecycle observations and resulting desired states;
+- environment relocation/quarantine dispositions;
+- FCM-M4-002 as the executable rollback gate owner.
+
+Do not interpret a ready preview as a completed backup, migration, canary, or rollback.

docs/fleet/reference/cli.md

@@ -11,8 +11,15 @@ mosaic fleet restart [name] --expected-generation <n> [--dry-run]
 mosaic fleet status [name]
 mosaic fleet verify
 mosaic fleet doctor
+mosaic fleet migrate-v1 preview --source <path> --decisions <path> --observations <path>
 ```
 
+`migrate-v1 preview` is non-mutating: it emits value-free v1 inventory, a canonical semantically
+validated v2 candidate when ready, sanitized environment dispositions, and non-executable recovery
+evidence. It has no write, apply, canary, or rollback option. Missing preview inputs also return one stable
+blocked JSON object and a non-zero exit, rather than Commander text. See
+[the migration preview contract](../migration/v1-to-v2.md).
+
 `apply` and `reconcile` use roster desired state. `start`, `stop`, and `restart` are exact local one-shot lifecycle effects and never persist a desired-state edit. `status`, `verify`, and `doctor` are observational.
 
 Commands emit one JSON object. Handled precondition errors emit `{ "error": { "code": "..." } }` and exit non-zero. Partial derived/lifecycle effects use explicit `authoritativeRoster`, `projections`, `lifecycle`, and bounded `recovery` fields; they never claim rollback. Any additive `cleanup` diagnostic also exits non-zero, even where known effects are complete: it is not a clean completion and the lock requires inspection before retry.

docs/fleet/reference/roster-v2-fields.md

@@ -62,24 +62,24 @@ agents:
 
 ## Nested fields
 
-| Path                                                 | Required | Constraint                                                                                           |
-| ---------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
-| `tmux.socket_name`                                   | yes      | non-empty `[A-Za-z0-9_.-]+`; an explicit named socket prevents default-versus-named socket ambiguity |
-| `tmux.holder_session`                                | yes      | non-empty `[A-Za-z0-9_.-]+`                                                                          |
-| `defaults.working_directory`                         | yes      | non-empty string                                                                                     |
-| `defaults.runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                            |
-| `runtimes.<runtime>.reset_command`                   | yes      | non-empty string; runtime key must be a supported local runtime                                      |
-| `agents[].name`                                      | yes      | unique `[A-Za-z0-9][A-Za-z0-9_.-]*` stable machine identity                                          |
-| `agents[].alias`                                     | yes      | non-empty display string                                                                             |
-| `agents[].class`                                     | yes      | `[a-z][a-z0-9-]*`; structural only in M1, semantic role resolution is FCM-M1-002                     |
-| `agents[].runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                            |
-| `agents[].provider`, `model`, `working_directory`    | yes      | non-empty strings; provider/model capability resolution is a later card                              |
-| `agents[].reasoning`                                 | yes      | `low`, `medium`, or `high`                                                                           |
-| `agents[].tool_policy`                               | yes      | `[a-z][a-z0-9-]*`; structural only in M1                                                             |
-| `agents[].persistent_persona`, `reset_between_tasks` | yes      | booleans                                                                                             |
-| `agents[].lifecycle.enabled`                         | yes      | boolean; stored now, reconciled in FCM-M3-001                                                        |
-| `agents[].lifecycle.desired_state`                   | yes      | `running` or `stopped`                                                                               |
-| `agents[].launch.yolo`                               | yes      | boolean; structured data only, not an arbitrary command escape hatch                                 |
+| Path                                                 | Required | Constraint                                                                                                    |
+| ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `tmux.socket_name`                                   | yes      | `[A-Za-z0-9_.-]*`; empty string means the literal default tmux server, while a non-empty value names a socket |
+| `tmux.holder_session`                                | yes      | non-empty `[A-Za-z0-9_.-]+`                                                                                   |
+| `defaults.working_directory`                         | yes      | non-empty string                                                                                              |
+| `defaults.runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                                     |
+| `runtimes.<runtime>.reset_command`                   | yes      | non-empty string; runtime key must be a supported local runtime                                               |
+| `agents[].name`                                      | yes      | unique `[A-Za-z0-9][A-Za-z0-9_.-]*` stable machine identity                                                   |
+| `agents[].alias`                                     | yes      | non-empty display string                                                                                      |
+| `agents[].class`                                     | yes      | `[a-z][a-z0-9-]*`; structural only in M1, semantic role resolution is FCM-M1-002                              |
+| `agents[].runtime`                                   | yes      | `claude`, `codex`, `opencode`, or `pi`; it must be declared in `runtimes`                                     |
+| `agents[].provider`, `model`, `working_directory`    | yes      | non-empty strings; provider/model capability resolution is a later card                                       |
+| `agents[].reasoning`                                 | yes      | `low`, `medium`, or `high`                                                                                    |
+| `agents[].tool_policy`                               | yes      | `[a-z][a-z0-9-]*`; structural only in M1                                                                      |
+| `agents[].persistent_persona`, `reset_between_tasks` | yes      | booleans                                                                                                      |
+| `agents[].lifecycle.enabled`                         | yes      | boolean; stored now, reconciled in FCM-M3-001                                                                 |
+| `agents[].lifecycle.desired_state`                   | yes      | `running` or `stopped`                                                                                        |
+| `agents[].launch.yolo`                               | yes      | boolean; structured data only, not an arbitrary command escape hatch                                          |
 
 ## Semantic handoff
 

docs/fleet/reference/roster-v2.schema.json

@@ -24,7 +24,7 @@
       "properties": {
         "socket_name": {
           "type": "string",
-          "pattern": "^[A-Za-z0-9_.-]+$"
+          "pattern": "^[A-Za-z0-9_.-]*$"
         },
         "holder_session": {
           "type": "string",

docs/scratchpads/758-fcm-m3-002-reconciler-lifecycle-gates.md

@@ -0,0 +1,84 @@
+# FCM-M3-002 — Reconciler lifecycle acceptance gates
+
+- **Task / issue:** FCM-M3-002 / mosaicstack/stack#758
+- **Branch:** `test/758-reconciler-lifecycle-gates`
+- **Required starting head:** `499090508ef1d768660e4d54e7934cbcf13cb1cd`
+- **Required starting tree:** `2f1bb7fed48291f3f7ba8b21c2b52491aa14fe2b`
+- **Scope:** isolated acceptance coverage and card-required evidence/tracking only; no live fleet, systemd, tmux, session, site, migration, canary, deployment, runtime, connector, or remote action.
+- **Budget:** use the task estimate of 25K as the working cap; keep the delta to one coherent acceptance suite plus required task/scratchpad evidence. No production change unless a failing reproducer proves an in-scope defect.
+
+## Intake evidence
+
+- Clean exact local branch/head/tree verified before editing.
+- `origin/test/758-reconciler-lifecycle-gates` fetched and verified at the same required head.
+- The Mosaic PR wrapper reported no open pull requests, so no open-PR branch collision exists.
+- Parent issue #758 is open and remains intentionally open through M5.
+- Requirements loaded from `docs/PRD.md` FCM requirements and `AC-FCM-05`, `docs/TASKS.md` FCM DAG, the M3 rows in `docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md`, and the FCM-M3-001 implementation scratchpad.
+
+## Objective
+
+Add broad, behavior-oriented acceptance evidence around the shipped local reconciler contracts. Exercise only injected fake systemd/tmux adapters and temporary filesystem fixtures. Prove exact ownership/targeting, persisted stopped-state safety, truthful partial-failure recovery, rollback behavior, and stable command JSON/exit outcomes without touching live services or sessions.
+
+## Acceptance mapping and evidence
+
+| FCM-M3-002 acceptance concern | Delivered isolated evidence |
+| --- | --- |
+| Systemd/tmux lifecycle | `fleet-reconciler.acceptance.spec.ts` drives apply, reconcile, stop, restart, status, and recovery reconcile through one stateful injected fake host. The fake models exact systemd effects and tmux session observations; no host commands run. |
+| Drift | Canonical roster-v2 YAML drives the Commander `fleet status` boundary and classifies `missing-session`, `unexpected-session`, and `disabled-running`, including combined drift, while asserting observation emits no lifecycle mutation. |
+| Exact default/named socket targeting | Canonical v2 requires an explicit non-empty named socket; the parser rejects missing/empty values and the Commander acceptance path asserts exact `-L mosaic-fleet` targeting. A separate canonical legacy-v1 roster loader plus runtime-transport path proves a socket-less compatibility roster targets the literal tmux default server with no `-L`. No unreachable empty-socket v2 fixture is used. |
+| Unmanaged-session classification | Stateful fixtures report sorted `coder0-shadow`/`unmanaged` sessions, then prove an exact roster stop leaves both sessions and the near-collision service intact. |
+| Crash/partial failure | Injected restart failure is applied after the fake effect to model crash/partial truth: result is `lifecycle: incomplete`, the roster is unchanged, and observed runtime may be active. |
+| Rollback/recovery semantics | M3 has no rollback command and explicitly does not claim automatic rollback. The acceptance workflow proves the bounded recovery contract: inspect, then exact reconcile restores the persisted stopped target without a start or fuzzy effect. M4 migration/canary rollback remains outside this card. |
+| Stopped-state preservation | Stateful apply and reconcile both stop an initially running observed agent whose persisted target is stopped; failed explicit restart leaves desired state stopped; recovery reconcile restores stopped state. No start call is emitted. |
+| Zero fuzzy destructive targeting | Near-collision `coder0-shadow` service/session plus `unmanaged` session remain untouched. The recorded destructive calls contain only exact `mosaic-agent@coder0.service`; no tmux kill action is emitted. |
+| Stable JSON/exit behavior | Temporary canonical roster fixture invokes the CLI boundary and asserts exactly one JSON line, exact partial-result shape, and exit code 1. Existing focused command specs continue to cover clean zero-exit and stable error JSON. |
+| Redacted truthful recovery | Fake stderr includes `PASSWORD=acceptance-secret`; exact CLI JSON contains only bounded recovery metadata and excludes the key, value, and raw diagnostic. |
+
+## Plan
+
+1. Inventory existing reconciler and command specs against the table above; avoid duplicating narrow assertions already present.
+2. Add one acceptance-level spec using only fake/injected adapters and temporary files.
+3. If a real defect is exposed, preserve the failing reproducer and make only the smallest FCM-M3-002-required fix; otherwise leave production unchanged.
+4. Reconcile `docs/TASKS.md` only for delivered M1/M2/M3-001 truth and mark FCM-M3-002 in progress.
+5. Run focused tests, full `@mosaicstack/mosaic` tests, package/root typecheck and lint, Prettier/format and diff checks, plus adversarial fake-runner cases.
+6. Record exact evidence and leave the tree uncommitted for independent synthetic-tree review.
+
+## TDD decision
+
+This card adds acceptance coverage to already-delivered behavior. Test-first applies to any product defect discovered: retain a failing reproducer before an in-scope fix. If the shipped behavior already satisfies the acceptance contract, no production code will be changed and the acceptance suite itself is the deliverable.
+
+## Progress
+
+- Intake and immutable baseline verification complete.
+- Existing coverage inventory confirmed strong unit coverage but no stateful cross-command lifecycle acceptance harness.
+- Added `packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts`: one injected stateful fake systemd/tmux host, temporary canonical v2 and legacy-v1 roster fixtures, and seven acceptance tests.
+- Production source is unchanged; no product defect requiring an FCM-M3-002 fix was found.
+- `docs/TASKS.md` reconciles only merged M1/M2/M3-001 truth and marks FCM-M3-002 in progress.
+
+## Verification evidence
+
+All commands ran from `/home/jarvis/src/mosaic-stack-local-reconciler` and passed unless explicitly noted.
+
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/fleet-reconciler.acceptance.spec.ts` — final remediation run: 1 file, 7 tests passed; canonical v2 named-socket parsing/Commander status, missing/empty v2 rejection, and canonical legacy-v1 default-server runtime targeting are distinct reachable cases.
+- Focused reconciler/roster/transport command covering acceptance, reconciler, command, CRUD, v2 parser, and runtime transport specs — 8 files, 304 tests passed.
+- `pnpm --filter @mosaicstack/mosaic test` — final remediation run: 57 files, 827 tests passed.
+- `pnpm --filter @mosaicstack/mosaic typecheck` — passed.
+- `pnpm --filter @mosaicstack/mosaic lint` — passed.
+- `pnpm typecheck` — 42/42 Turbo tasks successful.
+- `pnpm lint` — 23/23 Turbo tasks successful.
+- `pnpm exec prettier --check docs/TASKS.md docs/scratchpads/758-fcm-m3-002-reconciler-lifecycle-gates.md packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts` — passed.
+- `pnpm format:check` — all matched files use Prettier style.
+- `git diff --check` — passed with no output.
+- Initial scoped Prettier check found style drift in the new spec and tracking table; `pnpm exec prettier --write ...` remediated it before all final gates above.
+- No live fleet, systemctl, tmux, process, site, migration, canary, deploy, runtime, connector, or remote command was invoked.
+
+## Review boundary
+
+This is an author handoff. No self-review is represented as reviewer-of-record. The uncommitted synthetic tree is intended for independent review.
+
+## Risks / blockers
+
+- M3 truthfully reports incomplete lifecycle effects and bounded recovery; it does not implement or claim an automatic rollback command. This suite proves stopped-state restoration by the documented exact recovery reconcile. M4 retains migration/canary rollback ownership.
+- The fake host models only the public systemd/tmux runner contract and temporary roster filesystem boundary. This is intentional under the no-live-effects hold.
+- Parent issue closure, commit, push, PR, merge, deployment, and branch cleanup remain explicit holds.
+- No residual implementation blocker.

docs/scratchpads/758-fcm-m4-001-v1-v2-migrator.md

@@ -0,0 +1,80 @@
+# FCM-M4-001 — v1-to-v2 inventory, preview, and migrator
+
+- **Task / issue:** FCM-M4-001 / mosaicstack/stack#758
+- **Branch / base:** `feat/758-v1-v2-migrator` from `origin/main` `c1aecfabe97a5dc81a72f44910cd4e626f41863f`
+- **Base tree:** `46cdfbcdc1d1ff9c7b8b2b9cf3841086590bf774`
+- **Scope:** field-complete inventory, non-mutating preview, canonical v2 migration output, and migration/recovery disposition evidence. All effects use injected fakes or temporary fixtures.
+- **Budget:** 35K task estimate is the hard working cap. Keep one card/one PR and prefer focused reuse of the v2 compiler, shared role resolver, generated-env boundary, M1 executable disposition inventory, and reconciler observations.
+
+## Objective
+
+Implement preview-first v1 migration that never infers unresolved classes or lifecycle, preserves observed running/stopped state, quarantines forbidden legacy environment inputs with key-name/SHA-256-only diagnostics, inventories remote/connector/schema-only entries without reconciling them, covers every M1-classified shipped artifact, and emits deterministic recovery disposition evidence for the later M4-002 canary/rollback gate.
+
+## Acceptance mapping
+
+1. Field-by-field v1 inventory and no-mutation preview.
+2. Canonical output compiled by `roster-v2.ts` and semantically validated by the existing baseline-plus-`roles.local` resolver.
+3. Only approved deterministic aliases; every other noncanonical class requires an explicit disposition.
+4. Observed stopped/running maps explicitly to persisted lifecycle; stopped observations never produce running targets.
+5. Generated env is regenerated; strict local data is relocated; forbidden keys are quarantine inputs reported only by key name and SHA-256.
+6. Remote/connector/schema-only entries are inventory-only and excluded from local reconciliation output.
+7. Every shipped M1 example/profile/service preset has executable migration disposition evidence.
+8. Deterministic migration/recovery evidence records source, output, exclusions, quarantine, and restore prerequisites without executing a canary or rollback.
+
+## Boundaries
+
+Out of scope: FCM-M4-002 executable canary/rollback and host fixture, #766 communications, #636 commands/channels, live fleet/systemd/tmux/session/migration/deploy/connector/remote/gateway effects, `docs/TASKS.md`, parent issue mutation, commit, push, and PR operations.
+
+## TDD plan
+
+Migration rules and redaction are critical data-mutation/security logic, so tests are written red-first for inventory completeness, explicit class disposition, observed-state preservation, quarantine redaction, inventory-only remote/schema entries, compiler/resolver reuse, artifact coverage, and recovery evidence. Production code follows only after the focused tests fail for the missing behavior.
+
+## Plan
+
+1. Map existing v1 loader, v2 compiler/resolver, env quarantine, reconciler observation, and M1 disposition guard.
+2. Add behavior-oriented failing migration tests with temporary fixtures and injected observation/filesystem adapters only.
+3. Implement the narrow migration module and CLI boundary without a second resolver or live command runner.
+4. Add scoped M4 migration/recovery documentation and executable shipped-artifact evidence.
+5. Run focused tests, full package tests, package/root typecheck and lint, formatting, diff checks, and adversarial redaction/no-effect verification.
+6. Run independent code/security review, remediate findings, reconstruct the synthetic tree using a temporary index, and stop uncommitted.
+
+## Progress
+
+- Collision checks passed: no local/remote branch, worktree, target path, or open PR owned `feat/758-v1-v2-migrator`.
+- Dedicated worktree created at the exact green `origin/main` base.
+- Required global/repository guides and FCM requirements/evidence loaded.
+- No matching migration skill exists under the configured skill directories; no unrelated skill loaded.
+- Added a preview-only CLI and migration module that compile with the existing v2 parser/renderer and validate through the shared persona resolver.
+- Added value-free raw-v1 inventory, strict unknown-field/synonym/duplicate detection, inventory-only remote and connector handling, and explicit class/tool-policy decisions.
+- Added separate reviewed lifecycle observations with only unambiguous running/stopped mappings.
+- Added sanitized, non-mutating environment preflight and recovery evidence explicitly marked non-executable.
+- Added executable disposition evidence derived from the exact 13-entry M1 inventory and operator documentation.
+- Tightened untrusted decisions/observations to reject unknown keys, invalid types/enums, extra local records, and competing automatic-alias dispositions.
+- Remediated independent review findings: v1 runtime/reset defaults are preserved, `~` workdirs expand only at env preflight, malformed/required agent fields fail closed before remote exclusion, and all seven shipped v1 fixtures now execute real previews with explicit evidence.
+- Remediated socket and locality authority blockers: socket-only agents stay local; `host == fleetHost` stays local; only `host != fleetHost` is inventory-only; ssh-only, missing reviewed fleet-host identity, and contradictory host/ssh targets block explicitly without lifecycle omission.
+- Remediated final exact-tree blockers: a declared v1 root socket cannot be overridden; matching/conflicting socket decisions retain reviewed running evidence; canonical ordering uses a shared locale-independent Unicode code-point comparator; migration evidence preserves all four legacy environment dispositions; backup documentation no longer claims validation that M4-001 does not perform.
+- Remediated immutable-review socket-presence blocker: both `socket_name` and `socketName` are field-presence-aware, so explicit empty/default-server declarations remain authoritative and incompatible named decisions block rather than replacing them.
+- Remediated the replacement-tree blockers: the shared v2 compiler and reconciler accept an explicit empty socket as literal default-server identity; present-empty holder session, default/agent work directory, runtime reset command, and alias values block rather than defaulting; missing preview inputs emit one stable blocked JSON object with non-zero status. Snake/camel aliases and whitespace-only input have adversarial coverage.
+- Remediated the subsequent authority blockers: each present-empty CLI path emits exactly one stable blocked JSON object with exit 1 before file reads, and reconciler `start`/`restart` or desired-state `apply`/`reconcile` fail closed before fixed `mosaic-fleet` systemd services can act on a default-server roster.
+- Remediated committed-head review blockers: explicitly declared empty runtime objects use the production v1 `/clear` reset fallback while omitted `pi` retains `/new`; lifecycle observations are sorted by canonical agent name; and bare CLI path flags reach preview validation, emit one stable blocked JSON object with exit 1, and perform zero reads. Built production-CLI subprocess tests cover all three bare flags.
+- Remediated late-audit blockers: the documented M4 guard invokes the 13-artifact validator and all seven v1 previews; canonical `~`/`~/...` workdirs remain unchanged in migration evidence and traversal-free forms expand at the shared production projection boundary while ordinary relative and home-relative traversal paths remain rejected; remote inventory and exclusion evidence sort canonically; and every default-server lifecycle-mutating reconciler path fails before observation, projection preparation/application, or fixed-unit effects. Explicit regressions preserve `plan`, `status`, `doctor`, and `verify` as observational default-server commands.
+- Remediated exact-tree traversal review: `~/../escape` and `~/src/../../escape` remain unexpanded and fail the unchanged shared `unsafe-path` validation. Both the shared generated-environment boundary and the production v1 environment caller have red-first regressions, preventing earlier caller normalization from bypassing the boundary.
+
+## Verification evidence
+
+- Focused migration/compiler/environment/reconciler/CLI: 8 files, 372 tests passed.
+- Documented 13-artifact guard: 1 matching test passed and executed all seven v1 previews.
+- Full `@mosaicstack/mosaic`: 59 files, 902 tests passed.
+- Workspace build: 23 tasks passed.
+- Root typecheck: 42 tasks passed.
+- Root lint: 23 tasks passed.
+- Root format check and `git diff --check`: passed.
+- Built production CLI: canonical `~/src` remains in ready roster/YAML evidence; generated projection preflight succeeds with no blockers; a bare path flag emits one blocked JSON object, exit 1, and no stderr.
+- Independent high-effort late-audit review: no blocker remained in the four assigned repair surfaces; separate exact-tree security audits found no qualifying newly introduced vulnerability.
+- Exact temporary-index synthetic tree includes every tracked changed path; immutable SHA and duplicate reconstruction are recorded in the final handoff.
+
+## Risks / blockers
+
+- M4-001 emits rollback prerequisites/evidence only; executable rollback/canary and the managed/unmanaged host fixture remain owned by M4-002.
+- Remote/connector entries remain inventory-only; later federation or connector reconciliation requires separately reviewed work.
+- Existing environment data is only preflighted. Cutover backup, quarantine write, legacy removal, and generated projection application remain later reviewed effects.

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

@@ -0,0 +1,216 @@
+# Scratchpad — #791 Upgrade config protection (ms-791 worker lane)
+
+**Lane:** web1:ms-791 → reports to MS-LEAD (web1:mosaic-100). Do NOT contact Jason/Mos directly.
+**Worktree:** `/home/hermes/agent-work/stack-agents-dir-791`, branch `feat/791-upgrade-config-protection`
+off `origin/main` `9745bc3f` (verified exact head).
+
+## Mission prompt (verbatim intent)
+Protect operator-owned config under `~/.config/mosaic` from framework-upgrade wipes. Ratified
+combination (Mos-approved, do NOT re-litigate): (b) strict ownership separation [PRIMARY] + (a)
+transactional pre-update snapshot [safety net] + (d) regeneration-from-SSOT [recovery]. (c) periodic
+timer DEFERRED. HARD GATE: unit test that an upgrade run touches NO path outside the manifest.
+Design-first: write design doc, send to MS-LEAD, WAIT for confirmation before impl.
+
+## Session 1 (2026-07-16) — Phase 1 design
+
+### Evidence gathered (wipe mechanism, file/line)
+- `mosaic update` → `update-checker.ts:509` `buildReseedCommand` → `bash install.sh`
+  (`MOSAIC_SYNC_ONLY=1`, `MOSAIC_INSTALL_MODE=keep`).
+- Wipe = `packages/mosaic/framework/install.sh:199` `rsync -a --delete` + `PRESERVE_PATHS` denylist
+  (`install.sh:47`). cp-fallback `install.sh:223` `find ... -exec rm -rf`.
+- Denylist gaps → WIPED: `agents/*.conf`, `policy/*.md`, `*.local.md`, harvester/SOP,
+  `tools/_lib/credentials.json`.
+- Stale comment `update-checker.ts:492` claims `*.local` preserved — PRESERVE_PATHS has no such entry.
+- TS path `file-adapter.ts:157` → `file-ops.ts:66` `syncDirectory` = non-destructive copy-overlay, BUT
+  its preserve list (`file-adapter.ts:164`) already DRIFTED from install.sh (missing `fleet/backlog`,
+  `fleet/roles.local`). Evidence for single shared manifest SSOT.
+- Existing snapshot (`install.sh:76`) = /tmp, crash-trap only, deleted on success → inadequate; no
+  `mosaic restore`.
+- `fleet-reconciler.ts:93,234` already has `regenerate-projections-from-roster` phase separate from
+  lifecycle → `mosaic fleet regen` = thin projection-only wrapper (no restart), no FCM-M4/M5 preemption.
+
+### Design decisions
+- **(b)** Invert to allow-list: shared `framework/framework-manifest.json` (framework globs +
+  operatorReserved carve-outs); resolve per-path, deny-wins; **UNKNOWN ⇒ operator (fail-safe)**.
+  Mechanism: drop `--delete`; non-deleting bulk copy + explicit manifest-scoped prune pass (iterate
+  framework globs only → operator/unknown structurally unreachable). Pure prune-planner fn for tests.
+- **(a)** Snapshot to `~/.local/state/mosaic/backups/pre-update-<ts>/` 0700/0600, retention N=5,
+  post-sync verify+restore, `mosaic restore --list/--from`. No secret values in output.
+- **(d)** `mosaic fleet regen` projection-only, preview-first, never restart.
+- HARD GATE test includes a deliberately-unanticipated operator path to prove fail-safe default.
+- **PR split:** PR1 manifest+guard (root fix, ships alone) → PR2 snapshot/restore (secrev) → PR3
+  regen+docs. PR2/PR3 depend on PR1.
+
+### Status
+Design doc written: `docs/design/791-upgrade-config-protection.md`. Sent to MS-LEAD.
+
+## Session 1 (cont.) — MS-LEAD CONFIRMED → Phase 2 GO
+All 4 asks approved. Binding conditions:
+- TDD tests-first, red-first proof per PR; ≥85% new-code; co-located `*.spec.ts`; never `--no-verify`.
+- HARD GATE test (§2.4, unanticipated sentinel survives byte-identical + mtime unchanged) = MERGE-BLOCKING for PR1.
+- Manifest-completeness test (§6.2) required.
+- Bash+TS read ONE shared `framework-manifest.json`; parity test (§6.1) required (closes #631 drift class).
+- UNKNOWN⇒operator (rule 3) non-negotiable. Keep prune-planner PURE.
+- `fleet regen`: NEVER restart; dry-run default, `--write` to apply; "never issues restart" test mandatory.
+- Independent review every PR; PR2 dedicated secrev.
+- One PR at a time through DAG. Report PR1 exact head + red→green evidence for review commission.
+
+### Now: implementing PR1 (manifest + resolver + non-deleting sync + scoped prune + guard tests).
+
+## Session 2 (2026-07-16) — PR1 built, tests-first, red→green proven
+
+Deviation noted to MS-LEAD in PR: manifest is `framework-manifest.txt` (line-oriented), NOT `.json`.
+Rationale: keep the bash installer free of a python3/jq dependency. The "ONE shared file, parity-
+tested" requirement is honored — `manifest-parity.spec.ts` drives the bash resolver as a subprocess
+and asserts byte-identical ownership vs the TS resolver over 34 probe paths spanning every class.
+
+### PR1 artifacts
+- SSOT: `packages/mosaic/framework/framework-manifest.txt` ([framework]/[operator], deny-wins, fail-safe).
+- TS resolver: `src/framework/manifest.ts` (pure: parse/matchGlob/resolveOwnership/frameworkSubtreeRoots/
+  planPrune) + `manifest.spec.ts` (18 tests incl. planPrune property test + §6.2 completeness).
+- Bash resolver: `framework/tools/_lib/manifest.sh` (compiled globs → fork-free `manifest_is_framework`;
+  CLI `resolve|subtree-roots|classify`). Sourced by install.sh.
+- HARD GATE (§2.4): `framework/tools/quality/scripts/test-upgrade-manifest-guard.sh` — keep-mode reseed,
+  10 operator sentinels (incl. unanticipated `unknown-operator-dir/x`, `harvester/sop.md`,
+  `fleet/my-fleet.yaml`) survive byte-identical + mtime-unchanged; retired framework file pruned;
+  secret value absent from output. RED=31 fail (orig install.sh) → GREEN=48 pass (fixed).
+- install.sh: keep mode now manifest-driven (`sync_framework_keep`, no `--delete`); overwrite unchanged.
+  PRESERVE_PATHS denylist deleted.
+- TS sync: `file-ops.syncDirectory` gains `isOperatorOwned` guard; `file-adapter.syncFramework` derives
+  it from `loadManifest` — hardcoded (drifted) preservePaths deleted. Fixture uses the REAL manifest.
+- Parity: `manifest-parity.spec.ts` (§6.1) — bash↔TS agree on 34 paths + subtree roots.
+- Migration matrix `test-install-migration.sh`: F6 flipped — `my-fleet.yaml` now MUST survive (fail-safe).
+- CI: new merge-blocking `upgrade-guard` step (`.woodpecker/ci.yml`) runs both bash suites (adds rsync).
+- update-checker.ts reseed comment corrected to the manifest model.
+
+### Gates (all green)
+- `pnpm typecheck` ✓ · `pnpm lint` ✓ · `pnpm format:check` ✓
+- Full mosaic vitest: 1062 passed (cli-smoke needs `pnpm build` first — build-artifact dep, not this change).
+- HARD GATE 48/48 · migration 21/21 · parity 3/3 · manifest 18/18 · file-adapter 8/8.
+
+### PR opened + reported (2026-07-16)
+- **PR #802** http://git.mosaicstack.dev/mosaicstack/stack/pulls/802 — base `main`@`9745bc3f`,
+  head `34e55d4a` (commit `feat(mosaic): manifest-owned upgrade guard…`). 15 files, +1160/-142.
+- Reported PR head + red→green evidence to MS-LEAD (web1:mosaic-100); queued (lead busy).
+  Standing by for the independent-review commission at head `34e55d4a`.
+- **TWO items flagged to MS-LEAD for decision (awaiting reply):**
+  1. Deviation `.txt` vs `.json` — confirm accept (parity-tested) or convert to `.json`+jq.
+  2. `pr-create -i 791` appended `Fixes #791` → would auto-close the tracking issue on PR1 merge
+     while PR2/PR3 remain. Recommended edit to `Part of #791`; awaiting go-ahead to patch PR body.
+- DO NOT start PR2/PR3 until PR1 merges (DAG; one PR at a time).
+
+### MS-LEAD ruling → #797 ledger-survival sentinel folded into PR1 (2026-07-16)
+MS-LEAD ruled both my decisions: (1) `.txt` format ACCEPTED (parity must be strict/merge-blocking incl.
+format edge cases + negative probe); (2) trailer `Fixes #791`→`Part of #791` APPROVED (patched PR #802
+body via Gitea API — tracking issue no longer auto-closes on PR1 merge). Plus Mos-ELEVATED merge-blocker
+(spec `~/agent-work/planning/epic-796/791-ledger-survival-sentinel-SPEC.md`): #797 Runtime Session Ledger
+must survive upgrade. Two coupled deliverables landed in PR1:
+- (i) Carve-out: `fleet/run/**` was ALREADY an explicit `[operator]` entry — glob matches the spec's
+  pinned `fleet/run/**` EXACTLY, so NO divergence to route back to planner-opus. Strengthened its comment
+  to name the ledger (`fleet/run/sessions/` events.ndjson + ledger.json) so it is unmistakably load-bearing.
+- (ii) HARD-GATE sentinel: seeded populated ledger (events.ndjson 3 events + ledger.json node+edge+gen,
+  0600 under 0700) into test-upgrade-manifest-guard.sh sentinels; asserts byte-identical + mtime-unchanged
+  + dir-perms unchanged. Negative control (retired framework file IS pruned) relabeled explicitly.
+  HARD GATE now 58/58 (was 48).
+- Decision-1 parity hardening: format-edge fixtures (comments/blanks/whitespace, duplicate+overlapping
+  globs deny-wins, section/glob-ordering independence) + explicit UNKNOWN→operator negative probe, driven
+  through BOTH resolvers via MANIFEST_FILE override. Parity 7/7 (was 3).
+- RED-FIRST honesty note: the bash ledger sentinel stays GREEN even against the pre-fix installer (the
+  ledger was incidentally safe from the rsync --delete bug; overall pre-fix run 30/58 as expected). The
+  carve-out's TRUE load-bearing value (deny-wins if framework ownership ever broadens to `fleet/**`) is
+  isolated by a dedicated resolver-seam red→green in manifest.spec.ts: WITHOUT `fleet/run/**` operator
+  entry + hypothetical `fleet/**` framework → ledger resolves framework and planPrune DELETES it (RED);
+  WITH the carve-out → deny-wins → operator, unprunable (GREEN). manifest.spec.ts 21/21 (was 18).
+- Gates all green: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1069 passed · HARD GATE 58/58
+  · migration 21/21. Committing FORWARD on the branch (NOT rebasing 34e55d4a out from under review).
+
+### MS-LEAD REQUEST CHANGES @ 0a5e703a → B1/B2/B3 fixed red-first (2026-07-16)
+MS-LEAD returned REQUEST CHANGES (routed merge-blockers satisfied; 2 CRITICAL reliability defects from
+the commissioned independent review). Fixed forward on the branch, red-first:
+- **B1 (CRITICAL) — dead ERR trap.** install.sh had `set -euo pipefail` (no `-E`), so the
+  `trap restore_snapshot ERR` never fired for a failure inside sync_framework_keep() (function body) —
+  a mid-sync abort left a half-written target with NO rollback. Fix: `set -Eeuo pipefail` (errtrace) +
+  disarm the trap at the top of restore_snapshot() to prevent re-entrancy. New gate
+  `test-upgrade-rollback.sh`: injects a mid-sync `cp` EACCES (read-only divergent framework file);
+  Part A asserts the shipped installer rolls back (restore message fires AND target byte-identical to
+  pre-upgrade); Part B control strips `-E` and asserts the rollback message does NOT fire (dead trap) —
+  self-verifying red→green. 7/7.
+- **B2/B3 (CRITICAL) — empty/unreadable/malformed manifest divergence.** Pre-fix: TS `parseManifest('')`
+  returned `{framework:[],operator:[]}` (NO throw) → silent no-op "Installation complete"; bash aborted
+  fragilely (the `_manifest_compile` `"${MANIFEST_OPERATOR[@]:-}"` artifact returned 1 with no message)
+  AND the CLI dispatch swallowed manifest_load's rc (no `|| exit`) so `resolve` exited 0 resolving
+  everything operator. Fix (fail-loud + identical both langs):
+  * TS `parseManifest`: throw on zero framework entries; `loadManifest`: wrap read error →
+    "Cannot read framework manifest …".
+  * bash `manifest_load`: explicit unreadable guard (`[[ ! -r ]]`) + zero-`[framework]` guard, both loud
+    stderr + return 1; `_manifest_compile` gets explicit `return 0` (kills the empty-array artifact);
+    CLI dispatch `manifest_load … || exit 1`.
+  * `finalize.ts`: wrap syncFramework → `spin.stop('Framework sync aborted …')` + rethrow (never falls
+    through to "Installation complete").
+  Tests: manifest.spec.ts +5 fail-closed (empty/comment-only/operator-only/empty-section/missing);
+  manifest-parity.spec.ts +7 failure-mode parity (both reject empty/comment-only/operator-only/
+  empty-section/entry-before-header/unknown-header/missing — TS throws, bash CLI exits non-zero+stderr);
+  HARD GATE +4 end-to-end fail-closed matrices (empty/operator-only/malformed/missing → abort non-zero,
+  manifest error surfaced, every operator sentinel byte-identical). RED proven by reverting
+  manifest.ts+manifest.sh to HEAD → 12 new tests fail; restore → 40/40 green.
+- **Non-blocking addressed.** MEDIUM install.sh:222 find-empty now warns on a real failure instead of
+  blanket `|| true`. LOW: corrected the "both destructive paths rsync vs cp" overstatement in the HARD
+  GATE header + cp-fallback comment + ci.yml (keep mode is a single cp-based path; the rsync-present vs
+  -absent runs prove rsync-independence). `.pre-constitution.bak` triage: single-shot backup is
+  intentional (reconcile_framework_files backs up once), no change.
+- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1081 passed (was 1069, +12) · HARD GATE
+  118/118 (was 58) · rollback 7/7 (new) · migration 21/21. No --no-verify. Rollback test wired into
+  ci.yml upgrade-guard. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
+
+### Codex round 2 (pre-push self-review) → blockers A/B + should-fix C fixed red-first (2026-07-16)
+Before committing round 1 I re-ran codex on the change set; it surfaced two fresh reliability defects
+and one messaging defect on the SAME rollback/manifest path. Fixed forward, red-first:
+- **Blocker-A (CRITICAL) — signal trap resumed instead of terminating.** A bash INT/TERM handler that
+  merely `restore_snapshot` (returns) does NOT terminate the script — execution RESUMES past the
+  interrupt, cleans the snapshot and reports success, leaving a partial post-interrupt update. Fix:
+  `trap 'restore_snapshot; exit 1' ERR INT TERM` so both the errtrace (ERR) and signal (INT/TERM) paths
+  exit non-zero. Rollback test Part C: a `cp` shim that `kill -TERM $PPID` mid-sync then succeeds (so
+  set -e never fires and only the signal path governs) → asserts abort non-zero + restore fires + does
+  NOT print "file phase complete"; control strips `exit 1` and asserts the buggy resume-to-success.
+- **Blocker-B (CRITICAL) — degenerate `[framework]` section resolved everything operator.** A manifest
+  whose framework entries are all empty / bare-dot (`/`, `./`, `.`, `..`) passed the non-empty guard yet
+  yielded zero usable globs → nothing is framework → a keep-mode sync silently no-ops (bash resolved
+  `operator`, exit 0). Fix (both langs, parity): reject when no entry has a char other than `/`/`.` —
+  TS `isUsableFrameworkGlob` = `/[^/.]/.test(normalizeRel(glob))`, throws `ManifestError`; bash mirror
+  loops `[[ "$(_manifest_norm "$_g")" =~ [^/.] ]]`, loud stderr + return 1. Tests: manifest.spec.ts
+  `it.each(['/','./','.','..','/\n./'])` throw; parity +3 `expectBothReject` (root-slash/dot-slash/
+  bare-dot). RED: reverting the guard makes `[framework]\n/` resolve `operator` exit 0.
+- **Should-fix-C — misleading abort message.** finalize.ts printed one generic "may be partially
+  applied" for every sync failure. A `ManifestError` is a PRE-sync validation abort (manifest is
+  validated before any copy) → nothing was written; conflating it with a mid-copy failure misdirects
+  recovery. Fix: introduce `ManifestError` (exported from manifest.ts, thrown by every fail-closed
+  parse/load path), and classify in finalize.ts — ManifestError → "no files were changed"; any other →
+  "may be partially applied". New co-located `finalize-sync-abort.spec.ts` (3 tests) asserts both
+  branches re-throw the original error + the correct message, and that config writes are never reached.
+  RED proven by collapsing the classification → the ManifestError test fails.
+- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 (was 1081, +3 finalize-abort;
+  manifest specs already counted) · HARD GATE 193/193 · rollback 14/14 · migration 21/21.
+
+### Codex round 3 (pre-push self-review) → blockers D1/D2 fixed red-first (2026-07-16)
+Re-ran codex again; it found two more rollback-path gaps `set -E` cannot catch. Fixed forward, red-first:
+- **Blocker-D1 (CRITICAL) — `find` scan failures swallowed by process substitution.** Both the overlay
+  copy and the scoped prune consumed `< <(find … -print0)`. Bash does NOT propagate the producer's exit
+  status to the `while`, so an EACCES/I/O failure mid-scan truncates the file list yet leaves the loop
+  exiting 0 → a partial upgrade commits and reports success; the ERR/restore trap never fires. Fix:
+  `_scan_or_die` runs `find … -print0 > "$tmp"` to completion, checks its status, and returns non-zero
+  (→ ERR trap → restore) on failure; both loops now read from the checked temp file. Rollback test
+  Part D: a `find` shim that fails every `-print0` scan → shipped installer aborts non-zero + restores +
+  emits "Could not enumerate framework files" + target byte-identical; control neuters the `# D1-GUARD`
+  `return 1` → find failure swallowed, upgrade wrongly reports "file phase complete", no rollback.
+- **Blocker-D2 (CRITICAL) — silent `set -e` exit on a failed target reset.** restore_snapshot did a bare
+  `rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"` (trap disarmed, under set -e). If `rm`/`mkdir` fails —
+  possibly after `rm` deleted part of the target — the script exits immediately, skipping the cp AND the
+  recovery pointer, leaving a half-removed target and an orphaned snapshot the operator can't locate.
+  Fix: `if ! rm -rf … || ! mkdir -p …; then fail "Snapshot restore could not reset … preserved at:
+  $SNAPSHOT_DIR — copy it back …"; return 1; fi` (tested like the cp -a check; snapshot NOT deleted).
+  Rollback test Part E: cp-poison triggers restore + an `rm` shim fails `rm -rf <TARGET>` → shipped
+  emits the recovery pointer, the named snapshot dir survives, secret value never leaked; control deletes
+  the recovery line → operator gets no pointer. RED: reverting D1+D2 → 7 shipped/control assertions fail.
+- 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).

docs/scratchpads/issue-766-exact-fleet-comms.md

@@ -0,0 +1,80 @@
+# Issue 766 — exact cross-harness fleet comms targeting
+
+- **Issue:** #766
+- **Branch:** `fix/766-exact-fleet-comms`
+- **Worktree:** `/home/jarvis/src/stack-issue-766`
+- **Delivery boundary:** source/tests/docs only; no live tmux, session, or fleet actions; leave uncommitted for independent review.
+
+## Objective
+
+Replace inference-prone fleet onboarding guidance with one roster-resolved contract that gives Claude Code, Codex, OpenCode, and Pi the same authoritative local identity and exact executable command for every known peer.
+
+## Plan
+
+1. Add issue-specific normative requirements to `docs/PRD.md` before source changes; do not modify orchestrator-owned `docs/TASKS.md`.
+2. Extract the existing v1 roster parsing/normalization into one lightweight shared resolver used by both fleet commands and runtime comms composition.
+3. Write failing contract tests for explicit SSH-only cross-host targeting, global/default socket authority, authoritative identity, unknown-peer failure, no operational metavariables, and four-harness parity.
+4. Make source `TOOLS.md` non-operational and marker-versioned; prove fresh installation preserves that exact contract and composition detects a stale installed copy without rewriting it.
+5. Render a deterministic comms generation and document comparison/relaunch handling; never rewrite an active session.
+6. Run focused Vitest and shell exact-target tests, then package/repository typecheck, lint, format, test, and build gates as relevant.
+7. Reconstruct the exact uncommitted tree, including untracked files, for independent review and remediate findings without committing.
+
+## Contract decisions
+
+- `tmux.socket_name` is the one supported socket authority for every local fleet session. A per-agent `socket`, when present for compatibility, must equal that global value; independent per-agent sockets fail closed because the runtime does not provision them. A named socket renders `-L`, while the empty literal default renders no `-L`.
+- A peer is same-host only when its resolved host equals the current roster member's resolved host. Every host-omitted member resolves against the stable local fleet-host baseline, never against the viewer's explicit host. Same-host rows never render `-H`.
+- A cross-host row requires that peer's explicit roster `ssh`; absence is a contract error. Never substitute `host` as an SSH target.
+- The current member's explicit roster `host` wins; otherwise the local machine's short hostname is the baseline for host-omitted local members.
+- Unknown members/peers return a deterministic error listing exact known names and an exact self-scoped discovery command. No fuzzy session lookup.
+- Exact command fields are structurally constrained to safe targeting grammars and shell-rendered as individual arguments. Unsafe host/SSH/socket values fail roster normalization rather than entering executable guidance.
+- Existing installed `TOOLS.md` remains user-owned during ordinary keep-mode updates. Currency requires the expected source and installed marker/version plus bounded SHA-256 byte identity. Explicit `mosaic update --repair-tools` is the supported current-version recovery path: it makes a digest-qualified no-clobber backup, restores the contract and regular executable helper, and does not rewrite active context.
+- The v1 resolver preserves and validates `tmux`, `discord`, and `matrix` connector blocks in YAML and JSON; conflicting snake/camel aliases fail closed unless their values are identical.
+- JSON roster fallback occurs only when `roster.yaml` is absent. Keep-mode reseed preserves both formats, and relaunch discovery uses the same canonical resolver.
+- The helper is inspected without following symlinks and must be a regular executable file. Missing, directory, symlink, and non-executable installations fail closed with deterministic repair guidance.
+- Active contexts carry a deterministic comms generation. Operators compare it to `mosaic agent comms-block <exact-agent>` output; mismatch means stale and requires an explicit exact-agent relaunch.
+
+## Risks
+
+- Import cycles if runtime composition imports the command-heavy `fleet.ts`; mitigate with a lightweight shared roster module and re-export compatibility.
+- Existing schema prose allowed independent per-agent sockets even though runtime provisioning used one global socket; constrain compatibility declarations to the global value and preserve empty-global default behavior.
+- Remote inventory may be incomplete. Fail composition closed for an unreachable cross-host row rather than generating a guessed command.
+- `TOOLS.md` is user-seeded and intentionally preserved. Detect/report drift instead of overwriting custom content.
+
+## Planned evidence
+
+- `comms-onboarding.spec.ts`: resolver/renderer/failure/generation contracts.
+- `compose-contract.spec.ts`: identical authoritative comms section for all four harnesses and stale installed-contract reporting without mutation.
+- `file-adapter.test.ts`: source-to-fresh-install byte equality and preservation of customized installed `TOOLS.md`.
+- Existing `agent-send.test.sh`, socket isolation, and tmux runtime transport tests.
+- Repository quality gates and independent uncommitted-tree review.
+
+## Evidence log
+
+- Preflight collision scan: no issue-766 local/remote branch, worktree, or open PR collision before branch creation.
+- Isolated branch created from fetched `origin/main` at `4990905`; original checkout not edited.
+- One strict v1 resolver now serves fleet commands and communications composition; roster writes preserve `host`, `ssh`, and `socket`.
+- Exact renderer covers authoritative self identity, global/default socket authority, rejected independent sockets, stable hostless-peer resolution, same-host omission of `-H`, explicit-SSH-only cross-host rows, shell-safe argv rendering, deterministic generations, and fail-closed unknown/missing targets.
+- Real framework `defaults/TOOLS.md` is tested byte-equal through a fresh `FileConfigAdapter` install, the installed helper is executable, and the final Pi contract contains the same source contract plus exact generated command; separate parity coverage proves byte-equivalent comms sections for Claude Code, Codex, OpenCode, and Pi.
+- Second review remediation adds strict connector/alias coverage, full-semantic generation coverage, ENOENT-only fallback, no-follow helper validation, unconditional current-version repair, digest-qualified no-clobber backups, and marker/version-gated currency.
+- The helper, roster, installed TOOLS, and framework source files are read with canonical containment, every existing ancestor and target rejected if symlinked, `O_NOFOLLOW` descriptor reads, inode stability checks, and effective-identity execute access. Read-only TOOLS status treats source/installed symlinks as unavailable without following or rewriting them.
+- Explicit repair validates both bundled inputs before destination creation, stages backup/TOOLS/helper plus exact-mode rollback files before any persistent file commit, revalidates destination identity at each commit boundary, installs the digest backup without clobber, and removes or exactly rolls back every committed output on injected failure. `changed: false` is returned only after full cleanup; cleanup/rollback failure is reported as `changed: true`.
+- Connector schema and runtime normalization require kind-matching settings and reject inactive connector blocks. Keep-mode installers preserve only exact `roster.yaml`, `roster.json`, `agents/`, and `run/` paths while refreshing framework `roster.schema.json`; shell evidence covers byte preservation and schema refresh.
+- Solo contracts render normalized role/class plus explicit no-peer/no-remote authority boundaries; composed-contract evidence keeps role Mandate/Boundaries before Fleet Comms.
+- Operational documentation and CLI metavariable now use `mosaic agent comms-block <exact-member>`; historical issue-633 scratchpad text remains historical.
+- The latest independent review rejected synthetic tree `556ae4ea04f2715a4e9d381f3cafaf4c8b991b2e` on three mandatory findings: installed `TOOLS.md` could be read through target/ancestor symlinks before unsafe status was reported; ambient class/tool-policy state could split identity authority from the canonical roster member; and the connector schema admitted empty or whitespace-only Discord/Matrix strings rejected by runtime parsing.
+- Red-first reproduction proved all three findings with 20 failures and 79 passes. Remediation routes installed `TOOLS.md` through the bounded secure regular-file reader before composition, resolves one exact canonical fleet identity for persona/tool policy/normalized class/Fleet Comms, rejects canonicalized ambient class mismatches, canonicalizes compatibility classes during roster parsing, and aligns parser/schema non-whitespace requirements.
+- Four-runtime coverage proves unsafe target and ancestor symlink content is omitted without mutation, while Claude Code, Codex, OpenCode, and Pi all project the same canonical member authority. Connector parser/schema coverage includes empty and whitespace-only Discord `channel_id` and Matrix `homeserver_url`, `user_id`, and `room_id` values.
+- Remediated focused gates passed: 99/99 across the two finding-focused suites plus connector schema regression PASS; the six changed-suite matrix passed 341/341; secure-file/transaction coverage remains green, including 28/28 transactional repair tests; installer migration passed 21/21.
+- Mosaic package suite passed 906/906. Shell/runtime regressions passed: `agent-send.test.sh` `PASS=11 FAIL=0`; named-socket isolation; matrix/tmux transport 12/12 (Matrix 5/5, tmux 7/7).
+- Final repository gates passed: format check; typecheck 42/42 tasks; lint 23/23; tests 42/42 tasks (Mosaic 906/906, gateway 628 passed/12 skipped); build 23/23.
+- A subsequent immutable review of tree `aa6414123643a504145fce6ac1d66f0b535feb5e` found one roster-authority blocker: a canonical member with omitted `tool_policy` inherited ambient `MOSAIC_AGENT_TOOL_POLICY`. Red-first four-runtime coverage failed 4/39 specifically on the leaked operator-interaction policy. Composition now branches on canonical membership: fleet launches use only `canonicalMember.toolPolicy` (including canonical absence), while genuinely non-fleet launches retain ambient fallback.
+- Final remediated gates passed: four-runtime regression 39/39; six changed-suite matrix 345/345; connector schema regression PASS; Mosaic package 910/910; installer migration 21/21; `agent-send.test.sh` 11/11; named-socket isolation PASS; Matrix/tmux transport 12/12; repository format PASS; typecheck 42/42 tasks; lint 23/23 tasks; tests 42/42 tasks; build 23/23 tasks.
+- No live tmux/session/fleet mutation, commit, push, PR mutation, issue mutation, context mutation, or reviewer launch performed.
+- Exact synthetic-tree reconstruction and frozen evidence are included in the coordinator handoff.
+- Sole-remediation preflight reverified the clean committed checkout at head `0dc47cac92c93a3ffd39ba9dd6685ac4165f6361`, tree `538de6ccce1f8c44ba288a7493286e63a3413e75`, branch `fix/766-exact-fleet-comms`; issue and PR state were read only through Mosaic wrappers.
+- Deterministic red-first ancestor substitution swapped validated `root/tools` for an external symlink immediately after `lstat`; current head returned `external marker` (`1 failed, 4 passed`) before implementation.
+- Secure reads now hold `/` and every root/descendant directory descriptor, traverse appended components through Linux `/proc/self/fd` with `O_DIRECTORY|O_NOFOLLOW`, and read plus effective-identity execute-check the same final descriptor. Non-Linux or unavailable proc-fd capability fails closed; stable errors redact managed paths while retaining Node `code` compatibility for missing/non-executable repair behavior.
+- Added deterministic root-selection, descendant-ancestor, and final-target substitution coverage. All return trusted descriptor-bound bytes after rename/symlink replacement; the race suite passed 50/50 repeated runs.
+- Isolated CLI verification drove `mosaic agent --mosaic-home <fixture> comms-block self` while repeatedly swapping `fleet/` with an external symlink: `trusted=2 fail_closed=10 external_marker=0`; a persistent symlink ancestor exited 1 with a redacted unsafe-ancestor error. No live fleet state was used or mutated.
+- Remediation gates: focused secure-file/comms/launch/tmux/Matrix `110/110`; full `@mosaicstack/mosaic` `914/914`; package and repository typecheck pass (`42/42` repository tasks); package and repository lint pass (`23/23` repository tasks); repository format check and `git diff --check` pass.
+- Independent review found one production hardening blocker (nonblocking final open), one redacted-error blocker, and a deterministic ancestor-test gap. Remediation added `O_NONBLOCK`, normalized execute errors while preserving errno, proved the ancestor hook fires, and added final-target substitution coverage; post-remediation review evidence is clean on the production invariant.

packages/mosaic/framework/defaults/TOOLS.md

@@ -5,20 +5,20 @@ Tool suites live at `~/.config/mosaic/tools/<suite>/`. This is the index only.
 read it (or the relevant service guide) when your task actually touches that service.
 Project-specific tooling belongs in the project's `AGENTS.md`, not here.
 
-## ⚡ Most-used fleet tools (reach for these FIRST — don't hand-roll)
+## Most-used fleet tools (reach for these first)
 
-You are a Mosaic fleet agent. These cover the highest-frequency cross-agent and git-provider
-tasks — use them before improvising with raw `tmux send-keys`, raw `tea`/`gh`/`glab`, or `curl`.
+<!-- fleet-comms-contract: 1 -->
 
-**1. Message another agent** → `tools/tmux/agent-send.sh` (NOT raw `tmux send-keys`):
+You are a Mosaic fleet agent. Use the runtime-composed **Fleet Comms — authoritative exact targets**
+section for inter-agent messaging. It renders your authoritative local host, exact agent/session, resolved
+tmux socket, installed helper path, generation, and one executable command per known peer.
 
-```bash
-tools/tmux/agent-send.sh -s <target-session> -m "message"   # or -f <file> to send a file's contents
-```
+Select only a peer row rendered for your exact roster identity. Never invent, substitute, or fuzzy-match
+a host, session, socket, SSH destination, or helper path. If a peer is absent, stop and run the exact
+self-scoped discovery command shown in that composed section; report the peer as unknown if it remains
+absent. Do not use raw `tmux send-keys` for fleet messaging.
 
-The coordinator session is `mos-claude` — send status, findings, and questions there.
-
-**2. Issues / PRs / milestones** → `tools/git/*.sh` wrappers (before raw `tea`/`gh`/`glab`):
+**Issues / PRs / milestones** → `tools/git/*.sh` wrappers (before raw `tea`/`gh`/`glab`):
 
 ```bash
 tools/git/pr-create.sh ...   tools/git/issue-create.sh ...   tools/git/pr-merge.sh ...

packages/mosaic/framework/fleet/roster.schema.json

@@ -94,11 +94,11 @@
             "type": "string"
           },
           "ssh": {
-            "description": "SSH target (user@host) for a cross-host peer, so onboarding renders the `agent-send.sh -H <user@host>` form. Optional; only needed for agents on a different host than the fleet.",
+            "description": "Explicit SSH target (normally user@host) for a cross-host inventory peer. Exact comms rendering requires this whenever the peer's resolved host differs from the current agent's host; the host value is never substituted as an SSH destination.",
             "type": "string"
           },
           "socket": {
-            "description": "tmux socket the agent's session runs on. Onboarding renders `-L <socket>` when set; absent = the default socket (no `-L`). Must match the LIVE socket, not blindly inherit the roster's tmux.socket_name.",
+            "description": "Optional compatibility declaration of the fleet-wide tmux socket. When present it must exactly equal tmux.socket_name; independent per-agent sockets are rejected because the local fleet runtime provisions every session on the fleet-wide socket.",
             "type": "string"
           },
           "working_directory": {
@@ -150,29 +150,67 @@
       "description": "Orchestrator chat connector (F4). Optional — absent means tmux (back-compat). Secrets (access/bot tokens) come from the environment, never this file.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind"],
-      "properties": {
-        "kind": {
-          "enum": ["tmux", "discord", "matrix"]
-        },
-        "matrix": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["homeserver_url", "user_id", "room_id"],
-          "properties": {
-            "homeserver_url": { "type": "string" },
-            "user_id": { "type": "string" },
-            "room_id": { "type": "string" }
+      "oneOf": [
+        {
+          "properties": { "kind": { "const": "tmux" } },
+          "required": ["kind"],
+          "not": {
+            "anyOf": [{ "required": ["discord"] }, { "required": ["matrix"] }]
           }
         },
-        "discord": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["channel_id"],
+        {
           "properties": {
-            "channel_id": { "type": "string" }
-          }
+            "kind": { "const": "discord" },
+            "discord": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["channel_id"],
+              "properties": {
+                "channel_id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "\\S"
+                }
+              }
+            }
+          },
+          "required": ["kind", "discord"],
+          "not": { "required": ["matrix"] }
+        },
+        {
+          "properties": {
+            "kind": { "const": "matrix" },
+            "matrix": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["homeserver_url", "user_id", "room_id"],
+              "properties": {
+                "homeserver_url": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "\\S"
+                },
+                "user_id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "\\S"
+                },
+                "room_id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "\\S"
+                }
+              }
+            }
+          },
+          "required": ["kind", "matrix"],
+          "not": { "required": ["discord"] }
         }
+      ],
+      "properties": {
+        "kind": { "enum": ["tmux", "discord", "matrix"] },
+        "matrix": { "type": "object" },
+        "discord": { "type": "object" }
       }
     }
   }

packages/mosaic/framework/framework-manifest.txt

@@ -0,0 +1,85 @@
+# Mosaic framework path-ownership manifest — SSOT for the updater.
+#
+# This single file is the source of truth consumed by BOTH the bash installer
+# (packages/mosaic/framework/install.sh) and the TypeScript config adapter
+# (packages/mosaic/src/config/file-adapter.ts). A parity test asserts both
+# paths resolve the same ownership from this file, so the two can never drift
+# (the failure mode that #631 patched by hand in two places).
+#
+# Format: one glob per line, relative to the mosaic home (~/.config/mosaic).
+#   - Lines starting with '#' and blank lines are ignored.
+#   - '[framework]' / '[operator]' switch the active section.
+#   - '**' matches any depth; '*' matches within a single path segment.
+#
+# Ownership resolution for a path P (deny-wins / fail-safe):
+#   1. P matches an [operator] glob            -> operator-owned.
+#   2. else P matches a [framework] glob        -> framework-owned.
+#   3. else (matches neither)                   -> OPERATOR-OWNED BY DEFAULT.
+#
+# Rule 3 is the root-cause fix for #791: a path the manifest authors never
+# anticipated is protected because UNKNOWN defaults to operator. The updater
+# may only ever create/overwrite framework-owned paths, and may only prune a
+# framework-owned path that lives inside a shipped framework subtree and is
+# absent from the current framework source (a genuinely retired file).
+# Operator-owned and unknown paths are structurally unreachable by pruning.
+
+[framework]
+# Top-level framework contract files (also reconciled from defaults/ on upgrade).
+CONSTITUTION.md
+AGENTS.md
+STANDARDS.md
+# Shipped framework subtrees — pruning is scoped to these roots.
+adapters/**
+constitution/**
+CONTRIBUTING.md
+defaults/**
+examples/**
+guides/**
+install.sh
+install.ps1
+LICENSE
+profiles/**
+runtime/**
+systemd/**
+templates/**
+tools/**
+# Fleet: only the framework-seeded fleet subtrees are framework-owned.
+fleet/README.md
+fleet/examples/**
+fleet/profiles/**
+fleet/roles/**
+fleet/roster.schema.json
+fleet/services/**
+# The manifest itself is framework-owned.
+framework-manifest.txt
+
+[operator]
+# Identity / user-seeded contract files — generated by the wizard or seeded
+# once from defaults/, then owned by the operator. Never overwritten on upgrade.
+SOUL.md
+USER.md
+TOOLS.md
+# Local overlays (tighten-only) authored by the operator.
+*.local.md
+# Operator-owned trees the updater must never write over or prune.
+agents/**
+policy/**
+memory/**
+sources/**
+credentials/**
+# Secret-bearing operator file INSIDE the framework-owned tools/ subtree.
+# Listed explicitly so the deny-wins rule carves it out of tools/**.
+tools/_lib/credentials.json
+# Operator-owned fleet state (roster SSOT, per-agent env, heartbeats, backlog,
+# persona overrides). Losing these silently downgrades a running fleet (#791).
+fleet/roster.yaml
+fleet/roster.json
+fleet/agents/**
+# Runtime state, incl. the #797 Runtime Session Ledger at fleet/run/sessions/
+# (events.ndjson journal + ledger.json projection). This carve-out is the
+# mechanism that makes the ledger upgrade-safe: an upgrade that wiped it would
+# defeat its reason to exist. The HARD GATE (test-upgrade-manifest-guard.sh)
+# proves a populated ledger survives byte-identical + mtime-unchanged.
+fleet/run/**
+fleet/backlog/**
+fleet/roles.local/**

packages/mosaic/framework/install.sh

@@ -1,5 +1,10 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# -E (errtrace): the ERR trap must propagate INTO functions and command
+# substitutions. Without it the `trap restore_snapshot ERR` set below is dead
+# code for any failure inside sync_framework_keep() (its whole body runs in a
+# function) — a mid-sync failure would abort with a half-written target and NO
+# rollback (#791 B1). Keep -E first so every later function inherits the trap.
+set -Eeuo pipefail
 
 # ─── Mosaic Framework Installer ──────────────────────────────────────────────
 #
@@ -19,32 +24,19 @@ SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 
-# Files/dirs protected from rsync --delete during sync. NOTE: framework-owned
-# entries (CONSTITUTION/AGENTS/STANDARDS) ARE re-applied afterward by
-# reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
-# User-created content in these paths survives rsync --delete.
-#
-# fleet/* — the framework SEEDS fleet/examples, fleet/roles, fleet/profiles, and
-# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
-# and fleet/profiles/*.yaml system-type profile lands automatically via this sync,
-# so no per-file entry is needed; the preserved "fleet/*.yaml" glob is anchored to
-# the top level only and does NOT shadow fleet/profiles/*.yaml). The user's
-# own fleet files MUST
-# survive `mosaic update` (which runs this sync automatically): the active
-# roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
-# (`fleet/agents/`), heartbeat run dir (`fleet/run/`), and the Mosaic-native
-# backlog-of-record store (`fleet/backlog/` — embedded PGlite data dir; see
-# packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update
-# wipes the operator's fleet AND their backlog. Glob entries are honored by
-# both the rsync path (`--exclude`) and the glob-aware cp fallback below.
-#
-# fleet/roles.local — the persona OVERRIDE layer (H4). Baseline personas in
-# fleet/roles/ are reseeded normally on every update (delivering new baseline
-# personas), so any local edit there would be clobbered. User customizations
-# and user-ADDED personas instead live in fleet/roles.local/ and MUST survive
-# `mosaic update` — they win over the baseline on merge (AC-NS-7; see
-# packages/mosaic/src/commands/fleet-personas.ts).
-PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog" "fleet/roles.local")
+# Shared framework path-ownership manifest reader (#791). Parity with
+# packages/mosaic/src/framework/manifest.ts — both consume framework-manifest.txt.
+# Sourcing does not run its CLI dispatch (guarded by BASH_SOURCE==$0).
+# shellcheck source=tools/_lib/manifest.sh
+source "$SOURCE_DIR/tools/_lib/manifest.sh"
+
+# Which paths a keep-mode upgrade may touch is no longer a hand-maintained
+# denylist. It is derived from the shared framework-manifest.txt (#791): the
+# updater only ever creates/overwrites framework-owned paths and only prunes a
+# retired framework file inside a shipped framework subtree. Everything else —
+# every operator file, and every path the manifest never anticipated — is
+# operator-owned by default (fail-safe) and is never written or deleted. See
+# sync_framework_keep() below and packages/mosaic/src/framework/manifest.ts.
 
 # Framework-owned contract files: re-copied from defaults/ on every upgrade (the
 # user must not edit them; a divergent copy is backed up once before overwrite).
@@ -75,14 +67,45 @@ step() { echo -e "\n${BOLD}$1${RESET}"; }
 SNAPSHOT_DIR=""
 make_snapshot() {
   is_existing_install || return 0
+  # mktemp -d creates the dir 0700 — the snapshot (which mirrors operator config,
+  # possibly including secrets) is never world-readable.
   SNAPSHOT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-snapshot-XXXXXX")"
-  cp -a "$TARGET_DIR/." "$SNAPSHOT_DIR/" 2>/dev/null || true
+  # The snapshot MUST be complete: restore rebuilds the target from it, so a
+  # partial capture (unreadable file, disk-full, I/O error) would silently
+  # discard whatever it missed. If cp -a cannot copy the whole tree, abort NOW —
+  # before the restore trap is armed and before anything is mutated. Fail closed
+  # rather than proceed with a snapshot we cannot trust (#791 blocker-2).
+  if ! cp -a "$TARGET_DIR/." "$SNAPSHOT_DIR/"; then
+    fail "Could not capture a complete pre-upgrade snapshot of $TARGET_DIR — aborting before any changes were made (fail-closed)."
+    rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""
+    exit 1
+  fi
 }
 restore_snapshot() {
+  # Disarm the trap first: restore runs under `set -e`, and a non-zero step
+  # inside it must not re-enter this handler (errtrace makes ERR fire in
+  # functions now). One restore attempt, then let the script exit non-zero.
+  trap - ERR INT TERM
   [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] || return 0
   fail "Install interrupted/failed — restoring previous state from snapshot"
-  rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"
-  cp -a "$SNAPSHOT_DIR/." "$TARGET_DIR/" 2>/dev/null || true
+  # Reset the target before rebuilding from the snapshot — but CHECK it. Under
+  # `set -e` (trap already disarmed) a bare `rm -rf; mkdir -p` that fails would
+  # exit the whole script immediately, after `rm` may have deleted part of the
+  # target, WITHOUT ever printing the recovery pointer below — the operator would
+  # be left with a half-removed target and no idea the snapshot survives in /tmp.
+  # Test the reset explicitly (like the cp -a below), and on failure keep the
+  # snapshot and tell the operator where it is (#791 blocker-D2).
+  if ! rm -rf "$TARGET_DIR" || ! mkdir -p "$TARGET_DIR"; then
+    fail "Snapshot restore could not reset $TARGET_DIR. Your previous configuration is preserved at: $SNAPSHOT_DIR — copy it back into $TARGET_DIR manually."
+    return 1
+  fi
+  # Surface an incomplete restore instead of swallowing it: the snapshot is the
+  # last good copy, so if cp cannot fully rebuild the target we must NOT delete
+  # the snapshot — point the operator at it for manual recovery (#791 blocker-2).
+  if ! cp -a "$SNAPSHOT_DIR/." "$TARGET_DIR/"; then
+    fail "Snapshot restore did not complete cleanly. Your previous configuration is preserved at: $SNAPSHOT_DIR — copy it back into $TARGET_DIR manually."
+    return 1
+  fi
 }
 cleanup_snapshot() { [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] && rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""; }
 
@@ -184,63 +207,105 @@ sync_framework() {
     return
   fi
 
-  if command -v rsync >/dev/null 2>&1; then
-    local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak")
-
-    if [[ "$INSTALL_MODE" == "keep" ]]; then
-      # Anchor to the transfer root (leading /) so we preserve the TOP-LEVEL
-      # ~/.config/mosaic/<file> without also excluding defaults/<file> from sync
-      # (reconcile_framework_files needs the freshly-synced defaults/ copies).
-      for path in "${PRESERVE_PATHS[@]}"; do
-        rsync_args+=(--exclude "/$path")
-      done
-    fi
-
-    rsync "${rsync_args[@]}" "$SOURCE_DIR/" "$TARGET_DIR/"
+  if [[ "$INSTALL_MODE" == "keep" ]]; then
+    # The `mosaic update` path. Manifest-driven, never-deleting-outside-framework:
+    # operator config is structurally protected (#791). No rsync --delete here.
+    # The manifest is already loaded+validated in main() BEFORE the snapshot/trap
+    # (a fail-closed manifest must abort without ever restoring over operator
+    # files — see the pre-flight in main, #791 blocker-1).
+    sync_framework_keep
     return
   fi
 
-  # Fallback: cp-based sync. Glob-aware so entries like "fleet/*.yaml" preserve
-  # every matching user file (parity with the rsync --exclude path above).
-  local preserve_tmp=""
-  if [[ "$INSTALL_MODE" == "keep" ]]; then
-    preserve_tmp="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-preserve-XXXXXX")"
-    local match rel
-    for path in "${PRESERVE_PATHS[@]}"; do
-      # Unquoted $path lets the glob expand against TARGET_DIR; nullglob makes a
-      # non-matching pattern vanish instead of staying literal.
-      shopt -s nullglob
-      for match in "$TARGET_DIR/"$path; do
-        [[ -e "$match" ]] || continue
-        rel="${match#"$TARGET_DIR/"}"
-        mkdir -p "$preserve_tmp/$(dirname "$rel")"
-        cp -R "$match" "$preserve_tmp/$rel"
-      done
-      shopt -u nullglob
-    done
-  fi
+  # overwrite mode — a full replace, chosen only for a fresh install or when the
+  # operator explicitly asks to replace everything. No operator state to protect.
+  sync_framework_overwrite
+}
 
-  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" -exec rm -rf {} +
+# Enumerate a NUL-delimited file list via `find` into the temp file $1, failing
+# CLOSED if find errors. We capture to a checked file instead of consuming
+# `< <(find …)` directly because a process substitution discards the producer's
+# exit status: an EACCES/I/O failure partway through a scan would truncate the
+# list yet leave the reading `while` loop exiting 0, so a partial upgrade would
+# commit and report success and the ERR/restore trap would never fire. Running
+# find to completion first, then checking its status, turns that silent
+# truncation into a fail-closed abort that the restore trap can act on (#791
+# blocker-D1). $1 after the shift is the scan root — named in the error.
+_scan_or_die() {
+  local out="$1"; shift
+  if ! find "$@" -print0 > "$out"; then
+    fail "Could not enumerate framework files under '$1' — aborting before committing an incomplete sync (fail-closed)."
+    return 1  # D1-GUARD
+  fi
+}
+
+# Keep-mode sync: create/refresh framework-owned files and prune only retired
+# framework files inside shipped framework subtrees. Operator-owned and unknown
+# paths (fail-safe default) are never written and never deleted — the #791 HARD
+# GATE. Single code path (no rsync) so it is byte-for-byte parity-testable.
+sync_framework_keep() {
+  local src="$SOURCE_DIR" dst="$TARGET_DIR" abs rel root list
+
+  # 1) Overlay copy — every framework-owned source file, refreshed only when its
+  #    bytes changed (no mtime churn on unchanged files, never on operator files).
+  #    The source scan is captured fail-closed (#791 blocker-D1): a find failure
+  #    aborts the sync (→ ERR trap → restore) rather than silently truncating it.
+  list="$(mktemp)"
+  _scan_or_die "$list" "$src" -type f || { rm -f "$list"; return 1; }
+  while IFS= read -r -d '' abs; do
+    rel="${abs#"$src"/}"
+    case "$rel" in
+      .git|.git/*|.framework-version|*.pre-constitution.bak) continue ;;
+    esac
+    manifest_is_framework "$rel" || continue
+    if [[ -f "$dst/$rel" ]] && cmp -s "$abs" "$dst/$rel"; then continue; fi
+    [[ "$rel" == */* ]] && mkdir -p "$dst/${rel%/*}"
+    cp "$abs" "$dst/$rel"
+  done < "$list"
+  rm -f "$list"
+
+  # 2) Scoped prune — within each shipped framework subtree root, remove
+  #    framework-owned target files the current source no longer ships. Operator
+  #    carve-outs (e.g. tools/_lib/credentials.json) resolve to operator and are
+  #    skipped; unknown paths resolve to operator too — both are unreachable here.
+  #    Each subtree scan is captured fail-closed for the same reason as the copy.
+  while IFS= read -r root; do
+    [[ -n "$root" && -d "$dst/$root" ]] || continue
+    list="$(mktemp)"
+    _scan_or_die "$list" "$dst/$root" -type f || { rm -f "$list"; return 1; }
+    while IFS= read -r -d '' abs; do
+      rel="${abs#"$dst"/}"
+      case "$rel" in *.pre-constitution.bak) continue ;; esac
+      [[ -f "$src/$rel" ]] && continue                          # still shipped
+      manifest_is_framework "$rel" || continue
+      rm -f "$abs"
+    done < "$list"
+    rm -f "$list"
+    # Drop framework dirs left empty by the prune (never touches a dir that still
+    # holds an operator file — those are never emptied). A genuine find failure
+    # (unreadable dir) is surfaced as a warning rather than silently swallowed;
+    # the "directory not empty" races we tolerate are ignored via -delete's own
+    # rc, not by hiding stderr — so a real error is still visible to the operator.
+    if ! find "$dst/$root" -type d -empty -delete 2>/dev/null; then
+      warn "prune: could not fully sweep empty framework dirs under $root (left as-is)"
+    fi
+  done < <(manifest_subtree_roots)
+}
+
+# Overwrite-mode sync: full replace. Only reached for a fresh install or an
+# explicit operator "replace everything" choice, so nothing is preserved.
+sync_framework_overwrite() {
+  if command -v rsync >/dev/null 2>&1; then
+    rsync -a --delete \
+      --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak" \
+      "$SOURCE_DIR/" "$TARGET_DIR/"
+    return
+  fi
+  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 \
+    ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" \
+    -exec rm -rf {} +
   cp -R "$SOURCE_DIR"/. "$TARGET_DIR"/
   rm -rf "$TARGET_DIR/.git"
-
-  if [[ -n "$preserve_tmp" ]]; then
-    # Restore by re-globbing the SAME patterns against preserve_tmp, so each
-    # preserved item is restored at its own relative path (e.g. only
-    # fleet/roster.yaml is replaced — the freshly-synced fleet/examples stays).
-    for path in "${PRESERVE_PATHS[@]}"; do
-      shopt -s nullglob
-      for match in "$preserve_tmp/"$path; do
-        [[ -e "$match" ]] || continue
-        rel="${match#"$preserve_tmp/"}"
-        rm -rf "$TARGET_DIR/$rel"
-        mkdir -p "$TARGET_DIR/$(dirname "$rel")"
-        cp -R "$match" "$TARGET_DIR/$rel"
-      done
-      shopt -u nullglob
-    done
-    rm -rf "$preserve_tmp"
-  fi
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -311,9 +376,23 @@ else
   ok "Install mode: overwrite"
 fi
 
+# Pre-flight (keep mode): load + validate the framework manifest BEFORE taking a
+# snapshot or arming the restore trap. A fail-closed manifest (missing / empty /
+# malformed) must abort here WITHOUT deleting or restoring over operator files —
+# the snapshot/restore path exists only for a genuine mid-sync mutation failure,
+# not for a validation failure that has touched nothing yet (#791 blocker-1).
+if [[ "$INSTALL_MODE" == "keep" ]]; then
+  manifest_load
+fi
+
 # Snapshot before any destructive file operation; restore on interrupt/failure.
+# The trap MUST exit after restoring: a bash INT/TERM handler that merely returns
+# does NOT terminate the script — execution would resume past the interrupt,
+# clear the snapshot, and report success, leaving a partial post-interrupt update
+# (#791 blocker-A). `restore_snapshot; exit 1` guarantees a non-zero exit for
+# both the errtrace (ERR) and signal (INT/TERM) paths.
 make_snapshot
-trap 'restore_snapshot' ERR INT TERM
+trap 'restore_snapshot; exit 1' ERR INT TERM
 
 sync_framework
 

packages/mosaic/framework/tools/_lib/manifest.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# Shared bash reader for framework-manifest.txt (#791).
+#
+# This is the bash half of the SSOT ownership resolver; the TypeScript half is
+# packages/mosaic/src/framework/manifest.ts. BOTH read the same
+# framework-manifest.txt and MUST resolve identical ownership for any path — the
+# parity test (manifest-parity.spec.ts) invokes this file's `resolve` CLI and
+# compares it against the TS resolver, so the two can never drift (the #631
+# two-copies failure class this closes).
+#
+# Ownership resolution (deny-wins / fail-safe):
+#   1. operator glob matches  -> operator
+#   2. else framework glob    -> framework
+#   3. else                   -> operator   (UNKNOWN defaults to operator, #791)
+#
+# Globs are compiled once at load into exact-prefix checks or POSIX EREs, so the
+# hot resolver (manifest_is_framework) forks no subprocesses — the installer
+# calls it once per file across the whole tree.
+#
+# Usage as a library (source it, then):
+#   manifest_load [manifest-file]      # populates + compiles the manifest
+#   manifest_is_framework <rel-path>   # rc 0 = framework-owned, rc 1 = operator
+#   manifest_resolve <rel-path>        # echoes: framework | operator
+#   manifest_subtree_roots             # echoes shipped framework `dir/**` roots
+#
+# Usage as a CLI (parity harness):
+#   bash manifest.sh resolve <rel-path>
+#   bash manifest.sh subtree-roots
+#   bash manifest.sh classify          # reads paths on stdin -> "<own>\t<path>"
+
+MANIFEST_FRAMEWORK=()
+MANIFEST_OPERATOR=()
+
+# Compiled forms (parallel arrays). _*_KIND[i] is "exact" or "re".
+_MF_KIND=(); _MF_EXACT=(); _MF_RE=()
+_MO_KIND=(); _MO_EXACT=(); _MO_RE=()
+_MF_ROOTS=()
+
+_manifest_default_root() { cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd; }
+
+# Normalize a path/glob: backslashes -> slashes, strip leading ./ and /, strip
+# trailing / (mirrors normalizeRel in manifest.ts).
+_manifest_norm() {
+  local p="$1"
+  p="${p//\\//}"
+  p="${p#./}"
+  while [[ "$p" == /* ]]; do p="${p#/}"; done
+  while [[ "$p" == */ ]]; do p="${p%/}"; done
+  printf '%s' "$p"
+}
+
+# Translate a normalized glob into a POSIX ERE body (mirrors globToRegExpBody).
+_manifest_glob_to_ere() {
+  local pattern; pattern="$(_manifest_norm "$1")"
+  local out="" c n i len=${#pattern} trailing
+  for (( i = 0; i < len; i++ )); do
+    c="${pattern:i:1}"
+    if [[ "$c" == "*" ]]; then
+      n="${pattern:i+1:1}"
+      if [[ "$n" == "*" ]]; then
+        i=$((i + 1))
+        trailing=0
+        if [[ "${pattern:i+1:1}" == "/" ]]; then i=$((i + 1)); trailing=1; fi
+        if [[ "$out" == */ ]]; then
+          out="${out%/}(/.*)?"
+        elif [[ "$trailing" -eq 1 ]]; then
+          out="$out(.*/)?"
+        else
+          out="$out.*"
+        fi
+      else
+        out="$out[^/]*"
+      fi
+    else
+      case "$c" in
+        .|+|\?|^|\$|\{|\}|\(|\)|\||\[|\]|\\) out="$out\\$c" ;;
+        *) out="$out$c" ;;
+      esac
+    fi
+  done
+  printf '%s' "$out"
+}
+
+# Compile one raw glob into (kind, exact, re) appended to the given section.
+# $1 = raw glob, $2 = section letter (F|O).
+_manifest_compile_one() {
+  local norm; norm="$(_manifest_norm "$1")"
+  [[ -n "$norm" ]] || return 0
+  if [[ "$norm" == *"*"* ]]; then
+    local re="^$(_manifest_glob_to_ere "$norm")\$"
+    if [[ "$2" == F ]]; then
+      _MF_KIND+=(re); _MF_EXACT+=(""); _MF_RE+=("$re")
+    else
+      _MO_KIND+=(re); _MO_EXACT+=(""); _MO_RE+=("$re")
+    fi
+  else
+    if [[ "$2" == F ]]; then
+      _MF_KIND+=(exact); _MF_EXACT+=("$norm"); _MF_RE+=("")
+    else
+      _MO_KIND+=(exact); _MO_EXACT+=("$norm"); _MO_RE+=("")
+    fi
+  fi
+  [[ "$2" == F && "$norm" == */"**" ]] && _MF_ROOTS+=("${norm%/**}")
+  return 0
+}
+
+_manifest_compile() {
+  _MF_KIND=(); _MF_EXACT=(); _MF_RE=(); _MF_ROOTS=()
+  _MO_KIND=(); _MO_EXACT=(); _MO_RE=()
+  local g
+  for g in "${MANIFEST_FRAMEWORK[@]:-}"; do [[ -n "$g" ]] && _manifest_compile_one "$g" F; done
+  for g in "${MANIFEST_OPERATOR[@]:-}"; do [[ -n "$g" ]] && _manifest_compile_one "$g" O; done
+  # Explicit success: an empty operator array makes the final `[[ -n "" ]] && …`
+  # short-circuit to rc 1, which would otherwise become this function's (and
+  # manifest_load's) return code — a spurious failure (#791 B2). Never rely on
+  # the last loop's exit status here.
+  return 0
+}
+
+# Load + compile the manifest. Rejects a malformed file the same way
+# parseManifest() does (entry before a section header / unknown header).
+manifest_load() {
+  local file="${1:-}"
+  [[ -n "$file" ]] || file="$(_manifest_default_root)/framework-manifest.txt"
+  # Fail CLOSED on a missing/unreadable manifest. Without this, `done < "$file"`
+  # aborts on a raw redirection error with no explanation; downstream that reads
+  # as "no framework paths" and an upgrade could no-op silently (#791 B2/B3).
+  if [[ ! -r "$file" ]]; then
+    echo "manifest: cannot read manifest file: $file — refusing to sync (fail-closed)." >&2
+    return 1
+  fi
+  MANIFEST_FRAMEWORK=()
+  MANIFEST_OPERATOR=()
+  local section="" line
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line#"${line%%[![:space:]]*}"}" # ltrim
+    line="${line%"${line##*[![:space:]]}"}" # rtrim
+    [[ -z "$line" || "${line:0:1}" == "#" ]] && continue
+    case "$line" in
+      "[framework]") section=framework; continue ;;
+      "[operator]") section=operator; continue ;;
+      "["*) echo "manifest: unknown section header: $line" >&2; return 1 ;;
+    esac
+    if [[ -z "$section" ]]; then
+      echo "manifest: entry before any [section] header: $line" >&2
+      return 1
+    fi
+    if [[ "$section" == framework ]]; then
+      MANIFEST_FRAMEWORK+=("$line")
+    else
+      MANIFEST_OPERATOR+=("$line")
+    fi
+  done < "$file"
+  # An empty or comment-only manifest defines NO framework-owned paths. Treating
+  # that as valid would make every path resolve operator and an upgrade prune
+  # nothing / write nothing — a silent no-op indistinguishable from success.
+  # Fail loud instead, mirroring parseManifest()'s throw in manifest.ts (#791 B2).
+  if [[ ${#MANIFEST_FRAMEWORK[@]} -eq 0 ]]; then
+    echo "manifest: no [framework] entries in $file — refusing to sync (empty or malformed manifest)." >&2
+    return 1
+  fi
+  # An entry like `/` or `./` normalizes to nothing and compiles to a glob that
+  # matches no path — so a manifest whose only [framework] entries are degenerate
+  # passes the count guard above but leaves the framework matcher empty: every
+  # path resolves operator, the exact silent no-op we fail closed against. Require
+  # at least one entry with a real (non-slash, non-dot) character. Mirrors
+  # parseManifest()'s `isUsableFrameworkGlob` `/[^/.]/` test in manifest.ts (#791 blocker-B).
+  local _g _usable=0
+  for _g in "${MANIFEST_FRAMEWORK[@]:-}"; do
+    if [[ "$(_manifest_norm "$_g")" =~ [^/.] ]]; then _usable=1; break; fi
+  done
+  if [[ "$_usable" -eq 0 ]]; then
+    echo "manifest: no usable [framework] entries in $file (every entry is empty or a bare dot segment) — refusing to sync (malformed manifest)." >&2
+    return 1
+  fi
+  _manifest_compile
+  return 0
+}
+
+# Fork-free: does $1 (a mosaic-home-relative path) match an operator glob?
+_mo_matches() {
+  local path="$1" i n=${#_MO_KIND[@]} re pat
+  for (( i = 0; i < n; i++ )); do
+    if [[ "${_MO_KIND[i]}" == exact ]]; then
+      pat="${_MO_EXACT[i]}"
+      [[ "$path" == "$pat" || "$path" == "$pat/"* ]] && return 0
+    else
+      re="${_MO_RE[i]}"
+      [[ "$path" =~ $re ]] && return 0
+    fi
+  done
+  return 1
+}
+
+# Fork-free: does $1 match a framework glob?
+_mf_matches() {
+  local path="$1" i n=${#_MF_KIND[@]} re pat
+  for (( i = 0; i < n; i++ )); do
+    if [[ "${_MF_KIND[i]}" == exact ]]; then
+      pat="${_MF_EXACT[i]}"
+      [[ "$path" == "$pat" || "$path" == "$pat/"* ]] && return 0
+    else
+      re="${_MF_RE[i]}"
+      [[ "$path" =~ $re ]] && return 0
+    fi
+  done
+  return 1
+}
+
+# The installer hot path — no subshell. rc 0 = framework-owned, rc 1 = operator
+# (deny-wins / fail-safe). Assumes an already-clean POSIX relative path.
+manifest_is_framework() {
+  _mo_matches "$1" && return 1
+  _mf_matches "$1" && return 0
+  return 1
+}
+
+# Echo the ownership of a path: framework | operator. Normalizes first, so it is
+# safe for CLI / test callers passing unnormalized input.
+manifest_resolve() {
+  local path; path="$(_manifest_norm "$1")"
+  if manifest_is_framework "$path"; then echo framework; else echo operator; fi
+}
+
+# Echo each shipped framework subtree root (a `dir/**` entry, without the /**).
+manifest_subtree_roots() {
+  local r
+  for r in "${_MF_ROOTS[@]:-}"; do [[ -n "$r" ]] && printf '%s\n' "$r"; done
+}
+
+# CLI dispatch — only when executed directly, never when sourced.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  set -o pipefail
+  # Propagate a fail-closed manifest_load (missing/empty/malformed) as a non-zero
+  # exit instead of continuing to resolve against empty compiled arrays — that is
+  # what lets the parity test assert bash and TS reject the same bad inputs (#791 B2).
+  manifest_load "${MANIFEST_FILE:-}" || exit 1
+  cmd="${1:-}"
+  case "$cmd" in
+    resolve) manifest_resolve "${2:?path required}" ;;
+    subtree-roots) manifest_subtree_roots ;;
+    classify)
+      while IFS= read -r p; do
+        [[ -z "$p" ]] && continue
+        printf '%s\t%s\n' "$(manifest_resolve "$p")" "$p"
+      done
+      ;;
+    *)
+      echo "usage: manifest.sh {resolve <path>|subtree-roots|classify}" >&2
+      exit 2
+      ;;
+  esac
+fi

packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh

@@ -61,25 +61,36 @@ MOSAIC_HOME="$T5" MOSAIC_INSTALL_MODE=bogus MOSAIC_SYNC_ONLY=1 bash "$INSTALL" >
 chk "F5 failure: invalid mode rejected (nonzero exit)" "[ $rc -ne 0 ]"
 chk "F5 failure: SOUL + credentials intact" "grep -q orig '$T5/SOUL.md' && grep -q keepme '$T5/credentials/c.json'"
 
-# F6 — keep-mode re-seed (the `mosaic update` path) MUST NOT wipe user fleet data.
-# Regression for the roster-loss bug: fleet/ was not in PRESERVE_PATHS.
+# F6 — keep-mode re-seed (the `mosaic update` path) MUST preserve ALL user-owned
+# fleet state — including an unanticipated file the manifest never names, which
+# resolves to operator-owned by the #791 fail-safe — while refreshing the
+# framework-owned schema/examples.
 T6=$(mktemp -d); mkdir -p "$T6/fleet/examples" "$T6/fleet/run" "$T6/fleet/agents"
 printf '# persona\n' > "$T6/SOUL.md"   # makes it a recognized existing install (→ keep mode)
 printf 'version: 1\nagents:\n  - name: coder0\n' > "$T6/fleet/roster.yaml"
-printf 'version: 1\nagents:\n  - name: custom\n' > "$T6/fleet/my-fleet.yaml"
+printf '{"version":1,"agents":[{"name":"json-user"}]}\n' > "$T6/fleet/roster.json"
+printf 'version: 1\nagents:\n  - name: not-active-roster\n' > "$T6/fleet/my-fleet.yaml"
 printf 'ts=x\n' > "$T6/fleet/run/coder0.hb"
 printf 'MOSAIC_AGENT_NAME=coder0\n' > "$T6/fleet/agents/coder0.env"
 printf '# stale preset\n' > "$T6/fleet/examples/general.yaml"
+printf '{"stale":true}\n' > "$T6/fleet/roster.schema.json"
+E6=$(mktemp -d)
+cp "$T6/fleet/roster.yaml" "$E6/roster-yaml.expected"
+cp "$T6/fleet/roster.json" "$E6/roster-json.expected"
+cp "$T6/fleet/my-fleet.yaml" "$E6/my-fleet.expected"
+cp "$T6/fleet/run/coder0.hb" "$E6/run.expected"
+cp "$T6/fleet/agents/coder0.env" "$E6/agent.expected"
 echo 3 > "$T6/.framework-version"
 run "$T6" keep
-chk "F6 reseed: user roster.yaml SURVIVES keep-mode sync" "grep -q coder0 '$T6/fleet/roster.yaml'"
-chk "F6 reseed: other user fleet/*.yaml survives (glob)" "[ -f '$T6/fleet/my-fleet.yaml' ]"
-chk "F6 reseed: per-agent env (fleet/agents) survives" "[ -f '$T6/fleet/agents/coder0.env' ]"
-chk "F6 reseed: heartbeat run dir (fleet/run) survives" "[ -f '$T6/fleet/run/coder0.hb' ]"
-chk "F6 reseed: framework examples ARE refreshed (not preserved stale)" "grep -q orchestrator '$T6/fleet/examples/general.yaml'"
-chk "F6 reseed: framework roster.schema.json seeded" "[ -f '$T6/fleet/roster.schema.json' ]"
+chk "F6 reseed: exact roster.yaml bytes survive keep-mode sync" "cmp -s '$T6/fleet/roster.yaml' '$E6/roster-yaml.expected'"
+chk "F6 reseed: exact roster.json bytes survive keep-mode sync" "cmp -s '$T6/fleet/roster.json' '$E6/roster-json.expected'"
+chk "F6 reseed: unanticipated operator fleet file survives (fail-safe, #791)" "cmp -s '$T6/fleet/my-fleet.yaml' '$E6/my-fleet.expected'"
+chk "F6 reseed: per-agent env bytes survive" "cmp -s '$T6/fleet/agents/coder0.env' '$E6/agent.expected'"
+chk "F6 reseed: heartbeat bytes survive" "cmp -s '$T6/fleet/run/coder0.hb' '$E6/run.expected'"
+chk "F6 reseed: framework examples are refreshed" "grep -q orchestrator '$T6/fleet/examples/general.yaml'"
+chk "F6 reseed: framework roster schema is refreshed" "cmp -s '$T6/fleet/roster.schema.json' '$FW/fleet/roster.schema.json'"
 
-rm -rf "$T1" "$T2" "$T3" "$T4" "$T5" "$T6"
+rm -rf "$T1" "$T2" "$T3" "$T4" "$T5" "$T6" "$E6"
 echo
 echo "RESULT: $pass passed, $fail failed"
 [ "$fail" -eq 0 ]

packages/mosaic/framework/tools/quality/scripts/test-roster-schema.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Regression checks for connector-kind-conditional fleet roster schema."""
+
+import json
+import sys
+from pathlib import Path
+
+from jsonschema import Draft202012Validator
+
+schema_path = Path(__file__).resolve().parents[3] / "fleet" / "roster.schema.json"
+schema = json.loads(schema_path.read_text(encoding="utf-8"))
+validator = Draft202012Validator(schema)
+base = {
+    "version": 1,
+    "transport": "tmux",
+    "agents": [{"name": "orchestrator", "runtime": "pi"}],
+}
+
+valid = [
+    {"kind": "tmux"},
+    {"kind": "discord", "discord": {"channel_id": "123"}},
+    {
+        "kind": "matrix",
+        "matrix": {
+            "homeserver_url": "https://matrix.example",
+            "user_id": "@mosaic:example",
+            "room_id": "!room:example",
+        },
+    },
+]
+invalid = [
+    {"kind": "tmux", "discord": {"channel_id": "123"}},
+    {"kind": "tmux", "matrix": {}},
+    {"kind": "discord"},
+    {"kind": "discord", "matrix": {}},
+    {
+        "kind": "discord",
+        "discord": {"channel_id": "123"},
+        "matrix": {
+            "homeserver_url": "https://matrix.example",
+            "user_id": "@mosaic:example",
+            "room_id": "!room:example",
+        },
+    },
+    {"kind": "matrix"},
+    {"kind": "matrix", "discord": {"channel_id": "123"}},
+    {"kind": "discord", "discord": {"channel_id": ""}},
+    {"kind": "discord", "discord": {"channel_id": "   "}},
+    {
+        "kind": "matrix",
+        "matrix": {
+            "homeserver_url": "",
+            "user_id": "@mosaic:example",
+            "room_id": "!room:example",
+        },
+    },
+    {
+        "kind": "matrix",
+        "matrix": {
+            "homeserver_url": "\t",
+            "user_id": "@mosaic:example",
+            "room_id": "!room:example",
+        },
+    },
+    {
+        "kind": "matrix",
+        "matrix": {
+            "homeserver_url": "https://matrix.example",
+            "user_id": "",
+            "room_id": "!room:example",
+        },
+    },
+    {
+        "kind": "matrix",
+        "matrix": {
+            "homeserver_url": "https://matrix.example",
+            "user_id": "   ",
+            "room_id": "!room:example",
+        },
+    },
+    {
+        "kind": "matrix",
+        "matrix": {
+            "homeserver_url": "https://matrix.example",
+            "user_id": "@mosaic:example",
+            "room_id": "",
+        },
+    },
+    {
+        "kind": "matrix",
+        "matrix": {
+            "homeserver_url": "https://matrix.example",
+            "user_id": "@mosaic:example",
+            "room_id": "\n",
+        },
+    },
+]
+
+for connector in valid:
+    errors = list(validator.iter_errors({**base, "connector": connector}))
+    if errors:
+        print(f"expected valid connector {connector}: {errors}", file=sys.stderr)
+        raise SystemExit(1)
+
+for connector in invalid:
+    if not list(validator.iter_errors({**base, "connector": connector})):
+        print(f"expected invalid connector: {connector}", file=sys.stderr)
+        raise SystemExit(1)
+
+print("connector schema regression: PASS")

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

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# test-upgrade-manifest-guard.sh — the #791 HARD GATE.
+#
+# Proves that a keep-mode framework upgrade (the `mosaic update` path:
+# install.sh with MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1) touches NO path
+# outside the framework-owned manifest. Every operator-owned sentinel — including
+# a deliberately UNANTICIPATED one the manifest never names — must survive
+# byte-identical with an unchanged mtime (not even rewritten). Framework files
+# must still update, and a retired framework file inside a shipped subtree must
+# still be pruned. No operator secret value may appear in installer output.
+#
+# Keep mode is a SINGLE code path (sync_framework_keep, a manifest-driven cp
+# overlay + scoped prune — no rsync). The matrix still runs twice, once with
+# rsync on PATH and once with it hidden, to prove the keep path is genuinely
+# rsync-independent: it must obey the manifest identically whether or not rsync
+# happens to be installed (rsync --delete is only ever used by overwrite mode,
+# which has no operator state to protect).
+#
+# It also runs a fail-closed matrix (#791 B2/B3): an empty, operator-only,
+# malformed, or missing manifest must ABORT the upgrade loudly and leave every
+# operator path untouched — never silently no-op to "complete".
+#
+# Usage:  bash test-upgrade-manifest-guard.sh
+set -uo pipefail
+
+FW="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"   # packages/mosaic/framework
+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; }
+
+SECRET='SUPER-SECRET-TOKEN-do-not-log-3f9a'
+
+# Seed a throwaway MOSAIC_HOME with an operator sentinel per ownership class.
+seed_home() {
+  local H="$1"
+  mkdir -p "$H/agents" "$H/policy" "$H/memory" "$H/tools/_lib" \
+           "$H/fleet/agents" "$H/fleet/run/sessions" "$H/harvester" \
+           "$H/unknown-operator-dir" "$H/guides"
+  printf '# persona\n' > "$H/SOUL.md"          # marks a recognized existing install → keep mode
+  printf 'MODEL=opus\n' > "$H/agents/coder0.conf"
+  printf '# operator policy\n' > "$H/policy/custom.md"
+  printf '# soul overlay\n' > "$H/SOUL.local.md"
+  printf '# operator memory\n' > "$H/memory/note.md"
+  printf 'TOKEN=%s\n' "$SECRET" > "$H/tools/_lib/credentials.json"
+  printf 'MOSAIC_AGENT_NAME=coder0\n' > "$H/fleet/agents/coder0.env"
+  printf 'version: 2\nagents:\n  - name: coder0\n' > "$H/fleet/roster.yaml"
+  printf '# harvester SOP\n' > "$H/harvester/sop.md"
+  printf 'operator data the manifest never anticipated\n' > "$H/unknown-operator-dir/x"
+  printf 'version: 1\nagents:\n  - name: mine\n' > "$H/fleet/my-fleet.yaml"
+
+  # #797 Runtime Session Ledger (Mos-elevated to a #791 PR1 merge-blocker): a
+  # populated ledger under fleet/run/sessions/ must survive the upgrade — a
+  # runtime ledger an upgrade rsync can wipe is worthless. Seed it exactly as
+  # #797 writes it: a non-empty append journal + a non-empty compacted
+  # projection, files 0600 under a 0700 dir.
+  printf '%s\n%s\n%s\n' \
+    '{"seq":1,"kind":"session.spawn","node":"sess-42","generation":7}' \
+    '{"seq":2,"kind":"lease.grant","node":"sess-42","lease":"web1"}' \
+    '{"seq":3,"kind":"dispatch.create","from":"sess-42","to":"disp-9"}' \
+    > "$H/fleet/run/sessions/events.ndjson"
+  printf '%s\n' \
+    '{"generation":7,"nodes":[{"id":"sess-42","kind":"session"}],"edges":[{"from":"sess-42","to":"disp-9","kind":"dispatch"}]}' \
+    > "$H/fleet/run/sessions/ledger.json"
+  chmod 0700 "$H/fleet/run" "$H/fleet/run/sessions"
+  chmod 0600 "$H/fleet/run/sessions/events.ndjson" "$H/fleet/run/sessions/ledger.json"
+
+  # A retired framework file inside a shipped subtree (absent from source) — must be pruned.
+  printf '# retired guide\n' > "$H/guides/RETIRED-OLD-GUIDE.md"
+  echo 3 > "$H/.framework-version"
+}
+
+OPERATOR_SENTINELS=(
+  "agents/coder0.conf"
+  "policy/custom.md"
+  "SOUL.local.md"
+  "memory/note.md"
+  "tools/_lib/credentials.json"
+  "fleet/agents/coder0.env"
+  "fleet/roster.yaml"
+  "harvester/sop.md"
+  "unknown-operator-dir/x"
+  "fleet/my-fleet.yaml"
+  # #797 Runtime Session Ledger — populated journal + projection must survive.
+  "fleet/run/sessions/events.ndjson"
+  "fleet/run/sessions/ledger.json"
+)
+
+run_matrix() {
+  local label="$1"; shift          # extra env / PATH override applied to the run
+  local H E OUT rel before_hash after_hash before_mt after_mt
+  H=$(mktemp -d); E=$(mktemp -d); OUT=$(mktemp)
+  seed_home "$H"
+
+  # Snapshot hash + mtime of every operator sentinel before the upgrade.
+  for rel in "${OPERATOR_SENTINELS[@]}"; do
+    sha256sum "$H/$rel" | awk '{print $1}' > "$E/$(echo "$rel" | tr / _).hash"
+    stat -c %Y "$H/$rel" > "$E/$(echo "$rel" | tr / _).mt"
+  done
+
+  # Snapshot the ledger directory permission bits (#797 assert: perms unchanged).
+  local before_dirperm after_dirperm
+  before_dirperm=$(stat -c %a "$H/fleet/run/sessions")
+
+  # The upgrade under test (keep + sync-only = the `mosaic update` reseed path).
+  MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 "$@" bash "$INSTALL" >"$OUT" 2>&1
+
+  # HARD GATE: every operator sentinel survives byte-identical AND mtime-unchanged.
+  for rel in "${OPERATOR_SENTINELS[@]}"; do
+    before_hash=$(cat "$E/$(echo "$rel" | tr / _).hash")
+    before_mt=$(cat "$E/$(echo "$rel" | tr / _).mt")
+    after_hash=$(sha256sum "$H/$rel" 2>/dev/null | awk '{print $1}')
+    after_mt=$(stat -c %Y "$H/$rel" 2>/dev/null || echo MISSING)
+    chk "[$label] operator sentinel survives byte-identical: $rel" \
+      "[ -n '$after_hash' ] && [ '$before_hash' = '$after_hash' ]"
+    chk "[$label] operator sentinel not rewritten (mtime unchanged): $rel" \
+      "[ '$before_mt' = '$after_mt' ]"
+  done
+
+  # #797 assert 7: the ledger directory's permission bits are unchanged.
+  after_dirperm=$(stat -c %a "$H/fleet/run/sessions" 2>/dev/null || echo MISSING)
+  chk "[$label] ledger dir perms unchanged (#797): $before_dirperm" \
+    "[ '$before_dirperm' = '$after_dirperm' ]"
+
+  # Positive controls / negative controls — prove the test discriminates: the
+  # upgrade DOES write and prune framework-owned paths, so the operator sentinels
+  # (incl. the #797 ledger) survive because of the manifest, not because the
+  # upgrade is a no-op.
+  chk "[$label] positive control: framework file present after upgrade (guides synced)" \
+    "[ -f '$H/guides/E2E-DELIVERY.md' ]"
+  chk "[$label] negative control: retired framework file inside a subtree IS pruned" \
+    "[ ! -f '$H/guides/RETIRED-OLD-GUIDE.md' ]"
+  chk "[$label] manifest itself is installed" "[ -f '$H/framework-manifest.txt' ]"
+
+  # Secret-safety: the operator secret value never appears in installer output.
+  chk "[$label] operator secret value absent from installer stdout/stderr" \
+    "! grep -q '$SECRET' '$OUT'"
+
+  rm -rf "$H" "$E" "$OUT"
+}
+
+# Fail-closed matrix (#791 B2/B3 + blocker-1): run install.sh from a COPY of the
+# framework so the shipped manifest can be corrupted. Every corruption must abort
+# the upgrade non-zero with a manifest error, leaving all operator sentinels
+# byte-identical AND on the SAME inode. The inode check is the load-bearing part:
+# manifest validation is hoisted BEFORE make_snapshot/the restore trap, so a bad
+# manifest must abort without ever snapshotting, deleting, and restoring the
+# target. Were validation still armed under the ERR trap, restore_snapshot would
+# rm -rf + rebuild the target — same bytes but a NEW inode (broken hard links,
+# changed ctime), which a content-only hash would miss (#791 blocker-1).
+run_failclosed() {
+  local label="$1" mutate="$2"
+  local SRC H E OUT rc rel before_hash after_hash before_ino after_ino key
+  SRC=$(mktemp -d); H=$(mktemp -d); E=$(mktemp -d); OUT=$(mktemp)
+  cp -a "$FW/." "$SRC/"
+  case "$mutate" in
+    empty)         : > "$SRC/framework-manifest.txt" ;;
+    operator-only) printf '[operator]\nSOUL.md\n*.local.md\n' > "$SRC/framework-manifest.txt" ;;
+    malformed)     printf 'stray.md\n[framework]\nguides/**\n' > "$SRC/framework-manifest.txt" ;;
+    degenerate)    printf '[framework]\n/\n./\n[operator]\nSOUL.md\n' > "$SRC/framework-manifest.txt" ;;
+    missing)       rm -f "$SRC/framework-manifest.txt" ;;
+  esac
+
+  seed_home "$H"
+  for rel in "${OPERATOR_SENTINELS[@]}"; do
+    key=$(echo "$rel" | tr / _)
+    sha256sum "$H/$rel" | awk '{print $1}' > "$E/$key.hash"
+    stat -c '%i' "$H/$rel" > "$E/$key.ino"
+  done
+
+  MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash "$SRC/install.sh" >"$OUT" 2>&1
+  rc=$?
+
+  chk "[fail-closed:$label] upgrade aborts non-zero" "[ '$rc' -ne 0 ]"
+  chk "[fail-closed:$label] refuses loudly with a manifest error" \
+    "grep -qi 'manifest' '$OUT'"
+  for rel in "${OPERATOR_SENTINELS[@]}"; do
+    key=$(echo "$rel" | tr / _)
+    before_hash=$(cat "$E/$key.hash")
+    after_hash=$(sha256sum "$H/$rel" 2>/dev/null | awk '{print $1}')
+    chk "[fail-closed:$label] operator sentinel untouched: $rel" \
+      "[ -n '$after_hash' ] && [ '$before_hash' = '$after_hash' ]"
+    before_ino=$(cat "$E/$key.ino")
+    after_ino=$(stat -c '%i' "$H/$rel" 2>/dev/null)
+    chk "[fail-closed:$label] operator sentinel not deleted/recreated (inode stable): $rel" \
+      "[ -n '$after_ino' ] && [ '$before_ino' = '$after_ino' ]"
+  done
+  chk "[fail-closed:$label] operator secret value absent from output" \
+    "! grep -q '$SECRET' '$OUT'"
+
+  chmod -R u+w "$SRC" "$H" 2>/dev/null || true
+  rm -rf "$SRC" "$H" "$E" "$OUT"
+}
+
+echo "#791 upgrade manifest guard (HARD GATE):"
+
+# 1) rsync path (if available on this host).
+if command -v rsync >/dev/null 2>&1; then
+  run_matrix "rsync"
+else
+  echo "  · rsync not installed — skipping rsync-path matrix"
+fi
+
+# 2) rsync-absent path — hide rsync behind a scratch PATH. Keep mode never calls
+#    rsync, so this must resolve identically to run (1); it proves the keep path
+#    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; do
+  p=$(command -v "$t" 2>/dev/null) && ln -s "$p" "$FBIN/$t"
+done
+run_matrix "rsync-absent" env "PATH=$FBIN"
+rm -rf "$FBIN"
+
+# 3) fail-closed matrix (#791 B2/B3) — corrupt the shipped manifest four ways.
+run_failclosed "empty-manifest"       empty
+run_failclosed "operator-only"        operator-only
+run_failclosed "malformed-manifest"   malformed
+run_failclosed "degenerate-framework" degenerate
+run_failclosed "missing-manifest"     missing
+
+echo
+echo "RESULT: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

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

@@ -0,0 +1,319 @@
+#!/usr/bin/env bash
+# test-upgrade-rollback.sh — the #791 B1 regression gate.
+#
+# A keep-mode upgrade takes a pre-update snapshot and installs an ERR/INT/TERM
+# trap that restores it if the sync aborts midway (install.sh: make_snapshot +
+# `trap restore_snapshot`). That trap is only reached if `set -E` (errtrace) is
+# active — otherwise a failure INSIDE sync_framework_keep() (which runs entirely
+# in a function) never fires the trap, and the upgrade aborts leaving a
+# half-written target with NO rollback. This test proves:
+#
+#   Part A (the gate):   the shipped installer rolls back a mid-sync failure —
+#                        the restore message fires, the corrupted file is put
+#                        back, AND the whole target is byte-identical to its
+#                        pre-upgrade state.
+#   Part B (the control): the SAME installer with `-E` stripped does NOT roll back
+#                        (dead trap) — the mid-sync corruption survives, proving
+#                        errtrace is load-bearing. If anyone removes `set -E`,
+#                        Part A goes red.
+#
+# The mid-sync failure is injected with a PATH-shadowing `cp` shim rather than
+# file permissions. The earlier 0400/EACCES approach was NOT portable: Woodpecker
+# runs steps as root (node:24-alpine has no USER directive), and root overwrites a
+# 0400 file, so the failure never fired and this gate silently passed (#791
+# blocker-3). The shim fails deterministically for one framework-owned
+# destination regardless of uid, and — like a real interrupted cp (disk-full
+# mid-write) — leaves a partially-written target behind, so rollback has real
+# damage to undo and the control has real damage to expose.
+#
+# Usage:  bash test-upgrade-rollback.sh
+set -uo pipefail
+
+FW="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"   # packages/mosaic/framework
+INSTALL="$FW/install.sh"
+ORIG_PATH="$PATH"
+
+# The `-E`-stripped control installer must live INSIDE $FW: install.sh derives
+# SOURCE_DIR from its own path and `source`s $SOURCE_DIR/tools/_lib/manifest.sh,
+# so a copy anywhere else aborts at the source line before ever reaching the sync
+# loop — which would make the control a false negative. A root dotfile is
+# operator-owned (unknown→operator), so the sync loop skips it. Clean up on exit.
+STRIPPED="$FW/.install-rollback-control.tmp.sh"
+NOEXIT="$FW/.install-noexit-control.tmp.sh"
+D1CTRL="$FW/.install-d1guard-control.tmp.sh"
+D2CTRL="$FW/.install-d2guard-control.tmp.sh"
+rm -f "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
+trap 'rm -f "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"' EXIT
+
+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-b1'
+# A framework-owned file the shim fails the copy of. The seeded target holds GOOD
+# bytes; source ships different bytes, so sync_framework_keep() attempts the copy
+# and the shim intercepts it. Root-level framework files sort before guides/, so
+# several framework files are already refreshed when the copy reaches this one.
+POISON_REL='guides/E2E-DELIVERY.md'
+GOOD='GOOD-REFERENCE-CONTENT-pre-upgrade-b1'
+GARBAGE='PARTIAL-WRITE-GARBAGE-mid-sync-b1'
+
+# A `cp` shim: for the poisoned destination, simulate an interrupted copy — write
+# partial garbage to the target, then fail — otherwise delegate to the real cp
+# (resolved via the ORIGINAL PATH so make_snapshot/restore still work).
+make_cp_shim() {
+  local dir="$1"
+  cat > "$dir/cp" <<SHIM
+#!/usr/bin/env bash
+dest="\${@: -1}"
+case "\$dest" in
+  */$POISON_REL)
+    printf '%s' '$GARBAGE' > "\$dest" 2>/dev/null || true
+    exit 1 ;;
+esac
+exec env PATH="$ORIG_PATH" cp "\$@"
+SHIM
+  chmod +x "$dir/cp"
+}
+
+# A `find` shim that fails every enumeration scan (`-print0`) as if it hit an
+# EACCES/I/O error partway — it emits the real (here: complete) list first, then
+# exits non-zero, exactly the class of failure a `< <(find …)` process
+# substitution silently swallows. All non-`-print0` finds (e.g. the -delete
+# sweep) delegate to the real find on the original PATH. Used to prove #791
+# blocker-D1: the shipped installer must honor find's exit status and roll back.
+make_find_fail_shim() {
+  local dir="$1"
+  cat > "$dir/find" <<SHIM
+#!/usr/bin/env bash
+for a in "\$@"; do
+  if [ "\$a" = "-print0" ]; then
+    env PATH="$ORIG_PATH" find "\$@"   # emit the real list…
+    exit 1                              # …then fail as if the scan hit EACCES
+  fi
+done
+exec env PATH="$ORIG_PATH" find "\$@"
+SHIM
+  chmod +x "$dir/find"
+}
+
+# An `rm` shim that fails ONLY `rm -rf <FAIL_RM_TARGET>` (the restore's target
+# reset) and delegates every other rm to the real one. Used to prove #791
+# blocker-D2: when the target reset inside restore_snapshot fails, the installer
+# must emit the manual-recovery pointer (snapshot path) instead of exiting
+# silently under `set -e`. FAIL_RM_TARGET is exported into the installer env.
+make_rm_fail_shim() {
+  local dir="$1"
+  cat > "$dir/rm" <<'SHIM'
+#!/usr/bin/env bash
+last="${@: -1}"
+if [ -n "${FAIL_RM_TARGET:-}" ] && [ "$last" = "$FAIL_RM_TARGET" ]; then
+  exit 1
+fi
+exec env PATH="$ORIG_PATH_FOR_RM" rm "$@"
+SHIM
+  chmod +x "$dir/rm"
+}
+
+seed_home() {
+  local H="$1"
+  mkdir -p "$H/agents" "$H/tools/_lib" "$H/memory" "$H/guides"
+  printf '# persona\n' > "$H/SOUL.md"          # recognized install → keep mode + snapshot
+  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"
+  # Good pre-upgrade bytes; source ships different bytes, so cp is attempted.
+  printf '%s' "$GOOD" > "$H/$POISON_REL"
+}
+
+# Run one keep-mode upgrade against $1=installer, seeding a fresh home and a
+# byte-for-byte reference of the pre-upgrade state, with the cp shim first on
+# PATH. Echoes: "<exit>\t<out>\t<ref>\t<home>".
+run_upgrade() {
+  local installer="$1" shim_maker="${2:-make_cp_shim}" H REF OUT SHIM rc
+  H=$(mktemp -d); REF=$(mktemp -d); OUT=$(mktemp); SHIM=$(mktemp -d)
+  seed_home "$H"
+  env PATH="$ORIG_PATH" cp -a "$H/." "$REF/"     # pre-upgrade reference (real cp)
+  "$shim_maker" "$SHIM"
+  set +e
+  PATH="$SHIM:$ORIG_PATH" \
+    MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash "$installer" >"$OUT" 2>&1
+  rc=$?
+  set -e 2>/dev/null || true
+  rm -rf "$SHIM"
+  printf '%s\t%s\t%s\t%s\n' "$rc" "$OUT" "$REF" "$H"
+}
+
+echo "#791 upgrade rollback (B1 regression gate):"
+
+# ── Part A: the shipped installer must roll back a mid-sync failure ───────────
+IFS=$'\t' read -r rcA OUTA REFA HA < <(run_upgrade "$INSTALL")
+
+chk "[shipped] upgrade aborts non-zero on the injected mid-sync failure" \
+  "[ '$rcA' -ne 0 ]"
+chk "[shipped] restore_snapshot fires (rollback message present)" \
+  "grep -q 'restoring previous state from snapshot' '$OUTA'"
+chk "[shipped] the corrupted file is restored to its pre-upgrade bytes" \
+  "[ \"\$(cat '$HA/$POISON_REL')\" = '$GOOD' ]"
+chk "[shipped] target rolled back byte-identical to pre-upgrade state" \
+  "diff -r '$REFA' '$HA' >/dev/null 2>&1"
+chk "[shipped] operator secret value absent from installer output" \
+  "! grep -q '$SECRET' '$OUTA'"
+
+# ── Part B: control — strip `-E`, the trap is dead, no rollback happens ───────
+# Proves errtrace is what makes the trap reachable. If `set -E` is ever removed
+# from install.sh, Part A's rollback assertions fail exactly like this control.
+sed 's/^set -Eeuo pipefail/set -euo pipefail/' "$INSTALL" > "$STRIPPED"
+chk "[control] the -E strip actually changed the installer" \
+  "! cmp -s '$INSTALL' '$STRIPPED'"
+
+IFS=$'\t' read -r rcB OUTB REFB HB < <(run_upgrade "$STRIPPED")
+chk "[control] without -E the upgrade still aborts non-zero" \
+  "[ '$rcB' -ne 0 ]"
+# The load-bearing, deterministic proof of B1: without errtrace the ERR trap
+# never fires for a failure inside sync_framework_keep(), so no rollback runs.
+chk "[control] without -E the rollback message does NOT fire (dead trap)" \
+  "! grep -q 'restoring previous state from snapshot' '$OUTB'"
+chk "[control] without -E the mid-sync corruption survives (no rollback)" \
+  "[ \"\$(cat '$HB/$POISON_REL')\" = '$GARBAGE' ]"
+
+# ── Part C: an INT/TERM interrupt must terminate, not resume (blocker-A) ──────
+# A bash signal trap that merely returns lets the script continue past the
+# interrupt — restoring the snapshot, then resuming the sync and reporting
+# success. We inject a SIGTERM mid-sync with a cp that SUCCEEDS (so set -e never
+# fires and ONLY the signal path governs), and assert the shipped installer
+# restores AND exits without reporting success. The control strips `exit 1` from
+# the trap and shows the buggy resume-to-success.
+make_term_shim() {
+  local dir="$1"
+  cat > "$dir/cp" <<SHIM
+#!/usr/bin/env bash
+dest="\${@: -1}"
+case "\$dest" in
+  */$POISON_REL)
+    kill -TERM "\$PPID" 2>/dev/null   # signal install.sh; the copy still succeeds
+    exec env PATH="$ORIG_PATH" cp "\$@" ;;
+esac
+exec env PATH="$ORIG_PATH" cp "\$@"
+SHIM
+  chmod +x "$dir/cp"
+}
+
+# Run one keep-mode upgrade with the SIGTERM shim. Echoes "<exit>\t<out>\t<home>".
+run_signal_upgrade() {
+  local installer="$1" H OUT SHIM rc
+  H=$(mktemp -d); OUT=$(mktemp); SHIM=$(mktemp -d)
+  seed_home "$H"
+  make_term_shim "$SHIM"
+  set +e
+  PATH="$SHIM:$ORIG_PATH" \
+    MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash "$installer" >"$OUT" 2>&1
+  rc=$?
+  set -e 2>/dev/null || true
+  rm -rf "$SHIM"
+  printf '%s\t%s\t%s\n' "$rc" "$OUT" "$H"
+}
+
+IFS=$'\t' read -r rcC OUTC HC < <(run_signal_upgrade "$INSTALL")
+chk "[signal] SIGTERM mid-sync aborts non-zero (trap exits, does not resume)" \
+  "[ '$rcC' -ne 0 ]"
+chk "[signal] restore_snapshot fires on the interrupt" \
+  "grep -q 'restoring previous state from snapshot' '$OUTC'"
+chk "[signal] does NOT resume to report sync success after the interrupt" \
+  "! grep -q 'file phase complete' '$OUTC'"
+
+# Control: strip `exit 1` from the signal trap → the handler returns, the script
+# resumes past the interrupt and wrongly reports success. In $FW so SOURCE_DIR resolves.
+sed "s/trap 'restore_snapshot; exit 1' ERR INT TERM/trap 'restore_snapshot' ERR INT TERM/" \
+  "$INSTALL" > "$NOEXIT"
+chk "[control] the exit-strip actually changed the installer" \
+  "! cmp -s '$INSTALL' '$NOEXIT'"
+IFS=$'\t' read -r _rcD OUTD HD < <(run_signal_upgrade "$NOEXIT")
+chk "[control] without 'exit 1' the trap resumes and reports sync success (the bug)" \
+  "grep -q 'file phase complete' '$OUTD'"
+
+# ── Part D: a failed source/prune `find` scan must abort + roll back (D1) ─────
+# A `< <(find …)` process substitution discards find's exit status, so an
+# EACCES/I/O failure mid-scan would truncate the file list yet leave the reading
+# loop exiting 0 — a partial upgrade committed and reported as success, with the
+# ERR/restore trap never firing. The shipped installer captures the scan into a
+# checked temp file (_scan_or_die) and aborts on failure. We inject a `find` that
+# fails every `-print0` scan and assert the shipped installer rolls back.
+IFS=$'\t' read -r rcE OUTE REFE HE < <(run_upgrade "$INSTALL" make_find_fail_shim)
+chk "[find-fail] a failing framework scan aborts the upgrade non-zero" \
+  "[ '$rcE' -ne 0 ]"
+chk "[find-fail] restore_snapshot fires on the aborted scan" \
+  "grep -q 'restoring previous state from snapshot' '$OUTE'"
+chk "[find-fail] the abort is a fail-closed enumeration error (not a silent truncation)" \
+  "grep -q 'Could not enumerate framework files' '$OUTE'"
+chk "[find-fail] target rolled back byte-identical to pre-upgrade state" \
+  "diff -r '$REFE' '$HE' >/dev/null 2>&1"
+
+# Control: neuter the D1 guard (turn its `return 1` into a no-op) so a find
+# failure is swallowed exactly as `< <(find …)` would — the scan appears to
+# succeed and the upgrade reports completion with NO rollback.
+sed 's/return 1  # D1-GUARD/: # D1-GUARD-DISABLED/' "$INSTALL" > "$D1CTRL"
+chk "[control] the D1-guard strip actually changed the installer" \
+  "! cmp -s '$INSTALL' '$D1CTRL'"
+IFS=$'\t' read -r _rcF OUTF REFF HF < <(run_upgrade "$D1CTRL" make_find_fail_shim)
+chk "[control] with the D1 guard disabled the find failure is swallowed (no rollback)" \
+  "! grep -q 'restoring previous state from snapshot' '$OUTF'"
+chk "[control] with the D1 guard disabled the upgrade wrongly reports success" \
+  "grep -q 'file phase complete' '$OUTF'"
+
+# ── Part E: a failed target reset inside restore must not exit silently (D2) ──
+# restore_snapshot resets the target (`rm -rf; mkdir -p`) before rebuilding from
+# the snapshot. Under `set -e` (trap disarmed) a bare reset that fails would exit
+# the whole script immediately — after `rm` may have deleted part of the target —
+# WITHOUT printing where the snapshot lives. We trigger a rollback (cp poison) AND
+# fail the target reset (rm shim), then assert the shipped installer emits the
+# manual-recovery pointer and preserves the snapshot.
+run_rmfail_upgrade() {
+  local installer="$1" H OUT SHIM rc
+  H=$(mktemp -d); OUT=$(mktemp); SHIM=$(mktemp -d)
+  seed_home "$H"
+  make_cp_shim "$SHIM"        # poison cp → triggers the abort + restore
+  make_rm_fail_shim "$SHIM"   # rm -rf <H> fails → exercises the D2 reset guard
+  set +e
+  PATH="$SHIM:$ORIG_PATH" ORIG_PATH_FOR_RM="$ORIG_PATH" FAIL_RM_TARGET="$H" \
+    MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash "$installer" >"$OUT" 2>&1
+  rc=$?
+  set -e 2>/dev/null || true
+  rm -rf "$SHIM"
+  printf '%s\t%s\t%s\n' "$rc" "$OUT" "$H"
+}
+
+IFS=$'\t' read -r rcG OUTG HG < <(run_rmfail_upgrade "$INSTALL")
+chk "[reset-fail] a failed target reset still aborts non-zero" \
+  "[ '$rcG' -ne 0 ]"
+chk "[reset-fail] the manual-recovery pointer is emitted (not a silent set -e exit)" \
+  "grep -q 'Snapshot restore could not reset' '$OUTG'"
+chk "[reset-fail] the recovery message points at a preserved snapshot dir" \
+  "grep -q 'preserved at: .*mosaic-snapshot' '$OUTG'"
+SNAP_E="$(grep -o '/[^ ]*mosaic-snapshot[^ ]*' "$OUTG" | head -1)"
+chk "[reset-fail] the named snapshot directory actually survives for recovery" \
+  "[ -n '$SNAP_E' ] && [ -d '$SNAP_E' ]"
+chk "[reset-fail] operator secret value never appears in installer output" \
+  "! grep -q '$SECRET' '$OUTG'"
+
+# Control: delete the D2 recovery line so a failed reset returns non-zero with NO
+# operator pointer — the observable defect (half-reset target, snapshot orphaned
+# in /tmp with no path told to the operator). Proves the message is load-bearing.
+sed '/Snapshot restore could not reset/d' "$INSTALL" > "$D2CTRL"
+chk "[control] the D2-recovery strip actually changed the installer" \
+  "! cmp -s '$INSTALL' '$D2CTRL'"
+IFS=$'\t' read -r _rcH OUTH HH < <(run_rmfail_upgrade "$D2CTRL")
+chk "[control] without the D2 recovery line the operator gets no snapshot pointer" \
+  "! grep -q 'Snapshot restore could not reset' '$OUTH'"
+[ -n "${SNAP_E:-}" ] && rm -rf "$SNAP_E"
+# Reap any snapshot the reset-fail runs left in /tmp (reset failed → never cleaned).
+grep -o '/[^ ]*mosaic-snapshot[^ ]*' "$OUTH" 2>/dev/null | head -1 | while read -r s; do rm -rf "$s"; done
+
+# Cleanup ($STRIPPED / $NOEXIT / $D1CTRL / $D2CTRL are also removed by the EXIT trap).
+for d in "$HA" "$REFA" "$HB" "$REFB" "$HC" "$HD" "$HE" "$REFE" "$HF" "$REFF" "$HG" "$HH"; do rm -rf "$d"; done
+rm -f "$OUTA" "$OUTB" "$OUTC" "$OUTD" "$OUTE" "$OUTF" "$OUTG" "$OUTH" \
+  "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
+
+echo
+echo "RESULT: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

packages/mosaic/src/cli-smoke.spec.ts

@@ -1,3 +1,5 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 import { Command } from 'commander';
 import { registerBrainCommand } from '@mosaicstack/brain';
@@ -16,6 +18,8 @@ import { registerConfigCommand } from './commands/config.js';
 // without throwing. This is the "mosaic <cmd> --help exits 0" gate that
 // guards the sub-package CLI surface (CU-05-01..08) from silent breakage.
 
+const CLI_PATH = fileURLToPath(new URL('../dist/cli.js', import.meta.url));
+
 const REGISTRARS: Array<[string, (program: Command) => void]> = [
   ['auth', registerAuthCommand],
   ['brain', registerBrainCommand],
@@ -46,6 +50,40 @@ describe('sub-package CLI smoke (CU-05-10)', () => {
     });
   }
 
+  it.each(['source', 'decisions', 'observations'] as const)(
+    'production CLI emits one blocked JSON object for bare --%s',
+    (bareOption) => {
+      const args = [
+        CLI_PATH,
+        'fleet',
+        'migrate-v1',
+        'preview',
+        '--source=source',
+        '--decisions=decisions',
+        '--observations=observations',
+      ];
+      args[args.findIndex((argument) => argument.startsWith(`--${bareOption}=`))] =
+        `--${bareOption}`;
+
+      const result = spawnSync(process.execPath, args, { encoding: 'utf8' });
+      const outputLines = result.stdout.trim().split('\n');
+
+      expect(result.status).toBe(1);
+      expect(result.stderr).toBe('');
+      expect(outputLines).toHaveLength(1);
+      expect(JSON.parse(outputLines[0]!)).toEqual({
+        status: 'blocked',
+        blockers: [
+          {
+            code: 'missing-migration-preview-option-value',
+            path: `request.${bareOption}`,
+            detail: 'Required migration preview option value is missing.',
+          },
+        ],
+      });
+    },
+  );
+
   it('all nine sub-package commands coexist on a single program', () => {
     const program = new Command();
     for (const [, register] of REGISTRARS) register(program);

packages/mosaic/src/cli.ts

@@ -27,6 +27,7 @@ import {
   checkForAllUpdates,
   formatAllPackagesTable,
   getInstallAllCommand,
+  repairFleetCommsTools,
   runFrameworkReseed,
   refreshActiveFleetUnits,
   readRosterAgentNames,
@@ -420,115 +421,142 @@ program
     'Skip re-seeding framework files into ~/.config/mosaic after the CLI update',
   )
   .option('--relaunch', 'Restart durable fleet agents so the new launcher/runtime takes effect')
-  .action(async (opts: { check?: boolean; reseed?: boolean; relaunch?: boolean }) => {
-    // checkForAllUpdates imported statically above
-    const { execSync } = await import('node:child_process');
-
-    // Re-seed the framework from the freshly-installed package, propagate shipped
-    // systemd unit fixes to the active units, and (opt-in) relaunch durable
-    // agents. Shared by the "packages updated" and the "framework drift" paths.
-    const reseedFramework = (reason: string): void => {
-      console.log(reason);
-      const reseed = runFrameworkReseed();
-      if (!reseed.ok) {
-        console.error(
-          `\n⚠ Framework re-seed skipped: ${reseed.reason ?? 'unknown'}.\n` +
-            '  Activate manually: bash "$(npm root -g)/@mosaicstack/mosaic/framework/install.sh" ' +
-            '(MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep)',
+  .option(
+    '--repair-tools',
+    'Restore the supported current-version TOOLS contract and executable fleet helper',
+  )
+  .action(
+    async (opts: {
+      check?: boolean;
+      reseed?: boolean;
+      relaunch?: boolean;
+      repairTools?: boolean;
+    }) => {
+      if (opts.repairTools) {
+        const repair = repairFleetCommsTools();
+        if (!repair.ok) {
+          console.error(`Fleet communications tools repair failed: ${repair.reason ?? 'unknown'}`);
+          process.exitCode = 1;
+          return;
+        }
+        console.log(
+          repair.changed
+            ? 'Fleet communications tools repaired from the supported current framework.'
+            : 'Fleet communications tools already match the supported current framework.',
         );
+        if (repair.backupPath) console.log(`Preserved previous TOOLS.md at ${repair.backupPath}.`);
+        console.log('No active context or session was rewritten.');
         return;
       }
-      console.log('✔ Framework re-seeded.');
-      // Propagate shipped systemd unit fixes to the ACTIVE units (re-seed only
-      // touches ~/.config/mosaic/systemd/user; systemd runs ~/.config/systemd/user).
-      const units = refreshActiveFleetUnits();
-      if (units.refreshed.length > 0) {
-        console.log(`✔ Refreshed ${units.refreshed.length} active systemd unit(s).`);
-      }
-      const agents = readRosterAgentNames();
-      if (agents.length === 0) return;
-      if (opts.relaunch) {
-        console.log(`\nRelaunching ${agents.length} fleet agent(s) to pick up the new runtime…`);
-        for (const restart of buildRelaunchCommands(agents)) {
-          try {
-            execSync(restart.join(' '), { stdio: 'inherit', timeout: 30_000 });
-          } catch {
-            console.error(`  ⚠ failed to restart agent — run: ${restart.join(' ')}`);
-          }
+      // checkForAllUpdates imported statically above
+      const { execSync } = await import('node:child_process');
+
+      // Re-seed the framework from the freshly-installed package, propagate shipped
+      // systemd unit fixes to the active units, and (opt-in) relaunch durable
+      // agents. Shared by the "packages updated" and the "framework drift" paths.
+      const reseedFramework = (reason: string): void => {
+        console.log(reason);
+        const reseed = runFrameworkReseed();
+        if (!reseed.ok) {
+          console.error(
+            `\n⚠ Framework re-seed skipped: ${reseed.reason ?? 'unknown'}.\n` +
+              '  Activate manually: bash "$(npm root -g)/@mosaicstack/mosaic/framework/install.sh" ' +
+              '(MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep)',
+          );
+          return;
         }
-        console.log('✔ Agents relaunched.');
-      } else {
-        console.log(
-          `\nℹ ${agents.length} fleet agent(s) are still running the previous runtime. ` +
-            'Restart them to activate the update:\n    mosaic update --relaunch   ' +
-            '(or: mosaic fleet restart <agent>)',
-        );
+        console.log('✔ Framework re-seeded.');
+        // Propagate shipped systemd unit fixes to the ACTIVE units (re-seed only
+        // touches ~/.config/mosaic/systemd/user; systemd runs ~/.config/systemd/user).
+        const units = refreshActiveFleetUnits();
+        if (units.refreshed.length > 0) {
+          console.log(`✔ Refreshed ${units.refreshed.length} active systemd unit(s).`);
+        }
+        const agents = readRosterAgentNames();
+        if (agents.length === 0) return;
+        if (opts.relaunch) {
+          console.log(`\nRelaunching ${agents.length} fleet agent(s) to pick up the new runtime…`);
+          for (const restart of buildRelaunchCommands(agents)) {
+            try {
+              execSync(restart.join(' '), { stdio: 'inherit', timeout: 30_000 });
+            } catch {
+              console.error(`  ⚠ failed to restart agent — run: ${restart.join(' ')}`);
+            }
+          }
+          console.log('✔ Agents relaunched.');
+        } else {
+          console.log(
+            `\nℹ ${agents.length} fleet agent(s) are still running the previous runtime. ` +
+              'Restart them to activate the update:\n    mosaic update --relaunch   ' +
+              '(or: mosaic fleet restart <agent>)',
+          );
+        }
+      };
+
+      console.log('Checking for updates…');
+      const results = checkForAllUpdates({ skipCache: true });
+
+      console.log('');
+      console.log(formatAllPackagesTable(results));
+
+      const outdated = results.filter((r: { updateAvailable: boolean }) => r.updateAvailable);
+      if (outdated.length === 0) {
+        const anyInstalled = results.some((r: { current: string }) => r.current);
+        if (!anyInstalled) {
+          console.error('No @mosaicstack/* packages are installed.');
+          process.exit(1);
+        }
+        console.log('\n✔ All packages up to date.');
+        // #642: the CLI may have been upgraded outside `mosaic update` (e.g. a
+        // direct `npm i -g`), leaving the framework files stale even though no
+        // package is reported outdated. Detect that via the framework version and
+        // re-seed so shipped launcher/runtime fixes still activate.
+        const drift = checkFrameworkDrift();
+        if (drift.drifted && opts.reseed !== false) {
+          reseedFramework(
+            `\nFramework drift detected (on-disk v${drift.installed} < bundled v${drift.bundled}) — ` +
+              'the CLI was updated outside `mosaic update`. Re-seeding framework files into ' +
+              '~/.config/mosaic (data-safe; keeps your edits)…',
+          );
+        }
+        return;
       }
-    };
 
-    console.log('Checking for updates…');
-    const results = checkForAllUpdates({ skipCache: true });
+      if (opts.check) {
+        process.exit(2); // Signal to callers that an update exists
+      }
 
-    console.log('');
-    console.log(formatAllPackagesTable(results));
-
-    const outdated = results.filter((r: { updateAvailable: boolean }) => r.updateAvailable);
-    if (outdated.length === 0) {
-      const anyInstalled = results.some((r: { current: string }) => r.current);
-      if (!anyInstalled) {
-        console.error('No @mosaicstack/* packages are installed.');
+      console.log(`\nInstalling ${outdated.length} update(s)…`);
+      try {
+        // Relies on @mosaicstack:registry in ~/.npmrc
+        const cmd = getInstallAllCommand(outdated);
+        execSync(cmd, {
+          stdio: 'inherit',
+          timeout: 60_000,
+        });
+        console.log('\n✔ Updated successfully.');
+      } catch {
+        console.error('\nUpdate failed. Try manually: bash tools/install.sh');
         process.exit(1);
       }
-      console.log('\n✔ All packages up to date.');
-      // #642: the CLI may have been upgraded outside `mosaic update` (e.g. a
-      // direct `npm i -g`), leaving the framework files stale even though no
-      // package is reported outdated. Detect that via the framework version and
-      // re-seed so shipped launcher/runtime fixes still activate.
+
+      // F3-m3 / R13: the CLI is updated, but the framework files in
+      // ~/.config/mosaic/ are still the previous version. Re-seed them from the
+      // freshly-installed package so shipped launcher/runtime changes ACTIVATE.
+      // Re-seed when the framework-bearing package itself updated OR the on-disk
+      // framework is older than the freshly-installed one (#642 — e.g. only
+      // sibling packages were outdated but the CLI was already ahead).
+      const mosaicUpdated = outdated.some(
+        (r: { package: string }) => r.package === FRAMEWORK_RESEED_PACKAGE,
+      );
       const drift = checkFrameworkDrift();
-      if (drift.drifted && opts.reseed !== false) {
+      if ((mosaicUpdated || drift.drifted) && opts.reseed !== false) {
         reseedFramework(
-          `\nFramework drift detected (on-disk v${drift.installed} < bundled v${drift.bundled}) — ` +
-            'the CLI was updated outside `mosaic update`. Re-seeding framework files into ' +
-            '~/.config/mosaic (data-safe; keeps your edits)…',
+          '\nRe-seeding framework files into ~/.config/mosaic (data-safe; keeps your edits)…',
         );
       }
-      return;
-    }
-
-    if (opts.check) {
-      process.exit(2); // Signal to callers that an update exists
-    }
-
-    console.log(`\nInstalling ${outdated.length} update(s)…`);
-    try {
-      // Relies on @mosaicstack:registry in ~/.npmrc
-      const cmd = getInstallAllCommand(outdated);
-      execSync(cmd, {
-        stdio: 'inherit',
-        timeout: 60_000,
-      });
-      console.log('\n✔ Updated successfully.');
-    } catch {
-      console.error('\nUpdate failed. Try manually: bash tools/install.sh');
-      process.exit(1);
-    }
-
-    // F3-m3 / R13: the CLI is updated, but the framework files in
-    // ~/.config/mosaic/ are still the previous version. Re-seed them from the
-    // freshly-installed package so shipped launcher/runtime changes ACTIVATE.
-    // Re-seed when the framework-bearing package itself updated OR the on-disk
-    // framework is older than the freshly-installed one (#642 — e.g. only
-    // sibling packages were outdated but the CLI was already ahead).
-    const mosaicUpdated = outdated.some(
-      (r: { package: string }) => r.package === FRAMEWORK_RESEED_PACKAGE,
-    );
-    const drift = checkFrameworkDrift();
-    if ((mosaicUpdated || drift.drifted) && opts.reseed !== false) {
-      reseedFramework(
-        '\nRe-seeding framework files into ~/.config/mosaic (data-safe; keeps your edits)…',
-      );
-    }
-  });
+    },
+  );
 
 // ─── wizard ─────────────────────────────────────────────────────────────
 

packages/mosaic/src/commands/compose-contract.spec.ts

@@ -1,7 +1,20 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
+import {
+  accessSync,
+  chmodSync,
+  constants,
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  readFileSync,
+  renameSync,
+  symlinkSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FileConfigAdapter } from '../config/file-adapter.js';
 import { composeContract } from './launch.js';
 
 /**
@@ -22,7 +35,9 @@ import { composeContract } from './launch.js';
 const CONSTITUTION = '# CONSTITUTION\n\nGATE-1: the non-negotiable law.\n';
 const AGENTS = '# Mosaic Agent Dispatcher\n\nLoad order + guide router.\n';
 const USER = '# operator\n\nName: Test Operator\n';
-const TOOLS = '# tools index\n';
+const TOOLS = '# tools index\n\n<!-- fleet-comms-contract: 1 -->\n';
+const FRAMEWORK_SOURCE = fileURLToPath(new URL('../../framework', import.meta.url));
+const SOURCE_TOOLS_PATH = join(FRAMEWORK_SOURCE, 'defaults', 'TOOLS.md');
 
 function makeHome(): { home: string; root: string } {
   const root = mkdtempSync(join(tmpdir(), 'mosaic-compose-'));
@@ -31,6 +46,12 @@ function makeHome(): { home: string; root: string } {
     mkdirSync(join(home, 'runtime', h), { recursive: true });
     writeFileSync(join(home, 'runtime', h, 'RUNTIME.md'), `# ${h} runtime contract\n`);
   }
+  mkdirSync(join(home, 'defaults'), { recursive: true });
+  mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
+  writeFileSync(join(home, 'defaults', 'TOOLS.md'), TOOLS);
+  const helper = join(home, 'tools', 'tmux', 'agent-send.sh');
+  writeFileSync(helper, '#!/bin/sh\n');
+  chmodSync(helper, 0o755);
   writeFileSync(join(home, 'CONSTITUTION.md'), CONSTITUTION);
   writeFileSync(join(home, 'AGENTS.md'), AGENTS);
   writeFileSync(join(home, 'USER.md'), USER);
@@ -42,16 +63,31 @@ describe('composeContract — overlay composer', () => {
   let fixture: ReturnType<typeof makeHome>;
   let prevCwd: string;
   let cwdDir: string;
+  let prevAgentName: string | undefined;
+  let prevAgentClass: string | undefined;
+  let prevAgentToolPolicy: string | undefined;
 
   beforeEach(() => {
     fixture = makeHome();
     prevCwd = process.cwd();
+    prevAgentName = process.env['MOSAIC_AGENT_NAME'];
+    prevAgentClass = process.env['MOSAIC_AGENT_CLASS'];
+    prevAgentToolPolicy = process.env['MOSAIC_AGENT_TOOL_POLICY'];
+    delete process.env['MOSAIC_AGENT_NAME'];
+    delete process.env['MOSAIC_AGENT_CLASS'];
+    delete process.env['MOSAIC_AGENT_TOOL_POLICY'];
     cwdDir = mkdtempSync(join(tmpdir(), 'mosaic-cwd-'));
     process.chdir(cwdDir); // neutralize cwd-relative mission/PRD blocks
   });
 
   afterEach(() => {
     process.chdir(prevCwd);
+    if (prevAgentName === undefined) delete process.env['MOSAIC_AGENT_NAME'];
+    else process.env['MOSAIC_AGENT_NAME'] = prevAgentName;
+    if (prevAgentClass === undefined) delete process.env['MOSAIC_AGENT_CLASS'];
+    else process.env['MOSAIC_AGENT_CLASS'] = prevAgentClass;
+    if (prevAgentToolPolicy === undefined) delete process.env['MOSAIC_AGENT_TOOL_POLICY'];
+    else process.env['MOSAIC_AGENT_TOOL_POLICY'] = prevAgentToolPolicy;
     rmSync(fixture.root, { recursive: true, force: true });
     rmSync(cwdDir, { recursive: true, force: true });
   });
@@ -64,13 +100,17 @@ describe('composeContract — overlay composer', () => {
       [
         'version: 1',
         'transport: tmux',
+        'tmux:',
+        '  socket_name: mosaic-fleet',
         'agents:',
         '  - name: orchestrator',
         '    runtime: claude',
         '    class: orchestrator',
+        '    host: w-jarvis',
         '  - name: enhancer',
         '    runtime: claude',
         '    class: enhancer',
+        '    host: w-jarvis',
         '  - name: coder0-0',
         '    runtime: claude',
         '    class: implementer',
@@ -82,19 +122,266 @@ describe('composeContract — overlay composer', () => {
     const prev = process.env['MOSAIC_AGENT_NAME'];
     try {
       process.env['MOSAIC_AGENT_NAME'] = 'enhancer';
-      const out = composeContract('claude', fixture.home);
-      expect(out).toContain('# Fleet Comms');
-      expect(out).toMatch(/`\[[^\]]+:enhancer\]`/); // own [host:session] identity (host machine-dependent)
-      // local peer → no -H; cross-host peer → -H ssh
-      expect(out).toContain('-s orchestrator -m "…"');
-      expect(out).toContain('-H jwoltje@10.1.10.37 -s coder0-0 -m "…"');
-      expect(out).not.toContain('-H jwoltje@10.1.10.37 -s orchestrator'); // local stays local
+      const outputs = (['claude', 'codex', 'opencode', 'pi'] as const).map((runtime) =>
+        composeContract(runtime, fixture.home),
+      );
+      for (const out of outputs) {
+        expect(out).toContain('# Fleet Comms');
+        expect(out).toContain('Host: `w-jarvis`');
+        expect(out).toContain('Agent/session: `enhancer`');
+        expect(out).toContain('tmux socket: `mosaic-fleet`');
+        expect(out).toContain(
+          `Helper: \`${join(fixture.home, 'tools', 'tmux', 'agent-send.sh')}\``,
+        );
+        expect(out).toContain('-L mosaic-fleet -s orchestrator -m "…"');
+        expect(out).toContain('-L mosaic-fleet -H jwoltje@10.1.10.37 -s coder0-0 -m "…"');
+        expect(out).not.toContain('-H jwoltje@10.1.10.37 -s orchestrator');
+      }
+      const commsSection = (out: string): string => out.slice(out.indexOf('# Fleet Comms'));
+      const authoritative = commsSection(outputs[0]!);
+      expect(outputs.map(commsSection)).toEqual([
+        authoritative,
+        authoritative,
+        authoritative,
+        authoritative,
+      ]);
     } finally {
       if (prev === undefined) delete process.env['MOSAIC_AGENT_NAME'];
       else process.env['MOSAIC_AGENT_NAME'] = prev;
     }
   });
 
+  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
+    'derives canonical class, persona, tool policy, and comms from one roster member for %s',
+    (runtime) => {
+      mkdirSync(join(fixture.home, 'fleet', 'roles'), { recursive: true });
+      writeFileSync(
+        join(fixture.home, 'fleet', 'roles', 'code.md'),
+        '# Code\n\n(`class: code`)\n\nCANONICAL-CODE-MANDATE.\n',
+      );
+      writeFileSync(
+        join(fixture.home, 'fleet', 'roster.yaml'),
+        [
+          'version: 1',
+          'transport: tmux',
+          'agents:',
+          '  - name: exact-coder',
+          `    runtime: ${runtime}`,
+          '    class: implementer',
+          '    tool_policy: operator-interaction',
+          '',
+        ].join('\n'),
+      );
+      process.env['MOSAIC_AGENT_NAME'] = 'exact-coder';
+      process.env['MOSAIC_AGENT_CLASS'] = 'implementer';
+      process.env['MOSAIC_AGENT_TOOL_POLICY'] = 'ambient-policy-must-not-win';
+
+      const out = composeContract(runtime, fixture.home);
+
+      expect(out).toContain('# Persona Contract (code)');
+      expect(out).toContain('CANONICAL-CODE-MANDATE');
+      expect(out).toContain('Role/class: `code`');
+      expect(out).toContain('# Fleet Tool Policy (operator-interaction)');
+      expect(out).not.toContain('ambient-policy-must-not-win');
+      expect(out.indexOf('# Persona Contract')).toBeLessThan(out.indexOf('# Fleet Comms'));
+    },
+  );
+
+  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
+    'does not inherit ambient tool policy when canonical member omits tool_policy for %s',
+    (runtime) => {
+      mkdirSync(join(fixture.home, 'fleet', 'roles'), { recursive: true });
+      writeFileSync(
+        join(fixture.home, 'fleet', 'roles', 'code.md'),
+        '# Code\n\n(`class: code`)\n\nCANONICAL-CODE-MANDATE.\n',
+      );
+      writeFileSync(
+        join(fixture.home, 'fleet', 'roster.yaml'),
+        [
+          'version: 1',
+          'transport: tmux',
+          'agents:',
+          '  - name: exact-coder',
+          `    runtime: ${runtime}`,
+          '    class: implementer',
+          '',
+        ].join('\n'),
+      );
+      process.env['MOSAIC_AGENT_NAME'] = 'exact-coder';
+      process.env['MOSAIC_AGENT_CLASS'] = 'implementer';
+      process.env['MOSAIC_AGENT_TOOL_POLICY'] = 'operator-interaction';
+
+      const out = composeContract(runtime, fixture.home);
+
+      expect(out).toContain('# Persona Contract (code)');
+      expect(out).toContain('Role/class: `code`');
+      expect(out).toContain('# Fleet Comms');
+      expect(out).not.toContain('# Fleet Tool Policy (operator-interaction)');
+    },
+  );
+
+  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
+    'rejects an ambient class that mismatches the canonical roster member for %s',
+    (runtime) => {
+      mkdirSync(join(fixture.home, 'fleet'), { recursive: true });
+      writeFileSync(
+        join(fixture.home, 'fleet', 'roster.yaml'),
+        [
+          'version: 1',
+          'transport: tmux',
+          'agents:',
+          '  - name: exact-coder',
+          `    runtime: ${runtime}`,
+          '    class: implementer',
+          '',
+        ].join('\n'),
+      );
+      process.env['MOSAIC_AGENT_NAME'] = 'exact-coder';
+      process.env['MOSAIC_AGENT_CLASS'] = 'reviewer';
+
+      expect(() => composeContract(runtime, fixture.home)).toThrow(
+        /ambient MOSAIC_AGENT_CLASS.*review.*canonical roster.*code/i,
+      );
+    },
+  );
+
+  it('composes solo role mandate and boundaries before explicit no-peer authority', () => {
+    mkdirSync(join(fixture.home, 'fleet', 'roles'), { recursive: true });
+    writeFileSync(
+      join(fixture.home, 'fleet', 'roles', 'orchestrator.md'),
+      '# Orchestrator\n\n## Mandate\n\nCoordinate exact work.\n\n## Boundaries\n\nDo not infer authority.\n',
+    );
+    writeFileSync(
+      join(fixture.home, 'fleet', 'roster.yaml'),
+      [
+        'version: 1',
+        'transport: tmux',
+        'agents:',
+        '  - name: solo',
+        '    runtime: claude',
+        '    class: orchestrator',
+        '',
+      ].join('\n'),
+    );
+    process.env['MOSAIC_AGENT_NAME'] = 'solo';
+    process.env['MOSAIC_AGENT_CLASS'] = 'orchestrator';
+
+    const out = composeContract('claude', fixture.home);
+
+    expect(out).toContain('## Mandate');
+    expect(out).toContain('## Boundaries');
+    expect(out).toContain('Role/class: `orchestrator`');
+    expect(out).toContain('## Solo authority boundaries');
+    expect(out.indexOf('## Mandate')).toBeLessThan(out.indexOf('# Fleet Comms'));
+    expect(out.indexOf('## Boundaries')).toBeLessThan(out.indexOf('# Fleet Comms'));
+    expect(out).toContain('no peer, orchestrator, or remote communication authority');
+  });
+
+  it('proves real source TOOLS.md through fresh install, executable helper, and final composition', async () => {
+    const installRoot = mkdtempSync(join(tmpdir(), 'mosaic-real-contract-'));
+    const installedHome = join(installRoot, 'mosaic-home');
+    mkdirSync(installedHome, { recursive: true });
+    const previous = process.env['MOSAIC_AGENT_NAME'];
+
+    try {
+      const adapter = new FileConfigAdapter(installedHome, FRAMEWORK_SOURCE);
+      await adapter.syncFramework('fresh');
+
+      const sourceTools = readFileSync(SOURCE_TOOLS_PATH, 'utf8');
+      const installedToolsPath = join(installedHome, 'TOOLS.md');
+      expect(readFileSync(installedToolsPath, 'utf8')).toBe(sourceTools);
+      expect(sourceTools).toContain('fleet-comms-contract: 1');
+      expect(sourceTools).not.toMatch(
+        /<(?:user@host|src_host|src_session|dst_host|dst_session|target-session)>/,
+      );
+
+      const helper = join(installedHome, 'tools', 'tmux', 'agent-send.sh');
+      expect(() => accessSync(helper, constants.X_OK)).not.toThrow();
+
+      mkdirSync(join(installedHome, 'fleet'), { recursive: true });
+      writeFileSync(
+        join(installedHome, 'fleet', 'roster.yaml'),
+        [
+          'version: 1',
+          'transport: tmux',
+          'tmux:',
+          '  socket_name: exact-socket',
+          'agents:',
+          '  - name: exact-self',
+          '    runtime: pi',
+          '    class: orchestrator',
+          '    host: local-host',
+          '  - name: exact-peer',
+          '    runtime: claude',
+          '    class: implementer',
+          '    host: local-host',
+          '',
+        ].join('\n'),
+      );
+      process.env['MOSAIC_AGENT_NAME'] = 'exact-self';
+
+      const composed = composeContract('pi', installedHome);
+      expect(composed).toContain(sourceTools);
+      expect(composed).toContain(`Helper: \`${helper}\``);
+      expect(composed).toContain(`${helper} -L exact-socket -s exact-peer -m "…"`);
+      expect(composed).not.toContain('# Fleet Comms Installation Status');
+    } finally {
+      if (previous === undefined) delete process.env['MOSAIC_AGENT_NAME'];
+      else process.env['MOSAIC_AGENT_NAME'] = previous;
+      rmSync(installRoot, { recursive: true, force: true });
+    }
+  });
+
+  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
+    'never injects installed TOOLS.md through a target symlink for %s',
+    (runtime) => {
+      const toolsPath = join(fixture.home, 'TOOLS.md');
+      const external = join(fixture.root, 'attacker-tools.md');
+      writeFileSync(external, 'UNSAFE-TARGET-SYMLINK-CONTENT\n');
+      rmSync(toolsPath);
+      symlinkSync(external, toolsPath);
+
+      const out = composeContract(runtime, fixture.home);
+
+      expect(out).not.toContain('UNSAFE-TARGET-SYMLINK-CONTENT');
+      expect(out).toContain('# Fleet Comms Installation Status');
+      expect(out).toContain('unavailable');
+      expect(readFileSync(external, 'utf8')).toBe('UNSAFE-TARGET-SYMLINK-CONTENT\n');
+    },
+  );
+
+  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
+    'never injects installed TOOLS.md through an ancestor symlink for %s',
+    (runtime) => {
+      const realHome = join(fixture.root, 'real-mosaic-home');
+      renameSync(fixture.home, realHome);
+      symlinkSync(realHome, fixture.home, 'dir');
+      writeFileSync(join(realHome, 'TOOLS.md'), 'UNSAFE-ANCESTOR-SYMLINK-CONTENT\n');
+
+      const out = composeContract(runtime, fixture.home);
+
+      expect(out).not.toContain('UNSAFE-ANCESTOR-SYMLINK-CONTENT');
+      expect(out).toContain('# Fleet Comms Installation Status');
+      expect(out).toContain('unavailable');
+      expect(readFileSync(join(realHome, 'TOOLS.md'), 'utf8')).toBe(
+        'UNSAFE-ANCESTOR-SYMLINK-CONTENT\n',
+      );
+    },
+  );
+
+  it('reports stale preserved TOOLS.md without rewriting it', () => {
+    const toolsPath = join(fixture.home, 'TOOLS.md');
+    const stale = '# user-customized tools without fleet contract marker\n';
+    writeFileSync(toolsPath, stale);
+
+    const out = composeContract('pi', fixture.home);
+
+    expect(out).toContain('# Fleet Comms Installation Status');
+    expect(out).toContain('does not byte-match');
+    expect(out).toContain('active context was not rewritten');
+    expect(readFileSync(toolsPath, 'utf8')).toBe(stale);
+  });
+
   it('does NOT inject fleet comms when MOSAIC_AGENT_NAME is unset (non-fleet launch)', () => {
     const prev = process.env['MOSAIC_AGENT_NAME'];
     try {
@@ -105,6 +392,24 @@ describe('composeContract — overlay composer', () => {
     }
   });
 
+  it('fails closed when an explicitly requested fleet identity is unknown', () => {
+    mkdirSync(join(fixture.home, 'fleet'), { recursive: true });
+    writeFileSync(
+      join(fixture.home, 'fleet', 'roster.yaml'),
+      ['version: 1', 'transport: tmux', 'agents:', '  - name: exact-agent', '    runtime: pi'].join(
+        '\n',
+      ),
+    );
+    const previous = process.env['MOSAIC_AGENT_NAME'];
+    try {
+      process.env['MOSAIC_AGENT_NAME'] = 'invented-agent';
+      expect(() => composeContract('pi', fixture.home)).toThrow(/known exact names: exact-agent/i);
+    } finally {
+      if (previous === undefined) delete process.env['MOSAIC_AGENT_NAME'];
+      else process.env['MOSAIC_AGENT_NAME'] = previous;
+    }
+  });
+
   it('includes the per-tier anchors and the selected harness runtime', () => {
     const out = composeContract('claude', fixture.home);
     expect(out).toContain('GATE-1: the non-negotiable law.'); // L0
@@ -240,10 +545,14 @@ describe('composeContract — overlay composer', () => {
       writeFileSync(
         join(fixture.home, 'fleet', 'roster.yaml'),
         [
+          'version: 1',
+          'transport: tmux',
           'agents:',
           '  - name: orchestrator',
+          '    runtime: claude',
           '    class: orchestrator',
           '  - name: enhancer',
+          '    runtime: claude',
           '    class: enhancer',
           '',
         ].join('\n'),

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

@@ -0,0 +1,280 @@
+import { mkdir, mkdtemp, rm, 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 { registerFleetMigrationCommand } from './fleet-migration-command.js';
+
+let cleanup: string | undefined;
+
+afterEach(async (): Promise<void> => {
+  if (cleanup) await rm(cleanup, { recursive: true, force: true });
+  cleanup = undefined;
+});
+
+describe('fleet migrate-v1 preview command', (): void => {
+  it('emits one ready JSON result without any runtime or file mutation API', async () => {
+    cleanup = await mkdtemp(join(tmpdir(), 'fleet-migration-command-'));
+    const rolesDir = join(cleanup, 'roles');
+    const overrideDir = join(cleanup, 'roles.local');
+    await mkdir(rolesDir);
+    await mkdir(overrideDir);
+    await writeFile(join(rolesDir, 'code.md'), '# code\n');
+    const files: Record<string, string> = {
+      source: `version: 1\ntransport: tmux\ntmux:\n  socket_name: test\ndefaults:\n  working_directory: /srv\nruntimes:\n  pi:\n    reset_command: /new\nagents:\n  - name: coder0\n    runtime: pi\n    class: implementer\n`,
+      decisions: JSON.stringify({
+        generation: 2,
+        defaultRuntime: 'pi',
+        agents: {
+          coder0: {
+            provider: 'openai',
+            model: 'gpt-5.6-sol',
+            reasoning: 'high',
+            enabled: true,
+            launchYolo: false,
+            toolPolicyDisposition: { action: 'replace', className: 'code' },
+          },
+        },
+      }),
+      observations: JSON.stringify({ coder0: { systemd: 'inactive', tmux: 'missing' } }),
+    };
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command();
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', cleanup);
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: cleanup,
+      rolesDir,
+      overrideDir,
+      readText: async (path): Promise<string> => files[path] ?? '',
+      printJson,
+      setExitCode,
+    });
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'fleet',
+      'migrate-v1',
+      'preview',
+      '--source',
+      'source',
+      '--decisions',
+      'decisions',
+      '--observations',
+      'observations',
+    ]);
+
+    expect(printJson).toHaveBeenCalledTimes(1);
+    expect(printJson).toHaveBeenCalledWith(expect.objectContaining({ status: 'ready' }));
+    expect(setExitCode).not.toHaveBeenCalled();
+    expect(fleet.helpInformation()).toContain('migrate-v1');
+    const migration = fleet.commands.find((command) => command.name() === 'migrate-v1');
+    expect(migration?.helpInformation()).not.toMatch(/--write|apply|canary|rollback/);
+  });
+
+  it('emits one stable blocked JSON result when --observations is missing', async () => {
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command().exitOverride();
+    program.configureOutput({
+      writeErr: vi.fn(),
+      writeOut: vi.fn(),
+    });
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: '/unused',
+      readText: vi.fn(),
+      printJson,
+      setExitCode,
+    });
+
+    await expect(
+      program.parseAsync([
+        'node',
+        'test',
+        'fleet',
+        'migrate-v1',
+        'preview',
+        '--source',
+        'source',
+        '--decisions',
+        'decisions',
+      ]),
+    ).resolves.toBe(program);
+    expect(printJson).toHaveBeenCalledTimes(1);
+    expect(printJson).toHaveBeenCalledWith({
+      status: 'blocked',
+      blockers: [
+        {
+          code: 'missing-migration-preview-option',
+          path: 'request.observations',
+          detail: 'Required migration preview option is missing.',
+        },
+      ],
+    });
+    expect(setExitCode).toHaveBeenCalledWith(1);
+  });
+
+  it.each(['source', 'decisions', 'observations'] as const)(
+    'emits one stable blocked JSON result when bare --%s has no value',
+    async (bareOption) => {
+      const printJson = vi.fn();
+      const setExitCode = vi.fn();
+      const readText = vi.fn();
+      const writeErr = vi.fn();
+      const program = new Command().exitOverride();
+      program.configureOutput({ writeErr, writeOut: vi.fn() });
+      const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+      registerFleetMigrationCommand(fleet, {
+        mosaicHome: '/unused',
+        readText,
+        printJson,
+        setExitCode,
+      });
+      const args = [
+        'node',
+        'test',
+        'fleet',
+        'migrate-v1',
+        'preview',
+        '--source=source',
+        '--decisions=decisions',
+        '--observations=observations',
+      ];
+      args[args.findIndex((argument) => argument.startsWith(`--${bareOption}=`))] =
+        `--${bareOption}`;
+
+      await expect(program.parseAsync(args)).resolves.toBe(program);
+
+      expect(printJson).toHaveBeenCalledTimes(1);
+      expect(printJson).toHaveBeenCalledWith({
+        status: 'blocked',
+        blockers: [
+          {
+            code: 'missing-migration-preview-option-value',
+            path: `request.${bareOption}`,
+            detail: 'Required migration preview option value is missing.',
+          },
+        ],
+      });
+      expect(setExitCode).toHaveBeenCalledTimes(1);
+      expect(setExitCode).toHaveBeenCalledWith(1);
+      expect(readText).not.toHaveBeenCalled();
+      expect(writeErr).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(['source', 'decisions', 'observations'] as const)(
+    'emits one stable blocked JSON result when --%s is present-empty',
+    async (emptyOption) => {
+      const printJson = vi.fn();
+      const setExitCode = vi.fn();
+      const readText = vi.fn();
+      const program = new Command().exitOverride();
+      program.configureOutput({ writeErr: vi.fn(), writeOut: vi.fn() });
+      const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+      registerFleetMigrationCommand(fleet, {
+        mosaicHome: '/unused',
+        readText,
+        printJson,
+        setExitCode,
+      });
+      const paths = { source: 'source', decisions: 'decisions', observations: 'observations' };
+      paths[emptyOption] = '';
+
+      await expect(
+        program.parseAsync([
+          'node',
+          'test',
+          'fleet',
+          'migrate-v1',
+          'preview',
+          `--source=${paths.source}`,
+          `--decisions=${paths.decisions}`,
+          `--observations=${paths.observations}`,
+        ]),
+      ).resolves.toBe(program);
+
+      expect(printJson).toHaveBeenCalledTimes(1);
+      expect(printJson).toHaveBeenCalledWith({
+        status: 'blocked',
+        blockers: [
+          {
+            code: 'empty-migration-preview-option',
+            path: `request.${emptyOption}`,
+            detail: 'Required migration preview option must be a non-empty path.',
+          },
+        ],
+      });
+      expect(setExitCode).toHaveBeenCalledTimes(1);
+      expect(setExitCode).toHaveBeenCalledWith(1);
+      expect(readText).not.toHaveBeenCalled();
+    },
+  );
+
+  it('emits a blocked result and sets exit 1 for malformed evidence', async () => {
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command();
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: '/unused',
+      readText: async (path): Promise<string> => (path === 'decisions' ? 'not-json' : '{}'),
+      printJson,
+      setExitCode,
+    });
+    await program.parseAsync([
+      'node',
+      'test',
+      'fleet',
+      'migrate-v1',
+      'preview',
+      '--source',
+      'source',
+      '--decisions',
+      'decisions',
+      '--observations',
+      'observations',
+    ]);
+    expect(printJson).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: 'blocked',
+        blockers: [expect.objectContaining({ code: 'migration-preview-failed' })],
+      }),
+    );
+    expect(setExitCode).toHaveBeenCalledWith(1);
+  });
+
+  it('redacts adversarial values from validation failures', async () => {
+    const secret = 'never-print-command-or-token';
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command();
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: '/unused',
+      readText: async (path): Promise<string> =>
+        path === 'decisions'
+          ? JSON.stringify({ generation: 2, agents: {}, [secret]: secret })
+          : '{}',
+      printJson,
+      setExitCode,
+    });
+    await program.parseAsync([
+      'node',
+      'test',
+      'fleet',
+      'migrate-v1',
+      'preview',
+      '--source',
+      'source',
+      '--decisions',
+      'decisions',
+      '--observations',
+      'observations',
+    ]);
+    expect(JSON.stringify(printJson.mock.calls)).not.toContain(secret);
+    expect(setExitCode).toHaveBeenCalledWith(1);
+  });
+});

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

@@ -0,0 +1,170 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import {
+  parseV1MigrationObservations,
+  parseV1ToV2MigrationDecisions,
+  previewV1ToV2Migration,
+} from '../fleet/v1-v2-migration.js';
+
+export interface FleetMigrationCommandDeps {
+  readonly mosaicHome?: string;
+  readonly rolesDir?: string;
+  readonly overrideDir?: string;
+  readonly readText?: (path: string) => Promise<string>;
+  readonly printJson?: (value: unknown) => void;
+  readonly setExitCode?: (code: number) => void;
+}
+
+interface PreviewOptions {
+  readonly source?: string | boolean;
+  readonly decisions?: string | boolean;
+  readonly observations?: string | boolean;
+}
+
+/** Registers preview-only v1 migration. This command has no mutation verbs or runners. */
+export function registerFleetMigrationCommand(
+  fleetCommand: Command,
+  deps: FleetMigrationCommandDeps = {},
+): void {
+  fleetCommand
+    .command('migrate-v1')
+    .description('Preview a field-complete v1-to-v2 roster migration')
+    .command('preview')
+    .description('Compile migration evidence without writing files or changing runtimes')
+    .option('--source [path]', 'v1 roster YAML or JSON')
+    .option('--decisions [path]', 'explicit migration decisions JSON')
+    .option('--observations [path]', 'reviewed lifecycle observations JSON')
+    .action(async (options: PreviewOptions): Promise<void> => {
+      const readText = deps.readText ?? ((path: string): Promise<string> => readFile(path, 'utf8'));
+      const printJson =
+        deps.printJson ?? ((value: unknown): void => console.log(JSON.stringify(value)));
+      const setExitCode =
+        deps.setExitCode ?? ((code: number): void => void (process.exitCode = code));
+      try {
+        const requiredOptionNames = ['source', 'decisions', 'observations'] as const;
+        const missingOption = requiredOptionNames.find((name) => options[name] === undefined);
+        if (missingOption !== undefined) {
+          printJson({
+            status: 'blocked',
+            blockers: [
+              {
+                code: 'missing-migration-preview-option',
+                path: `request.${missingOption}`,
+                detail: 'Required migration preview option is missing.',
+              },
+            ],
+          });
+          setExitCode(1);
+          return;
+        }
+        const missingValueOption = requiredOptionNames.find((name) => options[name] === true);
+        if (missingValueOption !== undefined) {
+          printJson({
+            status: 'blocked',
+            blockers: [
+              {
+                code: 'missing-migration-preview-option-value',
+                path: `request.${missingValueOption}`,
+                detail: 'Required migration preview option value is missing.',
+              },
+            ],
+          });
+          setExitCode(1);
+          return;
+        }
+        const emptyOption = requiredOptionNames.find(
+          (name) => typeof options[name] === 'string' && options[name].trim() === '',
+        );
+        if (emptyOption !== undefined) {
+          printJson({
+            status: 'blocked',
+            blockers: [
+              {
+                code: 'empty-migration-preview-option',
+                path: `request.${emptyOption}`,
+                detail: 'Required migration preview option must be a non-empty path.',
+              },
+            ],
+          });
+          setExitCode(1);
+          return;
+        }
+        const sourcePath = options.source;
+        const decisionsPath = options.decisions;
+        const observationsPath = options.observations;
+        if (
+          typeof sourcePath !== 'string' ||
+          typeof decisionsPath !== 'string' ||
+          typeof observationsPath !== 'string'
+        ) {
+          throw new Error('Validated migration preview options became unavailable.');
+        }
+        const [source, decisionsSource, observationsSource] = await Promise.all([
+          readText(sourcePath),
+          readText(decisionsPath),
+          readText(observationsPath),
+        ]);
+        const decisions = parseV1ToV2MigrationDecisions(
+          parseJsonObject(decisionsSource, 'migration decisions'),
+        );
+        const observations = parseV1MigrationObservations(
+          parseJsonObject(observationsSource, 'lifecycle observations'),
+        );
+        const mosaicHome =
+          deps.mosaicHome ?? fleetCommand.opts<{ mosaicHome: string }>().mosaicHome;
+        const preview = await previewV1ToV2Migration({
+          source,
+          sourcePath,
+          decisions,
+          observations,
+          personaDirs: {
+            rolesDir: deps.rolesDir ?? join(mosaicHome, 'fleet', 'roles'),
+            overrideDir: deps.overrideDir ?? join(mosaicHome, 'fleet', 'roles.local'),
+          },
+          environment: {
+            mosaicHome,
+            agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+          },
+        });
+        printJson(preview);
+        if (preview.status === 'blocked') setExitCode(1);
+      } catch (error: unknown) {
+        printJson({
+          status: 'blocked',
+          blockers: [
+            {
+              code: 'migration-preview-failed',
+              path: 'request',
+              detail: safeErrorDetail(error),
+            },
+          ],
+        });
+        setExitCode(1);
+      }
+    });
+}
+
+function parseJsonObject(source: string, label: string): unknown {
+  let value: unknown;
+  try {
+    value = JSON.parse(source) as unknown;
+  } catch {
+    throw new Error(`${label} must be valid JSON.`);
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+  return value;
+}
+
+function safeErrorDetail(error: unknown): string {
+  if (error instanceof Error && isPublishableValidationMessage(error.message)) return error.message;
+  return 'Migration preview failed without publishable detail.';
+}
+
+function isPublishableValidationMessage(message: string): boolean {
+  return /^(migration decisions|lifecycle observations) must be (valid JSON|a JSON object)\.$/.test(
+    message,
+  );
+}

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

@@ -90,6 +90,7 @@ describe('registerFleetCommand', () => {
       'init',
       'install',
       'install-systemd',
+      'migrate-v1',
       'persona',
       'plan',
       'profile',
@@ -197,6 +198,26 @@ describe('fleet roster parsing', () => {
     expect(getRosterAgent(roster, 'canary-pi').runtime).toBe('pi');
   });
 
+  it('uses /clear for an explicitly declared empty pi runtime config', async () => {
+    cleanup = await tempDir();
+    const rosterPath = join(cleanup, 'roster.yaml');
+    await writeFile(
+      rosterPath,
+      [
+        'version: 1',
+        'transport: tmux',
+        'runtimes:',
+        '  pi: {}',
+        'agents:',
+        '  - name: canary-pi',
+        '    runtime: pi',
+      ].join('\n'),
+    );
+
+    const loaded = await loadFleetRoster(rosterPath);
+    expect(loaded.runtimes.pi?.resetCommand).toBe('/clear');
+  });
+
   it('accepts optional agent alias and provider metadata without requiring them', async () => {
     cleanup = await tempDir();
     const rosterPath = join(cleanup, 'roster.yaml');
@@ -270,6 +291,32 @@ describe('fleet roster parsing', () => {
     expect(env).toContain('MOSAIC_TMUX_SOCKET=\n');
   });
 
+  it('preserves home-relative traversal until the shared environment boundary rejects it', async () => {
+    for (const workingDirectory of ['~/../escape', '~/src/../../escape']) {
+      cleanup = await tempDir();
+      const rosterPath = join(cleanup, 'roster.json');
+      await writeFile(
+        rosterPath,
+        JSON.stringify({
+          version: 1,
+          transport: 'tmux',
+          defaults: { working_directory: workingDirectory },
+          agents: [{ name: 'coder0', runtime: 'pi' }],
+        }),
+      );
+      const roster = await loadFleetRoster(rosterPath);
+
+      expect(() => generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toThrow(
+        expect.objectContaining({
+          diagnostic: expect.objectContaining({
+            code: 'unsafe-path',
+            key: 'MOSAIC_AGENT_WORKDIR',
+          }),
+        }),
+      );
+    }
+  });
+
   it('generates deterministic per-agent EnvironmentFile content', async () => {
     cleanup = await tempDir();
     const rosterPath = join(cleanup, 'roster.json');
@@ -288,8 +335,8 @@ describe('fleet roster parsing', () => {
     expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toBe(
       [
         'MOSAIC_AGENT_NAME=coder0',
-        // Reflects the roster's non-default `class: implementer` (A3a).
-        'MOSAIC_AGENT_CLASS=implementer',
+        // Reflects the roster's canonicalized compatibility class (A3a).
+        'MOSAIC_AGENT_CLASS=code',
         'MOSAIC_AGENT_RUNTIME=codex',
         'MOSAIC_AGENT_MODEL=',
         'MOSAIC_AGENT_REASONING=',
@@ -3505,7 +3552,66 @@ describe('fleet add/remove — pure helpers', () => {
     }
   });
 
-  it('serializeRosterToYaml round-trips optional fields (modelHint, workingDirectory)', async () => {
+  it.each([
+    ['tmux', { kind: 'tmux' }],
+    ['discord', { kind: 'discord', discord: { channelId: '1234567890' } }],
+    [
+      'matrix',
+      {
+        kind: 'matrix',
+        matrix: {
+          homeserverUrl: 'https://matrix.example.test',
+          userId: '@mosaic:example.test',
+          roomId: '!fleet:example.test',
+        },
+      },
+    ],
+  ] as const)('round-trips the supported %s connector through YAML', async (_kind, connector) => {
+    const yaml = serializeRosterToYaml({ ...baseRoster, connector });
+    const dir = await mkdtemp(join(tmpdir(), 'mosaic-fleet-connector-'));
+    const rosterPath = join(dir, 'roster.yaml');
+    try {
+      await writeFile(rosterPath, yaml);
+      expect((await loadFleetRoster(rosterPath)).connector).toEqual(connector);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    ['tmux', { kind: 'tmux' }],
+    ['discord', { kind: 'discord', discord: { channel_id: '1234567890' } }],
+    [
+      'matrix',
+      {
+        kind: 'matrix',
+        matrix: {
+          homeserver_url: 'https://matrix.example.test',
+          user_id: '@mosaic:example.test',
+          room_id: '!fleet:example.test',
+        },
+      },
+    ],
+  ] as const)('parses the supported %s connector from JSON', async (_kind, connector) => {
+    const dir = await mkdtemp(join(tmpdir(), 'mosaic-fleet-connector-'));
+    const rosterPath = join(dir, 'roster.json');
+    try {
+      await writeFile(
+        rosterPath,
+        JSON.stringify({
+          version: 1,
+          transport: 'tmux',
+          agents: [{ name: 'orchestrator', runtime: 'claude', class: 'orchestrator' }],
+          connector,
+        }),
+      );
+      expect((await loadFleetRoster(rosterPath)).connector?.kind).toBe(_kind);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('serializeRosterToYaml round-trips optional fields and exact comms targets', async () => {
     const rosterWithOptionals: FleetRoster = {
       ...baseRoster,
       agents: [
@@ -3517,6 +3623,9 @@ describe('fleet add/remove — pure helpers', () => {
           workingDirectory: '/tmp/work',
           persistentPersona: true,
           resetBetweenTasks: false,
+          host: '10.1.10.37',
+          ssh: 'jwoltje@10.1.10.37',
+          socket: 'mosaic-fleet',
         },
       ],
     };
@@ -3524,6 +3633,9 @@ describe('fleet add/remove — pure helpers', () => {
     expect(yaml).toContain('model_hint: claude-3-5-sonnet');
     expect(yaml).toContain('working_directory: /tmp/work');
     expect(yaml).toContain('persistent_persona: true');
+    expect(yaml).toContain('host: 10.1.10.37');
+    expect(yaml).toContain('ssh: jwoltje@10.1.10.37');
+    expect(yaml).toContain('socket: mosaic-fleet');
 
     const dir = await mkdtemp(join(tmpdir(), 'mosaic-fleet-'));
     const rosterPath = join(dir, 'roster.yaml');
@@ -3533,6 +3645,9 @@ describe('fleet add/remove — pure helpers', () => {
       expect(loaded.agents[0]!.modelHint).toBe('claude-3-5-sonnet');
       expect(loaded.agents[0]!.workingDirectory).toBe('/tmp/work');
       expect(loaded.agents[0]!.persistentPersona).toBe(true);
+      expect(loaded.agents[0]!.host).toBe('10.1.10.37');
+      expect(loaded.agents[0]!.ssh).toBe('jwoltje@10.1.10.37');
+      expect(loaded.agents[0]!.socket).toBe('mosaic-fleet');
     } finally {
       await rm(dir, { recursive: true, force: true });
     }

packages/mosaic/src/commands/fleet.ts

@@ -18,10 +18,27 @@ import { spawn } from 'node:child_process';
 import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
+import {
+  getRosterAgent,
+  loadFleetRoster,
+  resolveInstalledFleetRosterPath,
+  type FleetAgent,
+  type FleetRoster,
+} from '../fleet/fleet-roster-v1.js';
+export {
+  getRosterAgent,
+  loadFleetRoster,
+  resolveInstalledFleetRosterPath,
+} from '../fleet/fleet-roster-v1.js';
+export type { FleetAgent, FleetRoster } from '../fleet/fleet-roster-v1.js';
 import {
   registerFleetAgentCrudCommands,
   type FleetAgentCrudCommandDeps,
 } from './fleet-agent-crud-command.js';
+import {
+  registerFleetMigrationCommand,
+  type FleetMigrationCommandDeps,
+} from './fleet-migration-command.js';
 import {
   executeReconcilerCommandJson,
   registerFleetReconcilerCommands,
@@ -84,72 +101,7 @@ export interface FleetCommandDeps {
   isStdinTTY?: boolean;
   projectionApplier?: FleetAgentCrudCommandDeps['projectionApplier'];
   reconcileDeps?: FleetReconcilerCommandDeps['reconcileDeps'];
-}
-
-interface RawFleetRoster {
-  version?: unknown;
-  transport?: unknown;
-  tmux?: {
-    socket_name?: unknown;
-    socketName?: unknown;
-    holder_session?: unknown;
-    holderSession?: unknown;
-  };
-  defaults?: {
-    working_directory?: unknown;
-    workingDirectory?: unknown;
-  };
-  runtimes?: Record<string, { reset_command?: unknown; resetCommand?: unknown }>;
-  agents?: Array<{
-    name?: unknown;
-    alias?: unknown;
-    provider?: unknown;
-    runtime?: unknown;
-    class?: unknown;
-    working_directory?: unknown;
-    workingDirectory?: unknown;
-    model_hint?: unknown;
-    modelHint?: unknown;
-    reasoning_level?: unknown;
-    reasoningLevel?: unknown;
-    tool_policy?: unknown;
-    toolPolicy?: unknown;
-    persistent_persona?: unknown;
-    persistentPersona?: unknown;
-    reset_between_tasks?: unknown;
-    resetBetweenTasks?: unknown;
-    kickstart_template?: unknown;
-    kickstartTemplate?: unknown;
-  }>;
-}
-
-export interface FleetAgent {
-  name: string;
-  alias?: string;
-  provider?: string;
-  runtime: string;
-  className: string;
-  workingDirectory?: string;
-  modelHint?: string;
-  reasoningLevel?: string;
-  toolPolicy?: string;
-  persistentPersona?: boolean | string;
-  resetBetweenTasks?: boolean;
-  kickstartTemplate?: string;
-}
-
-export interface FleetRoster {
-  version: 1;
-  transport: 'tmux';
-  tmux: {
-    socketName: string;
-    holderSession: string;
-  };
-  defaults: {
-    workingDirectory: string;
-  };
-  runtimes: Record<string, { resetCommand: string }>;
-  agents: FleetAgent[];
+  migrationDeps?: Omit<FleetMigrationCommandDeps, 'mosaicHome'>;
 }
 
 export interface FleetPaths {
@@ -170,8 +122,6 @@ type FleetServiceAction = 'start' | 'stop' | 'restart' | 'status';
  * fallback for a socket-less roster (that now resolves to the default socket).
  */
 export const DEFAULT_SOCKET_NAME = 'mosaic-fleet';
-const DEFAULT_HOLDER_SESSION = '_holder';
-const DEFAULT_WORKING_DIRECTORY = '~/src';
 
 /**
  * tmux `-L` args for a socket name. An empty/absent socket ⇒ the LITERAL default
@@ -195,13 +145,6 @@ export const VERIFY_POLL_INTERVAL_MS = 400;
  * Configurable via `--verify-timeout <ms>` on `agent send`.
  */
 export const VERIFY_DEFAULT_TIMEOUT_MS = 6_000;
-const DEFAULT_RUNTIME_RESETS: Record<string, { resetCommand: string }> = {
-  claude: { resetCommand: '/clear' },
-  codex: { resetCommand: '/clear' },
-  opencode: { resetCommand: '/clear' },
-  pi: { resetCommand: '/new' },
-};
-
 export function resolveFleetPaths(mosaicHome = defaultMosaicHome()): FleetPaths {
   return {
     mosaicHome,
@@ -229,20 +172,6 @@ function assertDefaultMosaicHomeForSystemd(mosaicHome: string): void {
   }
 }
 
-export async function loadFleetRoster(path: string): Promise<FleetRoster> {
-  const rawText = await readFile(path, 'utf8');
-  const parsed = parseRosterText(rawText, path);
-  return normalizeRoster(parsed);
-}
-
-export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
-  const agent = roster.agents.find((candidate) => candidate.name === name);
-  if (!agent) {
-    throw new Error(`Agent "${name}" is not in the fleet roster.`);
-  }
-  return agent;
-}
-
 // ---------------------------------------------------------------------------
 // NORTH_STAR — machine-readable fleet planning source + Markdown projection
 //
@@ -556,8 +485,8 @@ function generateAgentEnvValues(
     MOSAIC_AGENT_MODEL: agent.modelHint ?? '',
     MOSAIC_AGENT_REASONING: agent.reasoningLevel ?? '',
     MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy ?? '',
-    MOSAIC_AGENT_WORKDIR: expandHome(workingDirectory),
-    MOSAIC_TMUX_SOCKET: roster.tmux.socketName,
+    MOSAIC_AGENT_WORKDIR: workingDirectory,
+    MOSAIC_TMUX_SOCKET: agent.socket ?? roster.tmux.socketName,
   };
 }
 
@@ -2124,6 +2053,10 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
   // Roster-v2 desired-state mutations belong directly to the fleet control
   // plane; they do not share the root `mosaic agent` gateway-backed surface.
   registerFleetAgentCrudCommands(cmd, deps);
+  registerFleetMigrationCommand(cmd, {
+    ...deps.migrationDeps,
+    mosaicHome: deps.mosaicHome,
+  });
   registerFleetReconcilerCommands(cmd, {
     runner,
     mosaicHome: deps.mosaicHome,
@@ -2157,14 +2090,11 @@ export function registerFleetAgentCommands(
     });
 
   agentCommand
-    .command('comms-block <role>')
-    .description(
-      "Print the Fleet Comms cheat-sheet for a roster role (preview a peer's peer-reach view)",
-    )
-    .option('--host <host>', 'Override the fleet host (preview a cross-host peer view)')
-    .action((role: string, opts: { host?: string }) => {
+    .command('comms-block <exact-member>')
+    .description('Print the Fleet Comms contract for one exact roster member')
+    .action((exactMember: string) => {
       const mosaicHome = resolveMosaicHomeFromCommand(agentCommand, deps.mosaicHome);
-      const res = resolveCommsBlock(mosaicHome, role, opts.host);
+      const res = resolveCommsBlock(mosaicHome, exactMember);
       if (!res.ok) {
         console.error(`[mosaic] comms-block: ${res.error}`);
         process.exitCode = 1;
@@ -2490,253 +2420,6 @@ function resolveMosaicHomeFromCommand(command: Command, override?: string): stri
   return opts.mosaicHome ?? override ?? defaultMosaicHome();
 }
 
-function parseRosterText(text: string, path: string): RawFleetRoster {
-  const trimmed = text.trim();
-  if (path.endsWith('.json')) {
-    return JSON.parse(trimmed) as RawFleetRoster;
-  }
-  return YAML.parse(trimmed) as RawFleetRoster;
-}
-
-function normalizeRoster(raw: RawFleetRoster): FleetRoster {
-  assertObject(raw, 'Fleet roster');
-  assertKnownKeys(raw, 'Fleet roster', [
-    'version',
-    'transport',
-    'tmux',
-    'defaults',
-    'runtimes',
-    'agents',
-  ]);
-  if (raw.tmux !== undefined) {
-    assertObject(raw.tmux, 'Fleet roster tmux');
-    assertKnownKeys(raw.tmux, 'Fleet roster tmux', [
-      'socket_name',
-      'socketName',
-      'holder_session',
-      'holderSession',
-    ]);
-  }
-  if (raw.defaults !== undefined) {
-    assertObject(raw.defaults, 'Fleet roster defaults');
-    assertKnownKeys(raw.defaults, 'Fleet roster defaults', [
-      'working_directory',
-      'workingDirectory',
-    ]);
-  }
-  if (raw.runtimes !== undefined) {
-    assertObject(raw.runtimes, 'Fleet roster runtimes');
-    for (const [runtime, config] of Object.entries(raw.runtimes)) {
-      assertObject(config, `Fleet roster runtime "${runtime}"`);
-      assertKnownKeys(config, `Fleet roster runtime "${runtime}"`, [
-        'reset_command',
-        'resetCommand',
-      ]);
-    }
-  }
-  if (raw.version !== 1) {
-    throw new Error('Fleet roster version must be 1.');
-  }
-  if (raw.transport !== 'tmux') {
-    throw new Error('Fleet roster transport must be "tmux".');
-  }
-  if (!Array.isArray(raw.agents) || raw.agents.length === 0) {
-    throw new Error('Fleet roster must define at least one agent.');
-  }
-
-  const agents = raw.agents.map(normalizeAgent);
-  assertUniqueAgentNames(agents);
-
-  return {
-    version: 1,
-    transport: 'tmux',
-    tmux: {
-      // Absent socket_name ⇒ '' (the literal default tmux socket, no -L) — NOT
-      // mosaic-fleet. Shipped presets set socket_name explicitly, so they are
-      // unaffected; only socket-less rosters get default-socket behavior.
-      socketName: stringValue(
-        raw.tmux?.socket_name ?? raw.tmux?.socketName,
-        '',
-        'Fleet roster tmux socket_name',
-      ),
-      holderSession: stringValue(
-        raw.tmux?.holder_session ?? raw.tmux?.holderSession,
-        DEFAULT_HOLDER_SESSION,
-        'Fleet roster tmux holder_session',
-      ),
-    },
-    defaults: {
-      workingDirectory: stringValue(
-        raw.defaults?.working_directory ?? raw.defaults?.workingDirectory,
-        DEFAULT_WORKING_DIRECTORY,
-        'Fleet roster defaults working_directory',
-      ),
-    },
-    runtimes: normalizeRuntimes(raw.runtimes as RawFleetRoster['runtimes']),
-    agents,
-  };
-}
-
-function normalizeAgent(raw: NonNullable<RawFleetRoster['agents']>[number]): FleetAgent {
-  assertObject(raw, 'Fleet roster agent');
-  assertKnownKeys(raw, 'Fleet roster agent', [
-    'name',
-    'alias',
-    'provider',
-    'runtime',
-    'class',
-    'working_directory',
-    'workingDirectory',
-    'model_hint',
-    'modelHint',
-    'reasoning_level',
-    'reasoningLevel',
-    'tool_policy',
-    'toolPolicy',
-    'persistent_persona',
-    'persistentPersona',
-    'reset_between_tasks',
-    'resetBetweenTasks',
-    'kickstart_template',
-    'kickstartTemplate',
-  ]);
-  const name = stringValue(raw.name, '', 'Fleet roster agent name');
-  const runtime = stringValue(
-    raw.runtime,
-    '',
-    `Fleet roster agent "${name || '<unknown>'}" runtime`,
-  );
-  if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
-    throw new Error(`Invalid fleet agent name: ${name || '<empty>'}`);
-  }
-  if (!runtime) {
-    throw new Error(`Fleet agent "${name}" must define a runtime.`);
-  }
-  return {
-    name,
-    alias: optionalString(raw.alias, `Fleet roster agent "${name}" alias`),
-    provider: optionalString(raw.provider, `Fleet roster agent "${name}" provider`),
-    runtime,
-    className: stringValue(raw.class, 'worker', `Fleet roster agent "${name}" class`),
-    workingDirectory: optionalString(
-      raw.working_directory ?? raw.workingDirectory,
-      `Fleet roster agent "${name}" working_directory`,
-    ),
-    modelHint: optionalString(
-      raw.model_hint ?? raw.modelHint,
-      `Fleet roster agent "${name}" model_hint`,
-    ),
-    reasoningLevel: optionalString(
-      raw.reasoning_level ?? raw.reasoningLevel,
-      `Fleet roster agent "${name}" reasoning_level`,
-    ),
-    toolPolicy: optionalString(
-      raw.tool_policy ?? raw.toolPolicy,
-      `Fleet roster agent "${name}" tool_policy`,
-    ),
-    persistentPersona: optionalBooleanOrString(
-      raw.persistent_persona ?? raw.persistentPersona,
-      `Fleet roster agent "${name}" persistent_persona`,
-    ),
-    resetBetweenTasks: optionalBoolean(
-      raw.reset_between_tasks ?? raw.resetBetweenTasks,
-      `Fleet roster agent "${name}" reset_between_tasks`,
-    ),
-    kickstartTemplate: optionalString(
-      raw.kickstart_template ?? raw.kickstartTemplate,
-      `Fleet roster agent "${name}" kickstart_template`,
-    ),
-  };
-}
-
-function normalizeRuntimes(
-  raw: RawFleetRoster['runtimes'] | undefined,
-): Record<string, { resetCommand: string }> {
-  const result: Record<string, { resetCommand: string }> = { ...DEFAULT_RUNTIME_RESETS };
-  for (const [runtime, config] of Object.entries(raw ?? {})) {
-    result[runtime] = {
-      resetCommand: stringValue(
-        config.reset_command ?? config.resetCommand,
-        '/clear',
-        `Fleet roster runtime "${runtime}" reset_command`,
-      ),
-    };
-  }
-  return result;
-}
-
-function assertObject(value: unknown, label: string): asserts value is Record<string, unknown> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${label} must be an object.`);
-  }
-}
-
-function assertKnownKeys(
-  value: Record<string, unknown>,
-  label: string,
-  allowedKeys: readonly string[],
-): void {
-  const allowed = new Set(allowedKeys);
-  const unknownKeys = Object.keys(value).filter((key) => !allowed.has(key));
-  if (unknownKeys.length > 0) {
-    throw new Error(`${label} has unknown field(s): ${unknownKeys.join(', ')}.`);
-  }
-}
-
-function assertUniqueAgentNames(agents: FleetAgent[]): void {
-  const seen = new Set<string>();
-  for (const agent of agents) {
-    if (seen.has(agent.name)) {
-      throw new Error(`Fleet roster has duplicate agent name: ${agent.name}.`);
-    }
-    seen.add(agent.name);
-  }
-}
-
-function stringValue(value: unknown, fallback = '', label = 'Value'): string {
-  if (value === undefined) {
-    return fallback;
-  }
-  if (typeof value !== 'string') {
-    throw new Error(`${label} must be a string.`);
-  }
-  return value;
-}
-
-function optionalString(value: unknown, label = 'Value'): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  if (typeof value !== 'string') {
-    throw new Error(`${label} must be a string.`);
-  }
-  return value;
-}
-
-function optionalBoolean(value: unknown, label = 'Value'): boolean | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  if (typeof value !== 'boolean') {
-    throw new Error(`${label} must be a boolean.`);
-  }
-  return value;
-}
-
-function optionalBooleanOrString(value: unknown, label = 'Value'): boolean | string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  if (typeof value !== 'boolean' && typeof value !== 'string') {
-    throw new Error(`${label} must be a boolean or string.`);
-  }
-  return value;
-}
-
-function expandHome(path: string): string {
-  return path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
-}
-
 async function stopFleetBestEffort(runner: CommandRunner, agentNames: string[]): Promise<void> {
   const failures: string[] = [];
   for (const agentName of agentNames) {
@@ -2889,6 +2572,23 @@ export function removeAgentFromRoster(roster: FleetRoster, name: string): FleetR
   };
 }
 
+function serializeConnector(
+  connector: NonNullable<FleetRoster['connector']>,
+): Record<string, unknown> {
+  if (connector.kind === 'tmux') return { kind: 'tmux' };
+  if (connector.kind === 'discord') {
+    return { kind: 'discord', discord: { channel_id: connector.discord.channelId } };
+  }
+  return {
+    kind: 'matrix',
+    matrix: {
+      homeserver_url: connector.matrix.homeserverUrl,
+      user_id: connector.matrix.userId,
+      room_id: connector.matrix.roomId,
+    },
+  };
+}
+
 /**
  * Serialize a FleetRoster to YAML text (snake_case keys).
  * The output is parseable by loadFleetRoster.
@@ -2906,6 +2606,15 @@ export function serializeRosterToYaml(roster: FleetRoster): string {
     if (agent.provider !== undefined) {
       raw['provider'] = agent.provider;
     }
+    if (agent.host !== undefined) {
+      raw['host'] = agent.host;
+    }
+    if (agent.ssh !== undefined) {
+      raw['ssh'] = agent.ssh;
+    }
+    if (agent.socket !== undefined) {
+      raw['socket'] = agent.socket;
+    }
     if (agent.workingDirectory !== undefined) {
       raw['working_directory'] = agent.workingDirectory;
     }
@@ -2947,6 +2656,7 @@ export function serializeRosterToYaml(roster: FleetRoster): string {
     },
     runtimes,
     agents,
+    ...(roster.connector ? { connector: serializeConnector(roster.connector) } : {}),
   };
 
   return YAML.stringify(raw);
@@ -3093,6 +2803,5 @@ export async function resolveRosterPath(
   if (await canRead(yamlPath)) {
     return yamlPath;
   }
-  const jsonPath = join(mosaicHome, 'fleet', 'roster.json');
-  return jsonPath;
+  return resolveInstalledFleetRosterPath(mosaicHome);
 }

packages/mosaic/src/commands/launch.ts

@@ -19,10 +19,17 @@ import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import type { Command } from 'commander';
-import { readFleetCommsBlock } from '../fleet/comms-onboarding.js';
+import {
+  buildResolvedFleetCommsBlock,
+  renderToolsContractStatus,
+  resolveFleetIdentity,
+} from '../fleet/comms-onboarding.js';
+import { readRegularFileSecure } from '../fleet/secure-file.js';
 import { readPersonaContractBlock } from '../fleet/persona-contract.js';
+import { canonicalizeRoleClass } from './fleet-personas.js';
 
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+const MAX_INSTALLED_TOOLS_BYTES = 256 * 1024;
 
 type RuntimeName = 'claude' | 'codex' | 'opencode' | 'pi';
 
@@ -185,6 +192,17 @@ function readOptional(path: string): string {
   }
 }
 
+function readInstalledToolsSecure(mosaicHome: string): string {
+  try {
+    return readRegularFileSecure(join(mosaicHome, 'TOOLS.md'), {
+      root: mosaicHome,
+      maxBytes: MAX_INSTALLED_TOOLS_BYTES,
+    }).content.toString('utf8');
+  } catch {
+    return '';
+  }
+}
+
 function readJson(path: string): Record<string, unknown> | null {
   try {
     return JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown>;
@@ -361,9 +379,25 @@ For required push/merge/issue-close/release actions, execute without routine con
     parts.push('\n\n## Operator Overlay (USER.local.md)\n\n' + userLocal);
   }
 
+  const fleetIdentity = resolveFleetIdentity(mosaicHome, process.env['MOSAIC_AGENT_NAME']);
+  if (!fleetIdentity.ok) {
+    throw new Error(`Fleet communications contract unavailable: ${fleetIdentity.error}`);
+  }
+  const canonicalMember = fleetIdentity.identity?.member;
+  if (canonicalMember && process.env['MOSAIC_AGENT_CLASS']?.trim()) {
+    const ambientClass = canonicalizeRoleClass(process.env['MOSAIC_AGENT_CLASS']).canonicalClass;
+    if (ambientClass !== canonicalMember.className) {
+      throw new Error(
+        `Ambient MOSAIC_AGENT_CLASS resolves to "${ambientClass}" but canonical roster member "${canonicalMember.name}" resolves to "${canonicalMember.className}". Refusing split identity authority.`,
+      );
+    }
+  }
+
   // TOOLS.md
-  const tools = readOptional(join(mosaicHome, 'TOOLS.md'));
+  const tools = readInstalledToolsSecure(mosaicHome);
   if (tools) parts.push('\n\n# Machine Tools\n\n' + tools);
+  const toolsContractStatus = renderToolsContractStatus(mosaicHome);
+  if (toolsContractStatus) parts.push('\n\n' + toolsContractStatus);
 
   // Operator overlays whose base layers are load-on-demand (SOUL, STANDARDS):
   // inject only the small `.local` delta by value so the customization reaches
@@ -385,24 +419,23 @@ For required push/merge/issue-close/release actions, execute without routine con
   // Runtime-specific contract
   parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
 
-  // Persona contract (A3b): when this agent was spawned with a class
-  // (MOSAIC_AGENT_CLASS, exported into the pane env by A3a), inject its resolved
-  // role contract so its identity (mandate + boundaries) is resident from the
-  // first turn. Override-aware via the persona resolver: a user-customized
-  // persona in fleet/roles.local/ wins over the baseline (AC-NS-7 launch proof).
-  // Placed BEFORE fleet comms: identity first, then how-to-reach-peers. No-ops
-  // silently when the class is unset/unknown (mirrors the comms block).
-  const persona = readPersonaContractBlock(mosaicHome, process.env['MOSAIC_AGENT_CLASS']);
+  // Fleet launches derive every identity projection from the one canonical roster
+  // member resolved above. Non-fleet launches retain the legacy ambient persona
+  // and tool-policy behavior.
+  const personaClass = canonicalMember?.className ?? process.env['MOSAIC_AGENT_CLASS'];
+  const persona = readPersonaContractBlock(mosaicHome, personaClass);
   if (persona) parts.push('\n\n' + persona);
 
-  const toolPolicy = readFleetToolPolicyBlock(process.env['MOSAIC_AGENT_TOOL_POLICY']);
+  const toolPolicyName = canonicalMember
+    ? canonicalMember.toolPolicy
+    : process.env['MOSAIC_AGENT_TOOL_POLICY'];
+  const toolPolicy = readFleetToolPolicyBlock(toolPolicyName);
   if (toolPolicy) parts.push('\n\n' + toolPolicy);
 
-  // Fleet onboarding: when this is a spawned fleet agent (MOSAIC_AGENT_NAME set
-  // and present in the roster), inject a comms cheat-sheet + peer roster so it
-  // knows how to reach the orchestrator and its peers from its first turn.
-  const fleetComms = readFleetCommsBlock(mosaicHome, process.env['MOSAIC_AGENT_NAME']);
-  if (fleetComms) parts.push('\n\n' + fleetComms);
+  if (fleetIdentity.identity) {
+    const fleetComms = buildResolvedFleetCommsBlock(fleetIdentity.identity);
+    if (fleetComms) parts.push('\n\n' + fleetComms);
+  }
 
   return parts.join('\n');
 }

packages/mosaic/src/config/file-adapter.test.ts

@@ -1,9 +1,22 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  readFileSync,
+  existsSync,
+  copyFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { FileConfigAdapter, DEFAULT_SEED_FILES } from './file-adapter.js';
 
+// The real shipping manifest — the fixture uses it verbatim so these tests
+// exercise production ownership resolution, not a synthetic copy (#791).
+const REAL_FRAMEWORK_ROOT = fileURLToPath(new URL('../../framework', import.meta.url));
+
 /**
  * Regression tests for the `FileConfigAdapter.syncFramework` seed behavior.
  *
@@ -34,11 +47,21 @@ function makeFixture(): { sourceDir: string; mosaicHome: string; defaultsDir: st
   mkdirSync(defaultsDir, { recursive: true });
   mkdirSync(mosaicHome, { recursive: true });
 
+  // #791: syncFramework resolves ownership from the shared manifest under the
+  // source dir. Seed the real one so keep-mode syncs behave as in production.
+  copyFileSync(
+    join(REAL_FRAMEWORK_ROOT, 'framework-manifest.txt'),
+    join(sourceDir, 'framework-manifest.txt'),
+  );
+
   // Framework-contract defaults we expect the wizard to seed.
   writeFileSync(join(defaultsDir, 'CONSTITUTION.md'), '# CONSTITUTION default\n');
   writeFileSync(join(defaultsDir, 'AGENTS.md'), '# AGENTS default\n');
   writeFileSync(join(defaultsDir, 'STANDARDS.md'), '# STANDARDS default\n');
-  writeFileSync(join(defaultsDir, 'TOOLS.md'), '# TOOLS default\n');
+  writeFileSync(
+    join(defaultsDir, 'TOOLS.md'),
+    '# TOOLS default\n\n<!-- fleet-comms-contract: 1 -->\n',
+  );
 
   // Non-contract files we must NOT seed on first install.
   writeFileSync(join(defaultsDir, 'SOUL.md'), '# SOUL default (should not be seeded)\n');
@@ -71,9 +94,8 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
     for (const name of DEFAULT_SEED_FILES) {
       expect(existsSync(join(fixture.mosaicHome, name))).toBe(true);
     }
-    expect(readFileSync(join(fixture.mosaicHome, 'TOOLS.md'), 'utf-8')).toContain(
-      '# TOOLS default',
-    );
+    const sourceTools = readFileSync(join(fixture.defaultsDir, 'TOOLS.md'), 'utf-8');
+    expect(readFileSync(join(fixture.mosaicHome, 'TOOLS.md'), 'utf-8')).toBe(sourceTools);
   });
 
   it('does NOT seed SOUL.md or USER.md from defaults/ (wizard stages own those)', async () => {
@@ -100,9 +122,10 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
   });
 
   it('overwrites framework-owned files (backup-once) but preserves user-seeded files', async () => {
-    // Plant a root-level AGENTS.md in sourceDir so syncDirectory's preserve is exercised.
-    writeFileSync(join(fixture.sourceDir, 'AGENTS.md'), '# shipped AGENTS from source root\n');
-
+    // Contract files (CONSTITUTION/AGENTS/STANDARDS) ship only under defaults/ —
+    // reconcile_framework_files is their sole writer (backup-once). The bulk
+    // sync never sees a root-level copy, so a user's edited root file is backed
+    // up, not silently clobbered, on upgrade.
     writeFileSync(join(fixture.mosaicHome, 'TOOLS.md'), '# user-customized TOOLS\n');
     writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n');
 
@@ -153,17 +176,20 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
     expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS default\n');
   });
 
-  it('preserves user fleet data (roster.yaml, agents/, run/) through a keep-mode sync', async () => {
-    // Regression for the roster-loss bug (#631): user-authored fleet files must
+  it('preserves user fleet data (YAML/JSON rosters, agents/, run/) through a keep-mode sync', async () => {
+    // Regression for roster loss (#631/#766): user-authored fleet files must
     // survive the framework re-seed that `mosaic update` runs.
     mkdirSync(join(fixture.mosaicHome, 'fleet', 'run'), { recursive: true });
     mkdirSync(join(fixture.mosaicHome, 'fleet', 'agents'), { recursive: true });
     writeFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'version: 1\nMINE\n');
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'roster.json'), '{"mine":true}\n');
     writeFileSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'), 'ts=x\n');
     writeFileSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'), 'X=1\n');
-    // The framework ships fleet/examples — it should still seed/refresh.
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'roster.schema.json'), '{"stale":true}\n');
+    // The framework ships fleet/examples and roster.schema.json — both refresh.
     mkdirSync(join(fixture.sourceDir, 'fleet', 'examples'), { recursive: true });
     writeFileSync(join(fixture.sourceDir, 'fleet', 'examples', 'general.yaml'), '# preset\n');
+    writeFileSync(join(fixture.sourceDir, 'fleet', 'roster.schema.json'), '{"fresh":true}\n');
 
     const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
     await adapter.syncFramework('keep');
@@ -171,10 +197,16 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
     expect(readFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'utf-8')).toBe(
       'version: 1\nMINE\n',
     );
+    expect(readFileSync(join(fixture.mosaicHome, 'fleet', 'roster.json'), 'utf-8')).toBe(
+      '{"mine":true}\n',
+    );
     expect(existsSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'))).toBe(true);
     expect(existsSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'))).toBe(true);
-    // framework-owned fleet/examples is seeded
+    // Framework-owned fleet assets are refreshed; unrelated user YAML is not preserved.
     expect(existsSync(join(fixture.mosaicHome, 'fleet', 'examples', 'general.yaml'))).toBe(true);
+    expect(readFileSync(join(fixture.mosaicHome, 'fleet', 'roster.schema.json'), 'utf-8')).toBe(
+      '{"fresh":true}\n',
+    );
   });
 
   it('is a no-op for seeding when defaults/ dir does not exist', async () => {

packages/mosaic/src/config/file-adapter.ts

@@ -34,6 +34,7 @@ import {
   buildToolsTemplateVars,
 } from '../template/builders.js';
 import { atomicWrite, backupFile, syncDirectory } from '../platform/file-ops.js';
+import { loadManifest, resolveOwnership } from '../framework/manifest.js';
 
 /**
  * Parse a SoulConfig from an existing SOUL.md file.
@@ -155,37 +156,22 @@ export class FileConfigAdapter implements ConfigService {
   }
 
   async syncFramework(action: InstallAction): Promise<void> {
-    // Must match PRESERVE_PATHS in packages/mosaic/framework/install.sh so
-    // the bash and TS install paths have the same upgrade-preservation
-    // semantics. Contract files (AGENTS.md, STANDARDS.md, TOOLS.md) are
-    // seeded from defaults/ on first install and preserved thereafter;
-    // identity files (SOUL.md, USER.md) are generated by wizard stages and
-    // must never be touched by the framework sync.
-    const preservePaths =
-      action === 'keep' || action === 'reconfigure'
-        ? [
-            'CONSTITUTION.md',
-            'AGENTS.md',
-            'SOUL.md',
-            'USER.md',
-            'TOOLS.md',
-            'STANDARDS.md',
-            'memory',
-            'sources',
-            'credentials',
-            // User-authored fleet data MUST survive `mosaic update`'s re-seed.
-            // The framework seeds only fleet/examples + fleet/roles +
-            // fleet/roster.schema.json; the operator's roster, per-agent env, and
-            // heartbeat run dir stay user-owned. (Mirror of install.sh PRESERVE_PATHS.)
-            'fleet/*.yaml',
-            'fleet/agents',
-            'fleet/run',
-          ]
-        : [];
+    // #791: ownership is derived from the shared framework manifest
+    // (packages/mosaic/framework/framework-manifest.txt) — the SAME file the
+    // bash installer reads — so the TS and bash paths can never drift. On an
+    // upgrade (keep/reconfigure) the sync must NEVER write an operator-owned
+    // path: every operator file, and any path the manifest never anticipated
+    // (which resolves to operator by the fail-safe default), is left untouched.
+    // A fresh install ('overwrite'/'reconfigure' onto an empty home) seeds the
+    // full tree, so the guard applies only when preserving an existing home.
+    const guardOwnership = action === 'keep' || action === 'reconfigure';
+    const manifest = guardOwnership ? loadManifest(this.sourceDir) : undefined;
 
     syncDirectory(this.sourceDir, this.mosaicHome, {
-      preserve: preservePaths,
       excludeGit: true,
+      isOperatorOwned: manifest
+        ? (relPath) => resolveOwnership(manifest, relPath) === 'operator'
+        : undefined,
     });
 
     // Reconcile framework-contract files from framework/defaults/ into the mosaic

packages/mosaic/src/fleet/comms-onboarding.spec.ts

@@ -1,30 +1,43 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import {
+  chmodSync,
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  readFileSync,
+  symlinkSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { parseFleetRosterV1, type FleetRoster, type FleetAgent } from './fleet-roster-v1.js';
 import {
-  parseRosterAgents,
   buildFleetCommsBlock,
   renderPeerReach,
   readFleetCommsBlock,
   resolveCommsBlock,
-  type CommsPeer,
+  resolvePeerCommand,
+  renderToolsContractStatus,
 } from './comms-onboarding.js';
 
 const ROSTER = [
   'version: 1',
   'transport: tmux',
+  'tmux:',
+  '  socket_name: mosaic-fleet',
   'agents:',
   '  - name: orchestrator',
   '    runtime: claude',
   '    class: orchestrator',
+  '    host: w-jarvis',
   '  - name: enhancer',
   '    runtime: claude',
   '    class: enhancer',
+  '    host: w-jarvis',
   '  - name: coder0',
   '    runtime: pi',
   '    class: implementer',
-  '  # a manually-listed cross-host peer (pre-federation stopgap)',
+  '    host: w-jarvis',
   '  - name: coder0-0',
   '    runtime: claude',
   '    class: implementer',
@@ -33,206 +46,687 @@ const ROSTER = [
   '',
 ].join('\n');
 
-describe('parseRosterAgents', () => {
-  it('parses name + class + optional host/ssh', () => {
-    const peers = parseRosterAgents(ROSTER);
-    expect(peers.map((p) => p.name)).toEqual(['orchestrator', 'enhancer', 'coder0', 'coder0-0']);
-    expect(peers.find((p) => p.name === 'coder0')).toMatchObject({ className: 'implementer' });
-    expect(peers.find((p) => p.name === 'coder0-0')).toMatchObject({
-      className: 'implementer',
+function roster(source = ROSTER): FleetRoster {
+  return parseFleetRosterV1(source, 'yaml');
+}
+
+describe('shared fleet roster v1 resolver', () => {
+  it('resolves comms fields and the global socket through the canonical roster contract', () => {
+    const resolved = roster();
+    expect(resolved.tmux.socketName).toBe('mosaic-fleet');
+    expect(resolved.agents.find((agent) => agent.name === 'coder0-0')).toMatchObject({
+      className: 'code',
       host: '10.1.10.37',
       ssh: 'jwoltje@10.1.10.37',
     });
-    // local agents have no host/ssh
-    expect(peers.find((p) => p.name === 'orchestrator')!.host).toBeUndefined();
   });
 
-  it('parses an optional per-agent socket', () => {
-    const peers = parseRosterAgents(
-      ['agents:', '  - name: a', '    class: worker', '    socket: mosaic-fleet'].join('\n'),
+  it('rejects unknown fields instead of leniently constructing a second roster view', () => {
+    expect(() => parseFleetRosterV1(`${ROSTER}\nunknown: value\n`, 'yaml')).toThrow(
+      /unknown field/i,
     );
-    expect(peers[0]).toMatchObject({ name: 'a', socket: 'mosaic-fleet' });
   });
 
-  it('stops at the next top-level key', () => {
-    const peers = parseRosterAgents(
-      ['agents:', '  - name: a', '    class: worker', 'defaults:', '  working_directory: ~'].join(
-        '\n',
+  it('rejects an unsupported independent per-agent socket instead of targeting a nonexistent session', () => {
+    expect(() =>
+      roster(
+        ROSTER.replace(
+          '    host: w-jarvis\n  - name: coder0',
+          '    host: w-jarvis\n    socket: other-socket\n  - name: coder0',
+        ),
       ),
-    );
-    expect(peers.map((p) => p.name)).toEqual(['a']);
+    ).toThrow(/independent per-agent sockets are not supported/i);
   });
+
+  it('rejects unsafe operational targeting values', () => {
+    expect(() =>
+      roster(ROSTER.replace('    ssh: jwoltje@10.1.10.37', '    ssh: host;touch-owned')),
+    ).toThrow(/unsupported targeting characters/i);
+  });
+
+  it('normalizes matching connector settings for YAML and JSON rosters', () => {
+    const yamlSource = `${ROSTER}connector:\n  kind: discord\n  discord:\n    channel_id: "123"\n`;
+    const jsonSource = JSON.stringify({
+      version: 1,
+      transport: 'tmux',
+      agents: [{ name: 'a', runtime: 'claude', class: 'worker' }],
+      connector: {
+        kind: 'matrix',
+        matrix: {
+          homeserver_url: 'https://matrix.example',
+          user_id: '@a:example',
+          room_id: '!room:example',
+        },
+      },
+    });
+
+    expect(parseFleetRosterV1(yamlSource, 'yaml').connector).toEqual({
+      kind: 'discord',
+      discord: { channelId: '123' },
+    });
+    expect(parseFleetRosterV1(jsonSource, 'json').connector).toEqual({
+      kind: 'matrix',
+      matrix: {
+        homeserverUrl: 'https://matrix.example',
+        userId: '@a:example',
+        roomId: '!room:example',
+      },
+    });
+  });
+
+  it.each([
+    ['discord channel_id', { kind: 'discord', discord: { channel_id: '' } }],
+    ['discord channel_id whitespace', { kind: 'discord', discord: { channel_id: '   ' } }],
+    [
+      'matrix homeserver_url',
+      {
+        kind: 'matrix',
+        matrix: { homeserver_url: '', user_id: '@a:example', room_id: '!room:example' },
+      },
+    ],
+    [
+      'matrix homeserver_url whitespace',
+      {
+        kind: 'matrix',
+        matrix: { homeserver_url: '\t', user_id: '@a:example', room_id: '!room:example' },
+      },
+    ],
+    [
+      'matrix user_id',
+      {
+        kind: 'matrix',
+        matrix: {
+          homeserver_url: 'https://matrix.example',
+          user_id: '',
+          room_id: '!room:example',
+        },
+      },
+    ],
+    [
+      'matrix user_id whitespace',
+      {
+        kind: 'matrix',
+        matrix: {
+          homeserver_url: 'https://matrix.example',
+          user_id: '  ',
+          room_id: '!room:example',
+        },
+      },
+    ],
+    [
+      'matrix room_id',
+      {
+        kind: 'matrix',
+        matrix: {
+          homeserver_url: 'https://matrix.example',
+          user_id: '@a:example',
+          room_id: '',
+        },
+      },
+    ],
+    [
+      'matrix room_id whitespace',
+      {
+        kind: 'matrix',
+        matrix: {
+          homeserver_url: 'https://matrix.example',
+          user_id: '@a:example',
+          room_id: '\n',
+        },
+      },
+    ],
+  ])(
+    'rejects empty or whitespace-only parser-required connector string: %s',
+    (_label, connector) => {
+      expect(() =>
+        parseFleetRosterV1(
+          JSON.stringify({
+            version: 1,
+            transport: 'tmux',
+            agents: [{ name: 'a', runtime: 'claude', class: 'worker' }],
+            connector,
+          }),
+          'json',
+        ),
+      ).toThrow(/required/i);
+    },
+  );
+
+  it.each([
+    ['tmux with discord settings', { kind: 'tmux', discord: { channel_id: '123' } }],
+    ['discord without discord settings', { kind: 'discord' }],
+    [
+      'discord with matrix settings',
+      { kind: 'discord', discord: { channel_id: '123' }, matrix: {} },
+    ],
+    ['matrix without matrix settings', { kind: 'matrix' }],
+    [
+      'matrix with discord settings',
+      {
+        kind: 'matrix',
+        matrix: {
+          homeserver_url: 'https://matrix.example',
+          user_id: '@a:example',
+          room_id: '!room:example',
+        },
+        discord: { channel_id: '123' },
+      },
+    ],
+  ])('rejects connector kind/settings mismatch: %s', (_label, connector) => {
+    expect(() =>
+      parseFleetRosterV1(
+        JSON.stringify({
+          version: 1,
+          transport: 'tmux',
+          agents: [{ name: 'a', runtime: 'claude', class: 'worker' }],
+          connector,
+        }),
+        'json',
+      ),
+    ).toThrow();
+  });
+
+  it.each([
+    ['tmux socket', ['tmux', 'socket_name'], ['tmux', 'socketName'], 'same', 'different'],
+    ['tmux holder', ['tmux', 'holder_session'], ['tmux', 'holderSession'], 'same', 'different'],
+    [
+      'defaults working directory',
+      ['defaults', 'working_directory'],
+      ['defaults', 'workingDirectory'],
+      'same',
+      'different',
+    ],
+    [
+      'runtime reset command',
+      ['runtimes', 'claude', 'reset_command'],
+      ['runtimes', 'claude', 'resetCommand'],
+      'same',
+      'different',
+    ],
+    [
+      'agent working directory',
+      ['agents', 0, 'working_directory'],
+      ['agents', 0, 'workingDirectory'],
+      'same',
+      'different',
+    ],
+    [
+      'agent model hint',
+      ['agents', 0, 'model_hint'],
+      ['agents', 0, 'modelHint'],
+      'same',
+      'different',
+    ],
+    [
+      'agent reasoning level',
+      ['agents', 0, 'reasoning_level'],
+      ['agents', 0, 'reasoningLevel'],
+      'same',
+      'different',
+    ],
+    [
+      'agent tool policy',
+      ['agents', 0, 'tool_policy'],
+      ['agents', 0, 'toolPolicy'],
+      'same',
+      'different',
+    ],
+    [
+      'agent persistent persona',
+      ['agents', 0, 'persistent_persona'],
+      ['agents', 0, 'persistentPersona'],
+      true,
+      false,
+    ],
+    [
+      'agent reset between tasks',
+      ['agents', 0, 'reset_between_tasks'],
+      ['agents', 0, 'resetBetweenTasks'],
+      true,
+      false,
+    ],
+    [
+      'agent kickstart template',
+      ['agents', 0, 'kickstart_template'],
+      ['agents', 0, 'kickstartTemplate'],
+      'same',
+      'different',
+    ],
+  ] as const)(
+    'rejects conflicting %s aliases and accepts identical aliases',
+    (_label, snake, camel, same, different) => {
+      const base: Record<string, unknown> = {
+        version: 1,
+        transport: 'tmux',
+        tmux: {},
+        defaults: {},
+        runtimes: { claude: {} },
+        agents: [{ name: 'a', runtime: 'claude', class: 'worker' }],
+      };
+      const assign = (
+        root: Record<string, unknown>,
+        path: readonly (string | number)[],
+        value: unknown,
+      ) => {
+        let cursor: unknown = root;
+        for (const segment of path.slice(0, -1)) {
+          cursor = (cursor as Record<string | number, unknown>)[segment];
+        }
+        (cursor as Record<string | number, unknown>)[path.at(-1)!] = value;
+      };
+      assign(base, snake, same);
+      assign(base, camel, different);
+      expect(() => parseFleetRosterV1(JSON.stringify(base), 'json')).toThrow(
+        /aliases .* conflict/i,
+      );
+      assign(base, camel, same);
+      expect(() => parseFleetRosterV1(JSON.stringify(base), 'json')).not.toThrow();
+    },
+  );
 });
 
-describe('renderPeerReach — same-host vs cross-host', () => {
+describe('renderPeerReach — exact same-host/cross-host/socket targeting', () => {
   const send = '/home/u/.config/mosaic/tools/tmux/agent-send.sh';
+  const base: FleetAgent = {
+    name: 'peer',
+    runtime: 'claude',
+    className: 'worker',
+  };
 
-  it('renders the short form for a same-host peer', () => {
-    const peer: CommsPeer = { name: 'enhancer', className: 'enhancer' };
-    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s enhancer -m "…"`);
-  });
-
-  it('renders the -H form for a cross-host peer using ssh', () => {
-    const peer: CommsPeer = {
-      name: 'coder0-0',
-      className: 'implementer',
-      host: '10.1.10.37',
-      ssh: 'jwoltje@10.1.10.37',
-    };
-    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
-      `${send} -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
+  it('renders the global named socket and omits -H for a same-host peer', () => {
+    expect(renderPeerReach(base, 'w-jarvis', 'w-jarvis', 'mosaic-fleet', send)).toBe(
+      `${send} -L mosaic-fleet -s peer -m "…"`,
     );
   });
 
-  it('falls back to host when a cross-host peer has no ssh', () => {
-    const peer: CommsPeer = { name: 'x', className: 'worker', host: '10.0.0.9' };
-    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -H 10.0.0.9 -s x -m "…"`);
-  });
-
-  it('treats a peer whose host equals the fleet host as same-host', () => {
-    const peer: CommsPeer = { name: 'y', className: 'worker', host: 'w-jarvis' };
-    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s y -m "…"`);
-  });
-
-  it('emits NO -L for an unset/default socket', () => {
-    const peer: CommsPeer = { name: 'lead', className: 'orchestrator' };
-    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s lead -m "…"`);
-  });
-
-  it('emits -L <socket> for a named socket', () => {
-    const peer: CommsPeer = { name: 'coder0', className: 'implementer', socket: 'mosaic-fleet' };
-    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
-      `${send} -L mosaic-fleet -s coder0 -m "…"`,
-    );
-  });
-
-  it('combines -L (named socket) and -H (cross-host) in order', () => {
-    const peer: CommsPeer = {
+  it('uses only the explicit roster ssh target for a cross-host peer', () => {
+    const peer: FleetAgent = {
+      ...base,
       name: 'coder0-0',
-      className: 'implementer',
       host: '10.1.10.37',
       ssh: 'jwoltje@10.1.10.37',
-      socket: 'mosaic-fleet',
     };
-    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
+    expect(renderPeerReach(peer, 'w-jarvis', 'w-jarvis', 'mosaic-fleet', send)).toBe(
       `${send} -L mosaic-fleet -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
     );
   });
+
+  it('fails closed when a cross-host peer has no explicit roster ssh target', () => {
+    const peer: FleetAgent = { ...base, name: 'x', host: '10.0.0.9' };
+    expect(() => renderPeerReach(peer, 'w-jarvis', 'w-jarvis', 'mosaic-fleet', send)).toThrow(
+      /explicit roster ssh target/i,
+    );
+  });
+
+  it('renders only the fleet-wide supported socket', () => {
+    const peer: FleetAgent = { ...base, socket: 'mosaic-fleet' };
+    expect(renderPeerReach(peer, 'w-jarvis', 'w-jarvis', 'mosaic-fleet', send)).toBe(
+      `${send} -L mosaic-fleet -s peer -m "…"`,
+    );
+  });
+
+  it('resolves hostless peers against the stable fleet-host baseline, not the viewer host', () => {
+    const peer: FleetAgent = { ...base, ssh: 'fleet-user@w-jarvis' };
+    expect(renderPeerReach(peer, 'remote-host', 'w-jarvis', 'mosaic-fleet', send)).toBe(
+      `${send} -L mosaic-fleet -H fleet-user@w-jarvis -s peer -m "…"`,
+    );
+  });
+
+  it('shell-quotes an exact helper path that contains spaces', () => {
+    expect(
+      renderPeerReach(base, 'w-jarvis', 'w-jarvis', 'mosaic-fleet', '/home/test user/send.sh'),
+    ).toBe(`'/home/test user/send.sh' -L mosaic-fleet -s peer -m "…"`);
+  });
+
+  it('omits -L only for the literal default socket', () => {
+    expect(renderPeerReach(base, 'w-jarvis', 'w-jarvis', '', send)).toBe(`${send} -s peer -m "…"`);
+  });
 });
 
 describe('buildFleetCommsBlock', () => {
   const send = '/h/.config/mosaic/tools/tmux/agent-send.sh';
-  const agents = parseRosterAgents(ROSTER);
 
-  it('excludes self, lists peers, flags the orchestrator, and emits both address forms', () => {
+  it('renders authoritative identity, exact rows, generation, and no operational metavariables', () => {
     const block = buildFleetCommsBlock({
       selfName: 'enhancer',
-      agents,
-      fleetHost: 'w-jarvis',
+      roster: roster(),
+      localHost: 'ignored-process-host',
       agentSendPath: send,
     });
+
     expect(block).toContain('# Fleet Comms');
-    expect(block).toContain('You are **enhancer**');
-    // criterion 1: agent's own [host:session] identity
-    expect(block).toContain('`[w-jarvis:enhancer]`');
-    // self excluded
+    expect(block).toContain('Host: `w-jarvis`');
+    expect(block).toContain('Agent/session: `enhancer`');
+    expect(block).toContain('tmux socket: `mosaic-fleet`');
+    expect(block).toContain(`Helper: \`${send}\``);
+    expect(block).toMatch(/Comms generation: `[a-f0-9]{64}`/);
     expect(block).not.toMatch(/\|\s*enhancer\s*\|/);
-    // peers present
-    expect(block).toContain('| orchestrator |');
-    expect(block).toContain('point of contact');
-    // same-host peer short form
-    expect(block).toContain(`${send} -s coder0 -m "…"`);
-    // cross-host peer -H form + host annotation
-    expect(block).toContain(`${send} -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`);
-    expect(block).toContain('host `10.1.10.37`');
-    // conventions
-    expect(block).toContain('FLIP the preamble');
-    expect(block).toContain('ACCEPTED');
+    expect(block).toContain(`${send} -L mosaic-fleet -s orchestrator -m "…"`);
+    expect(block).toContain(`${send} -L mosaic-fleet -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`);
+    expect(block).toContain(`mosaic agent comms-block enhancer`);
+    expect(block).toMatch(/Never invent, substitute, or fuzzy-match/i);
+    expect(block).not.toMatch(
+      /<(?:user@host|src_host|src_session|dst_host|dst_session|target-session)>/,
+    );
+    expect(block).not.toContain('FLIP the preamble');
   });
 
-  it('returns empty when the agent has no peers', () => {
-    expect(
+  it('changes the generation when a rendered peer role changes', () => {
+    const generation = (block: string) => block.match(/Comms generation: `([a-f0-9]{64})`/)?.[1];
+    const before = buildFleetCommsBlock({
+      selfName: 'enhancer',
+      roster: roster(),
+      localHost: 'w-jarvis',
+      agentSendPath: send,
+    });
+    const changedRoster = roster(ROSTER.replace('class: implementer', 'class: reviewer'));
+    const after = buildFleetCommsBlock({
+      selfName: 'enhancer',
+      roster: changedRoster,
+      localHost: 'w-jarvis',
+      agentSendPath: send,
+    });
+    expect(generation(before)).toMatch(/^[a-f0-9]{64}$/);
+    expect(generation(after)).not.toBe(generation(before));
+  });
+
+  it('fails closed when any rendered cross-host row lacks ssh', () => {
+    const bad = roster(ROSTER.replace('    ssh: jwoltje@10.1.10.37\n', ''));
+    expect(() =>
       buildFleetCommsBlock({
-        selfName: 'solo',
-        agents: [{ name: 'solo', className: 'orchestrator' }],
-        fleetHost: 'h',
+        selfName: 'enhancer',
+        roster: bad,
+        localHost: 'w-jarvis',
         agentSendPath: send,
       }),
-    ).toBe('');
+    ).toThrow(/explicit roster ssh target/i);
+  });
+
+  it('still renders authoritative local identity when the agent has no peers', () => {
+    const solo = roster(
+      [
+        'version: 1',
+        'transport: tmux',
+        'agents:',
+        '  - name: solo',
+        '    runtime: claude',
+        '    class: orchestrator',
+      ].join('\n'),
+    );
+    const block = buildFleetCommsBlock({
+      selfName: 'solo',
+      roster: solo,
+      localHost: 'h',
+      agentSendPath: send,
+    });
+    expect(block).toContain('Host: `h`');
+    expect(block).toContain('Agent/session: `solo`');
+    expect(block).toContain('Role/class: `orchestrator`');
+    expect(block).toMatch(/Comms generation: `[a-f0-9]{64}`/);
+    expect(block).toContain('This roster has no peers');
+    expect(block).toContain('## Solo authority boundaries');
+    expect(block).toContain('no peer, orchestrator, or remote communication authority');
+    expect(block).toContain('Do not send, infer a target, or claim fleet coordination');
   });
 });
 
-describe('readFleetCommsBlock — situational (the context a spawned agent gets)', () => {
+describe('resolvePeerCommand', () => {
+  const send = '/h/.config/mosaic/tools/tmux/agent-send.sh';
+
+  it('returns one exact known-peer row', () => {
+    const result = resolvePeerCommand(roster(), 'enhancer', 'coder0-0', 'w-jarvis', send);
+    expect(result.ok).toBe(true);
+    expect(result.command).toContain('-H jwoltje@10.1.10.37 -s coder0-0');
+  });
+
+  it('fails closed for an unknown peer with exact-name discovery guidance', () => {
+    const result = resolvePeerCommand(roster(), 'enhancer', 'invented-host', 'w-jarvis', send);
+    expect(result.ok).toBe(false);
+    expect(result.command).toBe('');
+    expect(result.error).toContain('invented-host');
+    expect(result.error).toContain('orchestrator, coder0, coder0-0');
+    expect(result.error).toContain('mosaic agent comms-block enhancer');
+    expect(result.error).not.toContain('tmux ls');
+  });
+});
+
+describe('readFleetCommsBlock — spawned-agent context', () => {
   let home: string;
   beforeEach(() => {
     home = mkdtempSync(join(tmpdir(), 'mosaic-comms-'));
     mkdirSync(join(home, 'fleet'), { recursive: true });
+    mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
     writeFileSync(join(home, 'fleet', 'roster.yaml'), ROSTER);
+    const helper = join(home, 'tools', 'tmux', 'agent-send.sh');
+    writeFileSync(helper, '#!/bin/sh\n');
+    chmodSync(helper, 0o755);
   });
   afterEach(() => rmSync(home, { recursive: true, force: true }));
 
-  it('builds the cheat-sheet with correct peer addresses for a fleet member', () => {
-    const block = readFleetCommsBlock(home, 'orchestrator', 'w-jarvis');
-    expect(block).toContain('# Fleet Comms');
-    expect(block).toContain('| enhancer |');
-    expect(block).toContain(`${join(home, 'tools', 'tmux', 'agent-send.sh')} -s coder0 -m "…"`);
-    expect(block).toContain('-H jwoltje@10.1.10.37 -s coder0-0');
-    expect(block).not.toMatch(/\|\s*orchestrator\s*\|/); // self excluded
+  it('uses the authoritative self host and global socket from the shared roster resolver', () => {
+    const result = readFleetCommsBlock(home, 'enhancer', 'process-host-must-not-win');
+    expect(result.ok).toBe(true);
+    expect(result.output).toContain('Host: `w-jarvis`');
+    expect(result.output).toContain('tmux socket: `mosaic-fleet`');
+    expect(result.output).toContain('-L mosaic-fleet -s orchestrator');
   });
 
-  it('returns empty when MOSAIC_AGENT_NAME is unset, no roster, or agent not a member', () => {
-    expect(readFleetCommsBlock(home, undefined, 'w-jarvis')).toBe('');
-    expect(readFleetCommsBlock(home, 'stranger', 'w-jarvis')).toBe('');
-    expect(readFleetCommsBlock(mkdtempSync(join(tmpdir(), 'noroster-')), 'orchestrator')).toBe('');
+  it('fails closed for a requested fleet identity that is absent', () => {
+    const result = readFleetCommsBlock(home, 'stranger', 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.output).toBe('');
+    expect(result.error).toContain('Known exact names');
+  });
+
+  it('resolves a supported JSON-only installed roster', () => {
+    rmSync(join(home, 'fleet', 'roster.yaml'));
+    writeFileSync(
+      join(home, 'fleet', 'roster.json'),
+      JSON.stringify({
+        version: 1,
+        transport: 'tmux',
+        tmux: { socket_name: 'mosaic-fleet' },
+        agents: [
+          { name: 'enhancer', runtime: 'claude', class: 'enhancer', host: 'w-jarvis' },
+          { name: 'orchestrator', runtime: 'claude', class: 'orchestrator', host: 'w-jarvis' },
+        ],
+      }),
+    );
+    const result = readFleetCommsBlock(home, 'enhancer', 'process-host-must-not-win');
+    expect(result.ok).toBe(true);
+    expect(result.output).toContain('-L mosaic-fleet -s orchestrator');
+  });
+
+  it('fails closed on a YAML I/O error instead of falling back to JSON', () => {
+    rmSync(join(home, 'fleet', 'roster.yaml'));
+    mkdirSync(join(home, 'fleet', 'roster.yaml'));
+    writeFileSync(
+      join(home, 'fleet', 'roster.json'),
+      JSON.stringify({
+        version: 1,
+        transport: 'tmux',
+        agents: [{ name: 'enhancer', runtime: 'claude', class: 'enhancer' }],
+      }),
+    );
+    const result = readFleetCommsBlock(home, 'enhancer', 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('invalid fleet roster at');
+    expect(result.error).toContain('roster.yaml');
+  });
+
+  it.each([
+    ['missing', () => rmSync(join(home, 'tools', 'tmux', 'agent-send.sh'))],
+    [
+      'directory',
+      () => {
+        rmSync(join(home, 'tools', 'tmux', 'agent-send.sh'));
+        mkdirSync(join(home, 'tools', 'tmux', 'agent-send.sh'));
+      },
+    ],
+    [
+      'symlink',
+      () => {
+        const helper = join(home, 'tools', 'tmux', 'agent-send.sh');
+        rmSync(helper);
+        writeFileSync(join(home, 'real-send.sh'), '#!/bin/sh\n');
+        symlinkSync(join(home, 'real-send.sh'), helper);
+      },
+    ],
+    ['non-executable', () => chmodSync(join(home, 'tools', 'tmux', 'agent-send.sh'), 0o644)],
+  ])('fails closed for a %s helper with deterministic repair guidance', (_case, mutate) => {
+    mutate();
+    const result = readFleetCommsBlock(home, 'enhancer', 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.output).toBe('');
+    expect(result.error).toContain('mosaic update --repair-tools');
+    expect(result.error).toContain('no active context or session was rewritten');
+  });
+
+  it('does not rewrite the roster while resolving context', () => {
+    const path = join(home, 'fleet', 'roster.yaml');
+    const before = readFileSync(path, 'utf8');
+    readFleetCommsBlock(home, 'enhancer', 'w-jarvis');
+    expect(readFileSync(path, 'utf8')).toBe(before);
   });
 });
 
-describe('resolveCommsBlock — `mosaic fleet comms-block <role>` emitter semantics', () => {
-  // The emitter wraps readFleetCommsBlock but must NEVER print an empty string silently:
-  // an unknown role / missing roster has to fail loud (caller maps !ok → stderr + exit 1)
-  // so `mosaic fleet comms-block bogus` is a visible error, not a confusing no-op. The
-  // success path returns the block verbatim for `mosaic fleet comms-block <peer>` previews.
+describe('renderToolsContractStatus — non-mutating install drift', () => {
+  let home: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'mosaic-tools-status-'));
+    mkdirSync(join(home, 'defaults'), { recursive: true });
+    writeFileSync(
+      join(home, 'defaults', 'TOOLS.md'),
+      '# authoritative tools\n<!-- fleet-comms-contract: 1 -->\n',
+    );
+  });
+  afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+  it('uses the supported repair command when installed TOOLS.md is missing', () => {
+    const status = renderToolsContractStatus(home);
+    expect(status).toContain('mosaic update --repair-tools');
+    expect(status).not.toContain('--reseed');
+    expect(status).toContain('authorized operator');
+  });
+
+  it('reports stale preserved content without rewriting it', () => {
+    const path = join(home, 'TOOLS.md');
+    const stale = '# customized tools\n';
+    writeFileSync(path, stale);
+    const status = renderToolsContractStatus(home);
+    expect(status).toContain('fleet-comms-contract: 1');
+    expect(status).toContain('digest-qualified backup');
+    expect(status).toContain('mosaic update --repair-tools');
+    expect(status).toContain('active context was not rewritten');
+    expect(readFileSync(path, 'utf8')).toBe(stale);
+  });
+
+  it('does not accept marker-only customized content as current', () => {
+    const path = join(home, 'TOOLS.md');
+    writeFileSync(path, '<!-- fleet-comms-contract: 1 -->\ncorrupt\n');
+    expect(renderToolsContractStatus(home)).toContain('does not byte-match');
+  });
+
+  it('rejects markerless byte-equal source and installed content', () => {
+    const content = '# markerless but equal\n';
+    writeFileSync(join(home, 'defaults', 'TOOLS.md'), content);
+    writeFileSync(join(home, 'TOOLS.md'), content);
+    const status = renderToolsContractStatus(home);
+    expect(status).toContain('source contract');
+    expect(status).toContain('does not declare the expected');
+  });
+
+  it.each([
+    ['source', join('defaults', 'TOOLS.md')],
+    ['installed', 'TOOLS.md'],
+  ])('rejects a wrong contract version in %s content', (_case, relativePath) => {
+    const current = '# authoritative tools\n<!-- fleet-comms-contract: 1 -->\n';
+    writeFileSync(join(home, 'TOOLS.md'), current);
+    writeFileSync(join(home, 'defaults', 'TOOLS.md'), current);
+    writeFileSync(join(home, relativePath), current.replace('contract: 1', 'contract: 2'));
+    expect(renderToolsContractStatus(home)).not.toBe('');
+  });
+
+  it('treats installed TOOLS.md symlinks as stale without following or rewriting them', () => {
+    const external = join(home, 'external-tools.md');
+    const externalContent = '# external\n<!-- fleet-comms-contract: 1 -->\n';
+    writeFileSync(external, externalContent);
+    symlinkSync(external, join(home, 'TOOLS.md'));
+
+    const status = renderToolsContractStatus(home);
+
+    expect(status).toContain('unavailable');
+    expect(status).toContain('mosaic update --repair-tools');
+    expect(readFileSync(external, 'utf8')).toBe(externalContent);
+  });
+
+  it('treats source TOOLS.md symlinks as unavailable without following them', () => {
+    const external = join(home, 'external-source.md');
+    const content = '# authoritative tools\n<!-- fleet-comms-contract: 1 -->\n';
+    writeFileSync(external, content);
+    rmSync(join(home, 'defaults', 'TOOLS.md'));
+    symlinkSync(external, join(home, 'defaults', 'TOOLS.md'));
+    writeFileSync(join(home, 'TOOLS.md'), content);
+
+    const status = renderToolsContractStatus(home);
+
+    expect(status).toContain('source contract');
+    expect(status).toContain('unavailable');
+    expect(readFileSync(external, 'utf8')).toBe(content);
+  });
+
+  it('accepts byte-equal bounded source and installed contracts', () => {
+    const source = readFileSync(join(home, 'defaults', 'TOOLS.md'), 'utf8');
+    writeFileSync(join(home, 'TOOLS.md'), source);
+    expect(renderToolsContractStatus(home)).toBe('');
+  });
+});
+
+describe('resolveCommsBlock — mosaic agent comms-block', () => {
   let home: string;
   beforeEach(() => {
     home = mkdtempSync(join(tmpdir(), 'mosaic-commsblk-'));
     mkdirSync(join(home, 'fleet'), { recursive: true });
+    mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
     writeFileSync(join(home, 'fleet', 'roster.yaml'), ROSTER);
+    const helper = join(home, 'tools', 'tmux', 'agent-send.sh');
+    writeFileSync(helper, '#!/bin/sh\n');
+    chmodSync(helper, 0o755);
   });
   afterEach(() => rmSync(home, { recursive: true, force: true }));
 
-  it('returns ok + the cheat-sheet for a roster member', () => {
-    const res = resolveCommsBlock(home, 'orchestrator', 'w-jarvis');
-    expect(res.ok).toBe(true);
-    expect(res.output).toContain('# Fleet Comms');
-    expect(res.output).toContain('| enhancer |');
-    expect(res.error).toBeUndefined();
+  it('returns the exact contract for a roster member', () => {
+    const result = resolveCommsBlock(home, 'enhancer');
+    expect(result.ok).toBe(true);
+    expect(result.output).toContain('Host: `w-jarvis`');
+    expect(result.error).toBeUndefined();
   });
 
-  it('fails loud (not ok + error naming the role) for a non-member — never silently empty', () => {
-    const res = resolveCommsBlock(home, 'stranger', 'w-jarvis');
-    expect(res.ok).toBe(false);
-    expect(res.output).toBe('');
-    expect(res.error).toContain('stranger');
+  it('fails loud and lists known exact names for a non-member', () => {
+    const result = resolveCommsBlock(home, 'stranger');
+    expect(result.ok).toBe(false);
+    expect(result.output).toBe('');
+    expect(result.error).toContain('stranger');
+    expect(result.error).toContain('orchestrator');
+    expect(result.error).toContain('enhancer');
   });
 
-  it('fails loud when no roster exists at the mosaic home', () => {
+  it('fails loud when no roster exists', () => {
     const noRoster = mkdtempSync(join(tmpdir(), 'mosaic-noroster-'));
-    const res = resolveCommsBlock(noRoster, 'orchestrator', 'w-jarvis');
-    expect(res.ok).toBe(false);
-    expect(res.error).toBeTruthy();
+    mkdirSync(join(noRoster, 'tools', 'tmux'), { recursive: true });
+    const helper = join(noRoster, 'tools', 'tmux', 'agent-send.sh');
+    writeFileSync(helper, '#!/bin/sh\n');
+    chmodSync(helper, 0o755);
+    const result = resolveCommsBlock(noRoster, 'orchestrator');
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('no fleet roster');
     rmSync(noRoster, { recursive: true, force: true });
   });
 
   it('fails loud for a missing role argument', () => {
-    const res = resolveCommsBlock(home, undefined, 'w-jarvis');
-    expect(res.ok).toBe(false);
-    expect(res.error).toBeTruthy();
-  });
-
-  it('honors a host override so a peer can preview its own cross-host view', () => {
-    // coder0-0 viewing with its own host → its self-identity line uses that host.
-    const res = resolveCommsBlock(home, 'coder0-0', '10.1.10.37');
-    expect(res.ok).toBe(true);
-    expect(res.output).toContain('`[10.1.10.37:coder0-0]`');
+    const result = resolveCommsBlock(home, undefined);
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('requires');
   });
 });

packages/mosaic/src/fleet/comms-onboarding.ts

@@ -1,226 +1,423 @@
 /**
- * Fleet onboarding-injection (#620).
+ * Exact roster-resolved fleet communications contract (#766).
  *
- * Fleet agents are born not knowing how to reach their peers — the root cause of
- * a spawned agent's failed first send. When an agent boots via `mosaic yolo
- * <runtime>` (→ composeContract → system prompt), we append a comms cheat-sheet
- * + peer roster so it can talk to the orchestrator and other agents immediately.
- *
- * Cross-host aware: a peer may carry `host`/`ssh` (a deliberate pre-federation
- * stopgap — manual cross-host listing; federation/W1 auto-discovers later), so a
- * w-jarvis agent is born knowing the exact `-H` command to reach a dragon-lin
- * peer. Same-host peers render the short form.
- *
- * Standalone (no fleet.ts import) to keep launch.ts's prompt path free of the
- * heavy fleet command module. The roster is parsed leniently — the cheat-sheet
- * is best-effort onboarding, never a hard dependency.
+ * The runtime composer and `mosaic fleet` command surface share the canonical
+ * v1 roster resolver. This module never probes tmux, guesses an SSH target, or
+ * mutates an active session.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { homedir, hostname } from 'node:os';
 import { join } from 'node:path';
-
-export interface CommsPeer {
-  name: string;
-  /** Roster `class` (orchestrator | enhancer | implementer | worker | …). */
-  className: string;
-  /** Host the peer runs on; absent ⇒ the fleet host (same host). */
-  host?: string;
-  /** SSH target (user@host) for a cross-host peer; renders the `-H` form. */
-  ssh?: string;
-  /** tmux socket the peer's session lives on; absent ⇒ default socket (no `-L`). */
-  socket?: string;
-}
-
-/**
- * Lenient parse of a fleet `roster.yaml` for agent name/class/host/ssh. Avoids a
- * dependency on the full fleet roster parser; the format is `- name:` list items
- * with `class:`/`host:`/`ssh:` siblings under `agents:`.
- */
-export function parseRosterAgents(yamlText: string): CommsPeer[] {
-  const peers: CommsPeer[] = [];
-  let current: CommsPeer | null = null;
-  let inAgents = false;
-  const scalar = (line: string, key: string): string | null => {
-    const m = line.match(new RegExp(`^\\s*${key}:\\s*["']?([^"'#]+?)["']?\\s*$`));
-    return m ? (m[1] as string).trim() : null;
-  };
-  for (const rawLine of yamlText.split('\n')) {
-    const line = rawLine.replace(/\s+$/, '');
-    if (/^agents:\s*$/.test(line)) {
-      inAgents = true;
-      continue;
-    }
-    if (!inAgents) continue;
-    // A new top-level key (no leading space) ends the agents block.
-    if (/^\S/.test(line)) break;
-
-    const nameMatch = line.match(/^\s*-\s*name:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/);
-    if (nameMatch) {
-      if (current) peers.push(current);
-      current = { name: nameMatch[1] as string, className: 'worker' };
-      continue;
-    }
-    if (!current) continue;
-    const cls = scalar(line, 'class');
-    if (cls) current.className = cls;
-    const host = scalar(line, 'host');
-    if (host) current.host = host;
-    const ssh = scalar(line, 'ssh');
-    if (ssh) current.ssh = ssh;
-    const socket = scalar(line, 'socket');
-    if (socket) current.socket = socket;
-  }
-  if (current) peers.push(current);
-  return peers;
-}
+import { readRegularFileSecure } from './secure-file.js';
+import {
+  parseFleetRosterV1,
+  resolveInstalledFleetRosterPath,
+  getRosterAgent,
+  type FleetAgent,
+  type FleetRoster,
+} from './fleet-roster-v1.js';
 
 export interface FleetCommsOptions {
-  /** This agent's name (it is excluded from its own peer list). */
+  /** Exact current roster member. */
   selfName: string;
-  /** All roster agents (including self; filtered out internally). */
-  agents: CommsPeer[];
-  /** Host the fleet runs on (short hostname) — the same-host baseline. */
-  fleetHost: string;
-  /** Absolute path to agent-send.sh in this install. */
+  /** Canonically resolved roster. */
+  roster: FleetRoster;
+  /** Stable fleet-host baseline for members whose roster host is absent. */
+  localHost: string;
+  /** Absolute helper path in this installation. */
   agentSendPath: string;
 }
 
-/** Is this peer on a different host than the fleet baseline? */
-function isRemote(peer: CommsPeer, fleetHost: string): boolean {
-  return peer.host !== undefined && peer.host !== fleetHost;
+export interface CommsBlockResult {
+  ok: boolean;
+  output: string;
+  error?: string;
 }
 
-/**
- * Render the exact agent-send command to reach a peer (session = agent name).
- * Data-driven per peer: a named `socket` → `-L <socket>`; an unset socket → the
- * default tmux socket (no `-L`). A cross-host peer adds `-H <ssh|host>`.
- */
-export function renderPeerReach(peer: CommsPeer, fleetHost: string, agentSendPath: string): string {
-  const parts = [agentSendPath];
-  if (peer.socket) parts.push('-L', peer.socket); // unset ⇒ default socket, no -L
-  if (isRemote(peer, fleetHost)) parts.push('-H', peer.ssh ?? (peer.host as string));
-  parts.push('-s', peer.name, '-m', '"…"');
+export interface ResolvedFleetIdentity {
+  readonly roster: FleetRoster;
+  readonly member: FleetAgent;
+  readonly requestedName: string;
+  readonly agentSendPath: string;
+  readonly localHost: string;
+}
+
+export interface FleetIdentityResult {
+  ok: boolean;
+  identity?: ResolvedFleetIdentity;
+  error?: string;
+}
+
+export interface PeerCommandResult {
+  ok: boolean;
+  command: string;
+  error?: string;
+}
+
+export const FLEET_COMMS_TOOLS_CONTRACT = 'fleet-comms-contract: 1';
+const MAX_TOOLS_CONTRACT_BYTES = 256 * 1024;
+
+function shortHostname(): string {
+  return hostname().split('.')[0] || 'localhost';
+}
+
+function resolvedHost(agent: FleetAgent, fleetHost: string): string {
+  return agent.host ?? fleetHost;
+}
+
+function displaySocket(socket: string): string {
+  return socket || '(default)';
+}
+
+function knownNames(roster: FleetRoster, except?: string): string {
+  return roster.agents
+    .filter((agent) => agent.name !== except)
+    .map((agent) => agent.name)
+    .join(', ');
+}
+
+function missingMemberError(roster: FleetRoster, selfName: string): string {
+  return `Agent "${selfName}" is not in the fleet roster. Known exact names: ${knownNames(roster)}. Select an exact roster name; do not infer or fuzzy-match a tmux session.`;
+}
+
+/** Render one shell argument without changing already-safe exact values. */
+function shellArg(value: string): string {
+  if (/^[A-Za-z0-9_./:@=+-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+/** Render the exact command for one peer. Throws rather than guessing. */
+export function renderPeerReach(
+  peer: FleetAgent,
+  selfHost: string,
+  fleetHost: string,
+  rosterSocket: string,
+  agentSendPath: string,
+): string {
+  const parts = [shellArg(agentSendPath)];
+  if (rosterSocket) parts.push('-L', shellArg(rosterSocket));
+
+  const peerHost = resolvedHost(peer, fleetHost);
+  if (peerHost !== selfHost) {
+    if (!peer.ssh) {
+      throw new Error(
+        `Cross-host peer "${peer.name}" (${peerHost}) requires an explicit roster ssh target; refusing to substitute its host value.`,
+      );
+    }
+    parts.push('-H', shellArg(peer.ssh));
+  }
+  parts.push('-s', shellArg(peer.name), '-m', '"…"');
   return parts.join(' ');
 }
 
-/**
- * Build the `# Fleet Comms` onboarding block (pure markdown). Returns '' when
- * the agent has no peers (a single-agent roster has no one to talk to).
- */
+/** Resolve one requested peer without fuzzy lookup. */
+export function resolvePeerCommand(
+  roster: FleetRoster,
+  selfName: string,
+  peerName: string,
+  localHost: string,
+  agentSendPath: string,
+): PeerCommandResult {
+  const self = roster.agents.find((agent) => agent.name === selfName);
+  if (!self) return { ok: false, command: '', error: missingMemberError(roster, selfName) };
+  const peer = roster.agents.find((agent) => agent.name === peerName && agent.name !== selfName);
+  if (!peer) {
+    return {
+      ok: false,
+      command: '',
+      error:
+        `Peer "${peerName}" is absent from the fleet roster. Known exact peer names: ${knownNames(roster, selfName)}. ` +
+        `Run \`mosaic agent comms-block ${selfName}\` to rediscover exact rendered rows; do not infer or fuzzy-match a tmux session.`,
+    };
+  }
+  try {
+    return {
+      ok: true,
+      command: renderPeerReach(
+        peer,
+        resolvedHost(self, localHost),
+        localHost,
+        roster.tmux.socketName,
+        agentSendPath,
+      ),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      command: '',
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+interface ResolvedRow {
+  readonly peer: FleetAgent;
+  readonly host: string;
+  readonly socket: string;
+  readonly command: string;
+}
+
+function resolveRows(opts: FleetCommsOptions, self: FleetAgent): readonly ResolvedRow[] {
+  const selfHost = resolvedHost(self, opts.localHost);
+  return opts.roster.agents
+    .filter((agent) => agent.name !== opts.selfName)
+    .map(
+      (peer): ResolvedRow => ({
+        peer,
+        host: resolvedHost(peer, opts.localHost),
+        socket: opts.roster.tmux.socketName,
+        command: renderPeerReach(
+          peer,
+          selfHost,
+          opts.localHost,
+          opts.roster.tmux.socketName,
+          opts.agentSendPath,
+        ),
+      }),
+    );
+}
+
+function commsGeneration(
+  self: FleetAgent,
+  selfHost: string,
+  selfSocket: string,
+  helper: string,
+  rows: readonly ResolvedRow[],
+): string {
+  const canonical = JSON.stringify({
+    self: { ...self, resolvedHost: selfHost, resolvedSocket: selfSocket, helper },
+    peers: rows.map((row) => ({
+      ...row.peer,
+      resolvedHost: row.host,
+      resolvedSocket: row.socket,
+      exactCommand: row.command,
+    })),
+  });
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+/** Build the authoritative Markdown contract for one exact roster member. */
 export function buildFleetCommsBlock(opts: FleetCommsOptions): string {
-  const peers = opts.agents.filter((a) => a.name !== opts.selfName);
-  if (peers.length === 0) return '';
+  const self = opts.roster.agents.find((agent) => agent.name === opts.selfName);
+  if (!self) throw new Error(missingMemberError(opts.roster, opts.selfName));
+  const rows = resolveRows(opts, self);
+  const selfHost = resolvedHost(self, opts.localHost);
+  const selfSocket = opts.roster.tmux.socketName;
+  const generation = commsGeneration(self, selfHost, selfSocket, opts.agentSendPath, rows);
+  const orchestrator = rows.find((row) => row.peer.className === 'orchestrator');
+  const peerSection =
+    rows.length === 0
+      ? 'This roster has no peers. Do not invent a target.'
+      : `| Agent | Role | Host | Socket | Exact command |
+| ----- | ---- | ---- | ------ | ------------- |
+${rows
+  .map((row) => {
+    const pointOfContact = row.peer.className === 'orchestrator' ? ' ← point of contact' : '';
+    return `| ${row.peer.name} | ${row.peer.className}${pointOfContact} | ${row.host} | ${displaySocket(row.socket)} | \`${row.command}\` |`;
+  })
+  .join('\n')}`;
+  const contact = orchestrator
+    ? `Your point of contact is **${orchestrator.peer.name}**. Select that exact peer row for status, questions, and decisions.`
+    : rows.length === 0
+      ? 'No peer coordination target exists in this roster.'
+      : 'This roster has no orchestrator. Select an exact peer row for coordination.';
+  const soloAuthority =
+    rows.length === 0
+      ? `\n## Solo authority boundaries\n\nThis member is normalized as role/class **${self.className}**. The roster grants no peer, orchestrator, or remote communication authority. Do not send, infer a target, or claim fleet coordination until an exact peer is added to the canonical roster and this block is recomposed.\n`
+      : '';
 
-  const orchestrator = peers.find((p) => p.className === 'orchestrator');
-  const rows = peers
-    .map((p) => {
-      const where = isRemote(p, opts.fleetHost)
-        ? `${p.className} · host \`${p.host}\``
-        : p.className;
-      const role = p.className === 'orchestrator' ? `${where} ← point of contact` : where;
-      return `| ${p.name} | ${role} | \`${renderPeerReach(p, opts.fleetHost, opts.agentSendPath)}\` |`;
-    })
-    .join('\n');
+  return `# Fleet Comms — authoritative exact targets
 
-  const orchLine = orchestrator
-    ? `Your point of contact is **${orchestrator.name}** (the orchestrator) — route questions, ` +
-      `status, and decisions there.`
-    : `This fleet has no orchestrator in its roster; coordinate with your peers directly.`;
+## Local identity
 
-  return `# Fleet Comms — reach your peers
+- Host: \`${selfHost}\`
+- Agent/session: \`${self.name}\`
+- Role/class: \`${self.className}\`
+- tmux socket: \`${displaySocket(selfSocket)}\`
+- Helper: \`${opts.agentSendPath}\`
+- Comms generation: \`${generation}\`
 
-You are **${opts.selfName}** in this fleet. Your comms identity is \`[${opts.fleetHost}:${opts.selfName}]\` —
-that is the \`<src>\` other agents see and reply to. Reach other agents (durable tmux sessions) with the
-Mosaic comms tool at \`${opts.agentSendPath}\`. The **Reach** column below is the exact command per peer:
-same-host peers use the short form (no \`-H\`); cross-host peers include \`-H <user@host>\`.
+The roster-resolved rows below are the only valid operational targets. Select the row whose Agent value
+exactly matches the requested peer. Never invent, substitute, or fuzzy-match host, session, socket, SSH,
+or helper-path values. If the peer is absent, stop and run \`mosaic agent comms-block ${self.name}\` to
+rediscover this exact member's rows; if it is still absent, report the unknown peer.
 
 ## Peers
 
-| Agent | Role | Reach (session = agent name) |
-| ----- | ---- | ---------------------------- |
-${rows}
+${peerSection}
 
-${orchLine}
+${contact}
+${soloAuthority}
+## Context freshness
 
-## Conventions
+This block is a snapshot; Mosaic does not rewrite an active agent's context. Compare its Comms generation
+with fresh output from \`mosaic agent comms-block ${self.name}\`. If they differ, report stale composed
+context and have an authorized operator relaunch only this exact roster member with
+\`mosaic fleet restart ${self.name}\`. Do not restart or mutate a session automatically.`;
+}
 
-- Every message carries a self-identifying preamble \`[<src_host>:<src_session> -> <dst_host>:<dst_session>]\` — \`agent-send.sh\` adds it automatically.
-- **To reply, FLIP the preamble:** address your reply to the sender's \`src\` (their host:session becomes your \`-s\`/\`-H\`).
-- \`agent-send.sh\` (a.k.a. \`agent send --verify\`) confirms the message was **ACCEPTED** at the destination prompt — not merely injected. Prefer it for anything that matters.`;
+function validateAgentSendHelper(path: string, mosaicHome: string): string | undefined {
+  try {
+    readRegularFileSecure(path, { root: mosaicHome, executable: true });
+    return undefined;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return `helper is unavailable or unsafe: ${path} (${reason})`;
+  }
+}
+
+function helperFailureGuidance(reason: string): string {
+  return `${reason}. Run \`mosaic update --repair-tools\` to restore the supported current-version helper and TOOLS contract, then retry exact-member composition; no active context or session was rewritten.`;
+}
+
+export function resolveFleetIdentity(
+  mosaicHome: string,
+  requestedName: string | undefined,
+  localHost: string = shortHostname(),
+): FleetIdentityResult {
+  if (!requestedName) return { ok: true };
+  const agentSendPath = join(mosaicHome, 'tools', 'tmux', 'agent-send.sh');
+  const helperError = validateAgentSendHelper(agentSendPath, mosaicHome);
+  if (helperError) return { ok: false, error: helperFailureGuidance(helperError) };
+
+  let rosterPath: string;
+  try {
+    rosterPath = resolveInstalledFleetRosterPath(mosaicHome);
+  } catch (error) {
+    return {
+      ok: false,
+      error: `cannot inspect fleet roster.yaml: ${error instanceof Error ? error.message : String(error)}; refusing JSON fallback because fallback is allowed only when YAML is absent`,
+    };
+  }
+  if (!existsSync(rosterPath)) {
+    return {
+      ok: false,
+      error: `no fleet roster at ${join(mosaicHome, 'fleet', 'roster.yaml')} or ${join(mosaicHome, 'fleet', 'roster.json')}`,
+    };
+  }
+
+  let roster: FleetRoster;
+  try {
+    roster = parseFleetRosterV1(
+      readRegularFileSecure(rosterPath, { root: mosaicHome }).content.toString('utf8'),
+      rosterPath.endsWith('.json') ? 'json' : 'yaml',
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      error: `invalid fleet roster at ${rosterPath}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  try {
+    return {
+      ok: true,
+      identity: {
+        roster,
+        member: getRosterAgent(roster, requestedName),
+        requestedName,
+        agentSendPath,
+        localHost,
+      },
+    };
+  } catch {
+    return { ok: false, error: missingMemberError(roster, requestedName) };
+  }
+}
+
+/** Render Fleet Comms from one already-resolved canonical member identity. */
+export function buildResolvedFleetCommsBlock(identity: ResolvedFleetIdentity): string {
+  return buildFleetCommsBlock({
+    selfName: identity.member.name,
+    roster: identity.roster,
+    localHost: identity.localHost,
+    agentSendPath: identity.agentSendPath,
+  });
 }
 
 /**
- * Read the fleet roster from `mosaicHome` and build the comms block for
- * `selfName`. Returns '' when there is no roster, the agent is not in it, or
- * there are no peers — onboarding is best-effort and never throws.
+ * Read and resolve the installed roster for runtime composition. A requested
+ * fleet identity fails closed; only a genuinely non-fleet launch (no selfName)
+ * is a quiet no-op.
  */
 export function readFleetCommsBlock(
   mosaicHome: string,
   selfName: string | undefined,
-  fleetHost: string = hostname().split('.')[0] || 'localhost',
-): string {
-  if (!selfName) return '';
-  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
-  if (!existsSync(rosterPath)) return '';
-  let text: string;
-  try {
-    text = readFileSync(rosterPath, 'utf-8');
-  } catch {
-    return '';
-  }
-  const agents = parseRosterAgents(text);
-  if (!agents.some((a) => a.name === selfName)) return ''; // not a member of this fleet
-  return buildFleetCommsBlock({
-    selfName,
-    agents,
-    fleetHost,
-    agentSendPath: join(mosaicHome, 'tools', 'tmux', 'agent-send.sh'),
-  });
-}
-
-/** Result of resolving a comms-block emit request — see `mosaic fleet comms-block`. */
-export interface CommsBlockResult {
-  /** True when a cheat-sheet was produced; false maps to stderr + non-zero exit. */
-  ok: boolean;
-  /** The Fleet-Comms cheat-sheet (empty unless ok). */
-  output: string;
-  /** Operator-facing reason when !ok. */
-  error?: string;
-}
-
-/**
- * Resolve the Fleet-Comms cheat-sheet for an explicit <role>, backing the
- * `mosaic fleet comms-block <role>` command. Unlike readFleetCommsBlock — which
- * returns '' on any miss so composeContract can no-op silently during a launch —
- * this NEVER silently emits empty: an unknown role or missing roster yields
- * ok:false + an operator-facing reason, so the CLI surfaces it (stderr + exit 1)
- * rather than printing nothing. That makes it safe to preview any peer's view,
- * e.g. `mosaic fleet comms-block coder0-0`.
- */
-export function resolveCommsBlock(
-  mosaicHome: string,
-  role: string | undefined,
-  fleetHost?: string,
+  localHost: string = shortHostname(),
 ): CommsBlockResult {
-  if (!role) {
-    return { ok: false, output: '', error: 'comms-block requires a <role> argument' };
-  }
-  const block = fleetHost
-    ? readFleetCommsBlock(mosaicHome, role, fleetHost)
-    : readFleetCommsBlock(mosaicHome, role);
-  if (!block) {
-    const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
+  const resolved = resolveFleetIdentity(mosaicHome, selfName, localHost);
+  if (!resolved.ok) return { ok: false, output: '', error: resolved.error };
+  if (!resolved.identity) return { ok: true, output: '' };
+  try {
+    return { ok: true, output: buildResolvedFleetCommsBlock(resolved.identity) };
+  } catch (error) {
     return {
       ok: false,
       output: '',
-      error: existsSync(rosterPath)
-        ? `role "${role}" is not a member of the fleet roster at ${rosterPath}`
-        : `no fleet roster at ${rosterPath}`,
+      error: error instanceof Error ? error.message : String(error),
     };
   }
-  return { ok: true, output: block };
 }
 
-/** Default mosaic home (mirrors launch.ts), for callers that don't pass one. */
+/** Backing resolver for `mosaic agent comms-block <exact-member>`. */
+export function resolveCommsBlock(
+  mosaicHome: string,
+  exactMember: string | undefined,
+): CommsBlockResult {
+  if (!exactMember) {
+    return {
+      ok: false,
+      output: '',
+      error: 'comms-block requires an exact <exact-member> argument',
+    };
+  }
+  return readFleetCommsBlock(mosaicHome, exactMember);
+}
+
+function expectedContractVersion(content: Buffer | string): boolean {
+  return content.toString().includes(`<!-- ${FLEET_COMMS_TOOLS_CONTRACT} -->`);
+}
+
+function boundedContractDigest(
+  path: string,
+  mosaicHome: string,
+): { digest?: string; versionOk: boolean } {
+  try {
+    const content = readRegularFileSecure(path, {
+      root: mosaicHome,
+      maxBytes: MAX_TOOLS_CONTRACT_BYTES,
+    }).content;
+    return {
+      digest: createHash('sha256').update(content).digest('hex'),
+      versionOk: expectedContractVersion(content),
+    };
+  } catch {
+    return { versionOk: false };
+  }
+}
+
+function replacementGuidance(): string {
+  return `Run \`mosaic update --repair-tools\` to make a digest-qualified backup and restore the supported current-version TOOLS contract, then have an authorized operator explicitly relaunch the exact roster member. The active context was not rewritten.`;
+}
+
+/** Detect preserved installed TOOLS.md drift without changing it. */
+export function renderToolsContractStatus(mosaicHome: string): string {
+  const installedPath = join(mosaicHome, 'TOOLS.md');
+  const sourcePath = join(mosaicHome, 'defaults', 'TOOLS.md');
+  if (!existsSync(installedPath)) {
+    return `# Fleet Comms Installation Status\n\nInstalled TOOLS.md is missing at \`${installedPath}\`. ${replacementGuidance()}`;
+  }
+
+  const installed = boundedContractDigest(installedPath, mosaicHome);
+  const source = boundedContractDigest(sourcePath, mosaicHome);
+  if (!source.digest || !source.versionOk) {
+    return `# Fleet Comms Installation Status\n\nThe bounded framework source contract at \`${sourcePath}\` is unavailable or does not declare the expected \`${FLEET_COMMS_TOOLS_CONTRACT}\` version. Run \`mosaic update\` to restore framework source data, verify again, then have an authorized operator explicitly relaunch the exact roster member. The installed file and active context were not rewritten.`;
+  }
+  if (installed.versionOk && installed.digest === source.digest) return '';
+
+  return `# Fleet Comms Installation Status\n\nInstalled TOOLS.md is unavailable, has the wrong contract version, or does not byte-match the bounded framework source contract \`${FLEET_COMMS_TOOLS_CONTRACT}\`. ${replacementGuidance()}`;
+}
+
 export const DEFAULT_MOSAIC_HOME_FOR_COMMS = join(homedir(), '.config', 'mosaic');

packages/mosaic/src/fleet/deterministic-order.ts

@@ -0,0 +1,18 @@
+/** Locale-independent Unicode code-point ordering for canonical fleet evidence. */
+export function compareCodePoints(left: string, right: string): number {
+  const leftPoints = Array.from(left, (character): number => character.codePointAt(0) ?? 0);
+  const rightPoints = Array.from(right, (character): number => character.codePointAt(0) ?? 0);
+  const sharedLength = Math.min(leftPoints.length, rightPoints.length);
+
+  for (let index = 0; index < sharedLength; index += 1) {
+    const leftPoint = leftPoints[index];
+    const rightPoint = rightPoints[index];
+    if (leftPoint === undefined || rightPoint === undefined) continue;
+    if (leftPoint !== rightPoint) return leftPoint < rightPoint ? -1 : 1;
+  }
+  return leftPoints.length < rightPoints.length
+    ? -1
+    : leftPoints.length > rightPoints.length
+      ? 1
+      : 0;
+}

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

@@ -0,0 +1,484 @@
+import { chmod, mkdir, mkdtemp, rm, 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 CommandRunner } from '../commands/fleet.js';
+import {
+  executeFleetReconcile,
+  type FleetReconcileCommandResult,
+  type FleetReconcileDeps,
+  type FleetReconcileResult,
+} from './fleet-reconciler.js';
+import {
+  parseRosterV2,
+  renderRosterV2Yaml,
+  type FleetRosterV2,
+  type FleetRosterV2Agent,
+} from './roster-v2.js';
+import { FleetTmuxRuntimeTransport } from './tmux-runtime-transport.js';
+
+const holderIdentity = '11111111-1111-4111-8111-111111111111';
+const stoppedAgent: FleetRosterV2Agent = {
+  name: 'coder0',
+  alias: 'Coder 0',
+  className: 'code',
+  runtime: 'pi',
+  provider: 'openai',
+  model: 'gpt-5.6-sol',
+  reasoning: 'high',
+  toolPolicy: 'code',
+  workingDirectory: '/srv/mosaic',
+  persistentPersona: false,
+  resetBetweenTasks: true,
+  lifecycle: { enabled: true, desiredState: 'stopped' },
+  launch: { yolo: true },
+};
+
+const baseRoster: FleetRosterV2 = {
+  version: 2,
+  generation: 7,
+  transport: 'tmux',
+  tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
+  defaults: { workingDirectory: '/srv/mosaic', runtime: 'pi' },
+  runtimes: { pi: { resetCommand: '/new' } },
+  agents: [stoppedAgent],
+};
+
+interface InjectedLifecycleFailure {
+  readonly action: 'start' | 'stop' | 'restart';
+  readonly service: string;
+  readonly diagnostic: string;
+}
+
+class FakeLifecycleHost {
+  readonly calls: string[][] = [];
+  readonly sessions = new Set<string>();
+  readonly activeServices = new Set<string>();
+  private failure: InjectedLifecycleFailure | undefined;
+
+  constructor(readonly roster: FleetRosterV2) {
+    this.sessions.add(roster.tmux.holderSession);
+  }
+
+  injectFailure(failure: InjectedLifecycleFailure): void {
+    this.failure = failure;
+  }
+
+  readonly run = async (
+    command: string,
+    args: readonly string[],
+  ): Promise<FleetReconcileCommandResult> => {
+    this.calls.push([command, ...args]);
+    if (command === 'tmux') return this.runTmux(args);
+    if (command === 'systemctl') return this.runSystemctl(args);
+    return { stdout: '', stderr: 'unsupported fake command', exitCode: 127 };
+  };
+
+  private runTmux(args: readonly string[]): FleetReconcileCommandResult {
+    if (args.includes('list-sessions')) {
+      return { stdout: `${[...this.sessions].join('\n')}\n`, stderr: '', exitCode: 0 };
+    }
+    if (args.includes('has-session')) {
+      const targetArgument = args[args.indexOf('-t') + 1];
+      const sessionName = targetArgument?.replace(/^=/, '').split(':')[0];
+      return {
+        stdout: '',
+        stderr: '',
+        exitCode: sessionName !== undefined && this.sessions.has(sessionName) ? 0 : 1,
+      };
+    }
+    if (args.includes('show-environment')) {
+      return {
+        stdout: [
+          'HOME=/home/mosaic',
+          `MOSAIC_FLEET_OWNER=${holderIdentity}`,
+          `MOSAIC_TMUX_HOLDER=${this.roster.tmux.holderSession}`,
+          `MOSAIC_TMUX_SOCKET=${this.roster.tmux.socketName}`,
+          'PATH=/usr/bin:/bin',
+          'PWD=/home/mosaic',
+          '',
+        ].join('\n'),
+        stderr: '',
+        exitCode: 0,
+      };
+    }
+    return { stdout: '', stderr: 'destructive tmux action rejected by fake', exitCode: 125 };
+  }
+
+  private runSystemctl(args: readonly string[]): FleetReconcileCommandResult {
+    const action = args[1];
+    const service = args[2];
+    if (action === 'show' && service !== undefined) {
+      return {
+        stdout: `ActiveState=${this.activeServices.has(service) ? 'active' : 'inactive'}\n`,
+        stderr: '',
+        exitCode: 0,
+      };
+    }
+    if (
+      (action === 'start' || action === 'stop' || action === 'restart') &&
+      service !== undefined
+    ) {
+      this.applyLifecycleEffect(action, service);
+      if (this.failure?.action === action && this.failure.service === service) {
+        const diagnostic = this.failure.diagnostic;
+        this.failure = undefined;
+        return { stdout: '', stderr: diagnostic, exitCode: 1 };
+      }
+      return { stdout: '', stderr: '', exitCode: 0 };
+    }
+    return { stdout: '', stderr: 'unsupported fake systemctl action', exitCode: 125 };
+  }
+
+  private applyLifecycleEffect(action: 'start' | 'stop' | 'restart', service: string): void {
+    if (service === 'mosaic-tmux-holder.service') return;
+    const match = /^mosaic-agent@(.+)\.service$/.exec(service);
+    if (!match) return;
+    const agentName = match[1];
+    if (agentName === undefined) return;
+    if (action === 'stop') {
+      this.activeServices.delete(service);
+      this.sessions.delete(agentName);
+      return;
+    }
+    this.activeServices.add(service);
+    this.sessions.add(agentName);
+  }
+}
+
+const cleanupDirectories: string[] = [];
+
+afterEach(async (): Promise<void> => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+  await Promise.all(
+    cleanupDirectories.splice(0).map(async (directory: string): Promise<void> => {
+      await rm(directory, { recursive: true, force: true });
+    }),
+  );
+});
+
+function reconcileDeps(host: FakeLifecycleHost): FleetReconcileDeps {
+  return {
+    runner: host.run,
+    homeDirectory: '/home/mosaic',
+    readHolderIdentity: async () => holderIdentity,
+    validateRoster: async () => undefined,
+    prepareProjections: async () => [{ agentName: 'coder0' }],
+    applyProjection: async () => undefined,
+    readRoster: async () => host.roster,
+    acquireMutationLock: async () => async () => undefined,
+  };
+}
+
+async function execute(
+  host: FakeLifecycleHost,
+  command: 'apply' | 'reconcile' | 'restart' | 'status' | 'stop',
+  agentName?: string,
+): Promise<FleetReconcileResult> {
+  return executeFleetReconcile({
+    roster: host.roster,
+    command,
+    ...(agentName === undefined ? {} : { agentName }),
+    ...(command === 'status' ? {} : { expectedGeneration: host.roster.generation }),
+    deps: reconcileDeps(host),
+  });
+}
+
+async function fixtureHome(roster: FleetRosterV2): Promise<string> {
+  const home = await mkdtemp(join(tmpdir(), 'mosaic-reconciler-acceptance-'));
+  cleanupDirectories.push(home);
+  const fleetDirectory = join(home, 'fleet');
+  await mkdir(fleetDirectory, { mode: 0o700 });
+  await chmod(home, 0o700);
+  await chmod(fleetDirectory, 0o700);
+  await writeFile(join(fleetDirectory, 'roster.yaml'), renderRosterV2Yaml(roster), { mode: 0o600 });
+  return home;
+}
+
+async function fixtureLegacyRoster(): Promise<string> {
+  const home = await mkdtemp(join(tmpdir(), 'mosaic-reconciler-acceptance-v1-'));
+  cleanupDirectories.push(home);
+  const fleetDirectory = join(home, 'fleet');
+  await mkdir(fleetDirectory, { mode: 0o700 });
+  await chmod(home, 0o700);
+  await chmod(fleetDirectory, 0o700);
+  const rosterPath = join(fleetDirectory, 'roster.yaml');
+  await writeFile(
+    rosterPath,
+    [
+      'version: 1',
+      'transport: tmux',
+      'tmux:',
+      '  holder_session: _holder',
+      'agents:',
+      '  - name: coder0',
+      '    runtime: pi',
+      '    class: code',
+      '',
+    ].join('\n'),
+    { mode: 0o600 },
+  );
+  return rosterPath;
+}
+
+function cliProgram(home: string, host: FakeLifecycleHost): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerFleetCommand(program, {
+    mosaicHome: home,
+    runner: async (command: string, args: string[]): Promise<CommandResult> =>
+      host.run(command, args),
+    reconcileDeps: reconcileDeps(host),
+  });
+  return program;
+}
+
+function captureJson(): string[] {
+  const output: string[] = [];
+  vi.spyOn(console, 'log').mockImplementation((line: string): void => {
+    output.push(line);
+  });
+  return output;
+}
+
+describe('FCM-M3-002 reconciler lifecycle acceptance', (): void => {
+  it('observes named-socket drift through canonical roster-v2 parsing without runtime mutation', async (): Promise<void> => {
+    const roster: FleetRosterV2 = {
+      ...baseRoster,
+      agents: [
+        stoppedAgent,
+        {
+          ...stoppedAgent,
+          name: 'reviewer0',
+          alias: 'Reviewer 0',
+          lifecycle: { enabled: true, desiredState: 'running' },
+        },
+        {
+          ...stoppedAgent,
+          name: 'validator0',
+          alias: 'Validator 0',
+          lifecycle: { enabled: false, desiredState: 'stopped' },
+        },
+      ],
+    };
+    const home = await fixtureHome(roster);
+    const host = new FakeLifecycleHost(roster);
+    host.sessions.add('coder0');
+    host.sessions.add('validator0');
+    host.sessions.add('coder0-shadow');
+    const output = captureJson();
+
+    await cliProgram(home, host).parseAsync(['node', 'mosaic', 'fleet', 'status']);
+
+    expect(output).toHaveLength(1);
+    expect(JSON.parse(output[0] ?? '{}')).toMatchObject({
+      plan: {
+        agents: [
+          { name: 'coder0', drift: ['unexpected-session'] },
+          { name: 'reviewer0', drift: ['missing-session'] },
+          { name: 'validator0', drift: ['unexpected-session', 'disabled-running'] },
+        ],
+        unmanagedSessions: ['coder0-shadow'],
+      },
+    });
+    expect(host.calls[0]).toEqual([
+      'tmux',
+      '-L',
+      'mosaic-fleet',
+      'list-sessions',
+      '-F',
+      '#{session_name}',
+    ]);
+    expect(
+      host.calls.every(
+        (call: string[]): boolean =>
+          call[0] !== 'tmux' || (call[1] === '-L' && call[2] === 'mosaic-fleet'),
+      ),
+    ).toBe(true);
+    expect(
+      host.calls.every((call: string[]): boolean => call[0] !== 'systemctl' || call[2] === 'show'),
+    ).toBe(true);
+    expect(process.exitCode).toBe(0);
+  });
+
+  it('rejects a missing canonical roster-v2 tmux socket through parseRosterV2', (): void => {
+    const source = renderRosterV2Yaml(baseRoster).replace(/^  socket_name:.*\n/m, '');
+    expect(() => parseRosterV2(source, 'yaml')).toThrow(
+      'Roster v2 tmux socket_name is required and must be a string.',
+    );
+  });
+
+  it('accepts an explicit empty canonical roster-v2 socket as the literal default server', (): void => {
+    const source = renderRosterV2Yaml(baseRoster).replace(
+      /^  socket_name:.*$/m,
+      '  socket_name: ""',
+    );
+    expect(parseRosterV2(source, 'yaml').tmux.socketName).toBe('');
+  });
+
+  it('omits -L for the literal default tmux server at the runtime transport boundary', async (): Promise<void> => {
+    const rosterPath = await fixtureLegacyRoster();
+    const runner = vi.fn<CommandRunner>(
+      async (): Promise<CommandResult> => ({
+        stdout: '111 pi 0 0 0 0\n',
+        stderr: '',
+        exitCode: 0,
+      }),
+    );
+    const transport = new FleetTmuxRuntimeTransport({
+      mosaicHome: '/unused',
+      rosterPath,
+      runner,
+    });
+
+    await expect(transport.verifySession('coder0')).resolves.toEqual({
+      id: 'coder0',
+      runtimeId: 'pi',
+      socketName: '',
+    });
+    expect(runner).toHaveBeenCalledTimes(1);
+    expect(runner).toHaveBeenCalledWith('tmux', [
+      'list-panes',
+      '-t',
+      '=coder0:0.0',
+      '-F',
+      '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}',
+    ]);
+    expect(runner.mock.calls[0]?.[1]).not.toContain('-L');
+  });
+
+  it('classifies unmanaged near-collisions and stops only the exact roster-owned service', async (): Promise<void> => {
+    const host = new FakeLifecycleHost(baseRoster);
+    host.sessions.add('coder0');
+    host.sessions.add('coder0-shadow');
+    host.sessions.add('unmanaged');
+    host.activeServices.add('mosaic-agent@coder0.service');
+    host.activeServices.add('mosaic-agent@coder0-shadow.service');
+
+    const observed = await execute(host, 'status');
+    const stopped = await execute(host, 'stop', 'coder0');
+
+    expect(observed.plan.unmanagedSessions).toEqual(['coder0-shadow', 'unmanaged']);
+    expect(stopped).toMatchObject({ applied: true, lifecycle: 'complete' });
+    expect(host.activeServices.has('mosaic-agent@coder0.service')).toBe(false);
+    expect(host.activeServices.has('mosaic-agent@coder0-shadow.service')).toBe(true);
+    expect(host.sessions.has('coder0-shadow')).toBe(true);
+    expect(host.sessions.has('unmanaged')).toBe(true);
+    expect(host.calls).toContainEqual([
+      'systemctl',
+      '--user',
+      'stop',
+      'mosaic-agent@coder0.service',
+    ]);
+    expect(
+      host.calls.some(
+        (call: string[]): boolean =>
+          call.includes('kill-session') ||
+          call.includes('coder0-shadow.service') ||
+          call.includes('unmanaged.service'),
+      ),
+    ).toBe(false);
+  });
+
+  it('preserves persisted stopped state through apply, reconcile, restart failure, and recovery reconcile', async (): Promise<void> => {
+    const host = new FakeLifecycleHost(baseRoster);
+    host.sessions.add('coder0');
+    host.activeServices.add('mosaic-agent@coder0.service');
+
+    const applied = await execute(host, 'apply');
+    const reconciled = await execute(host, 'reconcile');
+    host.injectFailure({
+      action: 'restart',
+      service: 'mosaic-agent@coder0.service',
+      diagnostic: 'crash after effect: TOKEN=acceptance-secret',
+    });
+    const partialRestart = await execute(host, 'restart', 'coder0');
+
+    expect(applied).toMatchObject({ applied: true, lifecycle: 'complete' });
+    expect(reconciled).toMatchObject({ applied: true, lifecycle: 'complete' });
+    expect(host.roster.agents[0]?.lifecycle.desiredState).toBe('stopped');
+    expect(partialRestart).toMatchObject({
+      applied: false,
+      authoritativeRoster: 'unchanged',
+      projections: 'not-applied',
+      lifecycle: 'incomplete',
+      recovery: {
+        code: 'lifecycle-apply-failed',
+        action: 'rerun-after-inspecting-owned-resources',
+      },
+    });
+    expect(host.activeServices.has('mosaic-agent@coder0.service')).toBe(true);
+
+    const recovered = await execute(host, 'reconcile');
+
+    expect(recovered).toMatchObject({ applied: true, lifecycle: 'complete' });
+    expect(host.roster.agents[0]?.lifecycle.desiredState).toBe('stopped');
+    expect(host.activeServices.has('mosaic-agent@coder0.service')).toBe(false);
+    expect(host.sessions.has('coder0')).toBe(false);
+    const destructiveCalls = host.calls.filter(
+      (call: string[]): boolean =>
+        call[0] === 'systemctl' && ['start', 'stop', 'restart'].includes(call[2] ?? ''),
+    );
+    expect(
+      destructiveCalls.every(
+        (call: string[]): boolean => call[3] === 'mosaic-agent@coder0.service',
+      ),
+    ).toBe(true);
+    expect(destructiveCalls.some((call: string[]): boolean => call[2] === 'start')).toBe(false);
+  });
+
+  it('emits stable non-zero redacted JSON for a partial lifecycle effect', async (): Promise<void> => {
+    const home = await fixtureHome(baseRoster);
+    const host = new FakeLifecycleHost(baseRoster);
+    host.injectFailure({
+      action: 'restart',
+      service: 'mosaic-agent@coder0.service',
+      diagnostic: 'simulated runner stderr with PASSWORD=acceptance-secret',
+    });
+    const output = captureJson();
+
+    await cliProgram(home, host).parseAsync([
+      'node',
+      'mosaic',
+      'fleet',
+      'restart',
+      'coder0',
+      '--expected-generation',
+      '7',
+    ]);
+
+    const line = output.at(-1) ?? '';
+    expect(output).toHaveLength(1);
+    expect(JSON.parse(line)).toEqual({
+      applied: false,
+      authoritativeRoster: 'unchanged',
+      projections: 'not-applied',
+      lifecycle: 'incomplete',
+      plan: {
+        generation: 7,
+        holder: 'owned',
+        agents: [
+          {
+            name: 'coder0',
+            desiredState: 'stopped',
+            enabled: true,
+            systemd: 'inactive',
+            tmux: 'missing',
+            drift: [],
+          },
+        ],
+        unmanagedSessions: [],
+      },
+      recovery: {
+        code: 'lifecycle-apply-failed',
+        action: 'rerun-after-inspecting-owned-resources',
+      },
+    });
+    expect(process.exitCode).toBe(1);
+    expect(line).not.toContain('PASSWORD');
+    expect(line).not.toContain('acceptance-secret');
+    expect(line).not.toContain('simulated runner stderr');
+  });
+});

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

@@ -274,6 +274,95 @@ describe('fleet roster-owned reconciler', (): void => {
     ]);
   });
 
+  it.each(['plan', 'status', 'doctor', 'verify'] as const)(
+    'keeps default-server %s observational and free of lifecycle effects',
+    async (command) => {
+      const calls: string[][] = [];
+      const defaultServerRoster: FleetRosterV2 = {
+        ...roster,
+        tmux: { ...roster.tmux, socketName: '' },
+      };
+
+      await expect(
+        executeFleetReconcile({
+          roster: defaultServerRoster,
+          command,
+          deps: deps({
+            runner: async (executable, args) => {
+              calls.push([executable, ...args]);
+              if (executable === 'tmux' && args.includes('list-sessions')) {
+                return { stdout: '_holder\n', stderr: '', exitCode: 0 };
+              }
+              if (executable === 'tmux' && args.includes('show-environment')) {
+                return {
+                  stdout:
+                    'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+                  stderr: '',
+                  exitCode: 0,
+                };
+              }
+              return { stdout: 'ActiveState=inactive\n', stderr: '', exitCode: 0 };
+            },
+          }),
+        }),
+      ).resolves.toMatchObject({ applied: false, lifecycle: 'not-applied' });
+      expect(
+        calls.some(
+          ([executable, , action]): boolean =>
+            executable === 'systemctl' &&
+            (action === 'start' || action === 'stop' || action === 'restart'),
+        ),
+      ).toBe(false);
+    },
+  );
+
+  it.each(['start', 'stop', 'restart', 'apply', 'reconcile'] as const)(
+    'fails closed before %s can route fixed named-socket services for a default-server roster',
+    async (command) => {
+      const calls: string[][] = [];
+      let projectionPrepares = 0;
+      let projectionApplies = 0;
+      const defaultServerRoster: FleetRosterV2 = {
+        ...roster,
+        tmux: { ...roster.tmux, socketName: '' },
+        agents: [
+          {
+            ...roster.agents[0]!,
+            lifecycle: {
+              enabled: true,
+              desiredState: command === 'start' || command === 'restart' ? 'running' : 'stopped',
+            },
+          },
+        ],
+      };
+
+      await expect(
+        executeFleetReconcile({
+          roster: defaultServerRoster,
+          command,
+          expectedGeneration: 7,
+          deps: deps({
+            readRoster: async () => defaultServerRoster,
+            prepareProjections: async () => {
+              projectionPrepares += 1;
+              return [{ agentName: 'coder0' }];
+            },
+            applyProjection: async () => {
+              projectionApplies += 1;
+            },
+            runner: async (executable, args) => {
+              calls.push([executable, ...args]);
+              return { stdout: '', stderr: '', exitCode: 0 };
+            },
+          }),
+        }),
+      ).rejects.toMatchObject({ code: 'lifecycle-precondition-failed' });
+      expect(projectionPrepares).toBe(0);
+      expect(projectionApplies).toBe(0);
+      expect(calls).toEqual([]);
+    },
+  );
+
   it('starts only an explicitly running roster agent with exact systemd targets', async (): Promise<void> => {
     const calls: string[][] = [];
     const runningRoster: FleetRosterV2 = {

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

@@ -176,6 +176,7 @@ export async function executeFleetReconcile(
   assertLocalRosterOnly(request.roster);
   const validateRoster = request.deps.validateRoster ?? defaultValidateRoster(request);
   await validateRoster(request.roster);
+  assertLifecycleSocketAuthority(request);
   const plan = scopePlan(await observeFleet(request.roster, request.deps), request.agentName);
 
   if (request.command === 'status' || request.command === 'doctor') {
@@ -477,6 +478,19 @@ function assertVerificationSafe(plan: FleetReconcilePlan): void {
   }
 }
 
+function assertLifecycleSocketAuthority(request: FleetReconcileRequest): void {
+  const usesFixedLifecycleUnits =
+    request.command === 'apply' ||
+    request.command === 'reconcile' ||
+    isLifecycleCommand(request.command);
+  if (usesFixedLifecycleUnits && request.roster.tmux.socketName === '') {
+    throw new FleetReconcileError(
+      'lifecycle-precondition-failed',
+      'Default-server lifecycle mutation is unsupported by the fixed named-socket systemd units.',
+    );
+  }
+}
+
 function targetAgentsFor(roster: FleetRosterV2, agentName?: string): readonly FleetRosterV2Agent[] {
   if (agentName === undefined) return roster.agents;
   const agent = roster.agents.find(

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

@@ -0,0 +1,522 @@
+import { lstatSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { canonicalizeRoleClass } from '../commands/fleet-personas.js';
+
+interface RawFleetRoster {
+  version?: unknown;
+  transport?: unknown;
+  tmux?: {
+    socket_name?: unknown;
+    socketName?: unknown;
+    holder_session?: unknown;
+    holderSession?: unknown;
+  };
+  defaults?: {
+    working_directory?: unknown;
+    workingDirectory?: unknown;
+  };
+  runtimes?: Record<string, { reset_command?: unknown; resetCommand?: unknown }>;
+  agents?: Array<{
+    name?: unknown;
+    alias?: unknown;
+    provider?: unknown;
+    runtime?: unknown;
+    class?: unknown;
+    host?: unknown;
+    ssh?: unknown;
+    socket?: unknown;
+    working_directory?: unknown;
+    workingDirectory?: unknown;
+    model_hint?: unknown;
+    modelHint?: unknown;
+    reasoning_level?: unknown;
+    reasoningLevel?: unknown;
+    tool_policy?: unknown;
+    toolPolicy?: unknown;
+    persistent_persona?: unknown;
+    persistentPersona?: unknown;
+    reset_between_tasks?: unknown;
+    resetBetweenTasks?: unknown;
+    kickstart_template?: unknown;
+    kickstartTemplate?: unknown;
+  }>;
+  connector?: {
+    kind?: unknown;
+    matrix?: {
+      homeserver_url?: unknown;
+      user_id?: unknown;
+      room_id?: unknown;
+    };
+    discord?: {
+      channel_id?: unknown;
+    };
+  };
+}
+
+export interface FleetAgent {
+  name: string;
+  alias?: string;
+  provider?: string;
+  runtime: string;
+  className: string;
+  /** Resolved host identity. Absent means the caller's authoritative local host. */
+  host?: string;
+  /** Explicit SSH destination for a cross-host inventory peer. */
+  ssh?: string;
+  /** Compatibility declaration; when set it must equal fleet-wide tmux.socketName. */
+  socket?: string;
+  workingDirectory?: string;
+  modelHint?: string;
+  reasoningLevel?: string;
+  toolPolicy?: string;
+  persistentPersona?: boolean | string;
+  resetBetweenTasks?: boolean;
+  kickstartTemplate?: string;
+}
+
+export type FleetConnector =
+  | { kind: 'tmux' }
+  | {
+      kind: 'discord';
+      discord: { channelId: string };
+    }
+  | {
+      kind: 'matrix';
+      matrix: { homeserverUrl: string; userId: string; roomId: string };
+    };
+
+export interface FleetRoster {
+  version: 1;
+  transport: 'tmux';
+  tmux: {
+    socketName: string;
+    holderSession: string;
+  };
+  defaults: {
+    workingDirectory: string;
+  };
+  runtimes: Record<string, { resetCommand: string }>;
+  agents: FleetAgent[];
+  connector?: FleetConnector;
+}
+
+export type FleetRosterInputFormat = 'yaml' | 'json';
+
+export function resolveInstalledFleetRosterPath(mosaicHome: string): string {
+  const yamlPath = join(mosaicHome, 'fleet', 'roster.yaml');
+  try {
+    lstatSync(yamlPath);
+    return yamlPath;
+  } catch (error) {
+    if (!isNodeErrorCode(error, 'ENOENT')) throw error;
+    return join(mosaicHome, 'fleet', 'roster.json');
+  }
+}
+
+const DEFAULT_HOLDER_SESSION = '_holder';
+const DEFAULT_WORKING_DIRECTORY = '~/src';
+const DEFAULT_RUNTIME_RESETS: Record<string, { resetCommand: string }> = {
+  claude: { resetCommand: '/clear' },
+  codex: { resetCommand: '/clear' },
+  opencode: { resetCommand: '/clear' },
+  pi: { resetCommand: '/new' },
+};
+
+/** One structural v1 resolver used by fleet commands and runtime comms composition. */
+export function parseFleetRosterV1(
+  source: string,
+  format: FleetRosterInputFormat = 'yaml',
+): FleetRoster {
+  const trimmed = source.trim();
+  const parsed =
+    format === 'json'
+      ? (JSON.parse(trimmed) as RawFleetRoster)
+      : (YAML.parse(trimmed) as RawFleetRoster);
+  return normalizeFleetRosterV1(parsed);
+}
+
+export async function loadFleetRoster(path: string): Promise<FleetRoster> {
+  const source = await readFile(path, 'utf8');
+  return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
+}
+
+export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
+  const agent = roster.agents.find((candidate) => candidate.name === name);
+  if (!agent) throw new Error(`Agent "${name}" is not in the fleet roster.`);
+  return agent;
+}
+
+export function normalizeFleetRosterV1(raw: RawFleetRoster): FleetRoster {
+  assertObject(raw, 'Fleet roster');
+  assertKnownKeys(raw, 'Fleet roster', [
+    'version',
+    'transport',
+    'tmux',
+    'defaults',
+    'runtimes',
+    'agents',
+    'connector',
+  ]);
+  if (raw.tmux !== undefined) {
+    assertObject(raw.tmux, 'Fleet roster tmux');
+    assertKnownKeys(raw.tmux, 'Fleet roster tmux', [
+      'socket_name',
+      'socketName',
+      'holder_session',
+      'holderSession',
+    ]);
+  }
+  if (raw.defaults !== undefined) {
+    assertObject(raw.defaults, 'Fleet roster defaults');
+    assertKnownKeys(raw.defaults, 'Fleet roster defaults', [
+      'working_directory',
+      'workingDirectory',
+    ]);
+  }
+  if (raw.runtimes !== undefined) {
+    assertObject(raw.runtimes, 'Fleet roster runtimes');
+    for (const [runtime, config] of Object.entries(raw.runtimes)) {
+      assertObject(config, `Fleet roster runtime "${runtime}"`);
+      assertKnownKeys(config, `Fleet roster runtime "${runtime}"`, [
+        'reset_command',
+        'resetCommand',
+      ]);
+    }
+  }
+  if (raw.version !== 1) throw new Error('Fleet roster version must be 1.');
+  if (raw.transport !== 'tmux') throw new Error('Fleet roster transport must be "tmux".');
+  if (!Array.isArray(raw.agents) || raw.agents.length === 0) {
+    throw new Error('Fleet roster must define at least one agent.');
+  }
+
+  const socketName = targetingString(
+    aliasValue(raw.tmux, 'socket_name', 'socketName', 'Fleet roster tmux socket'),
+    '',
+    'Fleet roster tmux socket_name',
+    /^[A-Za-z0-9_.-]+$/,
+  );
+  const agents = raw.agents.map(normalizeAgent);
+  assertUniqueAgentNames(agents);
+  for (const agent of agents) {
+    if (agent.socket !== undefined && agent.socket !== socketName) {
+      throw new Error(
+        `Fleet agent "${agent.name}" socket must equal the fleet-wide tmux socket_name; independent per-agent sockets are not supported.`,
+      );
+    }
+  }
+  return {
+    version: 1,
+    transport: 'tmux',
+    tmux: {
+      socketName,
+      holderSession: stringValue(
+        aliasValue(raw.tmux, 'holder_session', 'holderSession', 'Fleet roster tmux holder'),
+        DEFAULT_HOLDER_SESSION,
+        'Fleet roster tmux holder_session',
+      ),
+    },
+    defaults: {
+      workingDirectory: stringValue(
+        aliasValue(
+          raw.defaults,
+          'working_directory',
+          'workingDirectory',
+          'Fleet roster defaults working directory',
+        ),
+        DEFAULT_WORKING_DIRECTORY,
+        'Fleet roster defaults working_directory',
+      ),
+    },
+    runtimes: normalizeRuntimes(raw.runtimes as RawFleetRoster['runtimes']),
+    agents,
+    connector: normalizeConnector(raw.connector as RawFleetRoster['connector']),
+  };
+}
+
+function normalizeAgent(raw: NonNullable<RawFleetRoster['agents']>[number]): FleetAgent {
+  assertObject(raw, 'Fleet roster agent');
+  assertKnownKeys(raw, 'Fleet roster agent', [
+    'name',
+    'alias',
+    'provider',
+    'runtime',
+    'class',
+    'host',
+    'ssh',
+    'socket',
+    'working_directory',
+    'workingDirectory',
+    'model_hint',
+    'modelHint',
+    'reasoning_level',
+    'reasoningLevel',
+    'tool_policy',
+    'toolPolicy',
+    'persistent_persona',
+    'persistentPersona',
+    'reset_between_tasks',
+    'resetBetweenTasks',
+    'kickstart_template',
+    'kickstartTemplate',
+  ]);
+  const name = stringValue(raw.name, '', 'Fleet roster agent name');
+  const runtime = stringValue(
+    raw.runtime,
+    '',
+    `Fleet roster agent "${name || '<unknown>'}" runtime`,
+  );
+  if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+    throw new Error(`Invalid fleet agent name: ${name || '<empty>'}`);
+  }
+  if (!runtime) throw new Error(`Fleet agent "${name}" must define a runtime.`);
+  return {
+    name,
+    alias: optionalString(raw.alias, `Fleet roster agent "${name}" alias`),
+    provider: optionalString(raw.provider, `Fleet roster agent "${name}" provider`),
+    runtime,
+    className: canonicalizeRoleClass(
+      stringValue(raw.class, 'worker', `Fleet roster agent "${name}" class`),
+    ).canonicalClass,
+    host: optionalTargetingString(
+      raw.host,
+      `Fleet roster agent "${name}" host`,
+      /^[A-Za-z0-9_.:[\]-]+$/,
+    ),
+    ssh: optionalTargetingString(
+      raw.ssh,
+      `Fleet roster agent "${name}" ssh`,
+      /^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9_.:[\]-]+$/,
+    ),
+    socket: optionalTargetingString(
+      raw.socket,
+      `Fleet roster agent "${name}" socket`,
+      /^[A-Za-z0-9_.-]+$/,
+    ),
+    workingDirectory: optionalString(
+      aliasValue(
+        raw,
+        'working_directory',
+        'workingDirectory',
+        `Fleet roster agent "${name}" working directory`,
+      ),
+      `Fleet roster agent "${name}" working_directory`,
+    ),
+    modelHint: optionalString(
+      aliasValue(raw, 'model_hint', 'modelHint', `Fleet roster agent "${name}" model hint`),
+      `Fleet roster agent "${name}" model_hint`,
+    ),
+    reasoningLevel: optionalString(
+      aliasValue(
+        raw,
+        'reasoning_level',
+        'reasoningLevel',
+        `Fleet roster agent "${name}" reasoning level`,
+      ),
+      `Fleet roster agent "${name}" reasoning_level`,
+    ),
+    toolPolicy: optionalString(
+      aliasValue(raw, 'tool_policy', 'toolPolicy', `Fleet roster agent "${name}" tool policy`),
+      `Fleet roster agent "${name}" tool_policy`,
+    ),
+    persistentPersona: optionalBooleanOrString(
+      aliasValue(
+        raw,
+        'persistent_persona',
+        'persistentPersona',
+        `Fleet roster agent "${name}" persistent persona`,
+      ),
+      `Fleet roster agent "${name}" persistent_persona`,
+    ),
+    resetBetweenTasks: optionalBoolean(
+      aliasValue(
+        raw,
+        'reset_between_tasks',
+        'resetBetweenTasks',
+        `Fleet roster agent "${name}" reset between tasks`,
+      ),
+      `Fleet roster agent "${name}" reset_between_tasks`,
+    ),
+    kickstartTemplate: optionalString(
+      aliasValue(
+        raw,
+        'kickstart_template',
+        'kickstartTemplate',
+        `Fleet roster agent "${name}" kickstart template`,
+      ),
+      `Fleet roster agent "${name}" kickstart_template`,
+    ),
+  };
+}
+
+function normalizeRuntimes(
+  raw: RawFleetRoster['runtimes'] | undefined,
+): Record<string, { resetCommand: string }> {
+  const result: Record<string, { resetCommand: string }> = { ...DEFAULT_RUNTIME_RESETS };
+  for (const [runtime, config] of Object.entries(raw ?? {})) {
+    result[runtime] = {
+      resetCommand: stringValue(
+        aliasValue(
+          config,
+          'reset_command',
+          'resetCommand',
+          `Fleet roster runtime "${runtime}" reset command`,
+        ),
+        '/clear',
+        `Fleet roster runtime "${runtime}" reset_command`,
+      ),
+    };
+  }
+  return result;
+}
+
+function normalizeConnector(raw: RawFleetRoster['connector']): FleetConnector | undefined {
+  if (raw === undefined) return undefined;
+  assertObject(raw, 'Fleet roster connector');
+  assertKnownKeys(raw, 'Fleet roster connector', ['kind', 'matrix', 'discord']);
+  const kind = stringValue(raw.kind, '', 'Fleet roster connector kind');
+  if (kind === 'tmux') {
+    if (raw.matrix !== undefined || raw.discord !== undefined) {
+      throw new Error('Fleet roster tmux connector must not define matrix or discord settings.');
+    }
+    return { kind };
+  }
+  if (kind === 'discord') {
+    if (raw.matrix !== undefined) {
+      throw new Error('Fleet roster discord connector must not define matrix settings.');
+    }
+    assertObject(raw.discord, 'Fleet roster connector discord');
+    assertKnownKeys(raw.discord, 'Fleet roster connector discord', ['channel_id']);
+    return {
+      kind,
+      discord: {
+        channelId: requiredString(
+          raw.discord.channel_id,
+          'Fleet roster connector discord channel_id',
+        ),
+      },
+    };
+  }
+  if (kind === 'matrix') {
+    if (raw.discord !== undefined) {
+      throw new Error('Fleet roster matrix connector must not define discord settings.');
+    }
+    assertObject(raw.matrix, 'Fleet roster connector matrix');
+    assertKnownKeys(raw.matrix, 'Fleet roster connector matrix', [
+      'homeserver_url',
+      'user_id',
+      'room_id',
+    ]);
+    return {
+      kind,
+      matrix: {
+        homeserverUrl: requiredString(
+          raw.matrix.homeserver_url,
+          'Fleet roster connector matrix homeserver_url',
+        ),
+        userId: requiredString(raw.matrix.user_id, 'Fleet roster connector matrix user_id'),
+        roomId: requiredString(raw.matrix.room_id, 'Fleet roster connector matrix room_id'),
+      },
+    };
+  }
+  throw new Error('Fleet roster connector kind must be one of: tmux, discord, matrix.');
+}
+
+function aliasValue<T extends Record<string, unknown>>(
+  source: T | undefined,
+  snake: keyof T,
+  camel: keyof T,
+  label: string,
+): unknown {
+  const snakeValue = source?.[snake];
+  const camelValue = source?.[camel];
+  if (snakeValue !== undefined && camelValue !== undefined && snakeValue !== camelValue) {
+    throw new Error(`${label} aliases ${String(snake)} and ${String(camel)} conflict.`);
+  }
+  return snakeValue ?? camelValue;
+}
+
+function isNodeErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error && 'code' in error && error.code === code;
+}
+
+function requiredString(value: unknown, label: string): string {
+  const resolved = stringValue(value, '', label).trim();
+  if (!resolved) throw new Error(`${label} is required.`);
+  return resolved;
+}
+
+function assertObject(value: unknown, label: string): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object.`);
+  }
+}
+
+function assertKnownKeys(
+  value: Record<string, unknown>,
+  label: string,
+  allowedKeys: readonly string[],
+): void {
+  const allowed = new Set(allowedKeys);
+  const unknownKeys = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(`${label} has unknown field(s): ${unknownKeys.join(', ')}.`);
+  }
+}
+
+function assertUniqueAgentNames(agents: FleetAgent[]): void {
+  const seen = new Set<string>();
+  for (const agent of agents) {
+    if (seen.has(agent.name)) {
+      throw new Error(`Fleet roster has duplicate agent name: ${agent.name}.`);
+    }
+    seen.add(agent.name);
+  }
+}
+
+function stringValue(value: unknown, fallback = '', label = 'Value'): string {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'string') throw new Error(`${label} must be a string.`);
+  return value;
+}
+
+function targetingString(value: unknown, fallback: string, label: string, pattern: RegExp): string {
+  const resolved = stringValue(value, fallback, label);
+  if (resolved && !pattern.test(resolved)) {
+    throw new Error(`${label} contains unsupported targeting characters.`);
+  }
+  return resolved;
+}
+
+function optionalTargetingString(
+  value: unknown,
+  label: string,
+  pattern: RegExp,
+): string | undefined {
+  const resolved = optionalString(value, label);
+  if (resolved !== undefined && (!resolved || !pattern.test(resolved))) {
+    throw new Error(`${label} contains unsupported targeting characters.`);
+  }
+  return resolved;
+}
+
+function optionalString(value: unknown, label = 'Value'): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') throw new Error(`${label} must be a string.`);
+  return value;
+}
+
+function optionalBoolean(value: unknown, label = 'Value'): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'boolean') throw new Error(`${label} must be a boolean.`);
+  return value;
+}
+
+function optionalBooleanOrString(value: unknown, label = 'Value'): boolean | string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'boolean' && typeof value !== 'string') {
+    throw new Error(`${label} must be a boolean or string.`);
+  }
+  return value;
+}

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

@@ -9,12 +9,13 @@ import {
   symlink,
   writeFile,
 } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
   AgentEnvBoundaryError,
   parseAgentEnvironment,
+  previewAgentEnvironmentProjection,
   renderGeneratedAgentEnvironment,
   writeAgentEnvironmentProjection,
 } from './generated-env-boundary.js';
@@ -86,6 +87,77 @@ describe('generated fleet agent environment boundary', (): void => {
     }).toThrow(AgentEnvBoundaryError);
   });
 
+  it('rejects traversal in home-relative workdirs before expansion', (): void => {
+    for (const workingDirectory of ['~/../escape', '~/src/../../escape']) {
+      expect((): void => {
+        renderGeneratedAgentEnvironment({
+          ...generatedValues,
+          MOSAIC_AGENT_WORKDIR: workingDirectory,
+        });
+      }).toThrow(
+        expect.objectContaining({
+          diagnostic: expect.objectContaining({
+            code: 'unsafe-path',
+            key: 'MOSAIC_AGENT_WORKDIR',
+          }),
+        }),
+      );
+    }
+  });
+
+  it('expands home-relative workdirs before preserving absolute-path validation', (): void => {
+    expect(
+      renderGeneratedAgentEnvironment({
+        ...generatedValues,
+        MOSAIC_AGENT_WORKDIR: '~/src',
+      }),
+    ).toContain(`MOSAIC_AGENT_WORKDIR=${join(homedir(), 'src')}\n`);
+
+    for (const workingDirectory of ['relative/path', '../outside']) {
+      expect((): void => {
+        renderGeneratedAgentEnvironment({
+          ...generatedValues,
+          MOSAIC_AGENT_WORKDIR: workingDirectory,
+        });
+      }).toThrow(AgentEnvBoundaryError);
+    }
+  });
+
+  it('previews legacy relocation and quarantine without exposing content or mutating files', async (): Promise<void> => {
+    cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
+    const mosaicHome = join(cleanup, 'mosaic');
+    const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
+    const legacyPath = join(agentEnvDir, 'coder0.env');
+    const legacy = 'MOSAIC_RUNTIME_BIN=/opt/mosaic/bin\nMOSAIC_AGENT_COMMAND=never-print-command\n';
+    await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
+    await writeFile(legacyPath, legacy, { mode: 0o600 });
+
+    const preview = await previewAgentEnvironmentProjection({
+      mosaicHome,
+      agentEnvDir,
+      agentName: 'coder0',
+      generated: generatedValues,
+    });
+
+    expect(preview).toMatchObject({
+      agentName: 'coder0',
+      generated: 'rebuild',
+      legacy: 'quarantine',
+      relocatedKeys: ['MOSAIC_RUNTIME_BIN'],
+      diagnostics: [
+        expect.objectContaining({
+          code: 'unknown-key',
+          key: 'MOSAIC_AGENT_COMMAND',
+          sha256: expect.stringMatching(/^[a-f0-9]{64}$/),
+        }),
+      ],
+    });
+    expect(JSON.stringify(preview)).not.toContain('never-print-command');
+    await expect(readFile(legacyPath, 'utf8')).resolves.toBe(legacy);
+    await expect(readFile(join(agentEnvDir, 'coder0.env.generated'), 'utf8')).rejects.toThrow();
+    await expect(readFile(join(agentEnvDir, 'coder0.env.quarantine'), 'utf8')).rejects.toThrow();
+  });
+
   it('creates missing managed directories privately before writing a projection', async (): Promise<void> => {
     cleanup = await mkdtemp(join(tmpdir(), 'mosaic-generated-env-'));
     const mosaicHome = join(cleanup, 'mosaic');

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

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { compareCodePoints } from './deterministic-order.js';
 
 export type AgentEnvironmentKind = 'generated' | 'local';
 
@@ -30,6 +32,15 @@ export interface AgentEnvironmentProjectionResult {
   readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
 
+/** Sanitized, non-mutating projection evidence safe for migration output. */
+export interface AgentEnvironmentProjectionPreview {
+  readonly agentName: string;
+  readonly generated: 'rebuild';
+  readonly legacy: 'absent' | 'regenerate-only' | 'relocate-local' | 'quarantine';
+  readonly relocatedKeys: readonly string[];
+  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
+}
+
 /** A projection fully validated without changing managed files. */
 export interface PreparedAgentEnvironmentProjection {
   readonly mosaicHome: string;
@@ -40,6 +51,7 @@ export interface PreparedAgentEnvironmentProjection {
   readonly generated: string;
   readonly local: string;
   readonly legacy?: string;
+  readonly legacyRelocatedKeys: readonly string[];
   readonly quarantinePath?: string;
   readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
@@ -186,6 +198,7 @@ export async function prepareAgentEnvironmentProjection(
     generated,
     local,
     ...(legacy === undefined ? {} : { legacy }),
+    legacyRelocatedKeys: Object.keys(legacyDisposition.localValues).sort(compareCodePoints),
     ...(quarantinePath === undefined ? {} : { quarantinePath }),
     diagnostics: legacyDisposition.diagnostics,
   };
@@ -208,6 +221,33 @@ export async function prepareAgentGeneratedProjectionDeletion(
   return generatedPath;
 }
 
+export async function previewAgentEnvironmentProjection(
+  options: AgentEnvironmentProjectionOptions,
+): Promise<AgentEnvironmentProjectionPreview> {
+  const prepared = await prepareAgentEnvironmentProjection(options);
+  const relocatedKeys = prepared.legacyRelocatedKeys;
+  const legacy =
+    prepared.legacy === undefined
+      ? 'absent'
+      : prepared.diagnostics.length > 0
+        ? 'quarantine'
+        : relocatedKeys.length > 0
+          ? 'relocate-local'
+          : 'regenerate-only';
+  return {
+    agentName: options.agentName,
+    generated: 'rebuild',
+    legacy,
+    relocatedKeys,
+    diagnostics: [...prepared.diagnostics].sort((left, right): number =>
+      compareCodePoints(
+        `${left.key}:${left.code}:${left.sha256}`,
+        `${right.key}:${right.code}:${right.sha256}`,
+      ),
+    ),
+  };
+}
+
 /** Applies a previously prepared deterministic projection. */
 export async function applyPreparedAgentEnvironmentProjection(
   prepared: PreparedAgentEnvironmentProjection,
@@ -279,7 +319,7 @@ function normalizeGeneratedValues(
   for (const key of GENERATED_AGENT_ENV_KEYS) {
     const value = values[key];
     if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
-    normalized[key] = value;
+    normalized[key] = key === 'MOSAIC_AGENT_WORKDIR' ? expandHomeDirectory(value) : value;
   }
   for (const [key, value] of Object.entries(values)) {
     if (!GENERATED_KEY_SET.has(key)) throw new AgentEnvBoundaryError('unknown-key', key, value);
@@ -288,17 +328,23 @@ function normalizeGeneratedValues(
   return Object.freeze(normalized);
 }
 
+function expandHomeDirectory(path: string): string {
+  if (path === '~') return homedir();
+  if (!path.startsWith('~/') || path.split('/').includes('..')) return path;
+  return join(homedir(), path.slice(2));
+}
+
 function renderLocalAgentEnvironment(values: Readonly<Record<string, string>>): string {
   if (Object.keys(values).length === 0) return '';
   const parsed = parseAgentEnvironment(
     Object.entries(values)
-      .sort(([left], [right]): number => left.localeCompare(right))
+      .sort(([left], [right]): number => compareCodePoints(left, right))
       .map(([key, value]): string => `${key}=${value}`)
       .join('\n'),
     'local',
   );
   return `${Object.entries(parsed)
-    .sort(([left], [right]): number => left.localeCompare(right))
+    .sort(([left], [right]): number => compareCodePoints(left, right))
     .map(([key, value]): string => `${key}=${value}`)
     .join('\n')}\n`;
 }

packages/mosaic/src/fleet/roster-v2.spec.ts

@@ -45,6 +45,12 @@ agents:
 
 let semanticTmp: string | undefined;
 
+it('preserves an explicit empty socket as the literal default tmux server', () => {
+  const roster = parseRosterV2(validRoster.replace('socket_name: mosaic-fleet', "socket_name: ''"));
+  expect(roster.tmux.socketName).toBe('');
+  expect(renderRosterV2Yaml(roster)).toContain('socket_name: ""');
+});
+
 afterEach(async (): Promise<void> => {
   if (semanticTmp) await rm(semanticTmp, { recursive: true, force: true });
   semanticTmp = undefined;

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

@@ -10,6 +10,7 @@ import {
   type PersonaResolution,
   type RoleAuthority,
 } from '../commands/fleet-personas.js';
+import { compareCodePoints } from './deterministic-order.js';
 
 export const ROSTER_V2_SUPPORTED_RUNTIMES = ['claude', 'codex', 'opencode', 'pi'] as const;
 export const ROSTER_V2_REASONING_LEVELS = ['low', 'medium', 'high'] as const;
@@ -172,7 +173,7 @@ export const ROSTER_V2_JSON_SCHEMA: JsonSchema = {
       additionalProperties: false,
       required: ['socket_name', 'holder_session'],
       properties: {
-        socket_name: { type: 'string', pattern: '^[A-Za-z0-9_.-]+$' },
+        socket_name: { type: 'string', pattern: '^[A-Za-z0-9_.-]*$' },
         holder_session: { type: 'string', pattern: '^[A-Za-z0-9_.-]+$' },
       },
     },
@@ -272,6 +273,7 @@ const AGENT_KEYS = [
 const LIFECYCLE_KEYS = ['enabled', 'desired_state'];
 const LAUNCH_KEYS = ['yolo'];
 const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const TMUX_SOCKET_IDENTIFIER = /^[A-Za-z0-9_.-]*$/;
 const TMUX_IDENTIFIER = /^[A-Za-z0-9_.-]+$/;
 const POLICY_IDENTIFIER = /^[a-z][a-z0-9-]*$/;
 
@@ -327,7 +329,7 @@ function normalizeTmux(value: unknown): FleetRosterV2Tmux {
   const raw = requiredObject(value, 'Roster v2 tmux');
   assertKnownKeys(raw, 'Roster v2 tmux', TMUX_KEYS);
   return {
-    socketName: requiredTmuxIdentifier(raw.socket_name, 'Roster v2 tmux socket_name'),
+    socketName: requiredTmuxSocket(raw.socket_name, 'Roster v2 tmux socket_name'),
     holderSession: requiredTmuxIdentifier(raw.holder_session, 'Roster v2 tmux holder_session'),
   };
 }
@@ -348,7 +350,7 @@ function normalizeRuntimes(value: unknown): Readonly<Record<string, FleetRosterV
     throw new RosterV2ValidationError('Roster v2 runtimes must not be empty.');
 
   const result: Record<string, FleetRosterV2Runtime> = {};
-  for (const name of names.sort()) {
+  for (const name of names.sort(compareCodePoints)) {
     const runtime = requiredRuntime(name, 'Roster v2 runtime name');
     const config = requiredObject(raw[name], `Roster v2 runtime "${runtime}"`);
     assertKnownKeys(config, `Roster v2 runtime "${runtime}"`, RUNTIME_KEYS);
@@ -416,7 +418,7 @@ function normalizeAgents(
     };
   });
   return agents.sort((left: FleetRosterV2Agent, right: FleetRosterV2Agent): number =>
-    left.name.localeCompare(right.name),
+    compareCodePoints(left.name, right.name),
   );
 }
 
@@ -473,6 +475,17 @@ function requiredIdentifier(value: unknown, label: string): string {
   return result;
 }
 
+function requiredTmuxSocket(value: unknown, label: string): string {
+  if (typeof value !== 'string') {
+    throw new RosterV2ValidationError(`${label} is required and must be a string.`);
+  }
+  const result = value.trim();
+  if (!TMUX_SOCKET_IDENTIFIER.test(result)) {
+    throw new RosterV2ValidationError(`Invalid ${label}: ${result}.`);
+  }
+  return result;
+}
+
 function requiredTmuxIdentifier(value: unknown, label: string): string {
   const result = requiredString(value, label);
   if (!TMUX_IDENTIFIER.test(result))
@@ -524,7 +537,7 @@ function toSourceShape(roster: FleetRosterV2): Record<string, unknown> {
     },
     runtimes: Object.fromEntries(
       Object.entries(roster.runtimes)
-        .sort(([left], [right]): number => left.localeCompare(right))
+        .sort(([left], [right]): number => compareCodePoints(left, right))
         .map(([name, runtime]): [string, unknown] => [
           name,
           { reset_command: runtime.resetCommand },
@@ -532,7 +545,7 @@ function toSourceShape(roster: FleetRosterV2): Record<string, unknown> {
     ),
     agents: [...roster.agents]
       .sort((left: FleetRosterV2Agent, right: FleetRosterV2Agent): number =>
-        left.name.localeCompare(right.name),
+        compareCodePoints(left.name, right.name),
       )
       .map(
         (agent: FleetRosterV2Agent): Record<string, unknown> => ({

packages/mosaic/src/fleet/secure-file.spec.ts

@@ -0,0 +1,179 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+  type PathLike,
+} from 'node:fs';
+import type * as NodeFs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface FilesystemRaceState {
+  afterLstat?: (path: string) => void;
+  afterOpen?: (path: string) => void;
+}
+
+const filesystemRaceState = vi.hoisted<FilesystemRaceState>(() => ({}));
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof NodeFs>();
+  return {
+    ...actual,
+    lstatSync: (path: PathLike) => {
+      const result = actual.lstatSync(path);
+      filesystemRaceState.afterLstat?.(String(path));
+      return result;
+    },
+    openSync: (path: PathLike, flags: string | number, mode?: number) => {
+      const fd = actual.openSync(path, flags, mode);
+      filesystemRaceState.afterOpen?.(String(path));
+      return fd;
+    },
+  };
+});
+
+import { assertCanonicalContainment, readRegularFileSecure } from './secure-file.js';
+
+describe('secure file reads', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'mosaic-secure-file-'));
+    filesystemRaceState.afterLstat = undefined;
+    filesystemRaceState.afterOpen = undefined;
+  });
+
+  afterEach(() => {
+    filesystemRaceState.afterLstat = undefined;
+    filesystemRaceState.afterOpen = undefined;
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('rejects canonical path escape', () => {
+    expect(() => assertCanonicalContainment(root, join(root, '..', 'outside'))).toThrow(
+      'path escapes managed root',
+    );
+  });
+
+  it('rejects a symlink in a file ancestor', () => {
+    const external = join(root, 'external');
+    mkdirSync(external);
+    writeFileSync(join(external, 'file'), 'external\n');
+    symlinkSync(external, join(root, 'linked'));
+
+    expect(() => readRegularFileSecure(join(root, 'linked', 'file'), { root })).toThrow(
+      'path ancestor is a symbolic link',
+    );
+  });
+
+  it('rejects a symlink target', () => {
+    const external = join(root, 'external');
+    writeFileSync(external, 'external\n');
+    symlinkSync(external, join(root, 'linked-file'));
+
+    expect(() => readRegularFileSecure(join(root, 'linked-file'), { root })).toThrow(
+      'file is a symbolic link',
+    );
+  });
+
+  it('keeps ancestor traversal bound when an opened directory is substituted', () => {
+    const tools = join(root, 'tools');
+    const displacedTools = join(root, 'tools.displaced');
+    const external = join(root, 'external');
+    const helper = join(tools, 'helper.sh');
+    mkdirSync(tools);
+    mkdirSync(external);
+    writeFileSync(helper, 'trusted\n', { mode: 0o755 });
+    writeFileSync(join(external, 'helper.sh'), 'external marker\n', { mode: 0o755 });
+
+    let substituted = false;
+    filesystemRaceState.afterOpen = (openedPath: string): void => {
+      if (substituted || !openedPath.startsWith('/proc/self/fd/')) return;
+      if (openedPath.split('/').at(-1) !== 'tools') return;
+      substituted = true;
+      renameSync(tools, displacedTools);
+      symlinkSync(external, tools);
+    };
+
+    const result = readRegularFileSecure(helper, { root, executable: true });
+    expect(substituted).toBe(true);
+    expect(result.content.toString('utf8')).toBe('trusted\n');
+  });
+
+  it('keeps root selection bound when the opened root is substituted', () => {
+    const displacedRoot = `${root}.displaced`;
+    const externalRoot = `${root}.external`;
+    const helper = join(root, 'helper.sh');
+    mkdirSync(externalRoot);
+    writeFileSync(helper, 'trusted root\n', { mode: 0o755 });
+    writeFileSync(join(externalRoot, 'helper.sh'), 'external root marker\n', { mode: 0o755 });
+
+    let substituted = false;
+    filesystemRaceState.afterOpen = (openedPath: string): void => {
+      if (substituted || !openedPath.startsWith('/proc/self/fd/')) return;
+      const match = openedPath.match(/\/([^/]+)$/);
+      if (match?.[1] !== root.split('/').filter(Boolean).at(-1)) return;
+      substituted = true;
+      renameSync(root, displacedRoot);
+      symlinkSync(externalRoot, root);
+    };
+
+    const result = readRegularFileSecure(helper, { root, executable: true });
+    expect(substituted).toBe(true);
+    expect(result.content.toString('utf8')).toBe('trusted root\n');
+    filesystemRaceState.afterOpen = undefined;
+    rmSync(root);
+    renameSync(displacedRoot, root);
+  });
+
+  it('keeps target read and execute validation bound to the opened file', () => {
+    const file = join(root, 'helper.sh');
+    const displaced = join(root, 'helper.displaced.sh');
+    const external = join(root, 'external-helper.sh');
+    writeFileSync(file, 'trusted target\n', { mode: 0o755 });
+    writeFileSync(external, 'external target marker\n', { mode: 0o755 });
+
+    let substituted = false;
+    filesystemRaceState.afterOpen = (openedPath: string): void => {
+      if (substituted || !openedPath.startsWith('/proc/self/fd/')) return;
+      if (openedPath.split('/').at(-1) !== 'helper.sh') return;
+      substituted = true;
+      renameSync(file, displaced);
+      symlinkSync(external, file);
+    };
+
+    const result = readRegularFileSecure(file, { root, executable: true });
+    expect(substituted).toBe(true);
+    expect(result.content.toString('utf8')).toBe('trusted target\n');
+  });
+
+  it('uses a stable redacted executable error while retaining the error code', () => {
+    const file = join(root, 'helper.sh');
+    writeFileSync(file, '#!/bin/sh\n', { mode: 0o644 });
+
+    try {
+      readRegularFileSecure(file, { root, executable: true });
+      throw new Error('expected executable validation to fail');
+    } catch (error) {
+      expect(error).toMatchObject({ message: 'managed file is not executable', code: 'EACCES' });
+      expect(String(error)).not.toContain('/proc/self/fd/');
+      expect(String(error)).not.toContain(root);
+    }
+  });
+
+  it('uses effective-identity execute access after regular-file validation', () => {
+    const file = join(root, 'helper.sh');
+    writeFileSync(file, '#!/bin/sh\n', { mode: 0o644 });
+    expect(() => readRegularFileSecure(file, { root, executable: true })).toThrow();
+
+    chmodSync(file, 0o755);
+    expect(readRegularFileSecure(file, { root, executable: true }).content.toString()).toBe(
+      '#!/bin/sh\n',
+    );
+  });
+});

packages/mosaic/src/fleet/secure-file.ts

@@ -0,0 +1,242 @@
+import {
+  accessSync,
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+} from 'node:fs';
+import { platform } from 'node:os';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+export interface SecureFileReadOptions {
+  root: string;
+  maxBytes?: number;
+  executable?: boolean;
+}
+
+export interface SecureFileSnapshot {
+  content: Buffer;
+  mode: number;
+  dev: number | bigint;
+  ino: number | bigint;
+}
+
+function sameIdentity(
+  left: { dev: number | bigint; ino: number | bigint },
+  right: { dev: number | bigint; ino: number | bigint },
+): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function secureFilesystemError(message: string, cause: unknown): Error {
+  const error = new Error(message);
+  if (cause instanceof Error && 'code' in cause && typeof cause.code === 'string') {
+    Object.defineProperty(error, 'code', { value: cause.code, enumerable: true });
+  }
+  return error;
+}
+
+function closeDescriptors(descriptors: number[]): void {
+  for (const fd of descriptors.reverse()) {
+    try {
+      closeSync(fd);
+    } catch {
+      // Best-effort cleanup must not replace the security decision already made.
+    }
+  }
+}
+
+function procDescriptorPath(fd: number, component?: string): string {
+  const descriptor = `/proc/self/fd/${fd}`;
+  return component === undefined ? descriptor : `${descriptor}/${component}`;
+}
+
+/**
+ * Hold each directory while opening its child through Linux proc-fd. The only
+ * symlink followed is the kernel-owned descriptor link; O_NOFOLLOW protects
+ * every appended filesystem component from substitution.
+ */
+function openDirectoryChain(absoluteDirectory: string): { fd: number; descriptors: number[] } {
+  if (platform() !== 'linux') {
+    throw new Error('secure descriptor traversal is unsupported on this platform');
+  }
+
+  const descriptors: number[] = [];
+  try {
+    let fd = openSync(sep, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    descriptors.push(fd);
+    for (const component of absoluteDirectory.split(sep).filter(Boolean)) {
+      fd = openSync(
+        procDescriptorPath(fd, component),
+        constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+      );
+      descriptors.push(fd);
+      if (!fstatSync(fd).isDirectory()) {
+        throw new Error('secure descriptor traversal encountered a non-directory component');
+      }
+    }
+    return { fd, descriptors };
+  } catch (error) {
+    closeDescriptors(descriptors);
+    throw secureFilesystemError(
+      'secure descriptor traversal failed: symbolic link, unavailable, or not a directory',
+      error,
+    );
+  }
+}
+
+function openFileBeneathRoot(root: string, target: string): { fd: number; descriptors: number[] } {
+  const canonicalRoot = resolve(root);
+  const canonicalTarget = resolve(target);
+  assertCanonicalContainment(canonicalRoot, canonicalTarget);
+  const components = relative(canonicalRoot, canonicalTarget).split(sep).filter(Boolean);
+  const fileName = components.pop();
+  if (fileName === undefined) throw new Error('managed file path names the managed root');
+
+  const rootChain = openDirectoryChain(canonicalRoot);
+  try {
+    let parentFd = rootChain.fd;
+    for (const component of components) {
+      try {
+        parentFd = openSync(
+          procDescriptorPath(parentFd, component),
+          constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+        );
+      } catch (error) {
+        throw secureFilesystemError(
+          'path ancestor is a symbolic link, unavailable, or not a directory',
+          error,
+        );
+      }
+      rootChain.descriptors.push(parentFd);
+      if (!fstatSync(parentFd).isDirectory()) {
+        throw new Error('path ancestor is a symbolic link or not a directory');
+      }
+    }
+    let fd: number;
+    try {
+      fd = openSync(
+        procDescriptorPath(parentFd, fileName),
+        constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW,
+      );
+    } catch (error) {
+      throw secureFilesystemError('file is a symbolic link or unavailable', error);
+    }
+    rootChain.descriptors.push(fd);
+    return { fd, descriptors: rootChain.descriptors };
+  } catch (error) {
+    closeDescriptors(rootChain.descriptors);
+    if (error instanceof Error) throw error;
+    throw new Error('secure managed file open failed');
+  }
+}
+
+export function assertCanonicalContainment(root: string, target: string): void {
+  const canonicalRoot = resolve(root);
+  const canonicalTarget = resolve(target);
+  const rel = relative(canonicalRoot, canonicalTarget);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`path escapes managed root ${canonicalRoot}: ${canonicalTarget}`);
+  }
+}
+
+/** Reject every symlink from the filesystem root through the target's parent. */
+export function assertNoSymlinkAncestors(target: string): void {
+  const absolute = resolve(target);
+  const parent = dirname(absolute);
+  const pieces = parent.split(sep).filter(Boolean);
+  let cursor: string = sep;
+  for (const piece of pieces) {
+    cursor = resolve(cursor, piece);
+    const stat = lstatSync(cursor);
+    if (stat.isSymbolicLink()) throw new Error(`path ancestor is a symbolic link: ${cursor}`);
+    if (!stat.isDirectory()) throw new Error(`path ancestor is not a directory: ${cursor}`);
+  }
+}
+
+export function ensureManagedDirectory(root: string, directory: string): void {
+  assertCanonicalContainment(root, directory);
+  const canonicalRoot = resolve(root);
+  const canonicalDirectory = resolve(directory);
+  assertNoSymlinkAncestors(canonicalRoot);
+  try {
+    const rootStat = lstatSync(canonicalRoot);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+      throw new Error(`managed root is not a real directory: ${canonicalRoot}`);
+    }
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+    mkdirSync(canonicalRoot, { mode: 0o700 });
+    const rootStat = lstatSync(canonicalRoot);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+      throw new Error(`managed root creation was redirected: ${canonicalRoot}`);
+    }
+  }
+  const rel = relative(canonicalRoot, canonicalDirectory);
+  let cursor = canonicalRoot;
+  for (const piece of rel.split(sep).filter(Boolean)) {
+    cursor = resolve(cursor, piece);
+    try {
+      const stat = lstatSync(cursor);
+      if (stat.isSymbolicLink()) throw new Error(`path ancestor is a symbolic link: ${cursor}`);
+      if (!stat.isDirectory()) throw new Error(`path ancestor is not a directory: ${cursor}`);
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+      mkdirSync(cursor, { mode: 0o700 });
+      const created = lstatSync(cursor);
+      if (!created.isDirectory() || created.isSymbolicLink()) {
+        throw new Error(`managed directory creation was redirected: ${cursor}`);
+      }
+    }
+  }
+}
+
+/**
+ * Read a regular file through an O_NOFOLLOW descriptor. The inode is checked
+ * before and after access/read, and executable access is tested against the
+ * already-open descriptor so path replacement cannot redirect the check.
+ */
+export function readRegularFileSecure(
+  path: string,
+  options: SecureFileReadOptions,
+): SecureFileSnapshot {
+  const openedFile = openFileBeneathRoot(options.root, path);
+  try {
+    const opened = fstatSync(openedFile.fd);
+    if (!opened.isFile()) throw new Error('managed file is not a regular file');
+    if (options.maxBytes !== undefined && opened.size > options.maxBytes) {
+      throw new Error(`managed file exceeds ${options.maxBytes} bytes`);
+    }
+    if (options.executable) {
+      try {
+        accessSync(procDescriptorPath(openedFile.fd), constants.X_OK);
+      } catch (error) {
+        throw secureFilesystemError('managed file is not executable', error);
+      }
+      const afterAccess = fstatSync(openedFile.fd);
+      if (!afterAccess.isFile() || !sameIdentity(opened, afterAccess)) {
+        throw new Error('managed file changed during executable access check');
+      }
+    }
+
+    const content = readFileSync(openedFile.fd);
+    const after = fstatSync(openedFile.fd);
+    if (!after.isFile() || !sameIdentity(opened, after)) {
+      throw new Error('managed file changed during secure read');
+    }
+    if (options.maxBytes !== undefined && content.byteLength > options.maxBytes) {
+      throw new Error(`managed file exceeds ${options.maxBytes} bytes`);
+    }
+    return {
+      content,
+      mode: Number(opened.mode),
+      dev: opened.dev,
+      ino: opened.ino,
+    };
+  } finally {
+    closeDescriptors(openedFile.descriptors);
+  }
+}

packages/mosaic/src/framework/manifest-parity.spec.ts

@@ -0,0 +1,343 @@
+import { afterAll, describe, it, expect } from 'vitest';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  loadManifest,
+  parseManifest,
+  resolveOwnership,
+  frameworkSubtreeRoots,
+} from './manifest.js';
+
+/**
+ * Bash ↔ TS parity (#791, §6.1).
+ *
+ * The installer (bash) and the config adapter (TS) each resolve path ownership
+ * from framework-manifest.txt. If the two resolvers disagreed on a single path,
+ * an upgrade could protect a file on one code path and wipe it on the other —
+ * exactly the two-copies drift that #631 patched by hand. This test drives the
+ * bash resolver (`tools/_lib/manifest.sh`) as a subprocess and asserts it agrees
+ * with the TS resolver for a broad set of paths spanning every ownership class.
+ */
+
+const FRAMEWORK_ROOT = fileURLToPath(new URL('../../framework', import.meta.url));
+const MANIFEST_SH = join(FRAMEWORK_ROOT, 'tools', '_lib', 'manifest.sh');
+
+const hasBash = (() => {
+  try {
+    execFileSync('bash', ['-c', 'true'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+})();
+
+function bashResolve(relPath: string): string {
+  return execFileSync('bash', [MANIFEST_SH, 'resolve', relPath], {
+    encoding: 'utf-8',
+  }).trim();
+}
+
+/** Drive the bash resolver against an arbitrary manifest file (MANIFEST_FILE override). */
+function bashResolveWith(manifestFile: string, relPath: string): string {
+  return execFileSync('bash', [MANIFEST_SH, 'resolve', relPath], {
+    encoding: 'utf-8',
+    env: { ...process.env, MANIFEST_FILE: manifestFile },
+  }).trim();
+}
+
+function bashSubtreeRoots(): string[] {
+  return execFileSync('bash', [MANIFEST_SH, 'subtree-roots'], { encoding: 'utf-8' })
+    .split('\n')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Drive the bash resolver CLI against a manifest file and report how it exited.
+ * A fail-closed manifest must make the CLI exit non-zero with a message on
+ * stderr — never exit 0 having silently resolved everything to operator.
+ */
+function bashCli(manifestFile: string): { status: number; stderr: string } {
+  const res = spawnSync('bash', [MANIFEST_SH, 'resolve', 'CONSTITUTION.md'], {
+    encoding: 'utf-8',
+    env: { ...process.env, MANIFEST_FILE: manifestFile },
+  });
+  return { status: res.status ?? -1, stderr: res.stderr ?? '' };
+}
+
+// Paths spanning every ownership class: framework single-files, framework
+// subtrees, operator declared trees, operator carve-out inside a framework
+// subtree, local overlays, and deliberately UNANTICIPATED paths (fail-safe).
+const PROBE_PATHS = [
+  'CONSTITUTION.md',
+  'AGENTS.md',
+  'STANDARDS.md',
+  'install.sh',
+  'framework-manifest.txt',
+  'guides/E2E-DELIVERY.md',
+  'tools/git/pr-create.sh',
+  'tools/_lib/manifest.sh',
+  'defaults/SOUL.md',
+  'fleet/README.md',
+  'fleet/roles/coder.md',
+  'fleet/roster.schema.json',
+  'fleet/examples/general.yaml',
+  // operator
+  'SOUL.md',
+  'USER.md',
+  'TOOLS.md',
+  'SOUL.local.md',
+  'USER.local.md',
+  'STANDARDS.local.md',
+  'agents/coder0.conf',
+  'policy/custom.md',
+  'memory/note.md',
+  'sources/skills/x.md',
+  'credentials/c.json',
+  'tools/_lib/credentials.json',
+  'fleet/roster.yaml',
+  'fleet/roster.json',
+  'fleet/agents/coder0.env',
+  'fleet/run/coder0.hb',
+  // #797 Runtime Session Ledger — must resolve operator on both paths.
+  'fleet/run/sessions/events.ndjson',
+  'fleet/run/sessions/ledger.json',
+  'fleet/backlog/data.db',
+  'fleet/roles.local/custom.md',
+  // unanticipated → operator (fail-safe)
+  'harvester/sop.md',
+  'unknown-operator-dir/x',
+  'fleet/my-fleet.yaml',
+  'random-root-file.md',
+  'tools/some-new-framework-tool.sh',
+];
+
+describe.skipIf(!hasBash)('bash ↔ TS manifest parity (§6.1)', () => {
+  it('the bash resolver CLI exists and is executable', () => {
+    expect(existsSync(MANIFEST_SH)).toBe(true);
+  });
+
+  it('bash and TS resolve identical ownership for every probe path', () => {
+    const manifest = loadManifest(FRAMEWORK_ROOT);
+    const disagreements: Array<{ path: string; ts: string; bash: string }> = [];
+    for (const p of PROBE_PATHS) {
+      const ts = resolveOwnership(manifest, p);
+      const bash = bashResolve(p);
+      if (ts !== bash) disagreements.push({ path: p, ts, bash });
+    }
+    expect(disagreements).toEqual([]);
+  });
+
+  it('bash and TS agree on the framework subtree roots', () => {
+    const manifest = loadManifest(FRAMEWORK_ROOT);
+    expect(bashSubtreeRoots().sort()).toEqual(frameworkSubtreeRoots(manifest).sort());
+  });
+});
+
+/**
+ * Format-safety parity (#791, Decision 1 — the `.txt` line-oriented format is
+ * accepted only because both resolvers agree on the format edge cases a hand-
+ * edited text file invites: comments, blank lines, stray whitespace, duplicate
+ * and overlapping globs (where deny-wins must resolve), and section ordering.
+ * Each fixture is driven through BOTH resolvers (bash via MANIFEST_FILE, TS via
+ * parseManifest) and must agree AND land on the expected ownership. Any
+ * divergence here means the format itself is unsafe and must be fixed/converted.
+ */
+describe.skipIf(!hasBash)('bash ↔ TS manifest format-edge parity (§6.1, Decision 1)', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'mf-parity-'));
+  afterAll(() => rmSync(tmp, { recursive: true, force: true }));
+
+  let fixtureSeq = 0;
+  function writeFixture(text: string): string {
+    const file = join(tmp, `manifest-${fixtureSeq++}.txt`);
+    writeFileSync(file, text);
+    return file;
+  }
+
+  // Both resolvers must agree, and on the expected value, for every probe.
+  function expectParity(text: string, cases: ReadonlyArray<readonly [string, string]>): void {
+    const file = writeFixture(text);
+    const manifest = parseManifest(text);
+    for (const [path, expected] of cases) {
+      const ts = resolveOwnership(manifest, path);
+      const bash = bashResolveWith(file, path);
+      expect(bash, `bash disagrees with TS on ${path}`).toBe(ts);
+      expect(ts, `ownership of ${path}`).toBe(expected);
+    }
+  }
+
+  it('tolerates comments, blank lines, and leading/trailing whitespace identically', () => {
+    // Entries and headers are padded with spaces/tabs; comments and blanks are
+    // interleaved. Both resolvers must trim and ignore them the same way.
+    const text = [
+      '# leading comment',
+      '   ',
+      '\t[framework]  ',
+      '   tools/**   ',
+      '# mid-section comment',
+      '',
+      '\tguides/**\t',
+      '  [operator] ',
+      '\ttools/_lib/credentials.json  ',
+      '*.local.md',
+      '',
+    ].join('\n');
+    expectParity(text, [
+      ['tools/git/pr-create.sh', 'framework'],
+      ['guides/E2E-DELIVERY.md', 'framework'],
+      ['tools/_lib/credentials.json', 'operator'], // deny-wins carve-out inside tools/**
+      ['SOUL.local.md', 'operator'],
+      ['nowhere/unknown.md', 'operator'], // negative probe: matches NO rule → operator
+    ]);
+  });
+
+  it('resolves deny-wins for overlapping and duplicate globs identically', () => {
+    // Framework claims tools/** (twice) and the overlapping tools/git/**;
+    // operator carves out tools/_lib/**. Operator must win the overlap on both.
+    const text = [
+      '[framework]',
+      'tools/**',
+      'tools/**', // duplicate — must not change resolution
+      'tools/git/**', // overlaps tools/**
+      '[operator]',
+      'tools/_lib/**',
+    ].join('\n');
+    expectParity(text, [
+      ['tools/git/pr-create.sh', 'framework'],
+      ['tools/other.sh', 'framework'],
+      ['tools/_lib/credentials.json', 'operator'], // deny-wins over both framework globs
+      ['tools/_lib/nested/deep.json', 'operator'],
+    ]);
+  });
+
+  it('is independent of section and glob ordering', () => {
+    // Same rule set, operator section first and entries reordered. Resolution
+    // must be identical because deny-wins checks all operator globs before any
+    // framework glob — order within or between sections cannot matter.
+    const forward = [
+      '[framework]',
+      'guides/**',
+      'tools/**',
+      '[operator]',
+      'tools/_lib/credentials.json',
+      '*.local.md',
+    ].join('\n');
+    const reversed = [
+      '[operator]',
+      '*.local.md',
+      'tools/_lib/credentials.json',
+      '[framework]',
+      'tools/**',
+      'guides/**',
+    ].join('\n');
+    const probes: ReadonlyArray<readonly [string, string]> = [
+      ['tools/git/pr-create.sh', 'framework'],
+      ['guides/E2E-DELIVERY.md', 'framework'],
+      ['tools/_lib/credentials.json', 'operator'],
+      ['SOUL.local.md', 'operator'],
+      ['unanticipated/path.md', 'operator'],
+    ];
+    expectParity(forward, probes);
+    expectParity(reversed, probes);
+    // And the two orderings agree path-for-path on both resolvers.
+    const fFile = writeFixture(forward);
+    const rFile = writeFixture(reversed);
+    for (const [path] of probes) {
+      expect(bashResolveWith(fFile, path)).toBe(bashResolveWith(rFile, path));
+    }
+  });
+
+  it('defaults an unmatched path to operator on both resolvers (UNKNOWN → operator)', () => {
+    // A manifest that names only a narrow framework slice. Everything else —
+    // including paths under no rule at all — must fail safe to operator.
+    const text = ['[framework]', 'guides/**', '[operator]', 'agents/**'].join('\n');
+    expectParity(text, [
+      ['guides/x.md', 'framework'],
+      ['agents/coder0.conf', 'operator'],
+      ['totally/unlisted/file.txt', 'operator'], // negative probe
+      ['fleet/run/sessions/ledger.json', 'operator'], // unlisted → operator
+      ['README.md', 'operator'],
+    ]);
+  });
+});
+
+/**
+ * Failure-mode parity (#791 B2/B3). A bad manifest is the dangerous case: if the
+ * two resolvers DISAGREED on rejection — one throwing while the other quietly
+ * resolved everything to operator — an upgrade could fail loud on one code path
+ * and no-op on the other. So for every malformed/empty/missing manifest, BOTH
+ * must reject: TS throws, and the bash CLI exits non-zero with a stderr message.
+ */
+describe.skipIf(!hasBash)('bash ↔ TS manifest failure-mode parity (§6.1, B2/B3)', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'mf-failmode-'));
+  afterAll(() => rmSync(tmp, { recursive: true, force: true }));
+
+  let seq = 0;
+  function writeFixture(text: string): string {
+    const file = join(tmp, `bad-manifest-${seq++}.txt`);
+    writeFileSync(file, text);
+    return file;
+  }
+
+  // TS throws AND bash CLI exits non-zero with a non-empty stderr — identical rejection.
+  function expectBothReject(label: string, manifestFile: string): void {
+    expect(() => parseManifestFile(manifestFile), `TS accepted ${label}`).toThrow();
+    const cli = bashCli(manifestFile);
+    expect(cli.status, `bash did not exit non-zero for ${label}`).not.toBe(0);
+    expect(cli.stderr.trim().length, `bash was silent for ${label}`).toBeGreaterThan(0);
+  }
+
+  // Read the file for the TS side the same way loadManifest does, so both halves
+  // see identical bytes (loadManifest keys off a directory, not an arbitrary file).
+  function parseManifestFile(file: string): void {
+    parseManifest(readFileSync(file, 'utf-8'));
+  }
+
+  it('both reject a completely empty manifest', () => {
+    expectBothReject('empty', writeFixture(''));
+  });
+
+  it('both reject a comment/blank-only manifest', () => {
+    expectBothReject('comment-only', writeFixture('# header only\n\n   \n'));
+  });
+
+  it('both reject an operator-only manifest (zero framework paths)', () => {
+    expectBothReject('operator-only', writeFixture('[operator]\nSOUL.md\n*.local.md\n'));
+  });
+
+  it('both reject a [framework] section with no entries', () => {
+    expectBothReject('empty-framework-section', writeFixture('[framework]\n[operator]\nSOUL.md\n'));
+  });
+
+  it('both reject a [framework] entry that normalizes to an empty glob (/)', () => {
+    expectBothReject('root-slash-framework', writeFixture('[framework]\n/\n'));
+  });
+
+  it('both reject a [framework] entry that normalizes to nothing (./)', () => {
+    expectBothReject('dot-slash-framework', writeFixture('[framework]\n./\n[operator]\nSOUL.md\n'));
+  });
+
+  it('both reject [framework] entries that are only bare dot segments', () => {
+    expectBothReject('bare-dot-framework', writeFixture('[framework]\n.\n..\n'));
+  });
+
+  it('both reject an entry that appears before any section header', () => {
+    expectBothReject('entry-before-header', writeFixture('stray.md\n[framework]\nguides/**\n'));
+  });
+
+  it('both reject an unknown section header', () => {
+    expectBothReject('unknown-header', writeFixture('[bogus]\nx\n'));
+  });
+
+  it('both reject a missing manifest file (fail-closed, not empty result)', () => {
+    const missing = join(tmp, 'does-not-exist.txt');
+    // TS: loadManifest would throw a read error; here read-then-parse throws on read.
+    expect(() => parseManifestFile(missing)).toThrow();
+    const cli = bashCli(missing);
+    expect(cli.status).not.toBe(0);
+    expect(cli.stderr.trim().length).toBeGreaterThan(0);
+  });
+});

packages/mosaic/src/framework/manifest.spec.ts

@@ -0,0 +1,327 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  parseManifest,
+  loadManifest,
+  matchGlob,
+  resolveOwnership,
+  frameworkSubtreeRoots,
+  planPrune,
+  ManifestError,
+  type FrameworkManifest,
+} from './manifest.js';
+
+const FRAMEWORK_ROOT = fileURLToPath(new URL('../../framework', import.meta.url));
+
+const SAMPLE = `
+# comment
+[framework]
+CONSTITUTION.md
+guides/**
+tools/**
+
+[operator]
+SOUL.md
+*.local.md
+agents/**
+tools/_lib/credentials.json
+`;
+
+describe('parseManifest', () => {
+  it('splits entries into framework and operator sections, ignoring comments/blanks', () => {
+    const m = parseManifest(SAMPLE);
+    expect(m.framework).toEqual(['CONSTITUTION.md', 'guides/**', 'tools/**']);
+    expect(m.operator).toEqual([
+      'SOUL.md',
+      '*.local.md',
+      'agents/**',
+      'tools/_lib/credentials.json',
+    ]);
+  });
+
+  it('rejects an entry that appears before any section header', () => {
+    expect(() => parseManifest('stray.md\n[framework]\n')).toThrow(/before any \[section\]/);
+  });
+
+  it('rejects an unknown section header', () => {
+    expect(() => parseManifest('[bogus]\nx\n')).toThrow(/Unknown manifest section/);
+  });
+});
+
+// Fail-closed parsing/loading (#791 B2/B3). An empty, comment-only, operator-only,
+// or unreadable manifest must NOT resolve to "framework owns nothing" (which would
+// make an upgrade a silent no-op). Both must throw so finalizeStage surfaces the
+// abort instead of reporting "Installation complete". The bash reader rejects the
+// same inputs — asserted for parity in manifest-parity.spec.ts.
+describe('parseManifest / loadManifest fail closed on empty or unreadable input', () => {
+  it('throws on a completely empty manifest', () => {
+    expect(() => parseManifest('')).toThrow(/no \[framework\] paths/);
+  });
+
+  it('throws on a comment- and blank-only manifest (no entries at all)', () => {
+    expect(() => parseManifest('# just a header comment\n\n   \n')).toThrow(
+      /no \[framework\] paths/,
+    );
+  });
+
+  it('throws when only an [operator] section is present (zero framework paths)', () => {
+    expect(() => parseManifest('[operator]\nSOUL.md\n*.local.md\n')).toThrow(
+      /no \[framework\] paths/,
+    );
+  });
+
+  it('throws on a [framework] header with no entries beneath it', () => {
+    expect(() => parseManifest('[framework]\n\n[operator]\nSOUL.md\n')).toThrow(
+      /no \[framework\] paths/,
+    );
+  });
+
+  // Degenerate framework entries that pass the length check but normalize to a
+  // glob matching nothing — the manifest would silently protect the whole tree
+  // as operator (#791 blocker-B). Both `/` and `./` normalize to '' ; `.`/`..`
+  // are bare-dot segments.
+  it.each([['/'], ['./'], ['.'], ['..'], ['/\n./']])(
+    'throws when the only [framework] entry (%j) normalizes to nothing usable',
+    (entry) => {
+      expect(() => parseManifest(`[framework]\n${entry}\n`)).toThrow(
+        /no usable \[framework\] paths/,
+      );
+    },
+  );
+
+  it('accepts a wildcard-only framework glob (** is usable)', () => {
+    expect(() => parseManifest('[framework]\n**\n')).not.toThrow();
+  });
+
+  it('loadManifest throws a clear fail-closed error when the manifest file is missing', () => {
+    const missingRoot = fileURLToPath(new URL('./__no_such_framework_root__', import.meta.url));
+    expect(() => loadManifest(missingRoot)).toThrow(/Cannot read framework manifest/);
+  });
+
+  // The distinct error type is what lets finalizeStage tell a pre-sync validation
+  // abort (nothing written) from a mid-sync filesystem failure (#791 blocker-C).
+  it('every fail-closed rejection is a ManifestError', () => {
+    expect(() => parseManifest('')).toThrow(ManifestError);
+    expect(() => parseManifest('[operator]\nSOUL.md\n')).toThrow(ManifestError);
+    expect(() => parseManifest('[framework]\n/\n')).toThrow(ManifestError);
+    expect(() => parseManifest('[bogus]\nx\n')).toThrow(ManifestError);
+    expect(() => parseManifest('stray.md\n[framework]\n')).toThrow(ManifestError);
+    const missingRoot = fileURLToPath(new URL('./__no_such_framework_root__', import.meta.url));
+    expect(() => loadManifest(missingRoot)).toThrow(ManifestError);
+  });
+});
+
+describe('matchGlob', () => {
+  it('matches an exact file', () => {
+    expect(matchGlob('CONSTITUTION.md', 'CONSTITUTION.md')).toBe(true);
+    expect(matchGlob('CONSTITUTION.md', 'AGENTS.md')).toBe(false);
+  });
+
+  it('treats a bare directory entry as covering its descendants', () => {
+    expect(matchGlob('memory', 'memory')).toBe(true);
+    expect(matchGlob('memory', 'memory/notes.md')).toBe(true);
+    expect(matchGlob('memory', 'memoryfoo')).toBe(false);
+  });
+
+  it('** matches any depth including the root itself', () => {
+    expect(matchGlob('agents/**', 'agents')).toBe(true);
+    expect(matchGlob('agents/**', 'agents/a.conf')).toBe(true);
+    expect(matchGlob('agents/**', 'agents/nested/deep.conf')).toBe(true);
+    expect(matchGlob('agents/**', 'agentsX')).toBe(false);
+  });
+
+  it('* stays within a single segment', () => {
+    expect(matchGlob('*.local.md', 'SOUL.local.md')).toBe(true);
+    expect(matchGlob('*.local.md', 'a/SOUL.local.md')).toBe(false);
+  });
+});
+
+describe('resolveOwnership (deny-wins + fail-safe)', () => {
+  const m = parseManifest(SAMPLE);
+
+  it('operator globs win over framework globs (carve-out inside a framework subtree)', () => {
+    expect(resolveOwnership(m, 'tools/_lib/credentials.json')).toBe('operator');
+    expect(resolveOwnership(m, 'tools/git/pr-create.sh')).toBe('framework');
+  });
+
+  it('framework-declared paths resolve to framework', () => {
+    expect(resolveOwnership(m, 'guides/E2E-DELIVERY.md')).toBe('framework');
+    expect(resolveOwnership(m, 'CONSTITUTION.md')).toBe('framework');
+  });
+
+  it('UNKNOWN paths default to operator (the #791 root-cause guarantee)', () => {
+    expect(resolveOwnership(m, 'agents/coder0.conf')).toBe('operator'); // declared
+    expect(resolveOwnership(m, 'harvester/sop.md')).toBe('operator'); // undeclared → fail-safe
+    expect(resolveOwnership(m, 'totally-unknown-dir/x')).toBe('operator');
+    expect(resolveOwnership(m, 'random-root-file.md')).toBe('operator');
+  });
+});
+
+describe('planPrune (pure prune planner)', () => {
+  const m = parseManifest(SAMPLE);
+
+  it('prunes a retired framework file inside a shipped subtree', () => {
+    const del = planPrune({
+      manifest: m,
+      targetPaths: ['guides/OLD.md', 'guides/KEEP.md'],
+      sourcePaths: ['guides/KEEP.md'],
+    });
+    expect(del).toEqual(['guides/OLD.md']);
+  });
+
+  it('never prunes operator-reserved paths even when absent from source', () => {
+    const del = planPrune({
+      manifest: m,
+      targetPaths: ['agents/coder0.conf', 'tools/_lib/credentials.json', 'SOUL.local.md'],
+      sourcePaths: [],
+    });
+    expect(del).toEqual([]);
+  });
+
+  it('never prunes UNKNOWN paths outside every framework subtree (fail-safe)', () => {
+    const del = planPrune({
+      manifest: m,
+      targetPaths: ['harvester/sop.md', 'my-fleet.yaml', 'unknown-dir/deep/x'],
+      sourcePaths: [],
+    });
+    expect(del).toEqual([]);
+  });
+
+  it('never prunes single-file framework entries (reconcile-managed, not in subtree)', () => {
+    const del = planPrune({ manifest: m, targetPaths: ['CONSTITUTION.md'], sourcePaths: [] });
+    expect(del).toEqual([]);
+  });
+
+  it('property: delete-set ⊆ {framework-owned ∧ in-target ∧ not-in-source} and ∩ operator = ∅', () => {
+    const operatorish = [
+      'agents/a.conf',
+      'policy/p.md',
+      'SOUL.local.md',
+      'memory/m.md',
+      'tools/_lib/credentials.json',
+      'harvester/sop.md',
+      'unknown-top/x',
+      'another-unknown/deep/y.txt',
+    ];
+    const frameworkish = ['guides/A.md', 'guides/sub/B.md', 'tools/git/x.sh'];
+    const targetPaths = [...operatorish, ...frameworkish];
+    const del = planPrune({ manifest: m, targetPaths, sourcePaths: [] });
+
+    for (const p of del) {
+      expect(resolveOwnership(m, p)).toBe('framework');
+      expect(targetPaths).toContain(p);
+    }
+    // No operator/unknown path ever appears in the delete-set.
+    for (const p of operatorish) expect(del).not.toContain(p);
+  });
+});
+
+// The #797 Runtime Session Ledger lives at fleet/run/sessions/. Today it is safe
+// twice over: it matches the explicit `fleet/run/**` operator carve-out AND, even
+// without it, the UNKNOWN→operator fail-safe. This test isolates the CARVE-OUT's
+// load-bearing value by simulating a future framework author who broadens fleet
+// ownership to `fleet/**`: without the operator carve-out the ledger would resolve
+// framework and be pruned; deny-wins is what keeps it protected. If deleting the
+// `fleet/run/**` line ever stops turning this test red, the carve-out has silently
+// stopped mattering — which is exactly the #797 regression we are gating against.
+describe('fleet/run/** carve-out is load-bearing for the #797 ledger (deny-wins)', () => {
+  const LEDGER = ['fleet/run/sessions/events.ndjson', 'fleet/run/sessions/ledger.json'];
+  // A framework that (hypothetically) ships all of fleet/** as a subtree.
+  const withoutCarveOut: FrameworkManifest = {
+    framework: ['fleet/**'],
+    operator: [],
+  };
+  const withCarveOut: FrameworkManifest = {
+    framework: ['fleet/**'],
+    operator: ['fleet/run/**'],
+  };
+
+  it('RED without the carve-out: the ledger resolves framework and is pruned', () => {
+    for (const p of LEDGER) expect(resolveOwnership(withoutCarveOut, p)).toBe('framework');
+    const del = planPrune({ manifest: withoutCarveOut, targetPaths: LEDGER, sourcePaths: [] });
+    expect(del.sort()).toEqual([...LEDGER].sort());
+  });
+
+  it('GREEN with the carve-out: deny-wins makes the ledger operator and unprunable', () => {
+    for (const p of LEDGER) expect(resolveOwnership(withCarveOut, p)).toBe('operator');
+    const del = planPrune({ manifest: withCarveOut, targetPaths: LEDGER, sourcePaths: [] });
+    expect(del).toEqual([]);
+  });
+
+  it('the SHIPPED manifest reserves fleet/run/** so the ledger is operator-owned', () => {
+    const shipped = loadManifest(FRAMEWORK_ROOT);
+    for (const p of LEDGER) expect(resolveOwnership(shipped, p)).toBe('operator');
+    // And it is structurally unreachable by pruning even if it were in a subtree.
+    expect(planPrune({ manifest: shipped, targetPaths: LEDGER, sourcePaths: [] })).toEqual([]);
+  });
+});
+
+describe('frameworkSubtreeRoots', () => {
+  it('returns only the /** subtree roots, not single-file entries', () => {
+    const m = parseManifest(SAMPLE);
+    expect(frameworkSubtreeRoots(m)).toEqual(['guides', 'tools']);
+  });
+});
+
+// ── SSOT manifest: shipped-file completeness (§6.2) ──────────────────────────
+// A newly-shipped framework file must not silently fall outside the manifest —
+// if it did, the updater could neither guarantee it as framework-owned nor
+// prune it when retired. Every file the framework actually ships must resolve
+// to `framework` (except the defaults/{SOUL,USER}.md identity seeds, which are
+// operator-owned by design).
+describe('manifest completeness against shipped framework tree', () => {
+  const manifest = loadManifest(FRAMEWORK_ROOT);
+
+  const IGNORED_TOP = new Set(['.git', 'node_modules']);
+  // Framework-shipped files that are operator-owned by design: the identity
+  // seeds under defaults/, and the `.gitkeep` placeholder that lets the empty
+  // operator-owned memory/ directory exist in git.
+  function isOperatorShipped(rel: string): boolean {
+    if (rel === 'defaults/SOUL.md' || rel === 'defaults/USER.md') return true;
+    if (rel.startsWith('memory/')) return true;
+    return false;
+  }
+
+  function walk(dir: string): string[] {
+    const out: string[] = [];
+    for (const entry of readdirSync(dir)) {
+      const abs = join(dir, entry);
+      const rel = relative(FRAMEWORK_ROOT, abs);
+      if (IGNORED_TOP.has(rel)) continue;
+      if (statSync(abs).isDirectory()) out.push(...walk(abs));
+      else out.push(rel);
+    }
+    return out;
+  }
+
+  it('every shipped framework file resolves to framework ownership', () => {
+    const shipped = walk(FRAMEWORK_ROOT);
+    const misclassified = shipped.filter(
+      (p) => !isOperatorShipped(p) && resolveOwnership(manifest, p) !== 'framework',
+    );
+    expect(misclassified).toEqual([]);
+  });
+
+  it('the operator-owned surface from #791 resolves to operator', () => {
+    const operatorPaths = [
+      'agents/coder0.conf',
+      'fleet/agents/coder0.env',
+      'memory/note.md',
+      'policy/custom.md',
+      'SOUL.local.md',
+      'USER.local.md',
+      'STANDARDS.local.md',
+      'tools/_lib/credentials.json',
+      'fleet/roster.yaml',
+      'fleet/roster.json',
+      'fleet/run/coder0.hb',
+      'fleet/backlog/data.db',
+      'fleet/roles.local/custom.md',
+    ];
+    for (const p of operatorPaths) {
+      expect(resolveOwnership(manifest, p), p).toBe('operator');
+    }
+  });
+});

packages/mosaic/src/framework/manifest.ts

@@ -0,0 +1,248 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Framework path-ownership manifest (#791).
+ *
+ * The updater must operate from an explicit framework-owned path manifest and
+ * NEVER write outside it. This module is the TypeScript reader for the shared
+ * SSOT manifest (`packages/mosaic/framework/framework-manifest.txt`) that the
+ * bash installer also consumes. Keeping both paths on one data file is what
+ * closes the two-copies-drift failure class (see #631 → #791).
+ *
+ * Everything here is pure (parse + resolve + plan) so the ownership guarantee
+ * is unit- and property-testable without touching the filesystem.
+ */
+
+export type Ownership = 'framework' | 'operator';
+
+/**
+ * Thrown when the manifest is missing, empty, or malformed. A distinct type lets
+ * callers (e.g. finalizeStage) tell a pre-sync validation abort — where NO files
+ * were touched — apart from a generic mid-sync filesystem failure, and message
+ * the user accurately (#791 blocker-C).
+ */
+export class ManifestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ManifestError';
+  }
+}
+
+export interface FrameworkManifest {
+  /** Globs the updater MAY create/overwrite, and prune only when retired. */
+  readonly framework: readonly string[];
+  /** Globs the updater must NEVER write over or prune. Win over `framework`. */
+  readonly operator: readonly string[];
+}
+
+type Section = 'framework' | 'operator' | null;
+
+/**
+ * Parse the line-oriented manifest text. `#` comments and blank lines are
+ * ignored; `[framework]` / `[operator]` headers switch the active section.
+ * Lines before any header are rejected — the format must be explicit.
+ */
+export function parseManifest(text: string): FrameworkManifest {
+  const framework: string[] = [];
+  const operator: string[] = [];
+  let section: Section = null;
+
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i] ?? '';
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+
+    if (line === '[framework]') {
+      section = 'framework';
+      continue;
+    }
+    if (line === '[operator]') {
+      section = 'operator';
+      continue;
+    }
+    if (line.startsWith('[')) {
+      throw new ManifestError(`Unknown manifest section header on line ${i + 1}: ${line}`);
+    }
+
+    if (section === null) {
+      throw new ManifestError(
+        `Manifest entry before any [section] header on line ${i + 1}: ${line}`,
+      );
+    }
+    (section === 'framework' ? framework : operator).push(line);
+  }
+
+  // Fail CLOSED on an empty or comment-only manifest. A manifest with zero
+  // framework-owned globs would make resolveOwnership() return `operator` for
+  // every path: an upgrade would prune nothing and refresh nothing — a silent
+  // no-op indistinguishable from success. Refuse loudly instead, mirroring the
+  // bash reader's `manifest_load` guard so both halves reject it identically (#791 B2).
+  if (framework.length === 0) {
+    throw new ManifestError(
+      'Framework manifest defines no [framework] paths — refusing to proceed (empty or malformed manifest).',
+    );
+  }
+
+  // Fail CLOSED on framework entries that normalize to nothing usable. A manifest
+  // like `[framework]\n/` or `[framework]\n./` passes the length check above but
+  // every entry normalizes to an empty (or bare-dot) glob that matches no real
+  // path — so the compiled framework matcher is empty and every path resolves
+  // `operator`: the same silent no-op as an empty manifest. Require at least one
+  // entry with a real, non-dot character (the bash reader applies the identical
+  // `[^/.]` test, so both halves reject these inputs together — #791 blocker-B).
+  if (!framework.some(isUsableFrameworkGlob)) {
+    throw new ManifestError(
+      'Framework manifest defines no usable [framework] paths (every entry is empty or a bare dot segment) — refusing to proceed (malformed manifest).',
+    );
+  }
+
+  return { framework, operator };
+}
+
+/**
+ * A framework glob is usable only if, once normalized, it still contains a
+ * character other than `/` or `.` — i.e. it names a real path segment or a
+ * wildcard. `''`, `/`, `./`, `.`, `..` are all unusable (they compile to a glob
+ * that matches nothing). Kept byte-compatible with the bash `[[ =~ [^/.] ]]`
+ * test so TS and bash accept/reject exactly the same manifests.
+ */
+function isUsableFrameworkGlob(glob: string): boolean {
+  return /[^/.]/.test(normalizeRel(glob));
+}
+
+/** Read and parse the manifest from a framework root directory. */
+export function loadManifest(frameworkRoot: string): FrameworkManifest {
+  const file = `${frameworkRoot}/framework-manifest.txt`;
+  let text: string;
+  try {
+    text = readFileSync(file, 'utf-8');
+  } catch (err) {
+    // A missing/unreadable manifest must fail closed with a clear message, not a
+    // raw ENOENT that a caller might mistake for an empty result set (#791 B2/B3).
+    throw new ManifestError(
+      `Cannot read framework manifest at ${file}: ${(err as Error).message} — refusing to sync (fail-closed).`,
+    );
+  }
+  return parseManifest(text);
+}
+
+/**
+ * Match a mosaic-home-relative POSIX path against one glob.
+ *
+ * Supported: `**` (any depth, including zero segments) and `*` (any run of
+ * characters within a single segment, not crossing `/`). A glob with no
+ * wildcard matches either the exact path OR any path beneath it (so a bare
+ * directory entry like `memory` covers `memory/notes.md`).
+ */
+export function matchGlob(glob: string, relPath: string): boolean {
+  const path = normalizeRel(relPath);
+  const pattern = normalizeRel(glob);
+  if (pattern === '') return false;
+
+  if (!pattern.includes('*')) {
+    // Exact file, or any descendant of a bare directory prefix.
+    return path === pattern || path.startsWith(`${pattern}/`);
+  }
+
+  const re = new RegExp(`^${globToRegExpBody(pattern)}$`);
+  return re.test(path);
+}
+
+/** True if the path matches any glob in the list. */
+export function matchesAny(globs: readonly string[], relPath: string): boolean {
+  return globs.some((g) => matchGlob(g, relPath));
+}
+
+/**
+ * Resolve ownership of a mosaic-home-relative path (deny-wins / fail-safe):
+ * operator globs win, then framework globs, else operator by default.
+ */
+export function resolveOwnership(manifest: FrameworkManifest, relPath: string): Ownership {
+  if (matchesAny(manifest.operator, relPath)) return 'operator';
+  if (matchesAny(manifest.framework, relPath)) return 'framework';
+  return 'operator';
+}
+
+/**
+ * The set of `[framework]` subtree roots that pruning is allowed to descend
+ * into (glob entries of the form `dir/**`). Single-file framework entries
+ * (e.g. `CONSTITUTION.md`) are reconcile-managed and never pruned.
+ */
+export function frameworkSubtreeRoots(manifest: FrameworkManifest): string[] {
+  const roots: string[] = [];
+  for (const g of manifest.framework) {
+    if (g.endsWith('/**')) roots.push(g.slice(0, -3));
+  }
+  return roots;
+}
+
+export interface PrunePlanInput {
+  readonly manifest: FrameworkManifest;
+  /** Mosaic-home-relative paths currently present in the target. */
+  readonly targetPaths: readonly string[];
+  /** Mosaic-home-relative paths the framework currently ships (source). */
+  readonly sourcePaths: readonly string[];
+}
+
+/**
+ * Pure prune planner — the testable seam of the #791 fix.
+ *
+ * Returns the delete-set: target paths that are framework-owned, live inside a
+ * shipped framework subtree, and are absent from the current source (retired
+ * framework files). By construction the result never contains an operator-owned
+ * or unknown path: those either resolve to `operator` or fall outside every
+ * framework subtree root, so they are structurally unreachable by pruning.
+ */
+export function planPrune(input: PrunePlanInput): string[] {
+  const { manifest, targetPaths, sourcePaths } = input;
+  const source = new Set(sourcePaths.map(normalizeRel));
+  const roots = frameworkSubtreeRoots(manifest);
+
+  const deleteSet: string[] = [];
+  for (const raw of targetPaths) {
+    const path = normalizeRel(raw);
+    if (source.has(path)) continue; // still shipped — keep
+    if (resolveOwnership(manifest, path) !== 'framework') continue; // operator/unknown — never prune
+    if (!roots.some((root) => path === root || path.startsWith(`${root}/`))) continue; // outside shipped subtrees
+    deleteSet.push(path);
+  }
+  return deleteSet;
+}
+
+function normalizeRel(p: string): string {
+  return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+/** Translate a glob body (already normalized) into a RegExp source fragment. */
+function globToRegExpBody(pattern: string): string {
+  let out = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === undefined) continue;
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**` — any depth. `a/**` must also match the bare root `a`, so when a
+        // literal `/` was just emitted, make it optional along with the rest.
+        i++;
+        let trailingSlash = false;
+        if (pattern[i + 1] === '/') {
+          i++;
+          trailingSlash = true;
+        }
+        if (out.endsWith('/')) {
+          out = `${out.slice(0, -1)}(?:/.*)?`;
+        } else if (trailingSlash) {
+          out += '(?:.*/)?';
+        } else {
+          out += '.*';
+        }
+      } else {
+        out += '[^/]*';
+      }
+    } else {
+      out += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return out;
+}

packages/mosaic/src/platform/file-ops.ts

@@ -62,16 +62,28 @@ function rotateBackups(filePath: string): void {
 /**
  * Sync a source directory to a target, with optional preserve paths.
  * Replaces the rsync/cp logic from install.sh.
+ *
+ * `isOperatorOwned` is the #791 ownership guard: when supplied, any source path
+ * it flags as operator-owned is never copied (the framework must never write an
+ * operator path). Callers derive it from the shared framework manifest so the TS
+ * and bash sync paths obey one source of truth. This copy is non-destructive —
+ * it never deletes a target file — so honoring the guard is sufficient to leave
+ * operator config untouched.
  */
 export function syncDirectory(
   source: string,
   target: string,
-  options: { preserve?: string[]; excludeGit?: boolean } = {},
+  options: {
+    preserve?: string[];
+    excludeGit?: boolean;
+    isOperatorOwned?: (relPath: string) => boolean;
+  } = {},
 ): void {
   // Guard: source and target are the same directory — nothing to sync
   if (resolve(source) === resolve(target)) return;
 
   const preserveSet = new Set(options.preserve ?? []);
+  const isOperatorOwned = options.isOperatorOwned ?? (() => false);
 
   // Collect files from source
   function copyRecursive(src: string, dest: string, relBase: string): void {
@@ -86,7 +98,7 @@ export function syncDirectory(
       if (options.excludeGit && (dirName === '.git' || relPath.includes('/.git'))) return;
 
       // Skip preserved paths at top level
-      if (preserveSet.has(relPath) && existsSync(dest)) return;
+      if (relPath !== '' && preserveSet.has(relPath) && existsSync(dest)) return;
 
       mkdirSync(dest, { recursive: true });
       for (const entry of readdirSync(src)) {
@@ -101,6 +113,10 @@ export function syncDirectory(
       // Skip preserved files at top level
       if (preserveSet.has(relPath) && existsSync(dest)) return;
 
+      // #791: never write an operator-owned path (the framework owns only its
+      // own files; unknown paths resolve to operator and are skipped too).
+      if (isOperatorOwned(relPath)) return;
+
       mkdirSync(dirname(dest), { recursive: true });
       copyFileSync(src, dest);
     }

packages/mosaic/src/runtime/update-checker.reseed.spec.ts

@@ -1,5 +1,18 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -11,8 +24,8 @@ import {
   readInstalledFrameworkVersion,
   readBundledFrameworkVersion,
   checkFrameworkDrift,
+  repairFleetCommsTools,
 } from './update-checker.js';
-import { existsSync, readFileSync } from 'node:fs';
 
 /**
  * F3-m3 / R13: `mosaic update` re-seeds the framework + (opt-in) relaunches
@@ -66,6 +79,7 @@ describe('readRosterAgentNames', () => {
       join(home, 'fleet', 'roster.yaml'),
       [
         'version: 1',
+        'transport: tmux',
         'agents:',
         '  - name: orchestrator',
         '    runtime: pi',
@@ -77,6 +91,212 @@ describe('readRosterAgentNames', () => {
     );
     expect(readRosterAgentNames(home)).toEqual(['orchestrator', 'coder0', 'reviewer-1']);
   });
+
+  it('extracts agent names from a JSON-only roster', () => {
+    mkdirSync(join(home, 'fleet'), { recursive: true });
+    writeFileSync(
+      join(home, 'fleet', 'roster.json'),
+      JSON.stringify({
+        version: 1,
+        transport: 'tmux',
+        agents: [
+          { name: 'orchestrator', runtime: 'pi', class: 'orchestrator' },
+          { name: 'coder0', runtime: 'claude', class: 'worker' },
+        ],
+      }),
+    );
+    expect(readRosterAgentNames(home)).toEqual(['orchestrator', 'coder0']);
+  });
+});
+
+describe('repairFleetCommsTools', () => {
+  let root: string;
+  let framework: string;
+  let home: string;
+  const toolsContent = '# tools\n<!-- fleet-comms-contract: 1 -->\n';
+  const helperContent = '#!/bin/sh\nexit 0\n';
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'mosaic-tools-repair-'));
+    framework = join(root, 'framework');
+    home = join(root, 'home');
+    mkdirSync(join(framework, 'defaults'), { recursive: true });
+    mkdirSync(join(framework, 'tools', 'tmux'), { recursive: true });
+    writeFileSync(join(framework, 'defaults', 'TOOLS.md'), toolsContent);
+    const helper = join(framework, 'tools', 'tmux', 'agent-send.sh');
+    writeFileSync(helper, helperContent);
+    chmodSync(helper, 0o755);
+  });
+
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  it('restores a partially deleted current-version installation without package updates', () => {
+    mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
+    writeFileSync(join(home, 'TOOLS.md'), toolsContent);
+
+    const result = repairFleetCommsTools(framework, home);
+
+    expect(result).toMatchObject({ ok: true, changed: true });
+    expect(readFileSync(join(home, 'TOOLS.md'), 'utf8')).toBe(toolsContent);
+    expect(readFileSync(join(home, 'tools', 'tmux', 'agent-send.sh'), 'utf8')).toBe(helperContent);
+    expect(lstatSync(join(home, 'tools', 'tmux', 'agent-send.sh')).mode & 0o111).not.toBe(0);
+  });
+
+  it('creates a digest-qualified no-clobber backup and is idempotent', () => {
+    mkdirSync(home, { recursive: true });
+    const stale = '# user tools\n';
+    writeFileSync(join(home, 'TOOLS.md'), stale);
+
+    const first = repairFleetCommsTools(framework, home);
+    expect(first).toMatchObject({ ok: true, changed: true });
+    expect(first.backupPath).toMatch(/\.pre-fleet-comms-[a-f0-9]{16}\.bak$/);
+    expect(readFileSync(first.backupPath!, 'utf8')).toBe(stale);
+
+    const second = repairFleetCommsTools(framework, home);
+    expect(second).toEqual({ ok: true, changed: false, backupPath: undefined });
+    expect(readFileSync(first.backupPath!, 'utf8')).toBe(stale);
+  });
+
+  it('rejects an installed helper symlink without modifying its target', () => {
+    mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
+    writeFileSync(join(home, 'TOOLS.md'), toolsContent);
+    const target = join(root, 'external-helper');
+    writeFileSync(target, 'do not touch\n');
+    symlinkSync(target, join(home, 'tools', 'tmux', 'agent-send.sh'));
+
+    const result = repairFleetCommsTools(framework, home);
+
+    expect(result).toMatchObject({ ok: false, changed: false });
+    expect(result.reason).toContain('symbolic link');
+    expect(readFileSync(target, 'utf8')).toBe('do not touch\n');
+    expect(lstatSync(join(home, 'tools', 'tmux', 'agent-send.sh')).isSymbolicLink()).toBe(true);
+  });
+
+  it('refuses a helper directory before replacing stale TOOLS content', () => {
+    mkdirSync(join(home, 'tools', 'tmux', 'agent-send.sh'), { recursive: true });
+    const stale = '# user tools\n';
+    writeFileSync(join(home, 'TOOLS.md'), stale);
+
+    const result = repairFleetCommsTools(framework, home);
+
+    expect(result).toMatchObject({ ok: false, changed: false });
+    expect(result.reason).toContain('not a regular file');
+    expect(readFileSync(join(home, 'TOOLS.md'), 'utf8')).toBe(stale);
+  });
+
+  it('refuses a pre-existing digest backup whose bytes do not match', () => {
+    mkdirSync(home, { recursive: true });
+    const stale = '# user tools\n';
+    writeFileSync(join(home, 'TOOLS.md'), stale);
+    const digest = createHash('sha256').update(stale).digest('hex').slice(0, 16);
+    writeFileSync(join(home, `TOOLS.md.pre-fleet-comms-${digest}.bak`), 'collision\n');
+
+    const result = repairFleetCommsTools(framework, home);
+
+    expect(result).toMatchObject({ ok: false, changed: false });
+    expect(result.reason).toContain('backup collision');
+    expect(readFileSync(join(home, 'TOOLS.md'), 'utf8')).toBe(stale);
+  });
+
+  it('rejects a symlink in each installed destination ancestor without external writes', () => {
+    const cases = [
+      { name: 'home', prefix: join(root, 'linked-home'), suffix: '' },
+      { name: 'tools', prefix: join(root, 'real-home'), suffix: 'tools' },
+      { name: 'tmux', prefix: join(root, 'real-home'), suffix: join('tools', 'tmux') },
+    ];
+    for (const testCase of cases) {
+      const external = join(root, `external-${testCase.name}`);
+      mkdirSync(external, { recursive: true });
+      const targetHome =
+        testCase.name === 'home' ? testCase.prefix : join(root, `installed-${testCase.name}`);
+      if (testCase.name === 'home') {
+        symlinkSync(external, targetHome);
+      } else {
+        mkdirSync(targetHome, { recursive: true });
+        const linkPath = join(targetHome, testCase.suffix);
+        mkdirSync(join(linkPath, '..'), { recursive: true });
+        symlinkSync(external, linkPath);
+      }
+
+      const result = repairFleetCommsTools(framework, targetHome);
+
+      expect(result, testCase.name).toMatchObject({ ok: false, changed: false });
+      expect(result.reason, testCase.name).toContain('symbolic link');
+      expect(readdirSync(external), testCase.name).toEqual([]);
+    }
+  });
+
+  it('rolls back the backup and exact TOOLS bytes/mode when helper commit fails', () => {
+    mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
+    const staleTools = '# user tools\n';
+    const staleHelper = '#!/bin/sh\nexit 17\n';
+    writeFileSync(join(home, 'TOOLS.md'), staleTools, { mode: 0o640 });
+    writeFileSync(join(home, 'tools', 'tmux', 'agent-send.sh'), staleHelper, { mode: 0o710 });
+
+    const result = repairFleetCommsTools(framework, home, {
+      beforeCommit(which) {
+        if (which === 'helper') throw new Error('injected helper commit failure');
+      },
+    });
+
+    expect(result).toMatchObject({ ok: false, changed: false });
+    expect(result.backupPath).toBeUndefined();
+    expect(result.reason).toContain('injected helper commit failure');
+    expect(readFileSync(join(home, 'TOOLS.md'), 'utf8')).toBe(staleTools);
+    expect(statSync(join(home, 'TOOLS.md')).mode & 0o777).toBe(0o640);
+    expect(readFileSync(join(home, 'tools', 'tmux', 'agent-send.sh'), 'utf8')).toBe(staleHelper);
+    expect(statSync(join(home, 'tools', 'tmux', 'agent-send.sh')).mode & 0o777).toBe(0o710);
+    expect(readdirSync(home).filter((name) => name.includes('pre-fleet-comms'))).toEqual([]);
+    expect(
+      readdirSync(home).some((name) => name.includes('.repair-')) ||
+        readdirSync(join(home, 'tools', 'tmux')).some((name) => name.includes('.repair-')),
+    ).toBe(false);
+  });
+
+  it('rolls back initially absent destinations and created directories on commit failure', () => {
+    const result = repairFleetCommsTools(framework, home, {
+      beforeCommit(which) {
+        if (which === 'helper') throw new Error('injected absent helper failure');
+      },
+    });
+
+    expect(result).toMatchObject({ ok: false, changed: false });
+    expect(result.reason).toContain('injected absent helper failure');
+    expect(existsSync(home)).toBe(false);
+  });
+
+  it('does not persist a backup or replacement when backup commit fails', () => {
+    mkdirSync(home, { recursive: true });
+    const stale = '# user tools\n';
+    writeFileSync(join(home, 'TOOLS.md'), stale, { mode: 0o640 });
+
+    const result = repairFleetCommsTools(framework, home, {
+      beforeCommit(which) {
+        if (which === 'backup') throw new Error('injected backup commit failure');
+      },
+    });
+
+    expect(result).toMatchObject({ ok: false, changed: false });
+    expect(readFileSync(join(home, 'TOOLS.md'), 'utf8')).toBe(stale);
+    expect(statSync(join(home, 'TOOLS.md')).mode & 0o777).toBe(0o640);
+    expect(readdirSync(home).filter((name) => name.includes('pre-fleet-comms'))).toEqual([]);
+  });
+
+  it('fails before writes when bundled source paths traverse a symlink ancestor', () => {
+    const external = join(root, 'external-source');
+    mkdirSync(join(external, 'defaults'), { recursive: true });
+    mkdirSync(join(external, 'tools', 'tmux'), { recursive: true });
+    writeFileSync(join(external, 'defaults', 'TOOLS.md'), toolsContent);
+    writeFileSync(join(external, 'tools', 'tmux', 'agent-send.sh'), helperContent, { mode: 0o755 });
+    const linkedFramework = join(root, 'linked-framework');
+    symlinkSync(external, linkedFramework);
+
+    const result = repairFleetCommsTools(linkedFramework, home);
+
+    expect(result).toMatchObject({ ok: false, changed: false });
+    expect(result.reason).toContain('symbolic link');
+    expect(existsSync(home)).toBe(false);
+  });
 });
 
 describe('runFrameworkReseed', () => {

packages/mosaic/src/runtime/update-checker.ts

@@ -15,16 +15,34 @@
 
 import { execSync } from 'node:child_process';
 import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-  readdirSync,
+  closeSync,
+  constants,
   copyFileSync,
+  existsSync,
+  fchmodSync,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
 } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { parseFleetRosterV1, resolveInstalledFleetRosterPath } from '../fleet/fleet-roster-v1.js';
+import {
+  assertCanonicalContainment,
+  assertNoSymlinkAncestors,
+  ensureManagedDirectory,
+  readRegularFileSecure,
+} from '../fleet/secure-file.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -54,6 +72,10 @@ const CACHE_FILE = join(CACHE_DIR, 'update-check.json');
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 const NETWORK_TIMEOUT_MS = 5_000;
 
+function isNodeErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error && 'code' in error && error.code === code;
+}
+
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
 function npmExec(args: string, timeoutMs = NETWORK_TIMEOUT_MS): string {
@@ -466,9 +488,13 @@ export function getInstallAllCommand(outdated: PackageUpdateResult[]): string {
 // `mosaic update` installs the new npm CLI but, on its own, leaves the framework
 // files in ~/.config/mosaic/ stale — so shipped launcher/runtime changes (e.g.
 // the agent-name export + native heartbeat) never ACTIVATE until a re-seed.
-// These helpers run the package's own install.sh in sync-only mode (the P4
-// data-safe reconcile: framework-owned overwrite + backup-once; SOUL/USER/
-// *.local/credentials preserved) and, opt-in, relaunch durable agents.
+// These helpers run the package's own install.sh in sync-only mode. The re-seed
+// is manifest-driven (#791): keep mode writes ONLY framework-owned paths from the
+// shared framework-manifest.txt and prunes only retired framework files inside
+// shipped subtrees — every operator path (SOUL/USER/*.local/credentials, fleet
+// roster + agents + backlog, and anything the manifest never anticipated) is
+// left byte-identical. Contract files are still reconciled (overwrite +
+// backup-once). Opt-in, this also relaunches durable agents.
 
 /** Resolve the framework/ directory bundled in the installed package. */
 export function resolveBundledFrameworkRoot(): string {
@@ -500,6 +526,346 @@ export function buildReseedCommand(
   };
 }
 
+export interface ToolsRepairResult {
+  ok: boolean;
+  changed: boolean;
+  backupPath?: string;
+  reason?: string;
+}
+
+export interface ToolsRepairHooks {
+  beforeCommit?: (which: 'backup' | 'tools' | 'helper') => void;
+}
+
+function optionalSecureFile(
+  path: string,
+  root: string,
+): ReturnType<typeof readRegularFileSecure> | undefined {
+  try {
+    return readRegularFileSecure(path, { root });
+  } catch (error) {
+    if (isNodeErrorCode(error, 'ENOENT')) return undefined;
+    throw error;
+  }
+}
+
+function stageManagedFile(
+  root: string,
+  directory: string,
+  target: string,
+  content: Buffer,
+  mode: number,
+): string {
+  assertCanonicalContainment(root, target);
+  ensureManagedDirectory(root, directory);
+  assertNoSymlinkAncestors(target);
+  const staged = join(directory, `.${basename(target)}.repair-${process.pid}-${cryptoRandom()}`);
+  assertCanonicalContainment(root, staged);
+  const fd = openSync(
+    staged,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    writeFileSync(fd, content);
+    fchmodSync(fd, mode);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  return staged;
+}
+
+function cryptoRandom(): string {
+  return randomBytes(8).toString('hex');
+}
+
+interface ManagedOriginal {
+  path: string;
+  snapshot?: ReturnType<typeof readRegularFileSecure>;
+}
+
+function assertManagedOriginalUnchanged(original: ManagedOriginal, root: string): void {
+  if (!original.snapshot) {
+    try {
+      lstatSync(original.path);
+      throw new Error(`repair destination appeared during staging: ${original.path}`);
+    } catch (error) {
+      if (isNodeErrorCode(error, 'ENOENT')) return;
+      throw error;
+    }
+  }
+  const current = readRegularFileSecure(original.path, { root });
+  if (
+    current.dev !== original.snapshot.dev ||
+    current.ino !== original.snapshot.ino ||
+    current.mode !== original.snapshot.mode ||
+    !current.content.equals(original.snapshot.content)
+  ) {
+    throw new Error(`repair destination changed during staging: ${original.path}`);
+  }
+}
+
+function installBackupNoClobber(staged: string, target: string, root: string): void {
+  assertCanonicalContainment(root, target);
+  assertNoSymlinkAncestors(target);
+  try {
+    lstatSync(target);
+    throw new Error(`digest-qualified backup collision at ${target}`);
+  } catch (error) {
+    if (!isNodeErrorCode(error, 'ENOENT')) throw error;
+  }
+  linkSync(staged, target);
+  unlinkSync(staged);
+}
+
+function atomicInstall(staged: string, target: string, root: string): void {
+  assertCanonicalContainment(root, target);
+  assertNoSymlinkAncestors(target);
+  try {
+    const current = lstatSync(target);
+    if (current.isSymbolicLink() || !current.isFile()) {
+      throw new Error(`repair destination is not a regular file: ${target}`);
+    }
+  } catch (error) {
+    if (!isNodeErrorCode(error, 'ENOENT')) throw error;
+  }
+  renameSync(staged, target);
+}
+
+/**
+ * Explicitly repair the user-owned TOOLS contract and required helper from the
+ * bundled current framework. Existing divergent TOOLS content is preserved in
+ * a digest-qualified no-clobber backup; repeated repairs are idempotent.
+ */
+export function repairFleetCommsTools(
+  frameworkRoot = resolveBundledFrameworkRoot(),
+  mosaicHome = join(homedir(), '.config', 'mosaic'),
+  hooks: ToolsRepairHooks = {},
+): ToolsRepairResult {
+  const sourceTools = join(frameworkRoot, 'defaults', 'TOOLS.md');
+  const sourceHelper = join(frameworkRoot, 'tools', 'tmux', 'agent-send.sh');
+  const installedTools = join(mosaicHome, 'TOOLS.md');
+  const helperDirectory = join(mosaicHome, 'tools', 'tmux');
+  const installedHelper = join(helperDirectory, 'agent-send.sh');
+  let stagedBackup: string | undefined;
+  let stagedTools: string | undefined;
+  let stagedHelper: string | undefined;
+  let rollbackTools: string | undefined;
+  let rollbackHelper: string | undefined;
+  let committedBackup = false;
+  let committedTools = false;
+  let committedHelper = false;
+  let createdHome = false;
+  let createdToolsDirectory = false;
+  let createdHelperDirectory = false;
+  let backupPath: string | undefined;
+  let toolsOriginal: ManagedOriginal | undefined;
+  let helperOriginal: ManagedOriginal | undefined;
+  try {
+    const sourceToolsSnapshot = readRegularFileSecure(sourceTools, { root: frameworkRoot });
+    const sourceHelperSnapshot = readRegularFileSecure(sourceHelper, {
+      root: frameworkRoot,
+      executable: true,
+    });
+    if (!sourceToolsSnapshot.content.includes('<!-- fleet-comms-contract: 1 -->')) {
+      return { ok: false, changed: false, reason: 'bundled TOOLS contract has wrong version' };
+    }
+
+    assertCanonicalContainment(mosaicHome, installedTools);
+    assertCanonicalContainment(mosaicHome, installedHelper);
+    assertNoSymlinkAncestors(mosaicHome);
+    const homeExisted = existsSync(mosaicHome);
+    const toolsDirectory = dirname(helperDirectory);
+    const toolsDirectoryExisted = existsSync(toolsDirectory);
+    const helperDirectoryExisted = existsSync(helperDirectory);
+    if (homeExisted) {
+      const homeStat = lstatSync(mosaicHome);
+      if (homeStat.isSymbolicLink()) {
+        throw new Error(`managed root is a symbolic link: ${mosaicHome}`);
+      }
+      if (!homeStat.isDirectory()) {
+        throw new Error(`managed root is not a real directory: ${mosaicHome}`);
+      }
+    }
+
+    const installedToolsSnapshot = homeExisted
+      ? optionalSecureFile(installedTools, mosaicHome)
+      : undefined;
+    let installedHelperSnapshot: ReturnType<typeof readRegularFileSecure> | undefined;
+    let installedHelperExecutable = false;
+    if (homeExisted) {
+      try {
+        installedHelperSnapshot = readRegularFileSecure(installedHelper, {
+          root: mosaicHome,
+          executable: true,
+        });
+        installedHelperExecutable = true;
+      } catch (error) {
+        if (!isNodeErrorCode(error, 'ENOENT') && !isNodeErrorCode(error, 'EACCES')) throw error;
+        if (isNodeErrorCode(error, 'EACCES')) {
+          installedHelperSnapshot = optionalSecureFile(installedHelper, mosaicHome);
+        }
+      }
+    }
+
+    const toolsChanged = !installedToolsSnapshot?.content.equals(sourceToolsSnapshot.content);
+    const helperChanged =
+      !installedHelperExecutable ||
+      !installedHelperSnapshot?.content.equals(sourceHelperSnapshot.content);
+    if (!toolsChanged && !helperChanged) return { ok: true, changed: false };
+
+    toolsOriginal = { path: installedTools, snapshot: installedToolsSnapshot };
+    helperOriginal = { path: installedHelper, snapshot: installedHelperSnapshot };
+
+    ensureManagedDirectory(dirname(mosaicHome), mosaicHome);
+    createdHome = !homeExisted;
+    ensureManagedDirectory(mosaicHome, helperDirectory);
+    createdToolsDirectory = !toolsDirectoryExisted;
+    createdHelperDirectory = !helperDirectoryExisted;
+
+    if (toolsChanged) {
+      stagedTools = stageManagedFile(
+        mosaicHome,
+        mosaicHome,
+        installedTools,
+        sourceToolsSnapshot.content,
+        sourceToolsSnapshot.mode & 0o777,
+      );
+      if (installedToolsSnapshot) {
+        const digest = createHash('sha256')
+          .update(installedToolsSnapshot.content)
+          .digest('hex')
+          .slice(0, 16);
+        backupPath = `${installedTools}.pre-fleet-comms-${digest}.bak`;
+        const existingBackup = optionalSecureFile(backupPath, mosaicHome);
+        if (existingBackup && !existingBackup.content.equals(installedToolsSnapshot.content)) {
+          throw new Error(`digest-qualified backup collision at ${backupPath}`);
+        }
+        if (!existingBackup) {
+          stagedBackup = stageManagedFile(
+            mosaicHome,
+            mosaicHome,
+            backupPath,
+            installedToolsSnapshot.content,
+            installedToolsSnapshot.mode & 0o777,
+          );
+        }
+        rollbackTools = stageManagedFile(
+          mosaicHome,
+          mosaicHome,
+          installedTools,
+          installedToolsSnapshot.content,
+          installedToolsSnapshot.mode & 0o777,
+        );
+      }
+    }
+    if (helperChanged) {
+      stagedHelper = stageManagedFile(
+        mosaicHome,
+        helperDirectory,
+        installedHelper,
+        sourceHelperSnapshot.content,
+        sourceHelperSnapshot.mode & 0o777,
+      );
+      if (installedHelperSnapshot) {
+        rollbackHelper = stageManagedFile(
+          mosaicHome,
+          helperDirectory,
+          installedHelper,
+          installedHelperSnapshot.content,
+          installedHelperSnapshot.mode & 0o777,
+        );
+      }
+    }
+
+    assertManagedOriginalUnchanged(toolsOriginal, mosaicHome);
+    assertManagedOriginalUnchanged(helperOriginal, mosaicHome);
+    if (stagedBackup && backupPath) {
+      hooks.beforeCommit?.('backup');
+      assertManagedOriginalUnchanged(toolsOriginal, mosaicHome);
+      assertManagedOriginalUnchanged(helperOriginal, mosaicHome);
+      installBackupNoClobber(stagedBackup, backupPath, mosaicHome);
+      stagedBackup = undefined;
+      committedBackup = true;
+    }
+    if (stagedTools) {
+      hooks.beforeCommit?.('tools');
+      assertManagedOriginalUnchanged(toolsOriginal, mosaicHome);
+      atomicInstall(stagedTools, installedTools, mosaicHome);
+      stagedTools = undefined;
+      committedTools = true;
+    }
+    if (stagedHelper) {
+      hooks.beforeCommit?.('helper');
+      assertManagedOriginalUnchanged(helperOriginal, mosaicHome);
+      atomicInstall(stagedHelper, installedHelper, mosaicHome);
+      stagedHelper = undefined;
+      committedHelper = true;
+    }
+    if (rollbackTools) unlinkSync(rollbackTools);
+    if (rollbackHelper) unlinkSync(rollbackHelper);
+    return { ok: true, changed: true, backupPath };
+  } catch (error) {
+    const failures: string[] = [];
+    try {
+      if (committedHelper) {
+        if (rollbackHelper) atomicInstall(rollbackHelper, installedHelper, mosaicHome);
+        else unlinkSync(installedHelper);
+        rollbackHelper = undefined;
+      }
+    } catch (rollbackError) {
+      failures.push(`helper rollback failed: ${String(rollbackError)}`);
+    }
+    try {
+      if (committedTools) {
+        if (rollbackTools) atomicInstall(rollbackTools, installedTools, mosaicHome);
+        else unlinkSync(installedTools);
+        rollbackTools = undefined;
+      }
+    } catch (rollbackError) {
+      failures.push(`TOOLS rollback failed: ${String(rollbackError)}`);
+    }
+    try {
+      if (committedBackup && backupPath) {
+        unlinkSync(backupPath);
+        committedBackup = false;
+      }
+    } catch (rollbackError) {
+      failures.push(`backup rollback failed: ${String(rollbackError)}`);
+    }
+    for (const staged of [stagedBackup, stagedTools, stagedHelper, rollbackTools, rollbackHelper]) {
+      if (!staged) continue;
+      try {
+        unlinkSync(staged);
+      } catch {
+        failures.push(`staging cleanup failed: ${staged}`);
+      }
+    }
+    for (const [created, directory] of [
+      [createdHelperDirectory, helperDirectory],
+      [createdToolsDirectory, dirname(helperDirectory)],
+      [createdHome, mosaicHome],
+    ] as const) {
+      if (!created) continue;
+      try {
+        rmdirSync(directory);
+      } catch (cleanupError) {
+        if (!isNodeErrorCode(cleanupError, 'ENOENT')) {
+          failures.push(`directory cleanup failed: ${directory}`);
+        }
+      }
+    }
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      changed: failures.length > 0,
+      backupPath: committedBackup ? backupPath : undefined,
+      reason: failures.length > 0 ? `${reason}; ${failures.join('; ')}` : reason,
+    };
+  }
+}
+
 /**
  * Re-seed the framework from the freshly-installed package. Returns a result
  * describing what happened (so callers can message + decide on relaunch).
@@ -591,25 +957,20 @@ export function checkFrameworkDrift(
 }
 
 /**
- * Best-effort parse of the fleet roster for agent names (used to relaunch
- * durable agents after a re-seed). Returns [] when no roster exists.
+ * Canonically parse the installed fleet roster for relaunch targets. JSON is
+ * considered only when roster.yaml is genuinely absent; all other failures
+ * return no targets rather than guessing.
  */
 export function readRosterAgentNames(mosaicHome = join(homedir(), '.config', 'mosaic')): string[] {
-  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
-  if (!existsSync(rosterPath)) return [];
-  let text: string;
   try {
-    text = readFileSync(rosterPath, 'utf-8');
+    const rosterPath = resolveInstalledFleetRosterPath(mosaicHome);
+    const source = readFileSync(rosterPath, 'utf8');
+    return parseFleetRosterV1(source, rosterPath.endsWith('.json') ? 'json' : 'yaml').agents.map(
+      (agent) => agent.name,
+    );
   } catch {
     return [];
   }
-  // Roster agents are listed as `- name: <id>` entries under `agents:`.
-  const names: string[] = [];
-  for (const line of text.split('\n')) {
-    const m = line.match(/^\s*-?\s*name:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/);
-    if (m && m[1]) names.push(m[1]);
-  }
-  return names;
 }
 
 /**

packages/mosaic/src/stages/finalize-sync-abort.spec.ts

@@ -0,0 +1,136 @@
+/**
+ * Tests for the framework-sync abort messaging (#791 B2 + blocker-C).
+ *
+ * finalizeStage runs `config.syncFramework()` first, inside a try/catch. If the
+ * sync throws, the wizard must:
+ *   1. NEVER fall through to "Installation complete" — the error is re-raised so
+ *      the process exits non-zero (#791 B2).
+ *   2. Classify the failure so recovery advice is accurate (#791 blocker-C):
+ *        - ManifestError  → a PRE-sync validation abort; nothing was written, so
+ *          the message states "no files were changed".
+ *        - any other error → may surface mid-copy, so the message must NOT claim
+ *          nothing changed; it warns the state "may be partially applied".
+ *
+ * We assert on the spinner's stop() message (the user-visible line) and that the
+ * original error is re-thrown unchanged in both cases.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { WizardState } from '../types.js';
+import type { ConfigService } from '../config/config-service.js';
+import { ManifestError } from '../framework/manifest.js';
+
+vi.mock('node:child_process', () => ({
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  spawnSync: vi.fn<any>().mockReturnValue({ status: 0, stdout: '', stderr: '' }),
+}));
+
+vi.mock('../platform/detect.js', () => ({
+  getShellProfilePath: () => null,
+}));
+
+import { finalizeStage } from './finalize.js';
+
+function makeState(mosaicHome: string): WizardState {
+  return {
+    mosaicHome,
+    sourceDir: mosaicHome,
+    mode: 'quick',
+    installAction: 'keep',
+    soul: { agentName: 'TestBot', communicationStyle: 'direct' },
+    user: {},
+    tools: {},
+    runtimes: { detected: [], mcpConfigured: false },
+    selectedSkills: [],
+  };
+}
+
+function buildPrompter() {
+  const stop = vi.fn();
+  const update = vi.fn();
+  const prompter = {
+    intro: vi.fn(),
+    outro: vi.fn(),
+    note: vi.fn(),
+    log: vi.fn(),
+    warn: vi.fn(),
+    text: vi.fn(),
+    confirm: vi.fn(),
+    select: vi.fn(),
+    multiselect: vi.fn(),
+    groupMultiselect: vi.fn(),
+    spinner: vi.fn().mockReturnValue({ update, stop }),
+    separator: vi.fn(),
+  };
+  return { prompter, stop };
+}
+
+function makeConfigService(syncFramework: ConfigService['syncFramework']): ConfigService {
+  return {
+    readSoul: vi.fn().mockResolvedValue({}),
+    readUser: vi.fn().mockResolvedValue({}),
+    readTools: vi.fn().mockResolvedValue({}),
+    writeSoul: vi.fn().mockResolvedValue(undefined),
+    writeUser: vi.fn().mockResolvedValue(undefined),
+    writeTools: vi.fn().mockResolvedValue(undefined),
+    syncFramework,
+    get: vi.fn(),
+    set: vi.fn(),
+    getSection: vi.fn(),
+  } as unknown as ConfigService;
+}
+
+describe('finalizeStage — framework sync abort (#791 B2 + blocker-C)', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'mosaic-sync-abort-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    vi.clearAllMocks();
+  });
+
+  it('re-throws a ManifestError and reports that no files were changed', async () => {
+    const err = new ManifestError('Framework manifest defines no usable [framework] paths');
+    const { prompter, stop } = buildPrompter();
+    const config = makeConfigService(vi.fn().mockRejectedValue(err));
+
+    await expect(finalizeStage(prompter, makeState(tmp), config)).rejects.toBe(err);
+
+    // The abort message must state nothing was written (pre-sync validation).
+    expect(stop).toHaveBeenCalledWith(expect.stringContaining('no files were changed'));
+    // It must NOT fall through to a success line.
+    expect(stop).not.toHaveBeenCalledWith(expect.stringContaining('Installation complete'));
+  });
+
+  it('re-throws a non-ManifestError and warns the state may be partially applied', async () => {
+    const err = new Error('cp: write error mid-sync (disk full)');
+    const { prompter, stop } = buildPrompter();
+    const config = makeConfigService(vi.fn().mockRejectedValue(err));
+
+    await expect(finalizeStage(prompter, makeState(tmp), config)).rejects.toBe(err);
+
+    // A generic mid-sync failure must NOT claim nothing changed…
+    expect(stop).toHaveBeenCalledWith(expect.stringContaining('may be partially applied'));
+    expect(stop).not.toHaveBeenCalledWith(expect.stringContaining('no files were changed'));
+    expect(stop).not.toHaveBeenCalledWith(expect.stringContaining('Installation complete'));
+  });
+
+  it('does not proceed to config writes when the sync aborts', async () => {
+    const err = new ManifestError('malformed manifest');
+    const { prompter } = buildPrompter();
+    const config = makeConfigService(vi.fn().mockRejectedValue(err));
+
+    await expect(finalizeStage(prompter, makeState(tmp), config)).rejects.toBe(err);
+
+    // writeSoul/writeUser/writeTools are only reached after a successful sync.
+    expect(config.writeSoul).not.toHaveBeenCalled();
+    expect(config.writeUser).not.toHaveBeenCalled();
+    expect(config.writeTools).not.toHaveBeenCalled();
+  });
+});

packages/mosaic/src/stages/finalize.ts

@@ -6,6 +6,7 @@ import type { WizardPrompter } from '../prompter/interface.js';
 import type { ConfigService } from '../config/config-service.js';
 import type { WizardState } from '../types.js';
 import { getShellProfilePath } from '../platform/detect.js';
+import { ManifestError } from '../framework/manifest.js';
 
 function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): void {
   const script = join(mosaicHome, 'bin', 'mosaic-link-runtime-assets');
@@ -160,7 +161,26 @@ export async function finalizeStage(
 
   // 1. Sync framework files (before config writes so identity files aren't overwritten)
   spin.update('Syncing framework files...');
-  await config.syncFramework(state.installAction);
+  try {
+    await config.syncFramework(state.installAction);
+  } catch (err) {
+    // Stop the spinner loudly and re-raise so the process exits non-zero — never
+    // fall through to "Installation complete" on an aborted sync (#791 B2).
+    // A ManifestError is a PRE-sync validation abort: the manifest is loaded and
+    // validated before any file is written, so nothing was touched. Any other
+    // error can surface AFTER files were partially copied, so we must NOT claim
+    // "no files were changed" for it — that would misdirect recovery (#791 blocker-C).
+    if (err instanceof ManifestError) {
+      spin.stop(
+        'Framework sync aborted — the framework manifest is missing, empty, or malformed; no files were changed.',
+      );
+    } else {
+      spin.stop(
+        'Framework sync aborted — the update did not complete and may be partially applied; see the error below.',
+      );
+    }
+    throw err;
+  }
 
   // 2. Write config files (after sync so they aren't overwritten by source templates)
   if (state.installAction !== 'keep') {

packages/mosaic/turbo.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["//"],
+  "tasks": {
+    "test": {
+      "dependsOn": ["^build", "build"]
+    }
+  }
+}