test(fleet): harden static command parsing

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

.woodpecker/ci.yml

@@ -42,23 +42,6 @@ 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:
@@ -67,7 +50,6 @@ steps:
     depends_on:
       - install
       - sanitization
-      - upgrade-guard
 
   # lint, format, and test are independent — run in parallel after typecheck
   lint:

docs/SITEMAP.md

@@ -2,10 +2,24 @@
 
 ## Fleet configuration management
 
-- [Generated environment boundary](fleet/reference/generated-env-boundary.md) — roster-derived launch projection, strict local data, legacy quarantine, and downstream interface evidence.
-- [Roster v2 structural contract](fleet/reference/roster-v2-fields.md) — local-tmux schema v2 parsing and structural validation.
-- [Role classes and authority](fleet/reference/role-classes.md) — canonical role resolver and protected authority boundaries.
-- [Executable asset dispositions](fleet/migration/example-profile-disposition.md) — shipped v1 fixture/profile/service validation posture.
+- [Fleet configuration entry point](fleet/README.md) — desired-versus-observed decision tree and complete operator link map.
+- [Desired, derived, and observed state](fleet/concepts/desired-vs-observed-state.md) — roster authority, generation, ownership, and drift.
+- [Identity, class, and runtime](fleet/concepts/identity-class-runtime.md) — stable name, display alias, class, runtime, provider, and model separation.
+- [Role authority and leases](fleet/concepts/role-authority-and-leases.md) — validator/merge-gate separation and bounded lease authority.
+- [Generated launch chain](fleet/concepts/generated-env-launch-chain.md) — strict data parsing, precedence, and quarantine.
+- [Roster v2 structural contract](fleet/reference/roster-v2-fields.md) — schema, supported values, required fields, defaults, and constraints.
+- [Fleet CLI reference](fleet/reference/cli.md) — local desired-state commands, JSON/exit behavior, and gateway-catalog separation.
+- [Lifecycle transitions](fleet/reference/lifecycle-transitions.md) — create/apply/reboot/migration/rollback boundaries.
+- [Status and drift](fleet/reference/status-and-drift.md) — desired/managed/observed state and current/future classifications.
+- [Safe agent CRUD](fleet/how-to/create-update-delete-agent.md) — expected generation, dry-run, and partial-failure recovery.
+- [Local lifecycle operations](fleet/how-to/start-stop-restart.md) — persisted versus one-shot actions.
+- [Configurable interaction instance](fleet/how-to/configure-tess-interaction.md) and [validator instance](fleet/how-to/configure-ultron-validator.md) — generic identities and protected limits.
+- [Reconcile and recover](fleet/operations/reconcile-and-recover.md) — plan/apply lock and recovery behavior.
+- [Environment quarantine](fleet/operations/env-quarantine.md) — private evidence and value-free diagnostics.
+- [Systemd/tmux troubleshooting](fleet/operations/systemd-tmux-troubleshooting.md) — socket, holder, unmanaged-session, and lock decisions.
+- [Backup/restore boundary](fleet/operations/backup-restore.md) and [upgrade-assets hold](fleet/operations/upgrade-assets.md).
+- [v1-to-v2 migration preview](fleet/migration/v1-to-v2.md) and [executable artifact dispositions](fleet/migration/example-profile-disposition.md).
+- [FCM M5 closure evidence](reports/documentation/758-fleet-config-ia-closure.md) and [approved deferrals](reports/deferred/758-fleet-config-deferrals.md).
 
 ## Official channel plugins
 

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 | 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 |
+| 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 | done        | 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      | PR #788; final head `d63bb0206a1d312ab8352ec1d3ca3631146b0baa`; tree `4da210da9a71b035130d4160a4a2e691bdfde2da`; squash `9745bc3f29c26b021a478b7ad03cfb494f6c9de3`; descendant-main pipeline 1855 terminal success |
+| 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      | HOLD: never starts a previously stopped agent or kills an unproven unmanaged session; not authorized by FCM-M5-001                                                                                                 |
+| FCM-M5-001 | in-progress | 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      | Sole owner: this FCM-M5-001 delivery on the recorded branch; 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      | HOLD: final #758 gate; quality, independent code/security review, validator certificate, merge-gate approval, and green CI remain out of M5-001                                                                    |
 
 ## Thin-core prompt diet (#528) — feat/contract-thin-core
 

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

@@ -1,290 +0,0 @@
-# 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-CONFIG-DOCS-IA-CHECKLIST.md

@@ -5,27 +5,27 @@
 This checklist is an acceptance contract for documentation and examples. It does not authorize
 schema, runtime, systemd, role, profile, or live-fleet changes. An item is complete only when its
 named artifact exists, is linked from the fleet documentation entry point, and its evidence is
-recorded in the M0 task/PR.
+recorded in the M5 closure report and linked deferral evidence.
 
 ## M0 baseline acceptance
 
-- [ ] `docs/PRD.md` states the roster as desired-state SSOT; generated environment, systemd,
+- [x] `docs/PRD.md` states the roster as desired-state SSOT; generated environment, systemd,
       tmux, and heartbeat artifacts as non-authoritative projections; and fail-closed handling of
       unsupported or quarantined legacy input.
-- [ ] `docs/PRD.md` defines the required classes and authority boundary: `validator` certifies but
+- [x] `docs/PRD.md` defines the required classes and authority boundary: `validator` certifies but
       does not merge; `merge-gate` remains sole approve-to-land/merge authority; `team-leader`
       capacity is lease-bounded; `interaction` is request/status only; instance names such as Tess
       and Ultron remain configurable.
-- [ ] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and
+- [x] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and
       observed state, including stopped-state preservation through migration, apply, and reboot.
-- [ ] `docs/PRD.md` defines the generated-env/local-override boundary, explicitly denies arbitrary
+- [x] `docs/PRD.md` defines the generated-env/local-override boundary, explicitly denies arbitrary
       command overrides in M1–M5, and requires key-name/hash-only quarantine diagnostics.
-- [ ] `docs/PRD.md` identifies the M1–M5 local-tmux scope and excludes remote reconciliation,
+- [x] `docs/PRD.md` identifies the M1–M5 local-tmux scope and excludes remote reconciliation,
       connector mutation, secret references, arbitrary commands/channels, gateway convergence, and
       UI configuration storage.
-- [ ] `docs/TASKS.md` contains the complete M0–M5 one-card/one-PR dependency DAG for #758 with
+- [x] `docs/TASKS.md` contains the complete M0–M5 one-card/one-PR dependency DAG for #758 with
       agent tier, branch, dependency, estimate, and evidence expectations.
-- [ ] `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` classifies every current shipped
+- [x] `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` classifies every current shipped
       fleet example, profile, and service preset before M1 implementation starts.
 
 ## Required documentation IA for M1–M5
@@ -72,15 +72,28 @@ recorded in the M0 task/PR.
 
 ## Cross-cutting evidence gates
 
-- [ ] Every retained or migrated YAML/JSON example, profile, and service preset validates through the
-      same executable schema and shared baseline-plus-`roles.local` resolver used by the CLI.
-- [ ] Every retired example/profile/service preset has a replacement link and deprecation note; no
+- [x] Every retained or migrated YAML/JSON example, profile, and service preset validates through the
+      same declared executable production parser/resolver path recorded by the disposition inventory;
+      versioned v1 fixtures are not forced through the v2 compiler.
+- [x] Every retired example/profile/service preset has a replacement link and deprecation note; no
       unresolved legacy class or tool-policy alias remains silently shipped.
-- [ ] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded
+- [x] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded
       Tess/Ultron identity.
-- [ ] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed
+- [x] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed
       `mosaic agent` catalog.
-- [ ] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of
+- [x] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of
       legacy sensitive keys are never printed.
-- [ ] M5 release review verifies links, schema/example validation, and that all checklist rows have
-      owner/evidence or an explicit approved deferral.
+- [x] M5 documentation validation verifies required IA paths, local file and heading-fragment links,
+      the canonical roster through the production compiler/resolver, and fenced/canonical-example
+      safety checks.
+- [ ] FCM-M5-001 does not deterministically assert owner/evidence/deferral metadata for every checklist
+      row. Closure and deferral reports provide human-reviewable evidence only; broader assertion
+      coverage remains unclaimed.
+
+## Held downstream gates
+
+These unchecked items are intentionally outside FCM-M5-001 and are not authorized by this checklist:
+
+- [ ] FCM-M4-002 executes and evidences live cutover, canary, stopped-state preservation, and rollback.
+- [ ] FCM-M5-002 completes independent exact-head review and issues the validator certificate.
+- [ ] The exact PR head reaches terminal-green CI after independent review.

docs/fleet/README.md

@@ -0,0 +1,63 @@
+# Fleet Configuration Management
+
+This book documents the local roster-v2 desired-state control plane delivered under issue #758. The normative requirements are the [FCM section of the repository PRD](../PRD.md#fleet-declarative-configuration-management-workstream-fcm-758), not the older fleet-suite or observability planning pages.
+
+## Authority boundary
+
+`<MOSAIC_HOME>/fleet/roster.yaml` is the sole writable desired-state authority for local fleet membership, launch policy, and persisted lifecycle. Generated environment files, systemd enablement, tmux sessions, heartbeat files, and status output are derived or observed. Rebuild projections from the roster; never edit them as desired state.
+
+This control plane is local tmux/systemd only. Remote/SSH entries and connectors are inventory, not reconciliation targets. Arbitrary commands, channels, secret references, gateway catalog convergence, and UI configuration storage are outside this workstream. `mos-comms` is temporary transport glue, not permanent fleet architecture.
+
+## Choose the right workflow
+
+1. **Need to inspect intent?** Read the roster and use `mosaic fleet get`; see [desired versus observed state](concepts/desired-vs-observed-state.md).
+2. **Need to inspect reality?** Use `status` or `doctor`; use `verify` for a strict non-zero drift/ownership gate. These commands do not repair anything.
+3. **Need to change membership or persisted policy?** Use generation-guarded `plan`, `create`, `update`, or `delete`; see [safe CRUD](how-to/create-update-delete-agent.md).
+4. **Need a one-time runtime action?** Use `start`, `stop`, or `restart`. These do not change persisted desired state.
+5. **Need convergence?** Review `apply --dry-run`, resolve blockers, then use `apply` with the same current generation; see [reconcile and recover](operations/reconcile-and-recover.md).
+6. **Need v1 migration evidence?** Use preview only. Cutover, canary, and rollback remain held for FCM-M4-002.
+7. **Need the gateway-backed agent catalog?** That is the separate `mosaic agent` surface, not local fleet desired state.
+
+## Concepts
+
+- [Desired versus observed state](concepts/desired-vs-observed-state.md)
+- [Identity, class, runtime, provider, and model](concepts/identity-class-runtime.md)
+- [Role authority and leases](concepts/role-authority-and-leases.md)
+- [Generated environment launch chain](concepts/generated-env-launch-chain.md)
+
+## Operator how-to
+
+- [Create, inspect, update, and delete](how-to/create-update-delete-agent.md)
+- [Start, stop, restart, and reconcile](how-to/start-stop-restart.md)
+- [Configure an interaction instance](how-to/configure-tess-interaction.md)
+- [Configure a validator instance](how-to/configure-ultron-validator.md)
+- [Customize roles](how-to/customize-roles.md)
+
+## Operations and recovery
+
+- [Reconcile and recover](operations/reconcile-and-recover.md)
+- [Environment quarantine](operations/env-quarantine.md)
+- [Systemd/tmux troubleshooting](operations/systemd-tmux-troubleshooting.md)
+- [Backup and restore boundary](operations/backup-restore.md)
+- [Upgrade and asset-drift hold](operations/upgrade-assets.md)
+
+## Reference and migration
+
+- [Roster v2 fields](reference/roster-v2-fields.md) · [executable JSON Schema](reference/roster-v2.schema.json) · [validated example](examples/roster-v2.yaml)
+- [CLI and exit codes](reference/cli.md)
+- [Role classes](reference/role-classes.md)
+- [Lifecycle transitions](reference/lifecycle-transitions.md)
+- [Status and drift](reference/status-and-drift.md)
+- [Generated environment boundary](reference/generated-env-boundary.md)
+- [v1-to-v2 preview](migration/v1-to-v2.md)
+- [Example/profile dispositions](migration/example-profile-disposition.md)
+- [Legacy class aliases](migration/legacy-class-aliases.md)
+
+## Acceptance evidence and holds
+
+- [M0/M5 IA checklist](FLEET-CONFIG-DOCS-IA-CHECKLIST.md)
+- [Legacy example/profile inventory](LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md)
+- [M5 closure evidence](../reports/documentation/758-fleet-config-ia-closure.md)
+- [Approved-existing deferrals and live-action holds](../reports/deferred/758-fleet-config-deferrals.md)
+
+The canonical publishing source remains this repository. This card does not publish externally, run a migration, operate a live fleet, or close parent issue #758.

