instar 1.3.366 → 1.3.367

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,6 +16,42 @@
       ],
       "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.",
@@ -138,7 +174,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 +272,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 +489,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 +734,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 +837,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 +849,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 +862,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 +875,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 +887,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 +900,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 +913,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/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).

package/upgrades/side-effects/working-set-trigger-p22b.md

@@ -0,0 +1,115 @@
+# Side-Effects Review — Working-set trigger + reflex + drain + visibility guard (P2.2b)
+
+**Version / slug:** `working-set-trigger-p22b`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (implements §3.3/§3.4/§3.6 of the 4-round-converged spec; everything rides the explicit replication gate; e2e proves the EXO case end-to-end)`
+
+## Summary of the change
+
+P2.2b — the working-set transfer now FIRES. Completes P2:
+
+1. `src/core/WorkingSetPullCoordinator.ts` — the orchestration layer: the
+   move trigger (receiver-side deliverMessage onAccepted seam), the reflex,
+   and the returning-peer staggered drain share ONE pipeline. Durable
+   (topic,epoch) op-key dedupe (restart-proof, `pull-opkeys.json`, bounded
+   window 200); skips not-owner / placing-confirm / prevOwner-self;
+   single-flight per topic; plural bounded nomination from journal evidence
+   (own + replicas, cap 3, cappedNominees named); pending-pulls filed with
+   busy-never-burns-an-attempt accounting; staggered drain (rearmConcurrency
+   1) with stale-owner clear + epoch supersession; slow sweep tick = TTL +
+   live-source re-arm.
+2. `src/core/PeerVisibilityGuard.ts` — §3.6 rider: pure
+   `detectImproperRevocations` (NOT inside loadRegistry — it stays hot +
+   pure) + cross-boot-deduped notices (keyed on revokedAt); 30-min-grace
+   disappearance notice naming stranded pending-pull topics; flap bound
+   (3 episodes/24h → ONE collapse notice). All notices ride the
+   agent-health attention lane.
+3. `POST /coherence/fetch-working-set` (routes.ts) — the reflex. 503 dark,
+   400 bad topic, 429 rate-limited, 200 outcome.
+4. `PeerPresencePuller.onPeerRecorded` seam — the §3.4 re-arm rides the
+   SAME 30s cadence journal-sync does (no new polling loop).
+5. server.ts wiring: coordinator + ledger + guard constructed ONLY when the
+   serve side exists (the explicit `replication.enabled === true` gate);
+   onAccepted hook fires BEFORE the session-pool stage gate
+   (fire-and-forget; the coordinator carries its own gates); ledger
+   onCorrupt/onExpired → agent-health attention items; 10-min sweep timer;
+   5-min guard timer.
+6. Agent Awareness + Migration Parity: CLAUDE.md template gains the
+   fetch-reflex section with the proactive trigger ("user references
+   files/work not on this machine"); `migrateClaudeMd` adds it
+   content-sniffed for existing agents.
+7. State-Coherence Registry: `pull-opkeys` + `visibility-guard` categories.
+
+## Decision-point inventory
+
+- **Trigger gates** (ordered): single-flight → ownership (live store, the
+  only authority) → epoch present → op-key dedupe (move only; the reflex
+  deliberately bypasses it — an explicit ask re-fetches) → prevOwner-self
+  skip → pressure defer (op-key NOT recorded, so the next accept
+  re-triggers — a defer is never a silent drop).
+- **busy vs attempts**: only genuine failures (unreachable/throw) reach
+  `recordAttempt`; busyExhausted re-files the record attempt-free (§3.2).
+- **Drain semantics**: per-record ownership recheck (stale-owner → clear,
+  newer epoch → supersede) so a drained record can never write onto a
+  topic this machine no longer owns.
+- **Guard honesty**: hygiene signal only — populated revocation fields are
+  NOT authenticated; the notice text says so explicitly.
+
+## 1. Over-block
+
+A reflex call within 30s of the last is 429'd (coalescing handles the
+concurrent case). A move while under host pressure defers the pull until
+the next trigger. The drain clears records for topics we no longer own —
+deliberate: the current owner's own pull covers truth.
+
+## 2. Under-block
+
+The op-key window is bounded at 200 — a topic moved 200+ epochs ago could
+re-pull (idempotent via skippedExisting, harmless). The disappearance
+notice depends on the pool registry's online view (a registry blind spot
+is the §3.6 known limitation). The pressure-defer relies on the next
+accept/reflex; a topic that never gets another message AND was deferred
+falls to the reflex (named spec §3.3 behavior).
+
+## 3. Level-of-abstraction fit
+
+The coordinator is transport-agnostic core (seam-injected like the puller);
+server.ts only constructs + wires. The guard's detector is a pure function
+per the integration-review finding (loadRegistry stays a hot dependency-free
+read). The onAccepted hook lands in the existing createDeliverMessageHandler
+seam — the exact place the spec's round-1 integration review corrected the
+design to (ownAction/confirmClaim run on the ROUTER, the wrong machine).
+
+## 4. Blast radius
+
+Dark everywhere except explicitly-replication-enabled pairs (today: the
+echo Laptop+Mini). The onAccepted hook is one optional-chained call on a
+coordinator that is undefined when dark. The reflex route 503s when dark.
+The guard runs only inside the same gated block. Template/migration text
+is awareness-only (the endpoint answers 503 until the layer is live).
+
+## Evidence
+
+- `tests/unit/WorkingSetPullCoordinator.test.ts` — 12 passing: ownership
+  gating, DURABLE op-key dedupe across a coordinator restart,
+  pressure-defer-leaves-opkey-unburned, prevOwner-self skip, plural
+  nomination (newest-first, cap, cappedNominees, self excluded), genuine
+  vs busy attempt accounting, live-source clear-on-success, staggered
+  drain (sequential, stale-owner clear, drain gate), reflex rate-limit +
+  coalescing.
+- `tests/unit/PeerVisibilityGuard.test.ts` — 5 passing: pure detector
+  matrix, cross-boot dedupe (crash-loop cannot re-spam), disappearance
+  episode lifecycle with stranded topics named + silent re-peer clear,
+  flap collapse to ONE notice.
+- `tests/integration/working-set-reflex-route.test.ts` — 2 passing: 503
+  dark / 400 / 200-through-a-real-coordinator / 429.
+- `tests/e2e/working-set-handoff-lifecycle.test.ts` — 2 passing,
+  production-shaped (REAL createDeliverMessageHandler + REAL signed
+  dispatcher/client + REAL journal streams): (1) a topic move lands the
+  file on the receiver, verified against the source's on-disk original +
+  re-delivery/op-key dedupe leaves it untouched; (2) THE EXO CASE —
+  producer offline at move, pending-pull survives a restart, re-fires on
+  the peer's return, file lands, record cleared.
+- Full P2 sweep: 95 tests across 11 suites green; typecheck + lint chain
+  (69 registry categories) + docs-coverage clean.