co-attest: probe-3 v10 byte-scope-verify PASS @ce5ba762 (B9 no-site, exact 2-line -S delta) — supersedes f320d075

Independent Opus SECREV review (ms-secrev-828 lane, dispatched by mosaic-100;
Gate-16 author≠reviewer; byte-only; did not build).
Reviewed object = ce5ba76205
harness sha256 = 7e14ead89a7b2a297fcc17e7653291b3bcace1d2002a8f90a989db74f6985b6f
Verdict PASS: B9 no-site startup closure — launcher -s -S -B (no -I) :515,
broker -I -S -B :554; empirically confirmed site NOT imported (no_site=1) so
system-site .pth/sitecustomize cannot run unpinned startup code; -S leaves
sys.path[0] intact so launcher sibling import + broker explicit --generation-module
import both still bind the pinned helper; delta vs 1c34e3cb = EXACT 2-line -S only
(byte-compared). All priors (B5/B6/B6c/B7/B8/fidelity/traceability/lease_anchor/
live-path/single-broker/--runs/-O-safe) byte-stable. Byte review only; ran nothing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.prettierignore

@@ -7,4 +7,3 @@ pnpm-lock.yaml
 .claude/
 docs/tess/TASKS.md
 docs/scratchpads/
-packages/mosaic/src/fleet/testdata/documentation-publication-v1/inline-migration-v1.json

.woodpecker/ci.yml

@@ -42,6 +42,27 @@ steps:
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
 
+  # Blocking gate (#791): a framework upgrade must never write or delete an
+  # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
+  # survives a keep-mode reseed byte-identical (with rsync present AND absent —
+  # keep mode is a single cp-based path that must not depend on rsync), and that a
+  # corrupt/empty/missing manifest aborts fail-closed leaving operator files
+  # untouched (B2/B3). The rollback gate proves a mid-sync failure is rolled back
+  # from the pre-update snapshot (B1). The durable-snapshot gate (#791 PR2) proves
+  # the retained, operator-scoped pre-update backup is taken before any mutation
+  # (0700/0600, secret never logged, retention-pruned) and that the post-sync
+  # verify net restores any operator file a manifest bug lets the sync touch. The
+  # migration matrix pins the v2→v3 contract-file semantics. Pure bash, no
+  # node_modules — runs early alongside sanitization.
+  upgrade-guard:
+    image: *node_image
+    commands:
+      - apk add --no-cache bash rsync
+      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-manifest-guard.sh
+      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh
+      - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh
+      - bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
+
   typecheck:
     image: *node_image
     commands:
@@ -50,6 +71,7 @@ steps:
     depends_on:
       - install
       - sanitization
+      - upgrade-guard
 
   # lint, format, and test are independent — run in parallel after typecheck
   lint:

Dockerfile.ci

@@ -22,10 +22,10 @@
 FROM node:24-alpine
 
 # Native toolchain required to compile node-gyp deps on musl, plus the
-# postgresql-client used by the test step's pg_isready readiness probe. `bash`
-# is baked here too — the sanitization step in ci.yml otherwise does a per-run
-# `apk add bash`.
-RUN apk add --no-cache python3 make g++ postgresql-client bash
+# postgresql-client used by the test step's pg_isready readiness probe. `bash`,
+# `git`, and `jq` are baked here too — framework shell tests and the shipped
+# Codex review wrappers require them without per-run installation in ci.yml.
+RUN apk add --no-cache python3 make g++ postgresql-client bash git jq
 
 # Pin pnpm to the repo's packageManager version via corepack.
 RUN corepack enable && corepack prepare pnpm@10.6.2 --activate

README.md

@@ -97,7 +97,10 @@ mosaic config path           # Print config file path
 ```bash
 mosaic doctor                # Health audit — detect drift and missing files
 mosaic sync                  # Sync skills from canonical source
-mosaic update                # Check for and install CLI updates
+mosaic skill list            # Audit Claude skill registrations and conflicts
+mosaic skill register <name> # Register one canonical skill with Claude Code
+mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
+mosaic update                # Update CLI/framework and auto-register canonical skills
 mosaic wizard                # Full guided setup wizard
 mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
 mosaic coord init            # Initialize a new orchestration mission
@@ -349,6 +352,8 @@ bash tools/install.sh --yes             # Non-interactive, accept all defaults
 bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```
 
+The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
+
 ## Contributing
 
 ```bash

docs/SITEMAP.md

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

docs/TASKS.md

@@ -53,7 +53,7 @@ Active workstream is **W1 — Federation v1**. Workers should:
 > the applicable acceptance evidence before merge. Issue #758 remains open until M5 closes.
 
 | id         | status      | description                                                                                                                                                            | issue | agent         | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                            |
-| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
 | FCM-M0-001 | done        | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet        | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5                                   |
 | FCM-M1-001 | done        | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | coder0        | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation               |
 | FCM-M1-002 | done        | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | #768 squash `a5e8e55`; shared resolver and canonical authority/alias validation delivered                        |
@@ -62,10 +62,10 @@ Active workstream is **W1 — Federation v1**. Workers should:
 | FCM-M2-002 | done        | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex         | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | #773 squash `bc5e736`; generation-guarded atomic CRUD and recovery contracts delivered                           |
 | FCM-M3-001 | done        | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex         | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | #785 squash `4990905`; exact roster-owned systemd/tmux reconcile and lifecycle contracts delivered               |
 | FCM-M3-002 | in-progress | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet        | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Canonical v2 named-socket + legacy-v1 default-server boundaries; fake adapters/temp fixtures only                |
-| FCM-M4-001 | done        | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | PR #788; final head `d63bb0206a1d312ab8352ec1d3ca3631146b0baa`; tree `4da210da9a71b035130d4160a4a2e691bdfde2da`; squash `9745bc3f29c26b021a478b7ad03cfb494f6c9de3`; descendant-main pipeline 1855 terminal success |
-| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | HOLD: never starts a previously stopped agent or kills an unproven unmanaged session; not authorized by FCM-M5-001                                                                                                 |
-| FCM-M5-001 | in-progress | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Sole owner: this FCM-M5-001 delivery on the recorded branch; must close every checklist item or record an approved deferral                                                                                        |
-| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | HOLD: final #758 gate; quality, independent code/security review, validator certificate, merge-gate approval, and green CI remain out of M5-001                                                                    |
+| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | Preview first; no unreviewed lifecycle inference                                                                 |
+| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | Never starts a previously stopped agent or kills an unproven unmanaged session                                   |
+| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Must close every checklist item or record an approved deferral                                                   |
+| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI |
 
 ## Thin-core prompt diet (#528) — feat/contract-thin-core
 

docs/compaction-refresh/GATE0-EVIDENCE.md

@@ -0,0 +1,352 @@
+# Compaction-Refresh WI-0 Gate0 Evidence Pack
+
+- **Issue:** Gitea #827
+- **Milestone:** 188 — Compaction-Refresh Mechanism
+- **Branch:** `feat/827-gate0-probe`
+- **Starting HEAD:** `d801d6c4c8a984d6a95033c49714210018d3d9a8`
+- **Host/runtime:** Linux 6.1.0-48-amd64; Mosaic 0.0.48; Pi 0.80.7; Claude Code 2.1.205
+- **Scope:** Probe fixtures and evidence only. No WI-1..WI-7 feature implementation.
+
+## Verdict — 5/6 PASS; BUILD ADMISSION: **NO**
+
+| Probe | Verdict | Short result |
+| --- | --- | --- |
+| P1 launcher topology + ancestry | **PASS** | Real Mosaic→Pi and Mosaic→Claude chains reached the registered anchor; real Claude `SessionStart` hook ancestry accepted; same-UID sibling with the minted victim ID rejected. |
+| P2 Pi last-position + nonce map | **PASS** | Real Pi proved last-or-closed; `message_end` mapped exact `toolCallId → requestNonce` before `tool_call`; provider-response hook occurred before stream consumption/content completion. |
+| P3 same-PID generation revocation | **PASS** | Same Pi PID/starttime persisted through reload/fork/new/resume while broker generations increased; reload revoked a prior `VERIFIED` generation. |
+| P4 `SO_PEERCRED` + socket posture | **PASS** | Real Unix socket peer PID/UID/starttime matched `/proc`; 0700 directory + 0600 socket demonstrated. Same-UID counterfeit replacement remains explicitly T-C without a distinct principal/authenticated response. |
+| P5 source invalidation | **PASS** | Missing, oversize, and hash-mismatched fragments each refused injection/promotion, revoked broker state, and blocked the exact emitted tool call. |
+| P6 atomic injection | **T-C GAP** | Both runtimes empirically delivered a complete single block/message, but neither installed runtime contract states an **atomic/prefix-preserving** transport guarantee. Observation is not a guarantee; A-v5-1/T27 cannot be admitted. |
+
+**Planner return item:** P6. The evidence establishes successful complete delivery in these runs, not the required invariant that the harness cannot middle-drop/replace bytes while preserving the terminal token. Per R1, such a middle-drop is not receipt-detectable. It is therefore classed **T-C**, not assumed away.
+
+## STEP 0 — Authority re-verification
+
+Command:
+
+```bash
+sha256sum \
+  ~/agent-work/reviews/compaction-refresh-BUILD-BRIEF.md \
+  ~/agent-work/reviews/compaction-refresh-SPEC-v5.md \
+  ~/agent-work/reviews/compaction-refresh-SPEC-RATIFICATION.md
+```
+
+Captured result:
+
+```text
+89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b  .../compaction-refresh-BUILD-BRIEF.md
+a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433  .../compaction-refresh-SPEC-v5.md
+bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67  .../compaction-refresh-SPEC-RATIFICATION.md
+```
+
+All three **MATCH**. They were read in full before probe construction. Raw artifact: [`evidence/raw/STEP0-authority-hashes.txt`](./evidence/raw/STEP0-authority-hashes.txt).
+
+## Evidence method
+
+The scripts under [`probes/`](./probes/) are isolated Gate0 instrumentation, not product implementation. They run the installed `mosaic yolo` launcher and real installed runtime binaries. Broker prototypes use Linux `SO_PEERCRED` and `/proc`; runtime adapters are temporary Claude hooks/Pi extensions. No product source under `packages/mosaic` was changed.
+
+Raw-output artifact integrity is indexed at [`evidence/RAW-SHA256SUMS.txt`](./evidence/RAW-SHA256SUMS.txt).
+
+---
+
+## P1 — Launcher exec/parent topology + supported-hook ancestry (D1)
+
+**Verdict: PASS**
+
+### Commands
+
+```bash
+python3 docs/compaction-refresh/probes/p1_run.py --runtime both
+rg -n "spawnSync|execRuntime" \
+  ~/.npm-global/lib/node_modules/@mosaicstack/mosaic/dist/commands/launch.js | tail -8
+```
+
+Full outputs:
+
+- [`evidence/raw/P1-launch-ancestry.txt`](./evidence/raw/P1-launch-ancestry.txt)
+- [`evidence/raw/P1-claude-hook-events.txt`](./evidence/raw/P1-claude-hook-events.txt)
+
+### Real topology observed
+
+The installed Mosaic launcher does **not** replace itself with the runtime despite its `execRuntime` name; installed `launch.js:668` uses `spawnSync`. The Gate0 anchor first registered, then `execvpe` replaced the anchor with the real `mosaic yolo` process (PID/starttime retained). Mosaic remained the stable parent while it spawned the runtime.
+
+Pi run:
+
+```text
+anchor before exec: pid=4010843 starttime=365919858 exe=/usr/bin/python3.11
+anchor after exec:  pid=4010843 starttime=365919858 exe=/usr/bin/node
+Pi runtime:         pid=4011046 ppid=4010843 starttime=365920219 exe=/usr/bin/node
+
+ps:
+4010843 4010840 Fri Jul 17 19:35:18 2026 1001 1001 node
+4011046 4010843 Fri Jul 17 19:35:22 2026 1001 1001 pi
+```
+
+Claude supported-hook run (latest capture):
+
+```text
+hook python  pid=4011380 starttime=365920845
+  -> /bin/sh pid=4011379 starttime=365920845
+  -> claude  pid=4011285 starttime=365920748
+  -> node/mosaic anchor pid=4011129 starttime=365920380
+```
+
+The stream independently recorded the real hook firing:
+
+```json
+{"type":"system","subtype":"hook_started","hook_name":"SessionStart:startup","hook_event":"SessionStart"}
+{"type":"system","subtype":"hook_response","hook_name":"SessionStart:startup","exit_code":0,"outcome":"success","stdout":"...GATE0_P1_SUPPORTED_HOOK_ANCESTRY_ACCEPTED..."}
+```
+
+### Authentication and sibling substitution
+
+The broker minted the logical ID on first peercred contact and keyed the anchor by `(pid,starttime)`. It took the hook/extension PID from `SO_PEERCRED`, walked `/proc/<pid>/stat`, and re-read every starttime before accepting.
+
+Real Pi acceptance excerpt:
+
+```json
+{"peercred":{"pid":4011046,"uid":1001,"gid":1001},"decision":"ACCEPT","reason":"ancestry-reaches-registered-anchor","starttimes_rechecked":true}
+```
+
+A separately spawned same-UID sibling was given the real minted victim ID. Its ancestry did not reach the anchor:
+
+```json
+{"attacker_uid":1001,"victim_session_id_known":true,"broker_decision":"REJECT","broker_reason":"victim-id-known-but-ancestry-mismatch"}
+```
+
+The same rejection occurred in both Pi and Claude runs. This is positive runtime evidence for D1/T15a under the supported non-daemonizing topology.
+
+---
+
+## P2 — Pi last-position invariant + nonce map (D5)
+
+**Verdict: PASS**
+
+### Commands
+
+```bash
+python3 docs/compaction-refresh/probes/pi_gate0_run.py
+python3 docs/compaction-refresh/probes/p2_provider_timing_run.py
+```
+
+Full outputs:
+
+- [`evidence/raw/P2-P3-P5-P6-pi.txt`](./evidence/raw/P2-P3-P5-P6-pi.txt)
+- [`evidence/raw/P2-provider-timing.txt`](./evidence/raw/P2-provider-timing.txt)
+
+### Last-or-closed evidence
+
+Real Pi argv/load order with the probe last:
+
+```json
+{"extensions":[".../mosaic-extension.ts",".../pi_gate0_extension.ts"],"lastPosition":true,"gateState":"UNVERIFIED_READY","pid":4004545}
+```
+
+A second real Pi launch deliberately appended a later handler:
+
+```json
+{"extensions":[".../mosaic-extension.ts",".../pi_gate0_extension.ts",".../pi_later_extension.ts"],"lastPosition":false,"gateState":"CLOSED_NOT_LAST","pid":4005692}
+```
+
+Thus the invariant observed is exactly **last or closed**, not an asserted registration order.
+
+### Exact nonce → tool-call-ID map
+
+In one real GPT-5.6 Sol Pi response, sequence 5 completed the assistant tool-call message and bound its exact ID:
+
+```json
+{"seq":5,"event":"message_end","requestNonce":"e5a82358-a6c9-490b-a0de-2e1f1d9b8d79","toolCallIds":["call_bgGE...57c"],"nonceMappings":[{"toolCallId":"call_bgGE...57c","requestNonce":"e5a82358-a6c9-490b-a0de-2e1f1d9b8d79"}]}
+```
+
+The following `tool_call` was sequence 6 and carried the same ID/nonce:
+
+```json
+{"seq":6,"event":"tool_call","toolCallId":"call_bgGE...57c","mapping":{"nonce":"e5a82358-a6c9-490b-a0de-2e1f1d9b8d79","verified":true},"allowed":true}
+```
+
+The harmless tool executed at sequence 7 with that same tool-call ID. No session-global “current epoch” was borrowed.
+
+### `after_provider_response` is not assistant-content observation
+
+A deterministic localhost HTTP provider was used only to force headers/status exposure through the real Pi transport. Actual order:
+
+```json
+{"seq":4,"event":"before_provider_request"}
+{"seq":5,"event":"after_provider_response","status":200,"assistantContentAvailableAtThisHook":false,"timing":"headers/status before stream consumption"}
+{"seq":6,"event":"message_end","role":"assistant","assistantContentObserved":true}
+```
+
+```text
+headers_hook_precedes_completed_message=True
+```
+
+This positively confirms SPEC-v5’s precision correction: receipt content is observed at `message_end`; `after_provider_response` is status/headers before stream consumption.
+
+---
+
+## P3 — Same-PID `runtime_generation` bump revokes prior lease (D4)
+
+**Verdict: PASS**
+
+### Command
+
+```bash
+python3 docs/compaction-refresh/probes/pi_gate0_run.py
+```
+
+Full output: [`evidence/raw/P2-P3-P5-P6-pi.txt`](./evidence/raw/P2-P3-P5-P6-pi.txt).
+
+The real Pi process identity remained:
+
+```text
+pid=4004545 starttime_ticks=365907677 uid=1001
+```
+
+Broker state around reload:
+
+```json
+{"event":"runtime_generation_bump","reason":"startup","old_generation":0,"new_generation":1,"new_lease_state":"UNVERIFIED"}
+{"event":"probe_lease_promoted","generation":1,"new_lease_state":"VERIFIED"}
+{"event":"runtime_generation_bump","phase":"shutdown","reason":"reload","old_generation":1,"new_generation":2,"prior_lease":"VERIFIED","prior_lease_revoked":true,"new_lease_state":"REVOKED"}
+{"event":"runtime_generation_bump","phase":"start","reason":"reload","old_generation":2,"new_generation":3,"new_lease_state":"UNVERIFIED"}
+```
+
+The same `(pid,starttime)` then emitted monotonic bumps for real `fork`, `new`, and `resume` replacement flows, reaching generation 12. Pi 0.80.7 emitted an additional conservative `session_start` callback in each of those replacement flows; the broker bumped again rather than reusing authority. This is an availability/idempotence consideration for implementation, not a fail-open result.
+
+---
+
+## P4 — `SO_PEERCRED` + socket authenticity posture
+
+**Verdict: PASS, with the spec’s named same-UID T-C residual**
+
+### Command
+
+```bash
+python3 docs/compaction-refresh/probes/p4_peercred_probe.py
+```
+
+Full output: [`evidence/raw/P4-so-peercred.txt`](./evidence/raw/P4-so-peercred.txt).
+
+Captured real socket result:
+
+```text
+server_pid=4013762 server_uid=1001 server_gid=1001
+directory_mode=0700 socket_mode=0600
+SO_PEERCRED pid=4013768 uid=1001 gid=1001
+client_claim={"pid":4013768,"starttime_ticks":365927069,"uid":1001,...}
+proc_observed={"pid":4013768,"starttime_ticks":365927069,"uid":1001,...}
+pid_match=True
+uid_match=True
+starttime_match=True
+client_exit_status=0
+```
+
+Achievable unprivileged posture on this host is a user-owned 0700 parent plus 0600 socket. That excludes other UIDs and positively authenticates the connecting kernel PID/UID/GID. It does **not** stop another process running as `hermes` from unlinking/rebinding the socket. A claim stronger than T-C against counterfeit replacement therefore requires the ratified distinct-principal system service or authenticated broker responses. No stronger claim is made.
+
+---
+
+## P5 — Source invalidation fail-closed
+
+**Verdict: PASS**
+
+### Command
+
+```bash
+python3 docs/compaction-refresh/probes/pi_gate0_run.py
+```
+
+Full output: [`evidence/raw/P2-P3-P5-P6-pi.txt`](./evidence/raw/P2-P3-P5-P6-pi.txt).
+
+Each fault was injected into the manifest/source read by the real Pi `context` hook. Each run reached an actual model-produced `toolCallId`, then the runtime gate refused it:
+
+| Fault | Runtime validation | Injection/promotion | Broker | Tool result |
+| --- | --- | --- | --- | --- |
+| Missing path | `reason=missing` | `injectionDecision=REFUSED`, `promotion=false` | `source_invalidation_revoke` | `allowed=false`, `unverified-source:missing` |
+| 65 bytes with 64-byte max | `reason=oversize` | `REFUSED`, `promotion=false` | revoked | `allowed=false`, `unverified-source:oversize` |
+| Bytes differ from pinned SHA-256 | `reason=hash-mismatch` | `REFUSED`, `promotion=false` | revoked | `allowed=false`, `unverified-source:hash-mismatch` |
+
+Missing example:
+
+```json
+{"event":"context_return","sourceValidation":{"ok":false,"reason":"missing"},"injectionDecision":"REFUSED","promotion":false,"sourceBroker":{"event":"source_invalidation_revoke","new_lease_state":"REVOKED"}}
+{"event":"tool_call","mapping":{"verified":false,"sourceReason":"missing"},"allowed":false,"reason":"unverified-source:missing"}
+```
+
+No fault case reached tool execution or promotion.
+
+---
+
+## P6 — Atomic Claude `additionalContext` + Pi `context` injection (A-v5-1 / T27)
+
+**Verdict: T-C GAP — returns to planner**
+
+### Commands
+
+```bash
+python3 docs/compaction-refresh/probes/pi_gate0_run.py
+python3 docs/compaction-refresh/probes/p6_claude_run.py
+rg -n -i "atomic|prefix-preserv" <installed Pi and Claude hook docs>
+```
+
+Full outputs:
+
+- [`evidence/raw/P2-P3-P5-P6-pi.txt`](./evidence/raw/P2-P3-P5-P6-pi.txt)
+- [`evidence/raw/P6-claude-additional-context.txt`](./evidence/raw/P6-claude-additional-context.txt)
+- [`evidence/raw/P6-contract-gap.txt`](./evidence/raw/P6-contract-gap.txt)
+
+### Positive empirical observations
+
+**Pi:** The real `context` hook returned exactly one additional `AgentMessage`; the prior message prefix hash was unchanged. The real final provider payload contained exactly one occurrence in one content item, and the real model copied all bytes exactly:
+
+```json
+{"event":"context_return","inputCount":1,"outputCount":2,"injectionDecision":"ONE_ATOMIC_AGENT_MESSAGE","prefixPreservedByReturn":true,"blockLength":108,"blockSha256":"99c3...a0dd"}
+{"event":"before_provider_request","markerOccurrences":1,"markerPaths":["$.input[1].content[0].text"],"finalPayloadValid":true}
+{"event":"message_end","exactContextBlockCopied":true,"assistantTextSha256":"99c3...a0dd"}
+```
+
+**Claude:** The real `SessionStart` hook emitted one `hookSpecificOutput.additionalContext` string. Claude’s stream recorded successful hook execution, and the real model’s exact copied block matched byte length and SHA-256:
+
+```text
+block_length=116
+block_sha256=ef6377d63552af075f4f4adec00165988418c5f46a992f4dce8e678b56fd34ac
+assistant_copy_length=116
+assistant_copy_sha256=ef6377d63552af075f4f4adec00165988418c5f46a992f4dce8e678b56fd34ac
+assistant_copy_exact=True
+```
+
+### Why this is not a PASS
+
+The installed Pi documentation says only that `context` receives a deep copy and may return `{ messages }`. The installed Claude documentation says only that `additionalContext` enters/adds to context/system prompt. The exact search result was:
+
+```text
+NO MATCH: neither installed runtime document states an atomic/prefix-preserving transport guarantee.
+```
+
+One or several successful complete deliveries cannot prove the transport invariant needed by A-v5-1. In particular, a harness-side middle deletion/replacement that preserves the terminal receipt is not detectable by the receipt. That is precisely R1’s assurance boundary. Therefore:
+
+- absent or prefix-truncated terminal token: receipt-detectable;
+- middle-drop preserving the tail token: **not receipt-detectable**;
+- no documented runtime contract excludes that transform;
+- classification: **T-C contract gap**.
+
+No atomicity claim is inferred from empirical success.
+
+---
+
+## Independent probe review
+
+After an initial review identified a session-global P2 correlation flaw, the probe was changed to queue request-scoped cycles from `before_provider_request` through assistant `message_end`; all runtime probes were re-run and raw checksums regenerated. The final independent review command was:
+
+```bash
+~/.config/mosaic/tools/codex/codex-code-review.sh \
+  -b d801d6c4c8a984d6a95033c49714210018d3d9a8 \
+  -o /tmp/827-gate0-rereview.json
+```
+
+Final review: **APPROVE**, confidence 0.91, 18 files reviewed, 0 blockers, 0 should-fix findings, 0 suggestions.
+
+## Final admission decision
+
+Gate0 requires every item to produce positive runtime evidence. P6 does not. **Do not admit WI-1..WI-7. Return A-v5-1/T27 to planner review.**
+
+No feature work, push, PR, merge, or issue closure was performed.

docs/compaction-refresh/evidence/RAW-SHA256SUMS.txt

@@ -0,0 +1,8 @@
+d19ed51612b52d8f5f4957321776e05157008d048b693217c03d71318dc4c763  docs/compaction-refresh/evidence/raw/P1-claude-hook-events.txt
+c2d7bc21200063a4a0e61c67ba91abaf958ee88aa686e86f3f71c2717732b413  docs/compaction-refresh/evidence/raw/P1-launch-ancestry.txt
+6efb12d908e9e20badcfda5b070aa1873409bd5a05f533f0b08bb1b4ef53d1a7  docs/compaction-refresh/evidence/raw/P2-P3-P5-P6-pi.txt
+a9df6cc9f5d45f60d7d914ad1f80b9601574b82831101b3a10eccf1b93787e94  docs/compaction-refresh/evidence/raw/P2-provider-timing.txt
+92e7aa7d69d53e58a151f9d56cfb583d90c206ecc0bc8a1b185e172c598fb177  docs/compaction-refresh/evidence/raw/P4-so-peercred.txt
+047d235c6b6553158e27378c4ace081b094e5746734f4b5db6a6dc8ef9e05ff2  docs/compaction-refresh/evidence/raw/P6-claude-additional-context.txt
+7df20b2878fc87aa4d1fc89121e494d8f4f7bf313b89e1e3147f16fdaa567cdd  docs/compaction-refresh/evidence/raw/P6-contract-gap.txt
+405bf3a06bf355d7f4f4d7b29d45a1ae70d93a690af5f7d0fc4819249e9f408f  docs/compaction-refresh/evidence/raw/STEP0-authority-hashes.txt

docs/compaction-refresh/evidence/raw/P1-claude-hook-events.txt

@@ -0,0 +1,28 @@
+$ python3 docs/compaction-refresh/probes/p1_run.py --runtime claude
+=== P1 CLAUDE REAL LAUNCH ===
+$ python3 docs/compaction-refresh/probes/p1_anchor_exec.py --socket <protected-socket> claude <runtime args>
+registered_anchor={"argc": 17, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 3933580, "ppid": 3933578, "starttime_ticks": 365788075}
+broker_minted_session_id=ebe9f9146ad1ba5b9fd757fe9517d24b
+hook_or_extension_record={"ancestry": [{"argc": 2, "argv0": "python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 3933983, "ppid": 3933982, "starttime_ticks": 365788568}, {"argc": 3, "argv0": "/bin/sh", "comm": "sh", "exe": "/usr/bin/dash", "pid": 3933982, "ppid": 3933751, "starttime_ticks": 365788568}, {"argc": 16, "argv0": "claude", "comm": "claude", "exe": "/home/hermes/.local/share/claude/versions/2.1.205", "pid": 3933751, "ppid": 3933580, "starttime_ticks": 365788474}, {"argc": 16, "argv0": "node", "comm": "node", "exe": "/usr/bin/node", "pid": 3933580, "ppid": 3933578, "starttime_ticks": 365788075}], "anchor": {"argc": 17, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 3933580, "ppid": 3933578, "starttime_ticks": 365788075}, "claimed_session_id": null, "decision": "ACCEPT", "event": "resolve-hook", "peercred": {"gid": 1001, "pid": 3933983, "uid": 1001}, "reason": "ancestry-reaches-registered-anchor", "resolved_session_id": "ebe9f9146ad1ba5b9fd757fe9517d24b", "starttimes_rechecked": true}
+sibling_attack_record={"ancestry": [{"argc": 6, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 3933581, "ppid": 3933578, "starttime_ticks": 365788080}, {"argc": 4, "argv0": "python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 3933578, "ppid": 3933576, "starttime_ticks": 365788059}, {"argc": 3, "argv0": "/bin/bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 3933576, "ppid": 3933575, "starttime_ticks": 365788058}, {"argc": 3, "argv0": "/bin/bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 3933575, "ppid": 3888118, "starttime_ticks": 365788058}, {"argc": 1, "argv0": "pi", "comm": "pi", "exe": "/usr/bin/node", "pid": 3888118, "ppid": 3887912, "starttime_ticks": 365707392}, {"argc": 6, "argv0": "node", "comm": "node", "exe": "/usr/bin/node", "pid": 3887912, "ppid": 3887869, "starttime_ticks": 365707050}, {"argc": 1, "argv0": "-bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 3887869, "ppid": 1244054, "starttime_ticks": 365706948}, {"argc": 10, "argv0": "tmux", "comm": "tmux: server", "exe": "/usr/bin/tmux", "pid": 1244054, "ppid": 745, "starttime_ticks": 114078803}, {"argc": 2, "argv0": "/lib/systemd/systemd", "comm": "systemd", "exe": "/usr/lib/systemd/systemd", "pid": 745, "ppid": 1, "starttime_ticks": 627}], "anchor": {"argc": 17, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 3933580, "ppid": 3933578, "starttime_ticks": 365788075}, "claimed_session_id": "ebe9f9146ad1ba5b9fd757fe9517d24b", "decision": "REJECT", "event": "claim-session", "peercred": {"gid": 1001, "pid": 3933581, "uid": 1001}, "reason": "victim-id-known-but-ancestry-mismatch", "resolved_session_id": null, "starttimes_rechecked": false}
+sibling_process_stdout={"attacker_pid": 3933581, "attacker_uid": 1001, "broker_decision": "REJECT", "broker_reason": "victim-id-known-but-ancestry-mismatch", "victim_session_id_known": true}
+sibling_process_exit=0
+ps_snapshot=<hook chain exited; broker /proc snapshot above is authoritative>
+launcher_stderr_excerpt:
+  {"argv": ["mosaic", "yolo", "claude", "<12 runtime args>"], "event": "anchor-exec", "note": "os.execvpe retains pid and /proc starttime", "pid": 3933580}
+runtime_stdout_excerpt:
+  
+  [mosaic] Claude Code settings audit:
+    ⚠ Missing PreToolUse hook: prevent-memory-write.sh
+    ⚠ Missing PostToolUse hook: qa-hook-stdin.sh
+    ⚠ Missing PostToolUse hook: typecheck-hook.sh
+    ⚠ Missing plugin: feature-dev
+    ⚠ Missing plugin: pr-review-toolkit
+    ⚠ Missing plugin: code-review
+runtime_hook_event_excerpt:
+    ⚠ Missing PreToolUse hook: prevent-memory-write.sh
+    ⚠ Missing PostToolUse hook: qa-hook-stdin.sh
+    ⚠ Missing PostToolUse hook: typecheck-hook.sh
+  {"type":"system","subtype":"hook_started","hook_id":"cadd5ded-a869-4b05-85fc-cfd1a4988217","hook_name":"SessionStart:startup","hook_event":"SessionStart","uuid":"b63d67bf-2247-4e1c-b16b-7ccffa73180b","session_id":"97e1224c-7c1c-42c7-9fb5-598d2cd3dfaf"}
+  {"type":"system","subtype":"hook_response","hook_id":"cadd5ded-a869-4b05-85fc-cfd1a4988217","hook_name":"SessionStart:startup","hook_event":"SessionStart","output":"{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"GATE0_P1_SUPPORTED_HOOK_ANCESTRY_ACCEPTED\"}}\n","stdout":"{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"GATE0_P1_SUPPORTED_HOOK_ANCESTRY_ACCEPTED\"}}\n","stderr":"","exit_code":0,"outcome":"success","uuid":"b2bb583d-d287-4b56-8061-09153a32adc2","session_id":"97e1224c-7c1c-42c7-9fb5-598d2cd3dfaf"}
+

docs/compaction-refresh/evidence/raw/P1-launch-ancestry.txt

@@ -0,0 +1,62 @@
+$ python3 docs/compaction-refresh/probes/p1_run.py --runtime both
+=== P1 PI REAL LAUNCH ===
+machine_assertions=PASS
+$ python3 docs/compaction-refresh/probes/p1_anchor_exec.py --socket <protected-socket> pi <runtime args>
+registered_anchor={"argc": 13, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4010843, "ppid": 4010840, "starttime_ticks": 365919858}
+broker_minted_session_id=5207bd0d8251b616fe4df4c68f438830
+hook_or_extension_record={"ancestry": [{"argc": 1, "argv0": "pi", "comm": "pi", "exe": "/usr/bin/node", "pid": 4011046, "ppid": 4010843, "starttime_ticks": 365920219}, {"argc": 12, "argv0": "node", "comm": "node", "exe": "/usr/bin/node", "pid": 4010843, "ppid": 4010840, "starttime_ticks": 365919858}], "anchor": {"argc": 13, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4010843, "ppid": 4010840, "starttime_ticks": 365919858}, "claimed_session_id": null, "decision": "ACCEPT", "event": "resolve-hook", "peercred": {"gid": 1001, "pid": 4011046, "uid": 1001}, "reason": "ancestry-reaches-registered-anchor", "resolved_session_id": "5207bd0d8251b616fe4df4c68f438830", "starttimes_rechecked": true}
+sibling_attack_record={"ancestry": [{"argc": 6, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4010844, "ppid": 4010840, "starttime_ticks": 365919864}, {"argc": 4, "argv0": "python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4010840, "ppid": 4010838, "starttime_ticks": 365919843}, {"argc": 3, "argv0": "/bin/bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 4010838, "ppid": 4010837, "starttime_ticks": 365919843}, {"argc": 3, "argv0": "/bin/bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 4010837, "ppid": 3888118, "starttime_ticks": 365919842}, {"argc": 1, "argv0": "pi", "comm": "pi", "exe": "/usr/bin/node", "pid": 3888118, "ppid": 3887912, "starttime_ticks": 365707392}, {"argc": 6, "argv0": "node", "comm": "node", "exe": "/usr/bin/node", "pid": 3887912, "ppid": 3887869, "starttime_ticks": 365707050}, {"argc": 1, "argv0": "-bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 3887869, "ppid": 1244054, "starttime_ticks": 365706948}, {"argc": 10, "argv0": "tmux", "comm": "tmux: server", "exe": "/usr/bin/tmux", "pid": 1244054, "ppid": 745, "starttime_ticks": 114078803}, {"argc": 2, "argv0": "/lib/systemd/systemd", "comm": "systemd", "exe": "/usr/lib/systemd/systemd", "pid": 745, "ppid": 1, "starttime_ticks": 627}], "anchor": {"argc": 13, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4010843, "ppid": 4010840, "starttime_ticks": 365919858}, "claimed_session_id": "5207bd0d8251b616fe4df4c68f438830", "decision": "REJECT", "event": "claim-session", "peercred": {"gid": 1001, "pid": 4010844, "uid": 1001}, "reason": "victim-id-known-but-ancestry-mismatch", "resolved_session_id": null, "starttimes_rechecked": false}
+sibling_process_stdout={"attacker_pid": 4010844, "attacker_uid": 1001, "broker_decision": "REJECT", "broker_reason": "victim-id-known-but-ancestry-mismatch", "victim_session_id_known": true}
+sibling_process_exit=0
+$ ps -o pid=,ppid=,lstart=,uid=,gid=,comm= -p 4011046,4010843
+4010843 4010840 Fri Jul 17 19:35:18 2026  1001  1001 node
+4011046 4010843 Fri Jul 17 19:35:22 2026  1001  1001 pi
+launcher_stderr_excerpt:
+  {"argv": ["mosaic", "yolo", "pi", "<8 runtime args>"], "event": "anchor-exec", "note": "os.execvpe retains pid and /proc starttime", "pid": 4010843}
+runtime_stdout_excerpt:
+  [mosaic] Launching Pi in YOLO mode...
+  {"type":"extension_ui_request","id":"4cf086c7-299e-4734-9264-6ad2964f3664","method":"notify","message":"Mosaic framework loaded","notifyType":"info"}
+  {"id":"state","type":"response","command":"get_state","success":true,"data":{"model":{"id":"gpt-5.6-sol","name":"GPT-5.6 Sol","api":"openai-codex-responses","provider":"openai-codex","baseUrl":"https://chatgpt.com/backend-api","compat":{"supportsToolSearch":true},"reasoning":true,"thinkingLevelMap":{"xhigh":"xhigh","max":"max","minimal":"low"},"input":["text","image"],"cost":{"input":5,"output":30,"cacheRead":0.5,"cacheWrite":6.25,"tiers":[{"inputTokensAbove":272000,"input":10,"output":45,"cache
+runtime_hook_event_excerpt:
+
+=== P1 CLAUDE REAL LAUNCH ===
+machine_assertions=PASS
+$ python3 docs/compaction-refresh/probes/p1_anchor_exec.py --socket <protected-socket> claude <runtime args>
+registered_anchor={"argc": 17, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4011129, "ppid": 4010840, "starttime_ticks": 365920380}
+broker_minted_session_id=f382fa5f4b2142ef79bb76204521ff2a
+hook_or_extension_record={"ancestry": [{"argc": 2, "argv0": "python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4011380, "ppid": 4011379, "starttime_ticks": 365920845}, {"argc": 3, "argv0": "/bin/sh", "comm": "sh", "exe": "/usr/bin/dash", "pid": 4011379, "ppid": 4011285, "starttime_ticks": 365920845}, {"argc": 16, "argv0": "claude", "comm": "claude", "exe": "/home/hermes/.local/share/claude/versions/2.1.205", "pid": 4011285, "ppid": 4011129, "starttime_ticks": 365920748}, {"argc": 16, "argv0": "node", "comm": "node", "exe": "/usr/bin/node", "pid": 4011129, "ppid": 4010840, "starttime_ticks": 365920380}], "anchor": {"argc": 17, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4011129, "ppid": 4010840, "starttime_ticks": 365920380}, "claimed_session_id": null, "decision": "ACCEPT", "event": "resolve-hook", "peercred": {"gid": 1001, "pid": 4011380, "uid": 1001}, "reason": "ancestry-reaches-registered-anchor", "resolved_session_id": "f382fa5f4b2142ef79bb76204521ff2a", "starttimes_rechecked": true}
+sibling_attack_record={"ancestry": [{"argc": 6, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4011130, "ppid": 4010840, "starttime_ticks": 365920385}, {"argc": 4, "argv0": "python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4010840, "ppid": 4010838, "starttime_ticks": 365919843}, {"argc": 3, "argv0": "/bin/bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 4010838, "ppid": 4010837, "starttime_ticks": 365919843}, {"argc": 3, "argv0": "/bin/bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 4010837, "ppid": 3888118, "starttime_ticks": 365919842}, {"argc": 1, "argv0": "pi", "comm": "pi", "exe": "/usr/bin/node", "pid": 3888118, "ppid": 3887912, "starttime_ticks": 365707392}, {"argc": 6, "argv0": "node", "comm": "node", "exe": "/usr/bin/node", "pid": 3887912, "ppid": 3887869, "starttime_ticks": 365707050}, {"argc": 1, "argv0": "-bash", "comm": "bash", "exe": "/usr/bin/bash", "pid": 3887869, "ppid": 1244054, "starttime_ticks": 365706948}, {"argc": 10, "argv0": "tmux", "comm": "tmux: server", "exe": "/usr/bin/tmux", "pid": 1244054, "ppid": 745, "starttime_ticks": 114078803}, {"argc": 2, "argv0": "/lib/systemd/systemd", "comm": "systemd", "exe": "/usr/lib/systemd/systemd", "pid": 745, "ppid": 1, "starttime_ticks": 627}], "anchor": {"argc": 17, "argv0": "/usr/bin/python3", "comm": "python3", "exe": "/usr/bin/python3.11", "pid": 4011129, "ppid": 4010840, "starttime_ticks": 365920380}, "claimed_session_id": "f382fa5f4b2142ef79bb76204521ff2a", "decision": "REJECT", "event": "claim-session", "peercred": {"gid": 1001, "pid": 4011130, "uid": 1001}, "reason": "victim-id-known-but-ancestry-mismatch", "resolved_session_id": null, "starttimes_rechecked": false}
+sibling_process_stdout={"attacker_pid": 4011130, "attacker_uid": 1001, "broker_decision": "REJECT", "broker_reason": "victim-id-known-but-ancestry-mismatch", "victim_session_id_known": true}
+sibling_process_exit=0
+ps_snapshot=<hook chain exited; broker /proc snapshot above is authoritative>
+launcher_stderr_excerpt:
+  {"argv": ["mosaic", "yolo", "claude", "<12 runtime args>"], "event": "anchor-exec", "note": "os.execvpe retains pid and /proc starttime", "pid": 4011129}
+runtime_stdout_excerpt:
+  
+  [mosaic] Claude Code settings audit:
+    ⚠ Missing PreToolUse hook: prevent-memory-write.sh
+    ⚠ Missing PostToolUse hook: qa-hook-stdin.sh
+    ⚠ Missing PostToolUse hook: typecheck-hook.sh
+    ⚠ Missing plugin: feature-dev
+    ⚠ Missing plugin: pr-review-toolkit
+    ⚠ Missing plugin: code-review
+runtime_hook_event_excerpt:
+    ⚠ Missing PreToolUse hook: prevent-memory-write.sh
+    ⚠ Missing PostToolUse hook: qa-hook-stdin.sh
+    ⚠ Missing PostToolUse hook: typecheck-hook.sh
+  {"type":"system","subtype":"hook_started","hook_id":"2a5f7dab-a064-4610-a6b1-4ad151ddcdd9","hook_name":"SessionStart:startup","hook_event":"SessionStart","uuid":"c6e0690c-f0c9-4d60-a8fb-5f0c25ea3208","session_id":"167d104d-907a-4120-9b07-bdf4762818a9"}
+  {"type":"system","subtype":"hook_response","hook_id":"2a5f7dab-a064-4610-a6b1-4ad151ddcdd9","hook_name":"SessionStart:startup","hook_event":"SessionStart","output":"{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"GATE0_P1_SUPPORTED_HOOK_ANCESTRY_ACCEPTED\"}}\n","stdout":"{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"GATE0_P1_SUPPORTED_HOOK_ANCESTRY_ACCEPTED\"}}\n","stderr":"","exit_code":0,"outcome":"success","uuid":"167b2a5b-a45a-4e70-a72b-1f4a609bb979","session_id":"167d104d-907a-4120-9b07-bdf4762818a9"}
+
+
+$ readlink -f "$(command -v mosaic)"
+/home/hermes/.npm-global/lib/node_modules/@mosaicstack/mosaic/dist/cli.js
+
+$ rg -n "spawnSync|execRuntime" ~/.npm-global/lib/node_modules/@mosaicstack/mosaic/dist/commands/launch.js | tail -8
+63:            spawnSync(initBin, [], { stdio: 'inherit' });
+131:    const result = spawnSync(checker, ['--check', '--runtime', runtime], { stdio: 'ignore' });
+624:            execRuntime('claude', cliArgs);
+637:            execRuntime('codex', cliArgs);
+643:            execRuntime('opencode', args);
+658:            execRuntime('pi', cliArgs);
+665:function execRuntime(cmd, args) {
+668:        const result = spawnSync(cmd, args, {

docs/compaction-refresh/evidence/raw/P2-P3-P5-P6-pi.txt

@@ -0,0 +1,52 @@
+$ python3 docs/compaction-refresh/probes/pi_gate0_run.py
+machine_assertions=PASS
+runtime_versions:
+  0.80.7
+  0.0.48
+
+P2_EVENT_ORDER_AND_NONCE_MAP:
+{"assistantContentObserved": true, "assistantTextSha256": "a36f1eb364f062cad2f9f7d7e2b62ef7715d2aef79caafcfccd3a227cecf3e61", "event": "message_end", "exactContextBlockCopied": false, "inFlightDepthAfter": 0, "nonceMappings": [{"requestNonce": "e5a82358-a6c9-490b-a0de-2e1f1d9b8d79", "toolCallId": "call_bgGEFnBJOmwJPEfmzMo1eHOy|fc_0fb3d12b5404a73c016a5ac9d6f9a4819b9ddf70296c0cf57c"}], "pid": 4004545, "requestNonce": "e5a82358-a6c9-490b-a0de-2e1f1d9b8d79", "role": "assistant", "seq": 5, "starttime_ticks": 365907677, "toolCallIds": ["call_bgGEFnBJOmwJPEfmzMo1eHOy|fc_0fb3d12b5404a73c016a5ac9d6f9a4819b9ddf70296c0cf57c"]}
+{"allowed": true, "event": "tool_call", "mapping": {"nonce": "e5a82358-a6c9-490b-a0de-2e1f1d9b8d79", "sourceReason": "all-fragments-valid", "verified": true}, "pid": 4004545, "reason": "exact-tool-call-id-mapped-to-verified-request-nonce", "seq": 6, "starttime_ticks": 365907677, "toolCallId": "call_bgGEFnBJOmwJPEfmzMo1eHOy|fc_0fb3d12b5404a73c016a5ac9d6f9a4819b9ddf70296c0cf57c", "toolName": "gate0_nonce_probe"}
+{"broker": {"event": "probe_lease_promoted", "generation": 1, "new_lease_state": "VERIFIED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "starttime_ticks": 365907677}, "event": "tool_execute", "label": "p2", "pid": 4004545, "seq": 7, "starttime_ticks": 365907677, "toolCallId": "call_bgGEFnBJOmwJPEfmzMo1eHOy|fc_0fb3d12b5404a73c016a5ac9d6f9a4819b9ddf70296c0cf57c"}
+{"assistantContentObserved": true, "assistantTextSha256": "99c3dce194b16405dfb555f126ee5ccc014fdc184d0882aee1a903cbc700a0dd", "event": "message_end", "exactContextBlockCopied": true, "inFlightDepthAfter": 0, "nonceMappings": [], "pid": 4004545, "requestNonce": "cca4b1e3-296a-4e4c-9805-a395c270c01f", "role": "assistant", "seq": 11, "starttime_ticks": 365907677, "toolCallIds": []}
+
+P2_LAST_OR_CLOSED:
+{"broker": {"event": "runtime_generation_bump", "new_generation": 1, "new_lease_state": "UNVERIFIED", "old_generation": 0, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "NONE", "prior_lease_revoked": true, "reason": "startup", "starttime_ticks": 365907677}, "event": "session_start", "extensions": ["/home/hermes/.config/mosaic/runtime/pi/mosaic-extension.ts", "/home/hermes/agent-work/stack-cr-wi0-gate0/docs/compaction-refresh/probes/pi_gate0_extension.ts"], "gateState": "UNVERIFIED_READY", "lastPosition": true, "pid": 4004545, "reason": "startup", "self": "/home/hermes/agent-work/stack-cr-wi0-gate0/docs/compaction-refresh/probes/pi_gate0_extension.ts", "seq": 1, "starttime_ticks": 365907677}
+{"broker": {"skipped": true}, "event": "session_start", "extensions": ["/home/hermes/.config/mosaic/runtime/pi/mosaic-extension.ts", "/home/hermes/agent-work/stack-cr-wi0-gate0/docs/compaction-refresh/probes/pi_gate0_extension.ts", "/home/hermes/agent-work/stack-cr-wi0-gate0/docs/compaction-refresh/probes/pi_later_extension.ts"], "gateState": "CLOSED_NOT_LAST", "lastPosition": false, "pid": 4005692, "reason": "startup", "self": "/home/hermes/agent-work/stack-cr-wi0-gate0/docs/compaction-refresh/probes/pi_gate0_extension.ts", "seq": 1, "starttime_ticks": 365910545}
+
+P3_GENERATION_BROKER:
+{"event": "runtime_generation_bump", "new_generation": 1, "new_lease_state": "UNVERIFIED", "old_generation": 0, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "NONE", "prior_lease_revoked": true, "reason": "startup", "starttime_ticks": 365907677}
+{"event": "probe_lease_promoted", "generation": 1, "new_lease_state": "VERIFIED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 2, "new_lease_state": "REVOKED", "old_generation": 1, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "shutdown", "prior_lease": "VERIFIED", "prior_lease_revoked": true, "reason": "reload", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 3, "new_lease_state": "UNVERIFIED", "old_generation": 2, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "REVOKED", "prior_lease_revoked": true, "reason": "reload", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 4, "new_lease_state": "REVOKED", "old_generation": 3, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "shutdown", "prior_lease": "UNVERIFIED", "prior_lease_revoked": true, "reason": "fork", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 5, "new_lease_state": "UNVERIFIED", "old_generation": 4, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "REVOKED", "prior_lease_revoked": true, "reason": "fork", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 6, "new_lease_state": "UNVERIFIED", "old_generation": 5, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "UNVERIFIED", "prior_lease_revoked": true, "reason": "fork", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 7, "new_lease_state": "REVOKED", "old_generation": 6, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "shutdown", "prior_lease": "UNVERIFIED", "prior_lease_revoked": true, "reason": "new", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 8, "new_lease_state": "UNVERIFIED", "old_generation": 7, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "REVOKED", "prior_lease_revoked": true, "reason": "new", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 9, "new_lease_state": "UNVERIFIED", "old_generation": 8, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "UNVERIFIED", "prior_lease_revoked": true, "reason": "new", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 10, "new_lease_state": "REVOKED", "old_generation": 9, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "shutdown", "prior_lease": "UNVERIFIED", "prior_lease_revoked": true, "reason": "resume", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 11, "new_lease_state": "UNVERIFIED", "old_generation": 10, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "REVOKED", "prior_lease_revoked": true, "reason": "resume", "starttime_ticks": 365907677}
+{"event": "runtime_generation_bump", "new_generation": 12, "new_lease_state": "UNVERIFIED", "old_generation": 11, "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "phase": "start", "prior_lease": "UNVERIFIED", "prior_lease_revoked": true, "reason": "resume", "starttime_ticks": 365907677}
+
+P5_SOURCE_INVALIDATION:
+{"blockLength": 108, "blockSha256": "99c3dce194b16405dfb555f126ee5ccc014fdc184d0882aee1a903cbc700a0dd", "event": "context_return", "injectionDecision": "REFUSED", "inputCount": 5, "lastPosition": true, "outputCount": 5, "pid": 4004545, "prefixHashAfter": "4f339e3e45989486374b75d8a40abad22a3f3091f1099e3b4112f3afd1c60eb0", "prefixHashBefore": "4f339e3e45989486374b75d8a40abad22a3f3091f1099e3b4112f3afd1c60eb0", "prefixPreservedByReturn": true, "promotion": false, "requestNonce": "24ef5352-bcc6-4418-b65f-c2763453cc46", "seq": 12, "sourceBroker": {"event": "source_invalidation_revoke", "generation": 12, "new_lease_state": "REVOKED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "prior_lease": "UNVERIFIED", "promotion": false, "source_reason": "missing", "starttime_ticks": 365907677}, "sourceValidation": {"fragment": "/tmp/gate0-pi-g_3gsk34/absent-fragment.md", "ok": false, "reason": "missing"}, "starttime_ticks": 365907677}
+{"allowed": false, "event": "tool_call", "mapping": {"nonce": "24ef5352-bcc6-4418-b65f-c2763453cc46", "sourceReason": "missing", "verified": false}, "pid": 4004545, "reason": "unverified-source:missing", "seq": 15, "starttime_ticks": 365907677, "toolCallId": "call_XBwBkiv5tZx2ayuDxHKD5vSB|fc_0fb3d12b5404a73c016a5ac9dc341c819bb6ed3e00ca2cf1a5", "toolName": "gate0_nonce_probe"}
+{"blockLength": 108, "blockSha256": "99c3dce194b16405dfb555f126ee5ccc014fdc184d0882aee1a903cbc700a0dd", "event": "context_return", "injectionDecision": "REFUSED", "inputCount": 9, "lastPosition": true, "outputCount": 9, "pid": 4004545, "prefixHashAfter": "1a39911018caefe8f5b5acb652cece9f92d937e7384109f5c1559266349480b7", "prefixHashBefore": "1a39911018caefe8f5b5acb652cece9f92d937e7384109f5c1559266349480b7", "prefixPreservedByReturn": true, "promotion": false, "requestNonce": "319646e8-59e2-4021-9b27-de1376b13c32", "seq": 22, "sourceBroker": {"event": "source_invalidation_revoke", "generation": 12, "new_lease_state": "REVOKED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "prior_lease": "REVOKED", "promotion": false, "source_reason": "oversize", "starttime_ticks": 365907677}, "sourceValidation": {"fragment": "/tmp/gate0-pi-g_3gsk34/oversize.md", "ok": false, "reason": "oversize"}, "starttime_ticks": 365907677}
+{"allowed": false, "event": "tool_call", "mapping": {"nonce": "319646e8-59e2-4021-9b27-de1376b13c32", "sourceReason": "oversize", "verified": false}, "pid": 4004545, "reason": "unverified-source:oversize", "seq": 25, "starttime_ticks": 365907677, "toolCallId": "call_P9d0wR5TSXSqZHydVHclh6Cg|fc_0fb3d12b5404a73c016a5ac9e02a28819bb39df373b7c9e23b", "toolName": "gate0_nonce_probe"}
+{"blockLength": 108, "blockSha256": "99c3dce194b16405dfb555f126ee5ccc014fdc184d0882aee1a903cbc700a0dd", "event": "context_return", "injectionDecision": "REFUSED", "inputCount": 13, "lastPosition": true, "outputCount": 13, "pid": 4004545, "prefixHashAfter": "224c8777dd0cd5fcf1ae02f0fc46198548b48647dbfd044ed131533d72086f16", "prefixHashBefore": "224c8777dd0cd5fcf1ae02f0fc46198548b48647dbfd044ed131533d72086f16", "prefixPreservedByReturn": true, "promotion": false, "requestNonce": "23f3125f-6e62-4f3c-aa60-3eaed705ddc1", "seq": 32, "sourceBroker": {"event": "source_invalidation_revoke", "generation": 12, "new_lease_state": "REVOKED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "prior_lease": "REVOKED", "promotion": false, "source_reason": "hash-mismatch", "starttime_ticks": 365907677}, "sourceValidation": {"fragment": "/tmp/gate0-pi-g_3gsk34/mismatch.md", "ok": false, "reason": "hash-mismatch"}, "starttime_ticks": 365907677}
+{"allowed": false, "event": "tool_call", "mapping": {"nonce": "23f3125f-6e62-4f3c-aa60-3eaed705ddc1", "sourceReason": "hash-mismatch", "verified": false}, "pid": 4004545, "reason": "unverified-source:hash-mismatch", "seq": 35, "starttime_ticks": 365907677, "toolCallId": "call_QUMvqBRnzv6HNqEd37jU5NUw|fc_0fb3d12b5404a73c016a5ac9e37510819b8506879faf287aa3", "toolName": "gate0_nonce_probe"}
+{"event": "source_invalidation_revoke", "generation": 12, "new_lease_state": "REVOKED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "prior_lease": "UNVERIFIED", "promotion": false, "source_reason": "missing", "starttime_ticks": 365907677}
+{"event": "source_invalidation_revoke", "generation": 12, "new_lease_state": "REVOKED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "prior_lease": "REVOKED", "promotion": false, "source_reason": "oversize", "starttime_ticks": 365907677}
+{"event": "source_invalidation_revoke", "generation": 12, "new_lease_state": "REVOKED", "peercred": {"gid": 1001, "pid": 4004545, "uid": 1001}, "prior_lease": "REVOKED", "promotion": false, "source_reason": "hash-mismatch", "starttime_ticks": 365907677}
+
+P6_PI_CONTEXT_ATOMIC_OBSERVATION:
+{"blockLength": 108, "blockSha256": "99c3dce194b16405dfb555f126ee5ccc014fdc184d0882aee1a903cbc700a0dd", "event": "context_return", "injectionDecision": "ONE_ATOMIC_AGENT_MESSAGE", "inputCount": 1, "lastPosition": true, "outputCount": 2, "pid": 4004545, "prefixHashAfter": "095a5415879b0d4006d1485dba3398fee6bf39850711ba0dc2e9cfa312e865dc", "prefixHashBefore": "095a5415879b0d4006d1485dba3398fee6bf39850711ba0dc2e9cfa312e865dc", "prefixPreservedByReturn": true, "promotion": false, "requestNonce": "e5a82358-a6c9-490b-a0de-2e1f1d9b8d79", "seq": 3, "sourceBroker": {"action": "none", "reason": "source-valid"}, "sourceValidation": {"ok": true, "reason": "all-fragments-valid"}, "starttime_ticks": 365907677}
+{"event": "before_provider_request", "finalPayloadValid": true, "inFlightDepth": 1, "markerOccurrences": 1, "markerPaths": ["$.input[1].content[0].text"], "pid": 4004545, "requestNonce": "e5a82358-a6c9-490b-a0de-2e1f1d9b8d79", "seq": 4, "starttime_ticks": 365907677}
+{"blockLength": 108, "blockSha256": "99c3dce194b16405dfb555f126ee5ccc014fdc184d0882aee1a903cbc700a0dd", "event": "context_return", "injectionDecision": "ONE_ATOMIC_AGENT_MESSAGE", "inputCount": 3, "lastPosition": true, "outputCount": 4, "pid": 4004545, "prefixHashAfter": "7c40cce3664af7581b21ea007a4a44764237fce1e4f16b031e96d60df2229855", "prefixHashBefore": "7c40cce3664af7581b21ea007a4a44764237fce1e4f16b031e96d60df2229855", "prefixPreservedByReturn": true, "promotion": false, "requestNonce": "cca4b1e3-296a-4e4c-9805-a395c270c01f", "seq": 9, "sourceBroker": {"action": "none", "reason": "source-valid"}, "sourceValidation": {"ok": true, "reason": "all-fragments-valid"}, "starttime_ticks": 365907677}
+{"event": "before_provider_request", "finalPayloadValid": true, "inFlightDepth": 1, "markerOccurrences": 1, "markerPaths": ["$.input[5].content[0].text"], "pid": 4004545, "requestNonce": "cca4b1e3-296a-4e4c-9805-a395c270c01f", "seq": 10, "starttime_ticks": 365907677}
+{"assistantContentObserved": true, "assistantTextSha256": "99c3dce194b16405dfb555f126ee5ccc014fdc184d0882aee1a903cbc700a0dd", "event": "message_end", "exactContextBlockCopied": true, "inFlightDepthAfter": 0, "nonceMappings": [], "pid": 4004545, "requestNonce": "cca4b1e3-296a-4e4c-9805-a395c270c01f", "role": "assistant", "seq": 11, "starttime_ticks": 365907677, "toolCallIds": []}
+
+RPC_EVENT_COUNTS:
+{"agent_end": 4, "agent_settled": 4, "agent_start": 4, "extension_ui_request": 8, "message_end": 16, "message_start": 16, "message_update": 105, "response": 9, "tool_execution_end": 4, "tool_execution_start": 4, "turn_end": 8, "turn_start": 8}
+stderr_nonempty=False

docs/compaction-refresh/evidence/raw/P2-provider-timing.txt

@@ -0,0 +1,9 @@
+$ python3 docs/compaction-refresh/probes/p2_provider_timing_run.py
+local_http_endpoint=http://127.0.0.1:42823/v1/chat/completions
+{"event": "before_provider_request", "finalPayloadValid": true, "inFlightDepth": 1, "markerOccurrences": 1, "markerPaths": ["$.messages[2].content[0].text"], "pid": 4008778, "requestNonce": "056b82c4-36eb-420b-94cf-b2c73813ef79", "seq": 4, "starttime_ticks": 365916346}
+{"assistantContentAvailableAtThisHook": false, "event": "after_provider_response", "pid": 4008778, "requestNonce": "056b82c4-36eb-420b-94cf-b2c73813ef79", "seq": 5, "starttime_ticks": 365916346, "status": 200, "timing": "headers/status before stream consumption"}
+{"assistantContentObserved": true, "assistantTextSha256": "fb4ebaab26d63661040dc15925a99e22dc07ee2b33df5c6b2ca93a5b34f08b1d", "event": "message_end", "exactContextBlockCopied": false, "inFlightDepthAfter": 0, "nonceMappings": [], "pid": 4008778, "requestNonce": "056b82c4-36eb-420b-94cf-b2c73813ef79", "role": "assistant", "seq": 6, "starttime_ticks": 365916346, "toolCallIds": []}
+machine_assertions=PASS
+after_provider_response_seq=5
+message_end_seq=6
+headers_hook_precedes_completed_message=True

docs/compaction-refresh/evidence/raw/P4-so-peercred.txt

@@ -0,0 +1,23 @@
+$ python3 docs/compaction-refresh/probes/p4_peercred_probe.py
+machine_assertions=PASS
+server_pid=4013762 server_uid=1001 server_gid=1001
+socket_path=/tmp/gate0-p4-nl1_8ap2/broker.sock
+directory_mode=0700 socket_mode=0600
+SO_PEERCRED pid=4013768 uid=1001 gid=1001
+client_claim={"exe": "/usr/bin/python3.11", "pid": 4013768, "ppid": 4013762, "starttime_ticks": 365927069, "uid": 1001}
+proc_observed={"exe": "/usr/bin/python3.11", "pid": 4013768, "ppid": 4013762, "starttime_ticks": 365927069, "uid": 1001}
+pid_match=True
+uid_match=True
+starttime_match=True
+client_exit_status=0
+same_principal_socket=true
+posture=0700 parent + 0600 socket excludes other UIDs, but does not prevent the same UID from unlinking/rebinding; distinct-principal system service remains required for a claim stronger than T-C against same-UID counterfeit replacement
+
+$ id
+uid=1001(hermes) gid=1001(hermes) groups=1001(hermes),40(src),100(users),996(docker)
+
+$ uname -srmo
+Linux 6.1.0-48-amd64 x86_64 GNU/Linux
+
+$ getconf CLK_TCK
+100

docs/compaction-refresh/evidence/raw/P6-claude-additional-context.txt

@@ -0,0 +1,21 @@
+$ python3 docs/compaction-refresh/probes/p6_claude_run.py
+machine_assertions=PASS
+command=mosaic yolo claude --settings <isolated> --model haiku --print --output-format stream-json --verbose --include-hook-events <prompt>
+claude_version=2.1.205 (Claude Code)
+mosaic_version=0.0.48
+exit_code=0
+hook_process_log={"block_length": 116, "block_sha256": "ef6377d63552af075f4f4adec00165988418c5f46a992f4dce8e678b56fd34ac", "emission": "one hookSpecificOutput.additionalContext string field", "hook_event_name": "SessionStart", "pid": 4015703, "ppid": 4015701, "starttime_ticks": 365930489}
+hook_stream_event={"hook_event": "SessionStart", "hook_id": "557d613e-574f-4523-8bfb-8c6e51946035", "hook_name": "SessionStart:startup", "session_id": "f821d0db-1177-4237-8ff5-83b2a46996a6", "subtype": "hook_started", "type": "system", "uuid": "59449134-e2d4-43a9-9d34-b59e74622c08"}
+hook_stream_event={"exit_code": 0, "hook_event": "SessionStart", "hook_id": "557d613e-574f-4523-8bfb-8c6e51946035", "hook_name": "SessionStart:startup", "outcome": "success", "output": "{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"GATE0_CLAUDE_ATOMIC_BEGIN\\nsegment-01=alpha-2d11\\nsegment-02=middle-8e22\\nsegment-03=omega-4f33\\nGATE0_CLAUDE_ATOMIC_END\"}}\n", "session_id": "f821d0db-1177-4237-8ff5-83b2a46996a6", "stderr": "", "stdout": "{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"GATE0_CLAUDE_ATOMIC_BEGIN\\nsegment-01=alpha-2d11\\nsegment-02=middle-8e22\\nsegment-03=omega-4f33\\nGATE0_CLAUDE_ATOMIC_END\"}}\n", "subtype": "hook_response", "type": "system", "uuid": "e05842c1-813a-41dd-93c9-768eb834f260"}
+block_length=116
+block_sha256=ef6377d63552af075f4f4adec00165988418c5f46a992f4dce8e678b56fd34ac
+stream_fields_containing_full_block=3
+stream_fields_exactly_equal_block=2
+assistant_copy_length=449
+assistant_copy_sha256=a65febbb3ad8fa4952894d94406a83a520ef712c0ecb9ab43be3212094b21ba1
+assistant_copy_exact=False
+assistant_copy="The user is asking me to return the exact GATE0_CLAUDE_ATOMIC block that was injected by SessionStart. This block was provided in the system-reminder at the beginning of the conversation:\n\n```\nGATE0_CLAUDE_ATOMIC_BEGIN\nsegment-01=alpha-2d11\nsegment-02=middle-8e22\nsegment-03=omega-4f33\nGATE0_CLAUDE_ATOMIC_END\n```\n\nThe user wants me to return ONLY this exact block, with no code fence or commentary. So I should just output it exactly as it appears."
+assistant_copy_length=116
+assistant_copy_sha256=ef6377d63552af075f4f4adec00165988418c5f46a992f4dce8e678b56fd34ac
+assistant_copy_exact=True
+assistant_copy="GATE0_CLAUDE_ATOMIC_BEGIN\nsegment-01=alpha-2d11\nsegment-02=middle-8e22\nsegment-03=omega-4f33\nGATE0_CLAUDE_ATOMIC_END"

docs/compaction-refresh/evidence/raw/P6-contract-gap.txt

@@ -0,0 +1,47 @@
+$ rg -n -i "atomic|prefix-preserv" <Pi extensions docs> <Claude hook docs>
+NO MATCH: neither installed runtime document states an atomic/prefix-preserving transport guarantee.
+
+$ rg -n -C 3 "#### context|event.messages - deep copy|return \{ messages" <Pi extensions docs>
+638-});
+639-```
+640-
+641:#### context
+642-
+643-Fired before each LLM call. Modify messages non-destructively. See [Session Format](session-format.md) for message types.
+644-
+645-```typescript
+646-pi.on("context", async (event, ctx) => {
+647:  // event.messages - deep copy, safe to modify
+648-  const filtered = event.messages.filter(m => !shouldPrune(m));
+649:  return { messages: filtered };
+650-});
+651-```
+652-
+
+$ rg -n -C 3 "additionalContext|add to the default system prompt" <Claude installed docs>
+/home/hermes/.config/mosaic/runtime/claude/RUNTIME.md-58-  tiered models via the Task `model` param).
+/home/hermes/.config/mosaic/runtime/claude/RUNTIME.md-59-
+/home/hermes/.config/mosaic/runtime/claude/RUNTIME.md-60-Note: PostToolUse hook plain stdout on exit 0 goes to the debug log, not model context — only
+/home/hermes/.config/mosaic/runtime/claude/RUNTIME.md:61:`hookSpecificOutput.additionalContext` (or exit-2 stderr) enters context.
+--
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/README.md-59-expressed as
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/README.md-60-[subagents](https://docs.claude.com/en/docs/claude-code/sub-agents), not as
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/README.md-61-SessionStart hooks. Subagents change the system prompt while SessionStart hooks
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/README.md:62:add to the default system prompt.
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/README.md-63-
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/README.md-64-## Managing changes
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/README.md-65-
+--
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-1-#!/usr/bin/env bash
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-2-
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh:3:# Output the explanatory mode instructions as additionalContext
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-4-# This mimics the deprecated Explanatory output style
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-5-
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-6-cat << 'EOF'
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-7-{
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-8-  "hookSpecificOutput": {
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-9-    "hookEventName": "SessionStart",
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh:10:    "additionalContext": "You are in 'explanatory' output style mode, where you should provide educational insights about the codebase as you help with the user's task.\n\nYou should be clear and educational, providing helpful explanations while remaining focused on the task. Balance educational content with task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.\n\n## Insights\nIn order to encourage learning, before and after writing code, always provide brief educational explanations about implementation choices using (with backticks):\n\"`★ Insight ─────────────────────────────────────`\n[2-3 key educational points]\n`─────────────────────────────────────────────────`\"\n\nThese insights should be included in the conversation, not in the codebase. You should generally focus on interesting insights that are specific to the codebase or the code you just wrote, rather than general programming concepts. Do not wait until the end to provide insights. Provide them as you write code."
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-11-  }
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-12-}
+/home/hermes/.claude/plugins/marketplaces/claude-plugins-official/plugins/explanatory-output-style/hooks-handlers/session-start.sh-13-EOF

docs/compaction-refresh/evidence/raw/STEP0-authority-hashes.txt

@@ -0,0 +1,9 @@
+$ sha256sum ~/agent-work/reviews/compaction-refresh-BUILD-BRIEF.md ~/agent-work/reviews/compaction-refresh-SPEC-v5.md ~/agent-work/reviews/compaction-refresh-SPEC-RATIFICATION.md
+89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b  /home/hermes/agent-work/reviews/compaction-refresh-BUILD-BRIEF.md
+a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433  /home/hermes/agent-work/reviews/compaction-refresh-SPEC-v5.md
+bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67  /home/hermes/agent-work/reviews/compaction-refresh-SPEC-RATIFICATION.md
+
+Expected:
+89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b  BUILD-BRIEF
+a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433  SPEC-v5
+bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67  RATIFICATION

docs/compaction-refresh/probes/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

docs/compaction-refresh/probes/p1_anchor_exec.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Register this PID as anchor, then exec the real `mosaic yolo` launcher."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import socket
+import sys
+
+
+def request(socket_path: str, payload: dict[str, object]) -> dict[str, object]:
+    conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    conn.connect(socket_path)
+    conn.sendall((json.dumps(payload) + "\n").encode())
+    response = json.loads(conn.makefile("r", encoding="utf-8").readline())
+    conn.close()
+    return response
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--socket", required=True)
+    parser.add_argument("runtime", choices=["pi", "claude"])
+    parser.add_argument("args", nargs=argparse.REMAINDER)
+    ns = parser.parse_args()
+
+    response = request(ns.socket, {"action": "register-anchor", "runtime": ns.runtime})
+    if response.get("decision") != "ACCEPT":
+        raise SystemExit("anchor registration refused")
+    os.environ["GATE0_SESSION_ID"] = str(response["session_id"])
+    argv = ["mosaic", "yolo", ns.runtime, *ns.args]
+    print(
+        json.dumps(
+            {
+                "event": "anchor-exec",
+                "pid": os.getpid(),
+                "argv": ["mosaic", "yolo", ns.runtime, f"<{len(ns.args)} runtime args>"],
+                "note": "os.execvpe retains pid and /proc starttime",
+            },
+            sort_keys=True,
+        ),
+        file=sys.stderr,
+        flush=True,
+    )
+    os.execvpe("mosaic", argv, os.environ)
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p1_broker.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Gate0 P1 broker prototype: peercred anchor minting and /proc ancestry checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import secrets
+import socket
+import stat
+import struct
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def proc_node(pid: int) -> dict[str, Any]:
+    text = Path(f"/proc/{pid}/stat").read_text()
+    close = text.rfind(")")
+    comm = text[text.find("(") + 1 : close]
+    fields = text[close + 2 :].split()
+    cmdline = Path(f"/proc/{pid}/cmdline").read_bytes().split(b"\0")
+    return {
+        "pid": pid,
+        "ppid": int(fields[1]),
+        "starttime_ticks": int(fields[19]),
+        "comm": comm,
+        "exe": os.readlink(f"/proc/{pid}/exe"),
+        "argv0": cmdline[0].decode(errors="replace") if cmdline and cmdline[0] else "",
+        "argc": len([part for part in cmdline if part]),
+    }
+
+
+def ancestry(peer_pid: int, anchor: dict[str, Any] | None) -> tuple[list[dict[str, Any]], bool, str]:
+    chain: list[dict[str, Any]] = []
+    pid = peer_pid
+    seen: set[int] = set()
+    try:
+        while pid > 0 and pid not in seen:
+            seen.add(pid)
+            node = proc_node(pid)
+            chain.append(node)
+            if anchor and pid == anchor["pid"]:
+                if node["starttime_ticks"] != anchor["starttime_ticks"]:
+                    return chain, False, "anchor-starttime-mismatch"
+                break
+            pid = node["ppid"]
+        else:
+            return chain, False, "anchor-not-reached"
+
+        if not anchor or chain[-1]["pid"] != anchor["pid"]:
+            return chain, False, "anchor-not-reached"
+
+        # Re-read every node after the walk. A disappearing PID or changed
+        # starttime invalidates the complete chain (PID-reuse/race closure).
+        for original in chain:
+            again = proc_node(original["pid"])
+            if again["starttime_ticks"] != original["starttime_ticks"]:
+                return chain, False, f"starttime-race:{original['pid']}"
+        return chain, True, "ancestry-reaches-registered-anchor"
+    except (FileNotFoundError, ProcessLookupError, PermissionError) as exc:
+        return chain, False, f"proc-walk-failed:{type(exc).__name__}"
+
+
+def emit(log_file: Path, record: dict[str, Any]) -> None:
+    line = json.dumps(record, sort_keys=True)
+    with log_file.open("a", encoding="utf-8") as out:
+        out.write(line + "\n")
+    print(line, flush=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--socket", required=True)
+    parser.add_argument("--log", required=True)
+    parser.add_argument("--state", required=True)
+    args = parser.parse_args()
+
+    socket_path = Path(args.socket)
+    log_file = Path(args.log)
+    state_file = Path(args.state)
+    socket_path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(socket_path.parent, 0o700)
+    socket_path.unlink(missing_ok=True)
+    log_file.unlink(missing_ok=True)
+    state_file.unlink(missing_ok=True)
+
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    server.bind(str(socket_path))
+    os.chmod(socket_path, 0o600)
+    server.listen(8)
+    anchor: dict[str, Any] | None = None
+    session_id: str | None = None
+    emit(
+        log_file,
+        {
+            "event": "broker-listen",
+            "pid": os.getpid(),
+            "socket": str(socket_path),
+            "directory_mode": f"{stat.S_IMODE(socket_path.parent.stat().st_mode):04o}",
+            "socket_mode": f"{stat.S_IMODE(socket_path.stat().st_mode):04o}",
+        },
+    )
+
+    while True:
+        conn, _ = server.accept()
+        with conn:
+            raw = conn.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, 12)
+            peer_pid, peer_uid, peer_gid = struct.unpack("3i", raw)
+            request = json.loads(conn.makefile("r", encoding="utf-8").readline())
+            action = request.get("action")
+
+            if action == "register-anchor" and anchor is None:
+                anchor = proc_node(peer_pid)
+                session_id = secrets.token_hex(16)
+                state = {"session_id": session_id, "anchor": anchor}
+                state_file.write_text(json.dumps(state, sort_keys=True) + "\n")
+                record = {
+                    "event": "anchor-minted",
+                    "decision": "ACCEPT",
+                    "peercred": {"pid": peer_pid, "uid": peer_uid, "gid": peer_gid},
+                    "anchor": anchor,
+                    "session_id": session_id,
+                }
+                emit(log_file, record)
+                conn.sendall((json.dumps(record) + "\n").encode())
+                continue
+
+            if action in {"resolve-hook", "claim-session"}:
+                chain, reaches, reason = ancestry(peer_pid, anchor)
+                claimed = request.get("session_id")
+                claim_ok = action == "resolve-hook" or claimed == session_id
+                accepted = bool(anchor and session_id and reaches and claim_ok)
+                if action == "claim-session" and claimed != session_id:
+                    reason = "unknown-session-id"
+                elif action == "claim-session" and claimed == session_id and not reaches:
+                    reason = "victim-id-known-but-ancestry-mismatch"
+                record = {
+                    "event": action,
+                    "decision": "ACCEPT" if accepted else "REJECT",
+                    "reason": reason,
+                    "peercred": {"pid": peer_pid, "uid": peer_uid, "gid": peer_gid},
+                    "claimed_session_id": claimed,
+                    "resolved_session_id": session_id if accepted else None,
+                    "anchor": anchor,
+                    "ancestry": chain,
+                    "starttimes_rechecked": reaches,
+                }
+                emit(log_file, record)
+                conn.sendall((json.dumps(record) + "\n").encode())
+                continue
+
+            if action == "shutdown":
+                record = {
+                    "event": "broker-shutdown",
+                    "peercred": {"pid": peer_pid, "uid": peer_uid, "gid": peer_gid},
+                }
+                emit(log_file, record)
+                conn.sendall((json.dumps(record) + "\n").encode())
+                break
+
+            record = {
+                "event": "invalid-request",
+                "decision": "REJECT",
+                "peercred": {"pid": peer_pid, "uid": peer_uid, "gid": peer_gid},
+            }
+            emit(log_file, record)
+            conn.sendall((json.dumps(record) + "\n").encode())
+
+    server.close()
+    socket_path.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        print(f"P1 broker fatal: {type(exc).__name__}: {exc}", file=sys.stderr)
+        raise

docs/compaction-refresh/probes/p1_hook_client.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Claude SessionStart hook client for P1 ancestry evidence."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+
+
+def main() -> None:
+    # Consume the real Claude hook payload without recording transcript paths or
+    # prompt content in the evidence artifact.
+    hook_input = json.load(sys.stdin)
+    conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    conn.connect(os.environ["GATE0_BROKER_SOCKET"])
+    conn.sendall((json.dumps({"action": "resolve-hook"}) + "\n").encode())
+    response = json.loads(conn.makefile("r", encoding="utf-8").readline())
+    conn.close()
+    event_name = hook_input.get("hook_event_name")
+    if response.get("decision") != "ACCEPT":
+        print(f"Gate0 broker rejected {event_name} hook ancestry", file=sys.stderr)
+        raise SystemExit(2)
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": event_name,
+                    "additionalContext": "GATE0_P1_SUPPORTED_HOOK_ANCESTRY_ACCEPTED",
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p1_pi_extension.ts

@@ -0,0 +1,35 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import net from 'node:net';
+
+async function brokerRequest(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const socketPath = process.env['GATE0_BROKER_SOCKET'];
+  if (!socketPath) throw new Error('GATE0_BROKER_SOCKET missing');
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let buffer = '';
+    socket.setEncoding('utf8');
+    socket.on('connect', () => socket.write(`${JSON.stringify(payload)}\n`));
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) return;
+      socket.end();
+      resolve(JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>);
+    });
+    socket.on('error', reject);
+  });
+}
+
+export default function register(pi: ExtensionAPI) {
+  pi.on('session_start', async () => {
+    const response = await brokerRequest({ action: 'resolve-hook', runtime: 'pi-extension' });
+    if (response['decision'] !== 'ACCEPT') {
+      throw new Error(`P1 broker rejected Pi extension ancestry: ${response['reason']}`);
+    }
+  });
+
+  pi.registerCommand('gate0-p1-ready', {
+    description: 'Return only after the P1 session_start ancestry hook completed',
+    handler: async () => undefined,
+  });
+}

docs/compaction-refresh/probes/p1_run.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Run P1 against the real installed Mosaic→Pi and Mosaic→Claude chains."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+HERE = Path(__file__).resolve().parent
+
+
+def wait_for(predicate, description: str, timeout: float = 30.0) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return
+        time.sleep(0.05)
+    raise TimeoutError(f"timed out waiting for {description}")
+
+
+def read_records(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text().splitlines() if line]
+
+
+def socket_request(path: Path, payload: dict[str, object]) -> dict[str, object]:
+    conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    conn.connect(str(path))
+    conn.sendall((json.dumps(payload) + "\n").encode())
+    response = json.loads(conn.makefile("r", encoding="utf-8").readline())
+    conn.close()
+    return response
+
+
+def start_broker(root: Path) -> tuple[subprocess.Popen[str], Path, Path, Path]:
+    socket_path = root / "broker.sock"
+    log_path = root / "broker.jsonl"
+    state_path = root / "state.json"
+    broker = subprocess.Popen(
+        [
+            sys.executable,
+            str(HERE / "p1_broker.py"),
+            "--socket",
+            str(socket_path),
+            "--log",
+            str(log_path),
+            "--state",
+            str(state_path),
+        ],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    wait_for(socket_path.exists, "broker socket")
+    return broker, socket_path, log_path, state_path
+
+
+def print_ps(record: dict[str, Any]) -> None:
+    chain = record.get("ancestry", [])
+    pids = [str(node["pid"]) for node in chain if Path(f"/proc/{node['pid']}").exists()]
+    if not pids:
+        print("ps_snapshot=<hook chain exited; broker /proc snapshot above is authoritative>")
+        return
+    command = [
+        "ps",
+        "-o",
+        "pid=,ppid=,lstart=,uid=,gid=,comm=",
+        "-p",
+        ",".join(pids),
+    ]
+    print("$ " + " ".join(command))
+    print(subprocess.check_output(command, text=True).rstrip())
+
+
+def run_runtime(runtime: str) -> None:
+    with tempfile.TemporaryDirectory(prefix=f"gate0-p1-{runtime}-") as temp:
+        root = Path(temp)
+        workspace = root / "workspace"
+        workspace.mkdir()
+        broker, socket_path, log_path, state_path = start_broker(root)
+        env = os.environ.copy()
+        env.update(
+            {
+                "GATE0_BROKER_SOCKET": str(socket_path),
+                "MOSAIC_PI_FORCE_SKILLS": "",
+                "PI_SKIP_VERSION_CHECK": "1",
+            }
+        )
+        stdout_path = root / f"{runtime}.stdout"
+        stderr_path = root / f"{runtime}.stderr"
+
+        if runtime == "pi":
+            runtime_args = [
+                "--mode",
+                "rpc",
+                "--no-session",
+                "--no-extensions",
+                "--no-context-files",
+                "--no-prompt-templates",
+                "--extension",
+                str(HERE / "p1_pi_extension.ts"),
+            ]
+        else:
+            settings = root / "claude-settings.json"
+            settings.write_text(
+                json.dumps(
+                    {
+                        "hooks": {
+                            "SessionStart": [
+                                {
+                                    "hooks": [
+                                        {
+                                            "type": "command",
+                                            "command": f'python3 "{HERE / "p1_hook_client.py"}"',
+                                            "timeout": 20,
+                                        }
+                                    ]
+                                }
+                            ]
+                        }
+                    }
+                )
+            )
+            runtime_args = [
+                "--settings",
+                str(settings),
+                "--model",
+                "haiku",
+                "--print",
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--include-hook-events",
+                "--max-budget-usd",
+                "0.03",
+                "Reply exactly: OK",
+            ]
+
+        out = stdout_path.open("w", encoding="utf-8")
+        err = stderr_path.open("w", encoding="utf-8")
+        anchor = subprocess.Popen(
+            [
+                sys.executable,
+                str(HERE / "p1_anchor_exec.py"),
+                "--socket",
+                str(socket_path),
+                runtime,
+                *runtime_args,
+            ],
+            cwd=workspace,
+            env=env,
+            stdin=subprocess.PIPE if runtime == "pi" else subprocess.DEVNULL,
+            stdout=out,
+            stderr=err,
+            text=True,
+            start_new_session=True,
+        )
+        try:
+            wait_for(state_path.exists, "anchor registration")
+            attacker = subprocess.run(
+                [
+                    sys.executable,
+                    str(HERE / "p1_sibling_attacker.py"),
+                    "--socket",
+                    str(socket_path),
+                    "--state",
+                    str(state_path),
+                ],
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+            if runtime == "pi":
+                assert anchor.stdin is not None
+                anchor.stdin.write('{"id":"state","type":"get_state"}\n')
+                anchor.stdin.flush()
+
+            wait_for(
+                lambda: any(r.get("event") == "resolve-hook" for r in read_records(log_path)),
+                f"{runtime} supported hook/extension broker contact",
+                timeout=60,
+            )
+            if runtime == "claude":
+                try:
+                    anchor.wait(timeout=90)
+                except subprocess.TimeoutExpired:
+                    pass
+            records = read_records(log_path)
+            state = json.loads(state_path.read_text())
+            resolve = next(r for r in records if r.get("event") == "resolve-hook")
+            reject = next(r for r in records if r.get("event") == "claim-session")
+            if resolve.get("decision") != "ACCEPT":
+                raise AssertionError(f"{runtime} hook ancestry was not accepted: {resolve}")
+            if reject.get("decision") != "REJECT":
+                raise AssertionError(f"{runtime} sibling substitution was not rejected: {reject}")
+            if attacker.returncode != 0:
+                raise AssertionError(f"{runtime} sibling probe did not observe rejection: {attacker.stderr}")
+
+            print(f"=== P1 {runtime.upper()} REAL LAUNCH ===")
+            print("machine_assertions=PASS")
+            print(
+                "$ python3 docs/compaction-refresh/probes/p1_anchor_exec.py "
+                f"--socket <protected-socket> {runtime} <runtime args>"
+            )
+            print("registered_anchor=" + json.dumps(state["anchor"], sort_keys=True))
+            print("broker_minted_session_id=" + state["session_id"])
+            print("hook_or_extension_record=" + json.dumps(resolve, sort_keys=True))
+            print("sibling_attack_record=" + json.dumps(reject, sort_keys=True))
+            print("sibling_process_stdout=" + attacker.stdout.strip())
+            print(f"sibling_process_exit={attacker.returncode}")
+            print_ps(resolve)
+            print("launcher_stderr_excerpt:")
+            for line in stderr_path.read_text(errors="replace").splitlines()[:12]:
+                print("  " + line[:500])
+            runtime_lines = stdout_path.read_text(errors="replace").splitlines()
+            print("runtime_stdout_excerpt:")
+            for line in runtime_lines[:8]:
+                print("  " + line[:500])
+            hook_lines = [
+                line
+                for line in runtime_lines
+                if "hook" in line.lower() or "GATE0_P1_SUPPORTED_HOOK" in line
+            ]
+            print("runtime_hook_event_excerpt:")
+            for line in hook_lines[:8]:
+                print("  " + line[:1000])
+            print()
+        finally:
+            if anchor.poll() is None:
+                try:
+                    os.killpg(anchor.pid, signal.SIGTERM)
+                except ProcessLookupError:
+                    pass
+                try:
+                    anchor.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    os.killpg(anchor.pid, signal.SIGKILL)
+                    anchor.wait(timeout=5)
+            out.close()
+            err.close()
+            try:
+                socket_request(socket_path, {"action": "shutdown"})
+            except OSError:
+                pass
+            try:
+                broker.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                broker.kill()
+                broker.wait()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--runtime", choices=["pi", "claude", "both"], default="both")
+    ns = parser.parse_args()
+    if ns.runtime in {"pi", "both"}:
+        run_runtime("pi")
+    if ns.runtime in {"claude", "both"}:
+        run_runtime("claude")
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p1_sibling_attacker.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Same-UID sibling that attempts to claim the anchor's broker-minted id."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import socket
+import time
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--socket", required=True)
+    parser.add_argument("--state", required=True)
+    ns = parser.parse_args()
+    state_path = Path(ns.state)
+    for _ in range(200):
+        if state_path.exists():
+            break
+        time.sleep(0.025)
+    state = json.loads(state_path.read_text())
+    conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    conn.connect(ns.socket)
+    conn.sendall(
+        (
+            json.dumps(
+                {"action": "claim-session", "session_id": state["session_id"]},
+                sort_keys=True,
+            )
+            + "\n"
+        ).encode()
+    )
+    response = json.loads(conn.makefile("r", encoding="utf-8").readline())
+    conn.close()
+    print(
+        json.dumps(
+            {
+                "attacker_pid": os.getpid(),
+                "attacker_uid": os.getuid(),
+                "victim_session_id_known": True,
+                "broker_decision": response.get("decision"),
+                "broker_reason": response.get("reason"),
+            },
+            sort_keys=True,
+        )
+    )
+    raise SystemExit(0 if response.get("decision") == "REJECT" else 1)
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p2_provider_timing_run.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Force a real Pi HTTP provider response to prove response-hook timing."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from pi_gate0_run import PiRpc, jsonl
+
+HERE = Path(__file__).resolve().parent
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, _format: str, *_args: object) -> None:
+        return
+
+    def do_POST(self) -> None:  # noqa: N802
+        length = int(self.headers.get("content-length", "0"))
+        self.rfile.read(length)
+        chunks = [
+            {
+                "id": "gate0-response",
+                "object": "chat.completion.chunk",
+                "created": 1,
+                "model": "gate0-model",
+                "choices": [{"index": 0, "delta": {"role": "assistant"}, "finish_reason": None}],
+            },
+            {
+                "id": "gate0-response",
+                "object": "chat.completion.chunk",
+                "created": 1,
+                "model": "gate0-model",
+                "choices": [
+                    {"index": 0, "delta": {"content": "TIMING_OK"}, "finish_reason": None}
+                ],
+            },
+            {
+                "id": "gate0-response",
+                "object": "chat.completion.chunk",
+                "created": 1,
+                "model": "gate0-model",
+                "choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}],
+                "usage": {"prompt_tokens": 10, "completion_tokens": 2, "total_tokens": 12},
+            },
+        ]
+        body = "".join(f"data: {json.dumps(chunk)}\n\n" for chunk in chunks) + "data: [DONE]\n\n"
+        encoded = body.encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.send_header("X-Gate0-Response", "headers-before-stream")
+        self.end_headers()
+        self.wfile.write(encoded)
+        self.wfile.flush()
+
+
+def main() -> None:
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    port = server.server_address[1]
+
+    with tempfile.TemporaryDirectory(prefix="gate0-p2-timing-") as temp:
+        root = Path(temp)
+        workspace = root / "workspace"
+        workspace.mkdir()
+        log = root / "hooks.jsonl"
+        env = os.environ.copy()
+        env.update(
+            {
+                "GATE0_PI_LOG": str(log),
+                "GATE0_LOCAL_PROVIDER_URL": f"http://127.0.0.1:{port}/v1",
+                "MOSAIC_PI_FORCE_SKILLS": "",
+                "PI_SKIP_VERSION_CHECK": "1",
+            }
+        )
+        command = [
+            "mosaic",
+            "yolo",
+            "pi",
+            "--mode",
+            "rpc",
+            "--no-session",
+            "--no-extensions",
+            "--no-context-files",
+            "--no-prompt-templates",
+            "--provider",
+            "gate0-local",
+            "--model",
+            "gate0-model",
+            "--extension",
+            str(HERE / "pi_gate0_extension.ts"),
+        ]
+        pi = PiRpc(command, workspace, env)
+        try:
+            pi.prompt_and_settle("timing", "Reply with TIMING_OK")
+            records = jsonl(log)
+            selected = [
+                record
+                for record in records
+                if record["event"] in {"before_provider_request", "after_provider_response", "message_end"}
+                and (record["event"] != "message_end" or record.get("role") == "assistant")
+            ]
+            print("$ python3 docs/compaction-refresh/probes/p2_provider_timing_run.py")
+            print(f"local_http_endpoint=http://127.0.0.1:{port}/v1/chat/completions")
+            for record in selected:
+                print(json.dumps(record, sort_keys=True))
+            after = next(record for record in selected if record["event"] == "after_provider_response")
+            message = next(record for record in selected if record["event"] == "message_end")
+            if not (
+                after["seq"] < message["seq"]
+                and after["assistantContentAvailableAtThisHook"] is False
+                and message["assistantContentObserved"] is True
+            ):
+                raise AssertionError("provider response/content observation ordering failed")
+            print("machine_assertions=PASS")
+            print(f"after_provider_response_seq={after['seq']}")
+            print(f"message_end_seq={message['seq']}")
+            print(f"headers_hook_precedes_completed_message={after['seq'] < message['seq']}")
+        finally:
+            pi.close()
+
+    server.shutdown()
+    server.server_close()
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p3_d4_focused_run.py

@@ -0,0 +1,849 @@
+#!/usr/bin/env python3
+"""D4-only same-PID runtime-generation revocation harness.
+
+AUTHORING NOTE: this file is intentionally not executed until the separately
+ratified FIRE authorization.  When run later, every invocation creates its own
+/tmp fixture and launches the real Pi RPC runtime with only the D4 extension
+and ``p3_generation_broker.py``.  It does not use the broader Gate0 runner.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import hashlib
+import json
+import os
+import queue
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+HERE = Path(__file__).resolve().parent
+# WI-3 remains in a reviewed worktree until the release package contains the
+# gated launcher. The probe resolves that worktree portably and never falls
+# back to the released `mosaic` binary.
+GATED_WI_ROOT_OVERRIDE = os.environ.get("GATED_WI_ROOT")
+GATED_WI_BRANCH = "refs/heads/feat/830-compaction-revoke"
+GATED_WI_HEAD = "f400830738998db105107a2a4c69c7f2a2a6fd5d"
+GATED_WI_ANCESTOR = "66b1e0a0"
+GATED_BROKER_HEAD = "23c0caca9b5d44002e6184cd7f2b6c837e8795b2"
+LEASE_BROKER_DIRECTORY = "packages/mosaic/framework/tools/lease-broker"
+BROKER_RELATIVE_PATH = "docs/compaction-refresh/probes/p3_generation_broker.py"
+GATED_LAUNCHER_SHA256 = "e950e4224e280f16979d90cabb89aa1896c5ee28bed2df957e14d018d43cda82"
+GATED_GENERATION_SHA256 = "061625402f08488eac47acd23272904e71fd1a71fd15b3bdab158632c801be4c"
+GATED_BROKER_SHA256 = "4db4fef1ac6658a8ca79ad5091cefc901d2aa26003265c3d6726c294cf895cad"
+
+
+class PiRpc:
+    """Small JSON-RPC client for an isolated real Pi process."""
+
+    def __init__(self, command: list[str], cwd: Path, env: dict[str, str]) -> None:
+        self.process = subprocess.Popen(
+            command,
+            cwd=cwd,
+            env=env,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+            start_new_session=True,
+        )
+        self.events: queue.Queue[dict[str, Any]] = queue.Queue()
+        self.stderr_lines: list[str] = []
+        threading.Thread(target=self._read_stdout, daemon=True).start()
+        threading.Thread(target=self._read_stderr, daemon=True).start()
+
+    def _read_stdout(self) -> None:
+        if self.process.stdout is None:
+            raise RuntimeError("Pi stdout pipe is unavailable")
+        for line in self.process.stdout:
+            try:
+                self.events.put(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    def _read_stderr(self) -> None:
+        if self.process.stderr is None:
+            raise RuntimeError("Pi stderr pipe is unavailable")
+        for line in self.process.stderr:
+            self.stderr_lines.append(line.rstrip("\n"))
+
+    def send(self, payload: dict[str, object]) -> None:
+        if self.process.stdin is None:
+            raise RuntimeError("Pi stdin pipe is unavailable")
+        self.process.stdin.write(json.dumps(payload) + "\n")
+        self.process.stdin.flush()
+
+    def wait(
+        self,
+        predicate: Callable[[dict[str, Any]], bool],
+        description: str,
+        timeout: float = 180,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self.process.poll() is not None and self.events.empty():
+                detail = " | ".join(self.stderr_lines[-5:])
+                raise RuntimeError(
+                    f"Pi exited {self.process.returncode} while waiting for {description}: {detail}"
+                )
+            try:
+                event = self.events.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            if predicate(event):
+                return event
+        raise TimeoutError(f"timed out waiting for {description}")
+
+    def response(self, request_id: str, timeout: float = 180) -> dict[str, Any]:
+        return self.wait(
+            lambda event: event.get("type") == "response" and event.get("id") == request_id,
+            f"response {request_id}",
+            timeout,
+        )
+
+    def prompt_and_settle(self, request_id: str, message: str) -> None:
+        self.send({"id": request_id, "type": "prompt", "message": message})
+        response = self.response(request_id)
+        if not response.get("success"):
+            raise RuntimeError(f"prompt rejected: {response}")
+        self.wait(
+            lambda event: event.get("type") == "agent_settled",
+            f"agent_settled {request_id}",
+        )
+
+    def close(self) -> None:
+        if self.process.poll() is None:
+            try:
+                os.killpg(self.process.pid, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+            try:
+                self.process.wait(timeout=8)
+            except subprocess.TimeoutExpired:
+                os.killpg(self.process.pid, signal.SIGKILL)
+                self.process.wait(timeout=5)
+
+
+def wait_path(path: Path, timeout: float = 20) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if path.exists():
+            return
+        time.sleep(0.05)
+    raise TimeoutError(f"timed out waiting for {path}")
+
+
+def request(path: Path, payload: dict[str, object]) -> dict[str, Any]:
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as conn:
+        conn.connect(str(path))
+        conn.sendall((json.dumps(payload) + "\n").encode())
+        reply = conn.makefile("r", encoding="utf-8").readline()
+    return json.loads(reply)
+
+
+def jsonl(path: Path) -> list[dict[str, Any]]:
+    return [json.loads(line) for line in path.read_text().splitlines() if line]
+
+
+def write_extension(path: Path) -> None:
+    """Write the minimal Pi lifecycle bridge into the isolated fixture only."""
+
+    path.write_text(
+        """import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { appendFileSync, readFileSync } from 'node:fs';
+import net from 'node:net';
+
+const socketPath = process.env['D4_GENERATION_SOCKET'];
+const logPath = process.env['D4_PI_LOG'];
+
+function starttime(): number {
+  const text = readFileSync(`/proc/${process.pid}/stat`, 'utf8');
+  const close = text.lastIndexOf(')');
+  return Number(text.slice(close + 2).trim().split(/\\s+/)[19]);
+}
+
+function log(event: string, details: Record<string, unknown> = {}): void {
+  if (!logPath) return;
+  appendFileSync(logPath, `${JSON.stringify({ event, pid: process.pid, starttime_ticks: starttime(), ...details })}\\n`);
+}
+
+function broker(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+  if (!socketPath) return Promise.reject(new Error('D4_GENERATION_SOCKET is required'));
+  return new Promise((resolve, reject) => {
+    const connection = net.createConnection(socketPath);
+    let buffer = '';
+    connection.setEncoding('utf8');
+    connection.on('connect', () => connection.write(`${JSON.stringify(payload)}\\n`));
+    connection.on('data', (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf('\\n');
+      if (newline < 0) return;
+      connection.end();
+      resolve(JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>);
+    });
+    connection.on('error', reject);
+  });
+}
+
+export default function register(pi: ExtensionAPI): void {
+  let initialStartup = true;
+
+  async function lifecycle(
+    phase: 'start' | 'shutdown',
+    reason: string,
+  ): Promise<Record<string, unknown>> {
+    if (!(phase === 'start' && reason === 'startup' && initialStartup)) {
+      const bump = await broker({ action: 'bump-generation' });
+      log('generation_state_bump', { phase, reason, bump });
+    }
+    initialStartup = false;
+    return broker({ action: 'lifecycle', phase, reason });
+  }
+
+  pi.on('session_start', async (event) => {
+    const lifecycleResult = await lifecycle('start', event.reason);
+    log('session_start', { reason: event.reason, lifecycle: lifecycleResult });
+    if (event.reason === 'reload') {
+      const generation = lifecycleResult['new_generation'];
+      if (typeof generation !== 'number') throw new Error('broker did not return new_generation');
+      const current = await broker({ action: 'authorize-probe', generation });
+      const superseded = await broker({ action: 'authorize-probe', generation: generation - 1 });
+      log('d4_generation_authorization', { generation, current, superseded });
+    }
+  });
+
+  pi.on('session_shutdown', async (event) => {
+    const lifecycleResult = await lifecycle('shutdown', event.reason);
+    log('session_shutdown', { reason: event.reason, lifecycle: lifecycleResult });
+  });
+
+  pi.registerTool({
+    name: 'd4_fixture_promote',
+    label: 'D4 Fixture Promotion',
+    description: 'Promotes only the fixture lease needed for the D4 revocation check.',
+    parameters: Type.Object({}),
+    async execute() {
+      // the promotion step is a D4 test fixture, not a P2 evidence-gathering authorization.
+      const promotion = await broker({ action: 'promote-probe' });
+      log('fixture_promotion', { promotion });
+      return { content: [{ type: 'text', text: 'D4 fixture promotion complete' }] };
+    },
+  });
+
+  pi.registerCommand('d4-reload', {
+    description: 'D4-only same-PID reload boundary.',
+    handler: async (_args, context) => {
+      await context.reload();
+    },
+  });
+}
+""",
+        encoding="utf-8",
+    )
+
+
+def repository_root() -> Path:
+    for candidate in HERE.parents:
+        if (candidate / ".git").exists():
+            return candidate
+    raise RuntimeError("D4 precondition: probe repository root is unavailable")
+
+
+def resolve_gated_wi_root() -> Path:
+    """Resolve an explicit override or the unique checked-out WI-3 branch."""
+
+    if GATED_WI_ROOT_OVERRIDE:
+        candidate = Path(GATED_WI_ROOT_OVERRIDE).expanduser()
+        candidates = [candidate]
+    else:
+        try:
+            listing = subprocess.check_output(
+                ["git", "-C", str(repository_root()), "worktree", "list", "--porcelain"],
+                text=True,
+            )
+        except (OSError, subprocess.CalledProcessError) as error:
+            raise RuntimeError("D4 precondition: cannot enumerate WI-3 worktrees") from error
+        candidates = []
+        worktree: Path | None = None
+        head: str | None = None
+        branch: str | None = None
+        for line in [*listing.splitlines(), ""]:
+            if line.startswith("worktree "):
+                worktree = Path(line.removeprefix("worktree "))
+                head = None
+                branch = None
+            elif line.startswith("HEAD "):
+                head = line.removeprefix("HEAD ")
+            elif line.startswith("branch "):
+                branch = line.removeprefix("branch ")
+            elif not line and worktree is not None:
+                if head == GATED_WI_HEAD and branch == GATED_WI_BRANCH:
+                    candidates.append(worktree)
+                worktree = None
+        if len(candidates) != 1:
+            raise RuntimeError("D4 precondition: WI-3 worktree is ambiguous or unavailable")
+
+    gated_root = candidates[0]
+    try:
+        if not gated_root.is_dir():
+            raise RuntimeError("D4 precondition: GATED_WI_ROOT is not a directory")
+        is_worktree = subprocess.check_output(
+            ["git", "-C", str(gated_root), "rev-parse", "--is-inside-work-tree"],
+            text=True,
+        ).strip()
+        head = subprocess.check_output(
+            ["git", "-C", str(gated_root), "rev-parse", "HEAD"], text=True
+        ).strip()
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise RuntimeError("D4 precondition: GATED_WI_ROOT is not a git worktree") from error
+    if is_worktree != "true":
+        raise RuntimeError("D4 precondition: GATED_WI_ROOT is not a git worktree")
+    if head != GATED_WI_HEAD:
+        raise RuntimeError(f"D4 precondition: gated WI head mismatch: {head}")
+    try:
+        forward_contains = subprocess.run(
+            [
+                "git",
+                "-C",
+                str(gated_root),
+                "merge-base",
+                "--is-ancestor",
+                GATED_WI_ANCESTOR,
+                GATED_WI_HEAD,
+            ],
+            check=False,
+        ).returncode == 0
+    except OSError as error:
+        raise RuntimeError("D4 precondition: cannot verify WI-3 ancestry") from error
+    if not forward_contains:
+        raise RuntimeError("D4 precondition: gated WI lacks required ancestor")
+    return gated_root
+
+
+@dataclass(frozen=True)
+class PinnedClosure:
+    launcher: Path
+    generation: Path
+    broker: Path
+
+
+def git_object_bytes(git_root: Path, commit: str, relative_path: str) -> bytes:
+    try:
+        return subprocess.check_output(
+            ["git", "-C", str(git_root), "show", f"{commit}:{relative_path}"]
+        )
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise RuntimeError(f"D4 precondition: missing pinned source {relative_path}") from error
+
+
+def closure_import_guard(member_sources: dict[str, str]) -> None:
+    """Refuse an incomplete project-code closure before materializing it."""
+
+    allowed_nonstdlib = {"lease_generation"}
+    stdlib = getattr(sys, "stdlib_module_names", frozenset())
+    for name, source in member_sources.items():
+        try:
+            tree = ast.parse(source, filename=name)
+        except SyntaxError as error:
+            raise RuntimeError(f"D4 precondition: pinned {name} does not parse") from error
+        for node in ast.walk(tree):
+            module: str | None = None
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    module = alias.name.split(".", maxsplit=1)[0]
+                    if module not in stdlib and module not in allowed_nonstdlib:
+                        raise RuntimeError(f"D4 precondition: unpinned import {module} in {name}")
+            elif isinstance(node, ast.ImportFrom):
+                if node.level:
+                    raise RuntimeError(f"D4 precondition: relative import in {name}")
+                if node.module:
+                    module = node.module.split(".", maxsplit=1)[0]
+                    if module not in stdlib and module not in allowed_nonstdlib:
+                        raise RuntimeError(f"D4 precondition: unpinned import {module} in {name}")
+
+
+def write_pinned_file(path: Path, data: bytes) -> None:
+    descriptor = os.open(
+        path,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_CLOEXEC,
+        0o600,
+    )
+    try:
+        remaining = memoryview(data)
+        while remaining:
+            written = os.write(descriptor, remaining)
+            if written <= 0:
+                raise OSError("pinned write made no progress")
+            remaining = remaining[written:]
+    finally:
+        os.close(descriptor)
+
+
+def materialize_closure(root: Path, gated_root: Path, gate0_root: Path) -> PinnedClosure:
+    """Pin the complete project-authored runtime closure inside this fixture."""
+
+    launcher_relative = f"{LEASE_BROKER_DIRECTORY}/launch-runtime.py"
+    generation_relative = f"{LEASE_BROKER_DIRECTORY}/lease_generation.py"
+    members = (
+        (
+            "launch-runtime.py",
+            gated_root,
+            GATED_WI_HEAD,
+            launcher_relative,
+            GATED_LAUNCHER_SHA256,
+        ),
+        (
+            "lease_generation.py",
+            gated_root,
+            GATED_WI_HEAD,
+            generation_relative,
+            GATED_GENERATION_SHA256,
+        ),
+        (
+            "p3_generation_broker.py",
+            gate0_root,
+            GATED_BROKER_HEAD,
+            BROKER_RELATIVE_PATH,
+            GATED_BROKER_SHA256,
+        ),
+    )
+    member_bytes: dict[str, bytes] = {}
+    member_sources: dict[str, str] = {}
+    for name, git_root, commit, relative_path, digest in members:
+        data = git_object_bytes(git_root, commit, relative_path)
+        if hashlib.sha256(data).hexdigest() != digest:
+            raise RuntimeError(f"D4 precondition: {name} hash mismatch")
+        try:
+            member_sources[name] = data.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise RuntimeError(f"D4 precondition: pinned {name} is not UTF-8") from error
+        member_bytes[name] = data
+    closure_import_guard(member_sources)
+
+    pinned = root / "pinned"
+    pinned.mkdir(mode=0o700)
+    paths = {name: pinned / name for name, *_ in members}
+    for name, path in paths.items():
+        write_pinned_file(path, member_bytes[name])
+    return PinnedClosure(
+        launcher=paths["launch-runtime.py"],
+        generation=paths["lease_generation.py"],
+        broker=paths["p3_generation_broker.py"],
+    )
+
+
+def gated_launcher_precondition(
+    root: Path, socket_path: Path, environment: dict[str, str]
+) -> PinnedClosure:
+    """Verify and materialize the full WI-3/probe closure before execution."""
+
+    if environment.get("MOSAIC_LEASE_BROKER_SOCKET") != str(socket_path):
+        raise RuntimeError("D4 precondition: lease broker socket is not this fixture")
+    if environment.get("MOSAIC_LEASE_GENERATION_FILE"):
+        raise RuntimeError("D4 precondition: inherited generation file is forbidden")
+    fixture_path_vars = (
+        "HOME",
+        "XDG_CONFIG_HOME",
+        "XDG_CACHE_HOME",
+        "XDG_STATE_HOME",
+        "XDG_RUNTIME_DIR",
+        "TMPDIR",
+        "D4_PI_LOG",
+        "MOSAIC_AGENT_WORKDIR",
+        "MOSAIC_HEARTBEAT_RUN_DIR",
+        "MOSAIC_HOME",
+    )
+    if any(
+        not (value := environment.get(name)) or not Path(value).is_relative_to(root)
+        for name in fixture_path_vars
+    ):
+        raise RuntimeError("D4 precondition: child write path escapes fixture root")
+    if socket_path.parent != root or root.parent != Path(tempfile.gettempdir()):
+        raise RuntimeError("D4 precondition: fixture socket is outside this run's temporary root")
+
+    gated_root = resolve_gated_wi_root()
+    closure = materialize_closure(root, gated_root, repository_root())
+    launcher_source = closure.launcher.read_text(encoding="utf-8")
+    generation_source = closure.generation.read_text(encoding="utf-8")
+    # Exact hashes in materialize_closure are the trust anchor. These marker
+    # checks are belt-and-suspenders diagnostics only.
+    behavior_markers = (
+        '"action": "register_anchor"',
+        "initialize_runtime_generation(generation_file, generation)",
+        "execute(command[0], command, environment)",
+        'source_environment["MOSAIC_LEASE_BROKER_SOCKET"]',
+        'socket_path.parent / f"generation-{session_id}.state"',
+        'environment["MOSAIC_LEASE_GENERATION_FILE"]',
+    )
+    if not all(marker in launcher_source for marker in behavior_markers) or not (
+        "def read_runtime_generation" in generation_source
+        and "def bump_runtime_generation" in generation_source
+    ):
+        raise RuntimeError("D4 precondition: pinned launcher lacks file-generation markers")
+    return closure
+
+
+def reject_pinned_bytecode(pinned_directory: Path) -> None:
+    cache_directory = pinned_directory / "__pycache__"
+    if cache_directory.exists() or any(pinned_directory.rglob("*.pyc")):
+        raise RuntimeError("D4 precondition: pinned bytecode cache is forbidden")
+
+
+def launch_verified_pi(
+    launcher: Path,
+    workspace: Path,
+    sessions: Path,
+    extension: Path,
+    environment: dict[str, str],
+) -> PiRpc:
+    command = [
+        sys.executable,
+        # -s preserves sys.path[0]=pinned/ for the launcher's sibling helper.
+        "-s",
+        "-S",
+        "-B",
+        str(launcher),
+        "--runtime",
+        "pi",
+        "--",
+        "pi",
+        "--mode",
+        "rpc",
+        "--session-dir",
+        str(sessions),
+        "--no-extensions",
+        "--no-context-files",
+        "--no-prompt-templates",
+        "--model",
+        "openai-codex/gpt-5.6-sol",
+        "--thinking",
+        "medium",
+        "--extension",
+        str(extension),
+    ]
+    reject_pinned_bytecode(launcher.parent)
+    # This is deliberately the statement immediately before Popen (inside
+    # PiRpc): the fixture-pinned launcher bytes are re-hashed then executed.
+    if hashlib.sha256(launcher.read_bytes()).hexdigest() != GATED_LAUNCHER_SHA256:
+        raise RuntimeError("D4 precondition: adjacent launcher hash mismatch")
+    return PiRpc(command, workspace, environment)
+
+
+def launch_verified_broker(
+    broker_path: Path,
+    generation_path: Path,
+    socket_path: Path,
+    log_path: Path,
+    environment: dict[str, str],
+) -> subprocess.Popen[str]:
+    command = [
+        sys.executable,
+        "-I",
+        "-S",
+        "-B",
+        str(broker_path),
+        "--socket",
+        str(socket_path),
+        "--log",
+        str(log_path),
+        "--generation-module",
+        str(generation_path),
+    ]
+    reject_pinned_bytecode(broker_path.parent)
+    if hashlib.sha256(broker_path.read_bytes()).hexdigest() != GATED_BROKER_SHA256:
+        raise RuntimeError("D4 precondition: pinned broker hash mismatch")
+    # The final helper re-hash is immediately adjacent to the broker Popen.
+    if hashlib.sha256(generation_path.read_bytes()).hexdigest() != GATED_GENERATION_SHA256:
+        raise RuntimeError("D4 precondition: pinned helper hash mismatch")
+    return subprocess.Popen(
+        command,
+        env=environment,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+
+
+def assert_d4(records: list[dict[str, Any]]) -> dict[str, object]:
+    def record_where(description: str, candidates: list[dict[str, Any]]) -> dict[str, Any]:
+        if not candidates:
+            raise AssertionError(f"missing D4 evidence record: {description}")
+        return candidates[0]
+
+    fixture_listen = record_where(
+        "fixture listen", [r for r in records if r.get("event") == "listen"]
+    )
+    fixture_root = Path(fixture_listen["socket"]).parent
+    lifecycle = [record for record in records if record.get("event") == "runtime_generation_bump"]
+    state_bumps = [record for record in records if record.get("event") == "generation_state_bumped"]
+    promotion = record_where(
+        "fixture promotion", [r for r in records if r.get("event") == "probe_lease_promoted"]
+    )
+    launcher_registration = record_where(
+        "lease anchor", [r for r in records if r.get("event") == "lease_anchor_registered"]
+    )
+    reload_revoke = record_where(
+        "reload shutdown",
+        [
+            r
+            for r in lifecycle
+            if r.get("reason") == "reload" and r.get("phase") == "shutdown"
+        ],
+    )
+    reload_start = record_where(
+        "reload start",
+        [
+            r
+            for r in lifecycle
+            if r.get("reason") == "reload" and r.get("phase") == "start"
+        ],
+    )
+    authorization = [
+        record for record in records if record.get("event") == "generation_authorization"
+    ]
+    current_generation = reload_start["new_generation"]
+    current_authorization = record_where(
+        "current-generation authorization",
+        [r for r in authorization if r.get("requested_generation") == current_generation],
+    )
+    superseded_authorization = record_where(
+        "superseded-generation authorization",
+        [r for r in authorization if r.get("requested_generation") == current_generation - 1],
+    )
+
+    identities = {
+        (record["peercred"]["pid"], record["starttime_ticks"])
+        for record in [*lifecycle, *state_bumps, promotion, launcher_registration, *authorization]
+    }
+    generations = [record["new_generation"] for record in lifecycle]
+    file_records = [*lifecycle, *state_bumps, promotion, *authorization]
+    observed_reasons = {record.get("reason") for record in lifecycle}
+    checks = {
+        "same_pid_starttime": len(identities) == 1,
+        "strictly_increasing_generation": all(
+            previous < current for previous, current in zip(generations, generations[1:])
+        ),
+        "state_file_drives_lifecycle": [record["generation"] for record in state_bumps]
+        == generations[1:],
+        "state_file_source": all(
+            record.get("generation_source") == "state-file" for record in file_records
+        ),
+        "state_file_in_fixture_root": all(
+            Path(record["generation_file"]).parent == fixture_root for record in file_records
+        )
+        and Path(launcher_registration["generation_file"]).parent == fixture_root,
+        "all_lifecycle_boundaries": {"startup", "reload", "fork", "new", "resume"}
+        <= observed_reasons,
+        "lease_anchor_fixture": launcher_registration.get("session_id_shape") == "hex-256",
+        "verified_revoked_on_reload": reload_revoke.get("prior_lease") == "VERIFIED"
+        and reload_revoke.get("prior_lease_revoked") is True,
+        "new_generation_unverified": current_authorization.get("code") == "MUTATOR_UNVERIFIED",
+        "prior_generation_stale": superseded_authorization.get("code") == "STALE_GENERATION",
+    }
+    failed = [name for name, passed in checks.items() if not passed]
+    if failed:
+        raise AssertionError(f"D4 checks failed: {', '.join(failed)}")
+    passed = all(checks.values())
+    if not passed:
+        raise AssertionError("D4 PASS derivation failed")
+
+    return {
+        "machine_assertions": "PASS" if passed else "FAIL",
+        "checks": checks,
+        "same_pid_starttime": next(iter(identities)),
+        "generations": generations,
+        "reload_revoke_verified": checks["verified_revoked_on_reload"],
+        "lease_anchor_fixture": checks["lease_anchor_fixture"],
+        "file_backed_generation": checks["state_file_drives_lifecycle"],
+        "new_generation_code": current_authorization["code"],
+        "superseded_generation_code": superseded_authorization["code"],
+    }
+
+
+def isolated_environment(
+    root: Path, index: int, workspace: Path, socket_path: Path, pi_log: Path
+) -> dict[str, str]:
+    """Build a write-confined child environment; no inherited path variable survives."""
+
+    fixture_home = root / "home"
+    fixture_config = root / "config"
+    fixture_cache = root / "cache"
+    fixture_state = root / "state"
+    fixture_runtime = root / "runtime"
+    fixture_tmp = root / "tmp"
+    fixture_heartbeat = root / "heartbeat"
+    fixture_mosaic_home = root / "mosaic-home"
+    for directory in (
+        fixture_home,
+        fixture_config,
+        fixture_cache,
+        fixture_state,
+        fixture_runtime,
+        fixture_tmp,
+        fixture_heartbeat,
+        fixture_mosaic_home,
+    ):
+        directory.mkdir(mode=0o700)
+
+    # Authentication/settings are copied into fixture HOME so Pi never writes
+    # under the operator's HOME. They are not emitted or modified in place.
+    source_agent = Path.home() / ".pi" / "agent"
+    target_agent = fixture_home / ".pi" / "agent"
+    target_agent.mkdir(parents=True, mode=0o700)
+    for name in ("settings.json", "auth.json", "bin/fd"):
+        source = source_agent / name
+        target = target_agent / name
+        if source.is_file():
+            target.parent.mkdir(parents=True, mode=0o700)
+            shutil.copy2(source, target)
+
+    environment = {
+        "HOME": str(fixture_home),
+        "XDG_CONFIG_HOME": str(fixture_config),
+        "XDG_CACHE_HOME": str(fixture_cache),
+        "XDG_STATE_HOME": str(fixture_state),
+        "XDG_RUNTIME_DIR": str(fixture_runtime),
+        "TMPDIR": str(fixture_tmp),
+        "PATH": os.environ.get("PATH", ""),
+        "LANG": os.environ.get("LANG", "C.UTF-8"),
+        "TERM": os.environ.get("TERM", "dumb"),
+        "D4_GENERATION_SOCKET": str(socket_path),
+        "MOSAIC_LEASE_BROKER_SOCKET": str(socket_path),
+        "D4_PI_LOG": str(pi_log),
+        "MOSAIC_AGENT_NAME": f"d4-fixture-{index}",
+        "MOSAIC_AGENT_WORKDIR": str(workspace),
+        "MOSAIC_HEARTBEAT_RUN_DIR": str(fixture_heartbeat),
+        "MOSAIC_HOME": str(fixture_mosaic_home),
+        "MOSAIC_PI_FORCE_SKILLS": "",
+        "PI_SKIP_VERSION_CHECK": "1",
+        "PYTHONDONTWRITEBYTECODE": "1",
+        "PYTHONNOUSERSITE": "1",
+    }
+    if "PI_CODING_AGENT" in os.environ:
+        environment["PI_CODING_AGENT"] = os.environ["PI_CODING_AGENT"]
+    return environment
+
+
+def scrub_fixture_credentials(root: Path) -> None:
+    """Remove the copied Pi credential/config subtree before retaining evidence."""
+
+    copied_agent = root / "home" / ".pi" / "agent"
+    if copied_agent.exists():
+        shutil.rmtree(copied_agent)
+    if copied_agent.exists():
+        raise RuntimeError("D4 credential scrub failed")
+
+
+def run_once(index: int) -> Path:
+    root = Path(tempfile.mkdtemp(prefix=f"gate0-d4-{index}-"))
+    workspace = root / "workspace"
+    sessions = root / "sessions"
+    workspace.mkdir(mode=0o700)
+    sessions.mkdir(mode=0o700)
+    socket_path = root / "generation.sock"
+    generation_log = root / "generation.jsonl"
+    pi_log = root / "pi.jsonl"
+    extension = root / "d4_extension.ts"
+    write_extension(extension)
+    broker: subprocess.Popen[str] | None = None
+    pi: PiRpc | None = None
+
+    try:
+        environment = isolated_environment(root, index, workspace, socket_path, pi_log)
+        # Must run before the fixture broker or Pi process is launched. It proves
+        # the launcher registers before exec and can only read this fixture socket.
+        closure = gated_launcher_precondition(root, socket_path, environment)
+        broker = launch_verified_broker(
+            closure.broker, closure.generation, socket_path, generation_log, environment
+        )
+        wait_path(socket_path)
+        pi = launch_verified_pi(closure.launcher, workspace, sessions, extension, environment)
+        pi.send({"id": "state", "type": "get_state"})
+        state = pi.response("state")
+        original_session = state["data"]["sessionFile"]
+        pi.prompt_and_settle(
+            "fixture-promote",
+            "Call d4_fixture_promote exactly once, then stop.",
+        )
+        pi.send({"id": "reload", "type": "prompt", "message": "/d4-reload"})
+        reload_response = pi.response("reload")
+        if not reload_response.get("success"):
+            raise RuntimeError(f"reload failed: {reload_response}")
+        for request_id, request_payload in [
+            ("clone", {"id": "clone", "type": "clone"}),
+            ("new", {"id": "new", "type": "new_session"}),
+            (
+                "resume",
+                {"id": "resume", "type": "switch_session", "sessionPath": original_session},
+            ),
+        ]:
+            pi.send(request_payload)
+            response = pi.response(request_id)
+            if not response.get("success") or response.get("data", {}).get("cancelled"):
+                raise RuntimeError(f"{request_id} failed: {response}")
+        results = assert_d4(jsonl(generation_log))
+        verdict = results.get("machine_assertions")
+        if verdict != "PASS":
+            raise RuntimeError(f"D4 checks did not derive PASS: {verdict}")
+        (root / "machine-assertions.json").write_text(
+            json.dumps(results, sort_keys=True, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        print(f"run={index} evidence_dir={root}")
+        print(f"machine_assertions={verdict}")
+        print(json.dumps(results, sort_keys=True))
+    except Exception as error:
+        (root / "machine-assertions.json").write_text(
+            json.dumps({"error": f"{type(error).__name__}: {error}"}, sort_keys=True, indent=2)
+            + "\n",
+            encoding="utf-8",
+        )
+        print(f"run={index} evidence_dir={root}")
+        print("machine_assertions=FAIL")
+        print(f"error={type(error).__name__}: {error}")
+        raise
+    finally:
+        try:
+            try:
+                if pi is not None:
+                    pi.close()
+            finally:
+                if broker is not None:
+                    try:
+                        request(socket_path, {"action": "shutdown-broker"})
+                    except OSError:
+                        pass
+                    try:
+                        broker.wait(timeout=5)
+                    except subprocess.TimeoutExpired:
+                        broker.kill()
+                        broker.wait()
+        finally:
+            scrub_fixture_credentials(root)
+    return root
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--runs", type=int, default=3, choices=(3,))
+    args = parser.parse_args()
+    roots: list[Path] = []
+    for index in range(1, args.runs + 1):
+        roots.append(run_once(index))
+    print("d4_isolation_runs=" + ",".join(str(root) for root in roots))
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p3_generation_broker.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""P3 broker prototype: peercred-keyed runtime_generation and lease revocation."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+import secrets
+import socket
+import struct
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+
+def proc_starttime(pid: int) -> int:
+    text = Path(f"/proc/{pid}/stat").read_text()
+    close = text.rfind(")")
+    return int(text[close + 2 :].split()[19])
+
+
+def emit(log: Path, value: dict[str, Any]) -> None:
+    with log.open("a", encoding="utf-8") as out:
+        out.write(json.dumps(value, sort_keys=True) + "\n")
+
+
+def load_generation_functions(
+    path: Path,
+) -> tuple[Callable[[Mapping[str, str]], int], Callable[[Mapping[str, str]], int]]:
+    spec = importlib.util.spec_from_file_location("d4_lease_generation", path)
+    if spec is None or spec.loader is None:
+        raise ValueError("generation module is unavailable")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    reader = getattr(module, "read_runtime_generation", None)
+    bumper = getattr(module, "bump_runtime_generation", None)
+    if not callable(reader) or not callable(bumper):
+        raise ValueError("generation module has no read/bump functions")
+    return reader, bumper
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--socket", required=True)
+    parser.add_argument("--log", required=True)
+    parser.add_argument("--generation-module", required=True, type=Path)
+    ns = parser.parse_args()
+    socket_path = Path(ns.socket)
+    log_path = Path(ns.log)
+    read_runtime_generation, bump_runtime_generation = load_generation_functions(
+        ns.generation_module
+    )
+    socket_path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(socket_path.parent, 0o700)
+    socket_path.unlink(missing_ok=True)
+    log_path.unlink(missing_ok=True)
+
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    server.bind(str(socket_path))
+    os.chmod(socket_path, 0o600)
+    server.listen(8)
+    generations: dict[tuple[int, int], int] = {}
+    lease_state: dict[tuple[int, int], str] = {}
+    # The gated launcher registers its own exec-preserved PID here.  This is
+    # deliberately volatile fixture state; nothing is written outside root.
+    launcher_sessions: dict[tuple[int, int], str] = {}
+    generation_files: dict[tuple[int, int], Path] = {}
+
+    def generation_environment(identity: tuple[int, int]) -> dict[str, str]:
+        state_path = generation_files.get(identity)
+        if state_path is None or state_path.parent != socket_path.parent:
+            raise ValueError("generation file is outside the fixture root")
+        return {"MOSAIC_LEASE_GENERATION_FILE": str(state_path)}
+
+    def file_generation(identity: tuple[int, int]) -> int:
+        return read_runtime_generation(generation_environment(identity))
+
+    emit(log_path, {"event": "listen", "pid": os.getpid(), "socket": str(socket_path)})
+
+    while True:
+        conn, _ = server.accept()
+        with conn:
+            raw = conn.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, 12)
+            pid, uid, gid = struct.unpack("3i", raw)
+            starttime = proc_starttime(pid)
+            request = json.loads(conn.makefile("r", encoding="utf-8").readline())
+            if request.get("action") == "shutdown-broker":
+                conn.sendall(b'{"ok":true}\n')
+                break
+            identity = (pid, starttime)
+            if request.get("action") == "register_anchor":
+                generation = request.get("runtime_generation")
+                if type(generation) is not int or generation < 0:
+                    conn.sendall(b'{"ok":false,"code":"INVALID_GENERATION"}\n')
+                    continue
+                session_id = launcher_sessions.setdefault(identity, secrets.token_hex(32))
+                generation_file = socket_path.parent / f"generation-{session_id}.state"
+                generation_files[identity] = generation_file
+                record = {
+                    "event": "lease_anchor_registered",
+                    "peercred": {"pid": pid, "uid": uid, "gid": gid},
+                    "starttime_ticks": starttime,
+                    "runtime_generation": generation,
+                    "session_id_shape": "hex-256",
+                    "generation_file": str(generation_file),
+                }
+                emit(log_path, record)
+                reply = {
+                    "ok": True,
+                    "session_id": session_id,
+                    "peer": {"pid": pid, "uid": uid, "gid": gid, "starttime": str(starttime)},
+                }
+                conn.sendall((json.dumps(reply, sort_keys=True) + "\n").encode())
+                continue
+            # The D4 extension requests this at each post-start lifecycle
+            # boundary; the exact WI-3 helper mutates the launcher-created file.
+            if request.get("action") == "bump-generation":
+                generation = bump_runtime_generation(generation_environment(identity))
+                record = {
+                    "event": "generation_state_bumped",
+                    "peercred": {"pid": pid, "uid": uid, "gid": gid},
+                    "starttime_ticks": starttime,
+                    "generation": generation,
+                    "generation_file": str(generation_files[identity]),
+                    "generation_source": "state-file",
+                }
+                emit(log_path, record)
+                conn.sendall((json.dumps(record, sort_keys=True) + "\n").encode())
+                continue
+            if request.get("action") == "promote-probe":
+                generation = file_generation(identity)
+                lease_state[identity] = "VERIFIED"
+                record = {
+                    "event": "probe_lease_promoted",
+                    "peercred": {"pid": pid, "uid": uid, "gid": gid},
+                    "starttime_ticks": starttime,
+                    "generation": generation,
+                    "generation_file": str(generation_files[identity]),
+                    "generation_source": "state-file",
+                    "new_lease_state": "VERIFIED",
+                }
+                emit(log_path, record)
+                conn.sendall((json.dumps(record, sort_keys=True) + "\n").encode())
+                continue
+            # D4 fixture-only authorization observation.  It exposes the broker's
+            # current versus superseded generation disposition without changing it.
+            if request.get("action") == "authorize-probe":
+                generation = request.get("generation")
+                if type(generation) is not int or generation < 0:
+                    conn.sendall(b'{"ok":false,"code":"INVALID_GENERATION"}\n')
+                    continue
+                current_generation = file_generation(identity)
+                current_lease = lease_state.get(identity, "NONE")
+                if generation < current_generation:
+                    code = "STALE_GENERATION"
+                elif generation > current_generation:
+                    code = "FUTURE_GENERATION"
+                elif current_lease != "VERIFIED":
+                    code = "MUTATOR_UNVERIFIED"
+                else:
+                    code = "ALLOW"
+                record = {
+                    "event": "generation_authorization",
+                    "peercred": {"pid": pid, "uid": uid, "gid": gid},
+                    "starttime_ticks": starttime,
+                    "requested_generation": generation,
+                    "current_generation": current_generation,
+                    "generation_file": str(generation_files[identity]),
+                    "generation_source": "state-file",
+                    "lease_state": current_lease,
+                    "ok": code == "ALLOW",
+                    "code": code,
+                }
+                emit(log_path, record)
+                conn.sendall((json.dumps(record, sort_keys=True) + "\n").encode())
+                continue
+            if request.get("action") != "lifecycle":
+                conn.sendall(b'{"ok":false,"reason":"invalid-action"}\n')
+                continue
+
+            old_generation = generations.get(identity, 0)
+            old_lease = lease_state.get(identity, "NONE")
+            new_generation = file_generation(identity)
+            if new_generation <= old_generation:
+                conn.sendall(b'{"ok":false,"code":"NON_MONOTONIC_STATE_FILE"}\n')
+                continue
+            generations[identity] = new_generation
+            # Every lifecycle boundary revokes first. A start establishes a new
+            # UNVERIFIED incarnation; it never inherits prior VERIFIED state.
+            lease_state[identity] = "UNVERIFIED" if request.get("phase") == "start" else "REVOKED"
+            record = {
+                "event": "runtime_generation_bump",
+                "peercred": {"pid": pid, "uid": uid, "gid": gid},
+                "starttime_ticks": starttime,
+                "phase": request.get("phase"),
+                "reason": request.get("reason"),
+                "old_generation": old_generation,
+                "new_generation": new_generation,
+                "generation_file": str(generation_files[identity]),
+                "generation_source": "state-file",
+                "prior_lease": old_lease,
+                "prior_lease_revoked": True,
+                "new_lease_state": lease_state[identity],
+            }
+            emit(log_path, record)
+            conn.sendall((json.dumps(record, sort_keys=True) + "\n").encode())
+
+    server.close()
+    socket_path.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p4_peercred_probe.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Gate0 P4: exercise Linux SO_PEERCRED and correlate it to /proc."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import stat
+import tempfile
+from pathlib import Path
+
+
+def proc_identity(pid: int) -> dict[str, int | str]:
+    stat_text = Path(f"/proc/{pid}/stat").read_text()
+    close = stat_text.rfind(")")
+    fields = stat_text[close + 2 :].split()
+    # fields[0] is field 3 (state); ppid is field 4 and starttime is field 22.
+    return {
+        "pid": pid,
+        "ppid": int(fields[1]),
+        "starttime_ticks": int(fields[19]),
+        "uid": int(Path(f"/proc/{pid}/status").read_text().split("Uid:", 1)[1].split()[0]),
+        "exe": os.readlink(f"/proc/{pid}/exe"),
+    }
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory(prefix="gate0-p4-") as tmp:
+        root = Path(tmp)
+        os.chmod(root, 0o700)
+        socket_path = root / "broker.sock"
+        server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        server.bind(str(socket_path))
+        os.chmod(socket_path, 0o600)
+        server.listen(1)
+
+        child = os.fork()
+        if child == 0:
+            client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            client.connect(str(socket_path))
+            identity = proc_identity(os.getpid())
+            client.sendall((json.dumps(identity, sort_keys=True) + "\n").encode())
+            # Keep /proc/<pid> alive until the server has correlated peercred.
+            if client.recv(2) != b"OK":
+                os._exit(2)
+            client.close()
+            os._exit(0)
+
+        conn, _ = server.accept()
+        raw = conn.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, 12)
+        peer_pid = int.from_bytes(raw[0:4], byteorder="little", signed=True)
+        peer_uid = int.from_bytes(raw[4:8], byteorder="little", signed=True)
+        peer_gid = int.from_bytes(raw[8:12], byteorder="little", signed=True)
+        claimed = json.loads(conn.makefile("r", encoding="utf-8").readline())
+        observed = proc_identity(peer_pid)
+        conn.sendall(b"OK")
+        _, status = os.waitpid(child, 0)
+
+        root_mode = stat.S_IMODE(root.stat().st_mode)
+        socket_mode = stat.S_IMODE(socket_path.stat().st_mode)
+        if not (
+            peer_pid == claimed["pid"] == observed["pid"]
+            and peer_uid == claimed["uid"] == observed["uid"]
+            and claimed["starttime_ticks"] == observed["starttime_ticks"]
+            and root_mode == 0o700
+            and socket_mode == 0o600
+            and os.waitstatus_to_exitcode(status) == 0
+        ):
+            raise AssertionError("SO_PEERCRED, /proc identity, or socket-mode correlation failed")
+        print("machine_assertions=PASS")
+        print(f"server_pid={os.getpid()} server_uid={os.getuid()} server_gid={os.getgid()}")
+        print(f"socket_path={socket_path}")
+        print(f"directory_mode={root_mode:04o} socket_mode={socket_mode:04o}")
+        print(f"SO_PEERCRED pid={peer_pid} uid={peer_uid} gid={peer_gid}")
+        print("client_claim=" + json.dumps(claimed, sort_keys=True))
+        print("proc_observed=" + json.dumps(observed, sort_keys=True))
+        print(f"pid_match={peer_pid == claimed['pid'] == observed['pid']}")
+        print(f"uid_match={peer_uid == claimed['uid'] == observed['uid']}")
+        print(
+            "starttime_match="
+            + str(claimed["starttime_ticks"] == observed["starttime_ticks"])
+        )
+        print(f"client_exit_status={os.waitstatus_to_exitcode(status)}")
+        print("same_principal_socket=true")
+        print(
+            "posture=0700 parent + 0600 socket excludes other UIDs, but does not prevent "
+            "the same UID from unlinking/rebinding; distinct-principal system service remains "
+            "required for a claim stronger than T-C against same-UID counterfeit replacement"
+        )
+
+        conn.close()
+        server.close()
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p6_claude_hook.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Claude SessionStart additionalContext producer for P6 observation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+BLOCK = "\n".join(
+    [
+        "GATE0_CLAUDE_ATOMIC_BEGIN",
+        "segment-01=alpha-2d11",
+        "segment-02=middle-8e22",
+        "segment-03=omega-4f33",
+        "GATE0_CLAUDE_ATOMIC_END",
+    ]
+)
+
+
+def starttime(pid: int) -> int:
+    text = Path(f"/proc/{pid}/stat").read_text()
+    return int(text[text.rfind(")") + 2 :].split()[19])
+
+
+def main() -> None:
+    hook_input = json.load(sys.stdin)
+    log = Path(os.environ["GATE0_CLAUDE_HOOK_LOG"])
+    record = {
+        "hook_event_name": hook_input.get("hook_event_name"),
+        "pid": os.getpid(),
+        "ppid": os.getppid(),
+        "starttime_ticks": starttime(os.getpid()),
+        "block_length": len(BLOCK.encode()),
+        "block_sha256": hashlib.sha256(BLOCK.encode()).hexdigest(),
+        "emission": "one hookSpecificOutput.additionalContext string field",
+    }
+    log.write_text(json.dumps(record, sort_keys=True) + "\n")
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "SessionStart",
+                    "additionalContext": BLOCK,
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/p6_claude_run.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Run real Claude 2.1.x through `mosaic yolo` for P6 observation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+HERE = Path(__file__).resolve().parent
+BLOCK = "\n".join(
+    [
+        "GATE0_CLAUDE_ATOMIC_BEGIN",
+        "segment-01=alpha-2d11",
+        "segment-02=middle-8e22",
+        "segment-03=omega-4f33",
+        "GATE0_CLAUDE_ATOMIC_END",
+    ]
+)
+
+
+def strings(value: Any):
+    if isinstance(value, str):
+        yield value
+    elif isinstance(value, list):
+        for item in value:
+            yield from strings(item)
+    elif isinstance(value, dict):
+        for item in value.values():
+            yield from strings(item)
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory(prefix="gate0-p6-claude-") as temp:
+        root = Path(temp)
+        workspace = root / "workspace"
+        workspace.mkdir()
+        settings = root / "settings.json"
+        hook_log = root / "hook.jsonl"
+        settings.write_text(
+            json.dumps(
+                {
+                    "hooks": {
+                        "SessionStart": [
+                            {
+                                "hooks": [
+                                    {
+                                        "type": "command",
+                                        "command": f'python3 "{HERE / "p6_claude_hook.py"}"',
+                                        "timeout": 20,
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                }
+            )
+        )
+        env = os.environ.copy()
+        env["GATE0_CLAUDE_HOOK_LOG"] = str(hook_log)
+        command = [
+            "mosaic",
+            "yolo",
+            "claude",
+            "--settings",
+            str(settings),
+            "--model",
+            "haiku",
+            "--print",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--include-hook-events",
+            "--max-budget-usd",
+            "0.10",
+            "Return only the exact full GATE0_CLAUDE_ATOMIC_BEGIN through GATE0_CLAUDE_ATOMIC_END block injected by SessionStart, with no code fence or commentary.",
+        ]
+        result = subprocess.run(
+            command,
+            cwd=workspace,
+            env=env,
+            stdin=subprocess.DEVNULL,
+            text=True,
+            capture_output=True,
+            timeout=150,
+            check=False,
+        )
+        events: list[dict[str, Any]] = []
+        for line in result.stdout.splitlines():
+            try:
+                events.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        hook_events = [
+            event
+            for event in events
+            if event.get("type") == "system"
+            and event.get("subtype") in {"hook_started", "hook_response"}
+        ]
+        full_matches = [text for event in events for text in strings(event) if BLOCK in text]
+        exact_matches = [text for event in events for text in strings(event) if text == BLOCK]
+        assistant_texts: list[str] = []
+        for event in events:
+            if event.get("type") != "assistant":
+                continue
+            for text in strings(event.get("message", {})):
+                if "GATE0_CLAUDE_ATOMIC_BEGIN" in text:
+                    assistant_texts.append(text)
+
+        if result.returncode != 0:
+            raise AssertionError(f"Claude probe exited {result.returncode}")
+        if not any(event.get("subtype") == "hook_response" and event.get("outcome") == "success" for event in hook_events):
+            raise AssertionError("Claude SessionStart hook did not complete successfully")
+        if BLOCK not in exact_matches:
+            raise AssertionError("Claude did not return an exact full-block field")
+
+        print("$ python3 docs/compaction-refresh/probes/p6_claude_run.py")
+        print("machine_assertions=PASS")
+        print("command=mosaic yolo claude --settings <isolated> --model haiku --print --output-format stream-json --verbose --include-hook-events <prompt>")
+        print("claude_version=" + subprocess.check_output(["claude", "--version"], text=True).strip())
+        print("mosaic_version=" + subprocess.check_output(["mosaic", "--version"], text=True).strip())
+        print(f"exit_code={result.returncode}")
+        print("hook_process_log=" + hook_log.read_text().strip())
+        for event in hook_events:
+            print("hook_stream_event=" + json.dumps(event, sort_keys=True))
+        print(f"block_length={len(BLOCK.encode())}")
+        print(f"block_sha256={hashlib.sha256(BLOCK.encode()).hexdigest()}")
+        print(f"stream_fields_containing_full_block={len(full_matches)}")
+        print(f"stream_fields_exactly_equal_block={len(exact_matches)}")
+        for text in assistant_texts:
+            print(f"assistant_copy_length={len(text.encode())}")
+            print(f"assistant_copy_sha256={hashlib.sha256(text.encode()).hexdigest()}")
+            print(f"assistant_copy_exact={text == BLOCK}")
+            print("assistant_copy=" + json.dumps(text))
+        if result.stderr.strip():
+            print("stderr_excerpt=" + json.dumps(result.stderr.splitlines()[:10]))
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/pi_gate0_extension.ts

@@ -0,0 +1,350 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, appendFileSync, statSync } from 'node:fs';
+import net from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+const SELF = resolve(fileURLToPath(import.meta.url).split('?')[0]!);
+const LOG = process.env['GATE0_PI_LOG'];
+const CONTEXT_BLOCK =
+  process.env['GATE0_PI_CONTEXT_BLOCK'] ??
+  [
+    'GATE0_PI_ATOMIC_BEGIN',
+    'segment-01=alpha-7e31',
+    'segment-02=middle-9c42',
+    'segment-03=omega-5b83',
+    'GATE0_PI_ATOMIC_END',
+  ].join('\n');
+
+let sequence = 0;
+
+function sha(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function procStarttime(): number {
+  const text = readFileSync(`/proc/${process.pid}/stat`, 'utf8');
+  const close = text.lastIndexOf(')');
+  const fields = text.slice(close + 2).trim().split(/\s+/);
+  return Number(fields[19]);
+}
+
+function log(event: string, details: Record<string, unknown> = {}): void {
+  if (!LOG) return;
+  sequence += 1;
+  appendFileSync(
+    LOG,
+    `${JSON.stringify({ seq: sequence, event, pid: process.pid, starttime_ticks: procStarttime(), ...details })}\n`,
+  );
+}
+
+function argvExtensions(): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < process.argv.length; i += 1) {
+    if (process.argv[i] === '--extension' || process.argv[i] === '-e') {
+      const candidate = process.argv[i + 1];
+      if (candidate) result.push(resolve(candidate));
+    }
+  }
+  return result;
+}
+
+interface SourceValidation {
+  ok: boolean;
+  reason: string;
+  fragment?: string;
+}
+
+function validateSources(): SourceValidation {
+  const manifestPath = process.env['GATE0_SOURCE_MANIFEST'];
+  if (!manifestPath) return { ok: true, reason: 'no-manifest-probe-disabled' };
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
+      maxBytes: number;
+      fragments: Array<{ path: string; sha256: string }>;
+    };
+    for (const fragment of manifest.fragments) {
+      let fileStat;
+      try {
+        fileStat = statSync(fragment.path);
+      } catch {
+        return { ok: false, reason: 'missing', fragment: fragment.path };
+      }
+      if (!fileStat.isFile()) {
+        return { ok: false, reason: 'not-regular-file', fragment: fragment.path };
+      }
+      if (fileStat.size > manifest.maxBytes) {
+        return { ok: false, reason: 'oversize', fragment: fragment.path };
+      }
+      const bytes = readFileSync(fragment.path);
+      if (sha(bytes) !== fragment.sha256) {
+        return { ok: false, reason: 'hash-mismatch', fragment: fragment.path };
+      }
+    }
+    return { ok: true, reason: 'all-fragments-valid' };
+  } catch (error) {
+    return { ok: false, reason: `manifest-error:${error instanceof Error ? error.name : 'unknown'}` };
+  }
+}
+
+function brokerRequest(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const socketPath = process.env['GATE0_GENERATION_SOCKET'];
+  if (!socketPath) return Promise.resolve({ skipped: true });
+  return new Promise((resolvePromise, reject) => {
+    const socket = net.createConnection(socketPath);
+    let buffer = '';
+    socket.setEncoding('utf8');
+    socket.on('connect', () => socket.write(`${JSON.stringify(payload)}\n`));
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) return;
+      socket.end();
+      resolvePromise(JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>);
+    });
+    socket.on('error', reject);
+  });
+}
+
+function markerPaths(value: unknown, path = '$'): string[] {
+  const matches: string[] = [];
+  if (typeof value === 'string') {
+    if (value.includes(CONTEXT_BLOCK)) matches.push(path);
+    return matches;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => matches.push(...markerPaths(item, `${path}[${index}]`)));
+    return matches;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      matches.push(...markerPaths(item, `${path}.${key}`));
+    }
+  }
+  return matches;
+}
+
+function assistantToolIds(message: unknown): string[] {
+  if (!message || typeof message !== 'object') return [];
+  const candidate = message as { role?: string; content?: unknown };
+  if (candidate.role !== 'assistant' || !Array.isArray(candidate.content)) return [];
+  return candidate.content
+    .filter(
+      (block): block is { type: 'toolCall'; id: string } =>
+        Boolean(
+          block &&
+            typeof block === 'object' &&
+            (block as { type?: string }).type === 'toolCall' &&
+            typeof (block as { id?: unknown }).id === 'string',
+        ),
+    )
+    .map((block) => block.id);
+}
+
+function assistantText(message: unknown): string {
+  if (!message || typeof message !== 'object') return '';
+  const candidate = message as { role?: string; content?: unknown };
+  if (candidate.role !== 'assistant' || !Array.isArray(candidate.content)) return '';
+  return candidate.content
+    .filter(
+      (block): block is { type: 'text'; text: string } =>
+        Boolean(
+          block &&
+            typeof block === 'object' &&
+            (block as { type?: string }).type === 'text' &&
+            typeof (block as { text?: unknown }).text === 'string',
+        ),
+    )
+    .map((block) => block.text)
+    .join('');
+}
+
+export default function register(pi: ExtensionAPI) {
+  const localProviderUrl = process.env['GATE0_LOCAL_PROVIDER_URL'];
+  if (localProviderUrl) {
+    pi.registerProvider('gate0-local', {
+      baseUrl: localProviderUrl,
+      apiKey: 'gate0-probe-not-a-secret',
+      api: 'openai-completions',
+      models: [
+        {
+          id: 'gate0-model',
+          name: 'Gate0 deterministic local model',
+          reasoning: false,
+          input: ['text'],
+          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+          contextWindow: 32_000,
+          maxTokens: 1_024,
+        },
+      ],
+    });
+  }
+
+  const extensions = argvExtensions();
+  const lastPosition = extensions.length > 0 && extensions.at(-1) === SELF;
+  interface RequestCycle {
+    nonce: string;
+    verified: boolean;
+    sourceReason: string;
+  }
+  let buildingCycle: RequestCycle | undefined;
+  const inFlightCycles: RequestCycle[] = [];
+  const toolNonce = new Map<string, { nonce: string; verified: boolean; sourceReason: string }>();
+
+  pi.on('session_start', async (event) => {
+    const broker = await brokerRequest({ action: 'lifecycle', phase: 'start', reason: event.reason });
+    log('session_start', {
+      reason: event.reason,
+      extensions,
+      self: SELF,
+      lastPosition,
+      gateState: lastPosition ? 'UNVERIFIED_READY' : 'CLOSED_NOT_LAST',
+      broker,
+    });
+  });
+
+  pi.on('session_shutdown', async (event) => {
+    const broker = await brokerRequest({ action: 'lifecycle', phase: 'shutdown', reason: event.reason });
+    log('session_shutdown', { reason: event.reason, broker });
+  });
+
+  pi.on('context', async (event) => {
+    const validation = validateSources();
+    buildingCycle = {
+      nonce: randomUUID(),
+      sourceReason: validation.reason,
+      verified: lastPosition && validation.ok,
+    };
+    const inputJson = JSON.stringify(event.messages);
+    const injected = {
+      role: 'custom' as const,
+      customType: 'gate0-context',
+      content: CONTEXT_BLOCK,
+      display: false,
+      timestamp: Date.now(),
+    };
+    const outputMessages = buildingCycle.verified
+      ? [...event.messages, injected]
+      : [...event.messages];
+    const outputPrefix = outputMessages.slice(0, event.messages.length);
+    const sourceBroker = validation.ok
+      ? { action: 'none', reason: 'source-valid' }
+      : await brokerRequest({ action: 'source-invalid', reason: validation.reason });
+    log('context_return', {
+      requestNonce: buildingCycle.nonce,
+      sourceValidation: validation,
+      sourceBroker,
+      lastPosition,
+      promotion: false,
+      injectionDecision: buildingCycle.verified ? 'ONE_ATOMIC_AGENT_MESSAGE' : 'REFUSED',
+      inputCount: event.messages.length,
+      outputCount: outputMessages.length,
+      prefixHashBefore: sha(inputJson),
+      prefixHashAfter: sha(JSON.stringify(outputPrefix)),
+      prefixPreservedByReturn: sha(inputJson) === sha(JSON.stringify(outputPrefix)),
+      blockLength: CONTEXT_BLOCK.length,
+      blockSha256: sha(CONTEXT_BLOCK),
+    });
+    return { messages: outputMessages };
+  });
+
+  pi.on('before_provider_request', async (event) => {
+    const paths = markerPaths(event.payload);
+    const cycle = buildingCycle;
+    buildingCycle = undefined;
+    if (cycle) inFlightCycles.push(cycle);
+    log('before_provider_request', {
+      requestNonce: cycle?.nonce,
+      inFlightDepth: inFlightCycles.length,
+      markerOccurrences: paths.length,
+      markerPaths: paths,
+      finalPayloadValid: Boolean(cycle?.verified && paths.length === 1),
+    });
+  });
+
+  pi.on('after_provider_response', async (event) => {
+    const cycle = inFlightCycles[0];
+    log('after_provider_response', {
+      requestNonce: cycle?.nonce,
+      status: event.status,
+      assistantContentAvailableAtThisHook: false,
+      timing: 'headers/status before stream consumption',
+    });
+  });
+
+  pi.on('message_end', async (event) => {
+    const role = (event.message as { role?: string }).role;
+    const ids = assistantToolIds(event.message);
+    const text = assistantText(event.message);
+    const cycle = role === 'assistant' ? inFlightCycles.shift() : undefined;
+    if (ids.length > 0 && cycle) {
+      for (const id of ids) {
+        toolNonce.set(id, {
+          nonce: cycle.nonce,
+          verified: cycle.verified,
+          sourceReason: cycle.sourceReason,
+        });
+      }
+    }
+    log('message_end', {
+      role,
+      assistantContentObserved: role === 'assistant',
+      requestNonce: cycle?.nonce,
+      inFlightDepthAfter: inFlightCycles.length,
+      toolCallIds: ids,
+      nonceMappings: ids.map((id) => ({ toolCallId: id, requestNonce: cycle?.nonce })),
+      exactContextBlockCopied: text.includes(CONTEXT_BLOCK),
+      assistantTextSha256: text ? sha(text) : null,
+    });
+  });
+
+  pi.on('tool_call', async (event) => {
+    const mapping = toolNonce.get(event.toolCallId);
+    const allowed = Boolean(lastPosition && mapping?.verified);
+    log('tool_call', {
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      mapping: mapping ?? null,
+      allowed,
+      reason: !lastPosition
+        ? 'closed-not-last'
+        : !mapping
+          ? 'unknown-tool-call-id'
+          : !mapping.verified
+            ? `unverified-source:${mapping.sourceReason}`
+            : 'exact-tool-call-id-mapped-to-verified-request-nonce',
+    });
+    if (!allowed) return { block: true, reason: 'Gate0 probe refused unverified tool batch' };
+  });
+
+  pi.on('agent_settled', async () => {
+    log('agent_settled', { retainedNonceMappingsBeforeClear: toolNonce.size });
+    toolNonce.clear();
+  });
+
+  pi.registerTool({
+    name: 'gate0_nonce_probe',
+    label: 'Gate0 Nonce Probe',
+    description: 'Gate0-only harmless tool used to prove toolCallId to request-nonce correlation.',
+    parameters: Type.Object({ label: Type.String() }),
+    async execute(toolCallId, params) {
+      const broker = await brokerRequest({ action: 'promote-probe' });
+      log('tool_execute', { toolCallId, label: params.label, broker });
+      return {
+        content: [{ type: 'text', text: `gate0_nonce_probe executed for ${params.label}` }],
+        details: { harmless: true },
+      };
+    },
+  });
+
+  pi.registerCommand('gate0-reload', {
+    description: 'Trigger a real same-PID Pi extension/runtime reload.',
+    handler: async (_args, ctx) => {
+      log('reload_command_before');
+      await ctx.reload();
+      return;
+    },
+  });
+}

docs/compaction-refresh/probes/pi_gate0_run.py

@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+"""Drive real Pi 0.80.x RPC for P2/P3/P5/P6 runtime evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import queue
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+HERE = Path(__file__).resolve().parent
+BLOCK = "\n".join(
+    [
+        "GATE0_PI_ATOMIC_BEGIN",
+        "segment-01=alpha-7e31",
+        "segment-02=middle-9c42",
+        "segment-03=omega-5b83",
+        "GATE0_PI_ATOMIC_END",
+    ]
+)
+
+
+def wait_path(path: Path, timeout: float = 20) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if path.exists():
+            return
+        time.sleep(0.05)
+    raise TimeoutError(f"timed out waiting for {path}")
+
+
+def socket_request(path: Path, payload: dict[str, object]) -> None:
+    conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    conn.connect(str(path))
+    conn.sendall((json.dumps(payload) + "\n").encode())
+    conn.makefile("r", encoding="utf-8").readline()
+    conn.close()
+
+
+def jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text().splitlines() if line]
+
+
+class PiRpc:
+    def __init__(self, command: list[str], cwd: Path, env: dict[str, str]):
+        self.process = subprocess.Popen(
+            command,
+            cwd=cwd,
+            env=env,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+            start_new_session=True,
+        )
+        self.events: queue.Queue[dict[str, Any]] = queue.Queue()
+        self.raw_lines: list[str] = []
+        self.stderr_lines: list[str] = []
+        threading.Thread(target=self._read_stdout, daemon=True).start()
+        threading.Thread(target=self._read_stderr, daemon=True).start()
+
+    def _read_stdout(self) -> None:
+        assert self.process.stdout is not None
+        for line in self.process.stdout:
+            stripped = line.rstrip("\n")
+            self.raw_lines.append(stripped)
+            try:
+                event = json.loads(stripped)
+            except json.JSONDecodeError:
+                continue
+            self.events.put(event)
+
+    def _read_stderr(self) -> None:
+        assert self.process.stderr is not None
+        for line in self.process.stderr:
+            self.stderr_lines.append(line.rstrip("\n"))
+
+    def send(self, payload: dict[str, object]) -> None:
+        assert self.process.stdin is not None
+        self.process.stdin.write(json.dumps(payload) + "\n")
+        self.process.stdin.flush()
+
+    def wait(self, predicate: Callable[[dict[str, Any]], bool], description: str, timeout: float = 180) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self.process.poll() is not None and self.events.empty():
+                raise RuntimeError(
+                    f"Pi exited {self.process.returncode} while waiting for {description}: "
+                    + " | ".join(self.stderr_lines[-5:])
+                )
+            try:
+                event = self.events.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            if predicate(event):
+                return event
+        raise TimeoutError(f"timed out waiting for {description}")
+
+    def response(self, request_id: str, timeout: float = 180) -> dict[str, Any]:
+        return self.wait(
+            lambda event: event.get("type") == "response" and event.get("id") == request_id,
+            f"response {request_id}",
+            timeout,
+        )
+
+    def prompt_and_settle(self, request_id: str, message: str) -> None:
+        self.send({"id": request_id, "type": "prompt", "message": message})
+        response = self.response(request_id)
+        if not response.get("success"):
+            raise RuntimeError(f"prompt rejected: {response}")
+        self.wait(lambda event: event.get("type") == "agent_settled", f"agent_settled {request_id}")
+
+    def close(self) -> None:
+        if self.process.poll() is None:
+            try:
+                os.killpg(self.process.pid, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+            try:
+                self.process.wait(timeout=8)
+            except subprocess.TimeoutExpired:
+                os.killpg(self.process.pid, signal.SIGKILL)
+                self.process.wait(timeout=5)
+
+
+def manifest(path: Path, fragment: Path, expected_hash: str, max_bytes: int = 64) -> None:
+    path.write_text(
+        json.dumps(
+            {
+                "maxBytes": max_bytes,
+                "fragments": [{"path": str(fragment), "sha256": expected_hash}],
+            },
+            sort_keys=True,
+        )
+    )
+
+
+def run_open(root: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str], list[str]]:
+    workspace = root / "workspace"
+    workspace.mkdir()
+    session_dir = root / "sessions"
+    session_dir.mkdir()
+    pi_log = root / "pi-hooks.jsonl"
+    generation_log = root / "generation.jsonl"
+    generation_socket = root / "generation.sock"
+    source_manifest = root / "manifest.json"
+    valid_fragment = root / "fragment.md"
+    valid_fragment.write_text("NORMATIVE-FRAGMENT-v1\n")
+    expected = hashlib.sha256(valid_fragment.read_bytes()).hexdigest()
+    manifest(source_manifest, valid_fragment, expected)
+
+    broker = subprocess.Popen(
+        [
+            sys.executable,
+            str(HERE / "p3_generation_broker.py"),
+            "--socket",
+            str(generation_socket),
+            "--log",
+            str(generation_log),
+        ],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    wait_path(generation_socket)
+    env = os.environ.copy()
+    env.update(
+        {
+            "GATE0_PI_LOG": str(pi_log),
+            "GATE0_GENERATION_SOCKET": str(generation_socket),
+            "GATE0_SOURCE_MANIFEST": str(source_manifest),
+            "GATE0_PI_CONTEXT_BLOCK": BLOCK,
+            "MOSAIC_PI_FORCE_SKILLS": "",
+            "PI_SKIP_VERSION_CHECK": "1",
+        }
+    )
+    command = [
+        "mosaic",
+        "yolo",
+        "pi",
+        "--mode",
+        "rpc",
+        "--session-dir",
+        str(session_dir),
+        "--no-extensions",
+        "--no-context-files",
+        "--no-prompt-templates",
+        "--model",
+        "openai-codex/gpt-5.6-sol",
+        "--thinking",
+        "medium",
+        "--extension",
+        str(HERE / "pi_gate0_extension.ts"),
+    ]
+    pi = PiRpc(command, workspace, env)
+    try:
+        pi.send({"id": "state-0", "type": "get_state"})
+        state0 = pi.response("state-0")
+        original_session = state0["data"]["sessionFile"]
+
+        pi.prompt_and_settle(
+            "p2",
+            "Call gate0_nonce_probe exactly once with label p2. After the tool finishes, copy the exact full GATE0_PI_ATOMIC_BEGIN through GATE0_PI_ATOMIC_END block from context, with no commentary.",
+        )
+
+        # P3 immediately follows the valid P2 promotion so reload must revoke a
+        # genuinely VERIFIED prior generation, not an already-invalid source run.
+        pi.send({"id": "reload", "type": "prompt", "message": "/gate0-reload"})
+        reload_response = pi.response("reload")
+        if not reload_response.get("success"):
+            raise RuntimeError(f"reload command failed: {reload_response}")
+
+        pi.send({"id": "clone", "type": "clone"})
+        clone_response = pi.response("clone")
+        if not clone_response.get("success") or clone_response.get("data", {}).get("cancelled"):
+            raise RuntimeError(f"clone failed: {clone_response}")
+
+        pi.send({"id": "new", "type": "new_session"})
+        new_response = pi.response("new")
+        if not new_response.get("success") or new_response.get("data", {}).get("cancelled"):
+            raise RuntimeError(f"new session failed: {new_response}")
+
+        pi.send(
+            {
+                "id": "resume",
+                "type": "switch_session",
+                "sessionPath": original_session,
+            }
+        )
+        resume_response = pi.response("resume")
+        if not resume_response.get("success") or resume_response.get("data", {}).get("cancelled"):
+            raise RuntimeError(f"resume failed: {resume_response}")
+
+        # P5 missing fragment: action-time source validation must revoke/refuse.
+        manifest(source_manifest, root / "absent-fragment.md", expected)
+        pi.prompt_and_settle(
+            "p5-missing",
+            "Call gate0_nonce_probe exactly once with label p5-missing, then stop.",
+        )
+
+        # P5 oversize fragment: expected hash is correct, size limit is not.
+        oversize = root / "oversize.md"
+        oversize.write_text("X" * 65)
+        manifest(source_manifest, oversize, hashlib.sha256(oversize.read_bytes()).hexdigest(), 64)
+        pi.prompt_and_settle(
+            "p5-oversize",
+            "Call gate0_nonce_probe exactly once with label p5-oversize, then stop.",
+        )
+
+        # P5 hash mismatch: size is valid but bytes differ from expected.
+        mismatch = root / "mismatch.md"
+        mismatch.write_text("tampered\n")
+        manifest(source_manifest, mismatch, expected, 64)
+        pi.prompt_and_settle(
+            "p5-hash",
+            "Call gate0_nonce_probe exactly once with label p5-hash-mismatch, then stop.",
+        )
+
+        time.sleep(1)
+        return jsonl(pi_log), jsonl(generation_log), list(pi.raw_lines), list(pi.stderr_lines)
+    finally:
+        pi.close()
+        try:
+            socket_request(generation_socket, {"action": "shutdown-broker"})
+        except OSError:
+            pass
+        try:
+            broker.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            broker.kill()
+            broker.wait()
+
+
+def run_closed(root: Path) -> list[dict[str, Any]]:
+    workspace = root / "closed-workspace"
+    workspace.mkdir()
+    pi_log = root / "closed-hooks.jsonl"
+    env = os.environ.copy()
+    env.update(
+        {
+            "GATE0_PI_LOG": str(pi_log),
+            "MOSAIC_PI_FORCE_SKILLS": "",
+            "PI_SKIP_VERSION_CHECK": "1",
+        }
+    )
+    command = [
+        "mosaic",
+        "yolo",
+        "pi",
+        "--mode",
+        "rpc",
+        "--no-session",
+        "--no-extensions",
+        "--no-context-files",
+        "--no-prompt-templates",
+        "--extension",
+        str(HERE / "pi_gate0_extension.ts"),
+        "--extension",
+        str(HERE / "pi_later_extension.ts"),
+    ]
+    pi = PiRpc(command, workspace, env)
+    try:
+        pi.send({"id": "closed-state", "type": "get_state"})
+        pi.response("closed-state")
+        time.sleep(0.5)
+        return jsonl(pi_log)
+    finally:
+        pi.close()
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory(prefix="gate0-pi-") as temp:
+        root = Path(temp)
+        records, generations, rpc_lines, stderr_lines = run_open(root)
+        closed = run_closed(root)
+
+        p2_message = next(
+            r for r in records if r["event"] == "message_end" and r.get("nonceMappings")
+        )
+        p2_tool = next(r for r in records if r["event"] == "tool_call" and r.get("allowed"))
+        mapped = p2_message["nonceMappings"][0]
+        assert mapped["toolCallId"] == p2_tool["toolCallId"]
+        assert mapped["requestNonce"] == p2_tool["mapping"]["nonce"]
+        assert next(r for r in records if r["event"] == "session_start")["lastPosition"] is True
+        assert next(r for r in closed if r["event"] == "session_start")["gateState"] == "CLOSED_NOT_LAST"
+        reload_revoke = next(
+            r
+            for r in generations
+            if r["event"] == "runtime_generation_bump"
+            and r.get("reason") == "reload"
+            and r.get("phase") == "shutdown"
+        )
+        assert reload_revoke["prior_lease"] == "VERIFIED"
+        assert reload_revoke["prior_lease_revoked"] is True
+        for reason in {"missing", "oversize", "hash-mismatch"}:
+            assert any(
+                r["event"] == "context_return"
+                and r.get("sourceValidation", {}).get("reason") == reason
+                and r.get("injectionDecision") == "REFUSED"
+                and r.get("promotion") is False
+                for r in records
+            )
+            assert any(
+                r["event"] == "tool_call"
+                and r.get("mapping", {}).get("sourceReason") == reason
+                and r.get("allowed") is False
+                for r in records
+            )
+        assert any(
+            r["event"] == "message_end" and r.get("exactContextBlockCopied") is True
+            for r in records
+        )
+
+        print("$ python3 docs/compaction-refresh/probes/pi_gate0_run.py")
+        print("machine_assertions=PASS")
+        print("runtime_versions:")
+        print("  " + subprocess.check_output(["pi", "--version"], text=True).strip())
+        print("  " + subprocess.check_output(["mosaic", "--version"], text=True).strip())
+
+        print("\nP2_EVENT_ORDER_AND_NONCE_MAP:")
+        for record in records:
+            if record["seq"] <= 12 and record["event"] in {
+                "after_provider_response",
+                "message_end",
+                "tool_call",
+                "tool_execute",
+            } and (
+                record["event"] != "message_end"
+                or record.get("role") == "assistant"
+            ):
+                print(json.dumps(record, sort_keys=True))
+
+        print("\nP2_LAST_OR_CLOSED:")
+        print(json.dumps(next(r for r in records if r["event"] == "session_start"), sort_keys=True))
+        print(json.dumps(next(r for r in closed if r["event"] == "session_start"), sort_keys=True))
+
+        print("\nP3_GENERATION_BROKER:")
+        for record in generations:
+            if record["event"] in {"probe_lease_promoted", "runtime_generation_bump"}:
+                print(json.dumps(record, sort_keys=True))
+
+        print("\nP5_SOURCE_INVALIDATION:")
+        fault_reasons = {"missing", "oversize", "hash-mismatch"}
+        emitted_context: set[str] = set()
+        emitted_tool: set[str] = set()
+        for record in records:
+            source_reason = record.get("sourceValidation", {}).get("reason")
+            if (
+                record["event"] == "context_return"
+                and source_reason in fault_reasons
+                and source_reason not in emitted_context
+            ):
+                print(json.dumps(record, sort_keys=True))
+                emitted_context.add(source_reason)
+            mapping_reason = record.get("mapping", {}).get("sourceReason")
+            if (
+                record["event"] == "tool_call"
+                and not record.get("allowed")
+                and mapping_reason in fault_reasons
+                and mapping_reason not in emitted_tool
+            ):
+                print(json.dumps(record, sort_keys=True))
+                emitted_tool.add(mapping_reason)
+        emitted_broker: set[str] = set()
+        for record in generations:
+            reason = record.get("source_reason")
+            if record["event"] == "source_invalidation_revoke" and reason not in emitted_broker:
+                print(json.dumps(record, sort_keys=True))
+                emitted_broker.add(str(reason))
+
+        print("\nP6_PI_CONTEXT_ATOMIC_OBSERVATION:")
+        for record in records:
+            include = (
+                (record["event"] == "context_return" and record.get("injectionDecision") == "ONE_ATOMIC_AGENT_MESSAGE")
+                or (record["event"] == "before_provider_request" and record.get("finalPayloadValid"))
+                or (record["event"] == "message_end" and record.get("exactContextBlockCopied"))
+            )
+            if include and record["seq"] <= 12:
+                print(json.dumps(record, sort_keys=True))
+
+        print("\nRPC_EVENT_COUNTS:")
+        counts: dict[str, int] = {}
+        for line in rpc_lines:
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            key = str(event.get("type"))
+            counts[key] = counts.get(key, 0) + 1
+        print(json.dumps(counts, sort_keys=True))
+        print("stderr_nonempty=" + str(bool(stderr_lines)))
+        for line in stderr_lines[:10]:
+            print("stderr: " + line[:500])
+
+
+if __name__ == "__main__":
+    main()

docs/compaction-refresh/probes/pi_later_extension.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+// Deliberately loaded after pi_gate0_extension.ts. The Gate0 extension must
+// observe its argv position and remain CLOSED rather than claiming finality.
+export default function register(pi: ExtensionAPI) {
+  pi.on('context', async (event) => ({ messages: [...event.messages] }));
+  pi.on('before_provider_request', async () => undefined);
+}

docs/compaction-refresh/reviews/GATE0-PROBE3-CLASSB-S3-REVIEW-v3.md

@@ -0,0 +1,65 @@
+# Gate0 Probe-3 (D4) Class-B — §3-Conformance Review v3
+
+**Verdict: ✅ PASS**
+
+## Pin (G1 — reviewed object, mandatory)
+
+- **Reviewed object = `ace6066762c088f4b9729860da71b4c84451a7c3`** (harness commit, branch `feat/827-gate0-probe`, `mosaicstack/stack` @ git.mosaicstack.dev).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py`
+- **Harness sha256 (pushed provider bytes, fetched `-o FILE`, FULL-40 ref, verified before trust):**
+  `2f11c9391c0eef203f26b1206bee8bc4cd106e8c1192399c5e7b71f41a3f6b75` (17162 bytes; no not-found sentinel).
+- **§3 amendment authority read at pin:** `GATE0-PROBE3-EXEC-AMENDMENT.md` @ ref `571f239154c6793fb1a5eac0d1cd4182f286a3ac`,
+  sha256 `9ac9ff873fad41a6e15763cc89cb94d0bc4a6b0cf9b6770561d1781b03f63276` (7699 bytes). MUST-HAVE/MUST-BE-ABSENT
+  confirmed against the actual fetched §3 text, not a paraphrase.
+
+## Independence (G2)
+
+Distinct Opus §3-conformance reviewer (Gate-16 author≠reviewer). I did **not** build this harness (author =
+ms-rev-826); I am not Mos. This verdict is my own; the author did not author or edit it. Byte review only — **ran
+nothing** (no harness, no broker, no sockets/state). Reviewed across v1 (FAIL, live-broker launch path) → v2 (PASS,
+later found runtime-dead producer) → this v3 (closes the live-path review-gap).
+
+## Why v3 (the review-gap closed)
+
+v2 PASS @`839d156f` credited the static presence of `lease_anchor_registered` as isolation proof. At FIRE the
+producing path was **dead**: the harness drove the *released* `mosaic` binary, which launched Pi **ungated**, so
+`register_anchor` never ran. Static presence of an assertion ≠ its producing path executing. v3 requires the
+producing path to be **live at runtime**.
+
+## Surface-by-surface
+
+| Surface | Result | Evidence (file:line) |
+|---|---|---|
+| Pushed bytes fetched + sha-verified | ✅ | sha256==`2f11c939…`, 17162B, no sentinel |
+| (a) LIVE-PATH — drives the **gated** launcher, producer in the exec chain, NOT released `mosaic`/plain `execRuntime` | ✅ | launch = `python3 <GATED_LAUNCHER> --runtime pi -- pi …` :357-364; `GATED_LAUNCHER=…/launch-runtime.py` :32, pinned `GATED_WI_HEAD=abd2791f…` :31; `mosaic yolo`/`execRuntime` = 0 hits. `launch-runtime.py` unconditionally `register_anchor`s before `execvpe`, so the producer is in the invoked chain |
+| (b) Fail-closed precondition present + correct (gated + fixture-socket, refuses otherwise), invoked before all launches | ✅ | `gated_launcher_precondition` :229-251, called :342 **before** broker Popen :343 and Pi launch :357. Verifies (ii) `MOSAIC_LEASE_BROKER_SOCKET==fixture` :232 + fixture in tempdir :234; (i) launcher HEAD==`abd2791f` :243 + source has `register_anchor` **before** `execute(command[0]…)` and reads `MOSAIC_LEASE_BROKER_SOCKET` :246-250. Raises `RuntimeError` (no run) on any miss :233/:235/:242/:244/:250 |
+| (c) Fixture-socket isolation (no live/default broker reachable, single p3 fixture, non-destructive) | ✅ | `pop("MOSAIC_LEASE_BROKER_SOCKET")` :330 + set to fixture socket :334; harness invokes `launch-runtime.py` directly so it reads `MOSAIC_LEASE_BROKER_SOCKET`=fixture with **no** `defaultLeaseBrokerSocket`/XDG/`/run/user` fallback in the path; `register_anchor` served by the single p3 fixture; `p3_generation_broker.py` **zero diff** vs `839d156f` (in-memory volatile hex-256 session `secrets.token_hex(32)`, nothing durable outside tempdir) |
+| (d) Assertion INTACT (`lease_anchor_registered` + `session_id_shape=="hex-256"`, not softened/optional/repointed) | ✅ | :256-258 (event), :298 (`hex-256`), folded into single-PID/starttime identity set :286. Not Case C |
+| spawns ONLY p3_generation_broker.py | ✅ | broker Popen = `HERE/p3_generation_broker.py` :343-346; the pinned launcher is a register-before-exec launch wrapper, not a 2nd broker |
+| promotion = fixture-only (not P2-banked) | ✅ | `d4_fixture_promote` "not a P2 evidence-gathering authorization"; `promote-probe` in-memory; precondition target only; no P2 import |
+| D4 assertions complete | ✅ | same-PID+starttime persist (incl. launcher registration) :284-288; gen strictly increases :290-293; reload revokes genuinely-VERIFIED prior :299-300; new→`MUTATOR_UNVERIFIED` :301; prior→`STALE_GENERATION` :302; lifecycle boundaries :294-297 |
+| P5 / P6 / P2-bank / retry-launder / live-effect / mechanism-change / scope-widen ABSENT | ✅ | 0 hits: `source-invalid`/`run_open`/`atomic`/`p2_provider`/`p5`/`p6`/`pi_gate0_run`/`retry`; no real-broker path; the only mechanism change is the required launch-routing fix (release→pinned gated launcher), which narrows scope, not widens |
+| non-destructive | ✅ | per-run `tempfile.mkdtemp` fixtures; p3 in-memory + tempdir socket/log only; reads `/proc/<pid>/stat` (read-only) |
+| deterministic | ✅ | isolated tempdir per run; deterministic assertions; session-id randomness is **shape**-asserted only (`hex-256`), `setdefault` idempotent |
+| hidden exec-at-import | ✅ absent | only `if __name__ == "__main__": main()`; docstring: not executed until FIRE |
+
+## Verdict
+
+**PASS @ `ace60667`** — (a) LIVE-PATH, (b) fail-closed precondition, (c) fixture-socket isolation, and
+(d) intact assertion all hold, with zero out-of-scope surface. The v2 review-gap (runtime-dead producer via the
+released ungated `mosaic`) is structurally closed: the harness no longer invokes `mosaic` at all — it invokes the
+pinned `abd2791f` `launch-runtime.py` directly (register-before-exec), and refuses to launch unless the launcher is
+that pinned gated register-before-exec binary bound to this run's fixture socket.
+
+**Findings: none.**
+
+## Scope reminder (not a finding)
+
+Per §3/§5 of the amendment, producing this evidence **executes** the Gate0 mechanism (launches processes, creates
+socket/state artifacts, exercises revocation). This review clears the **bytes**; **FIRE remains separately gated on
+Mos's explicit post-clear GO** and is not authorized by this review.
+
+---
+
+**Reviewer:** independent Opus §3-conformance reviewer (Gate-16 author≠reviewer). Byte review only; ran nothing.
+**Reviewed object (pin):** `ace6066762c088f4b9729860da71b4c84451a7c3` · harness sha256 `2f11c9391c0eef203f26b1206bee8bc4cd106e8c1192399c5e7b71f41a3f6b75`.

docs/compaction-refresh/reviews/GATE0-PROBE3-FIDELITY-S3-REVIEW-v4.md

@@ -0,0 +1,95 @@
+# Gate0 Probe-3 (D4) Observation-Fidelity — §3-Conformance Review v4
+
+**Verdict: ✅ PASS**
+
+## Pin (G1 — reviewed object, mandatory)
+
+- **Reviewed object = `484849387006ab5561798506fd6042ddbd5617de`** (harness commit, branch `feat/827-gate0-probe`, `mosaicstack/stack` @ git.mosaicstack.dev).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py` — sha256 (pushed provider bytes, `-o FILE`, FULL-40 ref, verified before trust): `9095eab7a4ddf11bb92bb5971d49e1facad12f4692ce2081665b0af47cbe5098` (23698 bytes, no not-found sentinel). Worktree bytes at `48484938` re-hashed identical.
+- **Co-reviewed fixture broker:** `docs/compaction-refresh/probes/p3_generation_broker.py` (sha256 `fd5327d2e9a2808282cbc9c4a4ccef42d2a806482b27cc48035191b9b11607c8`).
+- **Traceability anchor (independently recomputed):** `GATED_LAUNCHER_SHA256 = e950e4224e280f16979d90cabb89aa1896c5ee28bed2df957e14d018d43cda82` equals the sha256 of `packages/mosaic/framework/tools/lease-broker/launch-runtime.py` at WI-3 #830 reviewed head `f400830738998db105107a2a4c69c7f2a2a6fd5d` (computed from two independent worktrees).
+
+## Independence (G2)
+
+Distinct Opus §3-conformance reviewer (Gate-16 author≠reviewer). I did not build this harness (author = ms-rev-826);
+I am not Mos. This verdict is my own; the author did not author or edit it. Byte review only — **ran nothing** (no
+harness, no broker, no sockets/state). Prior v3 PASS (`ace60667`, pinned `abd2791f`) is correctly **superseded**:
+pinning a pre-`66b1e0a0` ancestor made D4 an in-memory socket simulation (hollow gate). v4 requires
+mechanism-fidelity within isolation (Jason R1).
+
+## BAR1 — Traceability (evidence attests the SHIPPED WI-3 D4 mechanism)
+
+| Check | Result | Evidence |
+|---|---|---|
+| `GATED_WI_HEAD == f4008307` (not `abd2791f`) | ✅ | :33 |
+| Launcher pinned by git-HEAD **and** sha256 | ✅ | precondition :285-288 (`head != GATED_WI_HEAD` raise; `sha256(launcher) != GATED_LAUNCHER_SHA256` raise); sha256 independently == f4008307's `launch-runtime.py` |
+| Launcher bytes contain the file-backed mechanism | ✅ | precondition requires `register_anchor` :290, `initialize_runtime_generation(generation_file, generation)` :291, `generation-{session_id}.state` :294, `MOSAIC_LEASE_GENERATION_FILE` :295, `read_runtime_generation`+`bump_runtime_generation` in `lease_generation.py` :296-299; order `register < initialize < execute` :302-303 |
+
+## BAR2 — Fidelity (file-backed generation, not in-memory simulation)
+
+| # | Requirement | Result | Evidence |
+|---|---|---|---|
+| i | Extension bumps `generation-{sid}.state` via the real helper, not in-mem | ✅ | ext `lifecycle()` calls `broker({action:'bump-generation'})` at every post-start boundary (harness :200-205); broker `bump-generation` → `bump_runtime_generation(generation_environment(identity))` (broker :119-120) |
+| ii | Broker reads generation via `read_runtime_generation`, not an in-mem counter | ✅ | broker loads the pinned module (`--generation-module`, :52-54); `file_generation()` = `read_runtime_generation(...)` (:77-78); authorize-probe reads `current_generation = file_generation(identity)` (:154); lifecycle `new_generation = file_generation(identity)` (:201). The in-mem `generations` dict is only an old-value cache for the monotonic guard (:199-204), never the authorization authority |
+| iii | `assert_d4` observes the FILE-BACKED transition | ✅ | `state_file_source` = all records `generation_source=="state-file"` (harness :370-372); `state_file_drives_lifecycle` = state-bumps == lifecycle generations[1:] (:368-369); `new_generation_unverified→MUTATOR_UNVERIFIED` :382; `prior_generation_stale→STALE_GENERATION` :383; `verified_revoked_on_reload` :380-381 — not a socket-only bump |
+| iv | `.state` bound to per-run fixture temp root | ✅ | broker `generation_environment` **raises if `state_path.parent != socket_path.parent`** (:73-74); `state_file_in_fixture_root` (:373-376); precondition forbids inherited `MOSAIC_LEASE_GENERATION_FILE` (:255-256) and requires socket in `gettempdir()` (:274-275); launcher/broker agree on `socket_path.parent / generation-{sid}.state` |
+
+## BAR3 — Carry-over
+
+| # | Result | Evidence |
+|---|---|---|
+| a LIVE-PATH (gated launcher @f4008307 at runtime, not released/plain execRuntime) | ✅ | Pi launched via `python3 <GATED_LAUNCHER> --runtime pi -- pi …` :502-505; `mosaic yolo`/`execRuntime` = 0 hits; register-before-exec producer in the invoked chain (precondition order gate) |
+| b Fail-closed precondition present+correct | ✅ | `gated_launcher_precondition` :250-306, invoked :485 **before** broker/Pi; raises on socket≠fixture / gen-file-inherited / write-path-escape / head-mismatch / hash-mismatch / not-register-before-exec-file-bound |
+| c Fixture-socket isolation, single p3 broker | ✅ | one broker Popen :486-500; `MOSAIC_LEASE_BROKER_SOCKET=socket_path` (fixture); direct launcher invocation ⇒ no default/XDG/`/run/user` fallback in path |
+| d `lease_anchor_registered` INTACT | ✅ | broker emits event + `session_id_shape=="hex-256"` (:102-107); `record_where` requires it (:324-326); `lease_anchor_fixture` check (:379) — not deleted/softened/optional/repointed (not Case-C) |
+
+## BAR4 — Homelab Gate-B carry-forward findings
+
+| # | Result | Evidence |
+|---|---|---|
+| b4-1 gated launcher @f4008307, not released/plain execRuntime | ✅ | :502-505; 0 `mosaic yolo`/`execRuntime` |
+| b4-2 **affirmative no-escape** (allow-list base, not deny-list) | ✅ | `isolated_environment` builds the child env from a **literal allow-list dict** (:442-461), NOT `os.environ.copy()`; only PATH/LANG/TERM/PI_CODING_AGENT (non-write-bearing) pass through; every write-bearing var (HOME/XDG*/TMPDIR/MOSAIC_AGENT_WORKDIR/HEARTBEAT_RUN_DIR/MOSAIC_HOME/D4_PI_LOG/socket) redirected under `root`; precondition double-checks each is `is_relative_to(root)` (:257-273). No unnamed/future inherited var survives |
+| b4-3 `--runs` exactly 3, fail-closed otherwise | ✅ | `add_argument("--runs", type=int, default=3, choices=(3,))` :591 (argparse rejects any other value) |
+| b4-4 cleanup try/finally spans the whole launch | ✅ | `broker=pi=None` :479-480; `try` opens **before** precondition/broker/PiRpc :482; nested `finally` always closes pi then broker+socket even on early `wait_path`/`PiRpc` failure :571-585 |
+| b4-5 `-O`-safe integrity + derived PASS | ✅ | load-bearing checks in a `checks` dict; `if failed: raise AssertionError` :385-387 and `if not passed: raise` :388-390 (NO bare `assert` anywhere — grep-confirmed); PASS = `"PASS" if passed else "FAIL"` derived from `all(checks.values())` :393, re-derived+checked in `run_once` :550-553 |
+
+## MUST-BE-ABSENT sweep
+
+`P5` / `P6` / `P2-bank` / `retry-launder` / `mosaic yolo` / `execRuntime` / `run_open` / `atomic-observation` /
+`pi_gate0_run` = **0 hits** (both files). Extension invokes only `bump-generation` / `lifecycle` /
+`authorize-probe` / `promote-probe`. No live/prod/real-broker path (single fixture broker; allow-list env; launcher
+pinned to fixture socket). No `.state`/gen-file path outside the fixture temp root (broker `generation_environment`
+raises otherwise). §4 live effect: none. No extra broker/socket beyond the single p3. No exec-at-import (both files
+`__main__`-guarded). Mechanism change is confined to the mandated R1 observation-fidelity deepening + BAR4 hardening;
+no scope-widen of what the probe touches.
+
+## Observations (transparency — not findings)
+
+1. The fixture broker retains a **dormant `source-invalid` action** (:179-194, P5-adjacent, in-mem). It is
+   **never invoked** by the harness or its embedded extension (verified: extension actions are only
+   bump/lifecycle/authorize/promote), and `assert_d4` never observes it — so the probe does **not** exercise or bank
+   P5. Pre-existing shared-fixture code, unchanged. Surfaced so Mos may, if desired, apply a stricter
+   purge-dormant-P5-from-the-fixture standard; under the "what the probe TOUCHES/does" framing it is not a violation.
+2. Fixture `HOME` receives a **read-only copy** of the operator's `~/.pi/agent` `settings.json`/`auth.json`/`bin/fd`
+   (:430-440, `shutil.copy2` into the fixture) so real Pi can authenticate to the model provider. It reads operator
+   state; it does not write/mutate operator HOME and does not emit/log credential material. Confined to the fixture.
+
+## Verdict
+
+**PASS @ `48484938`** — BAR1 (traceability to shipped f4008307 mechanism) + BAR2 (genuine file-backed generation,
+i–iv) + BAR3 (live-path / fail-closed precondition / isolation / intact assertion) + BAR4 (b4-1..b4-5) all hold,
+with zero out-of-scope surface exercised. The v3 hollow-gate (ancestor pin, in-mem simulation) is structurally
+closed: evidence now attests the shipped WI-3 D4 file-backed generation mechanism, launcher pinned by head+sha256,
+child env write-confined by allow-list, integrity `-O`-safe with a derived PASS.
+
+**Findings: none.**
+
+## Scope reminder (not a finding)
+
+Per §3/§5 of the amendment, producing this evidence **executes** the Gate0 mechanism. This review clears the
+**bytes**; **FIRE remains separately gated on Mos's explicit post-clear GO** and is not authorized by this review.
+
+---
+
+**Reviewer:** independent Opus §3-conformance reviewer (Gate-16 author≠reviewer). Byte review only; ran nothing.
+**Reviewed object (pin):** `484849387006ab5561798506fd6042ddbd5617de` · harness sha256 `9095eab7a4ddf11bb92bb5971d49e1facad12f4692ce2081665b0af47cbe5098`.

docs/compaction-refresh/reviews/GATE0-PROBE3-HYGIENE-S3-REVIEW-v5.md

@@ -0,0 +1,80 @@
+# Gate0 Probe-3 (D4) Hygiene-Delta — §3-Conformance Review v5
+
+**Verdict: ❌ FAIL** (hygiene delta (a)+(b) landed correctly and (c)+(d) hold, but homelab findings **NEW-5** and **NEW-6** are present in these bytes; both must close for PASS).
+
+## Pin (G1 — reviewed object, mandatory)
+
+- **Reviewed object = `7f975b95ad39096463a7548bd6be0dbb387cb61b`** (harness commit, branch `feat/827-gate0-probe`).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py` — sha256 (pushed provider bytes, `-o FILE`, FULL-40 ref, verified before trust): `c3a09a342a4b367184d44472ec6fc11f8a3aabb7e90d5a72aa6b7044b1d9b91e` (24174 bytes, no not-found sentinel).
+- **Co-reviewed fixture broker:** `p3_generation_broker.py` sha256 `4db4fef1ac6658a8ca79ad5091cefc901d2aa26003265c3d6726c294cf895cad`.
+
+## Reviewer identity / lane (independence — on the record)
+
+This review is produced by a **distinct independent Opus §3-conformance / SECREV session** (Gate-16 author≠reviewer),
+**byte review only, ran nothing**, that **did not build** this harness (author = ms-rev-826) and **is not Mos**. The
+PROCESS/LANE separation (build lane ≠ review lane) holds and is attested here. Homelab's separate observation — that
+the published PASS commits and the repair commits share the `ms-lead-reviewer` **Git signer identity** — is a
+git-identity-signer question I do **not** self-resolve; per instruction it is routed to Mos. My lane attestation is
+independent of the git signer.
+
+## Hygiene delta (v4 `48484938` → v5 `7f975b95`) — items (a)+(b): CLOSED
+
+Full `diff` of both files shows the delta touches **only** these:
+
+- **(a) Creds scrubbed — CLOSED.** New `scrub_fixture_credentials(root)` (:467-475): `shutil.rmtree(root/"home"/".pi"/"agent")` then a fail-closed re-check `if copied_agent.exists(): raise` (:473-474). Invoked in the **outermost `finally`** (:598), **after** pi/broker cleanup and **before** `return root` (:600) — so it runs on the **success path too**. The scrub target exactly matches the only copy site (`target_agent = fixture_home/".pi"/"agent"`, :433). `isolated_environment` was moved inside the `try` (:485) so the scrub finally also covers a partial env-setup failure. No copied agent credential/config subtree (incl. `auth.json`) survives in any retained root. ✅
+- **(b) `source-invalid` handler REMOVED — CLOSED.** `grep source-invalid / source_invalidation_revoke == 0` across **both** files. Broker delta is solely the deletion of the old `:179-194` block. ✅
+
+## (c) Everything-else byte-stable vs `48484938` — HOLDS
+
+Diff confirms **no other hunks**. Re-swept intact: traceability `GATED_WI_HEAD=f4008307` (:33) + `GATED_LAUNCHER_SHA256=e950e4224e…` (:35); fidelity `read_runtime_generation`/`bump_runtime_generation` + `generation_source=="state-file"` + `new→MUTATOR_UNVERIFIED`/`prior→STALE_GENERATION`; `lease_anchor_registered` + `hex-256`; `-O`-safe (0 bare `assert`, PASS derived `all(checks.values())`); allow-list literal env (0 `os.environ.copy`); `--runs choices=(3,)`; fail-closed precondition; single p3 broker. Blockers 1-4 (inherited env / `--runs`≠3 / cleanup-misses-setup-failure / `-O`-strips-checks) remain closed.
+
+## (d) ABSENT sweep — 0
+
+`P5`/`P6`/`P2-bank`/`retry-launder`/`mosaic yolo`/`execRuntime`/`run_open`/`atomic`/`pi_gate0` = 0 (both files);
+extension invokes only `bump-generation`/`lifecycle`/`authorize-probe`/`promote-probe`; no exec-at-import.
+
+## Homelab carry-forward — NEW-5 / NEW-6: **PRESENT → FAIL**
+
+### 🔴 NEW-6 — GATED_WI_ROOT resolves wrong / non-portably (CONFIRMED)
+`GATED_WI_ROOT = HERE.parents[3].parent / "stack-cr-wi3-revoke"` (:32). For the harness at
+`…/agent-work/stack-cr-wi0-gate0/docs/compaction-refresh/probes/`, this computes
+**`/home/hermes/stack-cr-wi3-revoke` — which does not exist**. The actual f4008307 worktree is
+`/home/hermes/agent-work/stack-cr-wi3-revoke` = `HERE.parents[3] / "stack-cr-wi3-revoke"`. The traversal is
+**off-by-one** (`.parents[3].parent` should be `.parents[3]`), and it additionally hardcodes the worktree name — a
+non-portable relative assumption. On this host the precondition therefore fail-closes ("gated WI launcher is
+unavailable") and the probe cannot locate/execute the pinned launcher at all. **Real resolution defect** (independently
+computed by path arithmetic; harness not run). **file:line — :32.**
+*Fix:* derive `GATED_WI_ROOT` from a portable, explicit anchor (e.g. an env-provided path validated to be the
+f4008307 worktree, or `HERE.parents[3] / "stack-cr-wi3-revoke"` with existence+HEAD assertion), not `.parents[3].parent`.
+
+### 🔴 NEW-5 — launcher precondition is check-then-exec, not pinned-executed-bytes (CONFIRMED)
+The precondition hashes `launcher_bytes = GATED_LAUNCHER.read_bytes()` (:280) against `GATED_LAUNCHER_SHA256` (:287),
+but the launcher is **executed separately** via `PiRpc([sys.executable, str(GATED_LAUNCHER), …])` (:514-515), which
+opens and **re-reads the file at exec time**. There is **no fd-handoff and no exec-from-verified-copy**, so the
+verified snapshot does **not** bind the executed bytes. The window between check (:287) and exec (:514-515) spans the
+broker `Popen` + `wait_path` (≤20 s) — a genuine **check-then-exec TOCTOU / mutable-path trust**; the `git rev-parse
+HEAD` check (:285-286) is likewise on a mutable HEAD, not the executed bytes. Per the bar this is a real gap.
+**file:line — hash :280/:287 vs exec :514-515.**
+*Fix:* execute the exact verified bytes with no window — e.g. read once, verify, and exec from a fixture-private
+copy of the verified bytes (or `python3 /proc/self/fd/<verified-fd>`), so the hashed bytes == executed bytes.
+
+## Verdict
+
+**FAIL @ `7f975b95`.** The hygiene delta itself is correct — (a) creds scrub (fail-closed finally, success path,
+every retained root) and (b) `source-invalid` removal both landed cleanly, (c) everything else is byte-stable vs
+`48484938`, and (d) the absent sweep is 0. **However**, homelab's NEW-5 (check-then-exec launcher TOCTOU / not
+pinned-executed-bytes) and NEW-6 (GATED_WI_ROOT off-by-one/non-portable resolution) are **present in these bytes**;
+the addendum requires both **closed** for PASS. Not softened. Returns to author (ms-rev-826) — not to a builder
+re-review, no PASS-launder.
+
+**Findings:** NEW-6 (`p3_d4_focused_run.py:32`); NEW-5 (`p3_d4_focused_run.py:280/:287` vs `:514-515`).
+
+## Scope reminder (not a finding)
+
+Producing this evidence **executes** the Gate0 mechanism (§3/§5). This review clears **bytes** only; FIRE remains
+separately gated on Mos's explicit post-clear GO — and is moot until this FAIL is remediated.
+
+---
+
+**Reviewer:** independent Opus §3-conformance/SECREV reviewer (Gate-16 author≠reviewer). Byte review only; ran nothing.
+**Reviewed object (pin):** `7f975b95ad39096463a7548bd6be0dbb387cb61b` · harness sha256 `c3a09a342a4b367184d44472ec6fc11f8a3aabb7e90d5a72aa6b7044b1d9b91e`.

docs/compaction-refresh/reviews/GATE0-PROBE3-MOS-COATTEST-v-final.md

@@ -0,0 +1,116 @@
+# GATE0 Probe-3 (#827) — Mos byte-scope-verify CO-ATTESTATION (v-final)
+
+**Principal:** Mos (orchestrator, merge authority for the mosaic-stack governance lane).
+**Committed under a DISTINCT git identity** (`mos-orchestrator@mosaic.local`) — deliberately NOT the
+`ms-lead-reviewer@mosaic.local` lane signer — so this record stands as a *distinct-identity*
+co-attestation, not a same-signer duplicate. See "Independence" below.
+
+**Verify class:** independent provider-byte read (guarded `git show <full-40>:path | sha256sum` from a
+read-only clone of `mosaicstack/stack`). Not a re-build, not a re-run — a byte/scope/hygiene audit of
+the exact committed objects on the provider branch.
+
+## Package under attestation
+
+| Artifact | Ref |
+|---|---|
+| Branch | `feat/827-gate0-probe` |
+| Harness commit-40 | `2d54a9dd14cb924701b2ae4ed72dae4df760c4e3` |
+| Harness `p3_d4_focused_run.py` sha256 | `15a154df55273f51301763a984485fd63813f6d1f05d2728abb9fb8b9c040b1a` (27366 B) |
+| §3-review-v6 commit-40 | `23c0caca9b5d44002e6184cd7f2b6c837e8795b2` |
+| Review path | `docs/compaction-refresh/reviews/GATE0-PROBE3-NEW56-S3-REVIEW-v6.md` |
+
+sha256 re-confirmed against the checked-out object at `HEAD:docs/compaction-refresh/probes/p3_d4_focused_run.py`
+(git object id `8c68cd07…`) — matches the relayed value byte-for-byte.
+
+## Findings — VERDICT: byte-scope + mechanism + hygiene **PASS**
+
+**Anchors.** Harness sha256 matches (27366 B). review-v6 (`23c0caca`) parent == harness commit
+`2d54a9dd`; review touches only the review `.md` (+82 lines, 1 file). Broker
+(`p3_generation_broker.py`) delta vs `48484938…` = **exactly** the 16-line `action=="source-invalid"`
+handler purge, byte-stable otherwise.
+
+**NEW-6 (GATED_WI_ROOT off-by-one) — CLOSED.** `resolve_gated_wi_root()` selects the worktree by
+`git worktree list --porcelain` enumeration, requires a UNIQUE match on `HEAD==GATED_WI_HEAD`
+(`f400830738998db105107a2a4c69c7f2a2a6fd5d`) AND `branch==refs/heads/feat/830-compaction-revoke`,
+then fail-closed re-validates (`is-inside-work-tree==true`, `rev-parse HEAD==GATED_WI_HEAD`);
+`RuntimeError` on ambiguity/mismatch. The `HERE.parents[3].parent / "stack-cr-wi3-revoke"` off-by-one
+and the hardcoded `/home/hermes/...` literal are **gone** — portable, zero hardcoded path.
+
+**NEW-5 (TOCTOU / pinned-executed-bytes) — CLOSED via approach (i), as mandated.** The `git`-object
+sha256 pin (`GATED_LAUNCHER_SHA256 = e950e422…`) is the trust anchor. Ordering/marker `.find()`
+heuristics are downgraded to explicitly diagnostic-only ("never a substitute for the pin"). In
+`launch_verified_pi()` the executed working-tree file is re-hashed against the pin **in the statement
+immediately before `Popen`** (no interleaved yield/IO), and the launcher is executed **in place at the
+pinned worktree path** — the higher-risk approach (ii) copy-to-fixture (previously at `7ff63cd5` /
+`6164dc07`) is **reverted** (the only remaining `shutil.copy2` is the legitimate credential copy, not a
+launcher copy). Residual sub-statement TOCTOU window on a local file inside a non-adversarial operator
+fixture is within this probe's threat model; the gross precondition→much-later-exec gap homelab flagged
+is closed.
+
+**Hygiene — CLOSED.** `scrub_fixture_credentials(root)` removes the entire `.pi/agent` subtree in a
+`finally` block (nested try/finally, after `pi.close()` + broker shutdown, before `return root`) and
+`RuntimeError`s if the scrub fails — credentials are removed from retained evidence; logs retained.
+
+**Invariants byte-stable (all INTACT):** assertion `lease_anchor_registered`; file-backed fidelity
+checks (`generation_source=="state-file"`, `state_file_in_fixture_root`, `MUTATOR_UNVERIFIED`,
+`STALE_GENERATION`); `-O`-safe (0 bare `assert`); allow-list env (0 `os.environ.copy`); single broker;
+`--runs choices=(3,)`; ABSENT-sweep (`yolo`/`execRuntime`/`p3_bank`/`promote_p2`/`retry`) = 0.
+
+**R1 mechanism-fidelity boundary — HELD.** D4 exercises #830's real file-backed revocation
+(`generation-{sid}.state` / `MOSAIC_LEASE_GENERATION_FILE`, from `66b1e0a0`); `.state` stays inside the
+fixture temp root; fixture-socket / child-write-escape / gettempdir isolation preconditions preserved;
+launcher exec is in place at the pinned worktree (same surface as R1, not a new production/live
+surface). **No path escapes the fixture root.** BEYOND-R1 tripwire NOT tripped.
+
+## Independence
+
+- **Substantive principal-independence** of review-v6 is satisfied by an orchestrator-dispatched,
+  builder-distinct Opus SECREV (`ms-secrev-828`, byte-only, non-builder) — that IS the substance of
+  Gate-16.
+- The shared `ms-lead-reviewer` git signer on harness+review commits is **evidentiary, not
+  substantive**. It is resolved by (1) this Mos co-attestation committed under a **distinct** identity
+  (`mos-orchestrator`), and (2) a homelab third-principal verify under its own distinct identity —
+  i.e. three distinct-identity principals of record.
+- The shared signer is a tracked **fleet-infra tooling-gap** (durable fix = per-lane distinct signers),
+  **not a blocker**.
+
+## Scope of this record — byte-clear, NOT fire-authorization
+
+Producing probe evidence **executes** the Gate0 mechanism; a byte-clear is not a fire-authorization.
+This co-attestation clears the **bytes/scope/hygiene**. FIRE remains gated on: **homelab
+third-principal verify** + **Mos transparency-to-Jason** (real-Pi consumes operator model creds inside
+the isolated fixture, scrubbed post-run, never emitted) + **Mos explicit FIRE GO**. Until then: nothing
+banked, WI-3 #830 held at `f4008307` (unmoved), C-hatch armed (if 3× isolation still no-fire /
+wrong-value / isolation-FAIL → possible Case-C → STOP + escalate to Jason).
+
+**Mos verdict: byte-scope + mechanism + hygiene PASS. Co-attestation of record — committed.**
+
+---
+
+## ⚠️ SUPERSEDED — homelab third-principal FAIL raised a stricter bar (evidence-integrity note)
+
+This co-attestation was **byte-clear on the v6 bar ONLY** and self-limited above to *"byte-clear
+ONLY, NOT fire-authorization; FIRE remains gated on homelab third-principal verify."* Homelab (the
+required third principal) subsequently returned **FAIL @2d54a9dd**, and Mos **UPHELD** it — so the v6
+byte-clear this document records is **SUPERSEDED** and does **NOT** authorize FIRE.
+
+Homelab's substantively-correct deepening (accepted as gate-**strengthening**, not softening):
+1. `launch_verified_pi` hashes the launcher then `Popen`/execve **reopens the path** → statement
+   adjacency shrinks but does not eliminate TOCTOU; hashed-snapshot ≠ executed-bytes.
+2. `lease_generation.py` helper is unpinned, loaded from the mutable worktree → HEAD + launcher-pin
+   do not bind the helper bytes.
+3. `p3_generation_broker.py` executes from the mutable worktree unhashed → reviewed broker bytes need
+   not be the evidence-producing bytes.
+
+For a fail-closed DO-178C evidence gate, **hashed==executed must hold on the FULL executed closure**
+(launcher + helper + broker), which v6 (approach (i) adjacency) does not meet. Mos therefore
+**authorized approach (ii) full-closure materialization** (SHA-pin + materialize the full closure into
+a fixture-private 0700/0600 dir or held verified fds, exec from there, launcher+broker consume the same
+pinned helper; re-hash==f4008307 pins immediately before exec, fail-closed). This rides the existing R1
+authorization + Mos adjudication authority (it deepens isolation of already-authorized touch and stays
+inside the fixture temp root → R1 owner tripwire not tripped; no fresh owner window).
+
+**Live target = v7** (materialized-closure harness, forthcoming). `2d54a9dd` / `23c0caca` / this
+co-attestation (`12914d8`) are **SUPERSEDED**. A fresh Mos co-attestation will be committed on v7
+byte-verify PASS. WI-3 #830 remains HELD at `f4008307`; nothing banked; C-hatch armed.
+

docs/compaction-refresh/reviews/GATE0-PROBE3-MOS-COATTEST-v10.md

@@ -0,0 +1,97 @@
+# GATE0 Probe-3 (#827) — Mos byte-scope-verify CO-ATTESTATION (v10 no-site startup closure)
+
+**Principal:** Mos (orchestrator, merge authority for the mosaic-stack governance lane).
+**Committed under a DISTINCT git identity** (`mos-orchestrator@mosaic.local`) — deliberately NOT the
+`ms-lead-reviewer@mosaic.local` lane signer that authored the harness and the §3 review — so this
+record stands as a *distinct-identity* co-attestation. See "Independence".
+
+**Verify class:** independent provider-byte read (`git show <full-40>:path | sha256sum`) plus a
+git-diff byte-comparison of the v9→v10 delta and source inspection of the executed command lines. Not
+a re-build, not a re-run. This SUPERSEDES the v9 co-attestation `f320d075` (byte-clear on the v9
+env-iso + bytecode-pin bar), which was overtaken by homelab's 4th-round FAIL @1c34e3cb
+(site-startup-closure hole) and the resulting B9 bar.
+
+## Package under attestation
+
+| Artifact | Ref |
+|---|---|
+| Branch | `feat/827-gate0-probe` (mosaicstack/stack) |
+| Harness commit-40 | `ce5ba762051354338889959bfce2b0381f4a4e2a` |
+| Harness `p3_d4_focused_run.py` sha256 | `7e14ead89a7b2a297fcc17e7653291b3bcace1d2002a8f90a989db74f6985b6f` (32753 B) |
+| §3-review-v10 commit-40 | `ffc3b573a8258a86e3ece9ef92bac925fb5a7a5b` (parent == harness `ce5ba762`, byte-stable; adds only the review `.md`, +86; ms-secrev-828 authored) |
+| Review path | `docs/compaction-refresh/reviews/GATE0-PROBE3-V10-NOSITE-S3-REVIEW-v10.md` |
+
+**Pinned closure (all 3 sha256 INDEPENDENTLY recomputed by Mos from git objects == pins == embedded harness constants; UNCHANGED from v9):**
+
+| Member | Source (commit:path) | Pin sha256 | Size |
+|---|---|---|---|
+| launcher `launch-runtime.py` | `f4008307:packages/mosaic/framework/tools/lease-broker/launch-runtime.py` | `e950e422…` | 4237 B |
+| helper `lease_generation.py` | `f4008307:packages/mosaic/framework/tools/lease-broker/lease_generation.py` | `061625402f…` | 3769 B |
+| broker `p3_generation_broker.py` | `23c0caca:docs/compaction-refresh/probes/p3_generation_broker.py` | `4db4fef1…` | — |
+
+> `f4008307` (held WI-3 #830 gated head) is **not on origin** — recomputed launcher+helper from the
+> local `stack-cr-wi3-revoke` worktree (HEAD == `f4008307`); broker from origin `23c0caca`.
+
+## Findings — VERDICT: byte-scope + mechanism + hygiene **PASS** (v10 = v9 + B9 no-site)
+
+The v9→v10 delta is **exactly 2 insertions / 0 deletions** (git-diff byte-compared), a `+28 B`
+harness growth **fully accounted** (2 × `        "-S",\n` = 14 B each). Every prior invariant is
+byte-stable — the diff touches nothing outside the two command lists.
+
+**B9 — no-site startup closure (homelab 4th-round finding CLOSED).** Both child command lists now
+carry `-S`, which disables the `site` module entirely (no `.pth` executable lines, no
+`sitecustomize`/`usercustomize`) so no unpinned startup code runs before the exact launcher/broker or
+outside `closure_import_guard`:
+- launcher `launch_verified_pi` (`:515`): `-s` + **`-S`** + `-B`, **no `-I`** (`-I` appears exactly
+  once in the harness, `:553`, the broker only).
+- broker `launch_verified_broker` (`:554`): `-I` + **`-S`** + `-B`.
+
+Homelab's finding was **independently reproduced by Mos** and the fix **empirically verified** on host
+Py3.11.2 (throwaway, not the harness): `[-s -B]`→`no_site=0, site imported` (the v9 hole); `[-I -B]`→
+`no_site=0, site imported` (proves `-I` does **not** imply `-S`); `[-s -S -B]`→`no_site=1`, `site` not
+in `sys.modules`, **and the launcher's bare `from lease_generation import` still resolves** (`sys.path[0]`
+untouched by `-S` → no B6c regression); `[-I -S -B]`→`no_site=1`. The launcher deliberately omits `-I`
+(B6c: on 3.11+ `-I` implies `-P`, dropping the script dir from `sys.path[0]` → sibling import breaks);
+its env isolation comes from the `PiRpc` `env=` allow-list, not `-I`.
+
+**All priors — byte-stable (outside the 2-line delta, re-confirmed from the v9 verify):**
+B5 conjunction (materialize-from-pin / `mkdir(0o700)`+`O_EXCL` no-writer-window / re-hash==pin
+immediately-before-exec); B6 (single pinned helper bound; `closure_import_guard` AST-reject); B6c
+(launcher no `-I`); B7 (broker `env=environment` strict allow-list `:570`); B8 (`reject_pinned_bytecode`
+fail-closed `:498-501` before each consumer `:535/:562` + `PYTHONDONTWRITEBYTECODE=1` `:729` + `-B` on
+both); fidelity asserts (`generation_source=='state-file'`, `state_file_in_fixture_root`,
+`MUTATOR_UNVERIFIED`, `STALE_GENERATION`); `lease_anchor_registered`; BAR1 `GATED_WI_HEAD==f4008307`
+(`:36`) + `merge-base --is-ancestor 66b1e0a0 f4008307` = **YES**; `--runs choices=(3,)`; `-O`-safe
+(0 bare `assert`); allow-list env (0 `os.environ.copy`); single broker (1 def + 1 call); the only
+`shutil.copy2` is the `.pi/agent` credential copy.
+
+**Closure = exactly 3 files, materialized inside the fixture root.** No path escapes the fixture temp
+root; no live/default broker; `.state` fixture-bound. **R1 owner tripwire NOT tripped** — `-S`
+deepens startup-closure isolation of an already-authorized touch; it does not widen the touched surface.
+
+## Independence
+
+Substantive principal-independence of review-v10 is satisfied by an orchestrator-dispatched,
+builder-distinct Opus SECREV (`ms-secrev-828`, byte-only, non-builder, non-Mos). The shared
+`ms-lead-reviewer` git signer on harness+review commits is evidentiary, not substantive — resolved by
+(1) this Mos co-attestation under a **distinct** identity (`mos-orchestrator`) and (2) a homelab
+third-principal verify under its own distinct identity = three distinct-identity principals of record.
+The prior 2-of-3 (`ms-secrev-828` v9 §3 PASS + `f320d075`) does **not** carry — all three re-verify
+this v10 SHA. Shared signer = tracked fleet-infra tooling-gap, not a blocker.
+
+## Scope of this record — byte-clear, NOT fire-authorization
+
+Producing probe evidence **executes** the Gate0 mechanism; a byte-clear is not a fire-authorization.
+This clears **bytes / scope / mechanism / hygiene on the v10 (v9 + B9 no-site) bar**. FIRE remains
+gated on: **homelab third-principal re-verify** (5th round, own distinct identity) + **Mos
+transparency-to-Jason** + **Mos explicit FIRE GO**. The FIRE GO additionally carries an
+**execution-procedure constraint**: the 3× isolation dispatch must launch the runner under
+externally-enforced **`python -I -S -B p3_d4_focused_run.py`** — a self-reexec is too late, the
+harness's own `site` runs before it could re-add `-S` to itself. Until FIRE GO: nothing banked, WI-3
+#830 held at `f4008307` (unmoved), C-hatch armed (fired-rig only: no-fire / wrong-value /
+assertion-FAIL / isolation-FAIL → possible Case-C → STOP + escalate to Jason).
+
+Prior v10-superseded set: `1c34e3cb` / `e1c9a468` / `f320d075` (and transitively the v7 chain).
+
+**Mos verdict: v10 (v9 + B9 no-site) byte-scope + mechanism + hygiene PASS. Co-attestation of
+record — committed.**

docs/compaction-refresh/reviews/GATE0-PROBE3-MOS-COATTEST-v7.md

@@ -0,0 +1,131 @@
+# GATE0 Probe-3 (#827) — Mos byte-scope-verify CO-ATTESTATION (v7 full-closure)
+
+**Principal:** Mos (orchestrator, merge authority for the mosaic-stack governance lane).
+**Committed under a DISTINCT git identity** (`mos-orchestrator@mosaic.local`) — deliberately NOT the
+`ms-lead-reviewer@mosaic.local` lane signer that authored both the harness and the §3 review — so this
+record stands as a *distinct-identity* co-attestation. See "Independence" below.
+
+**Verify class:** independent provider-byte read (guarded `git show <full-40>:path | sha256sum`) plus
+source-level inspection of the executed mechanism. Not a re-build, not a re-run. This SUPERSEDES the v6
+co-attestation `12914d8` (and its SUPERSEDED-note `b6bd0cd`), which was byte-clear on the v6 bar only
+and was overtaken by homelab's third-principal FAIL @2d54a9dd + the resulting stricter full-closure bar.
+
+## Package under attestation
+
+| Artifact | Ref |
+|---|---|
+| Branch | `feat/827-gate0-probe` |
+| Harness commit-40 | `f609a44953f5ae61916805fcb45ca337de00b0b0` |
+| Harness `p3_d4_focused_run.py` sha256 | `0f1bd1b39399b32f243d901230e2d840794a2144edd723a095dab716833a7a9b` (32071 B) |
+| §3-review-v7 commit-40 | `2bba933f67c821899d320a938a9473a73a136422` (adds only the review `.md`; harness parent byte-stable) |
+| Review path | `docs/compaction-refresh/reviews/GATE0-PROBE3-V7-FULLCLOSURE-S3-REVIEW-v7.md` |
+
+**Pinned closure (all 3 sha256 INDEPENDENTLY recomputed by Mos from git objects == pins):**
+
+| Member | Source (commit:path) | Pin sha256 | Size |
+|---|---|---|---|
+| launcher `launch-runtime.py` | `f4008307:packages/mosaic/framework/tools/lease-broker/launch-runtime.py` | `e950e422…` | 4237 B |
+| helper `lease_generation.py` | `f4008307:packages/mosaic/framework/tools/lease-broker/lease_generation.py` | `061625402f…` | 3769 B |
+| broker `p3_generation_broker.py` | `23c0caca:docs/compaction-refresh/probes/p3_generation_broker.py` | `4db4fef1…` | — |
+
+> Note: `f4008307` (the held WI-3 #830 gated head) is **not on origin** — it exists only as a local
+> `git worktree` on the build host. Mos recomputed the launcher+helper pins from that worktree
+> (`stack-cr-wi3-revoke`, HEAD == `f4008307`) rather than passing over a clone-completeness gap. The
+> broker pin was recomputed from origin `23c0caca`.
+
+## Findings — VERDICT: byte-scope + mechanism + hygiene **PASS** (v7 full-closure bar)
+
+Homelab's stricter bar — **hashed==executed on the FULL executed closure (launcher + helper + broker)**
+— is met. Verified at the source, not accepted on the review's assertion:
+
+**B5 conjunction (the load-bearing repair) — HELD, all three legs:**
+- **(a) materialized from pinned git-object bytes, NOT the mutable worktree.** `materialize_closure`
+  fetches each member via `git_object_bytes` (`git show {commit}:{path}`), then
+  `sha256(data) == pin` **fail-closed** (`RuntimeError` on mismatch) before use.
+- **(b) no writable window hash→consume.** `pinned/` is `mkdir(mode=0o700)`; each file is written with
+  `os.open(O_WRONLY|O_CREAT|O_EXCL|O_CLOEXEC, 0o600)` — `O_EXCL` refuses a pre-planted file. No `chmod`,
+  no `os.rename/replace`, no `symlink`, and nothing re-opens a pinned file for write (grep = 0). The
+  pinned bytes are immutable within the fixture threat model between hash and exec.
+- **(c) re-hash == pin IMMEDIATELY before each exec, no interleaved yield.** Launcher: re-hash then
+  `return PiRpc(command,…)` whose `__init__` **first statement** is `subprocess.Popen(command,…)` —
+  zero IO/yield/reopen between. Broker + helper: both re-hashed then `subprocess.Popen` on the next
+  line. Adjacency-alone-without-materialization (the v6 defect) is **absent** — all three exec from
+  `pinned/`.
+
+**B6 — helper pinned AND bound to the SAME single copy.** The broker receives
+`--generation-module {closure.generation}` (the pinned helper); the launcher runs from `pinned/` so its
+`import lease_generation` resolves to the sibling pinned copy via `sys.path[0]`. `closure_import_guard`
+AST-parses every member and raises on any non-stdlib import other than the allowed `lease_generation`
+— proving the dependency closure is complete and no unpinned module can enter at runtime.
+
+**Closure = exactly 3 files, materialized inside the fixture root** (`root / "pinned"`). No path escapes
+the fixture temp root; no live/default broker; `.state` remains fixture-bound. **R1 owner tripwire NOT
+tripped** — this deepened isolation of an already-authorized touch, it did not widen the touched surface.
+
+**Invariants (all INTACT):** BAR1 `GATED_WI_HEAD == f4008307` and `merge-base --is-ancestor 66b1e0a0
+f4008307` = YES (file-backed `.state` revocation fidelity present); BAR2 `.state` =
+`socket_path.parent / generation-{sid}.state`, `state_file_in_fixture_root` + `generation_source ==
+"state-file"` checks present; BAR3 `lease_anchor_registered` / live-path / fixture-socket isolation
+intact. `-O`-safe (0 bare `assert`); ABSENT-sweep (`yolo`/`execRuntime`/`p3_bank`/`promote_p2`/`retry`)
+= 0; single broker (1 def + 1 call site); `--runs choices=(3,)`; allow-list env (0 `os.environ.copy`);
+the only `shutil.copy2` is the legitimate `.pi/agent` credential copy (settings/auth/fd), **not** a
+launcher/helper/broker copy — the v6 copy-to-fixture concern is gone.
+
+## Independence
+
+- **Substantive principal-independence** of review-v7 is satisfied by an orchestrator-dispatched,
+  builder-distinct Opus SECREV (`ms-secrev-828`, byte-only, non-builder) — that IS the substance of
+  Gate-16.
+- The shared `ms-lead-reviewer` git signer on both the harness (`ms-rev-826` build) and the review
+  commit is **evidentiary, not substantive**. It is resolved by (1) this Mos co-attestation under a
+  **distinct** identity (`mos-orchestrator`), and (2) a homelab third-principal verify under its own
+  distinct identity — three distinct-identity principals of record. Tracked fleet-infra tooling-gap
+  (durable fix = per-lane distinct signers), **not a blocker**.
+
+## Scope of this record — byte-clear, NOT fire-authorization
+
+Producing probe evidence **executes** the Gate0 mechanism; a byte-clear is not a fire-authorization.
+This co-attestation clears the **bytes / scope / mechanism / hygiene on the v7 full-closure bar**. FIRE
+remains gated on: **homelab third-principal re-verify** (under its own distinct identity) + **Mos
+transparency-to-Jason** + **Mos explicit FIRE GO**. Until then: nothing banked, WI-3 #830 held at
+`f4008307` (unmoved), C-hatch armed (if the materialized-closure rig still no-fire / wrong-value /
+assertion-FAIL / isolation-FAIL → possible Case-C → STOP + escalate to Jason).
+
+**Mos verdict: v7 full-closure byte-scope + mechanism + hygiene PASS. Co-attestation of record —
+committed.**
+
+---
+
+## ⚠️ SUPERSEDED — homelab v7 third-principal FAIL @f609a449 raised a stricter bar (evidence-integrity note)
+
+This co-attestation was **byte-clear on the v7 full-closure bar ONLY** and self-limited above to
+*"byte-clear NOT fire-authorization; FIRE remains gated on homelab third-principal re-verify."*
+Homelab (the required third principal) subsequently returned **FAIL @f609a449** (static verify, no
+code run), and Mos **UPHELD** it after independently confirming both findings in source — so the v7
+byte-clear this document records is **SUPERSEDED** and does **NOT** authorize FIRE.
+
+Two residual isolation/binding holes WITHIN the materialized closure (both independently reproduced
+by Mos in the harness source; accepted as gate-**strengthening**, not softening):
+1. **Broker child env not isolated.** `launch_verified_broker` (`:551`) calls `Popen` with **no
+   `env=`** (only `PiRpc.__init__` `:50` passes an allow-listed `env`) → the broker child inherits
+   ambient `os.environ` (PYTHONPATH/PYTHONHOME/PYTHONPYCACHEPREFIX). `closure_import_guard` is a
+   static AST check and cannot bind the child's runtime stdlib resolution.
+2. **Executed bytecode-cache outside the pin.** No `PYTHONDONTWRITEBYTECODE`/`-I`/`-B`/`__pycache__`
+   handling anywhere. `exec_module` on the pinned helper writes derived `.pyc` the pin never covers;
+   only the `.py` is re-hashed → executed bytecode ≠ pinned-source-hash.
+
+Both break "hashed==executed on the FULL executed closure" on **fidelity** grounds even in a
+non-adversarial fixture. Mos **authorized the bounded repair** (broker `Popen` with strict
+allow-listed `env=` + `-I` + `PYTHON*` stripped; bytecode-cache suppressed via
+`PYTHONDONTWRITEBYTECODE=1`/`-B` + reject stray `__pycache__`/`.pyc` fail-closed before each
+consumer; launcher sibling-import binding to the pinned helper preserved). This **rides the existing
+(ii)-full-closure authorization + R1 + Mos adjudication** — it deepens isolation/binding of an
+already-authorized touch, stays inside the fixture temp root, no fresh Jason owner-window. It is
+**NOT a Case-C escalation** (no probe fired, no evidence produced — a static pre-fire catch, exactly
+what the review gate is for). Added review bars **B7** (broker child env-isolated) and **B8**
+(executed bytecode pinned-or-suppressed) on top of B5+B6+all priors.
+
+**Live target = v8** (env-isolated + bytecode-pinned harness, forthcoming). `f609a449` /
+`2bba933f` / this co-attestation (`e08ad03`) are **SUPERSEDED**. A fresh Mos co-attestation will be
+committed on v8 byte-verify PASS. WI-3 #830 remains HELD at `f4008307`; nothing banked; C-hatch
+armed; NO FIRE.

docs/compaction-refresh/reviews/GATE0-PROBE3-MOS-COATTEST-v9.md

@@ -0,0 +1,145 @@
+# GATE0 Probe-3 (#827) — Mos byte-scope-verify CO-ATTESTATION (v9 full-closure, env-isolated + bytecode-pinned)
+
+**Principal:** Mos (orchestrator, merge authority for the mosaic-stack governance lane).
+**Committed under a DISTINCT git identity** (`mos-orchestrator@mosaic.local`) — deliberately NOT the
+`ms-lead-reviewer@mosaic.local` lane signer that authored the harness and the §3 review — so this
+record stands as a *distinct-identity* co-attestation. See "Independence".
+
+**Verify class:** independent provider-byte read (`git show <full-40>:path | sha256sum`) plus
+source-level inspection of the executed mechanism and the v7→v9 delta. Not a re-build, not a re-run.
+This SUPERSEDES the v7 co-attestation `e08ad03` (and its SUPERSEDED note `2ae379e`), which was
+byte-clear on the v7 bar and was overtaken by homelab's third-principal FAIL @f609a449 (broker
+env-isolation + executed-bytecode-cache) and the resulting B7/B8 bar.
+
+## Package under attestation
+
+| Artifact | Ref |
+|---|---|
+| Branch | `feat/827-gate0-probe` |
+| Harness commit-40 | `1c34e3cb3172acdcd094e683e847d7c984afc96c` |
+| Harness `p3_d4_focused_run.py` sha256 | `29e5c7bfbe1911b52984bd94c79036bb1200ee82588318367b13c2b1053a0103` (32725 B) |
+| §3-review-v9 commit-40 | `e1c9a4682da2892ca5f5381012caffe1dd7b43a7` (parent == harness `1c34e3cb`, byte-stable; adds only the review `.md`; ms-secrev-828 authored) |
+| Review path | `docs/compaction-refresh/reviews/GATE0-PROBE3-V9-LAUNCHERFIX-S3-REVIEW-v9.md` |
+
+**Pinned closure (all 3 sha256 INDEPENDENTLY recomputed by Mos from git objects == pins == embedded harness constants):**
+
+| Member | Source (commit:path) | Pin sha256 | Size |
+|---|---|---|---|
+| launcher `launch-runtime.py` | `f4008307:packages/mosaic/framework/tools/lease-broker/launch-runtime.py` | `e950e422…` | 4237 B |
+| helper `lease_generation.py` | `f4008307:packages/mosaic/framework/tools/lease-broker/lease_generation.py` | `061625402f…` | 3769 B |
+| broker `p3_generation_broker.py` | `23c0caca:docs/compaction-refresh/probes/p3_generation_broker.py` | `4db4fef1…` | — |
+
+> `f4008307` (held WI-3 #830 gated head) is **not on origin** — recomputed launcher+helper from the
+> local `stack-cr-wi3-revoke` worktree (HEAD == `f4008307`); broker from origin `23c0caca`.
+
+## Findings — VERDICT: byte-scope + mechanism + hygiene **PASS** (v9 = v7 full-closure + B7 + B8)
+
+The v7→v9 delta is **exactly 22 insertions / 2 deletions**, confined to the intended B7+B8+B6c
+surface; every prior invariant is byte-stable (outside the delta) from the v7 verify.
+
+**B7 — broker child env-ISOLATED (homelab finding 1 CLOSED).** `launch_verified_broker` (`:568`) now
+passes `env=environment` (the strict allow-list, `:570`) — the ambient-`os.environ`-inheritance hole
+is gone — AND runs the broker with `-I` (`:552`, isolated: ignores `PYTHON*`/user-site) + `-B`
+(`:553`). Both children are env-controlled: the launcher was already `env=env` at `PiRpc` (`:53`).
+
+**B8 — executed bytecode PINNED/SUPPRESSED (homelab finding 2 CLOSED).** `reject_pinned_bytecode`
+(`:498`) raises `RuntimeError` fail-closed if a `__pycache__` dir or any `*.pyc` exists in the pinned
+dir, and is called before **each** consumer (launcher `:535`, broker `:562`). Bytecode writes are
+disabled via `PYTHONDONTWRITEBYTECODE=1` (`:729`) in the allow-list env **and** `-B` on both command
+lines. No unpinned `.pyc` can be executed; only the pinned `.py` re-hash governs.
+
+**B6c — launcher sibling-import PRESERVED (v8 regression FIXED).** v8 over-applied `-I` to the
+launcher; on Py3.11+ `-I` implies `-P`, dropping the script dir from `sys.path[0]`, so the pinned
+launcher's bare `from lease_generation import` (launch-runtime.py:15) would `ModuleNotFoundError`. v9
+uses `-s` (`:514`) + `-B` (`:515`) on the launcher (NO `-I`) — neither touches `sys.path[0]`, so the
+sibling import still resolves to `pinned/lease_generation.py`. **Mos empirically re-verified on host
+Py3.11.2** (throwaway, not the harness): `-I` launcher → `ModuleNotFoundError`; `-s`+`PYTHONNOUSERSITE`
+→ import OK. The launcher's env isolation comes from the `PiRpc` `env=` allow-list, NOT `-I`, so
+dropping `-I` does **not** reopen B7. My earlier constraint-(c) assumption ("`-I` does not strip the
+script dir") was FALSIFIED for 3.11+; the author≠reviewer gate (ms-secrev-828) caught it — recorded.
+
+**B5 conjunction (load-bearing repair) — HELD, all three legs (byte-stable from v7):**
+(a) materialized from pinned git-object bytes via `materialize_closure`/`git_object_bytes`, `sha256==pin`
+fail-closed; (b) `pinned/` `mkdir(0o700)` + `O_EXCL|O_CLOEXEC` `0o600`, no writable window — now also
+`reject_pinned_bytecode` closes the `.pyc` side-channel; (c) re-hash == pin IMMEDIATELY before each
+exec, no interleaved yield: launcher re-hash (`:538`) → `return PiRpc(command,…)` whose `__init__`
+first statement is `Popen` (`:50`); broker re-hash (`:563`) + helper re-hash (`:566`) → `Popen`
+(`:568`) on the next line.
+
+**B6 — single pinned helper, complete closure.** Broker gets `--generation-module {closure.generation}`;
+launcher resolves `import lease_generation` to the sibling pinned copy via `sys.path[0]`.
+`closure_import_guard` (`:351`, called `:433`) AST-rejects any non-stdlib import other than
+`lease_generation`. Single broker: `launch_verified_broker` 1 def (`:543`) + 1 call (`:766`).
+
+**Invariants (all INTACT):** BAR1 `GATED_WI_HEAD == f4008307` (`:36`) and `merge-base --is-ancestor
+66b1e0a0 f4008307` = YES (file-backed `.state` revocation fidelity present); fidelity
+`generation_source=='state-file'` (`:639`), `state_file_in_fixture_root` (`:641`),
+`MUTATOR_UNVERIFIED` (`:650`), `STALE_GENERATION` (`:651`); `lease_anchor_registered` (`:593`);
+`-O`-safe (0 bare `assert`); `--runs choices=(3,)` (`:838`); allow-list env (0 `os.environ.copy`);
+ABSENT-sweep (`yolo`/`execRuntime`/`p3_bank`/`promote_p2`/`retry`) = 0; the only `shutil.copy2`
+(`:708`) is the `.pi/agent` credential copy, not a closure copy.
+
+**Closure = exactly 3 files, materialized inside the fixture root.** No path escapes the fixture temp
+root; no live/default broker; `.state` fixture-bound. **R1 owner tripwire NOT tripped** — B7/B8
+deepen isolation/binding of an already-authorized touch, they do not widen the touched surface.
+
+## Independence
+
+Substantive principal-independence of review-v9 is satisfied by an orchestrator-dispatched,
+builder-distinct Opus SECREV (`ms-secrev-828`, byte-only, non-builder, non-Mos). The shared
+`ms-lead-reviewer` git signer on harness+review commits is evidentiary, not substantive — resolved by
+(1) this Mos co-attestation under a **distinct** identity (`mos-orchestrator`) and (2) a homelab
+third-principal verify under its own distinct identity = three distinct-identity principals of record.
+Shared signer = tracked fleet-infra tooling-gap (durable fix = per-lane distinct signers), not a blocker.
+
+## Scope of this record — byte-clear, NOT fire-authorization
+
+Producing probe evidence **executes** the Gate0 mechanism; a byte-clear is not a fire-authorization.
+This clears **bytes / scope / mechanism / hygiene on the v9 (full-closure + B7 + B8) bar**. FIRE
+remains gated on: **homelab third-principal re-verify** (4th round, own distinct identity) + **Mos
+transparency-to-Jason** + **Mos explicit FIRE GO**. Until then: nothing banked, WI-3 #830 held at
+`f4008307` (unmoved), C-hatch armed (materialized-closure rig still no-fire / wrong-value /
+assertion-FAIL / isolation-FAIL → possible Case-C → STOP + escalate to Jason).
+
+**Mos verdict: v9 full-closure + B7 + B8 byte-scope + mechanism + hygiene PASS. Co-attestation of
+record — committed.**
+
+---
+
+## ⚠️ SUPERSEDED — homelab v9 4th-round FAIL @1c34e3cb raised a stricter *startup-closure* bar
+
+This co-attestation was **byte-clear on the v9 (env-iso + bytecode-pin) bar ONLY** and self-limited
+above to *"byte-clear NOT fire-authorization; FIRE remains gated on homelab 4th-round re-verify."*
+Homelab (the required third principal) returned **FAIL @1c34e3cb** (static, nothing executed), and Mos
+**UPHELD** it after independently confirming the finding in-source AND empirically on host Py3.11.2 —
+so the v9 byte-clear this document records is **SUPERSEDED** and does **NOT** authorize FIRE.
+
+**Residual startup-closure hole (empirically reproduced by Mos; accepted as gate-STRENGTHENING):**
+neither child carries `-S`, so CPython imports the `site` module **before** the script runs. `-s`
+(launcher) suppresses only *user*-site; `-I` (broker) implies `-s -E -P` but **NOT** `-S`. Proven:
+
+    [-s  -B ]  no_site=0  site_imported=True    ← v9 launcher: site runs
+    [-I  -B ]  no_site=0  site_imported=True    ← v9 broker: -I does NOT imply -S
+    [-s -S -B] no_site=1  site_imported=False   ← v10 launcher fix (sibling import STILL resolves)
+    [-I -S -B] no_site=1  site_imported=False   ← v10 broker fix (additive)
+
+System-site executable `.pth` lines + sitecustomize/usercustomize can therefore run **unpinned startup
+code** before the exact launcher/broker and **outside** `closure_import_guard`, while every hash +
+`reject_pinned_bytecode` + import-guard still pass — defeating hashed==executed on the full *startup*
+closure (strictly wider than the module-import closure v9 cleared). A genuine fidelity hole for a
+fail-closed DO-178C evidence gate.
+
+Mos **authorized the bounded v10 repair**: add `-S` to the **launcher** (keep `-s -B`, NOT `-I`) and
+to the **broker** (keep `-I -B`) — a minimal 2-line delta; no B6c regression (launcher `-s -S -B`
+sibling import empirically intact; `-S` does not touch `sys.path[0]`). Added review bar **B9**
+(no-site startup closure). This **rides the existing (ii)-full-closure authorization + R1 + Mos
+adjudication** (deepens startup-closure isolation of an already-authorized touch, inside the fixture
+temp root, no fresh Jason owner-window) and is **NOT a Case-C escalation** (static pre-fire catch, no
+probe fired). A separate **FIRE-time** constraint is captured: the 3× isolation dispatch must launch
+the runner under externally-enforced `python -I -S -B` (a self-reexec is too late).
+
+**Live target = v10** (no-site harness, forthcoming). `1c34e3cb` / `e1c9a468` / this co-attestation
+(`f320d075`) are **SUPERSEDED**; the prior 2-of-3 (ms-secrev-828 v9 §3 PASS + `f320d075`) does NOT
+carry — all three distinct-identity principals re-verify the new v10 SHA. A fresh Mos co-attestation
+will be committed on v10 byte-verify PASS. WI-3 #830 remains HELD at `f4008307`; nothing banked;
+C-hatch armed (fired-rig only); NO FIRE.

docs/compaction-refresh/reviews/GATE0-PROBE3-NEW56-S3-REVIEW-v6.md

@@ -0,0 +1,82 @@
+# Gate0 Probe-3 (D4) NEW-5/NEW-6 Closure — §3-Conformance Review v6
+
+**Verdict: ✅ PASS**
+
+## Pin (G1 — reviewed object, mandatory)
+
+- **Reviewed object = `2d54a9dd14cb924701b2ae4ed72dae4df760c4e3`** (harness commit, branch `feat/827-gate0-probe`, approach-**(i)** build; supersedes the reverted (ii) copy-to-fixture builds `7ff63cd5`/`6164dc07`, which were NOT reviewed to a verdict).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py` — sha256 (pushed provider bytes, `-o FILE`, FULL-40 ref, verified before trust): `15a154df55273f51301763a984485fd63813f6d1f05d2728abb9fb8b9c040b1a` (27366 bytes, no not-found sentinel).
+- **Co-reviewed fixture broker:** `p3_generation_broker.py` sha256 `4db4fef1ac6658a8ca79ad5091cefc901d2aa26003265c3d6726c294cf895cad` — **byte-identical to v5** (unchanged by this delta).
+
+## Principal-independence attestation (Mos independence ruling — process of record)
+
+This review is produced by a **distinct Opus SECREV session, orchestrator-dispatched** — the **`ms-secrev-828`
+reviewer lane, dispatched by `mosaic-100`** — **byte review only, ran nothing**, and **did NOT build** this harness
+(builder = ms-rev-826). Author ≠ reviewer (Gate-16). This is one of three principals: **Mos commits his own
+distinct-identity byte-scope-verify co-attestation at v-final**, and **homelab's independent verify is the third
+principal**. (The `ms-lead-reviewer` **Git signer identity** shared across published review commits is a git-signer
+question routed to Mos; it does not bear on this lane's process/dispatch independence, attested here.)
+
+## NEW-5 CLOSED — approach (i): exact-byte pin, adjacent re-hash, exec in place
+
+- **Exact-byte sha256 is the trust anchor, NOT substring heuristics.** Launcher bytes are read from the immutable
+  git object (`git show f4008307:<path>`) and gated on `sha256(launcher_bytes) == GATED_LAUNCHER_SHA256`
+  (`e950e422…`) (:354). The `behavior_markers` `in`-checks (:364-372) are explicitly commented "the exact launcher
+  digest above is the trust anchor. These marker checks are diagnostic belt-and-suspenders only, never a substitute
+  for the pin" (:362-363). The old ordered `.find()` heuristic (`register < initialize < execute`, min<0) is **gone**.
+- **Final re-hash immediately adjacent to `Popen`, no interleaved yield.** `launch_verified_pi` assembles `command`,
+  then — as the statement **immediately before** `return PiRpc(command, …)` (which performs the `Popen`) — re-hashes
+  the launcher: `if hashlib.sha256(launcher.read_bytes()).hexdigest() != GATED_LAUNCHER_SHA256: raise` (:411-412),
+  `return PiRpc(...)` (:413). **No harness-controlled step (no `wait_path`, no broker spawn) sits between the re-hash
+  and the exec** — the broker `Popen` + `wait_path` occur *before* `launch_verified_pi` is called (:611-621). Window
+  narrowed to the fork/exec itself.
+- **Exec stays IN PLACE at the pinned f4008307-worktree path.** The precondition returns the worktree paths
+  `gated_root / launcher_relative`, `gated_root / generation_relative` (:378); Pi execs `str(launcher)` = that
+  worktree launch-runtime.py (:390,:621), and the broker `--generation-module` = the worktree lease_generation.py
+  (:614). The reverted (ii) machinery is **gone**: `grep pinned-lease-broker / PYTHONPATH / fixture_launcher /
+  fixture_generation / write_bytes == 0`. Launcher import resolution and the file-backed fidelity surface are
+  therefore **unperturbed** (this is the lower-risk approach Mos mandated over copy-to-fixture).
+
+## NEW-6 CLOSED — portable, validated, off-by-one gone
+
+`GATED_WI_ROOT` is no longer the off-by-one `HERE.parents[3].parent / "stack-cr-wi3-revoke"`. It is resolved by
+`resolve_gated_wi_root()` (:257-307): an explicit `GATED_WI_ROOT` env override, else **repo-relative** `git worktree
+list --porcelain` (from `repository_root()`, first parent containing `.git`) selecting the **unique** worktree whose
+`HEAD == f4008307` **and** `branch == refs/heads/feat/830-compaction-revoke` (raise if ambiguous/absent). It then
+**fail-closes** unless `gated_root.is_dir()`, `git rev-parse --is-inside-work-tree == "true"` (:304-305), and
+`HEAD == GATED_WI_HEAD` (:306-307). Independently recomputed on this host (git query, harness not run): it resolves
+to the real worktree **`/home/hermes/agent-work/stack-cr-wi3-revoke`**. Portable + validated; the off-by-one is gone.
+
+## Full v4/v5 carry-over re-sweep (byte-stable vs `7f975b95` except the NEW-5/6 delta)
+
+`diff 7f975b95 → 2d54a9dd` confines changes to launcher resolution (NEW-6) + adjacent-rehash-exec-in-place (NEW-5);
+nothing else moved. Re-swept intact: **creds-scrub** (`scrub_fixture_credentials` + outermost `finally`); **`source-invalid`
+ABSENT** (grep=0 both files); **fidelity file-backed** unperturbed (broker `read_runtime_generation`/`bump_runtime_generation`
+on the fixture `.state`; `assert_d4` `generation_source=="state-file"` + `state_file_drives_lifecycle` +
+`state_file_in_fixture_root` + `new→MUTATOR_UNVERIFIED`/`prior→STALE_GENERATION`); **`lease_anchor_registered`** INTACT
+(event + `hex-256`); **live-path** gated launcher; **fail-closed precondition**; **fixture-socket isolation**; **`-O`-safe**
+(0 bare `assert`, PASS derived); **allow-list env** (0 `os.environ.copy`); **`--runs choices=(3,)`**; **single p3 broker**
+(broker byte-identical to v5). **ABSENT sweep = 0** (P5/P6/P2-bank/retry-launder/mosaic-yolo/execRuntime/pi_gate0/run_open/
+atomic; extension actions only bump/lifecycle/authorize/promote; no exec-at-import). **Beyond-R1 tripwire: not tripped** —
+exec is in place, imports and the file-backed observation surface untouched; no isolation crossing.
+
+## Verdict
+
+**PASS @ `2d54a9dd`.** NEW-5 (approach (i): exact-byte sha256 pin as trust anchor; adjacent re-hash immediately
+before `Popen` with no interleaved yield; exec in place at the pinned f4008307-worktree path; (ii) copy-to-fixture/
+PYTHONPATH machinery reverted) and NEW-6 (portable, validated, off-by-one-gone root resolution) are both **closed**;
+the full v4/v5 carry-over holds byte-stable except the two intended surfaces; ABSENT sweep is 0; the R1 file-backed
+fidelity surface is unperturbed. Zero out-of-scope surface.
+
+**Findings: none.**
+
+## Scope reminder (not a finding)
+
+Producing this evidence **executes** the Gate0 mechanism (§3/§5). This review clears **bytes** only; **FIRE remains
+separately gated on Mos's explicit post-clear GO** and is not authorized by this review.
+
+---
+
+**Reviewer:** distinct Opus SECREV session (`ms-secrev-828` lane, dispatched by `mosaic-100`), Gate-16 author≠reviewer,
+byte review only; ran nothing; did not build.
+**Reviewed object (pin):** `2d54a9dd14cb924701b2ae4ed72dae4df760c4e3` · harness sha256 `15a154df55273f51301763a984485fd63813f6d1f05d2728abb9fb8b9c040b1a`.

docs/compaction-refresh/reviews/GATE0-PROBE3-V10-NOSITE-S3-REVIEW-v10.md

@@ -0,0 +1,86 @@
+# Gate0 Probe-3 (D4) No-Site Startup Closure — §3-Conformance Review v10
+
+**Verdict: ✅ PASS**
+
+## Pin (GUARD 1 — reviewed object)
+
+- **Reviewed object = `ce5ba762051354338889959bfce2b0381f4a4e2a`** (harness commit, branch `feat/827-gate0-probe`).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py` — sha256 (pushed provider bytes, `-o FILE`, FULL-40 ref, verified before trust): `7e14ead89a7b2a297fcc17e7653291b3bcace1d2002a8f90a989db74f6985b6f` (32753 bytes, no not-found sentinel).
+- **Closure pins (unchanged):** launcher `e950e422…` @f4008307 · helper `061625402f08488eac47acd23272904e71fd1a71fd15b3bdab158632c801be4c` @f4008307 · broker `4db4fef1…` @23c0caca.
+
+## Independence (GUARD 2 — principal-independence attestation)
+
+Distinct Opus SECREV session, orchestrator-dispatched — the **`ms-secrev-828` reviewer lane, dispatched by
+`mosaic-100`** — **byte review only, ran nothing** (harness/broker not executed); did **not** build this harness
+(builder = ms-rev-826); is not Mos; distinct principal from both. This re-verifies from scratch on the v10 SHA after
+homelab's 4th-round FAIL @`1c34e3cb` (no `-S` → `site` startup-closure hole) superseded my v9 PASS + Mos's co-attest.
+The `-S`/`-s`/`-I` behavior checks below use a *throwaway* script to observe interpreter startup — not the harness.
+
+## ★ B9 — No-site startup closure (the homelab 4th-round FAIL)
+
+The delta vs `1c34e3cb` is **exactly two `-S` insertions**, byte-confirmed by `diff` (nothing else; +28 B fully
+accounted by the two `        "-S",\n` lines):
+
+- **(i) Launcher command** (`launch_verified_pi`, :512-516): `sys.executable, "-s", "-S", "-B", str(launcher), …` —
+  carries `-s` + **`-S`** + `-B`, and **no `-I`**.
+- **(ii) Broker command** (`launch_verified_broker`, :551-554): `sys.executable, "-I", "-S", "-B", str(broker_path), …`
+  — carries `-I` + **`-S`** + `-B`.
+- **(iii) `site` not imported at child startup** — empirically confirmed (Python 3.11.2, throwaway script):
+  `python3 -s -S -B main.py` → `sys.flags.no_site == 1`, `'site' in sys.modules == False`; `python3 -I -S -B main.py`
+  → `no_site == 1`. So system-site `.pth` executable lines and `sitecustomize`/`usercustomize` **cannot run unpinned
+  startup code** before the pinned launcher/broker. (Contrast without `-S`: `python3 -s -B` → `no_site == 0`, `site`
+  imported — the exact v9 hole this closes.)
+- **(iv)** No harness reliance on any site-injected path/hook (env is the constructed allow-list; children execute
+  pinned bytes).
+- **(v) `-S` does not touch `sys.path[0]`** (unlike `-I`/`-P`) — empirically confirmed: `python3 -s -S -B main.py`
+  keeps `sys.path[0]` = the script's directory, so the launcher's bare `from lease_generation import
+  initialize_runtime_generation` (`f4008307:launch-runtime.py:15`) **still binds `pinned/lease_generation.py`** with
+  `-S` present. The broker's explicit `--generation-module` import (via `importlib`) binds the pinned helper
+  regardless of `sys.path`/site, so `-I -S` is correct there.
+- **(vi) Delta = exact 2-line `-S` only** vs `1c34e3cb` (git-diff/byte-compared, not accepted on assertion).
+
+## All prior bars — byte-stable (delta was only the two `-S` lines)
+
+- **B6(c):** launcher still carries no `-I`; sibling import binds `pinned/` (confirmed above with `-S` present). ✅
+- **B7:** broker `Popen` `env=environment` (allow-list, **not** `os.environ`; no `PYTHONPATH`/`PYTHONHOME`/
+  `PYTHONPYCACHEPREFIX`) + `-I`. ✅
+- **B8:** `reject_pinned_bytecode` fail-closed before each consumer; `PYTHONDONTWRITEBYTECODE=1` + `PYTHONNOUSERSITE=1`
+  in env; `-B` on both children. ✅
+- **B5:** 3-leg conjunction — materialize each of launcher/helper/broker from git-object bytes with `sha256==pin`
+  fail-closed; `pinned/` `0o700` in fixture root, files `O_EXCL 0o600` (no writable window); re-hash `==pin`
+  immediately before each `Popen`; launcher + broker consume the same single pinned helper. ✅
+- **B6:** `closure_import_guard` AST present; single pinned helper; broker `--generation-module = closure.generation`. ✅
+- **Fidelity:** extension bumps `generation-{sid}.state` via `MOSAIC_LEASE_GENERATION_FILE` (not in-mem); broker
+  `read_runtime_generation`; `assert_d4` `generation_source=="state-file"` / `state_file_in_fixture_root` /
+  `new→MUTATOR_UNVERIFIED` / `prior→STALE_GENERATION`; `.state` fixture-root-bound. ✅
+- **Traceability:** `GATED_WI_HEAD == f4008307` + `merge-base --is-ancestor 66b1e0a0 f4008307`. ✅
+- `lease_anchor_registered` + `hex-256` INTACT; LIVE-PATH (pinned gated launcher); single p3 broker;
+  promotion=fixture-only; `--runs choices=(3,)`; `-O`-safe (0 bare `assert`); `copy2` = creds-only; allow-list env
+  (0 `os.environ.copy`). ✅
+
+## ABSENT sweep
+
+P5/P6/P2-bank/retry-launder/mosaic-yolo/execRuntime = 0; `source-invalid` = 0; no live/real-broker path; no `.state`
+outside fixture root; no exec-at-import (`__main__`-guarded); no adjacency-only-exec-from-worktree; the only change is
+the authorized `-S` no-site isolation-deepening (no mechanism change, no scope-widen); `-O`-safe.
+
+## Verdict
+
+**PASS @ `ce5ba762`.** B9 (no-site startup closure) is closed — both children carry `-S`, `site` is not imported at
+startup (so system-site `.pth`/`sitecustomize` cannot execute unpinned code before the pinned launcher/broker),
+`-S` leaves `sys.path[0]` intact so the launcher sibling import and the broker explicit-path import both still bind
+the pinned helper, and the delta vs `1c34e3cb` is exactly the two `-S` insertions. All prior bars (B5/B6/B6c/B7/B8/
+fidelity/traceability/lease_anchor/live-path/single-broker/promotion/`--runs`/`-O`-safe) are byte-stable. Zero
+out-of-scope surface. **Findings: none.**
+
+## Scope reminder (not a finding)
+
+Producing this evidence **executes** the Gate0 mechanism (§3/§5). This review clears **bytes** only; **FIRE remains
+separately gated on Mos's explicit post-clear GO**, his byte-scope-verify co-attestation, and homelab's
+third-principal verify — not authorized by this review.
+
+---
+
+**Reviewer:** distinct Opus SECREV session (`ms-secrev-828` lane, dispatched by `mosaic-100`), Gate-16 author≠reviewer,
+byte review only; ran nothing.
+**Reviewed object (pin):** `ce5ba762051354338889959bfce2b0381f4a4e2a` · harness sha256 `7e14ead89a7b2a297fcc17e7653291b3bcace1d2002a8f90a989db74f6985b6f`.

docs/compaction-refresh/reviews/GATE0-PROBE3-V7-FULLCLOSURE-S3-REVIEW-v7.md

@@ -0,0 +1,120 @@
+> ⚠ SUPERSEDED by v8 (homelab 3rd-principal FAIL @f609a449: broker env-inherit + unpinned .pyc; PASS overtaken by stricter B7+B8 bar). This v7 PASS record is NOT fire-authorization.
+
+# Gate0 Probe-3 (D4) Full-Closure Materialization — §3-Conformance Review v7
+
+**Verdict: ✅ PASS** *(superseded — see banner above)*
+
+## Pin (GUARD 1 — reviewed object)
+
+- **Reviewed object = `f609a44953f5ae61916805fcb45ca337de00b0b0`** (harness commit, branch `feat/827-gate0-probe`).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py` — sha256 (pushed provider bytes, `-o FILE`, FULL-40 ref, verified before trust): `0f1bd1b39399b32f243d901230e2d840794a2144edd723a095dab716833a7a9b` (32071 bytes, no not-found sentinel).
+- **Closure pins (independently recomputed from the git objects):**
+  - launcher `packages/mosaic/framework/tools/lease-broker/launch-runtime.py` @ `f4008307` = `e950e4224e280f16979d90cabb89aa1896c5ee28bed2df957e14d018d43cda82` ✓
+  - **helper** `packages/mosaic/framework/tools/lease-broker/lease_generation.py` @ `f4008307` = `061625402f08488eac47acd23272904e71fd1a71fd15b3bdab158632c801be4c` ✓
+  - **broker** `docs/compaction-refresh/probes/p3_generation_broker.py` @ `23c0caca` = `4db4fef1ac6658a8ca79ad5091cefc901d2aa26003265c3d6726c294cf895cad` ✓
+
+## Independence (GUARD 2 — principal-independence attestation)
+
+This review is produced by a **distinct Opus SECREV session, orchestrator-dispatched — the `ms-secrev-828`
+reviewer lane, dispatched by `mosaic-100`** — **byte review only, ran nothing**, that **did NOT build** this harness
+(builder = ms-rev-826) and **is not Mos**. Three distinct principals: this reviewer, the builder, and Mos (whose
+own distinct-identity byte-scope-verify follows); homelab's independent verify is a further principal — it is
+homelab's third-principal FAIL @`2d54a9dd` (upheld by Mos) that correctly retired the approach-(i) adjacency
+re-hash and authorized this full-closure. v6/`2d54a9dd`/`23c0caca`/`12914d8` are superseded.
+
+## Why v7 (the reopen-after-hash hole)
+
+Approach (i) re-hashed the launcher then let `Popen` **reopen the worktree path** — hashed-snapshot ≠ executed-bytes
+(the worktree file is a shared, same-UID-mutable path). Statement adjacency alone did not bind. v7 closes it for the
+**full project-code closure** (launcher + `lease_generation.py` helper + `p3_generation_broker.py`).
+
+## B5 — HASHED == EXECUTED on the full closure (binding conjunction, stated verbatim)
+
+The reopen-after-hash shape is unavoidable for imported/exec'd files, so closure rests on the **conjunction of all
+three legs**, each byte-verified here:
+
+> **(a)** bytes are materialized **from the pinned git-object @ `f4008307`** (helper/launcher) and **@ `23c0caca`**
+> (broker) — `git show <commit>:<path>`, the trusted immutable object, **never the mutable worktree file**; **AND**
+> **(b)** into a **fixture-private `0o700` dir with `0o600` files created via `O_CREAT|O_EXCL`** — no writer exists in
+> the threat model between hash and exec; **AND** **(c)** each member is **re-hashed == its pin IMMEDIATELY before
+> exec/import, fail-closed (`RuntimeError`)**.
+
+Byte evidence:
+- **(a)** `git_object_bytes(git_root, commit, relative)` = `git show <commit>:<path>` (:322-327); `materialize_closure`
+  reads all three members from git objects and asserts `sha256(data) == digest` else `RuntimeError` (:415-433). Worktree
+  working-tree files are never read.
+- **(b)** `pinned = root / "pinned"; pinned.mkdir(mode=0o700)` (:435-436); `write_pinned_file` uses
+  `os.open(path, O_WRONLY|O_CREAT|O_EXCL|O_CLOEXEC, 0o600)` (:379-382). **No `os.chmod`/`os.rename`/`shutil.move`
+  anywhere** (grep=0); `O_EXCL` refuses a pre-planted file/symlink, so no symlink-follow or hijack gap; the dir is a
+  fresh per-run `mkdtemp` child, owner-only. **No code re-opens the pinned files for write between materialize and
+  consume** — there is no writable window.
+- **(c)** launcher re-hash `sha256(launcher.read_bytes()) == GATED_LAUNCHER_SHA256` is the statement immediately before
+  `return PiRpc(command,…)` (:528-530); broker **and** helper re-hashes (`== GATED_BROKER_SHA256`,
+  `== GATED_GENERATION_SHA256`) are the two statements immediately before `return subprocess.Popen(command,…)`
+  (:546-551). No interleaved harness yield.
+
+Adjacency-only exec-from-worktree is **absent** for every member (all three exec/import from `pinned/`; grep worktree-exec=0).
+
+## B6 — helper + broker pinned and bound to execution (one shared helper)
+
+`materialize_closure` writes exactly **one** `pinned/lease_generation.py` (:442). The broker executes the **pinned**
+broker with `--generation-module = closure.generation` = that pinned helper (`launch_verified_broker`, :533-551, called
+:746-747). The launcher executes the **pinned** launcher (`python3 pinned/launch-runtime.py`), whose
+`import lease_generation` resolves via `sys.path[0]` = the script's own `pinned/` dir to the **same** sibling
+`pinned/lease_generation.py`. Launcher-import and broker-`--generation-module` therefore resolve the **same single
+pinned helper copy**, not two copies and not the worktree. Worktree helper/broker are not re-read at runtime.
+
+**Closure-import guard:** `closure_import_guard` AST-parses each member and refuses any non-stdlib import outside the
+allow-set `{"lease_generation"}` (and any relative import) → `RuntimeError` (:341-364). The 3-member closure is
+therefore provably complete — no unpinned project-code dependency can slip in.
+
+## BAR1 — Traceability
+
+`GATED_WI_HEAD == f4008307`; the precondition asserts `git merge-base --is-ancestor 66b1e0a0 f4008307` (:315-330),
+independently confirmed **YES** — the pinned launcher forward-contains the `66b1e0a0` file-backed generation mechanism.
+
+## BAR2 — Fidelity file-backed, `.state` in fixture root, UNTOUCHED
+
+`pinned/` holds **code bytes only** (launcher/helper/broker). The `.state` generation file is written by the launcher
+to `socket_path.parent` (the fixture root), **not** `pinned/`. The broker (pinned, byte-identical `4db4fef1`) still
+enforces `generation_environment` raising if `state_path.parent != socket_path.parent` (grep=2), and `assert_d4`
+still checks `state_file_source == "state-file"` / `state_file_drives_lifecycle` / `state_file_in_fixture_root` +
+`new→MUTATOR_UNVERIFIED` / `prior→STALE_GENERATION` (grep=4, unchanged). The v7 change did not move `.state` into
+`pinned/` or perturb these asserts.
+
+## BAR3 — Carry-over
+
+(a) **live-path:** Pi launched via `python3 pinned/launch-runtime.py --runtime pi -- pi …` (gated register-before-exec);
+`mosaic yolo`/`execRuntime` = 0. (b) **fail-closed precondition:** `gated_launcher_precondition` (resolve+materialize+
+verify) runs before any launch, fail-closed. (c) **fixture-socket isolation:** `MOSAIC_LEASE_BROKER_SOCKET` = per-run
+fixture socket; single pinned p3 broker serves `register_anchor`; no live/default broker reachable; non-destructive.
+(d) **`lease_anchor_registered` INTACT:** event + `session_id_shape=="hex-256"` unchanged (broker byte-identical);
+`assert_d4` folds it into the single-identity set — not deleted/softened/optional/repointed.
+
+## Re-confirm + ABSENT sweep
+
+Spawns ONLY the single pinned p3 broker; promotion=fixture-only; full D4 asserts; `--runs choices=(3,)`; allow-list
+env (0 `os.environ.copy`); **`-O`-safe** (all new checks `RuntimeError`, **0 bare `assert`**); creds-scrub intact;
+non-destructive (fixture tempdir only); deterministic (git objects + fixed pins); closure-import guard present.
+**ABSENT = 0:** P5/P6/P2-bank/retry-launder/mosaic-yolo/execRuntime/pi_gate0; `source-invalid` grep=0; no live/real-broker
+path; no `.state`/gen path outside the fixture root; no extra broker/socket; no exec-at-import (`__main__`-guarded); no
+adjacency-only exec-from-worktree for any member; the only mechanism change is materialization; no scope-widen.
+
+## Verdict
+
+**PASS @ `f609a449`.** B5 (full-closure hashed==executed via the (a)+(b)+(c) conjunction with no writable window),
+B6 (one shared pinned helper bound to both launcher-import and broker-`--generation-module`; complete closure), BAR1,
+BAR2 (fidelity `.state`-in-fixture-root untouched), and BAR3 all hold, with zero out-of-scope surface. **Findings: none.**
+
+## Scope reminder (not a finding)
+
+Producing this evidence **executes** the Gate0 mechanism (§3/§5). This review clears **bytes** only; **FIRE remains
+separately gated on Mos's explicit post-clear GO**, his v-final byte-scope-verify co-attestation, and homelab's
+third-principal verify — not authorized by this review.
+
+---
+
+**Reviewer:** distinct Opus SECREV session (`ms-secrev-828` lane, dispatched by `mosaic-100`), Gate-16 author≠reviewer,
+byte review only; ran nothing; did not build.
+**Reviewed object (pin):** `f609a44953f5ae61916805fcb45ca337de00b0b0` · harness sha256 `0f1bd1b39399b32f243d901230e2d840794a2144edd723a095dab716833a7a9b`.
+**Pinned closure:** launcher `e950e422…` @f4008307 · helper `06162540…be4c` @f4008307 · broker `4db4fef1…` @23c0caca.

docs/compaction-refresh/reviews/GATE0-PROBE3-V8-ENVBYTECODE-S3-REVIEW-v8.md

@@ -0,0 +1,92 @@
+> ⚠ SUPERSEDED by v9: the reviewed harness `a92ad090` is superseded by the narrow fix `1c34e3cb` (my v8 B6(c) FAIL — `-I` on the launcher — was remediated by `-I`→`-s` + `PYTHONNOUSERSITE=1`; re-review v9 = PASS). This v8 FAIL record pertains to the superseded commit.
+
+# Gate0 Probe-3 (D4) Broker Env-Isolation + Bytecode Binding — §3-Conformance Review v8
+
+**Verdict: ❌ FAIL** (B7 and B8 land correctly, but the same change breaks **B6(c)**: the launcher is run with `-I`, which strips the script directory from `sys.path` on Python 3.11+, so its bare `import lease_generation` cannot resolve the pinned helper — empirically confirmed).
+
+## Pin (GUARD 1 — reviewed object)
+
+- **Reviewed object = `a92ad090ae3828c643f961c7628d809b8521185f`** (harness commit, branch `feat/827-gate0-probe`).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py` — sha256 (pushed provider bytes, `-o FILE`, FULL-40 ref, verified before trust): `915ebeb5aeab108cb60c5f629c1db520623ab4914eed427ca34ee66f9aa08390` (32614 bytes, no not-found sentinel).
+- **Closure pins (unchanged from v7):** launcher `e950e422…` @f4008307 · helper `061625402f08488eac47acd23272904e71fd1a71fd15b3bdab158632c801be4c` @f4008307 · broker `4db4fef1…` @23c0caca.
+
+## Independence (GUARD 2 — principal-independence attestation)
+
+Distinct Opus SECREV session, orchestrator-dispatched — the **`ms-secrev-828` reviewer lane, dispatched by
+`mosaic-100`** — **byte review only, ran nothing** (the harness/broker were not executed); did **not** build this
+harness (builder = ms-rev-826); is not Mos. This verdict is my own. (The `-I` semantics check below runs a *throwaway*
+two-line script to observe the interpreter's `sys.path` behavior — it does not run the harness, broker, or any part of
+the reviewed closure.)
+
+## 🔴 BLOCKING FINDING — B6(c) broken: `-I` on the launcher strips the pinned-helper import path
+
+**File:line — `p3_d4_focused_run.py:512`** (the `"-I"` added to `launch_verified_pi`'s launcher command).
+
+The pinned launcher `launch-runtime.py` @`f4008307` imports its helper with a **bare top-level import**:
+`from lease_generation import initialize_runtime_generation` (launcher line 15) — no `sys.path` manipulation. Under
+v7 this bound because `python3 pinned/launch-runtime.py` put the script's directory (`pinned/`) at `sys.path[0]`, so
+the sibling `lease_generation` resolved to `pinned/lease_generation.py`.
+
+v8 now runs the launcher as `python3 -I -B pinned/launch-runtime.py …` (:512-513). **`-I` implies `-P` (Python 3.11+),
+which does NOT prepend the script's directory to `sys.path`.** Empirically confirmed on this host (Python 3.11.2),
+using a throwaway script (not the harness):
+
+```
+python3 -I -B main.py  → sys.path[0] = '/usr/lib/python311.zip'
+                          import sibling → ModuleNotFoundError: No module named '…'
+python3    -B main.py  → sys.path[0] = '<script dir>'  → sibling import: OK
+```
+
+Therefore, at FIRE on Python 3.11+, the launcher's line-15 `from lease_generation import …` raises
+`ModuleNotFoundError` at module load — the pinned helper does **not** resolve (neither pinned nor worktree; the import
+simply fails). **B6(c) — "launcher sibling-import to `pinned/` via `sys.path[0]` STILL BINDS" — does not hold.** The
+build report's assertion "`-I` keeps script dir" is false on 3.11+, and could not have been observed under the
+correct "never run" boundary.
+
+Note: the env allow-list carries no `PYTHONPATH` (correct for B7), and `-I` ignores `PYTHON*` env regardless, so there
+is no alternate resolution path — the launcher import is unrecoverable under `-I`.
+
+**Fix:** remove `-I` from the **launcher** command only (keep `-B` + the `env=` allow-list — the launcher's
+env-isolation is already provided by the constructed allow-list, which contains no `PYTHONPATH`/`PYTHONHOME`/
+`PYTHONPYCACHEPREFIX`, and it needs `pinned/` at `sys.path[0]` for the sibling import). Keep `-I` on the **broker**
+command (it loads the helper by explicit `--generation-module` path via `importlib`, so it never needs the script
+dir on `sys.path`). Alternatively, inject the pinned dir explicitly (e.g. `PYTHONPATH=pinned/` — but that reintroduces
+a `PYTHON*` passthrough B7 forbids, so dropping `-I` on the launcher is the clean fix).
+
+## What DID land correctly (for the author's fast turnaround)
+
+- **B7 — broker child env-isolated: correct.** `launch_verified_broker` now takes `environment` and passes
+  `env=environment` (the constructed allow-list, **not** `os.environ`) to `Popen` (:566-568); the broker command
+  includes `-I` (:551); the allow-list contains no `PYTHONPATH`/`PYTHONHOME`/`PYTHONPYCACHEPREFIX` passthrough. The
+  broker child cannot inherit ambient env or resolve stdlib imports to ambient code. ✅
+- **B8 — bytecode pinned-or-suppressed: correct.** `PYTHONDONTWRITEBYTECODE=1` is in the allow-list env (:728) and
+  `-B` is on **both** child commands (:512-513 launcher, :551-552 broker); `reject_pinned_bytecode` fails closed
+  (`RuntimeError`) on any pre-existing `pinned/__pycache__` or `*.pyc` (:498-501) and is called **before each
+  consumer** (:534 launcher, :561 broker). No unpinned `.pyc` can be executed. ✅
+- **B5 conjunction / B6 single-helper / closure-import-guard / BAR1 / BAR2 (`.state` fidelity untouched) / BAR3
+  (live-path, fail-closed precondition, fixture-socket isolation, `lease_anchor_registered` + hex-256) / single p3
+  broker / `-O`-safe / allow-list env / `--runs==(3,)` / ABSENT sweep:** all intact/unperturbed (the delta touches only
+  the env/`-I`/`-B`/bytecode-reject surfaces). These are **not** the failing item.
+
+## Verdict
+
+**FAIL @ `a92ad090`.** B7 (broker env isolation) and B8 (bytecode pinned-or-suppressed) are correctly implemented,
+but the `-I` added to the **launcher** command breaks B6(c): the launcher's bare `from lease_generation import` at
+`f4008307:launch-runtime.py:15` cannot resolve the pinned helper because `-I`/`-P` strips `sys.path[0]` on Python
+3.11+ (empirically confirmed, 3.11.2 → `ModuleNotFoundError`). PASS requires **all** of B7+B8+B5+B6+BAR1/2/3; B6(c)
+does not hold. Not softened → returns to author (ms-rev-826). The fix is narrow: drop `-I` from the launcher command
+(retain `-B` + allow-list env), keep `-I` on the broker.
+
+**Findings:** B6(c) — `p3_d4_focused_run.py:512` (`-I` on the launcher command; breaks the pinned-helper sibling
+import under Python 3.11+).
+
+## Scope reminder (not a finding)
+
+Producing this evidence **executes** the Gate0 mechanism (§3/§5). This review clears **bytes** only; FIRE remains
+separately gated on Mos's post-clear GO — moot until this FAIL is remediated.
+
+---
+
+**Reviewer:** distinct Opus SECREV session (`ms-secrev-828` lane, dispatched by `mosaic-100`), Gate-16 author≠reviewer,
+byte review only; ran nothing (harness/broker not executed).
+**Reviewed object (pin):** `a92ad090ae3828c643f961c7628d809b8521185f` · harness sha256 `915ebeb5aeab108cb60c5f629c1db520623ab4914eed427ca34ee66f9aa08390`.

docs/compaction-refresh/reviews/GATE0-PROBE3-V9-LAUNCHERFIX-S3-REVIEW-v9.md

@@ -0,0 +1,95 @@
+> ⚠ SUPERSEDED: homelab 4th-round FAIL @`1c34e3cb` — no `-S` → Python imports `site` at startup, running unpinned system-site `.pth` executable lines + `sitecustomize`/`usercustomize` before the pinned launcher/broker (site startup-closure hole). This v9 PASS record is overtaken by the stricter B9 (no-site) bar and is NOT fire-authorization; superseded by v10.
+
+# Gate0 Probe-3 (D4) Launcher-Import Fix — §3-Conformance Review v9
+
+**Verdict: ✅ PASS** *(superseded — see banner above)*
+
+## Pin (GUARD 1 — reviewed object)
+
+- **Reviewed object = `1c34e3cb3172acdcd094e683e847d7c984afc96c`** (harness commit, branch `feat/827-gate0-probe`).
+- **Reviewed file:** `docs/compaction-refresh/probes/p3_d4_focused_run.py` — sha256 (pushed provider bytes, `-o FILE`, FULL-40 ref, verified before trust): `29e5c7bfbe1911b52984bd94c79036bb1200ee82588318367b13c2b1053a0103` (32725 bytes, no not-found sentinel).
+- **Closure pins (unchanged):** launcher `e950e422…` @f4008307 · helper `061625402f08488eac47acd23272904e71fd1a71fd15b3bdab158632c801be4c` @f4008307 · broker `4db4fef1…` @23c0caca.
+
+## Independence (GUARD 2 — principal-independence attestation)
+
+Distinct Opus SECREV session, orchestrator-dispatched — the **`ms-secrev-828` reviewer lane, dispatched by
+`mosaic-100`** — **byte review only, ran nothing** (harness/broker not executed); did **not** build this harness
+(builder = ms-rev-826); is not Mos. This is the re-review after **my own** v8 FAIL @`a92ad090` (B6(c): `-I` on the
+launcher broke the sibling import); the author applied the narrow fix and I verify it here. The `-s`/`-I` `sys.path`
+checks below use a *throwaway* two-line script to observe interpreter behavior — not the harness/broker/closure.
+
+## ★ B6(c) — THE FIX (was the v8 FAIL): launcher `-I` dropped; sibling import binds to `pinned/`
+
+The launcher command no longer carries `-I`; it now uses **`-s`** (`:514`, commented "`-s` preserves `sys.path[0]=pinned/`
+for the launcher's sibling helper") + `-B` (`:515`), and `PYTHONNOUSERSITE=1` is added to the allow-list env (`:730`).
+
+`-s` and `PYTHONNOUSERSITE` disable **user site-packages only** — they do **not** strip the script's directory from
+`sys.path` (unlike `-I`/`-P`). Empirically confirmed on this host (Python 3.11.2), throwaway script:
+
+```
+python3 -s -B main.py                       → sys.path[0] = '<script dir>'  → sibling import: OK
+PYTHONNOUSERSITE=1 python3 -s -B main.py     → sys.path[0] = '<script dir>'  → sibling import: OK
+python3 -I -B main.py   (the v8 FAIL form)   → sys.path[0] = stdlib zip     → ModuleNotFoundError
+```
+
+Therefore `python3 -s -B pinned/launch-runtime.py …` puts `pinned/` at `sys.path[0]`, so the pinned launcher's bare
+top-level `from lease_generation import initialize_runtime_generation` (`f4008307:launch-runtime.py:15`, no `sys.path`
+manipulation) resolves to the **pinned** `pinned/lease_generation.py` — not the worktree, not a miss. **B6(c) holds.**
+
+## B7 — Broker env-isolation (still holds)
+
+`launch_verified_broker` passes `env=environment` (the constructed allow-list, **not** `os.environ`; contains no
+`PYTHONPATH`/`PYTHONHOME`/`PYTHONPYCACHEPREFIX`) to `Popen` (`:570`), and the broker command includes `-I` (`:552`).
+The broker imports the helper by explicit `--generation-module` path via `importlib`, so it never needs `sys.path[0]`
+— `-I` is correct there and does not affect it. (The env's `PYTHONNOUSERSITE`/`PYTHONDONTWRITEBYTECODE` are hardening
+flags, not path/home passthrough, and `-I` ignores all `PYTHON*` env anyway.)
+
+## B8 — Bytecode pinned-or-suppressed (still holds)
+
+`PYTHONDONTWRITEBYTECODE=1` (`:729`) and `PYTHONNOUSERSITE=1` (`:730`) in the allow-list env; `-B` on **both** child
+commands (`:515` launcher, `:553` broker); `reject_pinned_bytecode` fails closed (`RuntimeError`) on any pre-existing
+`pinned/__pycache__` or `*.pyc` (`:498-501`) and is called **before each consumer** (`:535` launcher, `:562` broker).
+No unpinned `.pyc` can be executed.
+
+## B5 — 3-leg conjunction (still holds)
+
+`materialize_closure` reads launcher+helper+broker from **git-object bytes** (`git show <commit>:<path>`) and asserts
+`sha256 == pin` for each, fail-closed; `pinned/` is a fixture-private `0o700` dir inside the per-run fixture temp root;
+files created `O_WRONLY|O_CREAT|O_EXCL|O_CLOEXEC 0o600` (no chmod/rename/symlink gap → no writable window); each member
+re-hashed `== pin` immediately before its `Popen` (launcher; broker + helper). Launcher and broker consume the **same
+single** pinned helper. `closure_import_guard` AST-rejects any unpinned non-stdlib import.
+
+## Fidelity + traceability + carry-over (still hold)
+
+`GATED_WI_HEAD == f4008307` + `merge-base --is-ancestor 66b1e0a0 f4008307` (forward-contains). Extension bumps
+`generation-{sid}.state` via `MOSAIC_LEASE_GENERATION_FILE` (not in-mem); broker reads via `read_runtime_generation`;
+`assert_d4` observes the file-backed transition (`generation_source=="state-file"`, `state_file_drives_lifecycle`,
+`state_file_in_fixture_root`, new→`MUTATOR_UNVERIFIED`, prior→`STALE_GENERATION`); `.state` stays in the fixture temp
+root. `lease_anchor_registered` INTACT (event + `session_id_shape=="hex-256"`). LIVE-PATH drives the pinned gated
+launcher (no released `mosaic`/`execRuntime`). Fail-closed precondition before any launch. Single pinned p3 broker.
+Promotion=fixture-only. `--runs choices=(3,)`. `copy2` = creds-only. Allow-list env (0 `os.environ.copy`).
+
+## ABSENT sweep
+
+P5/P6/P2-bank/retry-launder/mosaic-yolo/execRuntime = 0; `source-invalid` = 0; no live/real-broker path; no `.state`
+outside the fixture root; no exec-at-import (`__main__`-guarded); no adjacency-only-exec-from-worktree; the only change
+is the authorized launcher-flag isolation fix (no mechanism change, no scope-widen); **`-O`-safe** (0 bare `assert`).
+
+## Verdict
+
+**PASS @ `1c34e3cb`.** The v8 FAIL is remediated by the narrow fix (launcher `-I` → `-s` + `PYTHONNOUSERSITE=1`),
+empirically verified to preserve `sys.path[0]=pinned/` so the pinned launcher's sibling import binds to the pinned
+helper; the broker retains `-I` (explicit-path import). B7, B8, B5, B6-rest, fidelity, traceability, and all carry-over
+bars remain intact; zero out-of-scope surface. **Findings: none.**
+
+## Scope reminder (not a finding)
+
+Producing this evidence **executes** the Gate0 mechanism (§3/§5). This review clears **bytes** only; **FIRE remains
+separately gated on Mos's explicit post-clear GO**, his byte-scope-verify co-attestation, and homelab's
+third-principal verify — not authorized by this review.
+
+---
+
+**Reviewer:** distinct Opus SECREV session (`ms-secrev-828` lane, dispatched by `mosaic-100`), Gate-16 author≠reviewer,
+byte review only; ran nothing.
+**Reviewed object (pin):** `1c34e3cb3172acdcd094e683e847d7c984afc96c` · harness sha256 `29e5c7bfbe1911b52984bd94c79036bb1200ee82588318367b13c2b1053a0103`.

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

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

docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md

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

docs/fleet/FLEET-LAUNCH.md

@@ -8,11 +8,11 @@ Generated environment files are rebuildable projections, not an operator-editabl
 | Layer               | Responsibility                                                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
-| Projection writer   | Renders deterministic fleet/agents/<name>.env.generated from the roster.                                                        |
-| Optional local data | Reads a strict, data-only fleet/agents/<name>.env.local; it cannot shadow generated keys.                                       |
-| systemd             | Starts the launcher with env -i and fixed bootstrap data. It does not preload either environment file.                          |
+| Projection writer   | Renders deterministic `fleet/agents/<name>.env.generated` from the roster.                                                      |
+| Optional local data | Reads a strict, data-only `fleet/agents/<name>.env.local`; it cannot shadow generated keys.                                     |
+| systemd             | Starts the launcher with `env -i` and fixed bootstrap data. It does not preload either environment file.                        |
 | session launcher    | Validates generated and local data before it queries, creates, or stops an exact tmux session.                                  |
-| runtime launch      | Derives the fixed mosaic yolo <runtime> argument array from validated roster data, then seeds the runtime contract.             |
+| runtime launch      | Derives the fixed `mosaic yolo <runtime>` argument array from validated roster data, then seeds the runtime contract.           |
 
 The launcher never `source`s or `eval`s an environment file and never accepts an environment-supplied
 command. `MOSAIC_AGENT_COMMAND`, command/channel overrides, unknown keys, generated-key shadowing,
@@ -20,7 +20,7 @@ secret-like key names, duplicate keys, comments, quoted/export syntax, and unsaf
 
 ## Generated and local files
 
-<name>.env.generated is complete, deterministic, and written only by Mosaic. Its ordered keys are:
+`<name>.env.generated` is complete, deterministic, and written only by Mosaic. Its ordered keys are:
 
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
@@ -33,12 +33,12 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
 
-The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. mosaic fleet add
+The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. `mosaic fleet add`
 rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
 The legacy dogfood stub remains an observability-only canary on its separate `mosaic-factory` socket;
 it has no generated-launch adapter and cannot be added through this path.
 
-<name>.env.local is optional and may contain only non-secret machine data:
+`<name>.env.local` is optional and may contain only non-secret machine data:
 
 - `MOSAIC_RUNTIME_BIN`
 - `MOSAIC_HEARTBEAT_RUN_DIR`
@@ -52,9 +52,9 @@ private, non-symlink paths. Violations fail closed before tmux interaction.
 
 ## Legacy input and diagnostics
 
-A legacy <name>.env is input only during projection generation. Roster-owned keys are regenerated;
+A legacy `<name>.env` is input only during projection generation. Roster-owned keys are regenerated;
 valid allowed local data can move to `.env.local`; invalid legacy input is privately retained at
-<name>.env.quarantine. Neither legacy nor quarantine files are launch authority.
+`<name>.env.quarantine`. Neither legacy nor quarantine files are launch authority.
 
 Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command
 text, credentials, or other values.
@@ -62,11 +62,11 @@ text, credentials, or other values.
 ## Launch and stop behavior
 
 The launcher obtains the agent's socket only from the validated generated projection. It creates or
-checks the exact =<agent-name> tmux target; it never uses an ambient socket or fuzzy session match.
+checks the exact `=<agent-name>` tmux target; it never uses an ambient socket or fuzzy session match.
 The same strict parser runs before exact-stop behavior. A fresh native Pi heartbeat remains authoritative;
 the shell sidecar only provides fallback state when the native marker is stale or absent.
 
-mosaic agent comms-block <exact-member> can inspect that exact roster member's resolved Fleet-Comms
+`mosaic agent comms-block <exact-member>` can inspect that exact roster member's resolved Fleet-Comms
 block. It is a read-only inspection tool and fails loudly for an unknown exact member or missing roster.
 On Linux, the installed roster, TOOLS contract, and executable helper are opened through a held
 descriptor chain rooted at `/`; every managed path component uses no-follow traversal, and content plus

docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md

@@ -14,7 +14,7 @@ parallel resolver. The current executable implementation and per-artifact outcom
 
 | Shipped file                                         | Current class evidence                                              | M0 disposition decision                                                                              | Required M1/M4 evidence                                              |
 | ---------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `framework/fleet/examples/coding.yaml`               | `orchestrator`, `enhancer`, `implementer`, `reviewer`               | Migrate: implementer → code, reviewer → review; retain orchestration/enhancer intent                 | v2 fixture validates; role aliases and authority matrix tested       |
+| `framework/fleet/examples/coding.yaml`               | `orchestrator`, `enhancer`, `implementer`, `reviewer`               | Migrate: `implementer → code`, `reviewer → review`; retain orchestration/enhancer intent             | v2 fixture validates; role aliases and authority matrix tested       |
 | `framework/fleet/examples/general.yaml`              | `orchestrator`, `enhancer`, `worker`                                | Migrate only after operator chooses a concrete canonical role for `worker`; no implicit conversion   | Explicit replacement class, or versioned v1 fixture/retirement note  |
 | `framework/fleet/examples/hybrid.yaml`               | `orchestrator`, `enhancer`, `implementer`, `researcher`, `reviewer` | Migrate aliases; resolve `researcher` through existing role resolver or retain/version               | Shared resolver validation; no ad-hoc class scanner                  |
 | `framework/fleet/examples/local-canary.yaml`         | `orchestrator`, `implementer`, `reviewer`                           | Migrate aliases; preserve its local-tmux canary purpose                                              | v2 fixture validates and preserves safe stopped/running behavior     |
@@ -35,13 +35,13 @@ parallel resolver. The current executable implementation and per-artifact outcom
 ## Service presets
 
 | Shipped file                                         | Current policy evidence                                                                                                                                               | M0 disposition decision                                                                                                                                                                                                              | Required M1/M4 evidence                                                                                                                                                               |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `framework/fleet/services/operator-interaction.yaml` | Generic policy only: runtime: pi, model: openai/gpt-5.6-sol, reasoning: high, tool_policy: operator-interaction; provisioning supplies the agent name as data | Retain as a generic service policy, not a Tess identity. Migrate tool_policy: operator-interaction only through the approved interaction tool-policy alias/semantic resolver; do not infer a class or machine name from this file. | Service-policy fixture validates runtime/model/reasoning and alias behavior; generic provisioning proves a configured interaction instance is supplied without a hardcoded Tess name. |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `framework/fleet/services/operator-interaction.yaml` | Generic policy only: `runtime: pi`, `model: openai/gpt-5.6-sol`, `reasoning: high`, `tool_policy: operator-interaction`; provisioning supplies the agent name as data | Retain as a generic service policy, not a Tess identity. Migrate `tool_policy: operator-interaction` only through the approved interaction tool-policy alias/semantic resolver; do not infer a class or machine name from this file. | Service-policy fixture validates runtime/model/reasoning and alias behavior; generic provisioning proves a configured interaction instance is supplied without a hardcoded Tess name. |
 
 ## Required disposition controls
 
-1. **No silent aliasing:** only implementer → code, reviewer → review, and
-   operator-interaction → interaction are approved deterministic aliases in this M0 baseline.
+1. **No silent aliasing:** only `implementer → code`, `reviewer → review`, and
+   `operator-interaction → interaction` are approved deterministic aliases in this M0 baseline.
    `worker`, `analyst`, `canary`, and domain-specific classes require resolver evidence or an
    explicit version/retirement decision.
 2. **No identity hardcoding:** Tess and Ultron are optional instance/display names. An example/profile

docs/fleet/NORTH_STAR.md

@@ -33,7 +33,7 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
 - **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
 - **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
 - **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
-- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives mosaic update: baseline reseed never clobbers user overrides.
+- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives `mosaic update`: baseline reseed never clobbers user overrides.
 
 ## Workstreams
 

docs/fleet/NORTH_STAR.yaml

@@ -97,7 +97,7 @@ success_criteria:
   - id: AC-NS-7
     text: >-
       A user-customized persona (edited or added via the orchestrator) survives
-      mosaic update: baseline reseed never clobbers user overrides.
+      `mosaic update`: baseline reseed never clobbers user overrides.
 
 workstreams:
   - id: A

docs/fleet/PRD-fleet-suite.md

@@ -8,7 +8,7 @@
 ## Mission
 
 Turn the proven fleet primitives into a **user-installable, AI-free-configurable fleet product**:
-a user runs mosaic fleet init, answers a few questions (general / coding / research / hybrid),
+a user runs `mosaic fleet init`, answers a few questions (general / coding / research / hybrid),
 gets a recommended set of agents plus one always-on orchestrator wired for chat-ops, and can
 operate, mutate, re-create, and observe the fleet — over tmux today and Matrix tomorrow — from
 CLI/TUI and (designed-for) the webUI.
@@ -22,9 +22,9 @@ functional, we use the fleet itself to continue the work.
 ### A. Configure-without-AI CLI
 
 | ID  | Requirement                                                                                                   |
-| --- | ----------------------------------------------------------------------------------------------------------- |
-| R1  | mosaic fleet command set is functional end-to-end (init/install/start/stop/status/ps/verify + agent verbs). |
-| R2  | mosaic fleet init is an interactive, **AI-free** CLI wizard.                                                |
+| --- | ------------------------------------------------------------------------------------------------------------- |
+| R1  | `mosaic fleet` command set is functional end-to-end (init/install/start/stop/status/ps/verify + agent verbs). |
+| R2  | `mosaic fleet init` is an interactive, **AI-free** CLI wizard.                                                |
 | R3  | Init asks the **configuration type**: `general`, `coding`, `research`, `hybrid`, … (extensible).              |
 | R4  | Based on the answer, the fleet is populated with a **recommended set of agents** (a preset).                  |
 | R5  | **Exactly one main orchestrator agent** is always configured, regardless of type.                             |
@@ -35,11 +35,11 @@ functional, we use the fleet itself to continue the work.
 ### B. Comms & orchestrator chat-ops
 
 | ID  | Requirement                                                                                                                       |
-| --- | ----------------------------------------------------------------------------------------------------------------------------- |
+| --- | --------------------------------------------------------------------------------------------------------------------------------- |
 | R6  | Init can wire the orchestrator to a chat connector — **Telegram / Discord / Matrix / Slack** — for command + comms.               |
 | R7  | Designed with the end-goal of **Matrix comms on a locally-controlled server**.                                                    |
 | R16 | Fleet supports **tmux AND Matrix** comms, **user-configurable** at init or any time. Not all users want Matrix.                   |
-| R19 | **"Mos" orchestrator on Discord** (chan 1517622518662434996 / srv 1112631390438166618) on `w-jarvis` — the first live target. |
+| R19 | **"Mos" orchestrator on Discord** (`chan 1517622518662434996` / `srv 1112631390438166618`) on `w-jarvis` — the first live target. |
 
 ### C. Runtime, health, lifecycle
 
@@ -64,15 +64,15 @@ functional, we use the fleet itself to continue the work.
 - **Orchestrator agent:** always present; carries the chat connector config (connector type + target IDs) so it can be commanded over chat. tmux is the substrate; the connector bridges chat ↔ the orchestrator session.
 - **Comms layers (R16):** (1) **tmux** inter-agent (`agent-send`, proven) — default, always available. (2) **chat connector** for human↔orchestrator (Discord now; Matrix the strategic target). (3) **Matrix** as the locally-controlled cross-agent bus (future). Connector is pluggable + reconfigurable.
 - **Heartbeat (R15):** runtime-agnostic launcher sidecar already covers pi/claude/codex (#584). Refine per-runtime (native HB) with the **custom Pi harness** (R14) + a Claude path.
-- **Updates (R13):** mosaic update (CLI) + a fleet-aware harness-update step that refreshes pi/claude/codex and re-launches agents safely (drain → update → relaunch via the durable launcher).
-- **webUI (R18):** the fleet exposes machine-readable state (fleet ps --json already carries tenant/host/heartbeat/managed) + control verbs (start/stop/watch/send); webUI consumes these (control plane rides federation per north star). Ensure a stable JSON contract + a terminate/attach(butt-in) path.
+- **Updates (R13):** `mosaic update` (CLI) + a fleet-aware harness-update step that refreshes pi/claude/codex and re-launches agents safely (drain → update → relaunch via the durable launcher).
+- **webUI (R18):** the fleet exposes machine-readable state (`fleet ps --json` already carries tenant/host/heartbeat/managed) + control verbs (start/stop/watch/send); webUI consumes these (control plane rides federation per north star). Ensure a stable JSON contract + a terminate/attach(butt-in) path.
 
 ## Phases (incremental, each shippable)
 
 | Phase                             | Deliverable                                                                                                                         | Notes                                 |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| **F1 Presets + init wizard**      | preset rosters (general/coding/research/hybrid) + always-orchestrator + AI-free fleet init selecting a preset; re-init idempotent | R1–R5, R8, R10, R17                   |
-| **F2 Connector + Mos-on-Discord** | orchestrator chat-connector config (Discord first) + **Mos live on Discord 1517…/1112…** on w-jarvis                              | R6, R19, partial R16                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| **F1 Presets + init wizard**      | preset rosters (general/coding/research/hybrid) + always-orchestrator + AI-free `fleet init` selecting a preset; re-init idempotent | R1–R5, R8, R10, R17                   |
+| **F2 Connector + Mos-on-Discord** | orchestrator chat-connector config (Discord first) + **Mos live on Discord `1517…`/`1112…`** on w-jarvis                            | R6, R19, partial R16                  |
 | **F3 Heartbeat + harness**        | HB confirmed for claude + pi/gpt; **custom Pi harness** (tool usage, native HB, model self-report); graceful harness updates        | R13, R14, R15                         |
 | **F4 Matrix + comms toggle**      | Matrix connector (local server) + user toggle tmux/Matrix at init/anytime                                                           | R7, R16                               |
 | **F5 Orchestrator-mutable fleet** | orchestrator can add/remove agents at runtime                                                                                       | R9                                    |
@@ -82,28 +82,28 @@ functional, we use the fleet itself to continue the work.
 ## Work division (proposed — confirm with dragon-lin)
 
 - **Jarvis @ w-jarvis (Lead):** F1 presets+wizard, F2 connector+Mos-on-Discord, F5 mutability, F6 webUI hooks; merge authority + dual-engine reviews; co-testing on w-jarvis.
-- **coder @ dragon-lin:** F3 custom Pi harness + harness-update flow (pi/codex-savvy); plus its in-flight constitution P4–P6 (P4 installer rework underpins fleet init/updates — coordinate the install path). Co-testing on dragon-lin (R11).
+- **coder @ dragon-lin:** F3 custom Pi harness + harness-update flow (pi/codex-savvy); plus its in-flight constitution P4–P6 (P4 installer rework underpins `fleet init`/updates — coordinate the install path). Co-testing on dragon-lin (R11).
 - **Shared:** F4 Matrix (whoever has bandwidth); F7 testing/docs continuous.
 
 ## Immediate target: Mos on Discord (F2 first slice)
 
-The discord plugin is available (~/.claude.json). Path: configure the **orchestrator** as a durable
+The discord plugin is available (`~/.claude.json`). Path: configure the **orchestrator** as a durable
 fleet session running Claude Code with the discord plugin bridged to channel `1517622518662434996`
 (server `1112631390438166618`) on w-jarvis, with the existing Discord Bridge Protocol (ack within
 ~3s, reply via `mcp__discord__reply`, no `AskUserQuestion`). Heartbeat via the launcher sidecar.
 
 ## Success criteria
 
-- A non-AI user can mosaic fleet init, pick a type, and get a working fleet + orchestrator.
-- **Mos answers in Discord 1517…** on w-jarvis.
-- Fleet runs + is observable (fleet ps) on **both** w-jarvis and dragon-lin.
+- A non-AI user can `mosaic fleet init`, pick a type, and get a working fleet + orchestrator.
+- **Mos answers in Discord `1517…`** on w-jarvis.
+- Fleet runs + is observable (`fleet ps`) on **both** w-jarvis and dragon-lin.
 - Harness updates handled gracefully; HB healthy for claude + pi/gpt agents.
 - Docs let a new operator install/configure/use the fleet.
 - Re-init + orchestrator mutation work.
 
 ## Assumptions (veto-able)
 
-- `ASSUMPTION:` presets ship as example rosters under the framework (fleet/examples/\*.yaml), selected by `init`.
+- `ASSUMPTION:` presets ship as example rosters under the framework (`fleet/examples/*.yaml`), selected by `init`.
 - `ASSUMPTION:` chat connectors are pluggable; Discord first (target exists), Matrix is the strategic default later.
 - `ASSUMPTION:` "Mos" = a Claude Code orchestrator session with the discord plugin (reuses the documented Discord Bridge Protocol).
 - `ASSUMPTION:` per north star, runtimes default to Codex/pi-on-Codex for workers; the orchestrator "Mos" runs Claude Code (in Claude Code, which is allowed).

docs/fleet/PRD.md

@@ -10,8 +10,8 @@
 The durable tmux fleet runs on the isolated `mosaic-fleet` socket. That isolation
 (which protects the operator's default tmux) makes the fleet **invisible** to default
 tooling, and truth is split across three planes no single command joins — systemd
-(systemctl --user), tmux (-L mosaic-fleet), and the process tree (`pstree`).
-agent tail (`capture-pane`) returns **blank for full-screen TUIs**, and agent send
+(`systemctl --user`), tmux (`-L mosaic-fleet`), and the process tree (`pstree`).
+`agent tail` (`capture-pane`) returns **blank for full-screen TUIs**, and `agent send`
 confirms only keystroke injection, not acceptance. Net: the operator has near-zero
 observability and no safe way to watch a session.
 
@@ -33,21 +33,21 @@ observability and no safe way to watch a session.
 ## Functional requirements
 
 | ID   | Requirement                                                                                                                                                                                                                                                                                                    |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FR-1 | mosaic fleet ps [--json] prints one row per roster agent joining: name · tenant · host · runtime · systemd(active/enabled) · pane(alive/dead) · pid · idle · **last-heartbeat age** · **drift** flag (roster runtime ≠ actual pane command) · **boot-enable** warning (active but `UnitFileState=disabled`). |
-| FR-2 | **Heartbeat protocol v1** (see below); `dogfood-agent.py` implements the responder. fleet ps issues probes (or reads last-seen) and reports health per FR-1.                                                                                                                                                 |
-| FR-3 | mosaic agent watch <name> opens a **read-only** view of the pane (grouped session or tmux attach -r) that cannot send keystrokes and does not shrink the agent's window.                                                                                                                                     |
-| FR-4 | mosaic agent attach <name> remains the **explicit** interactive-takeover path (separate verb, documented as the only one that can type).                                                                                                                                                                     |
-| FR-5 | mosaic agent send <name> --verify confirms the message was **accepted** (not left as an unsubmitted draft) and returns non-zero if delivery cannot be verified.                                                                                                                                              |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR-1 | `mosaic fleet ps [--json]` prints one row per roster agent joining: name · tenant · host · runtime · systemd(active/enabled) · pane(alive/dead) · pid · idle · **last-heartbeat age** · **drift** flag (roster runtime ≠ actual pane command) · **boot-enable** warning (active but `UnitFileState=disabled`). |
+| FR-2 | **Heartbeat protocol v1** (see below); `dogfood-agent.py` implements the responder. `fleet ps` issues probes (or reads last-seen) and reports health per FR-1.                                                                                                                                                 |
+| FR-3 | `mosaic agent watch <name>` opens a **read-only** view of the pane (grouped session or `tmux attach -r`) that cannot send keystrokes and does not shrink the agent's window.                                                                                                                                   |
+| FR-4 | `mosaic agent attach <name>` remains the **explicit** interactive-takeover path (separate verb, documented as the only one that can type).                                                                                                                                                                     |
+| FR-5 | `mosaic agent send <name> --verify` confirms the message was **accepted** (not left as an unsubmitted draft) and returns non-zero if delivery cannot be verified.                                                                                                                                              |
 | FR-6 | All structured output (`--json`) includes `tenant_id` and `host` fields.                                                                                                                                                                                                                                       |
 
 ## Heartbeat protocol v1
 
-- **Probe:** operator/fleet ps writes a sentinel line to the agent's input or a
-  well-known per-agent heartbeat file path ~/.config/mosaic/fleet/run/<agent>.hb.
-- **Response:** the runtime updates <agent>.hb with ts=<iso8601> pid=<pid> status=<ok|busy>
+- **Probe:** operator/`fleet ps` writes a sentinel line to the agent's input or a
+  well-known per-agent heartbeat file path `~/.config/mosaic/fleet/run/<agent>.hb`.
+- **Response:** the runtime updates `<agent>.hb` with `ts=<iso8601> pid=<pid> status=<ok|busy>`
   on a fixed interval (default 15s) and on demand when probed.
-- **Health rule:** `healthy` if now - ts <= 3 × interval; else `stale`; missing file = `unknown`.
+- **Health rule:** `healthy` if `now - ts <= 3 × interval`; else `stale`; missing file = `unknown`.
 - **Contract:** every runtime (dogfood stub now; claude/codex/pi/opencode in Phase 3)
   MUST emit the heartbeat. The protocol is file-based so it works for headless stubs and
   full-screen TUIs alike (no `capture-pane` dependency).
@@ -56,15 +56,15 @@ observability and no safe way to watch a session.
 
 ## Acceptance criteria
 
-- mosaic fleet ps shows all 5 live sessions on `mosaic-fleet` with correct
+- `mosaic fleet ps` shows all 5 live sessions on `mosaic-fleet` with correct
   pane/pid/idle and flags the dogfood **drift** (`canary-pi` runtime=pi but pane runs
   `dogfood-agent.py`) and the **boot-enable** gap (active but disabled).
 - Killing one agent's pane flips its row to dead/stale within one `interval`.
-- agent watch shows live output and provably cannot type into the pane; detaching
+- `agent watch` shows live output and provably cannot type into the pane; detaching
   leaves the agent's window size unchanged.
-- agent send --verify returns success on an accepting pane and non-zero on a wedged/draft pane.
-- Quality gates green: pnpm typecheck, pnpm lint, pnpm format:check, plus
-  pnpm --filter @mosaicstack/mosaic test.
+- `agent send --verify` returns success on an accepting pane and non-zero on a wedged/draft pane.
+- Quality gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, plus
+  `pnpm --filter @mosaicstack/mosaic test`.
 - Independent review passed; dogfood evidence captured against the live fleet.
 
 ## Test plan
@@ -72,18 +72,18 @@ observability and no safe way to watch a session.
 - Unit/CLI specs in `packages/mosaic/src/commands/fleet.spec.ts` (and a new
   `fleet-ps`/`watch`/`send-verify` spec) using the injected `CommandRunner` to assert
   exact tmux/systemd command construction and JSON shape (tenant+host present).
-- Situational: run against the live `mosaic-fleet` fleet; capture fleet ps output,
-  a kill-and-detect cycle, a read-only `watch`, and a send --verify pass/fail pair.
+- Situational: run against the live `mosaic-fleet` fleet; capture `fleet ps` output,
+  a kill-and-detect cycle, a read-only `watch`, and a `send --verify` pass/fail pair.
 
 ## Known limitations
 
-- **Verify heuristic is best-effort:** agent send --verify uses a > -prefix draft
+- **Verify heuristic is best-effort:** `agent send --verify` uses a `>` -prefix draft
   heuristic that is specific to pi/claude TUIs. Draft detection for codex and opencode
   TUIs is best-effort only; those runtimes may not use the same input-line indicator.
 - **Pane-change check is the best Phase-2 signal; verify now polls up to a bounded
-  timeout:** agent send --verify captures a BEFORE snapshot, sends the message, then
+  timeout:** `agent send --verify` captures a BEFORE snapshot, sends the message, then
   polls `capture-pane` every ~400 ms up to a configurable total timeout (default ~6 s,
-  controlled by --verify-timeout <ms>). On each poll it runs classifySendResult: if
+  controlled by `--verify-timeout <ms>`). On each poll it runs classifySendResult: if
   the pane shows 'accepted' or 'draft' the loop exits immediately; while the result is
   'unverifiable' (no pane change yet) it keeps polling. After the timeout with no
   definitive result, it fails closed: exit 1 with "no pane change after send". This
@@ -92,15 +92,15 @@ observability and no safe way to watch a session.
   requires a runtime acknowledgement (Phase-3 heartbeat-ack); the bounded pane-change
   poll is the best signal available against an opaque TUI for Phase-2.
 - **Blank AFTER capture fails closed:** Full-screen TUIs (claude, codex, opencode, pi)
-  render blank for tmux capture-pane. When the AFTER snapshot is empty, send --verify
+  render blank for `tmux capture-pane`. When the AFTER snapshot is empty, `send --verify`
   returns non-zero with an "unverifiable" message rather than silently succeeding. This
   is an intentional fail-closed design (FR-5).
-- **agent watch uses a grouped viewer session:** tmux attach -r directly against the
-  agent session lets the viewer terminal shrink the agent's window. agent watch instead
-  creates a throwaway grouped session (tmux new-session -d -t '=<agent>' -s
-  '<agent>-watch-<pid>'), attaches read-only to that session, and kills it on detach.
+- **`agent watch` uses a grouped viewer session:** `tmux attach -r` directly against the
+  agent session lets the viewer terminal shrink the agent's window. `agent watch` instead
+  creates a throwaway grouped session (`tmux new-session -d -t '=<agent>' -s
+'<agent>-watch-<pid>'`), attaches read-only to that session, and kills it on detach.
   The grouped session shares the agent's windows but has independent sizing, so the
-  agent's window is never affected. tmux attach is still interactive and requires
+  agent's window is never affected. `tmux attach` is still interactive and requires
   inherited stdio; the `interactiveRunner` handles TTY passthrough.
 
 ## Surfaces & parity (MVP-X1)

docs/fleet/README.md

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

docs/fleet/TASKS.md

@@ -8,13 +8,13 @@
 > Status: `not-started` | `in-progress` | `done` | `blocked` | `failed`
 
 | id            | status      | description                                                                                                        | depends_on            | agent       | pr  | notes                                                                                                                       |
-| ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
+| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
 | FLEET-OBS-000 | done        | Plan: north-star + Phase-2 PRD + workstream scaffolding                                                            | —                     | lead        | —   | persisted 2026-06-20 on `feat/fleet-observability`                                                                          |
-| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                      | FLEET-OBS-000         | lead        | —   | file-based ~/.config/mosaic/fleet/run/<agent>.hb; spec in PRD                                                               |
-| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                              | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc mosaic yolo fleet agent (dogfood)                                                                      |
-| FLEET-OBS-003 | done        | mosaic fleet ps — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
-| FLEET-OBS-004 | done        | mosaic agent watch <name> — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | attach -r; verb wired                                                                                                       |
-| FLEET-OBS-005 | done        | mosaic agent send --verify — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
+| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                        | FLEET-OBS-000         | lead        | —   | file-based `~/.config/mosaic/fleet/run/<agent>.hb`; spec in PRD                                                             |
+| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                                | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc `mosaic yolo` fleet agent (dogfood)                                                                    |
+| FLEET-OBS-003 | done        | `mosaic fleet ps` — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
+| FLEET-OBS-004 | done        | `mosaic agent watch <name>` — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | `attach -r`; verb wired                                                                                                     |
+| FLEET-OBS-005 | done        | `mosaic agent send --verify` — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
 | FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                       | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
 | FLEET-OBS-007 | not-started | Framework doc: fleet observability guide + verbs                                                                   | FLEET-OBS-003,004,005 | lead        | —   | `docs/guides/` or `framework/tools/.../README`                                                                              |
 | FLEET-OBS-008 | not-started | Independent review + dogfood verification on live fleet                                                            | FLEET-OBS-002..007    | reviewer    | —   | author ≠ reviewer; capture evidence in scratchpad                                                                           |
@@ -22,6 +22,6 @@
 
 ## Proposed MVP rollup row (for the MVP orchestrator — not written by this workstream)
 
-```text-table
+```
 | W-FLEET | in-progress | Fleet (agent-session execution layer) | Phase 2/5 | docs/fleet/TASKS.md | observability dogfooded on live stub fleet; control plane rides federation (W1) |
 ```

docs/fleet/backlog-conventions.md

@@ -2,10 +2,10 @@
 
 The **backlog** is Mosaic's native backlog-of-record for fleet work. It is built
 end-to-end on Mosaic's own storage layer (`@mosaicstack/db`, drizzle/Postgres)
-and surfaced as mosaic fleet backlog <sub> --json.
+and surfaced as `mosaic fleet backlog <sub> --json`.
 
 > **Mosaic-native, no Hermes.** This backlog REPLACES the former Hermes adapter.
-> There is **no** runtime dependency on Hermes, hermes kanban, or ~/.hermes
+> There is **no** runtime dependency on Hermes, `hermes kanban`, or `~/.hermes`
 > anywhere in this feature. Anything previously delegated to Hermes is recreated
 > here on Mosaic's own Postgres storage layer.
 
@@ -18,7 +18,7 @@ engine (no sqlite, no raw client).
 | ---------------------------------- | -------------------- | ---------------------------------------------------------------- |
 | `DATABASE_URL` injected at runtime | Full server Postgres | the verified runtime database; it never authorizes migration/DDL |
 | `PGLITE_DATA_DIR` set (no URL)     | Embedded PGlite      | that directory                                                   |
-| neither (default)                  | Embedded PGlite      | ~/.config/mosaic/fleet/backlog                                   |
+| neither (default)                  | Embedded PGlite      | `~/.config/mosaic/fleet/backlog`                                 |
 
 PGlite is real Postgres semantics in-process — including the row locks the atomic
 claim relies on — so the **same code** runs on a laptop (embedded, single-host
@@ -28,9 +28,9 @@ For embedded PGlite only, the local backlog routine may prepare its local schema
 
 ### Update safety
 
-The embedded PGlite store lives under ~/.config/mosaic/fleet/backlog, which is
+The embedded PGlite store lives under `~/.config/mosaic/fleet/backlog`, which is
 listed in `PRESERVE_PATHS` in `packages/mosaic/framework/install.sh`. This means
-mosaic update (which runs the framework sync with rsync --delete) will **not**
+`mosaic update` (which runs the framework sync with `rsync --delete`) will **not**
 wipe the operator's backlog — same protection as the roster, per-agent env, and
 heartbeat run dir.
 
@@ -46,10 +46,10 @@ A card is one row in the `backlog` table:
 | `phase`             | text (nullable)     | Board/phase grouping (see below).                             |
 | `priority`          | int (default 0)     | **Higher = sooner.** Claim picks the max-priority ready card. |
 | `status`            | enum                | `ready` \| `claimed` \| `blocked` \| `done`.                  |
-| `depends_on`        | jsonb string[]      | DAG edges — ids of cards this one depends on.                 |
+| `depends_on`        | jsonb `string[]`    | DAG edges — ids of cards this one depends on.                 |
 | `claim_owner`       | text (nullable)     | Owner token of the active claim.                              |
 | `claim_ttl_seconds` | int (nullable)      | TTL of the active claim.                                      |
-| `claimed_at`        | timestamptz (null)  | When the claim was taken. claimed_at + ttl = expiry.          |
+| `claimed_at`        | timestamptz (null)  | When the claim was taken. `claimed_at + ttl` = expiry.        |
 | `attempts`          | int (default 0)     | Incremented each time the card is claimed.                    |
 | `idempotency_key`   | text (unique, null) | Dedups `create`; NULLs are distinct in Postgres.              |
 | `acceptance`        | jsonb (nullable)    | Acceptance criteria (array of strings or object).             |
@@ -65,12 +65,12 @@ would add ceremony without benefit.
 ### Board / phase convention
 
 `phase` is a free-form grouping string used as the board column / milestone label
-(e.g. `M1`, `fleet`, `infra`). list --phase <phase> filters to one board lane.
+(e.g. `M1`, `fleet`, `infra`). `list --phase <phase>` filters to one board lane.
 `priority` orders cards **within** the ready pool regardless of phase.
 
 ## Status lifecycle
 
-```text-diagram
+```
             create
               │
               ▼
@@ -87,49 +87,51 @@ would add ceremony without benefit.
 - **blocked** — explicitly parked; never auto-claimed.
 - **done** — completed; satisfies dependents.
 
-## Atomic claim (FOR UPDATE SKIP LOCKED) + TTL
+## Atomic claim (`FOR UPDATE SKIP LOCKED`) + TTL
 
 `claim` is atomic. Inside a single transaction it locks candidate `ready` rows
-with SELECT ... FOR UPDATE SKIP LOCKED (via the drizzle `sql` operator), picks
+with `SELECT ... FOR UPDATE SKIP LOCKED` (via the drizzle `sql` operator), picks
 the highest-priority deps-satisfied card, and flips it to `claimed`. Because a row
 already locked by a concurrent claimer is **skipped**, two claimers can **never**
 both win the same card — the loser falls through to the next candidate or gets
 `null`. (Proven by the concurrency tests in `packages/db/src/backlog.spec.ts`.)
 
 - **Deps gate:** a card is only claimable when every id in `depends_on` is `done`.
-- **TTL:** claim --ttl <sec> (default **900s**) records `claim_ttl_seconds`.
-- **reclaim:** releases claims whose claimed_at + ttl is in the past (expired)
-  back to `ready`, clearing the claim fields. reclaim --id <id> force-releases a
+- **TTL:** `claim --ttl <sec>` (default **900s**) records `claim_ttl_seconds`.
+- **reclaim:** releases claims whose `claimed_at + ttl` is in the past (expired)
+  back to `ready`, clearing the claim fields. `reclaim --id <id>` force-releases a
   specific card regardless of expiry. This is how a crashed worker's card returns
   to the pool.
 
-## CLI — mosaic fleet backlog <sub> --json
+## CLI — `mosaic fleet backlog <sub> --json`
 
 All subcommands support `--json`.
 
 | Subcommand                                                                                    | Purpose                                                                                   |
-| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key] | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
-| list [--status --phase --ready-only]                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
-| claim --owner [--ttl <sec> --id <id>]                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
-| reclaim [--id <id>]                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
-| link --from --to                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
+| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key]` | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
+| `list [--status --phase --ready-only]`                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
+| `claim --owner [--ttl <sec> --id <id>]`                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
+| `reclaim [--id <id>]`                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
+| `link --from --to`                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
 | `stats`                                                                                       | Counts by status, oldest-ready age, expired-claim count.                                  |
-| block --id                                                                                  | Set a card to `blocked`.                                                                  |
-| complete --id                                                                               | Set a card to `done` (releases any claim).                                                |
+| `block --id`                                                                                  | Set a card to `blocked`.                                                                  |
+| `complete --id`                                                                               | Set a card to `done` (releases any claim).                                                |
 
 ### Example
 
-Seed two cards; the second depends on the first. Because A2 is gated on A1, claim returns A1 first. Finish A1, then list A2 as ready. Recover stalled work.
-
-```fleet-command
+```sh
+# Seed two cards, the second depends on the first.
 mosaic fleet backlog create --id A1 --title "schema" --priority 5
 mosaic fleet backlog create --id A2 --title "service" --depends-on A1 --priority 9
 
+# A2 is gated on A1, so claim returns A1 first.
 mosaic fleet backlog claim --owner worker-1 --ttl 600 --json
 
+# Finish A1; now A2 is ready.
 mosaic fleet backlog complete --id A1
 mosaic fleet backlog list --ready-only --json
 
+# Recover stalled work.
 mosaic fleet backlog reclaim --json
 ```

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

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

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

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

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

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

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

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

docs/fleet/examples/roster-v2.yaml

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

docs/fleet/f4-matrix-connector.md

@@ -15,7 +15,7 @@ core.
 
 Connectors implement one small, uniform interface (`src/fleet/connectors/types.ts`):
 
-```typescript
+```ts
 interface OrchestratorConnector {
   readonly kind: 'tmux' | 'discord' | 'matrix';
   send(message: OutboundMessage): Promise<SendResult>; // orchestrator → human
@@ -25,11 +25,11 @@ interface OrchestratorConnector {
 ```
 
 - **send / subscribe / health** — the only surface fleet core depends on. `SendResult` is the
-  ack half; health() is the liveness half.
+  ack half; `health()` is the liveness half.
 - **Thread-aware by metadata** — `OutboundMessage.threadId` / `InboundMessage.threadId` are
   optional, so thread-capable connectors (Matrix rooms/threads, the future first-party Mosaic
   Discord plugin) fit **without an interface change**.
-- **Registry** (`registry.ts`) — implementations register a factory by kind; createConnector(config)
+- **Registry** (`registry.ts`) — implementations register a factory by kind; `createConnector(config)`
   resolves one from roster config. Phase 1 ships the registry + `resolveConnectorKind` (defaults
   `tmux` when a roster declares no connector — **back-compat**); the factories land in Phase 2.
 
@@ -39,7 +39,7 @@ A roster may carry an optional `connector` block (`roster.schema.json`); absent
 
 ```yaml
 connector:
-  kind: matrix
+  kind: matrix # tmux | discord | matrix
   matrix:
     homeserver_url: https://matrix.example.internal
     user_id: '@mos:example.internal'
@@ -56,10 +56,10 @@ The connector speaks the **Matrix client-server API** directly over HTTPS (`fetc
 for MVP), so it is **homeserver-agnostic**:
 
 | Op          | Matrix CS-API                                                            |
-| ----------- | ----------------------------------------------------------------------- |
-| `send`      | PUT /\_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}      |
-| `subscribe` | GET /\_matrix/client/v3/sync (long-poll, `since` token) → room timeline |
-| `health`    | GET /\_matrix/client/versions (reachable) + …/account/whoami (authed)   |
+| ----------- | ------------------------------------------------------------------------ |
+| `send`      | `PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}`      |
+| `subscribe` | `GET /_matrix/client/v3/sync` (long-poll, `since` token) → room timeline |
+| `health`    | `GET /_matrix/client/versions` (reachable) + `…/account/whoami` (authed) |
 | threads     | `m.thread` relations ↔ `threadId`                                        |
 
 ## Local homeserver (infra, not connector code)
@@ -79,7 +79,7 @@ homeserver choice is a **deployment** concern (a Phase-2 deploy guide), not conn
 | ----- | --------------------------------------------------------------------------------------- | ------- |
 | **1** | Connector interface + types, registry + kind resolution, roster `connector` schema, doc | ✅ yes  |
 | 2     | Matrix CS-API client (fetch-based send/sync/health) + registered factory + tests        | follow  |
-| 2     | fleet init / `configure` connector-selection UX; roster parse wires the block           | follow  |
+| 2     | `fleet init` / `configure` connector-selection UX; roster parse wires the block         | follow  |
 | 2     | systemd launch wiring so the orchestrator starts on the chosen connector                | follow  |
 | 3     | Conduit deploy guide; first-party Mosaic Discord (threads) registers as a connector     | follow  |
 

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

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

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

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

docs/fleet/how-to/create-update-delete-agent.md

@@ -4,20 +4,20 @@ Use the local roster-v2 control plane only. These commands change desired state
 
 ## Read and plan first
 
-```fleet-synopsis
+```sh
 mosaic fleet get <name>
 mosaic fleet plan create --expected-generation <n> --agent '<json>'
 mosaic fleet plan update <name> --expected-generation <n> --agent '<json>'
 mosaic fleet plan delete <name> --expected-generation <n>
 ```
 
-plan create takes the name from `--agent`. plan update and plan delete require the target name immediately after the operation. A plan is deterministic and side-effect free: it validates the complete proposed roster and projection targets without changing files. Use `--dry-run` on `create`, `update`, or `delete` for the same no-write result.
+`plan create` takes the name from `--agent`. `plan update` and `plan delete` require the target name immediately after the operation. A plan is deterministic and side-effect free: it validates the complete proposed roster and projection targets without changing files. Use `--dry-run` on `create`, `update`, or `delete` for the same no-write result.
 
-Every successful command prints JSON. `get` returns { "generation", "agent" }; mutation results contain `plan`, `applied`, `authoritativeRoster`, and `projections`.
+Every successful command prints JSON. `get` returns `{ "generation", "agent" }`; mutation results contain `plan`, `applied`, `authoritativeRoster`, and `projections`.
 
 ## Create safely
 
-```fleet-command
+```sh
 mosaic fleet create --expected-generation 7 --agent '{
   "name":"coder0",
   "alias":"Coder 0",
@@ -34,20 +34,20 @@ mosaic fleet create --expected-generation 7 --agent '{
 }'
 ```
 
-Create defaults to enabled: true and desired_state: stopped. It does not start a process. Add `--persisted-start` only to persist desired_state: running; that still does not start a runtime in this M2 command. The JSON payload is an allowlist of the roster-v2 fields shown above plus `launch.yolo`; command, channel, secret-reference, and other unknown keys are rejected rather than ignored. The JSON error exposes only a stable code, never the rejected value.
+Create defaults to `enabled: true` and `desired_state: stopped`. It does not start a process. Add `--persisted-start` only to persist `desired_state: running`; that still does not start a runtime in this M2 command. The JSON payload is an allowlist of the roster-v2 fields shown above plus `launch.yolo`; command, channel, secret-reference, and other unknown keys are rejected rather than ignored. The JSON error exposes only a stable code, never the rejected value.
 
 ## Update and delete safely
 
-```fleet-synopsis
-mosaic fleet update <name> --expected-generation <n> --agent '<complete JSON agent payload>'
-mosaic fleet delete <name> --expected-generation <n>
+```sh
+mosaic fleet update coder0 --expected-generation 8 --agent '<complete JSON agent payload>'
+mosaic fleet delete coder0 --expected-generation 9
 ```
 
 Updates require a complete agent JSON payload and preserve the stable name. Delete removes only the exact roster-owned `coder0.env.generated` projection. It retains `coder0.env.local`, legacy `coder0.env`, `coder0.env.quarantine`, and every unrelated projection. A delete dry-run leaves all of those files byte-identical.
 
 ## Handle generation conflicts
 
-Every mutation requires the current authoritative `--expected-generation`. A stale value returns JSON error.code: "stale-generation" with a non-zero exit. Reload with mosaic fleet get <name> or reread the roster, plan again using the returned generation, then retry. A concurrent mutation returns `concurrent-mutation`; do not force or bypass the lock.
+Every mutation requires the current authoritative `--expected-generation`. A stale value returns JSON `error.code: "stale-generation"` with a non-zero exit. Reload with `mosaic fleet get <name>` or reread the roster, plan again using the returned generation, then retry. A concurrent mutation returns `concurrent-mutation`; do not force or bypass the lock.
 
 ## Interpret partial failures
 
@@ -71,4 +71,4 @@ This is not a rollback and not a no-op: reload the roster because its generation
 
 Handled validation errors and partial projection failures exit non-zero. `plan`/`--dry-run` and normal mutation JSON make the state explicit; scripts should use both the exit code and `authoritativeRoster`/`projections`, not `applied` alone.
 
-The commands operate only on <mosaic-home>/fleet/roster.yaml, the local roster desired-state authority. They do not accept arbitrary commands, channels, secrets, remote/connector actions, migration/canary actions, or runtime lifecycle operations.
+The commands operate only on `<mosaic-home>/fleet/roster.yaml`, the local roster desired-state authority. They do not accept arbitrary commands, channels, secrets, remote/connector actions, migration/canary actions, or runtime lifecycle operations.

docs/fleet/how-to/customize-roles.md

@@ -2,8 +2,8 @@
 
 Mosaic resolves persona contracts through two layers:
 
-1. fleet/roles/<canonical-class>.md — seeded baseline contract.
-2. fleet/roles.local/<canonical-class>.md — operator override or custom role; this layer wins.
+1. `fleet/roles/<canonical-class>.md` — seeded baseline contract.
+2. `fleet/roles.local/<canonical-class>.md` — operator override or custom role; this layer wins.
 
 The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation,
 and launch-time persona injection.
@@ -34,11 +34,11 @@ A custom class remains supported when a readable contract exists for the exact i
 The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
 ```
 
-Save it as `fleet/roles.local/release-notes.md`, then reference class: release-notes and a matching
-tool_policy: release-notes in roster v2. Adding only a `LIBRARY.md` row is insufficient.
+Save it as `fleet/roles.local/release-notes.md`, then reference `class: release-notes` and a matching
+`tool_policy: release-notes` in roster v2. Adding only a `LIBRARY.md` row is insufficient.
 
 Names such as `worker`, `analyst`, and `canary` are not built-in aliases; they need genuine custom
-contracts. agents[].alias, Tess, and Ultron are display names and cannot select a class.
+contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.
 
 ## Validation and authority boundaries
 

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

@@ -2,22 +2,22 @@
 
 Use the canonical local roster-v2 command surface:
 
-```fleet-synopsis
+```sh
 mosaic fleet apply --expected-generation <n> --dry-run
 mosaic fleet apply --expected-generation <n>
 mosaic fleet reconcile --expected-generation <n>
 mosaic fleet start <name> --expected-generation <n>
 mosaic fleet stop <name> --expected-generation <n>
 mosaic fleet restart <name> --expected-generation <n>
-mosaic fleet status [<name>]
+mosaic fleet status [name]
 mosaic fleet verify
 mosaic fleet doctor
 ```
 
-Start with `--dry-run`. It validates roster semantics, deterministic projections, private managed paths, exact holder ownership, and named-socket state without changing files or lifecycle state. Explicit `apply` and `reconcile` rebuild derived projections and enforce persisted roster state: enabled `running` agents may start, while stopped or disabled agents are not started. This guarantee does not extend to reboot/service activation yet; boot preservation remains an FCM-M3-002 hold.
+Start with `--dry-run`. It validates roster semantics, deterministic projections, private managed paths, exact holder ownership, and named-socket state without changing files or lifecycle state. `apply` and `reconcile` rebuild derived projections and enforce only persisted roster state: enabled `running` agents may start, while stopped or disabled agents are not started.
 
-`start`, `stop`, and `restart` are explicit one-shot exact-service actions. They do not persist a lifecycle change. `update` preserves the agent's existing lifecycle, and no delivered operation changes durable lifecycle after creation.
+`start`, `stop`, and `restart` are explicit one-shot exact-service actions. They do not persist a lifecycle change. Roster CRUD is the only way to change persisted desired state.
 
-Every command prints JSON. Observation commands report drift without mutation; `verify` exits non-zero on ownership mismatch, unmanaged sessions, or drift. A failed apply that wrote some derived projections reports projections: "incomplete" with bounded recovery to regenerate from the roster. A lifecycle failure after projections reports incomplete lifecycle work; it is never represented as a rollback or no-op.
+Every command prints JSON. Observation commands report drift without mutation; `verify` exits non-zero on ownership mismatch, unmanaged sessions, or drift. A failed apply that wrote some derived projections reports `projections: "incomplete"` with bounded recovery to regenerate from the roster. A lifecycle failure after projections reports incomplete lifecycle work; it is never represented as a rollback or no-op.
 
 These commands are local only. Remote/SSH/connector entries are inventory/validation-only. Commands do not accept arbitrary runtime commands, channels, secrets, generated-file desired state, or arbitrary tmux sockets.

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

@@ -11,7 +11,7 @@ artifact is added, removed, or left without one of the dispositions below.
 ## Disposition rules
 
 - **Explicit v1 fixture:** the artifact is loaded through the existing v1 roster parser and must
-  declare version: 1. It remains a compatibility fixture; it is not silently treated as a v2
+  declare `version: 1`. It remains a compatibility fixture; it is not silently treated as a v2
   roster or given inferred aliases.
 - **Canonical profile:** the artifact is loaded through `loadProfiles`, which uses the shared
   baseline-plus-`roles.local` persona resolver and rejects unreadable or unresolved classes.
@@ -59,7 +59,7 @@ rollback; those gates belong to FCM-M4-002. See [v1-to-v2 preview](./v1-to-v2.md
 
 ## Running the guard
 
-```fleet-command
+```bash
 pnpm --filter @mosaicstack/mosaic test -- v1-v2-migration.spec.ts \
   -t "validates all 13 shipped artifacts and executes ready previews for every v1 fixture"
 ```

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

@@ -2,14 +2,14 @@
 
 **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
+`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
 
-```fleet-command
+```bash
 mosaic fleet migrate-v1 preview \
   --source roster-v1.yaml \
   --decisions migration-decisions.json \
@@ -45,13 +45,13 @@ 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 |
+| 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 `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                                                                                                                                                                                                                                                                                                   |
@@ -61,8 +61,8 @@ be marked disabled. Observed-stopped agents always remain stopped.
 | 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
+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.
 

docs/fleet/north-star.md

@@ -44,9 +44,9 @@ The Fleet inherits — does not re-invent — the MVP's hard requirements:
 | MVP req                       | What it means for the Fleet                                                                                             |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
 | MVP-X1 three-surface parity   | fleet observability/control reachable via **CLI + TUI + webUI** (CLI first; webUI is required for parity, not optional) |
-| MVP-X2 multi-tenant isolation | one tenant = one **Linux uid** (own systemd --user, socket, ~/.config/mosaic); no cross-tenant leakage                  |
+| MVP-X2 multi-tenant isolation | one tenant = one **Linux uid** (own `systemd --user`, socket, `~/.config/mosaic`); no cross-tenant leakage              |
 | MVP-X3 auth (BetterAuth/SSO)  | operator→fleet and cross-host views are auth-gated through the platform's existing auth                                 |
-| MVP-X4 quality gates          | pnpm typecheck/`lint`/`format:check` green before any push                                                              |
+| MVP-X4 quality gates          | `pnpm typecheck`/`lint`/`format:check` green before any push                                                            |
 | MVP-X5 federated topology     | cross-host fleet visibility rides the **federation** boundary (W1), not a bespoke broker                                |
 | MVP-X6 OTEL tracing           | heartbeats, sends, and lifecycle events emit spans; `traceparent` crosses the federation boundary                       |
 | MVP-X7 trunk merge            | branch from `main`, squash-merge via PR, never push to `main`                                                           |
@@ -56,9 +56,9 @@ The Fleet inherits — does not re-invent — the MVP's hard requirements:
 One **definition** is the source of truth; the **session** is how it runs.
 
 | Layer                            | Owner                                                                                       | Phase-2 reality                                        | Destination                                                                                                                         |
-| -------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| **Definition + identity + auth** | gateway / `mosaic-as` (scoped tokens, #541)                                             | `roster.yaml` (tenant-tagged)                          | one definition; mosaic agent --new materializes it                                                                                  |
-| **Tenancy boundary**             | **Linux uid per tenant** (linger, own systemd --user, own socket, own ~/.config/mosaic) | one tenant: `jarvis` = tenant zero                     | uid-per-tenant; federation aggregates across hosts                                                                                  |
+| -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Definition + identity + auth** | gateway / `mosaic-as` (scoped tokens, #541)                                                 | `roster.yaml` (tenant-tagged)                          | one definition; `mosaic agent --new` materializes it                                                                                |
+| **Tenancy boundary**             | **Linux uid per tenant** (linger, own `systemd --user`, own socket, own `~/.config/mosaic`) | one tenant: `jarvis` = tenant zero                     | uid-per-tenant; federation aggregates across hosts                                                                                  |
 | **Runtime**                      | per-tenant tmux session on isolated socket                                                  | dogfood stub sessions (live now on `mosaic-factory`)   | claude/codex/pi/opencode TUIs                                                                                                       |
 | **Liveness**                     | **heartbeat protocol** every runtime answers                                                | protocol defined + dogfood stub answers it             | all runtimes answer; "healthy" ≠ "pane alive"                                                                                       |
 | **Observation**                  | read-only `watch` (native tmux) + `pipe-pane` stream                                        | CLI `watch`/`ps`; explicit opt-in `attach` for control | + auth-gated webUI streams                                                                                                          |
@@ -68,7 +68,7 @@ One **definition** is the source of truth; the **session** is how it runs.
 
 > **PoC socket hygiene:** the PoC fleet runs on the **default tmux socket** (no `-L`).
 > The named production-isolation socket is **`mosaic-fleet`** (matches the product brand);
-> an absent roster `socket_name` means the default socket everywhere (spawn, fleet ps,
+> an absent roster `socket_name` means the default socket everywhere (spawn, `fleet ps`,
 > onboarding cheat-sheet). The legacy dogfood canary still runs on the old `mosaic-factory`
 > socket pending migration.
 
@@ -177,7 +177,7 @@ routing flow**, **concurrency** (the spend multiplier), and **hard API-token $-l
 are enforced at the orchestrator + routing boundary, not inside individual workers (a worker never
 decides its own budget — see delegation discipline).
 
-**Budget CLI UX (#558):** mosaic budget set --reset-at sets the window reset; reset-datetimes
+**Budget CLI UX (#558):** `mosaic budget set --reset-at` sets the window reset; reset-datetimes
 carry **confidence tags** (`user` / `provider` / `estimated` / `unknown`); and **urgency/criticality
 is a dispatch-gate modifier** — high-urgency work may override even-spread pacing **within
 authorization**. (Also feeds the budgeting workstream, not only this doc.)
@@ -185,14 +185,14 @@ authorization**. (Also feeds the budgeting workstream, not only this doc.)
 ## Observation model
 
 | Verb                                | Behavior                                                                                           |
-| --------------------------------- | -------------------------------------------------------------------------------------------------- |
-| mosaic fleet ps                   | one table joining systemd + tmux + process + idle + last-heartbeat, with drift + boot-enable flags |
-| mosaic agent watch <name>         | **read-only** join (grouped session / `-r`), no resize tyranny, no keystrokes                      |
-| mosaic agent attach <name>        | explicit interactive takeover (the only path that can type)                                        |
-| mosaic agent send <name> --verify | confirms message **accepted**, not merely keystroke-injected                                       |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `mosaic fleet ps`                   | one table joining systemd + tmux + process + idle + last-heartbeat, with drift + boot-enable flags |
+| `mosaic agent watch <name>`         | **read-only** join (grouped session / `-r`), no resize tyranny, no keystrokes                      |
+| `mosaic agent attach <name>`        | explicit interactive takeover (the only path that can type)                                        |
+| `mosaic agent send <name> --verify` | confirms message **accepted**, not merely keystroke-injected                                       |
 
 > Why the current PoC blocks observation: sessions live on the isolated `mosaic-factory`
-> socket (invisible to default tmux ls), the only sanctioned read is `capture-pane`
+> socket (invisible to default `tmux ls`), the only sanctioned read is `capture-pane`
 > (blank for full-screen TUIs), and `attach` is read-write + resizes the session. The
 > verbs above restore "join and observe" safely.
 
@@ -214,7 +214,7 @@ compromised pane cannot corrupt or exfiltrate the register.
 | Layer                  | Responsibility                                                                                                | Implementation                                                                                                                                                                                            |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Register**           | Source of truth: agents, missions, tasks, heartbeats, spend                                                   | Postgres `fleet` schema — existing stack instance (`@mosaicstack/db`)                                                                                                                                     |
-| **Access**             | Typed, auth-gated API                                                                                         | Gateway fleet/\* routes                                                                                                                                                                                   |
+| **Access**             | Typed, auth-gated API                                                                                         | Gateway `fleet/*` routes                                                                                                                                                                                  |
 | **Dispatcher**         | Brief classification, BOD review, planning/coding/review/test/deploy sequencing + gates → fleet task dispatch | **forge pipeline engine** (`runPipeline`/`resumePipeline`, brief classifier, BOD) **+ thin `forge-exec` adapter → `agent-send.sh`**; NOT a new daemon — forge is reused, only stage→agent dispatch is new |
 | **Orchestrator (Mos)** | Goals, missions, judgment, user/PA interface                                                                  | Context-light; sets intent → re-engages only for decisions                                                                                                                                                |
 
@@ -236,7 +236,7 @@ role implementation.
 
 `docs/TASKS.md` and `MISSION-MANIFEST.md` are **generated projections** of the DB,
 not hand-maintained. The dispatcher (or a scheduled job) renders Markdown from
-fleet.\* tables and commits the output. DB is authoritative; docs are for human
+`fleet.*` tables and commits the output. DB is authoritative; docs are for human
 reference.
 
 ### Spend
@@ -267,11 +267,11 @@ re-evaluate if isolation or write-volume demands it.
 ## Phased roadmap
 
 | Phase                  | Outcome                                                                                                                                                                                                  | Status  |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
 | 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                                                                                   | ✅ done |
-| **2 — Observability**  | fleet ps (host+tenant aware join), heartbeat protocol + dogfood stub answers it, agent watch (read-only), agent send --verify receipts                                                                 | ▶ now   |
+| **2 — Observability**  | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts                                                             | ▶ now   |
 | 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)                                                                | planned |
-| 4 — Unified definition | one agent schema in gateway; mosaic agent --new → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
+| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
 | 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**              | planned |
 
 ## Decisions of record (2026-06-20, with Jason)
@@ -285,9 +285,9 @@ re-evaluate if isolation or write-volume demands it.
 - Delivery: **CLI-first now**, dogfood against the live stub fleet; webUI deferred to Phase 5.
 - Runtimes: fleet agents default to **Codex / pi-on-Codex**; **Claude is reserved for Claude
   Code only** (avoid alternate-harness API pricing). Validated durable recipe:
-  mosaic yolo pi --model openai-codex/gpt-5.5:high. Durable detached launch requires the
+  `mosaic yolo pi --model openai-codex/gpt-5.5:high`. Durable detached launch requires the
   runtime-bin on PATH (baked into the pane command) + boot-survival (`enable` + linger),
-  which fleet init should automate.
+  which `fleet init` should automate.
 
 ## Decisions of record (2026-06-22, with Jason)
 
@@ -304,18 +304,19 @@ re-evaluate if isolation or write-volume demands it.
 - **Session context cap = 200k tokens (GLOBAL to all Claude sessions):** Claude Code sessions are
   capped at a **max 200k-token context window**. Long-running sessions extended toward 1M tokens
   have proven **worse in practice** (degraded steering, off-plan divergence); 200k is the standard.
-  **Enforcement split:** the _window_ lives in **~/.claude/settings.json** (host-global) as
-  "autoCompactWindow": 200000 + "autoCompactEnabled": true; the _1M-disable_ lives in **launch
+  **Enforcement split:** the _window_ lives in **`~/.claude/settings.json`** (host-global) as
+  `"autoCompactWindow": 200000` + `"autoCompactEnabled": true`; the _1M-disable_ lives in **launch
   ENV** (`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, plus `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`) wherever
-  a [1m] model can be selected (`mos-claude.service` + the fleet Claude launcher), so every Claude
+  a `[1m]` model can be selected (`mos-claude.service` + the fleet Claude launcher), so every Claude
   agent is capped at spawn. (settings = window; env = 1M-disable.)
 - **Worker context bound (#8):** workers are kept context-bounded via the **ephemeral-per-lane
   lifecycle + native compaction**, not via the 200k knob. The explicit `autoCompactWindow` 200k knob
   **stays Claude-specific** — the _principle_ (bounded context) extends to workers, the _knob_ does not.
 - **Orchestrator delegation discipline:** the orchestrator **delegates all delivery work** to
-  subagents / workflows / ultracode / coder agents and confines its own context to the personal-assistant
-  lane. Keeping delivery out of the orchestrator's window keeps its context unpolluted and measurably
-  reduces off-plan divergence. The orchestrator coordinates and decides; it does not implement.
+  subagents / workflows / ultracode / coder agents and confines its own context to \*\*orchestration
+  - the personal-assistant lane\*\*. Keeping delivery out of the orchestrator's window keeps its
+    context unpolluted and measurably reduces off-plan divergence. The orchestrator coordinates and
+    decides; it does not implement.
 - **Budget governance is fleet doctrine:** token/API-dollar budgeting is a first-class fleet concern
   (see "Budget & token governance"). OAuth-sub usage-vs-limit feedback is ingested per account, spend
   is **auto-paced EVEN-SPREAD over remaining time** (rapid/overspend only on explicit authorization),
@@ -343,7 +344,7 @@ re-evaluate if isolation or write-volume demands it.
 ### Control plane & central register
 
 - **Store:** Postgres (existing stack instance, dedicated `fleet` schema via `@mosaicstack/db`). SQLite rejected: (1) it is a local file — structurally incompatible with a multi-host fleet; (2) concurrent multi-agent writes caused repeated corruption in Hermes. "SQLite + access service" rejected as reinventing a DB server badly; "LLM agent gating DB access" rejected as slow, expensive, and a single point of failure.
-- **Access:** gateway API only (`apps/gateway`, fleet/\* routes). No raw DB credentials in any agent/dispatcher pane — directly mitigates the tmux attack-surface concern.
+- **Access:** gateway API only (`apps/gateway`, `fleet/*` routes). No raw DB credentials in any agent/dispatcher pane — directly mitigates the tmux attack-surface concern.
 - **Dispatcher = forge (reuse, not a new build):** the dispatcher IS `@mosaicstack/forge`'s pipeline engine (`runPipeline`/`resumePipeline` + brief classifier + BOD persona loader), a fully-implemented software-factory pipeline (brief → BOD review → 3 planning stages → coding → review/remediation → testing → deploy). We do **not** design/build a new dispatcher and do **not** re-implement sequencing, gate logic, or brief classification. The only new fleet-owned piece is a thin **`forge-exec` TaskExecutor adapter** (suggested package `packages/forge-exec`) mapping a `ForgeTask` → `agent-send.sh` dispatch to a named fleet agent — forge's single missing piece. It is tracked as a Gitea issue and built **post-PoC** (not now).
 - **Register backs forge:** the Postgres `fleet` register is genuinely new (neither forge nor the fleet has cross-project state). It BACKS forge's pipeline state (durable `resumePipeline`, cross-host) plus cross-project missions/tasks/Kanban.
 - **'board' role = forge BOD:** the north-star role-library 'board' role IS forge's Board-of-Directors — reused, not reinvented.
@@ -356,9 +357,9 @@ re-evaluate if isolation or write-volume demands it.
 
 - **Per-agent model switch (operator-configurable, NOT a global lock):** model selection is
   **per-agent**, never a host-global pin. Claude sessions MUST NOT be locked to a single model in
-  ~/.claude/settings.json; each agent chooses its model independently. The plumbing already exists —
-  roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends --model <hint> to that
-  agent's harness (claude or pi); settable today via mosaic fleet add|edit <agent> --model <hint>.
+  `~/.claude/settings.json`; each agent chooses its model independently. The plumbing already exists —
+  roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends `--model <hint>` to that
+  agent's harness (claude or pi); settable today via `mosaic fleet add|edit <agent> --model <hint>`.
   **North-star target:** surface this as a **per-agent model switch in the webUI** (with CLI/TUI parity
   per MVP-X1) — read the roster, expose a per-agent model dropdown, write `model_hint` back, and restart
   that one agent to apply. Unset = inherit the harness default. This **composes with** the budget
@@ -384,7 +385,7 @@ re-evaluate if isolation or write-volume demands it.
   self-hosted homeserver (Conduit default, Synapse alt). Matrix is named here as the strategic
   future transport — peer to tmux/Discord, not superseded by them.
 - **tmux fleet attack-surface hardening.** Many always-on tmux sessions are an attack surface;
-  tmux send-keys / socket access could enable malicious action against agents directly.
+  `tmux send-keys` / socket access could enable malicious action against agents directly.
   Mitigations to build toward: socket ownership/perms, per-tenant socket isolation (already an
   invariant), authenticated `agent-send`, and an audit of who can write to any pane. **Post-MVP
   unless a P0 surfaces.** The control-plane register reinforces this (gateway-API access = no raw
@@ -417,9 +418,9 @@ re-evaluate if isolation or write-volume demands it.
 
 ---
 
-> **Release procedure (drift re-capture, 2026-06-22):** mosaic update only propagates new fleet
+> **Release procedure (drift re-capture, 2026-06-22):** `mosaic update` only propagates new fleet
 > commands when the **CLI version is bumped** — without a version bump, fleet command changes never
-> reach installed hosts. The release/version-bump procedure (bump → publish → mosaic update
+> reach installed hosts. The release/version-bump procedure (bump → publish → `mosaic update`
 > [→ `--relaunch`]) must be documented so fleet changes actually land. (Also feeds the budgeting
 > workstream.)
 >

docs/fleet/operations/backup-restore.md

@@ -30,7 +30,7 @@ connector entry.
 
 The preview evidence deliberately records:
 
-- executable: false;
+- `executable: false`;
 - required backup artifacts;
 - source and candidate identities;
 - lifecycle observations and resulting desired states;

docs/fleet/operations/env-quarantine.md

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

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

@@ -2,12 +2,10 @@
 
 ## Safe sequence
 
-1. Read mosaic fleet doctor and mosaic fleet status.
-2. Run mosaic fleet apply --expected-generation <n> --dry-run.
+1. Read `mosaic fleet doctor` and `mosaic fleet status`.
+2. Run `mosaic fleet apply --expected-generation <n> --dry-run`.
 3. Resolve stale generation, ownership mismatch, unsafe path, projection validation, or unmanaged-session findings before applying.
-4. Run mosaic fleet apply --expected-generation <n> only after the plan is understood.
-
-This is per-generation convergence, not a rolling canary. Executable canary cutover/rollback remains held for FCM-M4-002; rolling local release evidence remains FCM-M5-002. Do not approximate either with repeated live apply commands.
+4. Run `mosaic fleet apply --expected-generation <n>` only after the plan is understood.
 
 The reconciler uses the exact roster tmux socket, exact holder session, private installation holder identity, and the complete expected global environment. For mutations it acquires its exclusive lock before rereading the canonical roster and fencing its generation; only that under-lock roster drives validation, planning, projections, and lifecycle effects. Before effects, its exclusive lock proves real private `MOSAIC_HOME` and `fleet` ancestors, uses a private `0600` lock leaf, and binds cleanup to the created file identity and ownership token. A fake holder, contaminated global environment, missing identity, unsafe lock path, or unmanaged session fails closed. It does not adopt, kill, or rename any unproven session. A crash can leave a stale lock for explicit operator inspection; reconciliation deliberately does not guess ownership or remove it.
 
@@ -25,4 +23,4 @@ The roster is never changed by reconciliation. If derived projection application
 }
 ```
 
-If projections completed but lifecycle work failed, JSON reports projections: "complete", lifecycle: "incomplete", and the bounded action `rerun-after-inspecting-owned-resources`. If lock cleanup cannot be proven after an effect result, it adds cleanup: { "code": "lock-cleanup-failed", "action": "inspect-lock-before-retry" } without changing the known projection, lifecycle, or primary recovery truth. Inspect the retained lock before retrying; no rollback, release, or stale-lock removal is implied. Results do not include environment values, secrets, or privileged command content.
+If projections completed but lifecycle work failed, JSON reports `projections: "complete"`, `lifecycle: "incomplete"`, and the bounded action `rerun-after-inspecting-owned-resources`. If lock cleanup cannot be proven after an effect result, it adds `cleanup: { "code": "lock-cleanup-failed", "action": "inspect-lock-before-retry" }` without changing the known projection, lifecycle, or primary recovery truth. Inspect the retained lock before retrying; no rollback, release, or stale-lock removal is implied. Results do not include environment values, secrets, or privileged command content.

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

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

docs/fleet/operations/upgrade-assets.md

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

docs/fleet/reference/agent-mutations.md

@@ -4,17 +4,17 @@ FCM-M2-002 provides local roster-v2 create, get, update, delete, and plan operat
 
 ## CLI contract
 
-The commands operate only on the canonical <mosaic-home>/fleet/roster.yaml v2 authority and print one JSON object to stdout. `--agent` is a JSON object with the roster agent fields expressed as `className`, `toolPolicy`, `workingDirectory`, `persistentPersona`, `resetBetweenTasks`, and launch: { "yolo": boolean }.
+The commands operate only on the canonical `<mosaic-home>/fleet/roster.yaml` v2 authority and print one JSON object to stdout. `--agent` is a JSON object with the roster agent fields expressed as `className`, `toolPolicy`, `workingDirectory`, `persistentPersona`, `resetBetweenTasks`, and `launch: { "yolo": boolean }`.
 
-```fleet-synopsis
+```sh
 mosaic fleet get <name>
-mosaic fleet plan <create|update|delete> [<name>] --expected-generation <n> [--agent '<json>'] [--persisted-start]
+mosaic fleet plan <create|update|delete> [name] --expected-generation <n> [--agent '<json>'] [--persisted-start]
 mosaic fleet create --expected-generation <n> --agent '<json>' [--dry-run] [--persisted-start]
 mosaic fleet update <name> --expected-generation <n> --agent '<json>' [--dry-run]
 mosaic fleet delete <name> --expected-generation <n> [--dry-run]
 ```
 
-`get` returns the authoritative generation and the selected agent. plan create derives its name from `--agent`; plan update <name> and plan delete <name> require the target name. `--agent` accepts only the documented roster-v2 request fields and `launch.yolo`; unknown keys such as commands, channels, or secret references are rejected. Rejection diagnostics return only the stable `invalid-request` code and never echo a rejected value. `plan` and `--dry-run` validate the complete proposed roster and projections but write neither the roster nor projections. `--persisted-start` is available only for a create request: it records desired_state: running, but does not start a process. Without it, create records enabled: true and desired_state: stopped. Handled failures return JSON with `error.code` and exit non-zero; unclassified validation/projection failures use the redacted `mutation-failed` code.
+`get` returns the authoritative generation and the selected agent. `plan create` derives its name from `--agent`; `plan update <name>` and `plan delete <name>` require the target name. `--agent` accepts only the documented roster-v2 request fields and `launch.yolo`; unknown keys such as commands, channels, or secret references are rejected. Rejection diagnostics return only the stable `invalid-request` code and never echo a rejected value. `plan` and `--dry-run` validate the complete proposed roster and projections but write neither the roster nor projections. `--persisted-start` is available only for a create request: it records `desired_state: running`, but does not start a process. Without it, create records `enabled: true` and `desired_state: stopped`. Handled failures return JSON with `error.code` and exit non-zero; unclassified validation/projection failures use the redacted `mutation-failed` code.
 
 ## Generation, validation, and idempotency
 
@@ -22,7 +22,7 @@ Each create, update, or delete request includes `expectedGeneration`. A request
 
 `planFleetAgentMutation` is deterministic and side-effect free. `executeFleetAgentMutation` validates the complete proposed roster through the existing structural and shared persona resolver, prepares generated/local/quarantine projections, and writes the roster authority atomically before applying derived projections. Equivalent create retries and delete requests for an already-absent agent are idempotent no-ops.
 
-Delete removes only the exact <name>.env.generated projection for the removed roster entry. Operator-owned <name>.env.local, legacy <name>.env, quarantine records, and unrelated projections remain untouched. An already-absent generated projection is treated as stale derived state, not as a failed mutation.
+Delete removes only the exact `<name>.env.generated` projection for the removed roster entry. Operator-owned `<name>.env.local`, legacy `<name>.env`, quarantine records, and unrelated projections remain untouched. An already-absent generated projection is treated as stale derived state, not as a failed mutation.
 
 ## Result and recovery
 
@@ -40,4 +40,4 @@ Mutation results are JSON-safe objects with `applied`, `authoritativeRoster`, `p
 }
 ```
 
-Dry-runs and idempotent no-ops report authoritativeRoster: "unchanged" and projections: "not-applied"; a complete mutation reports "committed" and "complete". Recovery output identifies the authoritative roster path and regeneration action only. It never contains generated/local/quarantine values, credentials, or command text. A recovery result exits non-zero because the authoritative roster was persisted but derived projections require regeneration. Regenerate projections from the roster before attempting another mutation.
+Dry-runs and idempotent no-ops report `authoritativeRoster: "unchanged"` and `projections: "not-applied"`; a complete mutation reports `"committed"` and `"complete"`. Recovery output identifies the authoritative roster path and regeneration action only. It never contains generated/local/quarantine values, credentials, or command text. A recovery result exits non-zero because the authoritative roster was persisted but derived projections require regeneration. Regenerate projections from the roster before attempting another mutation.

docs/fleet/reference/cli.md

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

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

@@ -1,6 +1,6 @@
 # Fleet Generated Environment Boundary
 
-**Card:** FCM-M2-001 · **Issue:** #758 · **Status:** merged contract
+**Card:** FCM-M2-001 · **Issue:** #758 · **Status:** unreleased/card-local
 
 The local fleet roster is the desired-state authority. A launch reads a deterministic,
 roster-derived generated projection and an optional strictly data-only local file; neither file is
@@ -8,14 +8,14 @@ a second roster or a command configuration surface.
 
 ## Paths and ownership
 
-For agent <name> under <MOSAIC_HOME>/fleet/agents/:
+For agent `<name>` under `<MOSAIC_HOME>/fleet/agents/`:
 
 | Path                    | Owner                    | Purpose                                                                                                                      |
-| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| <name>.env.generated  | Mosaic projection writer | Complete deterministic launch data rendered from the authoritative roster.                                                   |
-| <name>.env.local      | Operator                 | Optional, constrained local machine data. It cannot shadow generated keys.                                                   |
-| <name>.env            | Legacy input only        | Read once during projection generation, then regenerated/relocated or privately quarantined. It is never a launch authority. |
-| <name>.env.quarantine | Mosaic quarantine        | Mode-`0600` private record of forbidden legacy input; it is never read by the launcher.                                      |
+| ----------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `<name>.env.generated`  | Mosaic projection writer | Complete deterministic launch data rendered from the authoritative roster.                                                   |
+| `<name>.env.local`      | Operator                 | Optional, constrained local machine data. It cannot shadow generated keys.                                                   |
+| `<name>.env`            | Legacy input only        | Read once during projection generation, then regenerated/relocated or privately quarantined. It is never a launch authority. |
+| `<name>.env.quarantine` | Mosaic quarantine        | Mode-`0600` private record of forbidden legacy input; it is never read by the launcher.                                      |
 
 The systemd templates do not load either environment file. They invoke Bash with a fixed, cleared
 bootstrap environment; the launcher reads and validates `.env.generated` and `.env.local` itself before
@@ -44,7 +44,7 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
 
-The generated launch contract supports only `claude`, `codex`, `opencode`, and `pi`. fleet add
+The generated launch contract supports only `claude`, `codex`, `opencode`, and `pi`. `fleet add`
 uses that same runtime authority and rejects any other runtime before it writes the roster or changes
 projection, local, or quarantine files. The legacy dogfood stub on its separate `mosaic-factory`
 socket remains an observability canary; it has no generated-launch adapter and cannot be added through
@@ -62,7 +62,7 @@ Local paths must be safe absolute paths and the interval must be a positive inte
 quoted/export syntax, duplicate keys, unknown keys, generated-key shadowing, sensitive key names,
 and `MOSAIC_AGENT_COMMAND` are rejected. The launcher derives the only executable command from the
 validated runtime, model, and reasoning data; no arbitrary command compatibility path exists. When a
-Pi runtime writes a fresh <name>.hb.native marker, its native heartbeat remains authoritative; the
+Pi runtime writes a fresh `<name>.hb.native` marker, its native heartbeat remains authoritative; the
 shell sidecar resumes its `status=ok` fallback only after that marker is stale or absent.
 
 ## Legacy disposition
@@ -79,13 +79,13 @@ consolidated downstream interface packet. Status is deliberately separated from
 product release version has been evidenced for this interface set.
 
 | Interface               | Canonical public path and version                                                                                                                 | Tracker/release status                                                                                                | Downstream limit                                                                              |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| M1 structural compiler  | `parseRosterV2` in `packages/mosaic/src/fleet/roster-v2.ts`; schema `docs/fleet/reference/roster-v2.schema.json`; roster version: 2             | FCM-M1-001 is recorded done, merged as #764 (`aa5b43b`); no released product version is asserted here.    | Parse YAML/JSON and canonicalize a supplied v2 site roster without writes.                    |
-| M1 semantic resolver    | `validateRosterV2Semantics` in `packages/mosaic/src/fleet/roster-v2.ts`; baseline `framework/fleet/roles/` plus `roles.local/`                  | FCM-M1-002 merged as #768 (`a5e8e55`); no released product version is asserted here.                      | Reuse the shared resolver only; no parallel role resolver or lifecycle action.                |
-| M1 disposition evidence | `packages/mosaic/src/fleet/example-profile-dispositions.ts`; `docs/fleet/migration/example-profile-disposition.md`; retained fixture version: 1 | FCM-M1-003 merged as #770 (`e9c4aa3`); checkout evidence remains validation, not migration authorization. | Inspect fixture/profile/service disposition evidence only; it is not migration authorization. |
-| M2 generated boundary   | `packages/mosaic/src/fleet/generated-env-boundary.ts`; generated projection contract in this document                                           | FCM-M2-001 merged as #772 (`191efae`); no released product version is asserted here.                      | Render/write a roster-derived projection; local input is never authority.                     |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| M1 structural compiler  | `parseRosterV2` in `packages/mosaic/src/fleet/roster-v2.ts`; schema `docs/fleet/reference/roster-v2.schema.json`; roster `version: 2`             | FCM-M1-001 is recorded done, merged as #764 (`aa5b43b`); no released product version is asserted here.                | Parse YAML/JSON and canonicalize a supplied v2 site roster without writes.                    |
+| M1 semantic resolver    | `validateRosterV2Semantics` in `packages/mosaic/src/fleet/roster-v2.ts`; baseline `framework/fleet/roles/` plus `roles.local/`                    | FCM-M1-002 remains `in-progress` in `docs/TASKS.md`; unreleased.                                                      | Reuse the shared resolver only; no parallel role resolver or lifecycle action.                |
+| M1 disposition evidence | `packages/mosaic/src/fleet/example-profile-dispositions.ts`; `docs/fleet/migration/example-profile-disposition.md`; retained fixture `version: 1` | FCM-M1-003 remains `not-started` in `docs/TASKS.md`; unreleased even though these checkout artifacts are inspectable. | Inspect fixture/profile/service disposition evidence only; it is not migration authorization. |
+| M2 generated boundary   | `packages/mosaic/src/fleet/generated-env-boundary.ts`; generated projection contract in this document                                             | FCM-M2-001 card-local and uncommitted; unreleased.                                                                    | Render/write a roster-derived projection; local input is never authority.                     |
 
-The canonical source remains <MOSAIC_HOME>/fleet/roster.yaml for the current local fleet path.
+The canonical source remains `<MOSAIC_HOME>/fleet/roster.yaml` for the current local fleet path.
 Generated environment data is a rebuildable projection, not an operator-editable source of membership,
 runtime policy, or lifecycle state.
 

docs/fleet/reference/lifecycle-transitions.md

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

docs/fleet/reference/role-classes.md

@@ -16,7 +16,7 @@ Only these legacy class aliases are recognized:
 
 No other alias is inferred. In particular, `worker`, `analyst`, and `canary` are custom classes only
 when an operator supplies a readable contract for that exact class. Tess and Ultron are instance
-names, not classes. agents[].alias is display-only and cannot grant authority.
+names, not classes. `agents[].alias` is display-only and cannot grant authority.
 
 Canonicalization happens before role lookup. For example, requesting `implementer` resolves
 `code.md`; a separate `roles.local/implementer.md` cannot redefine the legacy alias. A canonical

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

@@ -50,38 +50,36 @@ agents:
 
 ## Root fields
 
-| Field        | Required | Default | Constraint            | Meaning                                                                                           |
-| ------------ | -------- | ------- | --------------------- | ------------------------------------------------------------------------------------------------- |
-| `version`    | yes      | none    | integer constant `2`  | Identifies this contract. Version `1` stays on the compatibility path pending explicit migration. |
-| `generation` | yes      | none    | positive safe integer | Desired-state generation and mutation/reconcile concurrency fence.                                |
-| `transport`  | yes      | none    | constant `tmux`       | M1–M5 support local tmux only.                                                                    |
-| `tmux`       | yes      | none    | strict object         | Explicit local socket and holder-session configuration.                                           |
-| `defaults`   | yes      | none    | strict object         | Default work directory and one supported local runtime.                                           |
-| `runtimes`   | yes      | none    | non-empty object      | Declared local runtime reset policy map.                                                          |
-| `agents`     | yes      | none    | non-empty array       | Local fleet entries. Duplicate stable names are rejected.                                         |
+| Field        | Required | Constraint            | Meaning                                                                                                                               |
+| ------------ | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`    | yes      | integer constant `2`  | Identifies this contract. Version `1` is explicitly rejected by this compiler and remains on the existing v1 path until M4 migration. |
+| `generation` | yes      | positive safe integer | Desired-state generation. M2 uses it for mutation guards; M1 does not mutate it.                                                      |
+| `transport`  | yes      | constant `tmux`       | M1–M5 support local tmux only.                                                                                                        |
+| `tmux`       | yes      | strict object         | Explicit local socket and holder-session configuration.                                                                               |
+| `defaults`   | yes      | strict object         | Default work directory and one supported local runtime.                                                                               |
+| `runtimes`   | yes      | non-empty object      | Declared local runtime reset policy map.                                                                                              |
+| `agents`     | yes      | non-empty array       | Local fleet entries. Duplicate stable names are rejected.                                                                             |
 
 ## Nested fields
 
-All nested fields in the v2 schema are required and have no implicit default. CRUD `create` is the only higher-level convenience: it records lifecycle.enabled: true and desired_state: stopped unless `--persisted-start` explicitly records running. That convenience still performs no runtime action.
-
 | Path                                                 | Required | Constraint                                                                                                    |
-| -------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
-| `tmux.socket_name`                                 | yes      | [A-Za-z0-9_.-]\*; empty string means the literal default tmux server, while a non-empty value names a socket |
-| `tmux.holder_session`                              | yes      | non-empty [A-Za-z0-9_.-]+                                                                                    |
+| ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `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                                         |
+| `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
 
@@ -99,12 +97,12 @@ Semantic validation:
   `operator-interaction` to `interaction`;
 - canonicalizes `tool_policy` with the same exact alias table;
 - rejects protected class/tool-policy mismatches in either direction, while accepting
-  class: operator-interaction with tool_policy: operator-interaction as canonical
+  `class: operator-interaction` with `tool_policy: operator-interaction` as canonical
   `interaction`;
 - derives immutable protected authority only from canonical class; and
 - accepts custom baseline or `roles.local` classes without granting protected authority.
 
-agents[].alias remains display-only. Tess and Ultron are instance names, never semantic classes.
+`agents[].alias` remains display-only. Tess and Ultron are instance names, never semantic classes.
 Canonicalization happens before role-layer lookup, so a legacy-named override cannot redefine an
 alias as separate authority. See [Role Classes and Authority](./role-classes.md) and
 [Customize Fleet Roles](../how-to/customize-roles.md).
@@ -114,7 +112,7 @@ lifecycle mutation.
 
 ## Fail-closed boundary
 
-Every object is additionalProperties: false. The compiler rejects unknown, missing, malformed,
+Every object is `additionalProperties: false`. The compiler rejects unknown, missing, malformed,
 and wrong-type fields before producing a model. It specifically rejects remote/SSH/host/socket
 per-agent fields, connector blocks, secret references, channel fields, arbitrary command fields,
 and gateway fields because they are unsupported in the local-tmux M1 contract. It does not silently

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

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

docs/guides/dev-guide.md

@@ -8,8 +8,9 @@
 4. [Adding New Agent Tools](#adding-new-agent-tools)
 5. [Adding New MCP Tools](#adding-new-mcp-tools)
 6. [Database Schema and Migrations](#database-schema-and-migrations)
-7. [API Endpoint Reference](#api-endpoint-reference)
-8. [Local Fleet Canary](./fleet-local-canary.md)
+7. [Claude Code Skill Bridge](#claude-code-skill-bridge)
+8. [API Endpoint Reference](#api-endpoint-reference)
+9. [Local Fleet Canary](./fleet-local-canary.md)
 
 ---
 
@@ -353,6 +354,37 @@ defined there.
 
 ---
 
+## Claude Code Skill Bridge
+
+The framework's canonical skill root is `~/.config/mosaic/skills/`; Claude Code
+requires registrations under `~/.claude/skills/`. The implementation in
+`packages/mosaic/src/commands/skill.ts` owns only direct-child symlinks whose
+resolved target remains inside the canonical root.
+
+Security invariants:
+
+1. Validate the user-supplied name before filesystem access against
+   `[A-Za-z0-9][A-Za-z0-9._-]*`. Separators, control characters, whitespace,
+   `..`, absolute paths, and leading `-` are invalid; filesystem-derived invalid
+   names are escaped before terminal output.
+2. Never replace a real file, directory, foreign symlink, or live misdirected
+   symlink in the Claude skill directory.
+3. Repair a dangling link only when its lexical target is inside the canonical
+   Mosaic skills root.
+4. Unregister only a symlink pointing inside that root.
+5. Enumerate canonical directories at runtime; never hardcode framework skill
+   names.
+
+`finalizeStage` reconciles after wizard/framework synchronization, and
+`runFrameworkReseed` reconciles after the sync-only `mosaic update` path. A
+foreign conflict is reported but does not prevent unrelated canonical skills
+from registering. Filesystem tests use injected temporary roots in
+`skill.spec.ts`, `finalize-skills.spec.ts`, and `update-checker.reseed.spec.ts`.
+
+M1 intentionally manages Claude Code only. Pi's Mosaic launcher can discover the
+canonical root directly. Codex still relies on the existing full skill-sync
+linker and needs separate parity analysis before this lifecycle API is extended.
+
 ## API Endpoint Reference
 
 All endpoints are served by the gateway at `http://localhost:14242` by default.

docs/guides/fleet-local-canary.md

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

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

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

docs/guides/user-guide.md

@@ -183,6 +183,8 @@ non-interactive use:
 --no-auto-launch    # Skip auto-launch of wizard after install
 ```
 
+Unrecognized flags or positional arguments fail before installation starts and print the supported-option usage.
+
 Or if installed globally:
 
 ```bash
@@ -307,6 +309,39 @@ mosaic quality-rails
 
 ---
 
+### Claude Code Skill Registration
+
+Mosaic stores canonical skills under `~/.config/mosaic/skills/`. Claude Code scans
+`~/.claude/skills/`, so Mosaic maintains one symlink per skill between those
+directories.
+
+```bash
+mosaic skill list
+mosaic skill register <name>
+mosaic skill unregister <name>
+```
+
+- `register` is idempotent and repairs a dangling Mosaic-owned link. Names use
+  the safe grammar `[A-Za-z0-9][A-Za-z0-9._-]*`; files, directories, foreign
+  symlinks, path traversal, absolute paths, and names beginning with `-` are
+  refused.
+- `unregister` is idempotent when no entry exists. It removes only symlinks that
+  point inside `~/.config/mosaic/skills/`; foreign entries are never removed.
+- `list` reports `registered`, `unregistered`, `dangling`, `foreign`,
+  `foreign-dangling`, or `misdirected` for each canonical or Claude entry.
+
+Install, wizard finalization, and `mosaic update` framework re-seeding reconcile
+every canonical skill automatically. A skill directory added after initial
+setup therefore receives its Claude bridge without a per-skill code change or
+manual `ln -s`. If Claude Code is already running, use `/reload-skills` or start
+a new session after registration so its in-process skill registry rescans.
+
+This command group is Claude-only in M1. Pi can consume Mosaic's canonical skill
+root through its Mosaic launcher configuration and does not need this Claude
+bridge. Codex has a separate link path managed by the legacy full skill-sync
+script; equivalent lifecycle management remains follow-up scope and is not
+changed here.
+
 ## Sub-package Commands
 
 Each Mosaic sub-package exposes its full API surface through the `mosaic` CLI.

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

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

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

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

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

@@ -0,0 +1,529 @@
+# Scratchpad — #791 Upgrade config protection (ms-791 worker lane)
+
+**Lane:** web1:ms-791 → reports to MS-LEAD (web1:mosaic-100). Do NOT contact Jason/Mos directly.
+**Worktree:** `/home/hermes/agent-work/stack-agents-dir-791`, branch `feat/791-upgrade-config-protection`
+off `origin/main` `9745bc3f` (verified exact head).
+
+## Mission prompt (verbatim intent)
+Protect operator-owned config under `~/.config/mosaic` from framework-upgrade wipes. Ratified
+combination (Mos-approved, do NOT re-litigate): (b) strict ownership separation [PRIMARY] + (a)
+transactional pre-update snapshot [safety net] + (d) regeneration-from-SSOT [recovery]. (c) periodic
+timer DEFERRED. HARD GATE: unit test that an upgrade run touches NO path outside the manifest.
+Design-first: write design doc, send to MS-LEAD, WAIT for confirmation before impl.
+
+## Session 1 (2026-07-16) — Phase 1 design
+
+### Evidence gathered (wipe mechanism, file/line)
+- `mosaic update` → `update-checker.ts:509` `buildReseedCommand` → `bash install.sh`
+  (`MOSAIC_SYNC_ONLY=1`, `MOSAIC_INSTALL_MODE=keep`).
+- Wipe = `packages/mosaic/framework/install.sh:199` `rsync -a --delete` + `PRESERVE_PATHS` denylist
+  (`install.sh:47`). cp-fallback `install.sh:223` `find ... -exec rm -rf`.
+- Denylist gaps → WIPED: `agents/*.conf`, `policy/*.md`, `*.local.md`, harvester/SOP,
+  `tools/_lib/credentials.json`.
+- Stale comment `update-checker.ts:492` claims `*.local` preserved — PRESERVE_PATHS has no such entry.
+- TS path `file-adapter.ts:157` → `file-ops.ts:66` `syncDirectory` = non-destructive copy-overlay, BUT
+  its preserve list (`file-adapter.ts:164`) already DRIFTED from install.sh (missing `fleet/backlog`,
+  `fleet/roles.local`). Evidence for single shared manifest SSOT.
+- Existing snapshot (`install.sh:76`) = /tmp, crash-trap only, deleted on success → inadequate; no
+  `mosaic restore`.
+- `fleet-reconciler.ts:93,234` already has `regenerate-projections-from-roster` phase separate from
+  lifecycle → `mosaic fleet regen` = thin projection-only wrapper (no restart), no FCM-M4/M5 preemption.
+
+### Design decisions
+- **(b)** Invert to allow-list: shared `framework/framework-manifest.json` (framework globs +
+  operatorReserved carve-outs); resolve per-path, deny-wins; **UNKNOWN ⇒ operator (fail-safe)**.
+  Mechanism: drop `--delete`; non-deleting bulk copy + explicit manifest-scoped prune pass (iterate
+  framework globs only → operator/unknown structurally unreachable). Pure prune-planner fn for tests.
+- **(a)** Snapshot to `~/.local/state/mosaic/backups/pre-update-<ts>/` 0700/0600, retention N=5,
+  post-sync verify+restore, `mosaic restore --list/--from`. No secret values in output.
+- **(d)** `mosaic fleet regen` projection-only, preview-first, never restart.
+- HARD GATE test includes a deliberately-unanticipated operator path to prove fail-safe default.
+- **PR split:** PR1 manifest+guard (root fix, ships alone) → PR2 snapshot/restore (secrev) → PR3
+  regen+docs. PR2/PR3 depend on PR1.
+
+### Status
+Design doc written: `docs/design/791-upgrade-config-protection.md`. Sent to MS-LEAD.
+
+## Session 1 (cont.) — MS-LEAD CONFIRMED → Phase 2 GO
+All 4 asks approved. Binding conditions:
+- TDD tests-first, red-first proof per PR; ≥85% new-code; co-located `*.spec.ts`; never `--no-verify`.
+- HARD GATE test (§2.4, unanticipated sentinel survives byte-identical + mtime unchanged) = MERGE-BLOCKING for PR1.
+- Manifest-completeness test (§6.2) required.
+- Bash+TS read ONE shared `framework-manifest.json`; parity test (§6.1) required (closes #631 drift class).
+- UNKNOWN⇒operator (rule 3) non-negotiable. Keep prune-planner PURE.
+- `fleet regen`: NEVER restart; dry-run default, `--write` to apply; "never issues restart" test mandatory.
+- Independent review every PR; PR2 dedicated secrev.
+- One PR at a time through DAG. Report PR1 exact head + red→green evidence for review commission.
+
+### Now: implementing PR1 (manifest + resolver + non-deleting sync + scoped prune + guard tests).
+
+## Session 2 (2026-07-16) — PR1 built, tests-first, red→green proven
+
+Deviation noted to MS-LEAD in PR: manifest is `framework-manifest.txt` (line-oriented), NOT `.json`.
+Rationale: keep the bash installer free of a python3/jq dependency. The "ONE shared file, parity-
+tested" requirement is honored — `manifest-parity.spec.ts` drives the bash resolver as a subprocess
+and asserts byte-identical ownership vs the TS resolver over 34 probe paths spanning every class.
+
+### PR1 artifacts
+- SSOT: `packages/mosaic/framework/framework-manifest.txt` ([framework]/[operator], deny-wins, fail-safe).
+- TS resolver: `src/framework/manifest.ts` (pure: parse/matchGlob/resolveOwnership/frameworkSubtreeRoots/
+  planPrune) + `manifest.spec.ts` (18 tests incl. planPrune property test + §6.2 completeness).
+- Bash resolver: `framework/tools/_lib/manifest.sh` (compiled globs → fork-free `manifest_is_framework`;
+  CLI `resolve|subtree-roots|classify`). Sourced by install.sh.
+- HARD GATE (§2.4): `framework/tools/quality/scripts/test-upgrade-manifest-guard.sh` — keep-mode reseed,
+  10 operator sentinels (incl. unanticipated `unknown-operator-dir/x`, `harvester/sop.md`,
+  `fleet/my-fleet.yaml`) survive byte-identical + mtime-unchanged; retired framework file pruned;
+  secret value absent from output. RED=31 fail (orig install.sh) → GREEN=48 pass (fixed).
+- install.sh: keep mode now manifest-driven (`sync_framework_keep`, no `--delete`); overwrite unchanged.
+  PRESERVE_PATHS denylist deleted.
+- TS sync: `file-ops.syncDirectory` gains `isOperatorOwned` guard; `file-adapter.syncFramework` derives
+  it from `loadManifest` — hardcoded (drifted) preservePaths deleted. Fixture uses the REAL manifest.
+- Parity: `manifest-parity.spec.ts` (§6.1) — bash↔TS agree on 34 paths + subtree roots.
+- Migration matrix `test-install-migration.sh`: F6 flipped — `my-fleet.yaml` now MUST survive (fail-safe).
+- CI: new merge-blocking `upgrade-guard` step (`.woodpecker/ci.yml`) runs both bash suites (adds rsync).
+- update-checker.ts reseed comment corrected to the manifest model.
+
+### Gates (all green)
+- `pnpm typecheck` ✓ · `pnpm lint` ✓ · `pnpm format:check` ✓
+- Full mosaic vitest: 1062 passed (cli-smoke needs `pnpm build` first — build-artifact dep, not this change).
+- HARD GATE 48/48 · migration 21/21 · parity 3/3 · manifest 18/18 · file-adapter 8/8.
+
+### PR opened + reported (2026-07-16)
+- **PR #802** http://git.mosaicstack.dev/mosaicstack/stack/pulls/802 — base `main`@`9745bc3f`,
+  head `34e55d4a` (commit `feat(mosaic): manifest-owned upgrade guard…`). 15 files, +1160/-142.
+- Reported PR head + red→green evidence to MS-LEAD (web1:mosaic-100); queued (lead busy).
+  Standing by for the independent-review commission at head `34e55d4a`.
+- **TWO items flagged to MS-LEAD for decision (awaiting reply):**
+  1. Deviation `.txt` vs `.json` — confirm accept (parity-tested) or convert to `.json`+jq.
+  2. `pr-create -i 791` appended `Fixes #791` → would auto-close the tracking issue on PR1 merge
+     while PR2/PR3 remain. Recommended edit to `Part of #791`; awaiting go-ahead to patch PR body.
+- DO NOT start PR2/PR3 until PR1 merges (DAG; one PR at a time).
+
+### MS-LEAD ruling → #797 ledger-survival sentinel folded into PR1 (2026-07-16)
+MS-LEAD ruled both my decisions: (1) `.txt` format ACCEPTED (parity must be strict/merge-blocking incl.
+format edge cases + negative probe); (2) trailer `Fixes #791`→`Part of #791` APPROVED (patched PR #802
+body via Gitea API — tracking issue no longer auto-closes on PR1 merge). Plus Mos-ELEVATED merge-blocker
+(spec `~/agent-work/planning/epic-796/791-ledger-survival-sentinel-SPEC.md`): #797 Runtime Session Ledger
+must survive upgrade. Two coupled deliverables landed in PR1:
+- (i) Carve-out: `fleet/run/**` was ALREADY an explicit `[operator]` entry — glob matches the spec's
+  pinned `fleet/run/**` EXACTLY, so NO divergence to route back to planner-opus. Strengthened its comment
+  to name the ledger (`fleet/run/sessions/` events.ndjson + ledger.json) so it is unmistakably load-bearing.
+- (ii) HARD-GATE sentinel: seeded populated ledger (events.ndjson 3 events + ledger.json node+edge+gen,
+  0600 under 0700) into test-upgrade-manifest-guard.sh sentinels; asserts byte-identical + mtime-unchanged
+  + dir-perms unchanged. Negative control (retired framework file IS pruned) relabeled explicitly.
+  HARD GATE now 58/58 (was 48).
+- Decision-1 parity hardening: format-edge fixtures (comments/blanks/whitespace, duplicate+overlapping
+  globs deny-wins, section/glob-ordering independence) + explicit UNKNOWN→operator negative probe, driven
+  through BOTH resolvers via MANIFEST_FILE override. Parity 7/7 (was 3).
+- RED-FIRST honesty note: the bash ledger sentinel stays GREEN even against the pre-fix installer (the
+  ledger was incidentally safe from the rsync --delete bug; overall pre-fix run 30/58 as expected). The
+  carve-out's TRUE load-bearing value (deny-wins if framework ownership ever broadens to `fleet/**`) is
+  isolated by a dedicated resolver-seam red→green in manifest.spec.ts: WITHOUT `fleet/run/**` operator
+  entry + hypothetical `fleet/**` framework → ledger resolves framework and planPrune DELETES it (RED);
+  WITH the carve-out → deny-wins → operator, unprunable (GREEN). manifest.spec.ts 21/21 (was 18).
+- Gates all green: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1069 passed · HARD GATE 58/58
+  · migration 21/21. Committing FORWARD on the branch (NOT rebasing 34e55d4a out from under review).
+
+### MS-LEAD REQUEST CHANGES @ 0a5e703a → B1/B2/B3 fixed red-first (2026-07-16)
+MS-LEAD returned REQUEST CHANGES (routed merge-blockers satisfied; 2 CRITICAL reliability defects from
+the commissioned independent review). Fixed forward on the branch, red-first:
+- **B1 (CRITICAL) — dead ERR trap.** install.sh had `set -euo pipefail` (no `-E`), so the
+  `trap restore_snapshot ERR` never fired for a failure inside sync_framework_keep() (function body) —
+  a mid-sync abort left a half-written target with NO rollback. Fix: `set -Eeuo pipefail` (errtrace) +
+  disarm the trap at the top of restore_snapshot() to prevent re-entrancy. New gate
+  `test-upgrade-rollback.sh`: injects a mid-sync `cp` EACCES (read-only divergent framework file);
+  Part A asserts the shipped installer rolls back (restore message fires AND target byte-identical to
+  pre-upgrade); Part B control strips `-E` and asserts the rollback message does NOT fire (dead trap) —
+  self-verifying red→green. 7/7.
+- **B2/B3 (CRITICAL) — empty/unreadable/malformed manifest divergence.** Pre-fix: TS `parseManifest('')`
+  returned `{framework:[],operator:[]}` (NO throw) → silent no-op "Installation complete"; bash aborted
+  fragilely (the `_manifest_compile` `"${MANIFEST_OPERATOR[@]:-}"` artifact returned 1 with no message)
+  AND the CLI dispatch swallowed manifest_load's rc (no `|| exit`) so `resolve` exited 0 resolving
+  everything operator. Fix (fail-loud + identical both langs):
+  * TS `parseManifest`: throw on zero framework entries; `loadManifest`: wrap read error →
+    "Cannot read framework manifest …".
+  * bash `manifest_load`: explicit unreadable guard (`[[ ! -r ]]`) + zero-`[framework]` guard, both loud
+    stderr + return 1; `_manifest_compile` gets explicit `return 0` (kills the empty-array artifact);
+    CLI dispatch `manifest_load … || exit 1`.
+  * `finalize.ts`: wrap syncFramework → `spin.stop('Framework sync aborted …')` + rethrow (never falls
+    through to "Installation complete").
+  Tests: manifest.spec.ts +5 fail-closed (empty/comment-only/operator-only/empty-section/missing);
+  manifest-parity.spec.ts +7 failure-mode parity (both reject empty/comment-only/operator-only/
+  empty-section/entry-before-header/unknown-header/missing — TS throws, bash CLI exits non-zero+stderr);
+  HARD GATE +4 end-to-end fail-closed matrices (empty/operator-only/malformed/missing → abort non-zero,
+  manifest error surfaced, every operator sentinel byte-identical). RED proven by reverting
+  manifest.ts+manifest.sh to HEAD → 12 new tests fail; restore → 40/40 green.
+- **Non-blocking addressed.** MEDIUM install.sh:222 find-empty now warns on a real failure instead of
+  blanket `|| true`. LOW: corrected the "both destructive paths rsync vs cp" overstatement in the HARD
+  GATE header + cp-fallback comment + ci.yml (keep mode is a single cp-based path; the rsync-present vs
+  -absent runs prove rsync-independence). `.pre-constitution.bak` triage: single-shot backup is
+  intentional (reconcile_framework_files backs up once), no change.
+- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1081 passed (was 1069, +12) · HARD GATE
+  118/118 (was 58) · rollback 7/7 (new) · migration 21/21. No --no-verify. Rollback test wired into
+  ci.yml upgrade-guard. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
+
+### Codex round 2 (pre-push self-review) → blockers A/B + should-fix C fixed red-first (2026-07-16)
+Before committing round 1 I re-ran codex on the change set; it surfaced two fresh reliability defects
+and one messaging defect on the SAME rollback/manifest path. Fixed forward, red-first:
+- **Blocker-A (CRITICAL) — signal trap resumed instead of terminating.** A bash INT/TERM handler that
+  merely `restore_snapshot` (returns) does NOT terminate the script — execution RESUMES past the
+  interrupt, cleans the snapshot and reports success, leaving a partial post-interrupt update. Fix:
+  `trap 'restore_snapshot; exit 1' ERR INT TERM` so both the errtrace (ERR) and signal (INT/TERM) paths
+  exit non-zero. Rollback test Part C: a `cp` shim that `kill -TERM $PPID` mid-sync then succeeds (so
+  set -e never fires and only the signal path governs) → asserts abort non-zero + restore fires + does
+  NOT print "file phase complete"; control strips `exit 1` and asserts the buggy resume-to-success.
+- **Blocker-B (CRITICAL) — degenerate `[framework]` section resolved everything operator.** A manifest
+  whose framework entries are all empty / bare-dot (`/`, `./`, `.`, `..`) passed the non-empty guard yet
+  yielded zero usable globs → nothing is framework → a keep-mode sync silently no-ops (bash resolved
+  `operator`, exit 0). Fix (both langs, parity): reject when no entry has a char other than `/`/`.` —
+  TS `isUsableFrameworkGlob` = `/[^/.]/.test(normalizeRel(glob))`, throws `ManifestError`; bash mirror
+  loops `[[ "$(_manifest_norm "$_g")" =~ [^/.] ]]`, loud stderr + return 1. Tests: manifest.spec.ts
+  `it.each(['/','./','.','..','/\n./'])` throw; parity +3 `expectBothReject` (root-slash/dot-slash/
+  bare-dot). RED: reverting the guard makes `[framework]\n/` resolve `operator` exit 0.
+- **Should-fix-C — misleading abort message.** finalize.ts printed one generic "may be partially
+  applied" for every sync failure. A `ManifestError` is a PRE-sync validation abort (manifest is
+  validated before any copy) → nothing was written; conflating it with a mid-copy failure misdirects
+  recovery. Fix: introduce `ManifestError` (exported from manifest.ts, thrown by every fail-closed
+  parse/load path), and classify in finalize.ts — ManifestError → "no files were changed"; any other →
+  "may be partially applied". New co-located `finalize-sync-abort.spec.ts` (3 tests) asserts both
+  branches re-throw the original error + the correct message, and that config writes are never reached.
+  RED proven by collapsing the classification → the ManifestError test fails.
+- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 (was 1081, +3 finalize-abort;
+  manifest specs already counted) · HARD GATE 193/193 · rollback 14/14 · migration 21/21.
+
+### Codex round 3 (pre-push self-review) → blockers D1/D2 fixed red-first (2026-07-16)
+Re-ran codex again; it found two more rollback-path gaps `set -E` cannot catch. Fixed forward, red-first:
+- **Blocker-D1 (CRITICAL) — `find` scan failures swallowed by process substitution.** Both the overlay
+  copy and the scoped prune consumed `< <(find … -print0)`. Bash does NOT propagate the producer's exit
+  status to the `while`, so an EACCES/I/O failure mid-scan truncates the file list yet leaves the loop
+  exiting 0 → a partial upgrade commits and reports success; the ERR/restore trap never fires. Fix:
+  `_scan_or_die` runs `find … -print0 > "$tmp"` to completion, checks its status, and returns non-zero
+  (→ ERR trap → restore) on failure; both loops now read from the checked temp file. Rollback test
+  Part D: a `find` shim that fails every `-print0` scan → shipped installer aborts non-zero + restores +
+  emits "Could not enumerate framework files" + target byte-identical; control neuters the `# D1-GUARD`
+  `return 1` → find failure swallowed, upgrade wrongly reports "file phase complete", no rollback.
+- **Blocker-D2 (CRITICAL) — silent `set -e` exit on a failed target reset.** restore_snapshot did a bare
+  `rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"` (trap disarmed, under set -e). If `rm`/`mkdir` fails —
+  possibly after `rm` deleted part of the target — the script exits immediately, skipping the cp AND the
+  recovery pointer, leaving a half-removed target and an orphaned snapshot the operator can't locate.
+  Fix: `if ! rm -rf … || ! mkdir -p …; then fail "Snapshot restore could not reset … preserved at:
+  $SNAPSHOT_DIR — copy it back …"; return 1; fi` (tested like the cp -a check; snapshot NOT deleted).
+  Rollback test Part E: cp-poison triggers restore + an `rm` shim fails `rm -rf <TARGET>` → shipped
+  emits the recovery pointer, the named snapshot dir survives, secret value never leaked; control deletes
+  the recovery line → operator gets no pointer. RED: reverting D1+D2 → 7 shipped/control assertions fail.
+- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 · HARD GATE 193/193 ·
+  rollback 28/28 (was 14, +14 for D1/D2 with controls) · migration 21/21. shellcheck clean on new lines.
+  No --no-verify. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
+
+## Session 3 (2026-07-16) — PR1 MERGED, starting PR2 (durable snapshot + restore + secrev)
+PR1 (#802) squash-merged → main `32a0ffba`; issue #791 stays open (3-PR DAG umbrella). Independent Opus
+adversarial/security review APPROVED at head `af627e75` (Gitea RoR cmt 17892); lead ran rollback 28/28 +
+HARD GATE 193/193 green; CI #1877 green. PR2 UNBLOCKED.
+
+PR2 branch: `feat/791-pr2-snapshot-restore` off `origin/main` 32a0ffba. Same treatment applies:
+tests-first red-first, independent review + durable Gitea Reviewer-of-Record comment BEFORE MS-LEAD runs
+the queue guard/merge. Report PR2 number + exact head when ready. PR body: `Part of #791` (NOT Fixes).
+
+### PR2 scope (ratified §3/§5 of design doc, Mos-approved — do NOT re-litigate)
+- **(a) Durable pre-update snapshot** to `${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-ts>/`
+  — OUTSIDE ~/.config/mosaic and any repo. Perms dir 0700 / files 0600 (umask 077 + explicit chmod).
+  Scope = operator-owned surface that EXISTS (operatorReserved paths), not the framework tree. Taken
+  BEFORE any mutation. Retention N=5 (`MOSAIC_BACKUP_RETENTION`), prune older.
+- **Post-sync verify + selective restore**: diff operator surface vs snapshot; (b) should never touch
+  operator paths, so ANY diff = manifest bug → restore affected paths + warn loudly. (a) catches a (b) miss.
+- **`mosaic restore`** (TS CLI): `--list` (default, dry-run) enumerates snapshots by ts; `--from <ts>`
+  restores over operator surface, confirmation-gated. Counts/paths only.
+- **Secret-safety (secrev)**: snapshot/restore NEVER emit file contents; only paths/counts. Tests assert
+  0700/0600 AND that a secret value seeded in tools/_lib/credentials.json never appears in any output.
+
+### PR2 implementation status (2026-07-16, ready-for-review)
+All three tasks implemented, red-first proven, unit-green:
+- **Task #10 — durable snapshot (install.sh)**: `backup_root()`/`enumerate_operator_files()`/
+  `prune_durable_snapshots()`/`make_durable_snapshot()` wired into keep-mode main() after `manifest_load`,
+  before any mutation. umask 077 + explicit chmod 700/600. UTC ts, collision suffix. FAIL-OPEN (a backup
+  failure never aborts the upgrade it protects). Retention `MOSAIC_BACKUP_RETENTION` (default 5), in-place
+  `sort -r -o` prune (no `mv` — stays inside the rsync-absent coreutils whitelist).
+- **Task #11 — post-sync verify net (install.sh)**: `verify_operator_surface()` runs after sync (trap
+  disarmed), `cmp -s` each snapshot file vs target; restores any diverged/missing operator file + warns
+  loudly (a divergence = manifest bug). VERIFY-NET wired before `cleanup_snapshot`.
+- **Task #12 — `mosaic restore` (TS)**: `src/commands/restore.ts` + co-located spec (19 tests).
+  `--list` default (dry-run enumerate), `--from <ts>` confirmation-gated restore, `--dry-run`, `--yes`/
+  `MOSAIC_ASSUME_YES`. Injectable `confirm` for testability (proceed/decline/env-bypass covered). Restored
+  files forced 0600. Registered in `cli.ts`. Path convention mirrors install.sh `backup_root()`.
+- **CI**: `.woodpecker/ci.yml` upgrade-guard runs the new `test-upgrade-durable-snapshot.sh` gate.
+- **Gates green**: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1241 (+5) ·
+  durable-snapshot 26/26 · manifest-guard 193/193 · rollback 28/28 · migration 21/21.
+  Est. new-code coverage ≈93% (only the interactive readline default + process.exit-on-error uncovered).
+- Regression fixed: PR2's `date`/`sort`/`mv` broke the rsync-absent manifest-guard PATH whitelist →
+  made date/sort fail-open, replaced `mv` with in-place `sort -o`, added `date sort` to the test whitelist
+  + isolated `XDG_STATE_HOME`. All 193 manifest-guard assertions green under restricted PATH.
+- Codex code-review + security-review (secrev) run on the uncommitted diff before commit.
+
+### PR2 review round 1 — findings + remediations (2026-07-16, pre-PR)
+Codex code-review returned **request-changes** (1 blocker + 3 should-fix); Codex security-review returned
+**high** (1 high + 1 medium). Deduped to 5 distinct defects, ALL legitimate, ALL fixed FORWARD, each with
+a red-first regression test whose control neuters exactly the guard under test:
+
+- **A · BLOCKER — verify net undid the legacy bin/ migration (install.sh).** On a pre-v2 install `bin/**`
+  is operator-classified, so the durable snapshot captured it; `run_migrations()` deletes bin/ on purpose,
+  but `verify_operator_surface()` then saw it "missing" and healed it back — the migration would be silently
+  undone forever once the version stamps. **Fix:** `MIGRATION_REMOVED_PATHS[]` recorded by run_migrations
+  (`bin`,`rails`) + `is_migration_removed()` skip in the verify loop (`# MIGRATION-SKIP-GUARD`).
+  **Test:** Part 6 — v1 fixture with bin/; shipped keeps it removed + stamps v3; control (guard stripped)
+  wrongly restores bin/tool.sh.
+- **B · HIGH (CWE-59) — restore/verify wrote secrets THROUGH a symlink (install.sh + restore.ts).** An
+  attacker swapping an operator path (e.g. tools/_lib/credentials.json) for a symlink after the snapshot
+  would make `cp`/`copyFileSync` write the snapshot's secret out through the link. **Fix (bash):** refuse a
+  symlinked ancestor (`has_symlinked_parent`), drop a symlinked leaf before restore
+  (`# SYMLINK-LEAF-GUARD`). **Fix (TS):** reuse audited `secure-file.ts` — `assertCanonicalContainment`
+  + `ensureManagedDirectory` on every dst, open the leaf `O_NOFOLLOW|O_CREAT|O_TRUNC` 0600 (ELOOP =
+  fail-closed). **Tests:** Part 7 (shipped leaves external exfil target untouched, restores a real 0600
+  file; control leaks the secret through the link) + restore.spec symlinked-leaf/ancestor cases (red-first).
+- **C · MEDIUM/should-fix (CWE-22) — `--from` traversal escaped the backup root (restore.ts).**
+  `join(root, from)` accepted `../poison`. **Fix:** validate the selector against
+  `^\d{8}T\d{6}Z(?:-\d+)?$`, build exactly `join(root,'pre-update-'+ts)`, `lstat` (reject symlinked snap
+  dir). **Test:** restore.spec `it.each` of 6 malformed selectors + `--from ../poison` fail-closed (red-first).
+- **D · should-fix — verify `mkdir -p` unguarded under set -e (install.sh).** A parent replaced by a
+  regular file aborted the installer before the recovery pointer printed. **Fix:** guard `mkdir -p`, warn
+  + `continue` on failure (keeps healing remaining files).
+- **E · should-fix — snapshot `umask 077` leaked process-global (install.sh).** Later sync copies/dirs
+  inherited 0600/0700. **Fix:** save `old_umask`, restore on EVERY return path (`# UMASK-RESTORE-NORMAL`).
+  **Test:** Part 8 — synced framework file is 0644 while the secret backup stays 0600; control (restore
+  stripped) makes the synced file 0600.
+
+**Full gate suite re-run after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic
+vitest **1252** · restore.spec **30** · durable-snapshot **41** · manifest-guard 193 · rollback 28 ·
+migration 21. shellcheck clean on all new lines; new test markers mirror the existing `# VERIFY-NET`
+anchor convention. NOTE: codex self-review does NOT satisfy the independent-review gate — an independent
+(author≠reviewer) review + durable Gitea Reviewer-of-Record comment is still required before MS-LEAD merges.
+
+## Session 4 (2026-07-16) — PR2 MERGED, PR3 built (fleet regen — recovery layer)
+PR2 (#811) squash-merged → main `31607a4a`; issue #791 stays open (final PR of the 3-PR DAG). Independent
+exact-head RoR at `d12c5f78` APPROVE (Gitea cmt 17904); #1882 green; busybox-portable Part 7 control fix
+verified in-Alpine. PR3 UNBLOCKED.
+
+PR3 branch: `feat/791-pr3-fleet-regen` off `origin/main` 31607a4. Same discipline: tests-first red-first,
+independent review + durable Gitea RoR BEFORE MS-LEAD runs the queue guard/merge. PR body `Part of #791`.
+
+### PR3 scope (ratified §4/§7 of design doc) — `mosaic fleet regen`
+Projection-only recovery command: rebuilds each `fleet/agents/<name>.env.generated` from `roster.yaml`
+(SSOT). Dry-run default; `--write` applies; `--json` machine output. Structural guarantee: NO code path to
+systemd lifecycle — **never restarts an agent**. Single-SSOT: reuses `projectRosterV2AgentGeneratedEnv`
+(extracted, shared with the reconciler apply path) so regen and reconcile cannot drift. Secrev: paths +
+counts only, never the rendered KEY=value body.
+
+New files: `commands/fleet-regen-command.ts` (+ `.spec.ts`), guide `docs/guides/upgrade-safety-and-recovery.md`
+(three-layer model: PR1 manifest ownership → PR2 snapshot/restore → PR3 regen; do-NOT-restart-before-verify
+runbook), regen reference added to `docs/guides/fleet-local-canary.md`. Wired in `commands/fleet.ts`.
+
+### Independent review (3 reviewers: subagent code-reviewer + codex code-review + codex security) → 4 fixes, red-first
+- **A · BLOCKER (codex) — regen mutated/deleted legacy operator env.** `applyPreparedAgentEnvironmentProjection`
+  also writes `.env.local`/`.env.quarantine` and unlinks legacy `.env`. Violated projection-only contract.
+  **Fix:** NEW generated-only boundary primitives `prepareGeneratedAgentEnvironmentProjection` +
+  `applyPreparedGeneratedAgentEnvironmentProjection` (write ONLY `<name>.env.generated`). regen now has no
+  code path that touches `.env`/`.env.local`/`.env.quarantine`. **Test:** projection-only leaves legacy `.env`
+  verbatim, no local/quarantine fabricated.
+- **B · should-fix (codex + subagent + security) — partial write on mid-loop failure.** Interleaved
+  prepare/apply left earlier agents written when a later agent failed prepare. **Fix:** PREPARE ALL agents
+  before writing ANY (mirrors reconciler `defaultPrepareProjections`). **Test:** 2nd agent's projection
+  pre-seeded 0644 → prepare rejects → coder0 NOT written, exit 1.
+- **C · subagent — semantic-validation bypass.** Default readRoster skipped `validateRosterV2Semantics`, so
+  a tampered protected-class `tool_policy` would be silently projected. **Fix:** default readRoster now runs
+  `validateRosterV2Semantics` (persona resolution + protected-class match), rolesDir/overrideDir defaults
+  mirroring the reconciler. **Test:** merge-gate agent w/ tool_policy=code → fails closed, no write.
+- **D · MEDIUM (codex security, CWE-362) — concurrent-reconcile race.** regen `--write` wrote without the
+  reconcile lock. **Fix:** `--write` acquires `acquirePrivateReconcileLock(mosaicHome)` for the whole
+  read-prepare-apply sequence, released in `finally`; dry-run stays lock-free. **Test:** pre-held lock →
+  regen fails closed, no write.
+
+**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1265**
+(regen spec 13, incl. 4 new red-first regressions). NOTE: codex self-review does NOT satisfy the
+independent-review gate — an independent (author≠reviewer) review + durable Gitea RoR is still required
+before MS-LEAD merges. STOP at PR-open for MS-LEAD's exact-head review; do NOT self-merge.
+
+## Session 5 — PR3 review round 2 (finding L + M1/M2/M3), red-first fixes
+
+Second review pass on the lock-cleanup plumbing surfaced one round-1 residual (L) and three round-2
+findings (M1 blocker, M2/M3 should-fix). All fixed red-first (RED proven per-finding, then GREEN).
+
+- **L · should-fix (codex r1) — mutation-lock release swallowed unlink failures.** regen's
+  `acquirePrivateRosterMutationLock` release copied CRUD's `unlink().catch(()=>{})`, hiding a stale
+  `roster.yaml.mutation.lock`. **Fix:** its release PROPAGATES the unlink fault (finding-J stale-lock
+  warning then fires for this lock too). **Test:** acquire real lock, `rm` it, assert `release()` rejects.
+- **M1 · BLOCKER (codex r2) — replacement-lock race.** The propagating release from L did an
+  UNCONDITIONAL `unlink(lockPath)` without proving ownership. If the lock is cleared + re-created by
+  another writer mid-op, regen deletes the STRANGER's live lock → a third writer enters → mutual
+  exclusion defeated. **Fix (reuse, not reimplement):** generalized the reconciler's ownership-proving
+  lock body into shared `acquirePrivateManagedRosterLock(mosaicHome, lockLeaf, busyMessage, openLock)`;
+  `acquirePrivateReconcileLock` delegates to it (behavior-identical: same leaf/codes/messages), and a NEW
+  hardened `acquirePrivateRosterMutationLock` (now in fleet-reconciler.ts, leaf `roster.yaml.mutation.lock`)
+  records dev/ino + ownership token and RE-PROVES ownership (`assertLockOwnership`) before unlinking —
+  fails closed as `lock-cleanup-failed` if replaced. Removed the crud-based export; reverted
+  `acquireMutationLock` (fleet-agent-crud.ts) to its original inline empty-file/swallowing-release form
+  (CRUD behavior intentionally unchanged). Compatibility: CRUD empty-file `wx` and regen tokened `wx`
+  contend on the same path but never co-own (wx winner owns; loser → concurrent-mutation), so the token
+  is only ever read back by the same regen invocation. **Test:** acquire, `rm`+recreate lock (new inode),
+  assert `release()` rejects AND the replacement survives (not unlinked).
+- **M2 · should-fix (codex r2) — acquire-unwind fault dropped.** The acquire-failure catch discarded
+  `releaseFleetLocks`' return (a possible fault on the already-held first lock). **Fix:** capture and
+  augment — `const releaseFault = await releaseFleetLocks(releases); throw augmentWithLockCleanupFault(error, releaseFault);`
+  (symmetric to finding J). **Test:** mutation lock acquires w/ faulting release + reconcile acquire
+  throws → thrown error mentions stale/lock, nothing written.
+- **M3 · should-fix (codex r2 + subagent REQUEST-CHANGES) — cleanup warning named only reconcile lock.**
+  Finding L made the mutation-lock release fault reachable, so the `cleanup` marker can originate from
+  EITHER lock. **Fix:** `formatFleetRegenReport`'s WARNING now names BOTH `roster.yaml.mutation.lock` and
+  `roster.yaml.reconcile.lock`, matching `augmentWithLockCleanupFault`. **Test:** fault the mutation-lock
+  release specifically → report names both lock files.
+
+**Refactor note (no cycle):** neither fleet-reconciler nor fleet-agent-crud imports the other; regen
+imports lock acquirers from fleet-reconciler and the projection mapping from fleet-reconciler. The two
+reconcile-lock reviewers reconciled: independent reviewer validated acquire-time empty-file compatibility
+(preserved), codex flagged RELEASE-time replacement race (closed by ownership proof) — non-contradictory.
+
+**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1275**
+(regen spec 23, incl. 7 red-first lock regressions E/F/G/K/L/M1/M2/M3). RED proven per-finding by
+temporary revert before re-applying each fix. Independent (author≠reviewer) review of M1/M2/M3 + codex
+code/security re-run in flight. STOP at PR-open for MS-LEAD's exact-head review + durable Gitea RoR; do
+NOT self-merge; #791 umbrella stays OPEN; PR body `Part of #791`.
+
+### Round 3 review (after M1/M2/M3) — independent review PASS + codex residual-TOCTOU disposition
+Three reviewers on the post-M1/M2/M3 head:
+- **Independent (subagent, author≠reviewer) — PASS.** Verified M1/M2/M3 all correctly fixed; "never
+  restarts" is STRUCTURAL (runner never referenced in executable code); no secrets; no deadlock (only
+  regen holds both locks); tests meaningful (assert inode preservation + exact lock-file names). Raised:
+  - **should-fix #1 (fixed, red-first):** generalizing the lock helper left `assertSafeLockLeafIfPresent`/
+    `assertLockOwnership` hardcoding "reconciliation lock" in thrown messages → a MUTATION-lock fault
+    misreported as the reconcile lock, undercutting M3's accurate-diagnosis goal. **Fix:** thread
+    `lockLabel = fleet/<leaf>` through both helpers + the generic lock-io messages, so every fault names
+    the actual lock file. Red-first: strengthened the M1 test to assert `/roster\.yaml\.mutation\.lock/`
+    (RED: got "reconciliation lock"; GREEN after). Also resolves nit #3 (generic-message drift).
+  - **nit #2 (fixed):** `FleetRegenResult.cleanup` JSDoc still said "the shared reconcile lock"; now names
+    both locks (regen holds both).
+  - **nit #4 (fixed):** removed the redundant duplicate `assertLockOwnership` call before unlink
+    (pre-existing in merged main; harmless but dead — dropped since the fn was already being touched).
+- **Codex security — clean (risk: none).** Validates roster semantics, constrains env values, no shell
+  eval, no secret output, generated-only writes, serialized against both locks.
+- **Codex code — request-changes, 1 "blocker": residual check-then-unlink TOCTOU.** Between the final
+  `assertLockOwnership` and the path-based `unlink`, an external actor could vacate our inode and a new
+  writer grab the path, so the unlink deletes the stranger's lock. **Disposition: documented known
+  limitation, NOT fixed in PR3.** Rationale: (1) byte-identical to the MERGED, shipped reconcile-lock
+  release on origin/main (fleet-reconciler.ts L654-659) — not introduced here; (2) UNREACHABLE within the
+  `wx` writer protocol — no Mosaic writer removes a lock it doesn't own (wx fails EEXIST while our inode
+  exists), so only external interference can vacate our inode in the sub-instruction window; (3) the
+  ownership guard DOES close the reachable case (stale-lock reaper/operator cleared our lock + another
+  writer took it BEFORE release began → fail closed, don't delete stranger's lock); (4) the true atomic
+  fix — fd-held advisory lock (flock/lockf) adopted by ALL fleet writers (CRUD + reconcile + regen) — is
+  a cross-cutting mechanism change touching merged CRUD + reconciler, out of scope for a projection-only
+  recovery PR. Documented honestly in the acquirer doc + M1 test comment. **The binding independent
+  review did NOT treat this as a blocker.** Recommendation to MS-LEAD: proceed to PR-open + spin a
+  SEPARATE follow-up issue for the fd-advisory-lock migration; MS-LEAD adjudicates scope at exact-head
+  review (merge authority).
+
+**Gates after round-3 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
+**1275** (regen spec 23). Fresh codex code re-run in flight to confirm no NEW issues from the label fix.
+
+---
+
+## Session 6 — Round 4/5 convergence (stranded-lock robustness)
+
+**Two independent reviewers converged on the SAME should-fix** on the init-failure cleanup path,
+strengthening confidence it was real:
+
+- **Codex code-review-5 — 0 blockers, 1 should-fix.** "Stat failure after lock creation strands the new
+  lock." When `handle.stat()` ITSELF fails right after the `wx` create (transient EIO/EBADF), `created`
+  is `undefined`, so `removeOwnedLockLeafBestEffort` had `if (!created) return;` → no cleanup → the
+  just-created `roster.yaml.mutation.lock`/`reconcile.lock` is stranded, permanently blocking future
+  regen + CRUD. (Notably NO blocker, and the TOCTOU is no longer flagged in code-review as of r5.)
+- **Independent delta reviewer (author≠reviewer, pr-review-toolkit) — no blockers, same should-fix.**
+  Independently flagged the identical `!created` gap; validated FIX 1 (label threading — no call site
+  missed, codes unchanged, no test depended on old text) and FIX 2 (dev/ino-guarded cleanup, best-effort,
+  happy-path release reuses captured dev/ino) as correct. Suggested an unconditional best-effort unlink
+  in the `!created` branch; I took the **safer** variant below.
+- **Codex security-review-5 — 0 crit / 0 high / 1 medium.** The single medium is the SAME residual
+  check-then-unlink TOCTOU already dispositioned in round 3 (its own remediation = "migrate every writer
+  to an fd-held advisory lock" = the follow-up issue). No new security finding. No secrets.
+
+**Fix (red-first, safer than an unconditional unlink):** thread the persisted random `token` into
+`removeOwnedLockLeafBestEffort`. Two independent ownership proofs now: primary dev/ino (unchanged), and a
+**fallback** when the post-create stat failed — read the leaf and unlink ONLY if its content equals our
+`randomUUID()` token. Only OUR lock carries that token, so a CRUD (empty) or differently-tokened
+replacement is never deleted. `tokenPersisted` guards passing the token (only after `writeFile` lands).
+Doubly-degenerate case (stat fails AND token write never landed) leaves the lock in place rather than
+risk deleting a stranger's file — requires two independent fs faults on a just-created fd; documented.
+
+- **Red-first proof:** new test `does not strand the lock file when the post-create stat itself fails`
+  injects a real `wx` create + a Proxy handle whose `stat()` rejects (writeFile/close succeed), asserts
+  `exists(lockPath) === false`. RED before fix (`expected true to be false` — lock stranded); GREEN after.
+- **Also fixed (delta nit #3):** `fleet-regen-command.ts` `acquireRosterMutationLock` JSDoc said "CRUD's
+  private lock"; the default is the reconciler's hardened ownership-proving acquirer for the same
+  `fleet/roster.yaml.mutation.lock` path. Corrected.
+- **PR-description note (delta nit #2):** FIX 1 also collapsed a pre-existing duplicate back-to-back
+  `assertLockOwnership` call in the release closure (identical args, no intervening logic) into one — a
+  no-op simplification of merged code, not a behavior change. Called out so a future reader doesn't
+  wonder if the duplicate had a purpose.
+
+**Gates after round-4 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
+**1277** (regen spec now 25: +1 stat-failure stranded-lock regression). Residual TOCTOU still deferred to
+the fd-advisory-lock follow-up issue; MS-LEAD adjudicates scope at exact-head review (merge authority).
+
+---
+
+## Session 6 — Round 6 (persona-root wiring)
+
+**Codex code-review-6 — 0 blockers, 1 should-fix (NEW, distinct from the lock work).** "Forward
+configured persona directories to regen." `registerFleetRegenCommand` was registered at
+`fleet.ts:2069` with only `{ runner, mosaicHome }`, discarding `deps.reconcileDeps.rolesDir` /
+`overrideDir`. The regen command ALREADY has those seams (validates roster semantics via
+`validateRosterV2Semantics({ rolesDir, overrideDir })`, defaulting to `<mosaicHome>/fleet/roles{,.local}`),
+but the top-level wiring never forwarded the configured roots. **Impact:** in a deployment with custom
+persona roots, `fleet reconcile` (which honors the overrides) would ACCEPT a roster while `fleet regen`
+REJECTS the same roster (persona resolution against the wrong default dir) — blocking the recovery
+command and violating the documented "resolves personas the SAME way reconcile does" contract.
+
+**Fix (red-first):** forward `rolesDir`/`overrideDir` from `deps.reconcileDeps` into
+`registerFleetRegenCommand` at `fleet.ts:2069`. Red-first test `forwards configured persona roots
+(rolesDir/overrideDir) from reconcileDeps into regen`: seeds personas ONLY under a custom root, leaves
+the default `<home>/fleet/roles` empty, registers with `reconcileDeps: { rolesDir, overrideDir }`, and
+requires `fleet regen` to SUCCEED. RED before fix (`expected 1 not to be 1` — regen validated against the
+empty default and exited 1); GREEN after.
+
+**Codex security-review-6 — 0 crit / 0 high / 1 medium.** Same residual check-then-unlink TOCTOU, now
+noted at BOTH the release closure and the init-cleanup path; remediation = fd-held advisory lock across
+all writers = the SAME deferred follow-up item. No new security finding, no secrets.
+
+**Independent confirmation review of the token-fallback fix (Session 6/round 4) — PASS, no findings.**
+All 7 verification points confirmed; reviewer mechanically reverted `removeOwnedLockLeafBestEffort` to
+the pre-fix `if (!created) return;` and re-ran the new test → RED (`expected true to be false`),
+confirming the test genuinely pins the fix; restored after. No lint/type issues; doc-comment accurate.
+
+**Gates after round-6 fix (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
+**1278** (regen spec now 26: +1 persona-root wiring regression).
+
+---
+
+## Session 6 — Round 7 convergence (review CLOSED for PR-open)
+
+- **Codex code-review-7 — 0 blockers, 1 should-fix = the residual TOCTOU** (previously a "blocker" in r3,
+  dropped in r4/r5, now re-surfaced as a should-fix). **Codex security-review-7 — 0 crit / 0 high /
+  1 medium = the SAME residual TOCTOU.** Codex has CONVERGED: the only remaining finding across both
+  streams is that one race, whose own remediation is "fd-held advisory lock shared by all fleet writers"
+  = the deferred follow-up. No new distinct finding; the wiring fix introduced nothing.
+- **Independent confirmation review of the persona-root wiring fix — PASS, no findings.** Reviewer
+  mechanically reverted the two forwarded lines → RED (`Roster v2 agent "coder0" class "code" does not
+  resolve to a readable persona` → exit 1), restored → GREEN (26 regen + 204 fleet tests). Confirmed the
+  optional-chaining fallback preserves default-deployment behavior and no type/lint issue.
+
+**Review disposition for PR-open:** ALL actionable findings fixed red-first across rounds 3–6 (label
+threading, stranded-lock on init failure, stat-failure strand, persona-root wiring). The residual
+check-then-unlink TOCTOU is the ONLY open item and is DEFERRED to a follow-up issue (fd-advisory-lock
+migration across CRUD + reconcile + regen) — byte-identical to merged origin/main's reconcile-lock
+release, unreachable within the `wx` writer protocol (no Mosaic writer removes a lock it doesn't own;
+only external `rm`/a stale-lock reaper can vacate the inode mid-release), and its true fix is a
+cross-cutting mechanism change out of scope for a projection-only recovery PR. Two independent human-agent
+reviews (author≠reviewer) treated it as non-blocking. MS-LEAD adjudicates scope at exact-head review
+(merge authority); recommendation = proceed to PR-open + spin the follow-up issue.
+
+**Final gates (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1278**
+(regen spec 26). No secret values in any snapshot/projection/report output (counts + paths only). Regen
+NEVER issues a lifecycle/restart call (load-bearing recordingRunner gate). STOP at PR-open for MS-LEAD's
+exact-head review + durable Reviewer-of-Record before any merge; do NOT self-merge.

docs/scratchpads/804-install-unknown-flags.md

@@ -0,0 +1,86 @@
+# Issue #804 — fail closed on unknown installer arguments
+
+## Objective
+
+Implement Part 1 of Gitea issue #804 only: `tools/install.sh` must reject every unrecognized flag or argument with an actionable STDERR error and nonzero exit before installation starts.
+
+## Scope and constraints
+
+- Preserve all currently recognized options and behavior, including `-y` and `--ref <branch>`.
+- No positional arguments are currently accepted by the parser.
+- Do not add `--next`, `MOSAIC_NEXT`, prerelease routing, or any Part 2 behavior.
+- TDD is mandatory: add and observe a failing process-level regression test before changing `tools/install.sh`.
+- Worker lifecycle ends after branch push, PR creation, and coordinator notification; do not merge or close #804.
+- Existing launcher-owned changes in `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are out of scope and must not be committed.
+
+## Requirements and acceptance criteria
+
+- Unknown input names the offending argument on STDERR.
+- STDERR includes a short installer usage hint.
+- Exit status is nonzero.
+- The installer does not invoke npm or otherwise proceed into installation.
+- Existing recognized flags remain unchanged.
+
+## Plan
+
+1. Add a process-level Vitest regression using the installer test location under `packages/mosaic/src/commands/`.
+2. Run the focused test and record the expected RED failure.
+3. Commit the RED test as `test(#804): ...`.
+4. Replace the parser catch-all with a fail-closed STDERR error and usage hint.
+5. Update concise installer-facing documentation without introducing prerelease behavior.
+6. Run focused tests, shell syntax validation, package tests, lint, typecheck, and format checks.
+7. Run independent review tooling and remediate findings.
+8. Commit as `fix(#804): ...`, queue-guard, push, open a PR containing `Closes #804.`, notify the coordinator, and exit.
+
+## Budget
+
+- No explicit token cap supplied.
+- Working estimate: 8K tokens; narrow two-file behavior/test change plus concise docs and delivery gates.
+
+## Progress
+
+- 2026-07-17: Loaded mission state, issue #804, delivery/QA/documentation rails, and relevant TDD/Vitest/pnpm/Gitea skills.
+- 2026-07-17: Confirmed the parser has no legitimate positional arguments and currently drops all unmatched input via `*) shift ;;`.
+- 2026-07-17: Installed locked workspace dependencies with a worktree-local pnpm store; no lockfile changes.
+- 2026-07-17: Added the process-level unknown-argument regression with an isolated `$HOME` and npm shim.
+- 2026-07-17: Replaced the silent catch-all with STDERR error + usage output and exit 2 before preflight or installation.
+- 2026-07-17: Initial Codex code review found an unknown option could still be consumed as the `--ref` value. Added a second RED reproducer, then rejected option-shaped/missing `--ref` values without changing valid `--ref <branch>` behavior. The review's launcher-state note is handled by excluding both `.mosaic/orchestrator/` files from commits.
+- 2026-07-17: Updated README, user guide, and packaged framework README with the fail-closed argument contract. No API, auth, admin, sitemap/navigation, or publishing surface changed.
+
+## Verification
+
+- RED: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts` — expected failure: installer exited `0` instead of nonzero at the exit-status assertion; confirms the test reproduces the silent-drop defect before production changes.
+- Remediation RED: the added `--cli --ref --bogus` case exited `0`, proving `--ref` could swallow an unknown option before the guard was added.
+- GREEN: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts src/commands/install-heading.spec.ts` — 2 files, 3 tests passed.
+- Situational process check: unknown positional input exited 2, named the input on STDERR, printed usage, and did not call the npm shim.
+- `bash -n tools/install.sh` — passed.
+- Bare `--ref` process check — exited 2 with `Missing value for --ref` and usage.
+- `pnpm --filter @mosaicstack/mosaic test` — 69 files, 1,287 tests passed; framework shell checks passed. The first attempt lacked generated `dist/cli.js`; `pnpm --filter @mosaicstack/mosaic build` restored the required test precondition and the full rerun passed.
+- `pnpm lint` — 23/23 tasks passed.
+- `pnpm typecheck` — 42/42 tasks passed.
+- `pnpm format:check` — passed.
+- Codex code re-review against `origin/main` — `approve`, 0 blockers/should-fix/suggestions.
+- Codex security re-review against `origin/main` — risk `none`, 0 findings.
+
+## Acceptance evidence
+
+| Criterion | Evidence |
+| --- | --- |
+| Unknown input is named on STDERR | Process-level Vitest assertions for `--bogus`, including after `--ref` |
+| Short usage hint is printed on STDERR | Vitest usage regex + manual process output |
+| Exit is nonzero | Vitest status assertions and manual exit 2 |
+| Installation does not proceed | Isolated npm shim marker remains absent |
+| Recognized behavior is preserved | Parser cases are unchanged except validation of malformed `--ref`; full Mosaic package suite passed |
+| Part 2 is excluded | No `--next`, `MOSAIC_NEXT`, dist-tag, or prerelease routing changes |
+
+## Documentation checklist
+
+- Current canonical `docs/PRD.md` remains unchanged; issue #804 and the coordinator brief supply this bounded defect's acceptance contract.
+- Updated installer behavior in root README, user guide, and packaged framework README in the same logical change set.
+- API/OpenAPI, auth/permissions, admin operations, developer architecture, sitemap/navigation, and external publishing are not affected.
+- Scratchpad remains under `docs/scratchpads/`; no root-hygiene changes.
+
+## Risks and blockers
+
+- Part 2 remains owner-gated under #805 and is intentionally excluded.
+- No implementation blocker remains. Independent coordinator RoR, CI, merge, and issue closure remain pending after worker handoff.

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

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

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

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

docs/scratchpads/824-mosaic-skill-cli.md

@@ -0,0 +1,112 @@
+# Issue #824 — Mosaic skill CLI and Claude bridge auto-sync
+
+## Objective
+
+Deliver `mosaic skill register|unregister|list` plus install/upgrade reconciliation of every canonical `~/.config/mosaic/skills/*` entry into `~/.claude/skills/`, without clobbering runtime-owned files or directories.
+
+## Scope and constraints
+
+- Issue: mosaicstack/stack#824
+- Branch: `feat/824-mosaic-skill-cli`
+- M1 runtime: Claude Code only.
+- Pi/Codex parity is documentation-only; no non-Claude bridge implementation.
+- Do not author the downstream `mosaic-context-refresh` skill.
+- Workers do not modify `docs/TASKS.md`, merge, close #824, or touch `main`.
+- TDD is mandatory and red-first; filesystem tests use temporary directories only.
+- Budget: no explicit token cap supplied; use a focused single-worker implementation with no new dependencies.
+
+## Requirements mapping
+
+1. Register creates the canonical Claude symlink and is idempotent.
+2. Names are untrusted: reject empty/escaping/absolute/separator/`..`/leading-dash names before filesystem mutation, with clear CLI stderr and nonzero status.
+3. Register repairs only Mosaic-owned dangling symlinks and refuses foreign files, directories, and symlinks.
+4. Unregister removes only symlinks pointing inside the canonical Mosaic skills root and is idempotent when absent.
+5. List reports registered, dangling, foreign, and canonical-but-unregistered skills.
+6. Install and upgrade generically reconcile all canonical skills after framework sync/re-seed, continuing past foreign conflicts without clobbering them.
+7. User/developer documentation describes commands, status meanings, security boundaries, and Claude-only M1 scope.
+
+## Plan
+
+1. Add co-located failing Vitest coverage for all filesystem behaviors and auto-sync.
+2. Run the focused spec and record the expected RED failure.
+3. Commit the red contract as `test(#824): ...`.
+4. Implement the skill bridge and Commander command registration.
+5. Wire reconciliation into wizard finalize and `mosaic update` re-seed, preserving non-clobber behavior.
+6. Update canonical docs and sitemap if navigation changes.
+7. Run focused tests, package tests, typecheck, lint, and formatting.
+8. Commit implementation/docs as `feat(#824): ...`, queue-guard, push, open PR with `Closes #824.`, fire completion event, and notify the coordinator.
+
+## Progress
+
+- 2026-07-17: Loaded mission/delivery/TDD/documentation rails, issue #824, active mission state, and relevant installer/update paths.
+- 2026-07-17: Confirmed `mosaic update` invokes `framework/install.sh` with `MOSAIC_SYNC_ONLY=1`; that path exits before existing post-install skill linking, leaving newly present canonical skills unregistered.
+- 2026-07-17: Coordinator addendum classified the user-supplied skill name and runtime symlink target as a path-traversal/symlink-injection surface. Expanded the initial red contract to reject traversal before mutation, preserve every foreign entry, and unregister Mosaic-owned links only.
+- 2026-07-17: Implemented the Commander command group and secure generic bridge; wired wizard finalize and successful framework re-seed reconciliation; updated user/developer/installed/root docs and sitemap.
+- 2026-07-17: Focused, package-wide, repository baseline, temp-home situational, and independent review gates completed. Ready for scoped feature commit, queue guard, push, and PR handoff.
+
+## Tests and evidence
+
+### TDD evidence
+
+- RED environment attempt: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/skill.spec.ts` initially could not locate Vitest because this fresh worktree had no dependencies.
+- Dependency setup: `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` succeeded. The explicit store was required because machine pnpm config incorrectly resolves the default store under `/root`.
+- RED behavior: focused Vitest failed with `Failed to load url ./skill.js ... Does the file exist?`, proving the bridge API was absent.
+- RED integration: finalize/update specs failed because no Claude links or `skillSync` result existed.
+- RED symlink injection: symlinked Claude/canonical root tests failed because the initial implementation followed ancestor links.
+- GREEN after review remediation: `skill.spec.ts` 36/36, `finalize-skills.spec.ts` 6/6, and `update-checker.reseed.spec.ts` 30/30.
+
+### Baseline gates
+
+- `pnpm --filter '@mosaicstack/mosaic...' run build` — pass (fresh-worktree dependency outputs built).
+- `pnpm --filter @mosaicstack/mosaic run typecheck` — pass.
+- `pnpm --filter @mosaicstack/mosaic run lint` — pass.
+- `pnpm --filter @mosaicstack/mosaic test` — pass: 69 files, 1,325 Vitest tests plus framework shell suite.
+- `pnpm typecheck` — pass: 42/42 Turbo tasks.
+- `pnpm lint` — pass: 23/23 Turbo tasks.
+- `pnpm format:check` — pass.
+
+### Situational evidence
+
+A built-CLI temp-home smoke test (no real `~/.claude` or Mosaic config touched) proved:
+
+- register creates the exact link and a second run reports `already registered`;
+- list reports registered and unregistered canonical skills;
+- `../../etc` exits 1 with `Invalid skill name` and creates no escaped path;
+- unregister removes the managed link and a second run reports `already unregistered`;
+- a fake successful framework re-seed generically registered both `added-after-setup` and `second-skill` from runtime directory enumeration.
+
+### Review evidence
+
+- Initial uncommitted Codex code/security review described name validation/clobber protection as strong; its only finding was the harness-owned, unrelated `.mosaic/orchestrator/session.lock`, which is excluded from all commits and the PR.
+- Exact branch review then identified two remediations: preserve successful framework re-seed status when bridge-wide reconciliation fails, and reject/escape control-character names to prevent terminal/log injection.
+- Both findings were reproduced red-first and remediated. A subsequent exact review identified one finalize failure-isolation blocker; a root-wide bridge error now warns and allows wizard doctor/summary/next-steps completion, with a red-first regression.
+- All remediations passed the full package and repository gates. Final exact-head review is rerun after amending the feature commit.
+
+### Acceptance mapping
+
+| Acceptance criterion | Evidence |
+| --- | --- |
+| register/unregister/list, idempotent | `skill.spec.ts` and built-CLI temp-home smoke |
+| traversal/symlink-injection protection | invalid-name matrix, foreign file/dir/link tests, symlinked-root tests |
+| list flags dangling and foreign entries | deterministic list status test |
+| install and upgrade auto-sync every canonical directory | finalize + framework re-seed integration specs; two-skill built-module smoke |
+| newly added skill becomes discoverable without manual link | `added-after-setup` auto-sync creates exact Claude link; Claude can rescan with `/reload-skills` or a new session |
+| Pi/Codex parity captured as scope note | user guide, developer guide, installed framework README |
+| documentation gate | root README, user guide, developer guide, framework README, sitemap |
+
+## Risks
+
+- Symlink replacement uses `lstat` semantics so dangling links are detectable without following them.
+- Link ownership is determined lexically against the canonical skills root, and existing symlink ancestors in either managed root are rejected before mutation.
+- Auto-sync continues across per-skill conflicts while never deleting real files/directories or foreign symlinks.
+- Claude Code discovers filesystem skills at session launch/reload boundaries; bridge creation makes a later `/reload-skills` or new session able to discover the skill, but cannot mutate an already-cached in-process registry by itself.
+- Pi does not need this Claude bridge because its Mosaic launcher can consume the canonical root. Codex lifecycle parity remains explicitly deferred.
+- No deployment surface is affected.
+
+## PR #826 review remediation
+
+- 2026-07-17: Exact-head RoR requested changes for two ownership bugs: installer pruning deleted foreign-name links under `MOSAIC_HOME` outside canonical skills, and unregister deleted a same-root link targeting a different skill. It also requested trailing-dot rejection and executable coverage support.
+- RED evidence: focused regression run failed 4 tests: register/unregister accepted `safe.`, misdirected unregister did not throw, and the install linker deleted the foreign-name link.
+- GREEN evidence: `skill.spec.ts` passes 43/43, including live and dangling foreign-name links in a temp HOME/MOSAIC_HOME and the misdirected unregister invariant.
+- Coverage: `vitest run src/commands/skill.spec.ts --coverage` passes configured 85% thresholds for `skill.ts`: 91.05% statements/lines, 86.27% branches, 95.23% functions.
+- Full gates: package build passed; package tests passed 69 files / 1,332 tests plus framework shell suite; repository typecheck 42/42, lint 23/23, and format check passed.

docs/scratchpads/fcm-m5-001-fleet-config-operator-docs.md

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

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

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

packages/mosaic/README.md

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

packages/mosaic/framework/defaults/README.md

@@ -177,15 +177,23 @@ bash tools/install.sh --cli         # npm CLI only (skip framework)
 bash tools/install.sh --ref v1.0    # Install from a specific git ref
 ```
 
+The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
+
 ## Universal Skills
 
-The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories.
+The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`. Install, wizard finalization, and `mosaic update` automatically reconcile every canonical skill into Claude Code's `~/.claude/skills/` directory.
 
 ```bash
-mosaic sync                                    # Full sync (clone + link)
-~/.config/mosaic/bin/mosaic-sync-skills --link-only   # Re-link only
+mosaic sync                         # Full canonical catalog sync
+mosaic skill list                   # Show registered, missing, dangling, and foreign entries
+mosaic skill register <name>        # Register or repair one canonical Claude link
+mosaic skill unregister <name>      # Remove one Mosaic-owned Claude link
 ```
 
+Skill names are direct children using `[A-Za-z0-9][A-Za-z0-9._-]*`, not paths. Registration rejects traversal/control characters and never replaces foreign files, directories, or symlinks; unregister removes only links that point inside the canonical Mosaic skill root. After registering during a running Claude Code session, use `/reload-skills` or start a new session.
+
+M1 lifecycle management targets Claude Code. Pi can discover the canonical Mosaic root through its launcher configuration. Codex parity remains follow-up scope and continues to use the existing full skill-sync linker.
+
 ## Health Audit
 
 ```bash

packages/mosaic/framework/framework-manifest.txt

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

packages/mosaic/framework/install.sh

@@ -1,5 +1,10 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# -E (errtrace): the ERR trap must propagate INTO functions and command
+# substitutions. Without it the `trap restore_snapshot ERR` set below is dead
+# code for any failure inside sync_framework_keep() (its whole body runs in a
+# function) — a mid-sync failure would abort with a half-written target and NO
+# rollback (#791 B1). Keep -E first so every later function inherits the trap.
+set -Eeuo pipefail
 
 # ─── Mosaic Framework Installer ──────────────────────────────────────────────
 #
@@ -19,32 +24,19 @@ SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 
-# Files/dirs protected from rsync --delete during sync. NOTE: framework-owned
-# entries (CONSTITUTION/AGENTS/STANDARDS) ARE re-applied afterward by
-# reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
-# User-created content in these paths survives rsync --delete.
-#
-# fleet/* — the framework SEEDS fleet/examples, fleet/roles, fleet/profiles, and
-# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
-# and fleet/profiles/*.yaml system-type profile lands automatically via this sync,
-# so no per-file entry is needed; 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).
@@ -75,17 +67,267 @@ step() { echo -e "\n${BOLD}$1${RESET}"; }
 SNAPSHOT_DIR=""
 make_snapshot() {
   is_existing_install || return 0
+  # mktemp -d creates the dir 0700 — the snapshot (which mirrors operator config,
+  # possibly including secrets) is never world-readable.
   SNAPSHOT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-snapshot-XXXXXX")"
-  cp -a "$TARGET_DIR/." "$SNAPSHOT_DIR/" 2>/dev/null || true
+  # The snapshot MUST be complete: restore rebuilds the target from it, so a
+  # partial capture (unreadable file, disk-full, I/O error) would silently
+  # discard whatever it missed. If cp -a cannot copy the whole tree, abort NOW —
+  # before the restore trap is armed and before anything is mutated. Fail closed
+  # rather than proceed with a snapshot we cannot trust (#791 blocker-2).
+  if ! cp -a "$TARGET_DIR/." "$SNAPSHOT_DIR/"; then
+    fail "Could not capture a complete pre-upgrade snapshot of $TARGET_DIR — aborting before any changes were made (fail-closed)."
+    rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""
+    exit 1
+  fi
 }
 restore_snapshot() {
+  # Disarm the trap first: restore runs under `set -e`, and a non-zero step
+  # inside it must not re-enter this handler (errtrace makes ERR fire in
+  # functions now). One restore attempt, then let the script exit non-zero.
+  trap - ERR INT TERM
   [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] || return 0
   fail "Install interrupted/failed — restoring previous state from snapshot"
-  rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"
-  cp -a "$SNAPSHOT_DIR/." "$TARGET_DIR/" 2>/dev/null || true
+  # Reset the target before rebuilding from the snapshot — but CHECK it. Under
+  # `set -e` (trap already disarmed) a bare `rm -rf; mkdir -p` that fails would
+  # exit the whole script immediately, after `rm` may have deleted part of the
+  # target, WITHOUT ever printing the recovery pointer below — the operator would
+  # be left with a half-removed target and no idea the snapshot survives in /tmp.
+  # Test the reset explicitly (like the cp -a below), and on failure keep the
+  # snapshot and tell the operator where it is (#791 blocker-D2).
+  if ! rm -rf "$TARGET_DIR" || ! mkdir -p "$TARGET_DIR"; then
+    fail "Snapshot restore could not reset $TARGET_DIR. Your previous configuration is preserved at: $SNAPSHOT_DIR — copy it back into $TARGET_DIR manually."
+    return 1
+  fi
+  # Surface an incomplete restore instead of swallowing it: the snapshot is the
+  # last good copy, so if cp cannot fully rebuild the target we must NOT delete
+  # the snapshot — point the operator at it for manual recovery (#791 blocker-2).
+  if ! cp -a "$SNAPSHOT_DIR/." "$TARGET_DIR/"; then
+    fail "Snapshot restore did not complete cleanly. Your previous configuration is preserved at: $SNAPSHOT_DIR — copy it back into $TARGET_DIR manually."
+    return 1
+  fi
 }
 cleanup_snapshot() { [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] && rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""; }
 
+# ─── durable operator-config snapshot (#791 PR2) ─────────────────────────────
+# A SECOND, independent safety layer, distinct from SNAPSHOT_DIR above:
+#   • SNAPSHOT_DIR is ephemeral (/tmp, deleted on success) and mirrors the WHOLE
+#     target for CRASH rollback if the sync aborts mid-write.
+#   • DURABLE_SNAPSHOT_DIR is RETAINED, holds only the operator-owned surface, and
+#     lives OUTSIDE the framework tree and any repo. It exists for the failure the
+#     crash-rollback cannot see: a sync that finishes "successfully" yet a
+#     manifest/logic bug let it modify an operator file. verify_operator_surface()
+#     (post-sync) heals from it; `mosaic restore` recovers from it days later.
+# Path convention is mirrored in packages/mosaic/src/commands/restore.ts — keep
+# the two in sync (there is no shared code across the bash/TS boundary).
+DURABLE_SNAPSHOT_DIR=""
+backup_root() { printf '%s/mosaic/backups' "${XDG_STATE_HOME:-$HOME/.local/state}"; }
+
+# Relative paths that a migration INTENTIONALLY removes from the target (e.g. the
+# legacy bin/ tree). Such a path is operator-classified by the manifest (unknown⇒
+# operator), so the durable snapshot captures it — but its post-migration absence
+# is correct, NOT a manifest bug. run_migrations() records each removal here so
+# verify_operator_surface() does not "heal" it back and silently undo the
+# migration (which would then be skipped forever once the version is stamped).
+MIGRATION_REMOVED_PATHS=()
+
+# True (0) if $1 (a path relative to TARGET_DIR) equals or lives under a path a
+# migration deliberately removed this run.
+is_migration_removed() {
+  local rel="$1" removed
+  for removed in ${MIGRATION_REMOVED_PATHS[@]+"${MIGRATION_REMOVED_PATHS[@]}"}; do
+    [[ -n "$removed" ]] || continue
+    [[ "$rel" == "$removed" || "$rel" == "$removed"/* ]] && return 0
+  done
+  return 1
+}
+
+# True (0) if any parent directory of $1 (relative to TARGET_DIR) is a symlink.
+# Restoring THROUGH a symlinked ancestor would let cp write snapshot contents —
+# possibly secrets — outside the target (CWE-59), so the verify net refuses it.
+has_symlinked_parent() {
+  local rel="$1" dir p seg
+  dir="$(dirname "$rel")"
+  [[ "$dir" == "." ]] && return 1
+  p="$TARGET_DIR"
+  local IFS='/'
+  for seg in $dir; do
+    [[ -n "$seg" ]] || continue
+    p="$p/$seg"
+    [[ -L "$p" ]] && return 0
+  done
+  return 1
+}
+
+# Emit (NUL-delimited, into file $1) the operator-owned relative paths that exist
+# under TARGET_DIR, classified via the shared manifest (deny-wins; unknown⇒
+# operator). Returns non-zero if the filesystem walk itself failed — we must
+# NEVER snapshot from a truncated scan (a `< <(find …)` process substitution
+# would hide that error; capture-then-check does not — cf. #791 blocker-D1).
+enumerate_operator_files() {
+  local out="$1" scan abs rel
+  scan="$(mktemp)"
+  if ! find "$TARGET_DIR" -type f -print0 > "$scan"; then
+    rm -f "$scan"
+    return 1  # OP-SCAN-GUARD
+  fi
+  : > "$out"
+  while IFS= read -r -d '' abs; do
+    rel="${abs#"$TARGET_DIR"/}"
+    # Not operator config: version marker and any VCS metadata.
+    case "$rel" in .framework-version|.git|.git/*) continue ;; esac
+    manifest_is_framework "$rel" || printf '%s\0' "$rel" >> "$out"
+  done < "$scan"
+  rm -f "$scan"
+}
+
+# Retain only the newest MOSAIC_BACKUP_RETENTION (default 5) snapshots. The
+# pre-update-<UTC-ts> names sort lexicographically = chronologically, so a
+# reverse sort is newest-first. Pruning failures are non-fatal (they only leave
+# extra old backups); the enclosing find's status is still honored, not swallowed.
+prune_durable_snapshots() {
+  local root keep list d i=0
+  root="$(backup_root)"
+  keep="${MOSAIC_BACKUP_RETENTION:-5}"
+  [[ "$keep" =~ ^[0-9]+$ ]] && (( keep >= 1 )) || keep=5
+  list="$(mktemp)"
+  if ! find "$root" -maxdepth 1 -type d -name 'pre-update-*' > "$list"; then
+    rm -f "$list"; return 0
+  fi
+  # Newest-first ordering needs `sort` (`-o` writes back in place — no `mv`
+  # dependency); if it is somehow unavailable, leave the backups untouched rather
+  # than risk pruning in an undefined order.
+  if ! LC_ALL=C sort -r -o "$list" "$list" 2>/dev/null; then
+    rm -f "$list"; return 0
+  fi
+  while IFS= read -r d; do
+    [[ -n "$d" ]] || continue
+    i=$((i + 1))
+    (( i > keep )) && rm -rf "$d"
+  done < "$list"
+  rm -f "$list"
+}
+
+# Take the durable pre-update snapshot BEFORE any mutation. Fail-OPEN: the durable
+# snapshot is a recovery bonus on top of the manifest (which already keeps the
+# sync out of operator paths) and the crash-rollback — so an un-writable backup
+# location warns and continues rather than blocking the upgrade. Everything it
+# creates is private (umask 077 + explicit 0700 dirs / 0600 files): the snapshot
+# mirrors operator config, which may hold secrets, and must never be world-readable.
+make_durable_snapshot() {
+  is_existing_install || return 0
+  local root ts dir list rel src dst count=0 old_umask
+  root="$(backup_root)"
+  # Fail-open if we cannot even stamp a timestamp: the durable snapshot is a
+  # recovery bonus and must never be the thing that aborts an upgrade.
+  ts="$(date -u +%Y%m%dT%H%M%SZ 2>/dev/null || true)"
+  if [[ -z "$ts" ]]; then
+    warn "Durable snapshot skipped: no UTC timestamp available (upgrade continues)."
+    return 0
+  fi
+  # umask 077 makes every dir/file the snapshot creates private from birth (it
+  # mirrors operator config, which may hold secrets). It is PROCESS-global, so we
+  # save and restore it around exactly this block — otherwise every later sync
+  # copy and new framework dir would inherit 0600/0700 instead of 0644/0755.
+  old_umask="$(umask)"
+  umask 077
+  if ! mkdir -p "$root"; then
+    umask "$old_umask"
+    warn "Durable snapshot skipped: cannot create backup dir $root (upgrade continues; operator files remain manifest-protected)."
+    return 0
+  fi
+  chmod 700 "$root" 2>/dev/null || true
+  dir="$root/pre-update-$ts"
+  if [[ -e "$dir" ]]; then           # same-second re-run: disambiguate
+    local n=1; while [[ -e "$dir-$n" ]]; do n=$((n + 1)); done; dir="$dir-$n"
+  fi
+  if ! mkdir -p "$dir"; then
+    umask "$old_umask"
+    warn "Durable snapshot skipped: cannot create $dir (upgrade continues)."
+    return 0
+  fi
+  chmod 700 "$dir"
+  list="$(mktemp)"
+  if ! enumerate_operator_files "$list"; then
+    umask "$old_umask"
+    warn "Durable snapshot skipped: could not enumerate operator files (upgrade continues)."
+    rm -f "$list"; rmdir "$dir" 2>/dev/null || true
+    return 0
+  fi
+  while IFS= read -r -d '' rel; do
+    src="$TARGET_DIR/$rel"; dst="$dir/$rel"
+    [[ -f "$src" ]] || continue
+    mkdir -p "$(dirname "$dst")"
+    if ! cp "$src" "$dst"; then
+      warn "Durable snapshot: could not copy operator file '$rel' (skipped)."
+      continue
+    fi
+    chmod 600 "$dst" 2>/dev/null || true
+    count=$((count + 1))
+  done < "$list"
+  rm -f "$list"
+  # Tighten every dir the copy created (mkdir -p honors umask, but be explicit).
+  find "$dir" -type d -exec chmod 700 {} + 2>/dev/null || true
+  umask "$old_umask"   # UMASK-RESTORE-NORMAL — restore before the upgrade proper resumes (see above)
+  DURABLE_SNAPSHOT_DIR="$dir"
+  ok "Durable pre-update snapshot: $count operator file(s) saved to $dir (recover with: mosaic restore --list)"
+  prune_durable_snapshots
+}
+
+# Post-sync safety net: a keep-mode upgrade must NEVER modify an operator file.
+# Compare every file in the durable snapshot to its current target counterpart;
+# any that changed (or vanished) was touched by a framework bug — restore it from
+# the snapshot and warn loudly. This does NOT abort: the framework itself synced
+# correctly; we only heal the operator collateral. Runs after the restore trap is
+# disarmed so its corrective copies can't spuriously trip a full rollback, and
+# every step is guarded so `set -e` cannot exit silently mid-heal (cf. blocker-D2).
+verify_operator_surface() {
+  [[ -n "$DURABLE_SNAPSHOT_DIR" && -d "$DURABLE_SNAPSHOT_DIR" ]] || return 0
+  local scan snap rel cur healed=0
+  scan="$(mktemp)"
+  if ! find "$DURABLE_SNAPSHOT_DIR" -type f -print0 > "$scan"; then
+    rm -f "$scan"
+    warn "Post-upgrade verify skipped: could not enumerate the pre-update snapshot at $DURABLE_SNAPSHOT_DIR."
+    return 0
+  fi
+  while IFS= read -r -d '' snap; do
+    rel="${snap#"$DURABLE_SNAPSHOT_DIR"/}"
+    cur="$TARGET_DIR/$rel"
+    # A migration may legitimately delete an operator-classified path (e.g. legacy
+    # bin/). Its absence is intended — do not heal it back, or the migration is
+    # silently undone and never re-runs once the version is stamped (#791 PR2).
+    is_migration_removed "$rel" && continue   # MIGRATION-SKIP-GUARD
+    if [[ ! -e "$cur" ]] || ! cmp -s "$snap" "$cur"; then
+      # Never restore THROUGH a symlink: an operator path swapped for a link would
+      # otherwise let cp write snapshot contents (possibly secrets) outside the
+      # target (CWE-59). Refuse a symlinked parent; drop a symlinked leaf and write
+      # a real file in its place.
+      if has_symlinked_parent "$rel"; then
+        warn "Operator path '$rel' has a symlinked parent under $TARGET_DIR; refusing to restore through it (possible tampering) — recover it manually from $DURABLE_SNAPSHOT_DIR."
+        continue
+      fi
+      [[ -L "$cur" ]] && rm -f "$cur"   # SYMLINK-LEAF-GUARD
+      # Guard mkdir too: under set -e (trap already disarmed) a bare failure would
+      # exit the whole installer before the recovery pointer below is emitted.
+      if ! mkdir -p "$(dirname "$cur")"; then
+        warn "Operator file '$rel' was modified by the upgrade but could NOT be auto-restored (parent dir unavailable) — recover it manually from $DURABLE_SNAPSHOT_DIR."
+        continue
+      fi
+      if cp "$snap" "$cur"; then
+        chmod 600 "$cur" 2>/dev/null || true
+        warn "Operator file was modified by the upgrade and has been restored from the pre-update snapshot: $rel"
+        healed=$((healed + 1))
+      else
+        warn "Operator file '$rel' was modified by the upgrade but could NOT be auto-restored — recover it manually from $DURABLE_SNAPSHOT_DIR."
+      fi
+    fi
+  done < "$scan"
+  rm -f "$scan"
+  if (( healed > 0 )); then
+    warn "$healed operator file(s) were unexpectedly changed by this upgrade and were restored from the pre-update snapshot. A keep-mode upgrade must never modify operator files — this indicates a framework manifest bug; please report it (#791)."
+  fi
+}
+
 # Reconcile contract files after sync: framework-owned overwrite (backup-once),
 # user-seeded seed-if-absent.
 reconcile_framework_files() {
@@ -184,63 +426,105 @@ sync_framework() {
     return
   fi
 
-  if command -v rsync >/dev/null 2>&1; then
-    local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak")
-
   if [[ "$INSTALL_MODE" == "keep" ]]; then
-      # Anchor to the transfer root (leading /) so we preserve the TOP-LEVEL
-      # ~/.config/mosaic/<file> without also excluding defaults/<file> from sync
-      # (reconcile_framework_files needs the freshly-synced defaults/ copies).
-      for path in "${PRESERVE_PATHS[@]}"; do
-        rsync_args+=(--exclude "/$path")
-      done
-    fi
-
-    rsync "${rsync_args[@]}" "$SOURCE_DIR/" "$TARGET_DIR/"
+    # The `mosaic update` path. Manifest-driven, never-deleting-outside-framework:
+    # operator config is structurally protected (#791). No rsync --delete here.
+    # The manifest is already loaded+validated in main() BEFORE the snapshot/trap
+    # (a fail-closed manifest must abort without ever restoring over operator
+    # files — see the pre-flight in main, #791 blocker-1).
+    sync_framework_keep
     return
   fi
 
-  # Fallback: cp-based sync. 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 {} +
+# Enumerate a NUL-delimited file list via `find` into the temp file $1, failing
+# CLOSED if find errors. We capture to a checked file instead of consuming
+# `< <(find …)` directly because a process substitution discards the producer's
+# exit status: an EACCES/I/O failure partway through a scan would truncate the
+# list yet leave the reading `while` loop exiting 0, so a partial upgrade would
+# commit and report success and the ERR/restore trap would never fire. Running
+# find to completion first, then checking its status, turns that silent
+# truncation into a fail-closed abort that the restore trap can act on (#791
+# blocker-D1). $1 after the shift is the scan root — named in the error.
+_scan_or_die() {
+  local out="$1"; shift
+  if ! find "$@" -print0 > "$out"; then
+    fail "Could not enumerate framework files under '$1' — aborting before committing an incomplete sync (fail-closed)."
+    return 1  # D1-GUARD
+  fi
+}
+
+# Keep-mode sync: create/refresh framework-owned files and prune only retired
+# framework files inside shipped framework subtrees. Operator-owned and unknown
+# paths (fail-safe default) are never written and never deleted — the #791 HARD
+# GATE. Single code path (no rsync) so it is byte-for-byte parity-testable.
+sync_framework_keep() {
+  local src="$SOURCE_DIR" dst="$TARGET_DIR" abs rel root list
+
+  # 1) Overlay copy — every framework-owned source file, refreshed only when its
+  #    bytes changed (no mtime churn on unchanged files, never on operator files).
+  #    The source scan is captured fail-closed (#791 blocker-D1): a find failure
+  #    aborts the sync (→ ERR trap → restore) rather than silently truncating it.
+  list="$(mktemp)"
+  _scan_or_die "$list" "$src" -type f || { rm -f "$list"; return 1; }
+  while IFS= read -r -d '' abs; do
+    rel="${abs#"$src"/}"
+    case "$rel" in
+      .git|.git/*|.framework-version|*.pre-constitution.bak) continue ;;
+    esac
+    manifest_is_framework "$rel" || continue
+    if [[ -f "$dst/$rel" ]] && cmp -s "$abs" "$dst/$rel"; then continue; fi
+    [[ "$rel" == */* ]] && mkdir -p "$dst/${rel%/*}"
+    cp "$abs" "$dst/$rel"
+  done < "$list"
+  rm -f "$list"
+
+  # 2) Scoped prune — within each shipped framework subtree root, remove
+  #    framework-owned target files the current source no longer ships. Operator
+  #    carve-outs (e.g. tools/_lib/credentials.json) resolve to operator and are
+  #    skipped; unknown paths resolve to operator too — both are unreachable here.
+  #    Each subtree scan is captured fail-closed for the same reason as the copy.
+  while IFS= read -r root; do
+    [[ -n "$root" && -d "$dst/$root" ]] || continue
+    list="$(mktemp)"
+    _scan_or_die "$list" "$dst/$root" -type f || { rm -f "$list"; return 1; }
+    while IFS= read -r -d '' abs; do
+      rel="${abs#"$dst"/}"
+      case "$rel" in *.pre-constitution.bak) continue ;; esac
+      [[ -f "$src/$rel" ]] && continue                          # still shipped
+      manifest_is_framework "$rel" || continue
+      rm -f "$abs"
+    done < "$list"
+    rm -f "$list"
+    # Drop framework dirs left empty by the prune (never touches a dir that still
+    # holds an operator file — those are never emptied). A genuine find failure
+    # (unreadable dir) is surfaced as a warning rather than silently swallowed;
+    # the "directory not empty" races we tolerate are ignored via -delete's own
+    # rc, not by hiding stderr — so a real error is still visible to the operator.
+    if ! find "$dst/$root" -type d -empty -delete 2>/dev/null; then
+      warn "prune: could not fully sweep empty framework dirs under $root (left as-is)"
+    fi
+  done < <(manifest_subtree_roots)
+}
+
+# Overwrite-mode sync: full replace. Only reached for a fresh install or an
+# explicit operator "replace everything" choice, so nothing is preserved.
+sync_framework_overwrite() {
+  if command -v rsync >/dev/null 2>&1; then
+    rsync -a --delete \
+      --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak" \
+      "$SOURCE_DIR/" "$TARGET_DIR/"
+    return
+  fi
+  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 \
+    ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" \
+    -exec rm -rf {} +
   cp -R "$SOURCE_DIR"/. "$TARGET_DIR"/
   rm -rf "$TARGET_DIR/.git"
-
-  if [[ -n "$preserve_tmp" ]]; then
-    # Restore by re-globbing the SAME patterns against preserve_tmp, so each
-    # preserved item is restored at its own relative path (e.g. only
-    # fleet/roster.yaml is replaced — the freshly-synced fleet/examples stays).
-    for path in "${PRESERVE_PATHS[@]}"; do
-      shopt -s nullglob
-      for match in "$preserve_tmp/"$path; do
-        [[ -e "$match" ]] || continue
-        rel="${match#"$preserve_tmp/"}"
-        rm -rf "$TARGET_DIR/$rel"
-        mkdir -p "$TARGET_DIR/$(dirname "$rel")"
-        cp -R "$match" "$TARGET_DIR/$rel"
-      done
-      shopt -u nullglob
-    done
-    rm -rf "$preserve_tmp"
-  fi
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -261,6 +545,10 @@ run_migrations() {
   # Remove bin/ directory — all executables now live in the npm CLI.
   # Scripts that were in bin/ are now in tools/_scripts/.
   if [[ "$from_version" -lt 2 ]]; then
+    # bin/ and the rails symlink are operator-classified by the manifest (unknown⇒
+    # operator) and thus captured in the durable snapshot; record them as
+    # intentional removals so the post-sync verify net does not restore them.
+    MIGRATION_REMOVED_PATHS+=("bin" "rails")
     if [[ -d "$TARGET_DIR/bin" ]]; then
       ok "Removing legacy bin/ directory (executables now in npm CLI)"
       rm -rf "$TARGET_DIR/bin"
@@ -311,9 +599,26 @@ else
   ok "Install mode: overwrite"
 fi
 
+# Pre-flight (keep mode): load + validate the framework manifest BEFORE taking a
+# snapshot or arming the restore trap. A fail-closed manifest (missing / empty /
+# malformed) must abort here WITHOUT deleting or restoring over operator files —
+# the snapshot/restore path exists only for a genuine mid-sync mutation failure,
+# not for a validation failure that has touched nothing yet (#791 blocker-1).
+if [[ "$INSTALL_MODE" == "keep" ]]; then
+  manifest_load
+  # Durable, operator-scoped backup taken BEFORE any mutation (#791 PR2). Kept
+  # outside the framework tree; recovered later via `mosaic restore`. Fail-open.
+  make_durable_snapshot
+fi
+
 # Snapshot before any destructive file operation; restore on interrupt/failure.
+# The trap MUST exit after restoring: a bash INT/TERM handler that merely returns
+# does NOT terminate the script — execution would resume past the interrupt,
+# clear the snapshot, and report success, leaving a partial post-interrupt update
+# (#791 blocker-A). `restore_snapshot; exit 1` guarantees a non-zero exit for
+# both the errtrace (ERR) and signal (INT/TERM) paths.
 make_snapshot
-trap 'restore_snapshot' ERR INT TERM
+trap 'restore_snapshot; exit 1' ERR INT TERM
 
 sync_framework
 
@@ -342,6 +647,10 @@ run_migrations
 
 # File-system phase complete and consistent — clear the restore trap.
 trap - ERR INT TERM
+# Post-sync safety net: heal any operator file a manifest bug let the sync touch,
+# using the durable pre-update snapshot (#791 PR2). Runs with the trap disarmed so
+# a corrective copy can't spuriously trigger a full rollback.
+verify_operator_surface   # VERIFY-NET (#791 PR2)
 cleanup_snapshot
 
 # Testability / minimal-install hook: stop after the file-system phase, before any

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

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

packages/mosaic/framework/tools/_scripts/mosaic-sync-skills

@@ -161,6 +161,7 @@ link_targets=(
 )
 
 canonical_real="$(readlink -f "$MOSAIC_SKILLS_DIR")"
+local_real="$(readlink -f "$MOSAIC_LOCAL_SKILLS_DIR")"
 
 # Build an associative array from the colon-separated whitelist for O(1) lookup.
 # When MOSAIC_INSTALL_SKILLS is empty, all skills are allowed.
@@ -203,7 +204,14 @@ link_skill_into_target() {
   link_path="$target_dir/$name"
 
   if [[ -L "$link_path" ]]; then
+    local raw_target resolved_target
+    raw_target="$(readlink "$link_path")"
+    resolved_target="$(node -e 'const p=require("node:path"); process.stdout.write(p.resolve(p.dirname(process.argv[1]), process.argv[2]));' "$link_path" "$raw_target")"
+    if [[ "$resolved_target" == "$canonical_real/"* || "$resolved_target" == "$local_real/"* ]]; then
       ln -sfn "$skill_path" "$link_path"
+    else
+      echo "[mosaic-skills] Preserve foreign runtime symlink: $link_path"
+    fi
     return
   fi
 
@@ -234,14 +242,10 @@ prune_stale_links_in_target() {
       continue
     fi
 
-    resolved="$(readlink -f "$link_path" 2>/dev/null || true)"
-    if [[ -z "$resolved" ]]; then
-      rm -f "$link_path"
-      echo "[mosaic-skills] Removed stale broken skill link: $link_path"
-      continue
-    fi
-
-    if [[ "$resolved" == "$MOSAIC_HOME/"* ]]; then
+    # -m resolves lexical dangling targets too. If resolution fails, ownership
+    # is unproven and the link must be preserved.
+    resolved="$(readlink -m "$link_path" 2>/dev/null || true)"
+    if [[ -n "$resolved" && "$resolved" == "$canonical_real/"* ]]; then
       rm -f "$link_path"
       echo "[mosaic-skills] Removed stale retired skill link: $link_path"
     fi