docs/fleet/concepts/desired-vs-observed-state.md

@@ -0,0 +1,42 @@
+# Desired, Derived, and Observed Fleet State
+
+## One writable authority
+
+The canonical local v2 roster at `<MOSAIC_HOME>/fleet/roster.yaml` is desired state. Membership, stable identity, class, runtime/provider/model selection, launch policy, enablement, and persisted `running`/`stopped` intent are written only through generation-guarded roster mutations.
+
+Derived projections are reproducible consequences of that authority:
+
+- `<name>.env.generated`;
+- exact roster-named tmux sessions on the configured socket after reconciliation;
+- systemd service targets managed by installation/reconciliation.
+
+Current systemd unit enablement is not yet lifecycle-conformant at boot: installation can enable every
+agent unit, and the launcher projection does not carry `enabled` or `desired_state`. Therefore reboot
+preservation for stopped/disabled agents remains an FCM-M3-002 acceptance hold, not a guaranteed
+projection behavior.
+
+Observed evidence available to current roster-v2 status commands includes systemd active state, tmux
+presence, holder ownership, and unmanaged sessions. Heartbeat files are observational in the wider fleet,
+but roster-v2 `status`, `doctor`, and `verify` do not currently read them. Observation never writes back
+to the roster.
+
+## Generation and ownership
+
+`generation` is a positive integer concurrency fence. A mutating request must provide the current value. Successful changed CRUD increments it exactly once; stale or concurrent writers fail before mutation. Apply/reconcile rereads the canonical roster under a private exclusive lock and uses only that generation and content for effects.
+
+Ownership is exact, never fuzzy. Reconciliation is limited to roster names, the configured socket, the exact holder session, a private installation identity, and private managed paths. An ownership mismatch, unmanaged session, unsafe path, stale generation, or ambiguous lock fails closed.
+
+## Drift decisions
+
+| Observation                              | Interpretation           | Safe response                                                          |
+| ---------------------------------------- | ------------------------ | ---------------------------------------------------------------------- |
+| Generated file differs or is missing     | Derived projection drift | Review `apply --dry-run`; regenerate from the roster.                  |
+| Desired `running`, exact session missing | `missing-session`        | Diagnose ownership/runtime, then reconcile if safe.                    |
+| Desired `stopped`, exact session present | `unexpected-session`     | Inspect; reconciliation may stop only the proven roster target.        |
+| Disabled agent running                   | `disabled-running`       | Inspect; disabled state wins during explicit safe reconciliation.      |
+| Unknown session on the configured socket | Unmanaged state          | Report only. Do not adopt, rename, or kill it.                         |
+| Heartbeat stale in the wider fleet       | Liveness evidence        | Diagnose separately; current roster-v2 status does not read heartbeat. |
+
+`status` and `doctor` classify. `verify` is also observational but exits non-zero when ownership, drift, or unmanaged-state checks fail. `plan`/`apply --dry-run` validates proposed projection and lifecycle work without mutation. `apply` and `reconcile` converge only after all preconditions pass.
+
+A partial projection failure does not roll the roster back. Treat the committed roster as authority and regenerate. A lifecycle failure after projection completion preserves both roster and projections for inspection. Sensitive legacy values are never printed; diagnostics are bounded to stable codes, key names where applicable, and hashes.

docs/fleet/concepts/generated-env-launch-chain.md

@@ -0,0 +1,23 @@
+# Generated Environment Launch Chain
+
+The launcher consumes validated data, not shell configuration.
+
+1. Read and validate the canonical roster.
+2. Render deterministic `<name>.env.generated` data from that roster.
+3. Parse optional `<name>.env.local` through a strict allowlist.
+4. Reject generated-key shadowing, unknown or sensitive-looking keys, unsafe paths/values, duplicates, malformed lines, shell syntax, and command overrides.
+5. Derive the runtime command from validated runtime/model/reasoning data.
+6. Target only the exact configured tmux socket and roster session after ownership checks.
+
+## File precedence and ownership
+
+| File              | Owner                    | Use                                                                         |
+| ----------------- | ------------------------ | --------------------------------------------------------------------------- |
+| `.env.generated`  | Mosaic projection writer | Complete deterministic roster projection. Rebuild; do not edit.             |
+| `.env.local`      | Operator                 | Optional, private, strict machine-local data. Cannot shadow generated keys. |
+| `.env`            | Legacy input             | One-time migration input only; never launch authority.                      |
+| `.env.quarantine` | Private quarantine       | Retained unsafe legacy evidence; never loaded by the launcher.              |
+
+Neither systemd nor the launcher sources these files. No `eval`, shell expansion, arbitrary `MOSAIC_AGENT_COMMAND`, channel, or secret-reference compatibility path exists. Safe legacy generated keys are regenerated, allowed local keys are relocated, and unsafe material is quarantined.
+
+Diagnostics never expose the rejected value, credential material, or command text. They are bounded to stable rule code, key name where safe, and SHA-256 content identity. See [generated environment reference](../reference/generated-env-boundary.md) and [quarantine operations](../operations/env-quarantine.md).

docs/fleet/concepts/identity-class-runtime.md

@@ -0,0 +1,20 @@
+# Fleet Identity, Class, and Runtime
+
+Each roster field has one job. Do not use names or model strings as authority shortcuts.
+
+| Concern                 | Field                           | Contract                                                                                     |
+| ----------------------- | ------------------------------- | -------------------------------------------------------------------------------------------- |
+| Stable machine identity | `agents[].name`                 | Unique, immutable mutation target and exact service/session name.                            |
+| Display identity        | `agents[].alias`                | Human-facing label only; may be changed and grants no authority.                             |
+| Behavioral contract     | `agents[].class`                | Resolves through the shared baseline plus `roles.local` persona library.                     |
+| Tool boundary           | `agents[].tool_policy`          | Must match protected canonical classes; cannot independently grant authority.                |
+| Harness                 | `agents[].runtime`              | One of `claude`, `codex`, `opencode`, or `pi`, declared in `runtimes`.                       |
+| Backend selection       | `agents[].provider` and `model` | Explicit non-empty data; capability validity is not inferred from the display name or class. |
+| Effort                  | `agents[].reasoning`            | `low`, `medium`, or `high`.                                                                  |
+| Local placement         | `working_directory`             | Explicit safe local work path; not remote placement authority.                               |
+
+Tess and Ultron are conventional instance/display names only. They are not products, required machine identities, role aliases, or authority-bearing classes. A configurable interaction instance uses `class: interaction`; a configurable validation instance uses `class: validator`. Any stable name and alias satisfying the structural contract may be used.
+
+Class aliases are deliberately narrow: `implementer → code`, `reviewer → review`, and `operator-interaction → interaction`. No runtime, provider, model, persona prose, or instance name changes this mapping. See [role classes](../reference/role-classes.md) and the [validated generic example](../examples/roster-v2.yaml).
+
+Roster v2 is local-only. It contains no host/SSH placement, connector, channel, secret-reference, arbitrary-command, per-agent socket, or gateway mapping fields. Those concerns require separate requirements and threat models.

docs/fleet/concepts/role-authority-and-leases.md

@@ -0,0 +1,22 @@
+# Fleet Role Authority and Leases
+
+Role content describes behavior; protected authority is immutable code metadata derived only from the canonical class.
+
+## Required workstream classes
+
+`code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction` are required FCM classes. `merge-gate` is additionally protected because it remains the sole approve-to-land and merge authority.
+
+| Class                                        | Authority                                         | Boundary                                                                               |
+| -------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `merge-gate`                                 | Approve-to-land and merge                         | Sole merge authority.                                                                  |
+| `validator`                                  | Issue independent validation evidence/certificate | Never approves landing or merges.                                                      |
+| `orchestrator`                               | Orchestrate topology and issue bounded leases     | Does not gain merge authority.                                                         |
+| `team-leader`                                | Use explicitly leased capacity                    | Cannot issue leases or mutate roster, credentials, topology authority, or merge state. |
+| `interaction`                                | Receive requests and report status                | Cannot orchestrate, issue leases, mutate configuration, or merge.                      |
+| `code`, `review`, `enhancer`, custom classes | No protected authority by default                 | Persona prose cannot grant protected powers.                                           |
+
+A lease is capacity authorization from an orchestrator, not ownership. It must identify a bounded task or period and does not alter the leased agent's roster identity, role contract, credentials, authority, or persisted lifecycle. Expiry/revocation returns capacity; it does not rewrite the roster.
+
+Semantic validation rejects protected class/tool-policy mismatch in either direction. An instance named Ultron with `class: validator` remains validation-only. An instance named Tess with `class: interaction` remains request/status-only. Renaming either instance changes no authority.
+
+For resolver layering and safe customization, see [role classes](../reference/role-classes.md) and [customize roles](../how-to/customize-roles.md).

docs/fleet/examples/roster-v2.yaml

@@ -0,0 +1,61 @@
+version: 2
+generation: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~/src
+  runtime: pi
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: code-example
+    alias: Code Example
+    class: code
+    runtime: pi
+    provider: example-provider
+    model: example-model
+    reasoning: medium
+    tool_policy: code
+    working_directory: ~/src
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: false
+  - name: interaction-example
+    alias: Interaction Example
+    class: interaction
+    runtime: pi
+    provider: example-provider
+    model: example-model
+    reasoning: low
+    tool_policy: interaction
+    working_directory: ~/src
+    persistent_persona: true
+    reset_between_tasks: false
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: false
+  - name: validator-example
+    alias: Validator Example
+    class: validator
+    runtime: pi
+    provider: example-provider
+    model: example-model
+    reasoning: high
+    tool_policy: validator
+    working_directory: ~/src
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: false

docs/fleet/how-to/configure-tess-interaction.md

@@ -0,0 +1,21 @@
+# Configure an Interaction Instance
+
+An interaction instance is a configurable local roster member with canonical `class: interaction` and matching `tool_policy: interaction`. “Tess” may be used as a display alias, but neither that alias nor the stable name is required or authority-bearing.
+
+Use the [validated generic roster](../examples/roster-v2.yaml) as the safe shape. Choose a unique stable `name`, any descriptive `alias`, a supported declared runtime, explicit provider/model/reasoning, and a safe work directory. Start with:
+
+```yaml
+name: interaction-example
+alias: Interaction Example
+class: interaction
+tool_policy: interaction
+lifecycle:
+  enabled: true
+  desired_state: stopped
+```
+
+Plan the complete agent payload with the current roster generation, then create it without `--persisted-start`. Creation defaults to enabled/stopped and performs no runtime action. Review the resulting roster and projection plan before any later lifecycle decision.
+
+The interaction class is request/status only. It cannot orchestrate, issue leases, mutate the roster/configuration, grant credentials, certify validation, approve landing, or merge. Connector and channel configuration are outside roster v2; do not add connector, channel, secret, command, remote-host, or gateway fields.
+
+See [safe CRUD](create-update-delete-agent.md), [identity separation](../concepts/identity-class-runtime.md), and [role authority](../concepts/role-authority-and-leases.md).

docs/fleet/how-to/configure-ultron-validator.md

@@ -0,0 +1,21 @@
+# Configure a Validator Instance
+
+A validator instance is a configurable local roster member with canonical `class: validator` and matching `tool_policy: validator`. “Ultron” may be used as a display alias, but it is not a required identity, class alias, product name, or source of authority.
+
+Use the [validated generic roster](../examples/roster-v2.yaml) as the safe shape. Choose a unique stable name and explicit supported runtime/provider/model/reasoning values. Start stopped:
+
+```yaml
+name: validator-example
+alias: Validator Example
+class: validator
+tool_policy: validator
+lifecycle:
+  enabled: true
+  desired_state: stopped
+```
+
+Plan the full payload with the current generation and create without `--persisted-start`. Creation writes desired state and projections only; it does not launch a validator.
+
+`validator` may issue independent validation evidence or a certificate. It has no approve-to-land or merge authority. `merge-gate` remains the sole protected merge authority, and changing the validator's name, alias, persona prose, runtime, provider, model, or tool-policy text cannot elevate it.
+
+Certificate consumption and final release evidence remain FCM-M5-002 gates. This page does not create a certificate or authorize merge. See [safe CRUD](create-update-delete-agent.md) and [role authority](../concepts/role-authority-and-leases.md).

