instar 1.3.500 → 1.3.502

package/upgrades/1.3.501.md

@@ -0,0 +1,51 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Implements `docs/specs/reap-notify-per-topic-and-midwork-resume-queue.md` (converged 7 iterations with GPT-5.5 + Gemini 2.5 Pro cross-review, operator-approved 2026-06-12, topic 24662 — "reaped sessions should ALWAYS notify the user in the corresponding topic, and mid-work reaps need a persistent resume mechanism").
+
+**Part A — per-topic durable reap notices (default ON):**
+- `ReapNotifier` v2: per-topic coalescing — every topic that lost a session gets ONE notice in THAT topic (plain-English reasons, mid-work tag); the lifeline gets unbound sessions + a cross-topic index. Affected-set tracking is separate from the detail buffer, so storms still produce correct per-topic counts. Rollback: `monitoring.reapNotify.perTopic: false`.
+- Durable delivery: notices are `reap-notify:`-prefixed rows in the shared PendingRelayStore (release holds ride the existing `next_attempt_at` column — zero DDL), drained by a NEW always-on `ReapNoticeDrain` (30s tick, CAS claims, per-pass cap 15, backoff to 8 attempts, terminal escalation into ONE aggregated attention item). Independent of the default-OFF DeliveryFailureSentinel. Rollback: `monitoring.reapNotify.drainEnabled: false`.
+- **Store-level fix for everyone (R1.6):** the pending-relay restore-purge cutoff is now `max(attempted_at, next_attempt_at)` with a 7-day corruption clamp — a message HELD for future release no longer gets eaten at boot (the 2026-06-05 silent-deletion class, fixed for ALL rows, not just reap notices).
+- Outcome records: every notice attempt lands in the reap-log as `type:'notify'` pairs (`enqueued` → `sent`/`send-failed-escalated`/`no-topic`/`enqueue-failed`) — "did the user get told?" is now auditable.
+
+**Part B — mid-work tagging + resume queue (ships enabled + dry-run observe-only):**
+- Killers supply work evidence at THEIR decision point (the quota-shed migrator snapshots it BEFORE its Ctrl+C grace round tears the work down); the single kill chokepoint clamps it to an exact enum and stamps `midWork` on the event, the reap-log, and the session record.
+- `ResumeQueue`: durable per-machine queue (fsync persist discipline, single-writer lockfile with same-host stale reclaim + foreign-host loud-disable, corrupt-file sidecar, boot reconciliation from the reap-log). Eligibility is stricter than midWork: ≥1 strong signal (or topic-bound + 2 distinct weak); jobs opt in via `resumeOnReap: true` (default false); operator kills excluded by default.
+- `ResumeQueueDrainer`: revives AT MOST ONE entry per minute, only after 3 consecutive calm pressure ticks + quota headroom + session-cap + no migration in flight. Seven drain-time reality validations re-check the world before any spawn. Failure ladder: 3 attempts with backoff → gave-up; resurrection cap (2 per identity per 24h) kills kill-resume-kill loops; circuit breaker on consecutive failures. ALL give-up classes fold into ONE rolling attention item.
+- Emergency stops reach the queue: stop-all/MessageSentinel stops pause it (TTLs frozen, mutation routes 409); per-topic stops cancel that topic's entries; explicit unpause via `POST /sessions/resume-queue/resume`.
+- New spawn-path capability: sessions can now be spawned with an explicit per-spawn `cwd`, so interrupted worktree work resumes in ITS tree.
+- Tier 1 supervision (observe-only during the soak): each about-to-resume decision gets an audited fast-tier LLM sanity check that never defers.
+
+**Foundation fixes pulled in-scope (no deferrals):**
+- `SessionMigrator` no longer records a ReapGuard REFUSAL as "halted" — refused-but-alive sessions are no longer double-respawned after a quota migration.
+- The reap-log normalizer no longer strips `launchLane` on read.
+
+**Migration parity:** ConfigDefaults gains `reapNotify.perTopic` + `maxImmediatePerFlush` (resumeQueue keys deliberately code-defaulted for the later fleet flip); new content-sniffed `migrateClaudeMd()` section + framework-shadow marker; `state/resume-queue.json` registered machine-local (excluded from backup/restore).
+
+## What to Tell Your User
+
+- "When the system shuts down your sessions (low memory, usage limits), each affected conversation now gets its own clear notice — and the notice can't be silently lost anymore, even across restarts."
+- "Coming online in watch-mode: sessions killed mid-work get queued and automatically restarted one at a time once your machine recovers, picking the work back up."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Per-topic shutdown notices | Automatic — each affected topic is told, in plain English |
+| Durable notice delivery | Automatic — `reap-notify` rows in the pending-relay store, always-on drain |
+| Notice audit trail | `GET /sessions/reap-log` — `type:'notify'` outcome pairs |
+| Mid-work tagging | reap-log + session records carry `midWork` + `workEvidence` |
+| Resume queue state | `GET /sessions/resume-queue` (entries, paused, breaker, lastTickAt) |
+| Queue levers | `POST /sessions/resume-queue/:id/cancel` · `/:id/requeue` · `/resume` · `/drain` |
+| Job opt-in | `resumeOnReap: true` on a job definition |
+
+## Evidence
+
+- Tier-1: `tests/unit/pending-relay-store.test.ts` (R1.6 + origin scoping + CAS), `reap-log.test.ts`, `work-evidence.test.ts`, `session-migrator.test.ts` (pre-grace evidence + refusal recording), `reap-notifier.test.ts` (v2 matrix + legacy modes), `reap-notice-drain.test.ts`, `resume-queue.test.ts`, `resume-queue-drainer.test.ts`.
+- Tier-2/3: resume-queue route integration + reap→durable-notify lifecycle + feature-alive E2E (same PR).
+- Side-effects artifact: `upgrades/side-effects/reap-notify-resume-queue.md`.

