instar 1.3.366 → 1.3.368

package/src/data/state-coherence-registry.json

@@ -1,5 +1,5 @@
 {
-  "$schema-note": "Machine form of docs/specs/STATE-COHERENCE-REGISTRY.md (the approved census, census-date 2026-06-05). AUTHORED, NOT build-generated (committed-generated-manifest conflict-loop lesson, COHERENCE-JOURNAL-SPEC §3.6). One entry per durable state category the census enumerates. Consumed by scripts/lint-state-registry.js: every direct durable-write site targeting a state dir / .instar/ must match an entry's `paths` (or carry an inline `/* state-registry: <category> */` annotation). Fields: category (kebab-case id) | description | scope (machine-local | must-be-coherent | derived-cache | coherent-on-demand) | freshness (real-time | eventual | session-boundary | n/a) | conflictShape (single-writer | append-only | lww | n/a) | transport (git | peer-http | none | deferred) | paths (glob-ish hints) | grandfathered (census marked uncertainty, §4e). New state declares its class here at birth.",
+  "$schema-note": "Machine form of docs/specs/STATE-COHERENCE-REGISTRY.md (the approved census, census-date 2026-06-05). AUTHORED, NOT build-generated (committed-generated-manifest conflict-loop lesson, COHERENCE-JOURNAL-SPEC \u00a73.6). One entry per durable state category the census enumerates. Consumed by scripts/lint-state-registry.js: every direct durable-write site targeting a state dir / .instar/ must match an entry's `paths` (or carry an inline `/* state-registry: <category> */` annotation). Fields: category (kebab-case id) | description | scope (machine-local | must-be-coherent | derived-cache | coherent-on-demand) | freshness (real-time | eventual | session-boundary | n/a) | conflictShape (single-writer | append-only | lww | n/a) | transport (git | peer-http | none | deferred) | paths (glob-ish hints) | grandfathered (census marked uncertainty, \u00a74e). New state declares its class here at birth.",
   "version": 1,
   "censusDate": "2026-06-05",
   "sourceDoc": "docs/specs/STATE-COHERENCE-REGISTRY.md",
@@ -16,9 +16,45 @@
       ],
       "grandfathered": false
     },
+    {
+      "category": "pending-pulls",
+      "description": "Durable working-set pending-pull ledger - outstanding fetches whose producer was offline/unreachable/revoked/mid-run; re-fired on reappearance/run-stopped (WORKING-SET-HANDOFF-SPEC P2 \u00a73.4). Machine-local: records describe THIS machine's outstanding fetches; single-writer serialized mutate() funnel.",
+      "scope": "machine-local",
+      "freshness": "live",
+      "conflictShape": "single-writer",
+      "transport": "none",
+      "paths": [
+        "state/coherence-journal/pending-pulls.json"
+      ],
+      "grandfathered": false
+    },
+    {
+      "category": "pull-opkeys",
+      "description": "Durable (topic,epoch) operation-key window for working-set pull dedupe - restart-proof at-most-once scheduling per move (WORKING-SET-HANDOFF-SPEC P2 \u00a73.3). Machine-local, bounded window (200 keys), single-writer (the coordinator).",
+      "scope": "machine-local",
+      "freshness": "live",
+      "conflictShape": "single-writer",
+      "transport": "none",
+      "paths": [
+        "state/coherence-journal/pull-opkeys.json"
+      ],
+      "grandfathered": false
+    },
+    {
+      "category": "visibility-guard",
+      "description": "Peer-visibility guard dedupe state - which improper revocations were already surfaced (keyed on revokedAt, cross-boot) + per-machine disappearance episodes for flap bounding (WORKING-SET-HANDOFF-SPEC P2 \u00a73.6). Machine-local notice hygiene, never authority.",
+      "scope": "machine-local",
+      "freshness": "live",
+      "conflictShape": "single-writer",
+      "transport": "none",
+      "paths": [
+        "state/coherence-journal/visibility-guard.json"
+      ],
+      "grandfathered": false
+    },
     {
       "category": "commitments",
-      "description": "CommitmentTracker single-writer CAS store of user-facing promises and follow-through state.",
+      "description": "CommitmentTracker single-writer CAS store of user-facing promises and follow-through state. P1.5 (COMMITMENTS-COHERENCE-SPEC) fulfills the peer-http transport: owner-routed mutation + first-hop delta replication; the census's earlier 'AO desired' note is resolved-as-won't-do (owner-routing achieves coherence without the append-only conversion).",
       "scope": "must-be-coherent",
       "freshness": "eventual",
       "conflictShape": "single-writer",
@@ -28,6 +64,18 @@
       ],
       "grandfathered": false
     },