docs/fleet/how-to/start-stop-restart.md

@@ -14,9 +14,9 @@ mosaic fleet verify
 mosaic fleet doctor
 ```
 
-Start with `--dry-run`. It validates roster semantics, deterministic projections, private managed paths, exact holder ownership, and named-socket state without changing files or lifecycle state. `apply` and `reconcile` rebuild derived projections and enforce only persisted roster state: enabled `running` agents may start, while stopped or disabled agents are not started.
+Start with `--dry-run`. It validates roster semantics, deterministic projections, private managed paths, exact holder ownership, and named-socket state without changing files or lifecycle state. Explicit `apply` and `reconcile` rebuild derived projections and enforce persisted roster state: enabled `running` agents may start, while stopped or disabled agents are not started. This guarantee does not extend to reboot/service activation yet; boot preservation remains an FCM-M3-002 hold.
 
-`start`, `stop`, and `restart` are explicit one-shot exact-service actions. They do not persist a lifecycle change. Roster CRUD is the only way to change persisted desired state.
+`start`, `stop`, and `restart` are explicit one-shot exact-service actions. They do not persist a lifecycle change. `update` preserves the agent's existing lifecycle, and no delivered operation changes durable lifecycle after creation.
 
 Every command prints JSON. Observation commands report drift without mutation; `verify` exits non-zero on ownership mismatch, unmanaged sessions, or drift. A failed apply that wrote some derived projections reports `projections: "incomplete"` with bounded recovery to regenerate from the roster. A lifecycle failure after projections reports incomplete lifecycle work; it is never represented as a rollback or no-op.
 

docs/fleet/operations/env-quarantine.md

@@ -0,0 +1,20 @@
+# Environment Quarantine Operations
+
+Legacy `<name>.env` is input evidence, never current launch authority. Projection preparation classifies it deterministically:
+
+- generated roster keys → discard and regenerate;
+- allowed strict local keys → relocate to private `.env.local`;
+- malformed, duplicate, unknown, sensitive-looking, shell-bearing, unsafe, or command-override entries → move the legacy input to private `.env.quarantine`.
+
+## Safe response
+
+1. Stop and read the stable error code and reported key name/hash. Do not request or paste the value.
+2. Confirm the canonical roster contains the intended non-sensitive desired state.
+3. If the key is an allowed local machine-data field, place only its validated data form in `.env.local` under private permissions.
+4. Remove unsupported intent rather than translating it into commands, channels, secret references, or unknown `MOSAIC_AGENT_*` keys.
+5. Regenerate `.env.generated` from the roster and rerun a dry-run/verification gate.
+6. Retain quarantine evidence privately until the operator's normal retention process permits removal.
+
+The launcher never reads quarantine. Public/JSON diagnostics expose stable code, key name where safe, and SHA-256 only—never a legacy sensitive value, credential, rejected command, or full line. Quarantine does not prove remediation, backup, migration, or rollback.
+
+See [generated launch chain](../concepts/generated-env-launch-chain.md), [generated environment boundary](../reference/generated-env-boundary.md), and [migration field disposition](../migration/v1-to-v2.md#field-disposition).

docs/fleet/operations/reconcile-and-recover.md

@@ -7,6 +7,8 @@
 3. Resolve stale generation, ownership mismatch, unsafe path, projection validation, or unmanaged-session findings before applying.
 4. Run `mosaic fleet apply --expected-generation <n>` only after the plan is understood.
 
+This is per-generation convergence, not a rolling canary. Executable canary cutover/rollback remains held for FCM-M4-002; rolling local release evidence remains FCM-M5-002. Do not approximate either with repeated live apply commands.
+
 The reconciler uses the exact roster tmux socket, exact holder session, private installation holder identity, and the complete expected global environment. For mutations it acquires its exclusive lock before rereading the canonical roster and fencing its generation; only that under-lock roster drives validation, planning, projections, and lifecycle effects. Before effects, its exclusive lock proves real private `MOSAIC_HOME` and `fleet` ancestors, uses a private `0600` lock leaf, and binds cleanup to the created file identity and ownership token. A fake holder, contaminated global environment, missing identity, unsafe lock path, or unmanaged session fails closed. It does not adopt, kill, or rename any unproven session. A crash can leave a stale lock for explicit operator inspection; reconciliation deliberately does not guess ownership or remove it.
 
 ## Partial results

docs/fleet/operations/systemd-tmux-troubleshooting.md

@@ -0,0 +1,24 @@
+# Systemd and tmux Troubleshooting
+
+Start with read-only `mosaic fleet status`, `doctor`, and `verify`. Do not manually adopt, rename, terminate, or recreate sessions while ownership is ambiguous.
+
+## Decision table
+
+| Finding                         | Meaning                                              | Safe next step                                                                        |
+| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Empty roster `tmux.socket_name` | Literal default tmux server                          | Do not substitute the named `mosaic-fleet` socket. Use roster-derived commands only.  |
+| Non-empty socket                | Exact named socket                                   | Never target another socket or infer a per-agent socket.                              |
+| `holder: missing`               | Required exact holder absent                         | Inspect installation/projection readiness; do not create an unproven holder manually. |
+| `ownership-mismatch`            | Holder identity or global environment differs        | Stop. Verify private install identity and managed paths before retry.                 |
+| `missing-session`               | Desired-running roster agent lacks exact session     | Check service/runtime preconditions; review apply dry-run.                            |
+| `unexpected-session`            | Desired-stopped roster agent still has exact session | Confirm ownership; only reconciler may target the exact proven roster member.         |
+| `disabled-running`              | Disabled roster member is observed running           | Inspect and reconcile only after ownership proof.                                     |
+| `unmanagedSessions`             | Unknown session exists on configured named socket    | Report and investigate separately. Reconciler will not kill or adopt it.              |
+| stale/concurrent generation     | Desired state changed since plan                     | Reload roster/generation and recompute the plan.                                      |
+| stale or ambiguous lock         | Prior writer/cleanup cannot be proven                | Inspect ownership; do not blindly remove the lock.                                    |
+| projection failure              | Derived files incomplete                             | Keep roster as authority and regenerate projections.                                  |
+| lifecycle failure               | Projections complete, runtime convergence incomplete | Inspect the exact owned resource, then rerun with current generation.                 |
+
+Systemd state, tmux state, heartbeat, and generated files are observations/projections, not alternate desired state. Explicit apply/reconcile honors stopped/disabled intent, but current unit enablement and launcher projections do not yet prove lifecycle-safe reboot; inspect unit enablement before reboot and treat stopped/disabled boot preservation as an FCM-M3-002 hold. Current roster-v2 status commands also do not read heartbeat files. Executable gates do not provide site cutover/rollback or package asset-revision repair.
+
+Errors and troubleshooting output never print legacy sensitive values, credential contents, or privileged command text. Use stable codes, key names/hashes, exact roster identities, and bounded recovery actions. See [status and drift](../reference/status-and-drift.md) and [reconcile and recover](reconcile-and-recover.md).

docs/fleet/operations/upgrade-assets.md

@@ -0,0 +1,18 @@
+# Upgrade and Installed-Asset Drift
+
+Fleet source assets and installed assets can differ after an update, but FCM-M5-001 does not add a trustworthy source-versus-installed revision detector or refresh command. Do not infer freshness from checkout presence, timestamps, generated environment files, running sessions, or a ready migration preview.
+
+## Current safe boundary
+
+- The canonical roster remains authority and must survive package/framework refresh.
+- Generated projections are rebuilt from that roster after the installed contract is independently verified.
+- Operator `roles.local`, `.env.local`, and private quarantine evidence are not generated assets and must not be overwritten.
+- Baseline roles, schemas, examples, service presets, launcher helpers, and systemd templates must move as one reviewed release set.
+- Remote/connector inventory and `mos-comms` are not promoted into permanent architecture by an update.
+- No update may start an agent persisted stopped, adopt an unmanaged session, or bypass generation/ownership checks.
+
+## Explicit hold
+
+FCM-M5-002 owns deterministic asset-drift checks, safe package/update refresh evidence, rolling local canary, independent validation certificate, and release evidence. Until that card lands, this page is an operational hold rather than an executable procedure: use the repository/release review path, preserve backups, and do not claim source/installed parity without exact revision evidence from the future validator.
+
+See [approved deferrals](../../reports/deferred/758-fleet-config-deferrals.md) and [backup/restore boundary](backup-restore.md).

docs/fleet/reference/cli.md

@@ -1,6 +1,25 @@
 # Fleet Control-Plane CLI
 
-The local roster-v2 control plane is `mosaic fleet`.
+The local desired-state surface is `mosaic fleet`. It is distinct from the gateway-backed `mosaic agent` catalog and from legacy compatibility commands that act on roster v1.
+
+## Roster-v2 desired-state commands
+
+| Command                                                    | Effect                                         | Generation | Output                     |
+| ---------------------------------------------------------- | ---------------------------------------------- | ---------- | -------------------------- |
+| `mosaic fleet get <name>`                                  | Read one authoritative agent                   | no         | One JSON object            |
+| `mosaic fleet plan <create\|update\|delete> ...`           | Validate proposed CRUD and projections         | required   | One JSON object; no writes |
+| `mosaic fleet create ... [--dry-run] [--persisted-start]`  | Add desired state; default enabled/stopped     | required   | One JSON object            |
+| `mosaic fleet update <name> ... [--dry-run]`               | Replace mutable agent fields                   | required   | One JSON object            |
+| `mosaic fleet delete <name> ... [--dry-run]`               | Remove roster member/generated projection      | required   | One JSON object            |
+| `mosaic fleet apply ... [--dry-run]`                       | Plan or converge projections/lifecycle         | required   | One JSON object            |
+| `mosaic fleet reconcile ... [--dry-run]`                   | Alias of the same convergence contract         | required   | One JSON object            |
+| `mosaic fleet start\|stop\|restart [name] ... [--dry-run]` | Exact one-shot lifecycle action                | required   | One JSON object            |
+| `mosaic fleet status [name]`                               | Observe desired/managed/runtime state          | no         | One JSON object            |
+| `mosaic fleet verify`                                      | Strict observational drift/ownership gate      | no         | One JSON object            |
+| `mosaic fleet doctor`                                      | Classify local drift and recovery context      | no         | One JSON object            |
+| `mosaic fleet migrate-v1 preview ...`                      | Non-mutating field-complete migration evidence | no         | One JSON object            |
+
+CRUD syntax and full payload shape are documented in [agent mutations](agent-mutations.md). Reconciliation syntax:
 
 ```text
 mosaic fleet apply --expected-generation <n> [--dry-run]
@@ -14,14 +33,14 @@ 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).
+`get` is the read/show operation for one v2 agent. Full roster parsing and semantic validation occur on every v2 mutation/reconcile path; there is no separate mutable “config store.” The executable JSON Schema and validated example provide offline structural evidence. The PRD requires an explicit programmatic `mosaic fleet validate` operation, but the current CLI does not expose one; do not substitute another command or claim that requirement is delivered. This remains an implementation gap for #758.
 
