test(mosaic): gate #797 ledger upgrade-survival + harden manifest parity (#791 )

Fold the Mos-elevated #797 Runtime-Ledger survival sentinel into #791 PR1 and harden the .txt-format parity test per the accepted-format conditions. - framework-manifest.txt: annotate the existing fleet/run/** operator carve-out to name the #797 ledger (fleet/run/sessions/) so it reads as load-bearing. The glob already matches the #797 spec exactly — no location divergence. - HARD GATE (test-upgrade-manifest-guard.sh): seed a populated ledger (events.ndjson journal + ledger.json projection, 0600 under 0700) as an operator sentinel; assert byte-identical + mtime-unchanged + dir-perms unchanged after a keep-mode upgrade. Relabel the prune check as the explicit negative control. 48 -> 58 checks. - Parity (manifest-parity.spec.ts): add format-edge fixtures driven through BOTH resolvers via MANIFEST_FILE — comments/blanks/whitespace, duplicate and overlapping globs (deny-wins), section/glob-ordering independence, and an explicit UNKNOWN->operator negative probe; add ledger probe paths. - manifest.spec.ts: isolate the carve-out's load-bearing value with a resolver red->green — under a hypothetical fleet/** framework glob, the ledger is pruned WITHOUT the fleet/run/** carve-out and protected WITH it (deny-wins). Gates: typecheck, lint, format:check green; mosaic vitest 1069 passed; HARD GATE 58/58; migration 21/21. Commits forward on 34e55d4a (no rebase). Part of #791 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(mosaic): manifest-owned upgrade guard so updates never wipe operator config (#791 )
2026-07-16 16:11:06 -05:00 · 2026-07-16 15:47:28 -05:00 · 2026-07-16 15:14:50 -05:00 · 2026-07-16 13:11:16 +00:00
38 changed files with 6194 additions and 171 deletions
--- a/.woodpecker/ci.yml
+++ b/.woodpecker/ci.yml
@@ -42,6 +42,18 @@ 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 (both rsync + cp paths); 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-install-migration.sh
+
  typecheck:
    image: *node_image
    commands:
@@ -50,6 +62,7 @@ steps:
    depends_on:
      - install
      - sanitization
+      - upgrade-guard

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

+## M4 migration-preview evidence
+
+FCM-M4-001 layers an executable migration posture over the same 13-entry M1 inventory without
+changing the retained artifact classification:
+
+- every `v1-fixture` is previewed only with explicit class and lifecycle evidence;
+- every `canonical-profile` remains validated by the shared baseline-plus-`roles.local` resolver;
+- the canonical service policy remains generic and uses only the approved tool-policy alias.
+
+`validateShippedFleetMigrationDispositions` first runs the existing executable M1 guard, then requires
+explicit decisions and lifecycle observations and executes `previewV1ToV2Migration` for every shipped
+v1 fixture. `collectShippedFleetMigrationDispositions` derives the 13-entry posture directly from
+`SHIPPED_FLEET_ARTIFACT_DISPOSITIONS`, so additions or removals continue to fail the M1 guard rather
+than creating a second artifact list. None of these dispositions claims a cutover, canary, or
+rollback; those gates belong to FCM-M4-002. See [v1-to-v2 preview](./v1-to-v2.md).
+
 ## Running the guard

 ```bash
-pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts
+pnpm --filter @mosaicstack/mosaic test -- v1-v2-migration.spec.ts \
+  -t "validates all 13 shipped artifacts and executes ready previews for every v1 fixture"
 ```

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

+`migrate-v1 preview` is non-mutating: it emits value-free v1 inventory, a canonical semantically
+validated v2 candidate when ready, sanitized environment dispositions, and non-executable recovery
+evidence. It has no write, apply, canary, or rollback option. Missing preview inputs also return one stable
+blocked JSON object and a non-zero exit, rather than Commander text. See
+[the migration preview contract](../migration/v1-to-v2.md).
+
 `apply` and `reconcile` use roster desired state. `start`, `stop`, and `restart` are exact local one-shot lifecycle effects and never persist a desired-state edit. `status`, `verify`, and `doctor` are observational.

 Commands emit one JSON object. Handled precondition errors emit `{ "error": { "code": "..." } }` and exit non-zero. Partial derived/lifecycle effects use explicit `authoritativeRoster`, `projections`, `lifecycle`, and bounded `recovery` fields; they never claim rollback. Any additive `cleanup` diagnostic also exits non-zero, even where known effects are complete: it is not a clean completion and the lock requires inspection before retry.
--- a/docs/fleet/reference/roster-v2-fields.md
+++ b/docs/fleet/reference/roster-v2-fields.md
@@ -62,24 +62,24 @@ agents:

 ## Nested fields

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

 ## Semantic handoff