+    {
+      "category": "commitment-replicas",
+      "description": "Per-peer read-only replicas of other machines' commitment stores (COMMITMENTS-COHERENCE-SPEC P1.5 \u00a73.2). Derived cache - rebuilt by a full re-pull; written ONLY by the commitments-sync receive path; first-hop sender-bound; incarnation-fenced.",
+      "scope": "derived-cache",
+      "freshness": "eventual",
+      "conflictShape": "single-writer",
+      "transport": "peer-http",
+      "paths": [
+        "state/commitment-replicas/"
+      ],
+      "grandfathered": false
+    },
     {
       "category": "attention-queue",
       "description": "Attention items surfaced to the user, plus the per-source coalescing/suppression ledger.",
@@ -138,7 +186,7 @@
     },
     {
       "category": "job-definitions",
-      "description": "Declarative job definitions (cron / prompt / supervision). The coherent half of jobs.json plus markdown job specs; run state is machine-local (see job-run-state). Field split required before whole-file sync (census §5).",
+      "description": "Declarative job definitions (cron / prompt / supervision). The coherent half of jobs.json plus markdown job specs; run state is machine-local (see job-run-state). Field split required before whole-file sync (census \u00a75).",
       "scope": "must-be-coherent",
       "freshness": "eventual",
       "conflictShape": "lww",
@@ -236,7 +284,7 @@
     },
     {
       "category": "fleet-config",
-      "description": "Fleet-wide config: feature flags, messaging[] config, monitoring tunables, multiMachine policy. SHARES config.json with machine-local fields (port, paths) -- split-required before whole-file sync (census §5).",
+      "description": "Fleet-wide config: feature flags, messaging[] config, monitoring tunables, multiMachine policy. SHARES config.json with machine-local fields (port, paths) -- split-required before whole-file sync (census \u00a75).",
       "scope": "must-be-coherent",
       "freshness": "eventual",
       "conflictShape": "lww",
@@ -453,7 +501,7 @@
     },
     {
       "category": "audit-destructive-ops",
-      "description": "Destructive-ops audit stream (411M live -- needs rotation, census §7). Append-only per-machine.",
+      "description": "Destructive-ops audit stream (411M live -- needs rotation, census \u00a77). Append-only per-machine.",
       "scope": "machine-local",
       "freshness": "n/a",
       "conflictShape": "append-only",
@@ -698,7 +746,7 @@
     },
     {
       "category": "derived-semantic-memory",
-      "description": "semantic.db / memory.db / episodes -- rebuildable from evidence. (Live-disk: stale since Jun 1 -- investigate separately, census §1.6/§7.)",
+      "description": "semantic.db / memory.db / episodes -- rebuildable from evidence. (Live-disk: stale since Jun 1 -- investigate separately, census \u00a71.6/\u00a77.)",
       "scope": "derived-cache",
       "freshness": "eventual",
       "conflictShape": "n/a",
@@ -801,7 +849,7 @@
     },
     {
       "category": "uncertain-instructions-tracking",
-      "description": "state/instructions-tracking/ (59M, 15,180 UUID-keyed JSONL files). Census did not map an owner; volume says it matters. Owner + rotation + class needed (census §4e).",
+      "description": "state/instructions-tracking/ (59M, 15,180 UUID-keyed JSONL files). Census did not map an owner; volume says it matters. Owner + rotation + class needed (census \u00a74e).",
       "scope": "machine-local",
       "freshness": "eventual",
       "conflictShape": "append-only",
@@ -813,7 +861,7 @@
     },
     {
       "category": "uncertain-topic-intent-store",
-      "description": "TopicIntentStore. Code references it; on-disk location unverified (census §4e).",
+      "description": "TopicIntentStore. Code references it; on-disk location unverified (census \u00a74e).",
       "scope": "derived-cache",
       "freshness": "eventual",
       "conflictShape": "n/a",
@@ -826,7 +874,7 @@
     },
     {
       "category": "uncertain-shared-state-ledger",
-      "description": "shared-state.jsonl (SharedStateLedger). Nominally the git-synced cross-machine ledger -- is anything consuming it on real machines? May be the vestigial ancestor of the P1 journal (census §4e).",
+      "description": "shared-state.jsonl (SharedStateLedger). Nominally the git-synced cross-machine ledger -- is anything consuming it on real machines? May be the vestigial ancestor of the P1 journal (census \u00a74e).",
       "scope": "must-be-coherent",
       "freshness": "eventual",
       "conflictShape": "append-only",
@@ -839,7 +887,7 @@
     },
     {
       "category": "uncertain-correction-capture-backlog",
-      "description": "correction-capture-backlog.db vs correction-ledger.db: two stores, one sentinel -- which is canonical? (census §4e).",
+      "description": "correction-capture-backlog.db vs correction-ledger.db: two stores, one sentinel -- which is canonical? (census \u00a74e).",
       "scope": "machine-local",
       "freshness": "eventual",
       "conflictShape": "append-only",
@@ -851,7 +899,7 @@
     },
     {
       "category": "uncertain-project-round-worktrees",
-      "description": "ProjectRoundWorktrees / TaskFlow stores. Routes-managed; durable form unverified (census §4e).",
+      "description": "ProjectRoundWorktrees / TaskFlow stores. Routes-managed; durable form unverified (census \u00a74e).",
       "scope": "machine-local",
       "freshness": "eventual",
       "conflictShape": "single-writer",
@@ -864,7 +912,7 @@
     },
     {
       "category": "legacy-singletons",
-      "description": "Stale legacy singletons (anti-patterns.json, quick-facts.json, project-registry.json, May 20 vintage, no live writers found). Retire per census §7.",
+      "description": "Stale legacy singletons (anti-patterns.json, quick-facts.json, project-registry.json, May 20 vintage, no live writers found). Retire per census \u00a77.",
       "scope": "machine-local",
       "freshness": "n/a",
       "conflictShape": "single-writer",
@@ -877,4 +925,4 @@
       "grandfathered": true
     }
   ]