-`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.
+## JSON and exit behavior
 
-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.
+Roster-v2 CRUD and reconciler precondition failures emit `{ "error": { "code": "..." } }` and exit non-zero. Migration preview has its own result envelope: a non-ready preview emits `{ "status": "blocked", "blockers": [...] }` and exits non-zero rather than using the CRUD/reconciler error object. Use both exit status and command-specific state fields. A partial reconciliation result distinguishes `authoritativeRoster`, `projections`, `lifecycle`, `recovery`, and optional `cleanup`; it never claims automatic rollback. `verify` exits non-zero for drift, ownership failure, or unmanaged sessions. Sensitive legacy values, credentials, and rejected command text are never printed.
 
-This control plane is separate from the gateway-backed `mosaic agent` catalog. It is local-only and rejects remote/connector lifecycle mutation, arbitrary command/channel/secret input, and unproven tmux ownership.
+## Compatibility and scope
+
+Roster-v1 initialization, provisioning, profiles/personas, and historical `fleet add/remove` remain compatibility surfaces, not roster-v2 CRUD aliases. New v2 automation should use the table above. `migrate-v1 preview` writes nothing and has no cutover, canary, or rollback option.
+
+`mosaic agent` is a separate catalog/transport surface; it does not own `<MOSAIC_HOME>/fleet/roster.yaml` desired state. Remote/SSH reconciliation, connector mutation, arbitrary commands/channels, secret references, and gateway convergence are rejected or outside scope.

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

@@ -1,6 +1,6 @@
 # Fleet Generated Environment Boundary
 
-**Card:** FCM-M2-001 · **Issue:** #758 · **Status:** unreleased/card-local
+**Card:** FCM-M2-001 · **Issue:** #758 · **Status:** merged contract
 
 The local fleet roster is the desired-state authority. A launch reads a deterministic,
 roster-derived generated projection and an optional strictly data-only local file; neither file is
@@ -78,12 +78,12 @@ This card does not add a USC site file, write a USC roster, or run a site canary
 consolidated downstream interface packet. Status is deliberately separated from checkout presence: no
 product release version has been evidenced for this interface set.
 
-| Interface               | Canonical public path and version                                                                                                                 | Tracker/release status                                                                                                | Downstream limit                                                                              |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| M1 structural compiler  | `parseRosterV2` in `packages/mosaic/src/fleet/roster-v2.ts`; schema `docs/fleet/reference/roster-v2.schema.json`; roster `version: 2`             | FCM-M1-001 is recorded done, merged as #764 (`aa5b43b`); no released product version is asserted here.                | Parse YAML/JSON and canonicalize a supplied v2 site roster without writes.                    |
-| M1 semantic resolver    | `validateRosterV2Semantics` in `packages/mosaic/src/fleet/roster-v2.ts`; baseline `framework/fleet/roles/` plus `roles.local/`                    | FCM-M1-002 remains `in-progress` in `docs/TASKS.md`; unreleased.                                                      | Reuse the shared resolver only; no parallel role resolver or lifecycle action.                |
-| M1 disposition evidence | `packages/mosaic/src/fleet/example-profile-dispositions.ts`; `docs/fleet/migration/example-profile-disposition.md`; retained fixture `version: 1` | FCM-M1-003 remains `not-started` in `docs/TASKS.md`; unreleased even though these checkout artifacts are inspectable. | Inspect fixture/profile/service disposition evidence only; it is not migration authorization. |
-| M2 generated boundary   | `packages/mosaic/src/fleet/generated-env-boundary.ts`; generated projection contract in this document                                             | FCM-M2-001 card-local and uncommitted; unreleased.                                                                    | Render/write a roster-derived projection; local input is never authority.                     |
+| Interface               | Canonical public path and version                                                                                                                 | Tracker/release status                                                                                    | Downstream limit                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| M1 structural compiler  | `parseRosterV2` in `packages/mosaic/src/fleet/roster-v2.ts`; schema `docs/fleet/reference/roster-v2.schema.json`; roster `version: 2`             | FCM-M1-001 is recorded done, merged as #764 (`aa5b43b`); no released product version is asserted here.    | Parse YAML/JSON and canonicalize a supplied v2 site roster without writes.                    |
+| M1 semantic resolver    | `validateRosterV2Semantics` in `packages/mosaic/src/fleet/roster-v2.ts`; baseline `framework/fleet/roles/` plus `roles.local/`                    | FCM-M1-002 merged as #768 (`a5e8e55`); no released product version is asserted here.                      | Reuse the shared resolver only; no parallel role resolver or lifecycle action.                |
+| M1 disposition evidence | `packages/mosaic/src/fleet/example-profile-dispositions.ts`; `docs/fleet/migration/example-profile-disposition.md`; retained fixture `version: 1` | FCM-M1-003 merged as #770 (`e9c4aa3`); checkout evidence remains validation, not migration authorization. | Inspect fixture/profile/service disposition evidence only; it is not migration authorization. |
+| M2 generated boundary   | `packages/mosaic/src/fleet/generated-env-boundary.ts`; generated projection contract in this document                                             | FCM-M2-001 merged as #772 (`191efae`); no released product version is asserted here.                      | Render/write a roster-derived projection; local input is never authority.                     |
 
 The canonical source remains `<MOSAIC_HOME>/fleet/roster.yaml` for the current local fleet path.
 Generated environment data is a rebuildable projection, not an operator-editable source of membership,

docs/fleet/reference/lifecycle-transitions.md

@@ -1,14 +1,21 @@
 # Local Fleet Lifecycle Transitions
 
-FCM-M3-001 uses the roster-v2 `lifecycle.enabled` and `lifecycle.desired_state` fields as the only desired-state authority. Systemd, tmux, generated environment files, and heartbeats are derived or observed state.
+Roster-v2 `lifecycle.enabled` and `lifecycle.desired_state` are the only persisted lifecycle authority. Systemd, tmux, generated environment, and heartbeat state are derived or observed.
 
-| Command                           | Desired-state write | Runtime effect                                                                                                             | Preconditions                                                                                                             |
-| --------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `fleet apply` / `fleet reconcile` | Never               | Rebuilds projections, then starts only enabled agents desired `running`; stops disabled or desired-`stopped` roster agents | Current generation; private managed paths; valid projections; proven holder ownership; no unmanaged named-socket sessions |
-| `fleet start <name>`              | Never               | One-shot exact `mosaic-agent@<name>.service` start                                                                         | Current generation; exact enabled roster name; proven ownership                                                           |
-| `fleet stop <name>`               | Never               | One-shot exact service stop                                                                                                | Current generation; exact roster name; proven ownership                                                                   |
-| `fleet restart <name>`            | Never               | One-shot exact service restart                                                                                             | Current generation; exact roster name; proven ownership                                                                   |
+| Event                       | Desired-state write                                                        | Runtime effect                                                                              | Safety boundary                                                                                                                                             |
+| --------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fleet create`              | Adds enabled/stopped by default; `--persisted-start` records running       | None                                                                                        | Generation-guarded; validates full roster/projections.                                                                                                      |
+| `fleet update`              | Preserves the existing enabled/desired state; updates other mutable fields | None                                                                                        | Generation-guarded; stable name and lifecycle are immutable on this path.                                                                                   |
+| `fleet delete`              | Removes exact roster member                                                | None                                                                                        | Removes only generated projection; retains local/quarantine evidence.                                                                                       |
+| `fleet apply` / `reconcile` | Never                                                                      | Rebuilds projections; starts only enabled/running; stops disabled or stopped roster members | Current generation, private lock/paths, semantic validity, holder ownership, no unmanaged named-socket sessions.                                            |
+| `fleet start <name>`        | Never                                                                      | One-shot exact service start                                                                | Exact enabled roster name and proven ownership.                                                                                                             |
+| `fleet stop <name>`         | Never                                                                      | One-shot exact service stop                                                                 | Exact roster name and proven ownership.                                                                                                                     |
+| `fleet restart <name>`      | Never                                                                      | One-shot exact service restart                                                              | Exact enabled roster name and proven ownership.                                                                                                             |
+| Reboot/service activation   | Never                                                                      | Current installation may activate enabled units without honoring roster lifecycle           | **Held for FCM-M3-002:** boot preservation for stopped/disabled agents is not yet proven; inspect/disable units rather than assuming lifecycle-safe reboot. |
+| v1 migration preview        | Never                                                                      | None                                                                                        | Observed active+present maps running; inactive+missing maps stopped; ambiguity blocks.                                                                      |
+| Cutover/canary              | Held for FCM-M4-002                                                        | Not implemented by preview                                                                  | Must preserve every observed stopped state.                                                                                                                 |
+| Rollback                    | Held for FCM-M4-002                                                        | Not implemented                                                                             | Must restore selected authority/projections without surprise starts or unmanaged targeting.                                                                 |
 
-A stopped roster agent is never started by `apply` or `reconcile`. Direct lifecycle commands are explicit one-shot actions and do not change persisted desired state. Use roster CRUD with the explicit persisted-start option to change that desired state.
+Explicit apply/reconcile never starts a stopped roster agent. Direct lifecycle commands are explicit one-shot actions and do not persist intent. The current update operation preserves `existing.lifecycle`; there is no delivered generation-guarded CRUD operation for changing durable lifecycle after creation. Reboot preservation for stopped/disabled agents is not yet guaranteed because current enabled units and launcher projections do not carry the persisted lifecycle fence; that acceptance evidence remains FCM-M3-002.
 
-All mutations require `--expected-generation <n>` and acquire one private roster-adjacent reconciliation lock before projection or lifecycle effects. Missing or stale generations and concurrent writers fail before effects; the lock is released after success, partial failure, or thrown lifecycle failure. Stale, ownership, unmanaged-session, unsupported-runtime, path, projection, and lifecycle-precondition failures return stable redacted JSON errors and a non-zero exit. No command targets a fuzzy tmux name, arbitrary socket, arbitrary command, channel, secret, or generated file as authority.
+Missing/stale generation, concurrent writer, unsafe path, ownership mismatch, unmanaged session, unsupported runtime, invalid projection, and lifecycle precondition failures return stable redacted JSON and non-zero status. No command targets fuzzy names, arbitrary sockets/commands/channels/secrets, or generated files as authority. Legacy sensitive values are never printed.

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

@@ -50,18 +50,20 @@ agents:
 
 ## Root fields
 