--- a/docs/fleet/reference/roster-v2.schema.json
+++ b/docs/fleet/reference/roster-v2.schema.json
@@ -24,7 +24,7 @@
      "properties": {
        "socket_name": {
          "type": "string",
-          "pattern": "^[A-Za-z0-9_.-]+$"
+          "pattern": "^[A-Za-z0-9_.-]*$"
        },
        "holder_session": {
          "type": "string",
--- a/docs/scratchpads/758-fcm-m4-001-v1-v2-migrator.md
+++ b/docs/scratchpads/758-fcm-m4-001-v1-v2-migrator.md
@@ -0,0 +1,80 @@
+# FCM-M4-001 — v1-to-v2 inventory, preview, and migrator
+
+- **Task / issue:** FCM-M4-001 / mosaicstack/stack#758
+- **Branch / base:** `feat/758-v1-v2-migrator` from `origin/main` `c1aecfabe97a5dc81a72f44910cd4e626f41863f`
+- **Base tree:** `46cdfbcdc1d1ff9c7b8b2b9cf3841086590bf774`
+- **Scope:** field-complete inventory, non-mutating preview, canonical v2 migration output, and migration/recovery disposition evidence. All effects use injected fakes or temporary fixtures.
+- **Budget:** 35K task estimate is the hard working cap. Keep one card/one PR and prefer focused reuse of the v2 compiler, shared role resolver, generated-env boundary, M1 executable disposition inventory, and reconciler observations.
+
+## Objective
+
+Implement preview-first v1 migration that never infers unresolved classes or lifecycle, preserves observed running/stopped state, quarantines forbidden legacy environment inputs with key-name/SHA-256-only diagnostics, inventories remote/connector/schema-only entries without reconciling them, covers every M1-classified shipped artifact, and emits deterministic recovery disposition evidence for the later M4-002 canary/rollback gate.
+
+## Acceptance mapping
+
+1. Field-by-field v1 inventory and no-mutation preview.
+2. Canonical output compiled by `roster-v2.ts` and semantically validated by the existing baseline-plus-`roles.local` resolver.
+3. Only approved deterministic aliases; every other noncanonical class requires an explicit disposition.
+4. Observed stopped/running maps explicitly to persisted lifecycle; stopped observations never produce running targets.
+5. Generated env is regenerated; strict local data is relocated; forbidden keys are quarantine inputs reported only by key name and SHA-256.
+6. Remote/connector/schema-only entries are inventory-only and excluded from local reconciliation output.
+7. Every shipped M1 example/profile/service preset has executable migration disposition evidence.
+8. Deterministic migration/recovery evidence records source, output, exclusions, quarantine, and restore prerequisites without executing a canary or rollback.
+
+## Boundaries
+
+Out of scope: FCM-M4-002 executable canary/rollback and host fixture, #766 communications, #636 commands/channels, live fleet/systemd/tmux/session/migration/deploy/connector/remote/gateway effects, `docs/TASKS.md`, parent issue mutation, commit, push, and PR operations.
+
+## TDD plan
+
+Migration rules and redaction are critical data-mutation/security logic, so tests are written red-first for inventory completeness, explicit class disposition, observed-state preservation, quarantine redaction, inventory-only remote/schema entries, compiler/resolver reuse, artifact coverage, and recovery evidence. Production code follows only after the focused tests fail for the missing behavior.
+
+## Plan
+
+1. Map existing v1 loader, v2 compiler/resolver, env quarantine, reconciler observation, and M1 disposition guard.
+2. Add behavior-oriented failing migration tests with temporary fixtures and injected observation/filesystem adapters only.
+3. Implement the narrow migration module and CLI boundary without a second resolver or live command runner.
+4. Add scoped M4 migration/recovery documentation and executable shipped-artifact evidence.
+5. Run focused tests, full package tests, package/root typecheck and lint, formatting, diff checks, and adversarial redaction/no-effect verification.
+6. Run independent code/security review, remediate findings, reconstruct the synthetic tree using a temporary index, and stop uncommitted.
+
+## Progress
+
+- Collision checks passed: no local/remote branch, worktree, target path, or open PR owned `feat/758-v1-v2-migrator`.
+- Dedicated worktree created at the exact green `origin/main` base.
+- Required global/repository guides and FCM requirements/evidence loaded.
+- No matching migration skill exists under the configured skill directories; no unrelated skill loaded.
+- Added a preview-only CLI and migration module that compile with the existing v2 parser/renderer and validate through the shared persona resolver.
+- Added value-free raw-v1 inventory, strict unknown-field/synonym/duplicate detection, inventory-only remote and connector handling, and explicit class/tool-policy decisions.
+- Added separate reviewed lifecycle observations with only unambiguous running/stopped mappings.
+- Added sanitized, non-mutating environment preflight and recovery evidence explicitly marked non-executable.
+- Added executable disposition evidence derived from the exact 13-entry M1 inventory and operator documentation.
+- Tightened untrusted decisions/observations to reject unknown keys, invalid types/enums, extra local records, and competing automatic-alias dispositions.
+- Remediated independent review findings: v1 runtime/reset defaults are preserved, `~` workdirs expand only at env preflight, malformed/required agent fields fail closed before remote exclusion, and all seven shipped v1 fixtures now execute real previews with explicit evidence.
+- Remediated socket and locality authority blockers: socket-only agents stay local; `host == fleetHost` stays local; only `host != fleetHost` is inventory-only; ssh-only, missing reviewed fleet-host identity, and contradictory host/ssh targets block explicitly without lifecycle omission.
+- Remediated final exact-tree blockers: a declared v1 root socket cannot be overridden; matching/conflicting socket decisions retain reviewed running evidence; canonical ordering uses a shared locale-independent Unicode code-point comparator; migration evidence preserves all four legacy environment dispositions; backup documentation no longer claims validation that M4-001 does not perform.
+- Remediated immutable-review socket-presence blocker: both `socket_name` and `socketName` are field-presence-aware, so explicit empty/default-server declarations remain authoritative and incompatible named decisions block rather than replacing them.
+- Remediated the replacement-tree blockers: the shared v2 compiler and reconciler accept an explicit empty socket as literal default-server identity; present-empty holder session, default/agent work directory, runtime reset command, and alias values block rather than defaulting; missing preview inputs emit one stable blocked JSON object with non-zero status. Snake/camel aliases and whitespace-only input have adversarial coverage.
+- Remediated the subsequent authority blockers: each present-empty CLI path emits exactly one stable blocked JSON object with exit 1 before file reads, and reconciler `start`/`restart` or desired-state `apply`/`reconcile` fail closed before fixed `mosaic-fleet` systemd services can act on a default-server roster.
+- Remediated committed-head review blockers: explicitly declared empty runtime objects use the production v1 `/clear` reset fallback while omitted `pi` retains `/new`; lifecycle observations are sorted by canonical agent name; and bare CLI path flags reach preview validation, emit one stable blocked JSON object with exit 1, and perform zero reads. Built production-CLI subprocess tests cover all three bare flags.
+- Remediated late-audit blockers: the documented M4 guard invokes the 13-artifact validator and all seven v1 previews; canonical `~`/`~/...` workdirs remain unchanged in migration evidence and traversal-free forms expand at the shared production projection boundary while ordinary relative and home-relative traversal paths remain rejected; remote inventory and exclusion evidence sort canonically; and every default-server lifecycle-mutating reconciler path fails before observation, projection preparation/application, or fixed-unit effects. Explicit regressions preserve `plan`, `status`, `doctor`, and `verify` as observational default-server commands.
+- Remediated exact-tree traversal review: `~/../escape` and `~/src/../../escape` remain unexpanded and fail the unchanged shared `unsafe-path` validation. Both the shared generated-environment boundary and the production v1 environment caller have red-first regressions, preventing earlier caller normalization from bypassing the boundary.
+
+## Verification evidence
+
+- Focused migration/compiler/environment/reconciler/CLI: 8 files, 372 tests passed.
+- Documented 13-artifact guard: 1 matching test passed and executed all seven v1 previews.
+- Full `@mosaicstack/mosaic`: 59 files, 902 tests passed.
+- Workspace build: 23 tasks passed.
+- Root typecheck: 42 tasks passed.
+- Root lint: 23 tasks passed.
+- Root format check and `git diff --check`: passed.
+- Built production CLI: canonical `~/src` remains in ready roster/YAML evidence; generated projection preflight succeeds with no blockers; a bare path flag emits one blocked JSON object, exit 1, and no stderr.
+- Independent high-effort late-audit review: no blocker remained in the four assigned repair surfaces; separate exact-tree security audits found no qualifying newly introduced vulnerability.
+- Exact temporary-index synthetic tree includes every tracked changed path; immutable SHA and duplicate reconstruction are recorded in the final handoff.
+
+## Risks / blockers
+
+- M4-001 emits rollback prerequisites/evidence only; executable rollback/canary and the managed/unmanaged host fixture remain owned by M4-002.
+- Remote/connector entries remain inventory-only; later federation or connector reconciliation requires separately reviewed work.
+- Existing environment data is only preflighted. Cutover backup, quarantine write, legacy removal, and generated projection application remain later reviewed effects.
--- a/docs/scratchpads/791-upgrade-config-protection.md
+++ b/docs/scratchpads/791-upgrade-config-protection.md
@@ -0,0 +1,125 @@
+# 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).
--- a/packages/mosaic/framework/framework-manifest.txt
+++ b/packages/mosaic/framework/framework-manifest.txt
@@ -0,0 +1,85 @@
+# Mosaic framework path-ownership manifest — SSOT for the updater.
+#
+# This single file is the source of truth consumed by BOTH the bash installer
+# (packages/mosaic/framework/install.sh) and the TypeScript config adapter
+# (packages/mosaic/src/config/file-adapter.ts). A parity test asserts both
+# paths resolve the same ownership from this file, so the two can never drift
+# (the failure mode that #631 patched by hand in two places).
+#
+# Format: one glob per line, relative to the mosaic home (~/.config/mosaic).
+#   - Lines starting with '#' and blank lines are ignored.
+#   - '[framework]' / '[operator]' switch the active section.
+#   - '**' matches any depth; '*' matches within a single path segment.
+#
+# Ownership resolution for a path P (deny-wins / fail-safe):
+#   1. P matches an [operator] glob            -> operator-owned.
+#   2. else P matches a [framework] glob        -> framework-owned.
+#   3. else (matches neither)                   -> OPERATOR-OWNED BY DEFAULT.
+#
+# Rule 3 is the root-cause fix for #791: a path the manifest authors never
+# anticipated is protected because UNKNOWN defaults to operator. The updater
+# may only ever create/overwrite framework-owned paths, and may only prune a
+# framework-owned path that lives inside a shipped framework subtree and is
+# absent from the current framework source (a genuinely retired file).
+# Operator-owned and unknown paths are structurally unreachable by pruning.
+
+[framework]
+# Top-level framework contract files (also reconciled from defaults/ on upgrade).
+CONSTITUTION.md
+AGENTS.md
+STANDARDS.md
+# Shipped framework subtrees — pruning is scoped to these roots.
+adapters/**
+constitution/**
+CONTRIBUTING.md
+defaults/**
+examples/**
+guides/**
+install.sh
+install.ps1
+LICENSE
+profiles/**
+runtime/**
+systemd/**
+templates/**
+tools/**
+# Fleet: only the framework-seeded fleet subtrees are framework-owned.
+fleet/README.md
+fleet/examples/**
+fleet/profiles/**
+fleet/roles/**
+fleet/roster.schema.json
+fleet/services/**
+# The manifest itself is framework-owned.
+framework-manifest.txt
+
+[operator]
+# Identity / user-seeded contract files — generated by the wizard or seeded
+# once from defaults/, then owned by the operator. Never overwritten on upgrade.
+SOUL.md
+USER.md
+TOOLS.md
+# Local overlays (tighten-only) authored by the operator.
+*.local.md
+# Operator-owned trees the updater must never write over or prune.
+agents/**
+policy/**
+memory/**
+sources/**
+credentials/**
+# Secret-bearing operator file INSIDE the framework-owned tools/ subtree.
+# Listed explicitly so the deny-wins rule carves it out of tools/**.
+tools/_lib/credentials.json
+# Operator-owned fleet state (roster SSOT, per-agent env, heartbeats, backlog,
+# persona overrides). Losing these silently downgrades a running fleet (#791).
+fleet/roster.yaml
+fleet/roster.json
+fleet/agents/**
+# Runtime state, incl. the #797 Runtime Session Ledger at fleet/run/sessions/
+# (events.ndjson journal + ledger.json projection). This carve-out is the
+# mechanism that makes the ledger upgrade-safe: an upgrade that wiped it would
+# defeat its reason to exist. The HARD GATE (test-upgrade-manifest-guard.sh)
+# proves a populated ledger survives byte-identical + mtime-unchanged.
+fleet/run/**
+fleet/backlog/**
+fleet/roles.local/**
--- a/packages/mosaic/framework/install.sh
+++ b/packages/mosaic/framework/install.sh
@@ -19,32 +19,19 @@ SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"

-# Files/dirs protected from rsync --delete during sync. NOTE: framework-owned
-# entries (CONSTITUTION/AGENTS/STANDARDS) ARE re-applied afterward by
-# reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
-# User-created content in these paths survives rsync --delete.
-#
-# fleet/* — the framework SEEDS fleet/examples, fleet/roles, fleet/profiles, and
-# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
-# and fleet/profiles/*.yaml system-type profile lands automatically via this sync,
-# so no per-file entry is needed; 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")
+# Shared framework path-ownership manifest reader (#791). Parity with
+# packages/mosaic/src/framework/manifest.ts — both consume framework-manifest.txt.
+# Sourcing does not run its CLI dispatch (guarded by BASH_SOURCE==$0).
+# shellcheck source=tools/_lib/manifest.sh
+source "$SOURCE_DIR/tools/_lib/manifest.sh"
+
+# Which paths a keep-mode upgrade may touch is no longer a hand-maintained
+# denylist. It is derived from the shared framework-manifest.txt (#791): the
+# updater only ever creates/overwrites framework-owned paths and only prunes a
+# retired framework file inside a shipped framework subtree. Everything else —
+# every operator file, and every path the manifest never anticipated — is
+# operator-owned by default (fail-safe) and is never written or deleted. See
+# sync_framework_keep() below and packages/mosaic/src/framework/manifest.ts.

 # Framework-owned contract files: re-copied from defaults/ on every upgrade (the
 # user must not edit them; a divergent copy is backed up once before overwrite).
@@ -184,63 +171,72 @@ sync_framework() {
    return
  fi

-  if command -v rsync >/dev/null 2>&1; then
-    local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak")
-
-    if [[ "$INSTALL_MODE" == "keep" ]]; then
-      # Anchor to the transfer root (leading /) so we preserve the TOP-LEVEL
-      # ~/.config/mosaic/<file> without also excluding defaults/<file> from sync
-      # (reconcile_framework_files needs the freshly-synced defaults/ copies).
-      for path in "${PRESERVE_PATHS[@]}"; do
-        rsync_args+=(--exclude "/$path")
-      done
-    fi
-
-    rsync "${rsync_args[@]}" "$SOURCE_DIR/" "$TARGET_DIR/"
+  if [[ "$INSTALL_MODE" == "keep" ]]; then
+    # The `mosaic update` path. Manifest-driven, never-deleting-outside-framework:
+    # operator config is structurally protected (#791). No rsync --delete here.
+    manifest_load
+    sync_framework_keep
    return
  fi

-  # 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
+  # overwrite mode — a full replace, chosen only for a fresh install or when the
+  # operator explicitly asks to replace everything. No operator state to protect.
+  sync_framework_overwrite
+}

-  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" -exec rm -rf {} +
+# 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
+
+  # 1) Overlay copy — every framework-owned source file, refreshed only when its
+  #    bytes changed (no mtime churn on unchanged files, never on operator files).
+  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 < <(find "$src" -type f -print0)
+
+  # 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.
+  while IFS= read -r root; do
+    [[ -n "$root" && -d "$dst/$root" ]] || continue
+    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 < <(find "$dst/$root" -type f -print0)
+    # Drop framework dirs left empty by the prune (never touches a dir that still
+    # holds an operator file — those are never emptied).
+    find "$dst/$root" -type d -empty -delete 2>/dev/null || true
+  done < <(manifest_subtree_roots)
+}
+
+# Overwrite-mode sync: full replace. Only reached for a fresh install or an
+# explicit operator "replace everything" choice, so nothing is preserved.
+sync_framework_overwrite() {
+  if command -v rsync >/dev/null 2>&1; then
+    rsync -a --delete \
+      --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak" \
+      "$SOURCE_DIR/" "$TARGET_DIR/"
+    return
+  fi
+  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 \
+    ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" \
+    -exec rm -rf {} +
  cp -R "$SOURCE_DIR"/. "$TARGET_DIR"/
  rm -rf "$TARGET_DIR/.git"
-
-  if [[ -n "$preserve_tmp" ]]; then
-    # Restore by re-globbing the SAME patterns against preserve_tmp, so each
-    # preserved item is restored at its own relative path (e.g. only
-    # fleet/roster.yaml is replaced — the freshly-synced fleet/examples stays).
-    for path in "${PRESERVE_PATHS[@]}"; do
-      shopt -s nullglob
-      for match in "$preserve_tmp/"$path; do
-        [[ -e "$match" ]] || continue
-        rel="${match#"$preserve_tmp/"}"
-        rm -rf "$TARGET_DIR/$rel"
-        mkdir -p "$TARGET_DIR/$(dirname "$rel")"
-        cp -R "$match" "$TARGET_DIR/$rel"
-      done
-      shopt -u nullglob
-    done
-    rm -rf "$preserve_tmp"
-  fi
 }

 # ═══════════════════════════════════════════════════════════════════════════════
--- a/packages/mosaic/framework/tools/_lib/manifest.sh
+++ b/packages/mosaic/framework/tools/_lib/manifest.sh
@@ -0,0 +1,215 @@
+#!/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
+}
+
+# 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"
+  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"
+  _manifest_compile
+}
+
+# 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
+  manifest_load "${MANIFEST_FILE:-}"
+  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
--- a/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
+++ b/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
@@ -61,8 +61,10 @@ 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 only the
-# exact user-owned roster paths while refreshing framework-owned schema/examples.
+# F6 — keep-mode re-seed (the `mosaic update` path) MUST preserve ALL user-owned
+# fleet state — including an unanticipated file the manifest never names, which
+# resolves to operator-owned by the #791 fail-safe — while refreshing the
+# framework-owned schema/examples.
 T6=$(mktemp -d); mkdir -p "$T6/fleet/examples" "$T6/fleet/run" "$T6/fleet/agents"
 printf '# persona\n' > "$T6/SOUL.md"   # makes it a recognized existing install (→ keep mode)
 printf 'version: 1\nagents:\n  - name: coder0\n' > "$T6/fleet/roster.yaml"
@@ -75,13 +77,14 @@ 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: unrelated fleet YAML is not preserved" "[ ! -f '$T6/fleet/my-fleet.yaml' ]"
+chk "F6 reseed: unanticipated operator fleet file survives (fail-safe, #791)" "cmp -s '$T6/fleet/my-fleet.yaml' '$E6/my-fleet.expected'"
 chk "F6 reseed: per-agent env bytes survive" "cmp -s '$T6/fleet/agents/coder0.env' '$E6/agent.expected'"
 chk "F6 reseed: heartbeat bytes survive" "cmp -s '$T6/fleet/run/coder0.hb' '$E6/run.expected'"
 chk "F6 reseed: framework examples are refreshed" "grep -q orchestrator '$T6/fleet/examples/general.yaml'"
--- a/packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh
+++ b/packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh
@@ -0,0 +1,154 @@
+#!/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.
+#
+# Runs the whole matrix twice: once with rsync available, once forcing the
+# cp-based fallback (both destructive paths in install.sh must obey the manifest).
+#
+# 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"
+}
+
+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) cp fallback path — hide rsync behind a scratch PATH so install.sh takes the
+#    find/rm+cp branch. Provide the coreutils the fallback needs.
+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 "cp-fallback" env "PATH=$FBIN"
+rm -rf "$FBIN"
+
+echo
+echo "RESULT: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]
--- a/packages/mosaic/src/cli-smoke.spec.ts
+++ b/packages/mosaic/src/cli-smoke.spec.ts
@@ -1,3 +1,5 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 import { Command } from 'commander';
 import { registerBrainCommand } from '@mosaicstack/brain';
@@ -16,6 +18,8 @@ import { registerConfigCommand } from './commands/config.js';
 // without throwing. This is the "mosaic <cmd> --help exits 0" gate that
 // guards the sub-package CLI surface (CU-05-01..08) from silent breakage.

+const CLI_PATH = fileURLToPath(new URL('../dist/cli.js', import.meta.url));
+
 const REGISTRARS: Array<[string, (program: Command) => void]> = [
  ['auth', registerAuthCommand],
  ['brain', registerBrainCommand],
@@ -46,6 +50,40 @@ describe('sub-package CLI smoke (CU-05-10)', () => {
    });
  }

+  it.each(['source', 'decisions', 'observations'] as const)(
+    'production CLI emits one blocked JSON object for bare --%s',
+    (bareOption) => {
+      const args = [
+        CLI_PATH,
+        'fleet',
+        'migrate-v1',
+        'preview',
+        '--source=source',
+        '--decisions=decisions',
+        '--observations=observations',
+      ];
+      args[args.findIndex((argument) => argument.startsWith(`--${bareOption}=`))] =
+        `--${bareOption}`;
+
+      const result = spawnSync(process.execPath, args, { encoding: 'utf8' });
+      const outputLines = result.stdout.trim().split('\n');
+
+      expect(result.status).toBe(1);
+      expect(result.stderr).toBe('');
+      expect(outputLines).toHaveLength(1);
+      expect(JSON.parse(outputLines[0]!)).toEqual({
+        status: 'blocked',
+        blockers: [
+          {
+            code: 'missing-migration-preview-option-value',
+            path: `request.${bareOption}`,
+            detail: 'Required migration preview option value is missing.',
+          },
+        ],
+      });
+    },
+  );
+
  it('all nine sub-package commands coexist on a single program', () => {
    const program = new Command();
    for (const [, register] of REGISTRARS) register(program);
--- a/packages/mosaic/src/commands/fleet-migration-command.spec.ts
+++ b/packages/mosaic/src/commands/fleet-migration-command.spec.ts
@@ -0,0 +1,280 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { registerFleetMigrationCommand } from './fleet-migration-command.js';
+
+let cleanup: string | undefined;
+
+afterEach(async (): Promise<void> => {
+  if (cleanup) await rm(cleanup, { recursive: true, force: true });
+  cleanup = undefined;
+});
+
+describe('fleet migrate-v1 preview command', (): void => {
+  it('emits one ready JSON result without any runtime or file mutation API', async () => {
+    cleanup = await mkdtemp(join(tmpdir(), 'fleet-migration-command-'));
+    const rolesDir = join(cleanup, 'roles');
+    const overrideDir = join(cleanup, 'roles.local');
+    await mkdir(rolesDir);
+    await mkdir(overrideDir);
+    await writeFile(join(rolesDir, 'code.md'), '# code\n');
+    const files: Record<string, string> = {
+      source: `version: 1\ntransport: tmux\ntmux:\n  socket_name: test\ndefaults:\n  working_directory: /srv\nruntimes:\n  pi:\n    reset_command: /new\nagents:\n  - name: coder0\n    runtime: pi\n    class: implementer\n`,
+      decisions: JSON.stringify({
+        generation: 2,
+        defaultRuntime: 'pi',
+        agents: {
+          coder0: {
+            provider: 'openai',
+            model: 'gpt-5.6-sol',
+            reasoning: 'high',
+            enabled: true,
+            launchYolo: false,
+            toolPolicyDisposition: { action: 'replace', className: 'code' },
+          },
+        },
+      }),
+      observations: JSON.stringify({ coder0: { systemd: 'inactive', tmux: 'missing' } }),
+    };
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command();
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', cleanup);
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: cleanup,
+      rolesDir,
+      overrideDir,
+      readText: async (path): Promise<string> => files[path] ?? '',
+      printJson,
+      setExitCode,
+    });
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'fleet',
+      'migrate-v1',
+      'preview',
+      '--source',
+      'source',
+      '--decisions',
+      'decisions',
+      '--observations',
+      'observations',
+    ]);
+
+    expect(printJson).toHaveBeenCalledTimes(1);
+    expect(printJson).toHaveBeenCalledWith(expect.objectContaining({ status: 'ready' }));
+    expect(setExitCode).not.toHaveBeenCalled();
+    expect(fleet.helpInformation()).toContain('migrate-v1');
+    const migration = fleet.commands.find((command) => command.name() === 'migrate-v1');
+    expect(migration?.helpInformation()).not.toMatch(/--write|apply|canary|rollback/);
+  });
+
+  it('emits one stable blocked JSON result when --observations is missing', async () => {
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command().exitOverride();
+    program.configureOutput({
+      writeErr: vi.fn(),
+      writeOut: vi.fn(),
+    });
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: '/unused',
+      readText: vi.fn(),
+      printJson,
+      setExitCode,
+    });
+
+    await expect(
+      program.parseAsync([
+        'node',
+        'test',
+        'fleet',
+        'migrate-v1',
+        'preview',
+        '--source',
+        'source',
+        '--decisions',
+        'decisions',
+      ]),
+    ).resolves.toBe(program);
+    expect(printJson).toHaveBeenCalledTimes(1);
+    expect(printJson).toHaveBeenCalledWith({
+      status: 'blocked',
+      blockers: [
+        {
+          code: 'missing-migration-preview-option',
+          path: 'request.observations',
+          detail: 'Required migration preview option is missing.',
+        },
+      ],
+    });
+    expect(setExitCode).toHaveBeenCalledWith(1);
+  });
+
+  it.each(['source', 'decisions', 'observations'] as const)(
+    'emits one stable blocked JSON result when bare --%s has no value',
+    async (bareOption) => {
+      const printJson = vi.fn();
+      const setExitCode = vi.fn();
+      const readText = vi.fn();
+      const writeErr = vi.fn();
+      const program = new Command().exitOverride();
+      program.configureOutput({ writeErr, writeOut: vi.fn() });
+      const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+      registerFleetMigrationCommand(fleet, {
+        mosaicHome: '/unused',
+        readText,
+        printJson,
+        setExitCode,
+      });
+      const args = [
+        'node',
+        'test',
+        'fleet',
+        'migrate-v1',
+        'preview',
+        '--source=source',
+        '--decisions=decisions',
+        '--observations=observations',
+      ];
+      args[args.findIndex((argument) => argument.startsWith(`--${bareOption}=`))] =
+        `--${bareOption}`;
+
+      await expect(program.parseAsync(args)).resolves.toBe(program);
+
+      expect(printJson).toHaveBeenCalledTimes(1);
+      expect(printJson).toHaveBeenCalledWith({
+        status: 'blocked',
+        blockers: [
+          {
+            code: 'missing-migration-preview-option-value',
+            path: `request.${bareOption}`,
+            detail: 'Required migration preview option value is missing.',
+          },
+        ],
+      });
+      expect(setExitCode).toHaveBeenCalledTimes(1);
+      expect(setExitCode).toHaveBeenCalledWith(1);
+      expect(readText).not.toHaveBeenCalled();
+      expect(writeErr).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(['source', 'decisions', 'observations'] as const)(
+    'emits one stable blocked JSON result when --%s is present-empty',
+    async (emptyOption) => {
+      const printJson = vi.fn();
+      const setExitCode = vi.fn();
+      const readText = vi.fn();
+      const program = new Command().exitOverride();
+      program.configureOutput({ writeErr: vi.fn(), writeOut: vi.fn() });
+      const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+      registerFleetMigrationCommand(fleet, {
+        mosaicHome: '/unused',
+        readText,
+        printJson,
+        setExitCode,
+      });
+      const paths = { source: 'source', decisions: 'decisions', observations: 'observations' };
+      paths[emptyOption] = '';
+
+      await expect(
+        program.parseAsync([
+          'node',
+          'test',
+          'fleet',
+          'migrate-v1',
+          'preview',
+          `--source=${paths.source}`,
+          `--decisions=${paths.decisions}`,
+          `--observations=${paths.observations}`,
+        ]),
+      ).resolves.toBe(program);
+
+      expect(printJson).toHaveBeenCalledTimes(1);
+      expect(printJson).toHaveBeenCalledWith({
+        status: 'blocked',
+        blockers: [
+          {
+            code: 'empty-migration-preview-option',
+            path: `request.${emptyOption}`,
+            detail: 'Required migration preview option must be a non-empty path.',
+          },
+        ],
+      });
+      expect(setExitCode).toHaveBeenCalledTimes(1);
+      expect(setExitCode).toHaveBeenCalledWith(1);
+      expect(readText).not.toHaveBeenCalled();
+    },
+  );
+
+  it('emits a blocked result and sets exit 1 for malformed evidence', async () => {
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command();
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: '/unused',
+      readText: async (path): Promise<string> => (path === 'decisions' ? 'not-json' : '{}'),
+      printJson,
+      setExitCode,
+    });
+    await program.parseAsync([
+      'node',
+      'test',
+      'fleet',
+      'migrate-v1',
+      'preview',
+      '--source',
+      'source',
+      '--decisions',
+      'decisions',
+      '--observations',
+      'observations',
+    ]);
+    expect(printJson).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: 'blocked',
+        blockers: [expect.objectContaining({ code: 'migration-preview-failed' })],
+      }),
+    );
+    expect(setExitCode).toHaveBeenCalledWith(1);
+  });
+
+  it('redacts adversarial values from validation failures', async () => {
+    const secret = 'never-print-command-or-token';
+    const printJson = vi.fn();
+    const setExitCode = vi.fn();
+    const program = new Command();
+    const fleet = program.command('fleet').option('--mosaic-home <path>', '', '/unused');
+    registerFleetMigrationCommand(fleet, {
+      mosaicHome: '/unused',
+      readText: async (path): Promise<string> =>
+        path === 'decisions'
+          ? JSON.stringify({ generation: 2, agents: {}, [secret]: secret })
+          : '{}',
+      printJson,
+      setExitCode,
+    });
+    await program.parseAsync([
+      'node',
+      'test',
+      'fleet',
+      'migrate-v1',
+      'preview',
+      '--source',
+      'source',
+      '--decisions',
+      'decisions',
+      '--observations',
+      'observations',
+    ]);
+    expect(JSON.stringify(printJson.mock.calls)).not.toContain(secret);
+    expect(setExitCode).toHaveBeenCalledWith(1);
+  });
+});
--- a/packages/mosaic/src/commands/fleet-migration-command.ts
+++ b/packages/mosaic/src/commands/fleet-migration-command.ts
@@ -0,0 +1,170 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import {
+  parseV1MigrationObservations,
+  parseV1ToV2MigrationDecisions,
+  previewV1ToV2Migration,
+} from '../fleet/v1-v2-migration.js';
+
+export interface FleetMigrationCommandDeps {
+  readonly mosaicHome?: string;
+  readonly rolesDir?: string;
+  readonly overrideDir?: string;
+  readonly readText?: (path: string) => Promise<string>;
+  readonly printJson?: (value: unknown) => void;
+  readonly setExitCode?: (code: number) => void;
+}
+
+interface PreviewOptions {
+  readonly source?: string | boolean;
+  readonly decisions?: string | boolean;
+  readonly observations?: string | boolean;
+}
+
+/** Registers preview-only v1 migration. This command has no mutation verbs or runners. */
+export function registerFleetMigrationCommand(
+  fleetCommand: Command,
+  deps: FleetMigrationCommandDeps = {},
+): void {
+  fleetCommand
+    .command('migrate-v1')
+    .description('Preview a field-complete v1-to-v2 roster migration')
+    .command('preview')
+    .description('Compile migration evidence without writing files or changing runtimes')
+    .option('--source [path]', 'v1 roster YAML or JSON')
+    .option('--decisions [path]', 'explicit migration decisions JSON')
+    .option('--observations [path]', 'reviewed lifecycle observations JSON')
+    .action(async (options: PreviewOptions): Promise<void> => {
+      const readText = deps.readText ?? ((path: string): Promise<string> => readFile(path, 'utf8'));
+      const printJson =
+        deps.printJson ?? ((value: unknown): void => console.log(JSON.stringify(value)));
+      const setExitCode =
+        deps.setExitCode ?? ((code: number): void => void (process.exitCode = code));
+      try {
+        const requiredOptionNames = ['source', 'decisions', 'observations'] as const;
+        const missingOption = requiredOptionNames.find((name) => options[name] === undefined);
+        if (missingOption !== undefined) {
+          printJson({
+            status: 'blocked',
+            blockers: [
+              {
+                code: 'missing-migration-preview-option',
+                path: `request.${missingOption}`,
+                detail: 'Required migration preview option is missing.',
+              },
+            ],
+          });
+          setExitCode(1);
+          return;
+        }
+        const missingValueOption = requiredOptionNames.find((name) => options[name] === true);
+        if (missingValueOption !== undefined) {
+          printJson({
+            status: 'blocked',
+            blockers: [
+              {
+                code: 'missing-migration-preview-option-value',
+                path: `request.${missingValueOption}`,
+                detail: 'Required migration preview option value is missing.',
+              },
+            ],
+          });
+          setExitCode(1);
+          return;
+        }
+        const emptyOption = requiredOptionNames.find(
+          (name) => typeof options[name] === 'string' && options[name].trim() === '',
+        );
+        if (emptyOption !== undefined) {
+          printJson({
+            status: 'blocked',
+            blockers: [
+              {
+                code: 'empty-migration-preview-option',
+                path: `request.${emptyOption}`,
+                detail: 'Required migration preview option must be a non-empty path.',
+              },
+            ],
+          });
+          setExitCode(1);
+          return;
+        }
+        const sourcePath = options.source;
+        const decisionsPath = options.decisions;
+        const observationsPath = options.observations;
+        if (
+          typeof sourcePath !== 'string' ||
+          typeof decisionsPath !== 'string' ||
+          typeof observationsPath !== 'string'
+        ) {
+          throw new Error('Validated migration preview options became unavailable.');
+        }
+        const [source, decisionsSource, observationsSource] = await Promise.all([
+          readText(sourcePath),
+          readText(decisionsPath),
+          readText(observationsPath),
+        ]);
+        const decisions = parseV1ToV2MigrationDecisions(
+          parseJsonObject(decisionsSource, 'migration decisions'),
+        );
+        const observations = parseV1MigrationObservations(
+          parseJsonObject(observationsSource, 'lifecycle observations'),
+        );
+        const mosaicHome =
+          deps.mosaicHome ?? fleetCommand.opts<{ mosaicHome: string }>().mosaicHome;
+        const preview = await previewV1ToV2Migration({
+          source,
+          sourcePath,
+          decisions,
+          observations,
+          personaDirs: {
+            rolesDir: deps.rolesDir ?? join(mosaicHome, 'fleet', 'roles'),
+            overrideDir: deps.overrideDir ?? join(mosaicHome, 'fleet', 'roles.local'),
+          },
+          environment: {
+            mosaicHome,
+            agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
+          },
+        });
+        printJson(preview);
+        if (preview.status === 'blocked') setExitCode(1);
+      } catch (error: unknown) {
+        printJson({
+          status: 'blocked',
+          blockers: [
+            {
+              code: 'migration-preview-failed',
+              path: 'request',
+              detail: safeErrorDetail(error),
+            },
+          ],
+        });
+        setExitCode(1);
+      }
+    });
+}
+
+function parseJsonObject(source: string, label: string): unknown {
+  let value: unknown;
+  try {
+    value = JSON.parse(source) as unknown;
+  } catch {
+    throw new Error(`${label} must be valid JSON.`);
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+  return value;
+}
+
+function safeErrorDetail(error: unknown): string {
+  if (error instanceof Error && isPublishableValidationMessage(error.message)) return error.message;
+  return 'Migration preview failed without publishable detail.';
+}
+
+function isPublishableValidationMessage(message: string): boolean {
+  return /^(migration decisions|lifecycle observations) must be (valid JSON|a JSON object)\.$/.test(
+    message,
+  );
+}
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -90,6 +90,7 @@ describe('registerFleetCommand', () => {
      'init',
      'install',
      'install-systemd',
+      'migrate-v1',
      'persona',
      'plan',
      'profile',
@@ -197,6 +198,26 @@ describe('fleet roster parsing', () => {
    expect(getRosterAgent(roster, 'canary-pi').runtime).toBe('pi');
  });

+  it('uses /clear for an explicitly declared empty pi runtime config', async () => {
+    cleanup = await tempDir();
+    const rosterPath = join(cleanup, 'roster.yaml');
+    await writeFile(
+      rosterPath,
+      [
+        'version: 1',
+        'transport: tmux',
+        'runtimes:',
+        '  pi: {}',
+        'agents:',
+        '  - name: canary-pi',
+        '    runtime: pi',
+      ].join('\n'),
+    );
+
+    const loaded = await loadFleetRoster(rosterPath);
+    expect(loaded.runtimes.pi?.resetCommand).toBe('/clear');
+  });
+
  it('accepts optional agent alias and provider metadata without requiring them', async () => {
    cleanup = await tempDir();
    const rosterPath = join(cleanup, 'roster.yaml');
@@ -270,6 +291,32 @@ describe('fleet roster parsing', () => {
    expect(env).toContain('MOSAIC_TMUX_SOCKET=\n');
  });

+  it('preserves home-relative traversal until the shared environment boundary rejects it', async () => {
+    for (const workingDirectory of ['~/../escape', '~/src/../../escape']) {
+      cleanup = await tempDir();
+      const rosterPath = join(cleanup, 'roster.json');
+      await writeFile(
+        rosterPath,
+        JSON.stringify({
+          version: 1,
+          transport: 'tmux',
+          defaults: { working_directory: workingDirectory },
+          agents: [{ name: 'coder0', runtime: 'pi' }],
+        }),
+      );
+      const roster = await loadFleetRoster(rosterPath);
+
+      expect(() => generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toThrow(
+        expect.objectContaining({
+          diagnostic: expect.objectContaining({
+            code: 'unsafe-path',
+            key: 'MOSAIC_AGENT_WORKDIR',
+          }),
+        }),
+      );
+    }
+  });
+
  it('generates deterministic per-agent EnvironmentFile content', async () => {
    cleanup = await tempDir();
    const rosterPath = join(cleanup, 'roster.json');
--- a/packages/mosaic/src/commands/fleet.ts
+++ b/packages/mosaic/src/commands/fleet.ts
@@ -35,6 +35,10 @@ import {
  registerFleetAgentCrudCommands,
  type FleetAgentCrudCommandDeps,
 } from './fleet-agent-crud-command.js';
+import {
+  registerFleetMigrationCommand,
+  type FleetMigrationCommandDeps,
+} from './fleet-migration-command.js';
 import {
  executeReconcilerCommandJson,
  registerFleetReconcilerCommands,
@@ -97,6 +101,7 @@ export interface FleetCommandDeps {
  isStdinTTY?: boolean;
  projectionApplier?: FleetAgentCrudCommandDeps['projectionApplier'];
  reconcileDeps?: FleetReconcilerCommandDeps['reconcileDeps'];
+  migrationDeps?: Omit<FleetMigrationCommandDeps, 'mosaicHome'>;
 }

 export interface FleetPaths {
@@ -480,7 +485,7 @@ function generateAgentEnvValues(
    MOSAIC_AGENT_MODEL: agent.modelHint ?? '',
    MOSAIC_AGENT_REASONING: agent.reasoningLevel ?? '',
    MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy ?? '',
-    MOSAIC_AGENT_WORKDIR: expandHome(workingDirectory),
+    MOSAIC_AGENT_WORKDIR: workingDirectory,
    MOSAIC_TMUX_SOCKET: agent.socket ?? roster.tmux.socketName,
  };
 }
@@ -2048,6 +2053,10 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
  // Roster-v2 desired-state mutations belong directly to the fleet control
  // plane; they do not share the root `mosaic agent` gateway-backed surface.
  registerFleetAgentCrudCommands(cmd, deps);
+  registerFleetMigrationCommand(cmd, {
+    ...deps.migrationDeps,
+    mosaicHome: deps.mosaicHome,
+  });
  registerFleetReconcilerCommands(cmd, {
    runner,
    mosaicHome: deps.mosaicHome,
@@ -2411,10 +2420,6 @@ function resolveMosaicHomeFromCommand(command: Command, override?: string): stri
  return opts.mosaicHome ?? override ?? defaultMosaicHome();
 }

-function expandHome(path: string): string {
-  return path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
-}
-
 async function stopFleetBestEffort(runner: CommandRunner, agentNames: string[]): Promise<void> {
  const failures: string[] = [];
  for (const agentName of agentNames) {
--- a/packages/mosaic/src/config/file-adapter.test.ts
+++ b/packages/mosaic/src/config/file-adapter.test.ts
@@ -1,9 +1,22 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  readFileSync,
+  existsSync,
+  copyFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { FileConfigAdapter, DEFAULT_SEED_FILES } from './file-adapter.js';

+// The real shipping manifest — the fixture uses it verbatim so these tests
+// exercise production ownership resolution, not a synthetic copy (#791).
+const REAL_FRAMEWORK_ROOT = fileURLToPath(new URL('../../framework', import.meta.url));
+
 /**
 * Regression tests for the `FileConfigAdapter.syncFramework` seed behavior.
 *
@@ -34,6 +47,13 @@ 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');
@@ -102,9 +122,10 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
  });

  it('overwrites framework-owned files (backup-once) but preserves user-seeded files', async () => {
-    // Plant a root-level AGENTS.md in sourceDir so syncDirectory's preserve is exercised.
-    writeFileSync(join(fixture.sourceDir, 'AGENTS.md'), '# shipped AGENTS from source root\n');
-
+    // Contract files (CONSTITUTION/AGENTS/STANDARDS) ship only under defaults/ —
+    // reconcile_framework_files is their sole writer (backup-once). The bulk
+    // sync never sees a root-level copy, so a user's edited root file is backed
+    // up, not silently clobbered, on upgrade.
    writeFileSync(join(fixture.mosaicHome, 'TOOLS.md'), '# user-customized TOOLS\n');
    writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n');

--- a/packages/mosaic/src/config/file-adapter.ts
+++ b/packages/mosaic/src/config/file-adapter.ts
@@ -34,6 +34,7 @@ import {
  buildToolsTemplateVars,
 } from '../template/builders.js';
 import { atomicWrite, backupFile, syncDirectory } from '../platform/file-ops.js';
+import { loadManifest, resolveOwnership } from '../framework/manifest.js';

 /**
 * Parse a SoulConfig from an existing SOUL.md file.
@@ -155,38 +156,22 @@ export class FileConfigAdapter implements ConfigService {
  }

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

    syncDirectory(this.sourceDir, this.mosaicHome, {
-      preserve: preservePaths,
      excludeGit: true,
+      isOperatorOwned: manifest
+        ? (relPath) => resolveOwnership(manifest, relPath) === 'operator'
+        : undefined,
    });

    // Reconcile framework-contract files from framework/defaults/ into the mosaic
--- a/packages/mosaic/src/fleet/deterministic-order.ts
+++ b/packages/mosaic/src/fleet/deterministic-order.ts
@@ -0,0 +1,18 @@
+/** Locale-independent Unicode code-point ordering for canonical fleet evidence. */
+export function compareCodePoints(left: string, right: string): number {
+  const leftPoints = Array.from(left, (character): number => character.codePointAt(0) ?? 0);
+  const rightPoints = Array.from(right, (character): number => character.codePointAt(0) ?? 0);
+  const sharedLength = Math.min(leftPoints.length, rightPoints.length);
+
+  for (let index = 0; index < sharedLength; index += 1) {
+    const leftPoint = leftPoints[index];
+    const rightPoint = rightPoints[index];
+    if (leftPoint === undefined || rightPoint === undefined) continue;
+    if (leftPoint !== rightPoint) return leftPoint < rightPoint ? -1 : 1;
+  }
+  return leftPoints.length < rightPoints.length
+    ? -1
+    : leftPoints.length > rightPoints.length
+      ? 1
+      : 0;
+}
--- a/packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts
+++ b/packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts
@@ -303,25 +303,22 @@ describe('FCM-M3-002 reconciler lifecycle acceptance', (): void => {
    expect(process.exitCode).toBe(0);
  });

-  it.each([
-    {
-      label: 'missing',
-      source: renderRosterV2Yaml(baseRoster).replace(/^  socket_name:.*\n/m, ''),
-    },
-    {
-      label: 'empty',
-      source: renderRosterV2Yaml(baseRoster).replace(/^  socket_name:.*$/m, '  socket_name: ""'),
-    },
-  ])(
-    'rejects a $label canonical roster-v2 tmux socket through parseRosterV2',
-    ({ source }): void => {
-      expect(() => parseRosterV2(source, 'yaml')).toThrow(
-        'Roster v2 tmux socket_name is required and must be a non-empty string.',
-      );
-    },
-  );
+  it('rejects a missing canonical roster-v2 tmux socket through parseRosterV2', (): void => {
+    const source = renderRosterV2Yaml(baseRoster).replace(/^  socket_name:.*\n/m, '');
+    expect(() => parseRosterV2(source, 'yaml')).toThrow(
+      'Roster v2 tmux socket_name is required and must be a string.',
+    );
+  });

-  it('uses the literal default tmux server only through the legacy-v1 loader and runtime transport boundary', async (): Promise<void> => {
+  it('accepts an explicit empty canonical roster-v2 socket as the literal default server', (): void => {
+    const source = renderRosterV2Yaml(baseRoster).replace(
+      /^  socket_name:.*$/m,
+      '  socket_name: ""',
+    );
+    expect(parseRosterV2(source, 'yaml').tmux.socketName).toBe('');
+  });
+
+  it('omits -L for the literal default tmux server at the runtime transport boundary', async (): Promise<void> => {
    const rosterPath = await fixtureLegacyRoster();
    const runner = vi.fn<CommandRunner>(
      async (): Promise<CommandResult> => ({
--- a/packages/mosaic/src/fleet/fleet-reconciler.spec.ts
+++ b/packages/mosaic/src/fleet/fleet-reconciler.spec.ts
@@ -274,6 +274,95 @@ describe('fleet roster-owned reconciler', (): void => {
    ]);
  });

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

  if (request.command === 'status' || request.command === 'doctor') {
@@ -477,6 +478,19 @@ function assertVerificationSafe(plan: FleetReconcilePlan): void {
  }
 }

+function assertLifecycleSocketAuthority(request: FleetReconcileRequest): void {
+  const usesFixedLifecycleUnits =
+    request.command === 'apply' ||
+    request.command === 'reconcile' ||
+    isLifecycleCommand(request.command);
+  if (usesFixedLifecycleUnits && request.roster.tmux.socketName === '') {
+    throw new FleetReconcileError(
+      'lifecycle-precondition-failed',
+      'Default-server lifecycle mutation is unsupported by the fixed named-socket systemd units.',
+    );
+  }
+}
+
 function targetAgentsFor(roster: FleetRosterV2, agentName?: string): readonly FleetRosterV2Agent[] {
  if (agentName === undefined) return roster.agents;
  const agent = roster.agents.find(
--- a/packages/mosaic/src/fleet/generated-env-boundary.spec.ts
+++ b/packages/mosaic/src/fleet/generated-env-boundary.spec.ts
@@ -9,12 +9,13 @@ import {
  symlink,
  writeFile,
 } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
  AgentEnvBoundaryError,
  parseAgentEnvironment,
+  previewAgentEnvironmentProjection,
  renderGeneratedAgentEnvironment,
  writeAgentEnvironmentProjection,
 } from './generated-env-boundary.js';
@@ -86,6 +87,77 @@ describe('generated fleet agent environment boundary', (): void => {
    }).toThrow(AgentEnvBoundaryError);
  });

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

 export type AgentEnvironmentKind = 'generated' | 'local';

@@ -30,6 +32,15 @@ export interface AgentEnvironmentProjectionResult {
  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }

+/** Sanitized, non-mutating projection evidence safe for migration output. */
+export interface AgentEnvironmentProjectionPreview {
+  readonly agentName: string;
+  readonly generated: 'rebuild';
+  readonly legacy: 'absent' | 'regenerate-only' | 'relocate-local' | 'quarantine';
+  readonly relocatedKeys: readonly string[];
+  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
+}
+
 /** A projection fully validated without changing managed files. */
 export interface PreparedAgentEnvironmentProjection {
  readonly mosaicHome: string;
@@ -40,6 +51,7 @@ export interface PreparedAgentEnvironmentProjection {
  readonly generated: string;
  readonly local: string;
  readonly legacy?: string;
+  readonly legacyRelocatedKeys: readonly string[];
  readonly quarantinePath?: string;
  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
@@ -186,6 +198,7 @@ export async function prepareAgentEnvironmentProjection(
    generated,
    local,
    ...(legacy === undefined ? {} : { legacy }),
+    legacyRelocatedKeys: Object.keys(legacyDisposition.localValues).sort(compareCodePoints),
    ...(quarantinePath === undefined ? {} : { quarantinePath }),
    diagnostics: legacyDisposition.diagnostics,
  };
@@ -208,6 +221,33 @@ export async function prepareAgentGeneratedProjectionDeletion(
  return generatedPath;
 }

+export async function previewAgentEnvironmentProjection(
+  options: AgentEnvironmentProjectionOptions,
+): Promise<AgentEnvironmentProjectionPreview> {
+  const prepared = await prepareAgentEnvironmentProjection(options);
+  const relocatedKeys = prepared.legacyRelocatedKeys;
+  const legacy =
+    prepared.legacy === undefined
+      ? 'absent'
+      : prepared.diagnostics.length > 0
+        ? 'quarantine'
+        : relocatedKeys.length > 0
+          ? 'relocate-local'
+          : 'regenerate-only';
+  return {
+    agentName: options.agentName,
+    generated: 'rebuild',
+    legacy,
+    relocatedKeys,
+    diagnostics: [...prepared.diagnostics].sort((left, right): number =>
+      compareCodePoints(
+        `${left.key}:${left.code}:${left.sha256}`,
+        `${right.key}:${right.code}:${right.sha256}`,
+      ),
+    ),
+  };
+}
+
 /** Applies a previously prepared deterministic projection. */
 export async function applyPreparedAgentEnvironmentProjection(
  prepared: PreparedAgentEnvironmentProjection,
@@ -279,7 +319,7 @@ function normalizeGeneratedValues(
  for (const key of GENERATED_AGENT_ENV_KEYS) {
    const value = values[key];
    if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
-    normalized[key] = value;
+    normalized[key] = key === 'MOSAIC_AGENT_WORKDIR' ? expandHomeDirectory(value) : value;
  }
  for (const [key, value] of Object.entries(values)) {
    if (!GENERATED_KEY_SET.has(key)) throw new AgentEnvBoundaryError('unknown-key', key, value);
@@ -288,17 +328,23 @@ function normalizeGeneratedValues(
  return Object.freeze(normalized);
 }

+function expandHomeDirectory(path: string): string {
+  if (path === '~') return homedir();
+  if (!path.startsWith('~/') || path.split('/').includes('..')) return path;
+  return join(homedir(), path.slice(2));
+}
+
 function renderLocalAgentEnvironment(values: Readonly<Record<string, string>>): string {
  if (Object.keys(values).length === 0) return '';
  const parsed = parseAgentEnvironment(
    Object.entries(values)
-      .sort(([left], [right]): number => left.localeCompare(right))
+      .sort(([left], [right]): number => compareCodePoints(left, right))
      .map(([key, value]): string => `${key}=${value}`)
      .join('\n'),
    'local',
  );
  return `${Object.entries(parsed)
-    .sort(([left], [right]): number => left.localeCompare(right))
+    .sort(([left], [right]): number => compareCodePoints(left, right))
    .map(([key, value]): string => `${key}=${value}`)
    .join('\n')}\n`;
 }
--- a/packages/mosaic/src/fleet/roster-v2.spec.ts
+++ b/packages/mosaic/src/fleet/roster-v2.spec.ts
@@ -45,6 +45,12 @@ agents:

 let semanticTmp: string | undefined;

+it('preserves an explicit empty socket as the literal default tmux server', () => {
+  const roster = parseRosterV2(validRoster.replace('socket_name: mosaic-fleet', "socket_name: ''"));
+  expect(roster.tmux.socketName).toBe('');
+  expect(renderRosterV2Yaml(roster)).toContain('socket_name: ""');
+});
+
 afterEach(async (): Promise<void> => {
  if (semanticTmp) await rm(semanticTmp, { recursive: true, force: true });
  semanticTmp = undefined;
--- a/packages/mosaic/src/fleet/roster-v2.ts
+++ b/packages/mosaic/src/fleet/roster-v2.ts
@@ -10,6 +10,7 @@ import {
  type PersonaResolution,
  type RoleAuthority,
 } from '../commands/fleet-personas.js';
+import { compareCodePoints } from './deterministic-order.js';

 export const ROSTER_V2_SUPPORTED_RUNTIMES = ['claude', 'codex', 'opencode', 'pi'] as const;
 export const ROSTER_V2_REASONING_LEVELS = ['low', 'medium', 'high'] as const;
@@ -172,7 +173,7 @@ export const ROSTER_V2_JSON_SCHEMA: JsonSchema = {
      additionalProperties: false,
      required: ['socket_name', 'holder_session'],
      properties: {
-        socket_name: { type: 'string', pattern: '^[A-Za-z0-9_.-]+$' },
+        socket_name: { type: 'string', pattern: '^[A-Za-z0-9_.-]*$' },
        holder_session: { type: 'string', pattern: '^[A-Za-z0-9_.-]+$' },
      },
    },
@@ -272,6 +273,7 @@ const AGENT_KEYS = [
 const LIFECYCLE_KEYS = ['enabled', 'desired_state'];
 const LAUNCH_KEYS = ['yolo'];
 const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const TMUX_SOCKET_IDENTIFIER = /^[A-Za-z0-9_.-]*$/;
 const TMUX_IDENTIFIER = /^[A-Za-z0-9_.-]+$/;
 const POLICY_IDENTIFIER = /^[a-z][a-z0-9-]*$/;

@@ -327,7 +329,7 @@ function normalizeTmux(value: unknown): FleetRosterV2Tmux {
  const raw = requiredObject(value, 'Roster v2 tmux');
  assertKnownKeys(raw, 'Roster v2 tmux', TMUX_KEYS);
  return {
-    socketName: requiredTmuxIdentifier(raw.socket_name, 'Roster v2 tmux socket_name'),
+    socketName: requiredTmuxSocket(raw.socket_name, 'Roster v2 tmux socket_name'),
    holderSession: requiredTmuxIdentifier(raw.holder_session, 'Roster v2 tmux holder_session'),
  };
 }
@@ -348,7 +350,7 @@ function normalizeRuntimes(value: unknown): Readonly<Record<string, FleetRosterV
    throw new RosterV2ValidationError('Roster v2 runtimes must not be empty.');

  const result: Record<string, FleetRosterV2Runtime> = {};
-  for (const name of names.sort()) {
+  for (const name of names.sort(compareCodePoints)) {
    const runtime = requiredRuntime(name, 'Roster v2 runtime name');
    const config = requiredObject(raw[name], `Roster v2 runtime "${runtime}"`);
    assertKnownKeys(config, `Roster v2 runtime "${runtime}"`, RUNTIME_KEYS);
@@ -416,7 +418,7 @@ function normalizeAgents(
    };
  });
  return agents.sort((left: FleetRosterV2Agent, right: FleetRosterV2Agent): number =>
-    left.name.localeCompare(right.name),
+    compareCodePoints(left.name, right.name),
  );
 }

@@ -473,6 +475,17 @@ function requiredIdentifier(value: unknown, label: string): string {
  return result;
 }

+function requiredTmuxSocket(value: unknown, label: string): string {
+  if (typeof value !== 'string') {
+    throw new RosterV2ValidationError(`${label} is required and must be a string.`);
+  }
+  const result = value.trim();
+  if (!TMUX_SOCKET_IDENTIFIER.test(result)) {
+    throw new RosterV2ValidationError(`Invalid ${label}: ${result}.`);
+  }
+  return result;
+}
+
 function requiredTmuxIdentifier(value: unknown, label: string): string {
  const result = requiredString(value, label);
  if (!TMUX_IDENTIFIER.test(result))
@@ -524,7 +537,7 @@ function toSourceShape(roster: FleetRosterV2): Record<string, unknown> {
    },
    runtimes: Object.fromEntries(
      Object.entries(roster.runtimes)
-        .sort(([left], [right]): number => left.localeCompare(right))
+        .sort(([left], [right]): number => compareCodePoints(left, right))
        .map(([name, runtime]): [string, unknown] => [
          name,
          { reset_command: runtime.resetCommand },
@@ -532,7 +545,7 @@ function toSourceShape(roster: FleetRosterV2): Record<string, unknown> {
    ),
    agents: [...roster.agents]
      .sort((left: FleetRosterV2Agent, right: FleetRosterV2Agent): number =>
-        left.name.localeCompare(right.name),
+        compareCodePoints(left.name, right.name),
      )
      .map(
        (agent: FleetRosterV2Agent): Record<string, unknown> => ({
--- a/packages/mosaic/src/fleet/v1-v2-migration.spec.ts
+++ b/packages/mosaic/src/fleet/v1-v2-migration.spec.ts
--- a/packages/mosaic/src/fleet/v1-v2-migration.ts
+++ b/packages/mosaic/src/fleet/v1-v2-migration.ts
--- a/packages/mosaic/src/framework/manifest-parity.spec.ts
+++ b/packages/mosaic/src/framework/manifest-parity.spec.ts
@@ -0,0 +1,252 @@
+import { afterAll, describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, 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);
+}
+
+// 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'],
+    ]);
+  });
+});
--- a/packages/mosaic/src/framework/manifest.spec.ts
+++ b/packages/mosaic/src/framework/manifest.spec.ts
@@ -0,0 +1,263 @@
+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,
+  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/);
+  });
+});
+
+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');
+    }
+  });
+});
--- a/packages/mosaic/src/framework/manifest.ts
+++ b/packages/mosaic/src/framework/manifest.ts
@@ -0,0 +1,188 @@
+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';
+
+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 Error(`Unknown manifest section header on line ${i + 1}: ${line}`);
+    }
+
+    if (section === null) {
+      throw new Error(`Manifest entry before any [section] header on line ${i + 1}: ${line}`);
+    }
+    (section === 'framework' ? framework : operator).push(line);
+  }
+
+  return { framework, operator };
+}
+
+/** Read and parse the manifest from a framework root directory. */
+export function loadManifest(frameworkRoot: string): FrameworkManifest {
+  const text = readFileSync(`${frameworkRoot}/framework-manifest.txt`, 'utf-8');
+  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;
+}
--- a/packages/mosaic/src/platform/file-ops.ts
+++ b/packages/mosaic/src/platform/file-ops.ts
@@ -62,16 +62,28 @@ function rotateBackups(filePath: string): void {
 /**
 * Sync a source directory to a target, with optional preserve paths.
 * Replaces the rsync/cp logic from install.sh.
+ *
+ * `isOperatorOwned` is the #791 ownership guard: when supplied, any source path
+ * it flags as operator-owned is never copied (the framework must never write an
+ * operator path). Callers derive it from the shared framework manifest so the TS
+ * and bash sync paths obey one source of truth. This copy is non-destructive —
+ * it never deletes a target file — so honoring the guard is sufficient to leave
+ * operator config untouched.
 */
 export function syncDirectory(
  source: string,
  target: string,
-  options: { preserve?: string[]; excludeGit?: boolean } = {},
+  options: {
+    preserve?: string[];
+    excludeGit?: boolean;
+    isOperatorOwned?: (relPath: string) => boolean;
+  } = {},
 ): void {
  // Guard: source and target are the same directory — nothing to sync
  if (resolve(source) === resolve(target)) return;

  const preserveSet = new Set(options.preserve ?? []);
+  const isOperatorOwned = options.isOperatorOwned ?? (() => false);

  // Collect files from source
  function copyRecursive(src: string, dest: string, relBase: string): void {
@@ -86,7 +98,7 @@ export function syncDirectory(
      if (options.excludeGit && (dirName === '.git' || relPath.includes('/.git'))) return;

      // Skip preserved paths at top level
-      if (preserveSet.has(relPath) && existsSync(dest)) return;
+      if (relPath !== '' && preserveSet.has(relPath) && existsSync(dest)) return;

      mkdirSync(dest, { recursive: true });
      for (const entry of readdirSync(src)) {
@@ -101,6 +113,10 @@ export function syncDirectory(
      // Skip preserved files at top level
      if (preserveSet.has(relPath) && existsSync(dest)) return;

+      // #791: never write an operator-owned path (the framework owns only its
+      // own files; unknown paths resolve to operator and are skipped too).
+      if (isOperatorOwned(relPath)) return;
+
      mkdirSync(dirname(dest), { recursive: true });
      copyFileSync(src, dest);
    }
--- a/packages/mosaic/src/runtime/update-checker.ts
+++ b/packages/mosaic/src/runtime/update-checker.ts
@@ -488,9 +488,13 @@ export function getInstallAllCommand(outdated: PackageUpdateResult[]): string {
 // `mosaic update` installs the new npm CLI but, on its own, leaves the framework
 // files in ~/.config/mosaic/ stale — so shipped launcher/runtime changes (e.g.
 // the agent-name export + native heartbeat) never ACTIVATE until a re-seed.
-// These helpers run the package's own install.sh in sync-only mode (the P4
-// data-safe reconcile: framework-owned overwrite + backup-once; SOUL/USER/
-// *.local/credentials preserved) and, opt-in, relaunch durable agents.
+// These helpers run the package's own install.sh in sync-only mode. The re-seed
+// is manifest-driven (#791): keep mode writes ONLY framework-owned paths from the
+// shared framework-manifest.txt and prunes only retired framework files inside
+// shipped subtrees — every operator path (SOUL/USER/*.local/credentials, fleet
+// roster + agents + backlog, and anything the manifest never anticipated) is
+// left byte-identical. Contract files are still reconciled (overwrite +
+// backup-once). Opt-in, this also relaunches durable agents.

 /** Resolve the framework/ directory bundled in the installed package. */
 export function resolveBundledFrameworkRoot(): string {
--- a/packages/mosaic/turbo.json
+++ b/packages/mosaic/turbo.json
@@ -0,0 +1,8 @@
+{
+  "extends": ["//"],
+  "tasks": {
+    "test": {
+      "dependsOn": ["^build", "build"]
+    }
+  }
+}
Author	SHA1	Message	Date
Hermes Agent	0a5e703a70	test(mosaic): gate #797 ledger upgrade-survival + harden manifest parity (#791 ) All checks were successful ci/woodpecker/pr/ci Pipeline was successful Details Fold the Mos-elevated #797 Runtime-Ledger survival sentinel into #791 PR1 and harden the .txt-format parity test per the accepted-format conditions. - framework-manifest.txt: annotate the existing fleet/run/ operator carve-out to name the #797 ledger (fleet/run/sessions/) so it reads as load-bearing. The glob already matches the #797 spec exactly — no location divergence. - HARD GATE (test-upgrade-manifest-guard.sh): seed a populated ledger (events.ndjson journal + ledger.json projection, 0600 under 0700) as an operator sentinel; assert byte-identical + mtime-unchanged + dir-perms unchanged after a keep-mode upgrade. Relabel the prune check as the explicit negative control. 48 -> 58 checks. - Parity (manifest-parity.spec.ts): add format-edge fixtures driven through BOTH resolvers via MANIFEST_FILE — comments/blanks/whitespace, duplicate and overlapping globs (deny-wins), section/glob-ordering independence, and an explicit UNKNOWN->operator negative probe; add ledger probe paths. - manifest.spec.ts: isolate the carve-out's load-bearing value with a resolver red->green — under a hypothetical fleet/ framework glob, the ledger is pruned WITHOUT the fleet/run/** carve-out and protected WITH it (deny-wins). Gates: typecheck, lint, format:check green; mosaic vitest 1069 passed; HARD GATE 58/58; migration 21/21. Commits forward on `34e55d4a` (no rebase). Part of #791 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-16 16:11:06 -05:00
Hermes Agent	34e55d4a2e	feat(mosaic): manifest-owned upgrade guard so updates never wipe operator config (#791 ) All checks were successful ci/woodpecker/pr/ci Pipeline was successful Details Invert the framework updater from a denylist ("framework owns everything unless preserved") to an explicit allow-list manifest ("operator owns everything unless framework"). A path the manifest never anticipated resolves to operator-owned by the fail-safe default, so it is structurally unreachable by any write or prune. Root cause (#791): `mosaic update` re-seeds via `install.sh` keep-mode, whose `rsync -a --delete` + hand-maintained PRESERVE_PATHS denylist wiped operator paths the denylist forgot (agents/.conf, policy/.md, *.local.md, harvester SOP, tools/_lib/credentials.json, unanticipated fleet files). - framework-manifest.txt: single SSOT ([framework]/[operator], deny-wins, UNKNOWN=>operator fail-safe), read by BOTH installers. - src/framework/manifest.ts: pure resolver (parse/matchGlob/resolveOwnership/ frameworkSubtreeRoots/planPrune) — the testable seam. - tools/_lib/manifest.sh: bash resolver (compiled globs, fork-free hot path), sourced by install.sh; parity-tested against the TS resolver. - install.sh keep mode is now manifest-driven (no --delete): overlay-copy framework files, scoped-prune only retired framework files inside shipped subtrees. Operator + unknown paths are never written or deleted. - file-ops.syncDirectory gains an isOperatorOwned guard; file-adapter derives it from the shared manifest, replacing the drifted hardcoded preservePaths. Tests (TDD, red->green): - HARD GATE test-upgrade-manifest-guard.sh: 10 operator sentinels (incl. an unanticipated one) survive a keep-mode reseed byte-identical + mtime-unchanged; retired framework file pruned; secret value absent from output. RED 31 fail on the old installer -> GREEN 48 pass. Wired merge-blocking into CI. - manifest-parity.spec.ts (§6.1): bash<->TS agree on 34 paths + subtree roots. - manifest.spec.ts: 18 tests incl. planPrune property test + shipped-tree completeness (§6.2). - test-install-migration.sh F6 flipped: an unanticipated operator fleet file now MUST survive keep-mode reseed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-16 15:47:28 -05:00
Hermes Agent	87e21fd933	docs(791): Phase-1 design for upgrade config protection Design-only planning artifact for #791. Traces the wipe mechanism (install.sh:199 rsync --delete gated by PRESERVE_PATHS denylist) and specifies the ratified (b)+(a)+(d) fix: framework-owned manifest allow-list with fail-safe unknown=>operator default and manifest-scoped prune, a transactional pre-update snapshot with mosaic restore, and a projection-only mosaic fleet regen recovery path. No implementation changes. Refs #791 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-16 15:14:50 -05:00
jason.woltje	9745bc3f29	feat(fleet): add reviewed v1-to-v2 migration preview (#788 ) All checks were successful ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details	2026-07-16 13:11:16 +00:00