package/upgrades/1.3.502.md

@@ -0,0 +1,75 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Added the Durable Inbound Message Queue + Hold-for-Stability policy (CMT-1118,
+spec `docs/specs/durable-inbound-message-queue.md`, 10-round convergence). When
+the multi-machine router cannot deliver an inbound message right now (its
+conversation is mid-move, or the owning machine is briefly unhealthy), the
+message now goes into a crash-proof on-disk queue (`PendingInboundStore`,
+SQLite `synchronous=FULL`, 0600) instead of being injected into a possibly-stale
+local session or relying on platform resend — and a suspect-but-alive machine
+gets up to 90 seconds to recover before its conversation is moved (fewer
+machine swaps on 5-second blips). The drain engine carries the full reviewed
+safety set: receipt-before-inject at-most-once acting, transactional
+emergency-stop fences, queued-rows-only pause with cumulative caps, tenure
+clamps (acquisition-generation, never the renewal epoch), six boot-validated
+config invariants (violation = queue stays OFF, loudly), P19 brakes with an
+Eternal-Sentinel declared tick, and every loss window reported — never silent.
+New Bearer route `GET /pool/queue` (503 while dark); capacity heartbeats gain
+queue depth/tenure/top-K; guard manifest + dark-gate registrations included.
+**Ships DARK**: `multiMachine.sessionPool.inboundQueue` defaults
+`enabled:false, dryRun:true`; hold-for-stability trails one rollout stage.
+
+## What to Tell Your User
+
+Nothing changes today — this ships off by default. Once enabled (staged rollout,
+dry-run first): messages that arrive while your agent's conversation is moving
+between machines can no longer be lost or delivered to the wrong place — they
+wait in a small crash-proof queue and deliver in order when the move finishes.
+And a machine having a brief network blip gets ~90 seconds to recover before
+its conversations are moved off it, so you'll see far fewer pointless machine
+swaps. If anything ever can't be delivered, you get one plain notice naming
+what to resend — never silence.
+
+## Summary of New Capabilities
+
+- `GET /pool/queue` — queue counts (queued/claimed/held/frozen, delivered24h
+  which excludes possibly-not-injected), durable counters (incl. dry-run
+  `wouldEnqueue`/`wouldHold` promotion evidence, `possiblyNotInjected`,
+  `holdBypassedByAttemptsCap`), hold/flap state, tenure. 503 while dark.
+- Capacity heartbeats: `inboundQueue` block (depth, oldest, tenure, top-K) —
+  feeds the survivor loss-suspected item + capped session recovery when a
+  machine dies holding messages.
+- `DeliverAck` gains the typed `sender-rejected` NACK (receive-side authz
+  re-validation of carried sender envelopes).
+- Guard posture: `multiMachine.sessionPool.inboundQueue.enabled` +
+  `multiMachine.sessionPool.holdForStability.enabled` rows in `/guards`
+  (hold's getter reports the EFFECTIVE state — orphaned config derives
+  off-runtime-divergent).
+
+## Evidence
+
+- Unit: `pending-inbound-store.test.ts` 32/32 (tri-state, bounds + carve-out
+  boundary, AUTOINCREMENT across prunes, claim CAS, eviction-skips-claimed,
+  payload hygiene + locator retention, conditional receipt fence, tenure
+  derivation incl. A→B→A, cumulative pause accounting across restart, handle
+  encapsulation, 0600); `queue-drain-loop.test.ts` 35/35 (dispositions incl.
+  delivered-unconfirmed, stop-fence both interleavings, pause scope round-9,
+  hold budget across episodes, herd cap, maxHeldTotal degrade, maxAttempts
+  forced re-place both arms, tenure clamps, wake clamps, Eternal-Sentinel
+  episode latch, mirror reconciliation, P19 sustained-failure hour);
+  `inbound-queue-config.test.ts` 10/10 (all six invariants, defaults parity
+  with ConfigDefaults); `inbound-queue-boot-sweep.test.ts` 13/13 (gate-expiry
+  ×4 reasons, crash-table rows 1–3, stop-scoped PIS veto, pause-aware
+  recovery, quarantine + expiry).
+- Integration: `inbound-queue-route.test.ts` 3/3 (ships-dark 503, feature-alive
+  200 over real HTTP + real engine + real SQLite, delivered24h exclusion).
+- E2E: `inbound-queue-lifecycle.test.ts` 2/2 (production-init order: sweep →
+  invariants → engine adopts swept store → drain → route truth; and the
+  production-default disabled boot: gate-expiry + 503).
+- Lints: `lint-dev-agent-dark-gate` clean (both flags registered);
+  `lint-guard-manifest` clean (components listed).