-| Field        | Required | Constraint            | Meaning                                                                                                                               |
-| ------------ | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`    | yes      | integer constant `2`  | Identifies this contract. Version `1` is explicitly rejected by this compiler and remains on the existing v1 path until M4 migration. |
-| `generation` | yes      | positive safe integer | Desired-state generation. M2 uses it for mutation guards; M1 does not mutate it.                                                      |
-| `transport`  | yes      | constant `tmux`       | M1–M5 support local tmux only.                                                                                                        |
-| `tmux`       | yes      | strict object         | Explicit local socket and holder-session configuration.                                                                               |
-| `defaults`   | yes      | strict object         | Default work directory and one supported local runtime.                                                                               |
-| `runtimes`   | yes      | non-empty object      | Declared local runtime reset policy map.                                                                                              |
-| `agents`     | yes      | non-empty array       | Local fleet entries. Duplicate stable names are rejected.                                                                             |
+| Field        | Required | Default | Constraint            | Meaning                                                                                           |
+| ------------ | -------- | ------- | --------------------- | ------------------------------------------------------------------------------------------------- |
+| `version`    | yes      | none    | integer constant `2`  | Identifies this contract. Version `1` stays on the compatibility path pending explicit migration. |
+| `generation` | yes      | none    | positive safe integer | Desired-state generation and mutation/reconcile concurrency fence.                                |
+| `transport`  | yes      | none    | constant `tmux`       | M1–M5 support local tmux only.                                                                    |
+| `tmux`       | yes      | none    | strict object         | Explicit local socket and holder-session configuration.                                           |
+| `defaults`   | yes      | none    | strict object         | Default work directory and one supported local runtime.                                           |
+| `runtimes`   | yes      | none    | non-empty object      | Declared local runtime reset policy map.                                                          |
+| `agents`     | yes      | none    | non-empty array       | Local fleet entries. Duplicate stable names are rejected.                                         |
 
 ## Nested fields
 
+All nested fields in the v2 schema are required and have no implicit default. CRUD `create` is the only higher-level convenience: it records `lifecycle.enabled: true` and `desired_state: stopped` unless `--persisted-start` explicitly records running. That convenience still performs no runtime action.
+
 | 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 |

docs/fleet/reference/status-and-drift.md

@@ -1,13 +1,25 @@
 # Local Fleet Status and Drift
 
-`mosaic fleet status [name]`, `verify`, and `doctor` are observational roster-v2 commands. They emit one JSON result and do not write projections, change desired state, start services, stop services, restart services, or mutate tmux.
+`mosaic fleet status [name]`, `verify`, and `doctor` are observational roster-v2 commands. They emit one JSON result and do not write projections, mutate desired state, operate lifecycle, or change tmux.
 
-The report distinguishes:
+## State dimensions
 
-- `missing-session`: an enabled agent desired `running` has no exact roster-named tmux session.
-- `unexpected-session`: a desired-`stopped` agent still has its exact session.
-- `disabled-running`: a disabled roster agent has its exact session.
-- `unmanagedSessions`: sessions on the configured named socket that are neither the exact holder nor an exact roster agent.
-- `holder`: `owned`, `missing`, or `ownership-mismatch` after exact holder, private install identity, and complete global tmux environment validation.
+- **Desired:** roster membership, generation, enabled flag, and persisted running/stopped target.
+- **Managed/derived:** generated environment and expected exact service/session topology.
+- **Observed by current roster-v2 commands:** systemd active state, tmux presence, exact holder ownership, and unmanaged sessions.
 
-`doctor` and `status` classify rather than adopt, destroy, or repair unmanaged state. `verify` is observational too, but exits non-zero if ownership cannot be proven, unmanaged sessions exist, or drift is present. Reconciliation fails closed under those conditions and never kills or adopts an unmanaged session.
+Implemented drift classifications include:
+
+- `missing-session`: enabled/desired-running agent lacks its exact session;
+- `unexpected-session`: desired-stopped agent has its exact session;
+- `disabled-running`: disabled roster agent has its exact session;
+- `unmanagedSessions`: named-socket sessions that are neither exact holder nor roster agent;
+- `holder`: `owned`, `missing`, or `ownership-mismatch` after private identity and global environment checks.
+
+Generated projection failures/staleness are surfaced by plan/apply preparation and bounded recovery fields rather than adopted as configuration. Heartbeat remains wider-fleet observational evidence, never desired state, but the current roster-v2 `status`, `doctor`, and `verify` commands do not read heartbeat files. A provable removed-agent projection may be treated as stale derived state during deletion, but general projection-orphan classification and installed source-versus-asset revision mismatch remain FCM-M4-002/M5-002 holds; current commands must not claim those future checks.
+
+## Command behavior
+
+`status` and `doctor` classify rather than adopt, destroy, or repair. `verify` is observational too, but exits non-zero if ownership cannot be proven, unmanaged sessions exist, or drift is present. Reconciliation fails closed under those conditions and never kills or adopts an unmanaged session.
+
+Doctor/error output uses stable codes and bounded recovery context. Migration, quarantine, lifecycle, status, and troubleshooting output never prints a legacy sensitive value, credential, or privileged command text.

docs/reports/deferred/758-fleet-config-deferrals.md

@@ -0,0 +1,54 @@
+# FCM-M5-001 Fleet Documentation Deferrals and Holds
+
+**Issue:** #758 · **Branch:** `docs/758-fleet-config-operator-docs`
+
+These are accepted existing DAG boundaries, not omissions silently claimed as delivered.
+
+## FCM-M3-002 hold
+
+- Boot/reboot preservation for roster members persisted stopped or disabled.
+- Current installation may enable all agent units, while the launcher projection does not yet carry
+  `lifecycle.enabled` or `desired_state`; documentation therefore does not claim lifecycle-safe reboot.
+- Heartbeat/liveness integration into roster-v2 `status`, `doctor`, and `verify`; current observations
+  cover systemd active state, tmux sessions, holder ownership, and unmanaged sessions only.
+
+## FCM-M4-002 hold
+
+- Executable v1-to-v2 cutover, reversible canary, and rollback.
+- Stale-projection/orphan migration classification and current-host managed/unmanaged fixture coverage.
+- Any live migration, lifecycle, systemd/tmux/session, or rollback action.
+
+M5 docs describe prerequisites and the preview boundary only. A ready preview is not migration or rollback evidence.
+
+## Explicit validate-operation gap
+
+- `FCM-REQ-03` requires a documented programmatic `mosaic fleet validate` operation.
+- The current CLI does not expose that operation. Existing mutation/reconcile validation and the
+  documentation example test are not a replacement for the missing command.
+- FCM-M5-001 documents this implementation gap without inventing syntax, JSON, exit behavior, or an
+  owning implementation card. Parent #758 must remain open until the requirement is implemented and
+  evidenced or the PRD/DAG is explicitly revised through the authoritative process.
+
+## FCM-M5-002 hold
+
+- Deterministic source-versus-installed asset revision detection and safe refresh implementation.
+- Rolling local canary, independent validator certificate, final release evidence, merge-gate approval, and parent #758 closure.
+
+`operations/upgrade-assets.md` is therefore a fail-closed hold, not an invented procedure.
+
+## Compatibility interpretation
+
+The M0 cross-cutting row requiring every retained/migrated artifact to validate through the executable contract is satisfied by each artifact's declared executable disposition, not by forcing versioned v1 fixtures through the v2 parser:
+
+- retained examples are explicit `version: 1` fixtures validated by the production v1 parser;
+- canonical profiles validate through the shared baseline plus `roles.local` resolver;
+- the service preset validates through its production service-policy reader;
+- migration candidates validate through the production v2 compiler and shared semantic resolver.
+
+The executable disposition inventory rejects undeclared additions/removals and prevents silent legacy drift.
+
+## Repository-wide documentation structure
+
+The accepted #758 IA is the domain book under `docs/fleet/`. Creating global `USER-GUIDE`, `ADMIN-GUIDE`, or `DEVELOPER-GUIDE` books and cleaning unrelated pre-existing `docs/` root files are outside this bounded card. The repository sitemap links the fleet book. No HTTP/API/auth contract changed, so OpenAPI and endpoint-index updates are not applicable.
+
+Canonical documentation remains in-repository; no external publishing or generated publishing output is in scope. Parent issue #758 stays open through M5.

docs/reports/documentation/758-fleet-config-ia-closure.md

@@ -0,0 +1,44 @@
+# FCM-M5-001 Fleet Documentation IA Closure Evidence
+
+**Issue:** #758 · **Task:** FCM-M5-001
+
+## Artifact map
+
+- Fleet entry point and desired/observed decision tree: `docs/fleet/README.md`.
+- Concepts: `docs/fleet/concepts/` covers authority/projections, identity separation, role authority/leases, and the generated launch chain.
+- Operator workflows: `docs/fleet/how-to/` covers CRUD, lifecycle, interaction and validator instances, and role overrides.
+- Operations: `docs/fleet/operations/` covers reconciliation/recovery, quarantine, systemd/tmux troubleshooting, backup/restore boundaries, and upgrade-asset holds.
+- References: executable schema, complete field/default/constraint reference, CLI/JSON/exit behavior, lifecycle/status/drift, role authority, and generated environment boundary under `docs/fleet/reference/`.
+- Migration: preview field map, lifecycle preservation, backup/recovery prerequisites, aliases, and executable artifact dispositions under `docs/fleet/migration/`.
+- Navigation: `docs/SITEMAP.md` and the fleet entry point.
+
+## Acceptance mapping
+
+| Checklist area                                   | Evidence                                                                                                                                                                                                             |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Roster authority and fail-closed legacy handling | Root PRD FCM-REQ-01/05/08; desired/observed and quarantine pages.                                                                                                                                                    |
+| Classes and authority                            | Root PRD FCM-REQ-07; role authority concept/reference; configurable interaction/validator how-tos.                                                                                                                   |
+| Lifecycle                                        | Root PRD FCM-REQ-04; lifecycle transition table and operator lifecycle how-to.                                                                                                                                       |
+| Local-only generated launch boundary             | Root PRD FCM-REQ-05/09; generated launch concept/reference.                                                                                                                                                          |
+| Complete DAG and artifact inventory              | `docs/TASKS.md`; M0 inventory; executable disposition tests.                                                                                                                                                         |
+| IA pages                                         | Every path named by the M0 checklist exists and is linked from `docs/fleet/README.md`.                                                                                                                               |
+| Examples                                         | `docs/fleet/examples/roster-v2.yaml` validates through production v2 compiler/shared resolver; shipped artifact dispositions validate through declared production readers.                                           |
+| Links                                            | Deterministic local Markdown link test covers the entire fleet book and sitemap, including local heading-fragment resolution.                                                                                      |
+| Sensitive/example safety                         | Validator scans backtick- and tilde-fenced fleet-book examples plus the canonical roster for sensitive-looking keys, common credential formats (including Anthropic, OpenAI project, and Stripe restricted keys), path-qualified privileged commands, package-manager/root commands, arbitrary command override, and hardcoded Tess/Ultron identities; findings report only file/block and violation kind, never matched values. |
+| Holds                                            | `docs/reports/deferred/758-fleet-config-deferrals.md` records M3-002, M4-002, M5-002, compatibility, and repository-structure boundaries.                                                                            |
+
+## Documentation completion checklist
+
+- [x] Root PRD exists and remains the #758 requirements authority.
+- [ ] The accepted project-specific fleet book is indexed, but it is not complete against `FCM-REQ-03`: the required explicit programmatic `mosaic fleet validate` operation is not implemented. The CLI reference and deferral report record this gap without inventing behavior.
+- [x] Sitemap links the fleet entry point and operator-critical pages.
+- [x] No HTTP/API/auth contract changed; OpenAPI/endpoint rows are not applicable.
+- [x] Working evidence remains under `docs/scratchpads/`; closure and deferral evidence remains under `docs/reports/`.
+- [x] Canonical source remains in-repository; no external publishing action is in scope.
+- [ ] Independent exact-head documentation review, PR CI, and FCM-M5-002 release certificate remain post-PR gates and are not claimed here.
+
+## Live-action boundary
+
+No migration, canary, rollback, deployment, systemd/tmux/session operation, generated projection, or product mutation was performed. `roster.yaml` remains the sole writable desired-state authority. `mos-comms` remains temporary. Parent issue #758 remains open.
+
+Validation command results and exact commit/tree evidence are recorded in the task scratchpad and PR body after execution.

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

@@ -1,216 +0,0 @@
-# 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/fcm-m5-001-fleet-config-operator-docs.md

@@ -0,0 +1,85 @@
+# FCM-M5-001 — Fleet configuration operator documentation
+
+- Task: `FCM-M5-001`
+- Issue: `#758`
+- Branch: `docs/758-fleet-config-operator-docs`
+- Exact base: `9745bc3f29c26b021a478b7ad03cfb494f6c9de3` (tree `4da210da9a71b035130d4160a4a2e691bdfde2da`)
+
+## Objective
+
+Deliver the accepted fleet documentation information architecture, operator workflows, operations and migration references, comprehensive contract documentation, and deterministic link/example validation without live fleet action or product mutation.
+
+## Scope and constraints
+
+- Documentation, examples, documentation validation, and tracking only.
+- `roster.yaml` remains the sole writable desired-state authority; generated state is derived/observed.
+- No M4-002 implementation or execution; no canary, migration, rollback, deployment, systemd/tmux/session, generated projection, or product mutation.
+- `mos-comms` is temporary and is not permanent architecture.
+- Parent issue `#758` remains open through M5.
+- No credentials, sensitive values, or privileged command content.
+
+## Plan
+
+1. Update tracking first with exact M4-001 evidence and mark M5-001 in progress.
+2. Map the M0 checklist and current implementation behavior to documentation pages.
+3. Author operator, operations, migration, schema/reference, recovery, troubleshooting, and security/authority docs.
+4. Add or extend deterministic documentation/link/example validation if required, red-first.
+5. Run repository documentation, link, example, and relevant package checks; review and remediate.
+6. Commit, queue-guard, push one branch, and open one wrapper-created PR; stop for independent review.
+
+## Budget
+
+- Task estimate: `24K`.
+- Working cap: stay within the card estimate by parallelizing read-only discovery and limiting edits to checklist-required artifacts.
+
+## Progress checkpoints
+
+- [x] Loaded repository/global delivery and documentation contracts.
+- [x] Verified `origin/main` is exact required base and created isolated worktree.
+- [x] Tracking updated first.
+- [x] Checklist mapped and docs authored.
+- [x] Validation green.
+- [x] Review/remediation complete.
+- [x] Commit, queue guard, push, PR #789.
+- [x] Rejected exact-head RoR findings repaired on a new descendant commit candidate.
+- [ ] New exact-head review and CI after repair push.
+
+## Tests and verification
+
+- Red-first documentation validator initially failed for the absent fleet entry point and canonical
+  example, then passed after the IA and example were added.
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts src/fleet/example-profile-dispositions.spec.ts src/fleet/fleet-documentation.spec.ts src/fleet/v1-v2-migration.spec.ts src/fleet/generated-env-boundary.spec.ts src/fleet/fleet-agent-crud.spec.ts src/fleet/fleet-reconciler.spec.ts` — 7 files, 195 tests passed after building workspace dependencies.
+- `pnpm format:check` — passed.
+- `pnpm lint` — 23 tasks passed.
+- `pnpm typecheck` — 42 tasks passed.
+- `pnpm test` — 43 tasks passed; `@mosaicstack/mosaic` contributed 61 files and 1,045 tests.
+- `bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh` — passed.
+- `bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh` — passed.
+- `git diff --check` — passed before final review.
+- Independent staged-snapshot review identified four documentation/validation blockers: reboot safety,
+  heartbeat observation, migration failure envelope, and example-scan coverage. All were remediated;
+  focused rereview approved the staged remediations with no blockers. Exact committed-head review remains
+  a post-PR gate.
+- Post-remediation `@mosaicstack/mosaic` lint/typecheck passed; package test passed 61 files / 1,045
+  tests; sanitization and resident-budget gates passed again.
+
+- Post-PR exact-head RoR on rejected head `0aee2c09819fd06e28f927384ea56fa2ef374edf`
+  identified five blockers: update-lifecycle overclaim, missing explicit `fleet validate` gap,
+  fragment-blind link validation, unsupported checklist-evidence claim, and insufficient example safety
+  validation. Red-first regressions failed before implementation for missing-heading, privileged-command,
+  and credential-format fixtures. Repairs now preserve/document implementation truth, validate heading
+  fragments, narrow checklist claims, and scan fenced/canonical examples for common credential formats
+  and privileged commands without printing fixture values.
+- Repair-focused fleet contracts: 7 files, 192 tests passed after review remediation; documentation
+  validator contributed 11 tests. Full gates passed: format; lint 23/23; typecheck 42/42; test 43/43
+  tasks with `@mosaicstack/mosaic` 61 files / 1,052 tests; sanitization; resident budget; and
+  `git diff --check`. New exact-head review/CI remain pending until the repair commit is pushed.
+
+## Risks/blockers
+
+- Checklist may include behavior intentionally deferred to M4-002/M5-002; such items must be recorded as approved-existing holds rather than claimed delivered.
+- Commands/examples must remain non-live and avoid privileged/sensitive content.
+
+## Final evidence
+
+- Pending.

packages/mosaic/framework/framework-manifest.txt

@@ -1,85 +0,0 @@
-# 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,10 +1,5 @@
 #!/usr/bin/env bash
-# -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
+set -euo pipefail
 
 # ─── Mosaic Framework Installer ──────────────────────────────────────────────
 #
@@ -24,19 +19,32 @@ SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 
-# 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.
+# 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; exact preserved roster paths are anchored to
+# the top level only and do NOT shadow fleet/profiles/*.yaml). The user's
+# own fleet files MUST
+# survive `mosaic update` (which runs this sync automatically): the active
+# rosters (`fleet/roster.yaml` and `fleet/roster.json`), 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/roster.yaml" "fleet/roster.json" "fleet/agents" "fleet/run" "fleet/backlog" "fleet/roles.local")
 
 # 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).
@@ -67,45 +75,14 @@ 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")"
-  # 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
+  cp -a "$TARGET_DIR/." "$SNAPSHOT_DIR/" 2>/dev/null || true
 }
 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"
-  # 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
+  rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"
+  cp -a "$SNAPSHOT_DIR/." "$TARGET_DIR/" 2>/dev/null || true
 }
 cleanup_snapshot() { [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] && rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""; }
 
@@ -207,105 +184,63 @@ sync_framework() {
     return
   fi
 
-  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
-
-  # 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
-}
-
-# 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/"
+    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/"
     return
   fi
-  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 \
-    ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" \
-    -exec rm -rf {} +
+
+  # Fallback: cp-based sync. Exact top-level preserved paths mirror the
+  # root-anchored rsync excludes 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
+
+  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
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -376,23 +311,9 @@ 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; exit 1' ERR INT TERM
+trap 'restore_snapshot' ERR INT TERM
 
 sync_framework
 

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

@@ -1,253 +0,0 @@
-#!/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,10 +61,8 @@ 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 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.
+# F6 — keep-mode re-seed (the `mosaic update` path) MUST preserve only the
+# exact user-owned roster paths while refreshing 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"
@@ -77,14 +75,13 @@ 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: 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: unrelated fleet YAML is not preserved" "[ ! -f '$T6/fleet/my-fleet.yaml' ]"
 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'"

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

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

@@ -1,319 +0,0 @@
-#!/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/config/file-adapter.test.ts

@@ -1,22 +1,9 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import {
-  mkdtempSync,
-  mkdirSync,
-  writeFileSync,
-  rmSync,
-  readFileSync,
-  existsSync,
-  copyFileSync,
-} from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } 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.
  *
@@ -47,13 +34,6 @@ 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');
@@ -122,10 +102,9 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
   });
 
   it('overwrites framework-owned files (backup-once) but preserves user-seeded files', async () => {
-    // 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.
+    // 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');
+
     writeFileSync(join(fixture.mosaicHome, 'TOOLS.md'), '# user-customized TOOLS\n');
     writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n');
 

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

@@ -34,7 +34,6 @@ 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.
@@ -156,22 +155,38 @@ export class FileConfigAdapter implements ConfigService {
   }
 
   async syncFramework(action: InstallAction): Promise<void> {
-    // #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;
+    // 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/roster.yaml',
+            'fleet/roster.json',
+            'fleet/agents',
+            'fleet/run',
+          ]
+        : [];
 
     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/fleet-documentation.spec.ts

@@ -0,0 +1,889 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { parseRosterV2, validateRosterV2Semantics } from './roster-v2.js';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const repositoryRoot = resolve(packageRoot, '..', '..');
+const fleetDocs = join(repositoryRoot, 'docs', 'fleet');
+const frameworkFleet = join(packageRoot, 'framework', 'fleet');
+
+const REQUIRED_FLEET_PAGES = [
+  'README.md',
+  'concepts/desired-vs-observed-state.md',
+  'concepts/identity-class-runtime.md',
+  'concepts/role-authority-and-leases.md',
+  'concepts/generated-env-launch-chain.md',
+  'reference/roster-v2.schema.json',
+  'reference/roster-v2-fields.md',
+  'reference/cli.md',
+  'reference/role-classes.md',
+  'reference/lifecycle-transitions.md',
+  'reference/status-and-drift.md',
+  'how-to/create-update-delete-agent.md',
+  'how-to/start-stop-restart.md',
+  'how-to/configure-tess-interaction.md',
+  'how-to/configure-ultron-validator.md',
+  'how-to/customize-roles.md',
+  'operations/reconcile-and-recover.md',
+  'operations/env-quarantine.md',
+  'operations/systemd-tmux-troubleshooting.md',
+  'operations/backup-restore.md',
+  'operations/upgrade-assets.md',
+  'migration/v1-to-v2.md',
+  'migration/example-profile-disposition.md',
+  'migration/legacy-class-aliases.md',
+] as const;
+
+async function markdownFiles(root: string): Promise<string[]> {
+  const entries = await readdir(root, { withFileTypes: true });
+  const paths = await Promise.all(
+    entries.map(async (entry): Promise<string[]> => {
+      const path = join(root, entry.name);
+      if (entry.isDirectory()) return markdownFiles(path);
+      return extname(entry.name) === '.md' ? [path] : [];
+    }),
+  );
+  return paths.flat().sort();
+}
+
+function localMarkdownTargets(source: string): string[] {
+  const link =
+    /\[[^\]]*\]\(\s*(?:<([^>]+)>|((?:\\.|[^()\s]|\([^()]*\))+))(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g;
+  return [...source.matchAll(link)]
+    .map((match): string => match[1] ?? match[2] ?? '')
+    .filter(
+      (target): boolean =>
+        target !== '' &&
+        !target.startsWith('http://') &&
+        !target.startsWith('https://') &&
+        !target.startsWith('mailto:'),
+    );
+}
+
+function markdownHeadingAnchors(source: string): Set<string> {
+  const anchors = new Set<string>();
+  let fence: { readonly marker: string; readonly length: number } | undefined;
+
+  for (const line of source.split('\n')) {
+    const fenceMatch = line.match(/^\s{0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence === undefined && fenceMatch !== null) {
+      const run = fenceMatch[1] ?? '';
+      fence = { marker: run[0] ?? '', length: run.length };
+      continue;
+    }
+    if (fence !== undefined) {
+      const closingRun = line.match(/^\s{0,3}(`{3,}|~{3,})\s*$/)?.[1];
+      if (
+        closingRun !== undefined &&
+        closingRun[0] === fence.marker &&
+        closingRun.length >= fence.length
+      ) {
+        fence = undefined;
+      }
+      continue;
+    }
+
+    const heading = line.match(/^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/)?.[1];
+    if (heading === undefined) continue;
+    const base = heading
+      .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+      .replace(/<[^>]*>/g, '')
+      .replace(/[`*_~]/g, '')
+      .toLowerCase()
+      .trim()
+      .replace(/[^\p{L}\p{N}\s-]/gu, '')
+      .replace(/\s+/g, '-');
+    let anchor = base;
+    let duplicate = 0;
+    while (anchors.has(anchor)) {
+      duplicate += 1;
+      anchor = `${base}-${duplicate}`;
+    }
+    anchors.add(anchor);
+  }
+  return anchors;
+}
+
+function markdownLinkViolations(
+  sourcePath: string,
+  source: string,
+  documents: Readonly<Record<string, string>>,
+): string[] {
+  const violations: string[] = [];
+  for (const target of localMarkdownTargets(source)) {
+    const [encodedPath = '', encodedFragment] = target.split('#', 2);
+    const targetPath = decodeURIComponent(encodedPath);
+    const normalizedTarget = resolve('/', dirname(sourcePath), targetPath).slice(1);
+    const targetSource = documents[normalizedTarget];
+    if (targetSource === undefined) {
+      violations.push(`${sourcePath} -> ${target}: missing file`);
+      continue;
+    }
+    if (encodedFragment !== undefined) {
+      const fragment = decodeURIComponent(encodedFragment);
+      if (fragment === '' || !markdownHeadingAnchors(targetSource).has(fragment)) {
+        violations.push(`${sourcePath} -> ${target}: missing heading`);
+      }
+    }
+  }
+  return violations;
+}
+
+function commandBasename(token: string): string {
+  return token.slice(token.lastIndexOf('/') + 1);
+}
+
+function shellCommandSegments(source: string): string[] {
+  const segments: string[] = [];
+  let segment = '';
+  let quote = '';
+  let wordStarted = false;
+
+  const flush = (): void => {
+    if (segment.trim() !== '') segments.push(segment);
+    segment = '';
+    wordStarted = false;
+  };
+
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index] ?? '';
+    const next = source[index + 1] ?? '';
+    if (character === '\\' && quote !== "'") {
+      if (next === '\n') {
+        index += 1;
+        continue;
+      }
+      segment += character + next;
+      wordStarted = true;
+      index += 1;
+      continue;
+    }
+    if (quote !== '') {
+      segment += character;
+      if (character === quote) quote = '';
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      segment += character;
+      quote = character;
+      wordStarted = true;
+      continue;
+    }
+    if (character === '#' && !wordStarted && segment.trim() !== '') {
+      while (index + 1 < source.length && source[index + 1] !== '\n') index += 1;
+      continue;
+    }
+    if (character === '\n' || character === ';' || character === '&' || character === '|') {
+      flush();
+      continue;
+    }
+    segment += character;
+    if (/\s/.test(character)) wordStarted = false;
+    else wordStarted = true;
+  }
+  flush();
+  return segments;
+}
+
+function shellCommandTokens(source: string): string[] {
+  const tokens: string[] = [];
+  let token = '';
+  let quote = '';
+  let escaped = false;
+
+  for (const character of source) {
+    if (escaped) {
+      token += character;
+      escaped = false;
+      continue;
+    }
+    if (character === '\\' && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if (quote !== '') {
+      if (character === quote) quote = '';
+      else token += character;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (token !== '') {
+        tokens.push(token);
+        token = '';
+      }
+      continue;
+    }
+    token += character;
+  }
+  if (escaped) token += '\\';
+  if (token !== '') tokens.push(token);
+  return tokens;
+}
+
+function envSplitStringTokens(source: string): string[] {
+  const tokens: string[] = [];
+  let token = '';
+  let quote = '';
+  let tokenStarted = false;
+
+  const flush = (): void => {
+    if (tokenStarted) tokens.push(token);
+    token = '';
+    tokenStarted = false;
+  };
+
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index] ?? '';
+    if (character === "'" || character === '"') {
+      if (quote === '') {
+        quote = character;
+        tokenStarted = true;
+        continue;
+      }
+      if (quote === character) {
+        quote = '';
+        continue;
+      }
+    }
+    if (character === '\\') {
+      const escaped = source[index + 1];
+      if (escaped === undefined) {
+        token += '\\';
+        tokenStarted = true;
+        continue;
+      }
+      if (quote === "'" && escaped !== "'" && escaped !== '\\') {
+        token += `\\${escaped}`;
+        tokenStarted = true;
+        index += 1;
+        continue;
+      }
+      if (escaped === 'c' && quote === '') break;
+      if (escaped === '_' && quote !== '"') {
+        flush();
+        index += 1;
+        continue;
+      }
+      const escapes: Readonly<Record<string, string>> = {
+        f: '\f',
+        n: '\n',
+        r: '\r',
+        t: '\t',
+        v: '\v',
+        '#': '#',
+        $: '$',
+        _: ' ',
+        '"': '"',
+        "'": "'",
+        '\\': '\\',
+      };
+      const value = escapes[escaped];
+      if (value !== undefined) {
+        if (/\s/.test(value) && quote === '') flush();
+        else {
+          token += value;
+          tokenStarted = true;
+        }
+        index += 1;
+        continue;
+      }
+      token += `\\${escaped}`;
+      tokenStarted = true;
+      index += 1;
+      continue;
+    }
+    if (character === '#' && quote === '' && !tokenStarted) break;
+    if (/\s/.test(character) && quote === '') {
+      flush();
+      continue;
+    }
+    token += character;
+    tokenStarted = true;
+  }
+  flush();
+  return tokens;
+}
+
+function normalizedCommandTokens(segment: string): string[] {
+  const tokens = shellCommandTokens(segment.trim().replace(/^(?:[$#>]\s*)/, ''));
+  let index = 0;
+
+  while (index < tokens.length) {
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index] ?? '')) index += 1;
+    const wrapper = commandBasename(tokens[index] ?? '');
+    if (wrapper === 'env') {
+      index += 1;
+      while (index < tokens.length) {
+        const token = tokens[index] ?? '';
+        if (!token.startsWith('-') && /^[^=]+=/.test(token)) {
+          index += 1;
+          continue;
+        }
+        if (token === '--') {
+          index += 1;
+          break;
+        }
+        if (token === '--help' || token === '--version') return [];
+        if (/^(?:--unset|--chdir|--argv0)$/.test(token)) {
+          index += 2;
+          continue;
+        }
+        if (/^(?:--unset=|--chdir=|--argv0=)/.test(token)) {
+          index += 1;
+          continue;
+        }
+        if (token === '--split-string') {
+          tokens.splice(index, 2, ...envSplitStringTokens(tokens[index + 1] ?? ''));
+          continue;
+        }
+        const longSplitString = token.match(/^--split-string=(.*)$/)?.[1];
+        if (longSplitString !== undefined) {
+          tokens.splice(index, 1, ...envSplitStringTokens(longSplitString));
+          continue;
+        }
+        if (/^-[^-]/.test(token)) {
+          const options = token.slice(1);
+          let consumed = false;
+          for (let optionIndex = 0; optionIndex < options.length; optionIndex += 1) {
+            const option = options[optionIndex] ?? '';
+            if (option === 'u' || option === 'C' || option === 'a') {
+              index += options.slice(optionIndex + 1) === '' ? 2 : 1;
+              consumed = true;
+              break;
+            }
+            if (option === 'S') {
+              const attached = options.slice(optionIndex + 1);
+              const operand = attached === '' ? (tokens[index + 1] ?? '') : attached;
+              tokens.splice(index, attached === '' ? 2 : 1, ...envSplitStringTokens(operand));
+              consumed = true;
+              break;
+            }
+          }
+          if (!consumed) index += 1;
+          continue;
+        }
+        if (token.startsWith('-')) {
+          index += 1;
+          continue;
+        }
+        break;
+      }
+      continue;
+    }
+    if (wrapper === 'command') {
+      index += 1;
+      let availabilityQuery = false;
+      while ((tokens[index] ?? '').startsWith('-')) {
+        const option = tokens[index] ?? '';
+        index += 1;
+        if (option === '--') break;
+        if (/^-[^-]*[vV]/.test(option)) availabilityQuery = true;
+      }
+      if (availabilityQuery) return [];
+      continue;
+    }
+    break;
+  }
+
+  return tokens.slice(index);
+}
+
+function containsPrivilegedCommand(source: string, depth = 0): boolean {
+  const privilegedCommands = new Set([
+    'sudo',
+    'doas',
+    'pkexec',
+    'systemctl',
+    'service',
+    'mount',
+    'umount',
+    'reboot',
+    'shutdown',
+    'poweroff',
+    'halt',
+    'chown',
+    'chmod',
+    'chroot',
+    'useradd',
+    'usermod',
+    'groupadd',
+    'visudo',
+    'apt',
+    'apt-get',
+    'apt-cache',
+    'dpkg',
+    'yum',
+    'dnf',
+    'rpm',
+    'apk',
+    'pacman',
+    'zypper',
+    'emerge',
+    'snap',
+    'flatpak',
+    'brew',
+    'nix-env',
+  ]);
+
+  return shellCommandSegments(source).some((segment): boolean => {
+    const tokens = normalizedCommandTokens(segment);
+    const command = commandBasename(tokens[0] ?? '');
+    if (privilegedCommands.has(command)) return true;
+    if ((command === 'sh' || command === 'bash') && depth < 3) {
+      let index = 1;
+      while (index < tokens.length) {
+        const token = tokens[index] ?? '';
+        if (token === '--') {
+          index += 1;
+          continue;
+        }
+        if (token === '-c' || token === '--command') {
+          return containsPrivilegedCommand(tokens[index + 1] ?? '', depth + 1);
+        }
+        if (token === '-o' || token === '+o') {
+          index += 2;
+          continue;
+        }
+        if (/^-[^-]*c/.test(token)) {
+          return containsPrivilegedCommand(tokens[index + 1] ?? '', depth + 1);
+        }
+        if (token.startsWith('-') || token.startsWith('+')) {
+          index += 1;
+          continue;
+        }
+        break;
+      }
+      return false;
+    }
+    if (command !== 'su') return false;
+
+    let index = 1;
+    let user: string | undefined;
+    let rootGroup = false;
+    while (index < tokens.length) {
+      const token = tokens[index] ?? '';
+      if (token === '--') {
+        user ??= tokens[index + 1];
+        break;
+      }
+      const longOperand = token.match(
+        /^--(command|session-command|group|supp-group|shell|whitelist-environment)=(.*)$/,
+      );
+      if (longOperand !== null) {
+        if (
+          (longOperand[1] === 'group' || longOperand[1] === 'supp-group') &&
+          longOperand[2] === 'root'
+        ) {
+          rootGroup = true;
+        }
+        index += 1;
+        continue;
+      }
+      if (
+        /^(?:--command|--session-command|--group|--supp-group|--shell|--whitelist-environment)$/.test(
+          token,
+        )
+      ) {
+        if ((token === '--group' || token === '--supp-group') && tokens[index + 1] === 'root') {
+          rootGroup = true;
+        }
+        index += 2;
+        continue;
+      }
+      if (/^-[^-]/.test(token)) {
+        const options = token.slice(1);
+        let consumed = false;
+        for (let optionIndex = 0; optionIndex < options.length; optionIndex += 1) {
+          const option = options[optionIndex] ?? '';
+          if ('cgGsw'.includes(option)) {
+            const attached = options.slice(optionIndex + 1);
+            const operand = attached === '' ? tokens[index + 1] : attached;
+            if ((option === 'g' || option === 'G') && operand === 'root') rootGroup = true;
+            index += attached === '' ? 2 : 1;
+            consumed = true;
+            break;
+          }
+        }
+        if (!consumed) index += 1;
+        continue;
+      }
+      if (token.startsWith('-')) {
+        index += 1;
+        continue;
+      }
+      user ??= token;
+      index += 1;
+    }
+    return rootGroup || user === undefined || user === 'root';
+  });
+}
+
+function exampleSafetyViolationKinds(source: string): string[] {
+  const kinds = new Set<string>();
+  const sensitiveKey = /(?:secret|token|password|credential|MOSAIC_AGENT_COMMAND)/i;
+  const credentialFormat =
+    /(?:\bAKIA[0-9A-Z]{16}\b|\bAIza[0-9A-Za-z_-]{35}\b|\bgh[pousr]_[A-Za-z0-9]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bglpat-[A-Za-z0-9_-]{20,}\b|\bnpm_[A-Za-z0-9]{20,}\b|\bsk-ant-(?:api\d{2}-)?[A-Za-z0-9_-]{20,}\b|\bsk-proj-[A-Za-z0-9_-]{20,}\b|\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b|\bxox[baprs]-[A-Za-z0-9-]{10,}\b|\bBearer\s+[A-Za-z0-9._~+/=-]{16,}\b|\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b|-----BEGIN [A-Z ]*PRIVATE KEY-----|\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s/:]+:[^\s/@]+@)/;
+
+  if (sensitiveKey.test(source)) kinds.add('sensitive-key');
+  if (credentialFormat.test(source)) kinds.add('credential-format');
+  if (containsPrivilegedCommand(source)) kinds.add('privileged-command');
+  if (/\b(?:Tess|Ultron)\b/.test(source)) kinds.add('identity');
+  return [...kinds].sort();
+}
+
+function fencedCodeBlocks(source: string): string[] {
+  const blocks: string[] = [];
+  let fence: { readonly marker: string; readonly length: number } | undefined;
+  let lines: string[] = [];
+
+  for (const line of source.split('\n')) {
+    const openingRun = line.match(/^\s{0,3}(`{3,}|~{3,})[^\n]*$/)?.[1];
+    if (fence === undefined && openingRun !== undefined) {
+      fence = { marker: openingRun[0] ?? '', length: openingRun.length };
+      lines = [];
+      continue;
+    }
+    if (fence === undefined) continue;
+
+    const closingRun = line.match(/^\s{0,3}(`{3,}|~{3,})\s*$/)?.[1];
+    if (
+      closingRun !== undefined &&
+      closingRun[0] === fence.marker &&
+      closingRun.length >= fence.length
+    ) {
+      blocks.push(lines.join('\n'));
+      fence = undefined;
+      lines = [];
+      continue;
+    }
+    lines.push(line);
+  }
+
+  if (fence !== undefined) blocks.push(lines.join('\n'));
+  return blocks;
+}
+
+const UNSAFE_EXAMPLE_FIXTURES = [
+  {
+    expected: 'privileged-command',
+    source: ['cd /srv && su', 'do systemctl restart example'].join(''),
+  },
+  { expected: 'privileged-command', source: '/usr/bin/sudo systemctl restart example' },
+  { expected: 'privileged-command', source: '/usr/bin/apt-get install example' },
+  {
+    expected: 'privileged-command',
+    source: '/usr/bin/env -i /usr/bin/command -- /usr/bin/apt-get install example',
+  },
+  {
+    expected: 'privileged-command',
+    source: '/usr/bin/env -u FOO /usr/bin/apt-get install example',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env -iu FOO /usr/bin/apt-get --version',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env -ivS/usr/bin/apt-get --version',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env --unset FOO /usr/bin/apt-get install example',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env -a alternate /usr/bin/apt-get --version',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env --argv0 alternate /usr/bin/apt-get --version',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env --argv0=alternate /usr/bin/apt-get --version',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env -ia alternate /usr/bin/apt-get --version',
+  },
+  {
+    expected: 'privileged-command',
+    source: 'env -iaalternate /usr/bin/apt-get --version',
+  },
+  {
+    expected: 'privileged-command',
+    source: "env -S '-a alternate /usr/bin/apt-get --version'",
+  },
+  {
+    expected: 'privileged-command',
+    source: "env -S '--argv0=alternate /usr/bin/apt-get --version'",
+  },
+  { expected: 'privileged-command', source: 'env -S apt-get install example' },
+  { expected: 'privileged-command', source: "env -S 'apt-get update'" },
+  { expected: 'privileged-command', source: "env -S'/usr/bin/apt-get --version'" },
+  {
+    expected: 'privileged-command',
+    source: "env --split-string='apt-get update'",
+  },
+  {
+    expected: 'privileged-command',
+    source: "env --split-string='-i /usr/bin/apt-get update'",
+  },
+  {
+    expected: 'privileged-command',
+    source: "env --split-string='FOO=x /usr/bin/apt-get update'",
+  },
+  {
+    expected: 'privileged-command',
+    source: "env --split-string='-- /usr/bin/apt-get update'",
+  },
+  { expected: 'privileged-command', source: "env -S '\\_apt-get --version'" },
+  { expected: 'privileged-command', source: "env -S '\\tapt-get --version'" },
+  {
+    expected: 'privileged-command',
+    source: String.raw`env -S 'env -S "\_apt-get --version"'`,
+  },
+  { expected: 'privileged-command', source: 'LC_ALL=C apt-get --version' },
+  { expected: 'privileged-command', source: "env 'x-y=1' apt-get --version" },
+  { expected: 'privileged-command', source: 'env 1X=value apt-get --version' },
+  { expected: 'privileged-command', source: "sh -c 'apt-get --version'" },
+  { expected: 'privileged-command', source: "/bin/bash -lc 'apt-get --version'" },
+  {
+    expected: 'privileged-command',
+    source: "bash --noprofile -o pipefail -c 'apt-get --version'",
+  },
+  { expected: 'privileged-command', source: 'su operator --group root' },
+  { expected: 'privileged-command', source: 'su --group=root operator' },
+  { expected: 'privileged-command', source: 'su operator -g root' },
+  { expected: 'privileged-command', source: 'su -groot operator' },
+  { expected: 'privileged-command', source: 'su operator --supp-group root' },
+  { expected: 'privileged-command', source: 'su --supp-group=root operator' },
+  { expected: 'privileged-command', source: 'su operator -G root' },
+  { expected: 'privileged-command', source: 'su -lGroot operator' },
+  { expected: 'privileged-command', source: 'apt\\\n-get --version' },
+  { expected: 'privileged-command', source: 'reboot' },
+  { expected: 'privileged-command', source: 'su --command=/bin/sh' },
+  { expected: 'privileged-command', source: 'su -lc /usr/bin/id' },
+  { expected: 'privileged-command', source: 'su -l root' },
+  { expected: 'privileged-command', source: 'su -l -s /bin/sh root' },
+  { expected: 'privileged-command', source: '/usr/bin/su --login root' },
+  { expected: 'privileged-command', source: 'su root' },
+  { expected: 'privileged-command', source: '/usr/sbin/chroot /srv/example' },
+  { expected: 'credential-format', source: ['ghp_', 'a'.repeat(36)].join('') },
+  {
+    expected: 'credential-format',
+    source: ['sk-ant-api03-', 'a'.repeat(80)].join(''),
+  },
+  {
+    expected: 'credential-format',
+    source: ['sk-proj-', 'a'.repeat(80)].join(''),
+  },
+  {
+    expected: 'credential-format',
+    source: ['rk_live_', 'a'.repeat(24)].join(''),
+  },
+  {
+    expected: 'credential-format',
+    source: ['eyJ', 'a'.repeat(12), '.', 'b'.repeat(12), '.', 'c'.repeat(12)].join(''),
+  },
+] as const;
+
+describe('documentation validation regressions', (): void => {
+  it('rejects a local Markdown link whose heading fragment does not exist', (): void => {
+    expect(
+      markdownLinkViolations('docs/fleet/source.md', '[broken](target.md#missing)', {
+        'docs/fleet/target.md': '# Present',
+      }),
+    ).toEqual(['docs/fleet/source.md -> target.md#missing: missing heading']);
+  });
+
+  it('accepts balanced-parenthesis link destinations and visible-text heading anchors', (): void => {
+    expect(localMarkdownTargets('[guide](guide-(legacy).md#setup "Guide")')).toEqual([
+      'guide-(legacy).md#setup',
+    ]);
+    expect(markdownHeadingAnchors('# [Fleet API](cli.md) behavior')).toContain(
+      'fleet-api-behavior',
+    );
+  });
+
+  it('keeps longer fenced blocks closed only by an equal-or-longer fence', (): void => {
+    expect(markdownHeadingAnchors('````markdown\n```\n# Not a heading\n````\n# Present')).toEqual(
+      new Set(['present']),
+    );
+  });
+
+  it('assigns a free suffix when a prior heading already occupies the next duplicate anchor', (): void => {
+    expect(markdownHeadingAnchors('# Foo\n# Foo-1\n# Foo')).toEqual(
+      new Set(['foo', 'foo-1', 'foo-2']),
+    );
+  });
+
+  it('allows command availability queries without classifying the queried command', (): void => {
+    expect(exampleSafetyViolationKinds('command -v apt-get')).not.toContain('privileged-command');
+  });
+
+  it('keeps quoted command separators as inert argument data', (): void => {
+    expect(
+      exampleSafetyViolationKinds("printf '%s\\n' 'safe; /usr/bin/apt-get update'"),
+    ).not.toContain('privileged-command');
+  });
+
+  it('still detects commands after unquoted command separators', (): void => {
+    expect(exampleSafetyViolationKinds('printf safe; /usr/bin/apt-get update')).toContain(
+      'privileged-command',
+    );
+  });
+
+  it.each([
+    'printf safe # ; apt-get --version',
+    'env --help apt-get',
+    'env --version sudo',
+    "env -S '\\\\_printf safe'",
+    "env -S 'printf\\_safe'",
+    "env -S 'printf \\#safe'",
+    "env -S 'printf safe \\c apt-get --version'",
+    'LC_ALL=C printf safe',
+    "env 'x-y=1' printf safe",
+    'env 1X=value printf safe',
+    "sh -c 'printf safe'",
+    "/bin/bash -lc 'command -v apt-get'",
+    "printf '%s\\n' 'sh -c apt-get --version'",
+    'su operator --group operators',
+    'su --group=operators operator',
+    'su operator -g operators',
+    'su -goperators operator',
+    'su operator --supp-group operators',
+    'su --supp-group=operators operator',
+    'su operator -G operators',
+    'su -lGoperators operator',
+    "printf '%s\\n' 'apt\\\\\\n-get --version'",
+  ])('keeps new benign command-parser controls safe', (source): void => {
+    expect(exampleSafetyViolationKinds(source)).not.toContain('privileged-command');
+  });
+
+  it.each([
+    "env --split-string='-i -- /usr/bin/printf safe'",
+    "env --split-string='FOO=x /usr/bin/printf safe'",
+    'env -iu FOO /usr/bin/printf safe',
+    'env -ivS/usr/bin/printf safe',
+    'env -a alternate /usr/bin/printf safe',
+    'env --argv0 alternate /usr/bin/printf safe',
+    'env --argv0=alternate /usr/bin/printf safe',
+    'env -ia alternate /usr/bin/printf safe',
+    'env -iaalternate /usr/bin/printf safe',
+    "env -S '-a alternate /usr/bin/printf safe'",
+    "env -S '--argv0 alternate /usr/bin/printf safe'",
+    'env -a',
+    'env --argv0',
+    'env -ia alternate',
+    "printf '%s\\n' 'env -a alternate /usr/bin/apt-get --version'",
+    'command -v env -a alternate /usr/bin/apt-get',
+    'su -lc /usr/bin/id operator',
+    'su -l -s /bin/sh operator',
+    'su -s /bin/sh -- operator',
+    'su -c /usr/bin/id operator',
+    'su --command=/usr/bin/id operator',
+    'su --session-command=/usr/bin/id operator',
+  ])('keeps valid non-privileged env and su forms safe', (source): void => {
+    expect(exampleSafetyViolationKinds(source)).not.toContain('privileged-command');
+  });
+
+  it.each(UNSAFE_EXAMPLE_FIXTURES)(
+    'classifies unsafe example fixture as $expected',
+    ({ expected, source }): void => {
+      expect(exampleSafetyViolationKinds(source)).toContain(expected);
+    },
+  );
+
+  it('extracts tilde-fenced and unclosed examples without exposing their contents', (): void => {
+    const sensitiveFixture = ['sk-ant-api03-', 'a'.repeat(80)].join('');
+    const blocks = fencedCodeBlocks(
+      `~~~sh\n${sensitiveFixture}\n~~~\n\n\`\`\`sh\n${sensitiveFixture}`,
+    );
+
+    expect(blocks).toHaveLength(2);
+    for (const block of blocks) {
+      const kinds = exampleSafetyViolationKinds(block);
+      expect(kinds).toContain('credential-format');
+      expect(JSON.stringify(kinds)).not.toContain(sensitiveFixture);
+    }
+  });
+});
+
+describe('fleet operator documentation', (): void => {
+  it('ships every accepted information-architecture page', async (): Promise<void> => {
+    await expect(
+      Promise.all(REQUIRED_FLEET_PAGES.map((path) => readFile(join(fleetDocs, path), 'utf8'))),
+    ).resolves.toHaveLength(REQUIRED_FLEET_PAGES.length);
+  });
+
+  it('resolves every local Markdown link and heading fragment in the fleet book and sitemap', async (): Promise<void> => {
+    const files = [...(await markdownFiles(fleetDocs)), join(repositoryRoot, 'docs', 'SITEMAP.md')];
+    const documents: Record<string, string> = {};
+    for (const file of files) {
+      const relative = file.slice(repositoryRoot.length + 1);
+      documents[relative] = await readFile(file, 'utf8');
+    }
+
+    const violations: string[] = [];
+    for (const [sourcePath, source] of Object.entries(documents)) {
+      for (const target of localMarkdownTargets(source)) {
+        const encodedPath = target.split('#', 1)[0] ?? '';
+        const targetPath = resolve(
+          dirname(join(repositoryRoot, sourcePath)),
+          decodeURIComponent(encodedPath),
+        );
+        const relativeTarget = targetPath.slice(repositoryRoot.length + 1);
+        if (documents[relativeTarget] === undefined) {
+          try {
+            documents[relativeTarget] = await readFile(targetPath, 'utf8');
+          } catch {
+            // The deterministic validator below records the missing target without exposing content.
+          }
+        }
+      }
+      violations.push(...markdownLinkViolations(sourcePath, source, documents));
+    }
+    expect(violations).toEqual([]);
+  });
+
+  it('validates the canonical documentation example through the production compiler and resolver', async (): Promise<void> => {
+    const source = await readFile(join(fleetDocs, 'examples', 'roster-v2.yaml'), 'utf8');
+    const roster = parseRosterV2(source, 'yaml');
+    const validated = await validateRosterV2Semantics(roster, {
+      rolesDir: join(frameworkFleet, 'roles'),
+      overrideDir: join(fleetDocs, 'examples', 'roles.local'),
+    });
+
+    expect(validated.generation).toBe(1);
+    expect(validated.agents.map((agent) => agent.canonicalClass)).toEqual([
+      'code',
+      'interaction',
+      'validator',
+    ]);
+  });
+
+  it('keeps every fenced fleet example free of sensitive values, privileged commands, arbitrary command overrides, and product-hardcoded identities', async (): Promise<void> => {
+    const violations: string[] = [];
+    for (const file of await markdownFiles(fleetDocs)) {
+      const source = await readFile(file, 'utf8');
+      for (const [index, block] of fencedCodeBlocks(source).entries()) {
+        for (const kind of exampleSafetyViolationKinds(block)) {
+          violations.push(`${file.slice(repositoryRoot.length + 1)}#block-${index + 1}: ${kind}`);
+        }
+      }
+    }
+
+    const rosterSource = await readFile(join(fleetDocs, 'examples', 'roster-v2.yaml'), 'utf8');
+    for (const kind of exampleSafetyViolationKinds(rosterSource)) {
+      violations.push(`docs/fleet/examples/roster-v2.yaml: ${kind}`);
+    }
+    expect(violations).toEqual([]);
+  });
+});

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