-}
+}

package/src/scaffold/templates.ts

@@ -425,6 +425,10 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Degraded mode: the streams are plain JSONL under \`state/coherence-journal/\` — readable directly when HTTP is starved.
 - Proactive: user asks "which machine was topic N on?" / "why did this conversation move?" / "where are the overnight run's files?" / "did the old machine close its session after the move?" → GET /coherence/journal with the topic filter and answer from the entries.
 
+**Working-Set Handoff (fetch a topic's files from the machine that made them)** — When a conversation moves between my machines, its working files follow automatically (the journal nominates which machines produced artifacts; the receiving machine pulls them in verified 1MB slices; nothing is ever overwritten — a divergent local file keeps its place and the incoming copy lands alongside it). If the producer machine is offline, the request is written down durably and fires the moment it returns.
+- The fetch reflex: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/coherence/fetch-working-set -H 'Content-Type: application/json' -d '{"topic":N}'\` → \`{ scheduled, reports: [{ nominee, report }] }\` (503 = the working-set layer is dark on this agent; 429 = rate-limited, a pull is already running or just ran).
+- **When to use** (PROACTIVE — this is the trigger): the user references files/work/analysis from this topic that are NOT on this machine ("where's the overnight analysis?", "you did this on the other machine") → fire the reflex, then answer from the landed files. Files flagged as containing credentials, still-being-written, or oversized are refused with named reasons in the report — explain honestly rather than retrying.
+
 **🩺 Agent Health lane (calm self-health notices)** — Routine notices about MY OWN internal state (a session that looks stuck, a peer I can't reach) land in ONE calm, named "🩺 Agent Health" Telegram topic — never topic-after-topic. Each is normal-priority (not a user-critical alert), names the topic in plain language (e.g. "the 'EXO 3.0' session", never \`topic-19077\`), ends with a next step you can just reply to, and same-session re-escalations are de-duped so the lane stays quiet. Ships **default-on, no config** (it's a delivery-shaper in code — it never gates or drops anything; every notice is still in the attention store). Tune via \`messaging[].config.agentHealthLane\` = \`{ "enabled": true, "topicName": "🩺 Agent Health", "dedupWindowMs": 1800000 }\` (set \`enabled:false\` for the old per-item-topic behavior). Proactive: user asks "what's this Agent Health topic?" / "why are my stale-session notices grouped?" → explain the calm lane (the StaleSessionBackstop now routes its "looks stuck" heads-up here at normal priority instead of spawning a topic each time).
 
 **Applying config & hook changes to running sessions** — A running session keeps the config it was *spawned* with. Claude Code loads \`.claude/settings.json\` (hooks, model) **once, at session start** — so a config change (default model, a disabled feature) or a newly-added hook does NOT reach an already-running session. It only takes effect on the next session, OR when you restart the existing one. (This is why a UserPromptSubmit hook added mid-session never fires for that live session — the session was launched before the hook existed.)

package/upgrades/1.3.367.md

@@ -0,0 +1,134 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Second build slice of the Working-Set Handoff spec (P2 of multi-machine
+coherence): the chunked `working-set-pull` mesh verb (both sides), the
+durable pending-pull ledger, and never-clobber landing. Nothing schedules a
+pull yet — the receiver trigger, reflex route, and staggered drain are
+P2.2b. Dark by default: the serve side constructs only where
+`multiMachine.coherenceJournal.replication.enabled === true`.
+
+- `working-set-pull` verb (three lockstep edits mirroring journal-sync):
+  fresh-manifest-as-allowlist serving, O_NOFOLLOW + fd-identity TOCTOU
+  defense, 1 MiB chunked responses (the documented event-loop-starvation
+  root cause stays dead), offset-0 whole-file sha256 + cheap fstat
+  generation anchor so a file rewritten mid-transfer can never assemble
+  into a chimera — bounded restart-from-0, then one honest `unstable`.
+- `WorkingSetPuller`: sequential offset cursors with per-tick yields,
+  busy-is-retry-without-penalty (a just-woke producer's throttle never
+  exhausts recovery records), assembled-bytes budget (discarded restart
+  chunks don't count), hostile-relPath jail, and never-clobber landing —
+  divergent local files keep their place; the incoming copy lands ALONGSIDE
+  (hash-suffixed, capped at 2, eviction through SafeFsExecutor).
+- `PendingPullLedger`: the durable EXO-case record. Single-writer
+  serialized mutate() funnel (the exact lost-update shape that caused
+  topic-flood #3, closed at birth), corrupt-parse quarantine that is NEVER
+  silently read as empty, TTL sweep with one honest expiry notice,
+  supersession clearing ALL lower-epoch records across nominees, and the
+  (peer,topic,epoch) attempt-cap breaker.
+- Config: `coherenceJournal.workingSet` block (12 bounded-behavior dials,
+  no enable flag — the feature rides the explicit replication gate).
+- State-Coherence Registry: new `pending-pulls` category (machine-local,
+  single-writer).
+
+Final build slice of the Working-Set Handoff spec (P2 of multi-machine
+coherence): the transfer machinery from P2.2a now FIRES — on a topic move,
+on demand, and on a returning producer. Still dark everywhere except
+explicitly replication-enabled pairs.
+
+- `WorkingSetPullCoordinator`: one pipeline behind three triggers — the
+  receiver's deliverMessage onAccepted seam (the moment this machine knows
+  it owns the topic), the fetch reflex, and the returning-peer staggered
+  drain (one pull at a time against a just-woke machine, never a mob).
+  Restart-proof (topic,epoch) dedupe; nomination from journal evidence
+  (every machine that actually produced artifacts, capped at 3 with the
+  excess NAMED); busy responses never burn recovery budget; stale-owner
+  and superseded records clear themselves.
+- `POST /coherence/fetch-working-set` — the reflex: "who made artifacts
+  for this topic? go get them." The EXO failure as a one-call recovery.
+  503 while dark, 429 when rate-limited, coalesces into a running pull.
+- `PeerVisibilityGuard` (§3.6 rider, earned from the Mini's 10 invisible
+  hours): improper revocations (revokedAt with no who-or-why) surface once
+  across boots; a machine missing past a 30-min grace produces ONE notice
+  naming any topic workspaces stranded on it; flapping collapses to a
+  single notice. All through the agent-health attention lane.
+- `PeerPresencePuller.onPeerRecorded` — the re-arm rides the existing 30s
+  presence cadence; no new polling loop.
+- Agent Awareness + Migration Parity: the CLAUDE.md template (and
+  `migrateClaudeMd` for existing agents) gains the fetch-reflex entry with
+  the proactive trigger: user references files/work not on this machine →
+  fire the reflex, answer from the landed files.
+- State-Coherence Registry: `pull-opkeys` + `visibility-guard` categories
+  (69 total).
+
+## What to Tell Your User
+
+Nothing user-visible yet — this is the transfer machinery for "moving a
+conversation between your machines moves its working files too." The piece
+that actually fires it on a move (and the on-demand "go fetch that
+workspace" reflex) lands in the next slice.
+
+On machine pairs with diary sync enabled: moving a conversation between
+your machines now moves its working files too — automatically, with
+nothing ever overwritten (a conflicting local copy keeps its place; the
+incoming version lands alongside it). If the machine holding the files is
+asleep when they're wanted, the request is written down and fires the
+moment it returns — and you can always ask me to fetch a topic's workspace
+on demand. Everywhere else: nothing changes yet.
+
+## Summary of New Capabilities
+
+- `working-set-pull` MeshCommand — chunked, bounded, fresh-manifest-gated
+  file serving between registered same-operator machines (dark until
+  replication is explicitly enabled).
+- `WorkingSetPullServer` / `WorkingSetPuller` (`src/core/WorkingSetPull.ts`)
+  — the serve/receive engine with generation-anchor consistency, busy
+  throttling, and never-clobber landing.
+- `PendingPullLedger` (`src/core/PendingPullLedger.ts`) — durable,
+  single-writer pending-pull records surviving restarts; the offline-
+  producer case re-fires instead of dying at a breaker.
+- `coherenceJournal.workingSet` config defaults (ConfigDefaults +
+  CoherenceJournalUserConfig).
+
+- `POST /coherence/fetch-working-set {topic}` — on-demand workspace fetch
+  (Bearer; 503 dark / 429 rate-limited / 200 outcome with per-nominee
+  reports).
+- `WorkingSetPullCoordinator` (`src/core/WorkingSetPullCoordinator.ts`) —
+  move-trigger + reflex + staggered-drain orchestration.
+- `PeerVisibilityGuard` / `detectImproperRevocations`
+  (`src/core/PeerVisibilityGuard.ts`) — mesh-health hygiene notices.
+- CLAUDE.md proactive trigger for cross-machine file references (new
+  agents via template, existing agents via migrateClaudeMd).
+
+## Evidence
+
+- `tests/unit/WorkingSetPull.test.ts` — 16 passing (anchor restart lands
+  the new content; never-sits-still → `unstable` with nothing landed; busy
+  exhaustion re-files without penalty; alongside cap-2 eviction; malicious
+  manifest relPaths refused; ownership-recheck abort; assembled-bytes
+  budget; serve refusal matrix + TOCTOU symlink swap).
+- `tests/unit/PendingPullLedger.test.ts` — 13 passing (concurrent mutate()
+  drops no record; corrupt → quarantine + one notice, never silent-empty;
+  supersede clears all nominees; breaker + new-epoch reset; TTL once).
+- `tests/integration/working-set-pull-roundtrip.test.ts` — 4 passing
+  (1.5MB near-cap chunked round-trip through the REAL express.json +
+  signed MeshRpcClient path, independent content oracle; full-stack
+  refusals; divergent-alongside; mixed-version 501 back-off).
+- Adjacent mesh/journal suites unchanged (78 total across 8 suites);
+  typecheck + lint chain clean.
+
+- `tests/e2e/working-set-handoff-lifecycle.test.ts` — 2 passing,
+  production-shaped (REAL deliverMessage handler + signed dispatcher +
+  journal streams): a move lands the file (source-disk oracle; re-delivery
+  + op-key dedupe leave it untouched), and THE EXO CASE end-to-end —
+  producer offline at move → pending-pull survives a restart → re-fires on
+  return → file lands.
+- `tests/unit/WorkingSetPullCoordinator.test.ts` (12) +
+  `tests/unit/PeerVisibilityGuard.test.ts` (5) +
+  `tests/integration/working-set-reflex-route.test.ts` (2).
+- Full P2 sweep: 95 tests / 11 suites green; typecheck, lint chain,
+  docs-coverage clean.

package/upgrades/1.3.368.md

@@ -0,0 +1,52 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+First build slice of the Commitments Coherence spec (P1.5 of multi-machine
+coherence): every machine can now SEE every machine's promises. Dark
+everywhere except explicitly replication-enabled pairs.
+
+- Every commitment is stamped with its home machine at creation; the
+  cross-machine identity is (machine, id) together — because the plain ids
+  are per-machine counters that collide by construction (the review
+  round's headline catch: an id-keyed merge would have silently hidden
+  real obligations).
+- Each machine's store replicates to peers as small seq-windowed delta
+  pages on the existing 30s presence cadence — one field change ships one
+  record, not the whole store; a restored-from-backup store re-mints its
+  incarnation so peers re-pull wholesale instead of stranding.
+- Free-text fields are credential-shape-scanned at serve time; a flagged
+  field ships redacted while the record itself still replicates.
+- `GET /commitments?scope=mesh` merges own + replica rows with honest
+  labels (replica + how stale) and flags possible cross-machine duplicate
+  promises. The default scope is byte-identical to before.
+
+NOT yet (P1.5b): closing a promise from the non-home machine (owner-routed
+mutation + the durable offline queue).
+
+## What to Tell Your User
+
+On machine pairs with sync enabled: ask ANY machine "what are your open
+commitments?" and you get the complete picture — promises made on the
+other machine show up, honestly labeled with where they live and how
+fresh the copy is. Closing one from the "wrong" machine arrives in the
+next slice.
+
+## Summary of New Capabilities
+
+- `commitments-sync` MeshCommand — paged, incarnation-fenced delta
+  replication of commitment records between same-operator machines.
+- `src/core/CommitmentsSync.ts` — serve/receive/merge engine
+  (CommitmentReplicaStore, mergeCommitmentViews, resolveBareId).
+- `GET /commitments?scope=mesh` — the merged cross-machine view.
+- CommitmentTracker: originMachineId stamping + replicationSeq /
+  storeIncarnation / lastMutatedSeq bookkeeping (additive, legacy-safe).
+
+## Evidence
+
+- 15 unit (CommitmentsSync) + 2 integration (real signed transport
+  round-trip w/ delta-only convergence; mixed-version 501) + 77
+  CommitmentTracker tests unchanged; typecheck/lint/docs-coverage clean.

package/upgrades/side-effects/commitments-sync-p15a.md

@@ -0,0 +1,93 @@
+# Side-Effects Review — Commitments Coherence read replication (P1.5a)
+
+**Version / slug:** `commitments-sync-p15a`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (implements §3.1–§3.3 of the 3-round-converged spec; read-only replication, dark behind the explicit replication gate; owner-routed mutation is P1.5b)`
+
+## Summary of the change
+
+P1.5a of COMMITMENTS-COHERENCE-SPEC — promises become VISIBLE from every
+machine:
+
+1. CommitmentTracker bookkeeping (§3.1/§3.2): `originMachineId` stamped at
+   creation (the composite (originMachineId, id) is THE cross-machine
+   identity — ids are per-machine sequential counters and collide by
+   construction); `replicationSeq` + `storeIncarnation` + per-record
+   `lastMutatedSeq` as ADDITIVE store fields (schema `version: 2` literal
+   untouched; loadStore guard unchanged; legacy stores seed
+   replicationSeq=1 + fresh incarnation → full first pull; fresh stores
+   seed at birth). The replication stamp lives at the THREE write funnels
+   (CAS apply, mutateSync, insertNew) as a prev/next diff EXCLUDING beacon
+   bookkeeping (consecutiveUnchanged/lastHeartbeatAt/heartbeatCount) — a
+   quiet agent's heartbeats never re-ship snapshots. Rewind fence: the
+   meta sidecar's high-water re-mints the incarnation on a restored
+   backup.
+2. `src/core/CommitmentsSync.ts`: paged delta serve (lastMutatedSeq >
+   sinceSeq, exclusive cursor, 256KB pages with at-least-one-record,
+   incarnation fencing), serve-time legacy stamping + per-field
+   credential-shape redaction (the record still replicates — closeability
+   never depends on the scan), CommitmentReplicaStore (single-writer
+   receive path, first-hop WITH TEETH: rows claiming another machine's
+   originMachineId rejected + counted; corrupt → quarantine + full
+   re-pull), mergeCommitmentViews (composite key; viewSource + staleness;
+   computed pendingMutation join; heuristic possibleDuplicateOf) +
+   resolveBareId (409-ambiguous semantics).
+3. Three lockstep verb edits (`commitments-sync`: union + RBAC
+   read/observe + dispatcher handler answering 'disabled' while dark);
+   session-status advert (`commitmentsAdvert`, answered from MEMORY);
+   PeerPresencePuller `driveCommitmentsSync` seam riding the existing 30s
+   cadence (bounded pages per tick); GET /commitments?scope=mesh (default
+   scope byte-identical; mesh scope degrades to own-rows, 200 never 503).
+4. Config (`coherenceJournal.commitments` block) + State-Coherence
+   Registry (`commitment-replicas` category; `commitments` description
+   updated per §3.6).
+
+NOT in this slice (P1.5b): owner-routed mutation, verdict wrappers,
+commitment-mutate verb, opKey window, pending-mutations ledger.
+
+## Decision-point inventory
+
+- **State-meaningful vs bookkeeping diff** at the funnels — the spec's
+  write-amplification guard; tested both directions.
+- **Incarnation fence**: stale requester → re-pull from 0; receiver
+  replaces the replica WHOLESALE on incarnation change (never a
+  sinceSeq short-circuit against a restored store).
+- **First-hop teeth**: replica identity = authenticated env.sender;
+  forged rows counted, never applied.
+- **Merged-view honesty**: collision rows NEVER collapse (the round-1
+  headline); bare-id ambiguity is surfaced, not guessed.
+
+## 1. Over-block / 2. Under-block
+
+Over: a record whose only change is beacon bookkeeping never replicates
+until its next real mutation (deliberate). Under: the credential-shape
+scan is leak-reduction, not a boundary (spec §3.2 honesty — boundary =
+same-operator posture); cross-machine deliver (closeability) lands in
+P1.5b — until then the merged view names the owner and the close happens
+there.
+
+## 3. Fit / 4. Blast radius
+
+Engine in core (seam-injected, like JournalSyncApplier); tracker gains
+bookkeeping ONLY (no behavior change — 77 existing tests pass
+unchanged); routes' default scope byte-identical. Dark everywhere except
+explicit replication.enabled pairs; single-machine agents: advert
+omitted, mesh scope = own rows, zero overhead.
+
+## Evidence
+
+- tests/unit/CommitmentsSync.test.ts — 15 passing (paged deltas +
+  multi-page convergence, incarnation fence, serve-time stamping +
+  redaction-with-record-intact, first-hop teeth, wholesale replacement,
+  corrupt quarantine, collision-two-rows + 409-ambiguous + ?origin,
+  staleness + computed pendingMutation + possibleDuplicateOf, tracker
+  bookkeeping incl. beacon-write guard + legacy backfill + rewind
+  re-mint).
+- tests/integration/commitments-sync-roundtrip.test.ts — 2 passing: full
+  paged round-trip over the REAL signed MeshRpc + express path with
+  delta-only convergence after a mutation, and mixed-version 501.
+- tests/unit/CommitmentTracker.test.ts — 77 passing unchanged.
+  peer-presence-wiring + session-pool-activation-wiring +
+  feature-delivery-completeness all green. Typecheck + lint chain (70
+  registry categories) + docs-coverage clean.