package/upgrades/side-effects/1.3.492.md

@@ -0,0 +1,20 @@
+# Side-Effects Review — v1.3.492 (version-named pairing)
+
+This is the version-named pairing for the v1.3.492 release, completing the
+rename step the release cut is expected to perform alongside the
+`NEXT.md → 1.3.492.md` guide rename (see `scripts/pre-push-gate.js` check 5:
+"the fragment/NEXT.md -> <version>.md rename pairs with an artifact rename").
+The release flow did not perform the artifact half of the pairing, which makes
+check 5 false-positive on every docs-only push from a clean post-release tree.
+
+The actual side-effects review for everything shipped in v1.3.492 is:
+
+- `upgrades/side-effects/cartographer-sweep-eventloop-safety.md`
+  (cited by `upgrades/1.3.492.md` § Evidence — reviewer raised 2 material
+  concerns, both fixed before commit)
+
+That artifact is left in place under its slug name because the release guide's
+Evidence section cites it by that path. This file exists so the repo state
+matches the gate's documented post-release expectation. The underlying gap
+(release automation never renames artifacts) is logged to the framework-issues
+ledger under dedupKey `pre-push-gate-versioned-artifact-fallback`.

package/upgrades/side-effects/durable-inbound-message-queue.md

@@ -0,0 +1,213 @@
+# Side-Effects Review — Durable Inbound Message Queue + Hold-for-Stability
+
+**Version / slug:** `durable-inbound-message-queue`
+**Date:** `2026-06-12`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `independent reviewer subagent (required — gates dispatch + session lifecycle)`
+
+## Summary of the change
+
+Implements the converged + approved spec `docs/specs/durable-inbound-message-queue.md`
+(CMT-1118, 10 convergence rounds): when the session-pool router cannot deliver an
+inbound message right now (`queued`/`placement-blocked` verdicts that today fall
+through to possibly-wrong-place local dispatch), the message is taken into durable
+SQLite custody (`PendingInboundStore`, `synchronous=FULL`, 0600) and a drain engine
+(`QueueDrainLoop`) delivers it when the blockage clears — with hold-for-stability
+giving a suspect-but-alive owner up to `holdMaxMs` (90s) before its conversation is
+re-placed. Ships DARK (`multiMachine.sessionPool.inboundQueue` enabled:false +
+dryRun:true; hold trails one stage). Files: new `src/core/PendingInboundStore.ts`,
+`QueueDrainLoop.ts`, `inboundQueueConfig.ts`, `inboundQueueBootSweep.ts`; edits to
+`SessionRouter.ts`, `OwnerSuspectBreaker.ts`, `DeliverMessageHandler.ts`,
+`MachinePoolRegistry.ts`, `BackupManager.ts`, `ConfigDefaults.ts`,
+`devGatedFeatures.ts`, `guardManifest.ts`, `types.ts`, `TelegramAdapter.ts`,
+`PostUpdateMigrator.ts`, `templates.ts`, `routes.ts`, `AgentServer.ts`,
+`commands/server.ts`, `scripts/lint-guard-manifest.js`; four new test files
+(unit ×4, integration ×1, e2e ×1).
+
+## Decision-point inventory
+
+- `SessionRouter.queueMessage` — modify — no-op → tri-state custody taking; router
+  sets `acked` only for `queued`/`already-queued` (refused keeps today's un-acked
+  fall-through).
+- `Consumption site (server.ts onTopicMessage route consult)` — modify — adds the
+  ordering gate, the custody-ack short-circuit, and the custody-aware route-throw
+  point read; all three no-op when the engine is null (dark).
+- `OwnerHoldVerdict (new)` — add — hold/failover/deliver at every
+  `placeAndClaim('failover')` site; always-`failover` injected when the policy is
+  off/dry-run (§4.2 effective-state honesty, /guards getter on the unconditional
+  boot path).
+- `DeliverMessageHandler.validateSender` — add — receive-side authz re-validation;
+  typed non-retryable `sender-rejected` NACK; only consulted when an envelope is
+  present (old peers unaffected).
+- `Emergency-stop custody settle (TelegramAdapter.onSentinelStopCustody)` — add —
+  stop transitions queued custody terminal + PIS cleanup; pause is engine-level
+  (queued-rows-only freeze) and currently API-driven only (the sentinel 'pause'
+  category still Escape-keys the session as before — unchanged behavior).
+- `Boot sweep (runInboundQueueBootSweep)` — add — unconditional boot path, before
+  `recoverPendingInjects`; gate-expires custody with named reasons; quarantines a
+  corrupt store; vetoes PIS records for operator-stop rows ONLY.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The enqueue path can `refuse` legitimate messages at the caps (`maxPerSession` 50 /
+`maxTotal` 500 / `hardMaxTotal` 1000 / oversize >64KB) — but a refusal is NEVER a
+block: it maps to `acked:false` → today's exact local-dispatch fall-through, so the
+worst case for a legitimate message is the pre-feature behavior (delivery, possibly
+wrong-place, counted in `orderingViolations`). The `sender-rejected` NACK can reject
+a sender deauthorized on the receiving machine but still authorized on the sender's
+— per-machine registry divergence during a deauthorization window; the spec chose
+the conservative side (the receive-side registry wins), the entry terminals
+loss-REPORTED, and an old peer (no envelope) is never affected. The config-seam
+validation refuses to START the queue on a violated invariant — deliberately
+over-blocking the feature itself (OFF = today's behavior) rather than running
+half-configured.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The spec enumerates these as named windows: loss windows 1–6 (machine disk death;
+crash instants around the receipt; restore-to-new-machine silent forfeit) and
+duplicate windows 1–5 (PIS at-least-once replay instant; route-throw point-read
+error fail-open; version-skew receipt boundary). None are silent — each is reported
+or explicitly accepted in the spec with bounds. The hold verdict cannot detect a
+hard-crashed machine faster than the heartbeat staleness window (one hold cycle of
+added latency, named in spec §4.2). The §5.1 survivor arm only sees peers whose
+last heartbeat carried depth fields (old/mesh-less peers are honestly unknown).
+
+## 3. Level-of-abstraction fit
+
+The custody store sits at the router verdict layer — the exact seam where the
+no-op `queueMessage` already existed; it does not duplicate the ingress
+exactly-once ledger (bypassed by design for drained entries — the receipt class is
+the drain's own authority) nor the PendingRelayStore (outbound). The hold policy
+feeds the EXISTING OwnerSuspectBreaker signals rather than adding a parallel
+detector. The boot sweep lives on the unconditional boot path because the gated-off
+states are exactly the ones whose components never construct (round-2/round-4
+findings). No higher-layer gate exists that this should feed instead.
+
+## 4. Signal vs authority compliance
+
+Every decision is a deterministic policy evaluation over enumerable inputs (route
+outcome enum, heartbeat liveness, breaker state, row state) — no brittle
+pattern-matching holds blocking authority (`docs/signal-vs-authority.md`). The
+fail direction is open-to-today's-behavior everywhere: storage failure → refused →
+fall-through; point-read error → fall-through; invariant violation → queue OFF.
+The flap detector and loss reports are signal-only (attention items, counters).
+The one new blocking-shaped surface — `sender-rejected` — is an authz re-check
+against the durable users registry (existing authority, new enforcement point),
+not a new heuristic. Spec §Supervision documents the Tier-0
+deterministic-evaluator carve-out; the 10-round convergence (including the
+lessons-aware reviewer) audited exactly this question.
+
+## 5. Interactions
+
+- The ingress exactly-once ledger: custody COMPLETES the ledger row (the spec's
+  §2.2 lifecycle); drained entries bypass the ledger gate by design — the
+  injection receipt is a DISTINCT class, so no double-fire.
+- PendingInjectStore: receipt-first ordering pinned (round-7); stop deletes PIS
+  records; the boot sweep runs BEFORE `recoverPendingInjects` and vetoes
+  operator-stop records only — the pause case deliberately does NOT veto.
+- OwnerSuspectBreaker: `onClose` is additive; `recordSuccess` semantics unchanged.
+- The reaper/respawn machinery: the drain reuses `respawnSessionForTopic` /
+  `spawnSessionForTopic` WITH the `spawningTopics` guard, so drain and live spawns
+  cannot race a duplicate spawn.
+- Telegram dedup/confirmations: drain deliveries suppress the per-message
+  "✓ Delivered" (the §3.1 contract) — no confirmation flood.
+- Double-dispatch: the custody-ack short-circuit only fires when the enqueue
+  COMMITTED (acked), and the route-throw catch point-reads the store — the
+  enumerated residual is a point-read ERROR failing open (bounded duplicate,
+  §5-enumerated).
+
+## 6. External surfaces
+
+- New Bearer-gated route `GET /pool/queue` (503 while dark). No payload content is
+  ever served — counts, counters, tenure only.
+- Mesh `deliverMessage` envelope gains optional `senderEnvelope`; `DeliverAck`
+  gains `'sender-rejected'`. Old peers: never emit the new ack value, ignore the
+  new field — both skew directions named in the spec.
+- Capacity heartbeat gains the `inboundQueue` block (depth/oldest/tenure/topK) —
+  additive, absent = unknown on old peers.
+- CLAUDE.md template + `migrateClaudeMd` section (Agent Awareness + Migration
+  Parity); ConfigDefaults delivers the dark config blocks to existing agents via
+  the existing add-missing recursion (verified by test).
+- The store file is excluded from backups via the unconditional
+  `BLOCKED_PATH_PREFIXES` (restoring custody to a new machine would claim
+  messages it never held).
+- Timing/runtime dependence: drain behavior depends on heartbeat freshness and the
+  breaker's suspect windows — exactly the dependencies the spec's hold-budget and
+  clamp bounds were designed around.
+
+## 7. Rollback cost
+
+Feature is dark by default; nothing changes on deploy until an operator advances
+the rollout. If wrong in production: flip `inboundQueue.enabled:false` (or
+`dryRun:true`) + normal restart — the boot sweep gate-expires any residual custody
+with named, loss-reported reasons (no silent stranding; flag semantics are
+boot-read by design, spec §5.3). No data migration: the SQLite store is created on
+first use and quarantine/prune paths bound its lifetime. The OFF-state is
+byte-for-byte today's behavior except the one-shot residual sweep — verified by
+the gate × behavior matrix tests. Worst-case backout is a hot-fix release deleting
+the wiring; no agent state repair is ever needed (rows are per-machine,
+self-expiring, backup-excluded).
+
+## Known deliberate simplifications (named, not hidden)
+
+- The §3.1 "extraction" is implemented as a drain-specific tail
+  (`_drainLocalDeliver`) built from the same primitives as the live tail rather
+  than relocating the live tail's 150 lines into a shared function — the live
+  hot path is byte-untouched (zero regression risk), at the cost of two parallel
+  tails to keep in sync. The drain tail enumerates every contract divergence in
+  its comment block.
+- The sentinel 'pause' category keeps its existing behavior (Escape key); the
+  engine's pause/freeze surface (`onPause`/`onResume`) is fully built + tested
+  but not yet bound to a user-facing trigger — binding it is a UX decision the
+  operator should make with live dry-run data (the spec's §3.6 pause semantics
+  are about WHEN frozen rows behave correctly, which is what ships).
+- `custodyDurability` reports `'unknown'` (no fsync probe in v1) — the spec's
+  round-8 field shipped as an honest placeholder rather than a guessed value.
+- The §5.1 survivor re-placement uses empty-payload synthetic messages through
+  `SessionRouter.forceReplace` (the router path, honoring pins + CAS) — "session
+  recovery without message replay", exactly the spec's framing.
+
+## Known deliberate simplifications — addendum after second-pass review
+
+- Lease-acquisition tenure events: `onLeaseAcquired` is called once at engine
+  construction (and `handoffInProgress` is unwired); per-acquisition tenure
+  bumps + the §3.5 ordered-handoff enqueue gate are pre-promotion work, bounded
+  meanwhile by the cross-boot clamp (`boot_session_id`) and the now-wired REAL
+  `holdsLease` gate (a non-holder takes no custody at all, which closes the
+  §2.2 exposure the reviewer named). <!-- tracked: CMT-1118 (rollout-criteria: dark→dev-dry-run gate; must land before dev-live promotion) -->
+
+## Second-pass review
+
+---
+
+**Independent second-pass review (reviewer subagent, 2026-06-12):**
+
+Verified against the implementation before raising concerns: MUST 1/3/4/6/7/9/10/11/12 are real — the conditional receipt is one transaction gated on the row still being `claimed` (`src/core/PendingInboundStore.ts`), the drain tail commits the receipt before the PIS record/inject and re-checks stop after it (`src/commands/server.ts` drain tail), the six config-seam invariants are checked at construction and a violation keeps the queue OFF with one loud error per inequality + an attention item, and the boot sweep runs on the unconditional path before `recoverPendingInjects`. The Q1/Q4 fail-open directions are real in code: storage throw → `refused`, null engine → `'refused'`, point-read error → fall-through. Dark-ship holds: all three consumption-site edits are inside the `_sessionRouter && _sessionPoolStage() !== 'dark'` block and additionally null-guarded on `_inboundQueue`; with the default config the engine is never constructed, `/pool/queue` 503s, and the only OFF-state delta is the named boot sweep (a no-op when no store file exists). `sender-rejected` is a registry re-check (existing authority), consulted only when an envelope is present; the hold verdict is a deterministic policy over enumerated inputs — no new brittle blocking authority. Backup exclusion, dev-gate registration, guard manifest, ConfigDefaults, migrator, and the test files all exist as claimed.
+
+**Concern raised: the `no-mesh-identity` gate reason is never produced — a fully-enabled queue on a machine without mesh identity strands custody silently.** [...] produce the named gate-expiry (or fold the identity check into the sweep's gate) before live promotion.
+
+**Concern raised: the dry-run rollout stage is structurally invisible — its evidence path is dead code.** [...] Either construct the engine in dry-run mode (it never claims custody by design) or name this in "Known deliberate simplifications".
+
+**Concern raised: the lease gate is hardwired open and this simplification is not named.** [...] before live promotion either wire the real serving-lease signal (it exists — `leaseCoordinatorRef`) or add this to "Known deliberate simplifications".
+
+**Concern raised (minor, latent): MUST 2's no-throw-after-commit is convention, not structure, at the engine layer.** [...] scoping the try to the `store.enqueue` call alone would make the invariant structural. No code change demanded for this dark ship; fix opportunistically.
+
+Disposition: the dark-ship contract, fail-open directions, custody/receipt core, and signal-vs-authority compliance all check out in code. The four concerns are pre-promotion obligations (1–3) and a hardening note (4), not dark-deploy blockers.
+
+**Author response (iterated per Phase 5, same session):** all four concerns ADDRESSED in code before commit —
+1. no-mesh-identity: a one-shot 90s orphan-store backstop at the sweep site gate-expires + loss-reports custody whenever the swept store is never adopted by an engine (covers identity-missing AND construction-throw paths) — `server.ts` sweep block.
+2. dry-run visibility: the engine now constructs in dry-run too (`qcfg.enabled` alone gates construction); the §2.4 counters accumulate and `/pool/queue` serves them — the promotion evidence is live.
+3. lease gate: `holdsLease` wired to `leaseCoordinatorRef.holdsLease()` (single-machine no-coordinator defaults true); the remaining per-acquisition tenure-event wiring is the named tracked simplification above.
+4. MUST 2: the refusal-mapping try now covers ONLY the store commit; post-commit bookkeeping throws are logged and can no longer convert a committed enqueue into `refused`.
+
+**Post-merge addendum (same session):** marked the queue's three defensive
+catches with the in-brace `@silent-fallback-ok` convention (Eternal-Sentinel
+episode latch; loud-log quarantine failure; normal no-quarantine-dir case) —
+no behavior change; restores no-silent-fallbacks headroom after main moved.

package/upgrades/side-effects/reap-notify-resume-queue.md

@@ -0,0 +1,89 @@
+# Side-Effects Review — Per-Topic Reap Notification + Mid-Work Resume Queue
+
+**Version / slug:** `reap-notify-resume-queue`
+**Date:** `2026-06-12`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `[pending — required: session lifecycle + sentinel surface]`
+
+> STATUS: IN-FLIGHT — this artifact accompanies the per-step commits of the
+> build and is completed (all seven questions answered, second-pass appended)
+> before the PR opens. Driven by the converged + approved spec
+> `docs/specs/reap-notify-per-topic-and-midwork-resume-queue.md` (r7).
+
+## Summary of the change
+
+Implements the reap-notify + resume-queue spec: Part A makes every non-silent
+session reap produce a durable per-topic notice (PendingRelayStore rows with a
+`reap-notify:` PK prefix, drained by a new always-on ReapNoticeDrain; the
+store's restore-purge gains the R1.6 held-row exemption + 7-day corruption
+clamp), and Part B tags mid-work reaps with killer-supplied evidence at the
+terminateSession chokepoint and revives them in order via a durable
+ResumeQueue + gated ResumeQueueDrainer (observe-only Tier 1 LLM check during
+soak). Files: src/messaging/{pending-relay-store,reap-notice-delivery-id}.ts,
+src/monitoring/{delivery-failure-sentinel,ReapNotifier,ReapNoticeDrain,ReapLog,
+ResumeQueue,ResumeQueueDrainer,PressureGauge,SessionMigrator,SessionReaper}.ts,
+src/core/SessionManager.ts, server wiring + routes, ConfigDefaults,
+PostUpdateMigrator, templates, three test tiers.
+
+## Decision-point inventory
+
+- `PendingRelayStore.purgeStaleClaimable` — modify — restore-purge staleness predicate (R1.6); brittle by design (transport-layer mechanics, not judgment).
+- `PendingRelayStore claim queries (selectClaimable / selectClaimableReapNotices / claimCas)` — modify/add — origin-scoped single-owner contract between two drains; transport-layer mechanics.
+- `ReapNotifier flush` — modify — per-topic grouping + release-tier selection (IMMEDIATE vs SUMMARY vs quiet-hours); deterministic template authoring, no judgment blocking.
+- `ReapNoticeDrain` — add — tier0 deterministic delivery state machine (claim → send → backoff → terminal escalation).
+- `terminateSession evidence clamp` — modify — enum whitelist on killer-supplied evidence (hard-invariant validation, brittle-blocker exemption).
+- `ResumeQueue eligibility classifier` — add — deterministic eligibility rules (strong/weak evidence, job opt-in).
+- `ResumeQueueDrainer gates` — add — deterministic spawn-eligibility checks delegating to EXISTING authorities (PressureGauge, QuotaManager.canSpawnSession, session cap, migration-in-flight); plus observe-only Tier 1 LLM check.
+- `Dequeue hard invariants` — add — UUID/enum/charset/length clamps protecting `claude --resume` argv (brittle-blocker exemption).
+- `Emergency-stop → queue pause` — add — pass-through consumer of the existing MessageSentinel/stop-all authority.
+
+---
+
+## 1. Over-block
+
+[IN-FLIGHT — completed at Phase 4 after build.]
+
+## 2. Under-block
+
+[IN-FLIGHT — completed at Phase 4 after build.]
+
+## 3. Level-of-abstraction fit
+
+[IN-FLIGHT — completed at Phase 4 after build.]
+
+## 4. Signal vs authority compliance
+
+[IN-FLIGHT — completed at Phase 4 after build. Phase 1 written check recorded
+in build plan: no new brittle judgment blockers; drainer gates delegate to
+existing authorities; Tier 1 check observe-only; hard invariants under the
+documented exemption.]
+
+## 5. Interactions
+
+[IN-FLIGHT — completed at Phase 4 after build.]
+
+## 6. External surfaces
+
+[IN-FLIGHT — completed at Phase 4 after build.]
+
+## 7. Rollback cost
+
+[IN-FLIGHT — completed at Phase 4 after build. Levers: reapNotify.perTopic=false,
+reapNotify.drainEnabled=false, resumeQueue.enabled=false / dryRun=true; no DDL.]
+
+## Build progress notes (per-step, folded into the final review)
+
+- Step 1 (relay-store foundation): R1.6 purge fix + origin scoping + CAS claim; DFS spec §3h updated.
+- Step 2 (ReapLog): notify record pairs + midWork/workEvidence through the normalizer; fixed pre-existing launchLane drop-on-read (Rule-1 deviation, noted for SUMMARY).
+- Step 3 (evidence chokepoint): WorkEvidence vocabulary module + terminateSession opts.workEvidence with enum clamp + ReapGuard.workEvidence() observe-only fallback (closure-error → nothing; critical-tier marker) + midWork stamped on event/reap-log/session record.
+- Step 4 (killer stamps): SessionMigrator pre-grace evidence snapshot + halt-refusal recording (refusals ≠ halted, no double-respawn); SessionReaper asserts authoritative-empty evidence on proven-idle reaps; chokepoint fallback excludes active-process under bypassActiveProcessKeep.
+- Step 5 (ReapNotifier v2): per-topic grouping with separate affected-set (cap 500 + overflow), plain-English reason map, IMMEDIATE/SUMMARY release tiers with quiet-hours holds + per-flush cap, durable enqueue with outcome records, loud enqueue-failure fallback, legacy modes preserved (perTopic:false byte-compatible; drainEnabled:false direct-send).
+- Step 6 (ReapNoticeDrain): always-on 30s drain over the reap-notify lane (CAS claim, lease + prior-boot reclaim, per-pass cap 15, backoff to maxAttempts 8, terminal escalation into ONE stable-id attention item, bounded terminal-row cleanup [Rule-2 deviation: added because DFS's retention pass is default-OFF, so the always-on lane needed its own growth bound]); boot wiring with lazy telegram refs; NotificationBatcher gains quietHoursEndAt/nextSummaryReleaseAt (one quiet-hours clock).
+- Step 7 (PressureGauge): the spec's "shared PressureGauge extraction" already exists as HostPressureSampler (one shared definition delegating to SessionReaper.computePressure, parity-tested in host-pressure-sampler.test.ts) — plan deviation Rule 4: reused instead of duplicating. Wired sessionManager.setPressureTierProvider to it with the reaper's configured thresholds.
+- Step 8 (ResumeQueue): durable JSON queue (fsync discipline temp→rename→dir), single-writer lockfile (same-host stale reclaim; foreign-host NEVER probed — loud disable with documented recovery), R2.2 eligibility classifier, stable-key dedupe, resurrection ledger with 24h window + requeue-as-the-one-override, incident-age TTL with pause-freeze + pressure-starved marker, overflow drop-to-aggregate, corrupt-file sidecar, boot reconciliation (starting→failed-attempt + reap-log re-enqueue seam). Dry-run interpretation recorded: entries ARE durably enqueued (soak observable); only spawning + user-facing claims are gated.
+
+- Step 9 (ResumeQueueDrainer + spawn cwd): gated one-per-tick drainer (calm-ticks on the shared gauge, quota/cap/migration gates never bypassable, manual drain skips calm-ticks ONLY), 7 reality validations + hard invariants (fail-safe on dep errors), failure ladder + breaker + aggregated give-ups, Tier1 observe-only with 5s deadline + off-lever, dry-run inertness (would-resume once per entry, no attention), R2.11 honest notice + literal-data continuation prompt; spawnInteractiveSession + spawnSessionForTopic gain the explicit per-spawn cwd (L13 named extension).
+- Step 10 (boot wiring + emergency stop + routes): queue+drainer constructed at boot (lock-disable logged, lazy telegram refs, 30s-deferred reap-log boot reconciliation — topic-bound candidates only; job entries rely on cron recurrence since opt-in is not reconstructible from the reap-log); enqueue hook at the sessionReaped listener; emergency-stop wiring (stop-all → pause; per-topic stop + MessageSentinel stop → cancelByTopic + operator-stop record); R2.10 routes with clamps; QuotaManager.isMigrationInFlight added (canSpawnSession permits mid-migration spawns absent pressure — the drainer needs the stricter probe); Session.cwd recorded at spawn; JobDefinition.resumeOnReap; Tier1 check wired via shared LlmQueue with attribution.
+- Step 11 (config + migration parity): ConfigDefaults gains reapNotify.perTopic + maxImmediatePerFlush ONLY (drainEnabled + resumeQueue.* deliberately code-defaulted for the fleet flip — registration-discipline test pins this); resumeQueue classified in DARK_GATE_EXCLUSIONS (cost-bearing); resume-queue state files registered machine-local in the state-coherence registry; generateClaudeMd Reap-Log section updated + NEW content-sniffed migrateClaudeMd section + framework-shadow marker; release fragment with maturity-tagged announcements (Part A stable, Part B preview/watch-mode).
+- Step 12 (test tier): integration lifecycle (reap → durable notify pair, quota-shed end-to-end, P17/P19 burst invariants incl. K-entries-vs-rejecting-spawn-target) + R2.10 routes/emergency-stop integration + Tier-3 feature-alive E2E on the production init path (real AgentServer + ReapLog + PendingRelayStore + ReapNotifier + ReapNoticeDrain + ResumeQueue + ResumeQueueDrainer; cwd round-trip through the L13 spawn-path parameter; wiring integrity for pressure gauge / spawn gate / relay store / LlmQueue tier-1).
+- Step 13 (full-suite triage): ratchet/parity updates for the new code (dark-gate golden map +10 shift re-verified by hand; ResumeQueueDrainer registered in componentCategories; migrator CLAUDE.md section tracked in feature-delivery-completeness; session-reaper exact-match assertions gain workEvidence). Behavior-relevant: THREE lenient-side catches REMOVED so a throwing dep resolves to the drainer's strict side per R2.6 — QuotaManager.isMigrationInFlight no longer swallows probe errors (sole caller is the drainer gate, which blocks on throw), and the server's migrationInFlight/topicOwnerElsewhere dep wrappers no longer catch (drainer gate/validateReality resolve to blocked/invalidated). Every remaining new catch carries an in-brace @silent-fallback-ok justification; no-silent-fallbacks baseline untouched (net −1 vs main). localhost-link-guard-route test made hermetic (own tmp stateDir — '/tmp' shared outbound-dedup.db across runs and suppressed sends).