@@ -1,343 +0,0 @@
-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

@@ -1,327 +0,0 @@
-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

@@ -1,248 +0,0 @@
-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,28 +62,16 @@ 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;
-    isOperatorOwned?: (relPath: string) => boolean;
-  } = {},
+  options: { preserve?: string[]; excludeGit?: 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 {
@@ -98,7 +86,7 @@ export function syncDirectory(
       if (options.excludeGit && (dirName === '.git' || relPath.includes('/.git'))) return;
 
       // Skip preserved paths at top level
-      if (relPath !== '' && preserveSet.has(relPath) && existsSync(dest)) return;
+      if (preserveSet.has(relPath) && existsSync(dest)) return;
 
       mkdirSync(dest, { recursive: true });
       for (const entry of readdirSync(src)) {
@@ -113,10 +101,6 @@ 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.ts

@@ -488,13 +488,9 @@ 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 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.
+// 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.
 
 /** Resolve the framework/ directory bundled in the installed package. */
 export function resolveBundledFrameworkRoot(): string {

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

@@ -1,136 +0,0 @@
-/**
- * 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,7 +6,6 @@ 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');
@@ -161,26 +160,7 @@ export async function finalizeStage(
 
   // 1. Sync framework files (before config writes so identity files aren't overwritten)
   spin.update('Syncing framework files...');
-  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;
-  }
+  await config.syncFramework(state.installAction);
 
   // 2. Write config files (after sync so they aren't overwritten by source templates)
   if (state.installAction !== 'keep') {