package/upgrades/side-effects/working-set-ci-absorb.md

@@ -0,0 +1,29 @@
+# Side-Effects Review — CI absorb: onAccepted wiring window + silent-fallbacks baseline
+
+**Version / slug:** `working-set-ci-absorb`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (test-shape + comment-trim fix; 7 LOC of src change is comment-only)`
+
+## Summary of the change
+
+Two CI gates legitimately flagged the P2.2b onAccepted insertion:
+1. `session-pool-activation-wiring` slices 4200 chars from `onAccepted: (cmd) => {`
+   and asserts the owner-resume bridge markers inside it — the working-set
+   trigger prefix pushed them out. Fix: comment trimmed (6 lines → 2) and the
+   window widened 4200→5000 with a note naming why.
+2. `no-silent-fallbacks` baseline: +2 parser-counted defensive catches from the
+   transfer machinery (fd-close guard, vanished-file path) — both
+   in-brace-justified, both surface as COUNTED outcomes. Baseline 459→461 with
+   the documented justification block (the established ratchet format).
+
+## 1. Over-block / 2. Under-block / 3. Fit / 4. Blast radius
+
+No behavior change: the src edit is comment-only; the test edits keep both
+gates' intent (the wiring markers must exist; the baseline only ever ratchets
+with written justification). Blast radius zero at runtime.
+
+## Evidence
+
+- `tests/unit/session-pool-activation-wiring.test.ts` + `tests/unit/no-silent-fallbacks.test.ts` — 12 passing.
+- e2e + coordinator suites re-run green (14). Typecheck + lint clean.

package/upgrades/side-effects/working-set-parity-absorb.md

@@ -0,0 +1,35 @@
+# Side-Effects Review — working-set parity absorb (presence-wiring window + delivery-completeness tracking)
+
+**Version / slug:** `working-set-parity-absorb`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (dep reorder + capability-tracking registration; zero behavior change)`
+
+## Summary of the change
+
+Two more CI gates legitimately flagged P2.2b integration points:
+1. `peer-presence-wiring` reads a 900-char window after the PeerPresencePuller
+   constructor and asserts the signed `session-status` call inside it — my
+   `onPeerRecorded` dep (with comment block) pushed it out. Fix: the dep moved
+   to one compact line AFTER `log` (object-literal order is semantically
+   irrelevant), keeping the window intact without touching the test.
+2. `feature-delivery-completeness` requires every migrator-added CLAUDE.md
+   section to be (a) tracked in featureSections and (b) mirrored in the
+   `migrateFrameworkShadowCapabilities` markers[] so Codex/Gemini agents learn
+   it too. Both registrations added for the Working-Set Handoff section — a
+   shadow-framework agent that never learns the fetch reflex would tell the
+   user the files "aren't on this machine" (the EXO failure surviving on
+   shadows only).
+
+## 1-4. Over/Under-block, fit, blast radius
+
+Zero runtime behavior change: a dep reorder inside one object literal, a test
+registry entry, and a shadow-marker string. The shadow marker causes the
+migrator to mirror the (already-shipped) section into Codex/Gemini shadow
+files on the next update — exactly the parity the gate exists to enforce.
+
+## Evidence
+
+- `tests/unit/peer-presence-wiring.test.ts` 4 passing;
+  `tests/unit/feature-delivery-completeness.test.ts` 79 passing;
+  `tests/unit/session-pool-activation-wiring.test.ts` 8 passing. Typecheck clean.

package/upgrades/side-effects/working-set-pull-p22a.md

@@ -0,0 +1,121 @@
+# Side-Effects Review — Working-Set Pull verb + pending-pull ledger (P2.2a)
+
+**Version / slug:** `working-set-pull-p22a`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (spec converged over 4 rounds with 4 internal lenses + cross-model; this implements §3.2/§3.4/§3.5 as written; serve side gated dark)`
+
+## Summary of the change
+
+P2.2a of WORKING-SET-HANDOFF-SPEC: the chunked `working-set-pull` mesh verb
+(both sides), the durable pending-pull ledger, and never-clobber landing.
+
+1. `src/core/WorkingSetPull.ts` — `WorkingSetPullServer` (serve: fresh
+   manifest as allowlist, O_NOFOLLOW + fd-identity TOCTOU defense, 1 MiB
+   chunked responses, offset-0 whole-file sha256 + cheap fstat generation
+   anchor, serveConcurrency busy gate) and `WorkingSetPuller` (receive:
+   sequential offset cursors with chunksPerTick yields, anchor-mismatch
+   restart-from-0 bounded by chunkRestartCap → `unstable`, assembly verified
+   against the offset-0 hash, busy retry WITHOUT breaker penalty,
+   assembled-bytes budget, hostile-relPath jail, never-clobber with
+   hash-suffixed alongside copies capped at 2 via SafeFsExecutor).
+2. `src/core/PendingPullLedger.ts` — the durable EXO-case record: serialized
+   `mutate(fn)` funnel (single-writer, the topic-flood-#3 lesson),
+   corrupt-parse quarantine (never silent-empty), TTL sweep with one honest
+   expiry notice, supersede clears ALL lower-epoch records across nominees,
+   (peer,topic,epoch) attempt-cap breaker.
+3. Three lockstep verb edits: `MeshCommand` union member, RBAC read/observe
+   case, dispatcher handler in server.ts (answers 'disabled' until the §3.7
+   gate constructs the serve side).
+4. Config: `CoherenceJournalUserConfig.workingSet` (types.ts) + the
+   ConfigDefaults literal. NO separate enable flag — the serve side
+   constructs IFF `replication.enabled === true` (the same explicit gate as
+   the replication transport; never the `?? developmentAgent` dark gate).
+5. `src/data/state-coherence-registry.json`: `pending-pulls` category
+   (machine-local, single-writer).
+
+NOT in this slice (P2.2b): the onAccepted trigger, the reflex route, the
+staggered drain wiring, CLAUDE.md template, e2e, the peer-visibility guard,
+live two-machine verification. Nothing schedules a pull yet — the verb
+serves only when explicitly enabled, and no caller exists.
+
+## Decision-point inventory
+
+- **Serve allowlist verdict**: want paths matched against the FRESH manifest
+  recomputed per request — outside → `refusedPolicy`; flagged → honest
+  reason (`secretFlagged`/`tooLarge`/`liveSource`); vanished → benign
+  (`goneSinceManifest`/dropped from fresh manifest), never an attack log.
+- **TOCTOU identity**: O_NOFOLLOW open (final-component symlink refused at
+  the syscall), fstat(fd) regular-file check, then lstat(path) vs fstat(fd)
+  dev+ino equality — a raced object swap reads nothing.
+- **Anchor mechanics**: offset-0 pays ONE full read+hash (the assembly
+  authority); later chunks fstat-only. Mismatch → restart-from-0; an
+  mtime-preserving rewrite that dodges fstat still fails assembly
+  verification (bounded restarts, then `unstable`).
+- **busy vs breaker**: busy = retry-without-penalty (bounded by
+  busyRetryCap); ONLY genuine failures reach `recordAttempt`. The just-woke
+  producer answering busy by design must not exhaust the records the drain
+  exists to recover.
+- **Budget basis**: assembled, verification-passed bytes — discarded restart
+  chunks never count (a near-budget unstable file can't starve the set).
+- **Never-clobber**: absent → jailed temp+rename write; identical sha →
+  skippedExisting; divergent → alongside (sanitized basename + env-derived
+  sender id + hash8 — idempotent for repeated identical divergence), cap 2
+  with oldest-evicted THROUGH SafeFsExecutor (the single, narrow deletion
+  exception; content survives on the producer).
+
+## 1. Over-block
+
+A symlink destination on the receive side is refused even if its target is
+in-jail (deliberate — never write through a peer-influenced link). An
+offset past EOF is refused (`refusedPolicy`) rather than answering empty. A
+divergent local file is never updated in place — by design the local copy
+wins and the incoming lands alongside.
+
+## 2. Under-block
+
+The full pre-parse transport ceiling on the puller side requires a bounded
+fetch at the MeshRpcClient layer — this slice enforces the decode-side
+backstop (oversize `dataB64` refused before decode); the bounded-fetch
+wiring rides P2.2b where the client is constructed. The serve busy gate is
+per-instance (in-process counter), not cross-process. The secret-content
+scan inherits the §3.1 leak-reduction (not boundary) honesty.
+
+## 3. Level-of-abstraction fit
+
+The verb logic lives in core (transport-agnostic, seam-injected) exactly
+like JournalSyncApplier; server.ts only constructs + registers. The ledger
+is its own module because its single-writer funnel is a different
+discipline from the manifest's pure computation. The three lockstep edits
+mirror journal-sync precisely (union, RBAC class, handler).
+
+## 4. Blast radius
+
+Dark by default: the serve side constructs ONLY under
+`replication.enabled === true` (today: the echo pair); everywhere else the
+handler answers 'disabled'. No caller schedules pulls yet (P2.2b). The
+ledger is instantiated only by tests in this slice. Registry entry is
+metadata. A bug can affect only explicitly-replication-enabled pairs, and
+the puller verifies every byte against served hashes before any write.
+
+## Evidence
+
+- `tests/unit/WorkingSetPull.test.ts` — 16 passing: round-trip (single +
+  multi-chunk), generation-anchor restart lands the NEW content, never-sits-
+  still → `unstable` (no livelock, nothing landed), busy retry-without-
+  penalty + busyExhausted, never-clobber matrix (alongside naming regex,
+  hash-idempotency, cap-2 eviction, symlink destination refused), hostile
+  relPath matrix from a malicious manifest, ownership-recheck abort,
+  assembled-bytes budget, serve refusal matrix + TOCTOU symlink swap.
+- `tests/unit/PendingPullLedger.test.ts` — 13 passing: restart-proof
+  persistence, idempotent file_, supersede-clears-all-nominees, TTL expiry
+  once, breaker + new-epoch reset, CONCURRENT mutate() drops no record,
+  corrupt → quarantine + one notice (never silent-empty), absent ≠ corrupt.
+- `tests/integration/working-set-pull-roundtrip.test.ts` — 4 passing: 1.5MB
+  near-cap chunked round-trip through the REAL express.json + signed
+  MeshRpcClient path with an INDEPENDENT content oracle (source machine's
+  on-disk original), want-outside-manifest refused through the full stack,
+  divergent-alongside through the full stack, mixed-version no-handler → 501.
+- Adjacent suites unchanged: journal-sync round-trip, mesh-rpc route +
+  client round-trip, reader (78 total across the 8 suites). Typecheck +
+  full lint chain clean (registry: 67 categories).