instar 1.3.62 → 1.3.63

package/upgrades/1.3.62.md

@@ -4,6 +4,8 @@
 
 ## What Changed
 
+### ContextWedgeSentinel — detect + (optionally) recover the thinking-block-400 wedge
+
 **A new way sessions die is now detected and (optionally) auto-recovered.** When
 a tool call is cancelled inside a *parallel* tool batch while extended thinking
 is on, Claude Code corrupts the thinking block on the latest assistant turn —
@@ -33,57 +35,53 @@ and rides the Graduated Feature Rollout track. The sentinel also feeds the
 SessionReaper kill-veto so the reaper never reaps a session mid-recovery. New
 config kill switch `monitoring.contextWedgeSentinel.enabled` (default true).
 
+### Unified session-lifecycle robustness — Phase 1 (ReapAuthority + reap-log + backstop)
+
+Phase 1 of **unified session-lifecycle robustness** (spec `docs/specs/unified-session-lifecycle-robustness.md`, converged + approved). The trigger was a real incident: at a busy server boot the startup "cleanup crew" treated a slow-to-answer tmux session as *dead* and wiped 9 of 9 live sessions — silently. The audit that followed found eight different code paths that can end a session, each re-inventing "alive or dead?" its own way, several of them able to mistake slow/busy for dead and none of them telling the user. This release builds the single authority + safety backbone that the rest of the killers will move onto.
+
+What landed:
+
+- **One authority, not eight.** `terminateSession()` is now the sole kill chokepoint. Every autonomous shutoff routes through it and can only *request* a kill — the authority holds the safety checks: a compare-and-set live-status guard, the `protected` set, an **awake-machine-only lease gate** (a standby never reaps another machine's sessions), and a mandatory **KEEP-guard** consult (the same positive-evidence checks the careful SessionReaper uses — relay-lease, pending-injection, recent-user-message, active subagent/process, etc.). An explicit **operator** kill (stamped only by the Bearer-authed HTTP route) bypasses those gates so a human "kill" always happens. The first three killers — boot purge, the age/5-hour cutoff, and the idle-zombie killer — are funneled through it.
+- **A reap is never silent.** A new coalescing notifier surfaces "your session was shut down — <reason>" so a session can't just vanish. Routine kill-to-respawn bounces and your own operator kills stay quiet; a burst collapses into ONE consolidated message instead of spamming. Default **on** (`monitoring.reapNotify`).
+- **A reap-log you can read.** Every shutoff *and* every refused/skipped shutoff (protected / not-lease-holder / a KEEP-hold / in-flight) is recorded as one JSON line, served read-only at `GET /sessions/reap-log`. "Where did my session go?" now always has an answer.
+- **Nothing is unconditionally immortal — and nothing can lock you out.** A signal-only backstop watches for a session that fakes work (heartbeat-byte / tight-loop) or is stuck unverifiable, and after a threshold raises ONE deduped Attention item asking *you* to decide — it never auto-kills. Long-unverifiable sessions are excluded from the absolute spawn cap so a fleet of stuck panes can't lock you out of starting new work.
+
+All changes are additive and only make killing *more* conservative; the boot-purge fix already turns the original 9-of-9 wipe into 0 false kills. Phase 2 (watchdog / orphan / recovery / wake-reaper onto the authority) and Phase 3 (quota soft-check + session-label-follows-rename) follow.
+
 ## What to Tell Your User
 
 - I can now spot a specific way a session silently dies — it gets stuck on a
   "can't modify the thinking block" error and fails instantly on every message
   while still looking busy — which used to leave you seeing only standby replies.
-- By default I just notice it and log it (nothing is killed). You can opt in to
-  having me automatically restart a stuck session cleanly; when that's on I throw
-  away the corrupted conversation and start fresh so it can't get re-stuck.
-- Nothing you see changes by default. If you ever want the auto-restart on, it's
-  one config switch, and it's on a track that will nag toward on-by-default once
-  it's proven itself.
+  By default I just notice and log it; you can opt in to having me restart a
+  stuck session cleanly (I throw away the corrupted conversation so it can't get
+  re-stuck).
+- Your sessions also won't silently disappear anymore. The startup cleanup no
+  longer mistakes a slow-to-answer session for a dead one, and if anything does
+  get shut down you get told why — with a reap-log page recording every shutoff
+  and every refused shutoff.
+- Every automatic cleanup now goes through one careful gatekeeper that refuses to
+  end a session that might be working, and only the "awake" machine ever reaps.
+  When you kill a session it still happens immediately.
+- Nothing can get wedged-but-immortal or quietly fill your slots: instead of ever
+  auto-killing a stuck session, the agent raises a single "this looks stuck —
+  investigate or force-kill?" item for you.
 
-## Evidence
+## Summary of New Capabilities
 
-**Reproduction (live, 2026-05-28).** The `echo-instar-exo` session (topic 13481,
-the `mm-proof-build` worktree) fired a parallel Bash batch; one call
-(`rm -rf …/echo…`) was blocked by the source-tree guard, which cancelled the
-whole batch. With extended thinking on, that corrupted the latest assistant
-turn's thinking block.
-
-**Observed before.** Every subsequent inbound Telegram message produced, in the
-tmux pane, an instant:
-```
-⎿  API Error: 400 messages.9.content.20: `thinking` or `redacted_thinking` blocks
-   in the latest assistant message cannot be modified.
-✻ Cooked for 0s
-```
-The user sent "How is this looking?" twice over ~30 minutes and received only
-sentinel/standby replies — the session was a corpse, and the silence + socket
-sentinels never fired (output never went quiet; no disconnect string).
-
-**Observed after.** With ContextWedgeSentinel: the wedge is detected as the live
-tail and written to `logs/sentinel-events.jsonl` (`kind:detected` →
-`kind:escalated` in detect-only mode, or `kind:recovered` when autoRecovery is
-on). The e2e test (`tests/e2e/context-wedge-sentinel-lifecycle.test.ts`) drives
-the production assembly and reads those exact rows back from disk; the live
-recovery clears the topic's resume UUID so the respawn starts fresh (verified by
-`SessionRefresh.test.ts` asserting the kill→clear→respawn order). The original
-wedged session was recovered manually by killing it (the next message spawned
-clean), confirming the fresh-respawn approach before it was automated.
+| Capability | How to Use |
+|-----------|-----------|
+| ContextWedgeSentinel (thinking-block-400 detection) | Automatic + default-on housekeeping; audits to `logs/sentinel-events.jsonl` |
+| Opt-in wedge auto-recovery | `{"monitoring": {"contextWedgeSentinel": {"autoRecovery": {"enabled": true, "dryRun": false}}}}` (Graduated Rollout track) |
+| SessionRefresh `fresh` mode | Internal — kill + respawn that clears the topic's resume UUID (no re-wedge loop) |
+| Single ReapAuthority (all autonomous kills funnel through `terminateSession`) | Automatic — boot-purge, age-kill, and idle-zombie now route through it with the KEEP-guard + lease gate |
+| Reap notice ("your session was shut down — <reason>") | On by default; silence it with `{"monitoring": {"reapNotify": {"enabled": false}}}` |
+| Reap-log | `curl -H "Authorization: Bearer $AUTH" "http://localhost:4040/sessions/reap-log?limit=50"` (read-only) |
+| Unkillability backstop (escalate, never auto-kill) | Automatic + signal-only; tune via `monitoring.staleBackstop` |
+| Spawn-cap exclusion for long-unverifiable sessions | Automatic — they no longer count toward the absolute `maxSessions × 3` cap |
 
-## Summary of New Capabilities
+## Evidence
+
+**ContextWedgeSentinel.** Reproduced live 2026-05-28: a parallel Bash batch with one guard-blocked call corrupted the latest assistant thinking block; every subsequent message fast-failed with the `400 … cannot be modified` error while the silence + socket sentinels stayed quiet. After: the wedge is detected as the live tail and written to `logs/sentinel-events.jsonl`; the e2e test drives the production assembly and reads those rows back; the live recovery clears the topic's resume UUID so the respawn starts fresh.
 
-- **ContextWedgeSentinel** — detects the thinking-block-400 fast-fail wedge as a
-  non-progressing session tail (45s confirm window); audits every transition to
-  `logs/sentinel-events.jsonl`.
-- **SessionRefresh `fresh` mode** — kill + respawn that clears the topic's resume
-  UUID, so recovery never reloads a corrupted transcript (no re-wedge loop).
-- **Opt-in auto-recovery** — `monitoring.contextWedgeSentinel.autoRecovery`
-  (default off + dry-run), on the Graduated Feature Rollout track; promotion to
-  default-on propagates fleet-wide on update with no migration.
-- Escalation (when a confirmed wedge isn't auto-recovered) routes through the
-  existing tone-gated SentinelNotifier, gated by `sentinelTelegramEscalation`
-  (default off, coalesced).
+**Session-lifecycle Phase 1.** 123 unit + 10 integration + 3 e2e green: ReapGuard (15), ReapNotifier (10), ReapLog (6), StaleSessionBackstop (10), terminate-CAS (9), liveness-oracle (15), boot-purge death-spiral reproduction (the 2026-05-27 9-of-9 incident → 0 false purges), reap-log route (integration + e2e "feature is alive" 200-not-503), and a full event-path integration (autonomous reap → log + one notice; recovery-bounce/operator silent; relay-lease/standby/protected refused-and-survive). `tsc --noEmit` clean. Migration parity: `reapNotify` + `staleBackstop` defaults flow to existing agents via ConfigDefaults; the reap-log Agent-Awareness section ships in both the CLAUDE.md template and `migrateClaudeMd`. Spec converged over 3 code-grounded review rounds (`docs/specs/reports/unified-session-lifecycle-robustness-convergence.md`); side-effects review: `upgrades/side-effects/unified-session-lifecycle-robustness.md`. Honest scope note: the boot-purge false-purge and the notice/log/survival paths are reproduced at the unit + real-event-path + real-AgentServer tiers; a live "boot a server, slow tmux, watch a Telegram notice land" pass was not performed in this environment.

package/upgrades/1.3.63.md

@@ -0,0 +1,87 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+### ContextWedgeSentinel — detect + (optionally) recover the thinking-block-400 wedge
+
+**A new way sessions die is now detected and (optionally) auto-recovered.** When
+a tool call is cancelled inside a *parallel* tool batch while extended thinking
+is on, Claude Code corrupts the thinking block on the latest assistant turn —
+and from then on the Anthropic API rejects every resume with
+`400 … thinking blocks in the latest assistant message cannot be modified`. The
+session fast-fails instantly on every message ("Cooked for 0s"): permanently
+dead, yet still emitting output. Because it's not *silent* and hasn't lost its
+socket, neither the ActiveWorkSilenceSentinel nor the SocketDisconnectSentinel
+catches it — the user just sees standby/sentinel replies forever while the real
+session is a corpse. (Live incident: a session on a real topic fast-failed every
+"How is this looking?" for ~30 minutes.)
+
+The new **ContextWedgeSentinel** (a 4th member of the silently-stopped family)
+recognizes this exact wedge: it matches the error as the *live session tail* and
+waits a 45s confirm window so a session merely *discussing* the bug is never
+flagged. A gentle nudge can't fix this one (re-engaging re-sends the corrupted
+turn), so recovery is a **fresh respawn** — kill the session and clear the
+topic's saved resume UUID so the bridge spawns a brand-new conversation instead
+of `--resume`-ing the corrupted transcript (which would just re-wedge on the
+next message — the central correctness property). This reuses the existing
+rate-guarded `SessionRefresh` via a new `fresh` mode.
+
+Detection + audit are **default-ON housekeeping** (they write to
+`logs/sentinel-events.jsonl` and kill nothing). The destructive auto-respawn is
+**opt-in** (`monitoring.contextWedgeSentinel.autoRecovery`, default off + dry-run)
+and rides the Graduated Feature Rollout track. The sentinel also feeds the
+SessionReaper kill-veto so the reaper never reaps a session mid-recovery. New
+config kill switch `monitoring.contextWedgeSentinel.enabled` (default true).
+
+### Unified session-lifecycle robustness — Phase 1 (ReapAuthority + reap-log + backstop)
+
+Phase 1 of **unified session-lifecycle robustness** (spec `docs/specs/unified-session-lifecycle-robustness.md`, converged + approved). The trigger was a real incident: at a busy server boot the startup "cleanup crew" treated a slow-to-answer tmux session as *dead* and wiped 9 of 9 live sessions — silently. The audit that followed found eight different code paths that can end a session, each re-inventing "alive or dead?" its own way, several of them able to mistake slow/busy for dead and none of them telling the user. This release builds the single authority + safety backbone that the rest of the killers will move onto.
+
+What landed:
+
+- **One authority, not eight.** `terminateSession()` is now the sole kill chokepoint. Every autonomous shutoff routes through it and can only *request* a kill — the authority holds the safety checks: a compare-and-set live-status guard, the `protected` set, an **awake-machine-only lease gate** (a standby never reaps another machine's sessions), and a mandatory **KEEP-guard** consult (the same positive-evidence checks the careful SessionReaper uses — relay-lease, pending-injection, recent-user-message, active subagent/process, etc.). An explicit **operator** kill (stamped only by the Bearer-authed HTTP route) bypasses those gates so a human "kill" always happens. The first three killers — boot purge, the age/5-hour cutoff, and the idle-zombie killer — are funneled through it.
+- **A reap is never silent.** A new coalescing notifier surfaces "your session was shut down — <reason>" so a session can't just vanish. Routine kill-to-respawn bounces and your own operator kills stay quiet; a burst collapses into ONE consolidated message instead of spamming. Default **on** (`monitoring.reapNotify`).
+- **A reap-log you can read.** Every shutoff *and* every refused/skipped shutoff (protected / not-lease-holder / a KEEP-hold / in-flight) is recorded as one JSON line, served read-only at `GET /sessions/reap-log`. "Where did my session go?" now always has an answer.
+- **Nothing is unconditionally immortal — and nothing can lock you out.** A signal-only backstop watches for a session that fakes work (heartbeat-byte / tight-loop) or is stuck unverifiable, and after a threshold raises ONE deduped Attention item asking *you* to decide — it never auto-kills. Long-unverifiable sessions are excluded from the absolute spawn cap so a fleet of stuck panes can't lock you out of starting new work.
+
+All changes are additive and only make killing *more* conservative; the boot-purge fix already turns the original 9-of-9 wipe into 0 false kills. Phase 2 (watchdog / orphan / recovery / wake-reaper onto the authority) and Phase 3 (quota soft-check + session-label-follows-rename) follow.
+
+## What to Tell Your User
+
+- I can now spot a specific way a session silently dies — it gets stuck on a
+  "can't modify the thinking block" error and fails instantly on every message
+  while still looking busy — which used to leave you seeing only standby replies.
+  By default I just notice and log it; you can opt in to having me restart a
+  stuck session cleanly (I throw away the corrupted conversation so it can't get
+  re-stuck).
+- Your sessions also won't silently disappear anymore. The startup cleanup no
+  longer mistakes a slow-to-answer session for a dead one, and if anything does
+  get shut down you get told why — with a reap-log page recording every shutoff
+  and every refused shutoff.
+- Every automatic cleanup now goes through one careful gatekeeper that refuses to
+  end a session that might be working, and only the "awake" machine ever reaps.
+  When you kill a session it still happens immediately.
+- Nothing can get wedged-but-immortal or quietly fill your slots: instead of ever
+  auto-killing a stuck session, the agent raises a single "this looks stuck —
+  investigate or force-kill?" item for you.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| ContextWedgeSentinel (thinking-block-400 detection) | Automatic + default-on housekeeping; audits to `logs/sentinel-events.jsonl` |
+| Opt-in wedge auto-recovery | `{"monitoring": {"contextWedgeSentinel": {"autoRecovery": {"enabled": true, "dryRun": false}}}}` (Graduated Rollout track) |
+| SessionRefresh `fresh` mode | Internal — kill + respawn that clears the topic's resume UUID (no re-wedge loop) |
+| Single ReapAuthority (all autonomous kills funnel through `terminateSession`) | Automatic — boot-purge, age-kill, and idle-zombie now route through it with the KEEP-guard + lease gate |
+| Reap notice ("your session was shut down — <reason>") | On by default; silence it with `{"monitoring": {"reapNotify": {"enabled": false}}}` |
+| Reap-log | `curl -H "Authorization: Bearer $AUTH" "http://localhost:4040/sessions/reap-log?limit=50"` (read-only) |
+| Unkillability backstop (escalate, never auto-kill) | Automatic + signal-only; tune via `monitoring.staleBackstop` |
+| Spawn-cap exclusion for long-unverifiable sessions | Automatic — they no longer count toward the absolute `maxSessions × 3` cap |
+
+## Evidence
+
+**ContextWedgeSentinel.** Reproduced live 2026-05-28: a parallel Bash batch with one guard-blocked call corrupted the latest assistant thinking block; every subsequent message fast-failed with the `400 … cannot be modified` error while the silence + socket sentinels stayed quiet. After: the wedge is detected as the live tail and written to `logs/sentinel-events.jsonl`; the e2e test drives the production assembly and reads those rows back; the live recovery clears the topic's resume UUID so the respawn starts fresh.
+
+**Session-lifecycle Phase 1.** 123 unit + 10 integration + 3 e2e green: ReapGuard (15), ReapNotifier (10), ReapLog (6), StaleSessionBackstop (10), terminate-CAS (9), liveness-oracle (15), boot-purge death-spiral reproduction (the 2026-05-27 9-of-9 incident → 0 false purges), reap-log route (integration + e2e "feature is alive" 200-not-503), and a full event-path integration (autonomous reap → log + one notice; recovery-bounce/operator silent; relay-lease/standby/protected refused-and-survive). `tsc --noEmit` clean. Migration parity: `reapNotify` + `staleBackstop` defaults flow to existing agents via ConfigDefaults; the reap-log Agent-Awareness section ships in both the CLAUDE.md template and `migrateClaudeMd`. Spec converged over 3 code-grounded review rounds (`docs/specs/reports/unified-session-lifecycle-robustness-convergence.md`); side-effects review: `upgrades/side-effects/unified-session-lifecycle-robustness.md`. Honest scope note: the boot-purge false-purge and the notice/log/survival paths are reproduced at the unit + real-event-path + real-AgentServer tiers; a live "boot a server, slow tmux, watch a Telegram notice land" pass was not performed in this environment.

package/upgrades/side-effects/unified-session-lifecycle-robustness.md

@@ -0,0 +1,241 @@
+# Side-Effects Review — Unified Session-Lifecycle Robustness (implementation)
+
+Spec: `docs/specs/unified-session-lifecycle-robustness.md` (converged 3 iterations, approved by Justin
+topic 2169). Full adversarial/standards review in
+`docs/specs/reports/unified-session-lifecycle-robustness-convergence.md`. This artifact tracks the
+side-effects of the *implementation* commits as they land.
+
+## Commit 1 — P1 SessionLivenessOracle + boot-purge fix
+
+**Files:**
+- `src/core/SessionLivenessOracle.ts` (new) — tri-state liveness oracle.
+- `src/core/SessionManager.ts` — lazy oracle field + `setLivenessOracle()` DI seam; `purgeDeadSessions()`
+  rewired to use the oracle (purge only on `dead`, keep on `indeterminate`/`alive`).
+- `src/core/types.ts` — added optional `liveness?: Partial<SessionLivenessOracleConfig>` to
+  `SessionManagerConfig`.
+- `tests/unit/session-liveness-oracle.test.ts` (new, 15 tests) — incident fix (timeout→indeterminate),
+  exact-id match, cache, retry, boot-cap, coalescing, config floors.
+- `tests/unit/death-spiral-fixes.test.ts` — purge suite rewritten to oracle semantics + the 2026-05-27
+  incident reproduction (timing-out tmux at boot → 0 purges).
+
+**What changes behaviorally:** the boot purge no longer treats a slow/timing-out/unreachable
+`tmux` probe as "dead." It resolves liveness from a single `tmux list-sessions` and purges ONLY when
+the server is reachable AND the exact session id is absent. A timeout/unreachable result is
+`indeterminate` → the session is KEPT and re-verified on the next monitoring tick.
+
+**Over-block risk (a live session wrongly purged):** eliminated for the timeout case — the root cause
+of the incident. Residual: a name-collision could in theory hide a live session, but matching is
+exact-full-id against `list-sessions` output, not prefix/substring.
+
+**Under-block risk (a dead session lingers):** bounded — a genuinely dead session absent from a
+reachable `list-sessions` is still purged immediately. Only the *unverifiable* case lingers, and only
+until the next tick (cheap). The §P5 backstop (later commit) escalates a permanently-unverifiable
+session to the Attention queue so it can never leak forever or fill the spawn cap.
+
+**Death-spiral (the original purge's reason for existing):** preserved and improved. The oracle is
+async (never `execFileSync` on boot), resolves the whole set from ONE `list-sessions`, retries once
+with backoff, and is bounded by a total boot-cap (default 8s) — on cap it returns `indeterminate`
+rather than blocking boot. So conservatism does not re-introduce startup-blocking latency.
+
+**Signal vs authority:** the oracle is pure-data (tier0) — it only *reports* alive/dead/indeterminate;
+it never kills. The kill decision stays with `terminateSession()` (the authority, wired in a later
+commit). No new kill authority is introduced here.
+
+**Migration parity:** the oracle is server-side TS (ships with the server, no migrator needed). The new
+`liveness` config block is optional (`Partial`), defaults applied in-code via `DEFAULT_LIVENESS_CONFIG`;
+a `migrateConfig` entry + startup validation (`validateLivenessConfig`, rejects a sub-floor timeout)
+land with the config-wiring commit.
+
+**Rollback:** additive. Reverting the `purgeDeadSessions` change restores the old behavior; the new
+module is unreferenced if the field/getter are removed. The DI seam (`setLivenessOracle`) is test-only
+surface with no production caller.
+
+**Tests:** 15 (oracle) + 14 (purge/death-spiral) green; typecheck clean. Reproduce-before-claim for
+the live boot scenario is owed before declaring the incident fixed end-to-end (E2E tier, later commit).
+
+## Commit 2 — P2 ReapGuard (stateless KEEP-guards extracted from SessionReaper)
+
+**Files:**
+- `src/core/ReapGuard.ts` (new) — `reapBlockedReason(session)` over the stateless guards: protected,
+  spawn-grace (parameterized minAgeMs), recovery-in-flight, pending-injection, relay-lease,
+  recent-user-message, open-commitment, active-subagent, structural-long-work, active-process,
+  main-process-uninspectable/active. Cheap-first ordering; safe-by-default (a throwing signal →
+  KEEP 'guard-error', never reap).
+- `src/monitoring/SessionReaper.ts` — `evaluate()` now calls the shared guard first, then layers its
+  STATEFUL checks (transcript-growth via per-instance `obs`, positive-idle via captured frame). Guard
+  built in the constructor from the reaper's deps + cfg.
+- `tests/unit/reap-guard.test.ts` (new, 15 tests) — both sides of every guard, cannot-inspect→KEEP,
+  cheap-first ordering, throwing-signal→KEEP.
+- `tests/unit/session-reaper.test.ts` — one label assertion updated ('eval-error'→'guard-error') for
+  the throwing-stateless-signal case; the KEEP-never-reap behavior is unchanged and still asserted.
+
+**Parity:** SessionReaper's 30 existing tests all pass post-extraction — the `keptBy` reasons are
+identical for every extracted guard (the spec's required wiring/parity check). Only the diagnostic
+label for a *throwing* stateless signal moved (the guard now catches it as 'guard-error' rather than
+letting it propagate to the reaper's outer 'eval-error' catch — a safer default for the shared guard;
+the reaper's outer catch remains live for throws in the stateful checks).
+
+**Behavioral change:** none for the reaper (parity). The guard is not yet consulted by
+`terminateSession` — that wiring is P0 (next commit). So no other killer's behavior changes yet; this
+commit is a pure, parity-verified extraction.
+
+**Signal vs authority:** the guard is a pure predicate (no kill power) — it only *reports* a KEEP
+reason. The authority (terminateSession) decides; wired in P0.
+
+**Rollback:** additive. Reverting restores the inlined guards in `evaluate()`; `ReapGuard.ts` is
+unreferenced if the reaper's guard field + call are removed.
+
+**Tests:** 15 (guard) + 30 (reaper parity) + 4 (wiring) green; typecheck clean.
+
+## Commit — P0 ReapAuthority gates + funnel killers #1/#2/#3
+
+**Files:**
+- `src/core/SessionManager.ts` — `terminateSession` gains `origin`/`disposition`/`knownDead` opts, a
+  lease-holder gate, the mandatory ReapGuard consult, and a single `sessionReaped` emission;
+  `setReapGuard()`/`setAwakeChecker()` DI seams. Killers funneled: #1 boot-purge (`knownDead:true`,
+  lease-gated), #2 age-limit (inline kill → `terminateSession('age-limit')`), #3 idle-zombie (explicit
+  `disposition:'terminal'`).
+- `src/server/routes.ts` — `DELETE /sessions/:id` is now async and routes through
+  `terminateSession(origin:'operator')` instead of the raw `killSession`.
+- `src/commands/server.ts` — shared `reapGuardDeps` back BOTH the SessionReaper and the authority's
+  ReapGuard (built `minAgeMs:0`); `setAwakeChecker` wires the lease gate (single-machine ⇒ always awake).
+
+**Implementation decisions with side-effects (reviewed):**
+1. **Operator kill bypasses `protected`.** The `protected` check moved *inside* the autonomous-only
+   gate block, so an `origin:'operator'` kill is no longer blocked on protected sessions. Risk: an
+   operator can now kill a protected (e.g. lifeline) session via the dashboard. Mitigation/justification:
+   this *preserves* the prior behavior — the old `DELETE` route used `killSession`, which killed
+   unconditionally — and matches the spec's "an explicit human kill must always happen". Autonomous
+   reapers remain fully blocked on protected.
+2. **`knownDead` bypass for boot-purge.** A `dead` verdict skips the KEEP-guard. Risk: a mis-verdict
+   would skip protection. Mitigation: the oracle returns `dead` ONLY on tmux-server-reachable +
+   exact-full-id-absent, never on timeout/unreachable/unknown — so `knownDead` is only ever passed for a
+   provably-gone session, which has no liveness to protect. Without the bypass, the guard's
+   liveness-blind topic-state KEEPs (recent-user-message / open-commitment) would pin a dead record in
+   the running list and re-create the boot death-spiral.
+3. **`DELETE` route now emits `beforeSessionKill`/`sessionComplete`/`sessionReaped`.** The old
+   `killSession` path historically emitted none of these. Effect: resume-UUID listeners now fire on an
+   operator kill (beneficial — a manually-killed topic session can be resumed), and the operator kill
+   lands in the reap-log (P4). No double-emit: `killSession` is no longer on this path.
+
+**Signal vs authority:** unchanged — killers *request*, the authority decides. The only callers that
+may mint `origin:'operator'` are Bearer-authed HTTP routes; in-process killers default to `autonomous`
+and so always pass through the gates.
+
+**Re-entrancy:** the guard is consulted before the in-flight (`terminating`) lock is acquired, so the
+authority never misreads its own lock as a KEEP (spec §P0 ordering).
+
+**Rollback:** additive per killer; reverting restores the inline kills. P0 gates default to the prior
+behavior when `setReapGuard`/`setAwakeChecker` are unset (tests/standalone) — no guard consult, treated
+as awake.
+
+**Tests:** terminate (9) + reaper (30) + guard (15) + oracle (15) + timeout (4+6) + async-monitor (6) +
+lifecycle integration (6) green; typecheck clean. One brittle source-string test updated to the new
+age-kill log + funnel contract.
+
+## Commit — P3 reap-notify seam + P4 reap-log + Agent-Awareness + migration
+
+**Files:**
+- `src/monitoring/ReapNotifier.ts` (new) — single coalescing `sessionReaped` listener. Silent on
+  `recovery-bounce` and `origin:'operator'`; isolated reap → bound topic (or lifeline); burst within
+  the window → ONE consolidated lifeline message stating the EXACT total (count tracked separately from
+  the bounded detail buffer, so an overflow never under-reports). User-controlled names/reasons wrapped
+  as literal inline-code spans (inner backticks neutralized) so the downstream formatter never renders
+  them as markup.
+- `src/monitoring/ReapLog.ts` (new) — append-only JSONL audit at `logs/reap-log.jsonl`; records BOTH
+  reaps (`sessionReaped`) and refused/skipped terminates (`reapBlocked`); JSON-encoded (no concat →
+  no newline injection); read tolerates corrupt lines.
+- `src/server/routes.ts` — `GET /sessions/reap-log` (Bearer-auth via router middleware, read-only,
+  `?limit` capped at 1000, default 200).
+- `src/server/AgentServer.ts` — `reapLog` option + ctx wire (mirrors `sessionReaper`).
+- `src/commands/server.ts` — ReapLog + ReapNotifier built and the `sessionReaped`/`reapBlocked`
+  listeners + `setAwakeChecker` wired BEFORE the boot purge, so boot reaps are lease-gated, logged, and
+  notified. (The KEEP-guard is wired later, after its tracker deps exist — safe: boot-purge bypasses it
+  via `knownDead`, and no monitorTick kill can fire in the first seconds.)
+- `src/core/types.ts` + `src/config/ConfigDefaults.ts` — `monitoring.reapNotify {enabled, coalesceWindowMs}`,
+  default ON.
+- `src/scaffold/templates.ts` (Agent-Awareness) + `src/core/PostUpdateMigrator.migrateClaudeMd` (existing
+  agents get the Reap-Log section) + `migrateConfig` via ConfigDefaults (existing agents get the
+  `reapNotify` default automatically).
+
+**Notify default = ON (deliberate, differs from sentinelTelegramEscalation).** The silently-stopped
+sentinel escalation defaults OFF (post-2026-05-22 flood). The reap-notify defaults ON because the
+incident this whole spec answers is *silent disappearance* — the user explicitly asked to be told. The
+flood risk is bounded by: (a) coalescing a burst into one message, (b) staying silent on the common
+recovery-bounce + operator paths, (c) SUMMARY tier (quiet-hours aware). A single config flag disables it.
+
+**Discoverability:** `/sessions/reap-log` lives under the already-classified `sessions` prefix
+(operator/dashboard-only in CapabilityIndex) — no new prefix, no lint change. Agent-awareness is carried
+by the CLAUDE.md template + migrateClaudeMd instead (the template IS the agent's awareness).
+
+**Ordering side-effect (reviewed):** the listeners attach pre-boot-purge; the guard wires post. The only
+guard consumers besides boot-purge are monitorTick #2/#3, which require multi-hour age / 15+m observed
+idle — unreachable in the sub-second guard-unset window. Documented inline.
+
+**Tests:** ReapNotifier (10: silent dispositions/origins, isolated bound/unbound routing, burst
+coalescing, overflow exact-count, auto-timer, malicious-name literalization, unreachable-channel drop)
++ ReapLog (6: empty, reaped/skipped fields, newline-injection→valid-JSON, tail, corrupt-line tolerance)
+green; typecheck clean. Route integration + e2e land in the test-phase commit.
+
+## Commit — P5 unkillability backstop
+
+**Files:**
+- `src/monitoring/StaleSessionBackstop.ts` (new) — signal-only. Per-tick forward-progress check; after
+  M min of no-forward-progress OR N consecutive indeterminate probes, raises ONE per-episode-deduped
+  Attention item (never auto-kills). Forward progress = meaningful transcript advance (≥floor AND new
+  tail — guards the heartbeat/loop case) OR main-process CPU OR a prompt/idle-state change. A
+  control-plane-unreachable tick raises ONE global item, not one per session.
+- `src/core/SessionManager.ts` — `markLongIndeterminate()` + a `longIndeterminateSessions` set excluded
+  from the ABSOLUTE `maxSessions × 3` spawn cap (so unverifiable panes can't lock out spawning);
+  `probeLivenessBatch()` resolves tri-state liveness + reachability from ONE oracle snapshot.
+- `src/core/types.ts` + `src/config/ConfigDefaults.ts` — `monitoring.staleBackstop`, default ON;
+  propagates to existing agents via ConfigDefaults.
+- `src/commands/server.ts` — backstop wired after the SessionReaper; snapshot built from probeTranscript
+  (+ tail-hash read so a heartbeat byte isn't "progress"), captureOutput frame-hash, hasActiveProcesses;
+  Attention via makeAttentionPoster.
+
+**Never-auto-kills (structural):** the backstop's deps surface has NO terminate/kill function — it
+physically cannot end a session. Asserted by a unit test. It only observes and asks.
+
+**Oracle interaction (reviewed):** with the committed single-snapshot oracle, a session is only
+`indeterminate` when the whole snapshot is non-authoritative (server unreachable). So the per-session
+indeterminate-streak path is currently reached only under global unreachability (handled by the global
+item); the live, reachable path is the M-minute no-forward-progress escalation for ALIVE-but-faking
+sessions. The per-session indeterminate code is kept (defensive — correct if the oracle later adds
+individual re-probes that return indeterminate while reachable).
+
+**Spawn-cap exclusion:** long-indeterminate sessions are removed from the ABSOLUTE-cap count only; they
+still count toward the soft scheduler cap. Cleared the moment a session is verifiable again.
+
+**Tests:** StaleSessionBackstop (10: M-min escalation, no-re-raise-per-episode, heartbeat-not-progress,
+meaningful-advance/CPU/prompt-change progress, per-episode re-raise after recovery, global-unreachable
+dedup, long-indeterminate flag set+cleared, never-kills structural) green; typecheck clean.
+
+## Commit — Phase 1 test tiers (integration + e2e)
+
+**Files:**
+- `tests/integration/reap-log-route.test.ts` (new, 4) — GET /sessions/reap-log through the real
+  createRoutes pipeline: 503-when-unwired, 200 with reaped+skipped entries, ?limit tail, read-only
+  (POST/DELETE → 404).
+- `tests/integration/session-lifecycle-reap-wiring.test.ts` (new, 6) — the real SessionManager
+  terminateSession authority wired (as server.ts does) to ReapGuard + ReapNotifier + ReapLog, asserting
+  through the real emit path: autonomous terminal reap → log + exactly one notice; recovery-bounce →
+  logged-but-silent; operator → logged-silent + bypasses guard+protected; relay-lease KEEP → refused +
+  survives + logged 'skipped'; standby → refused + survives; protected → refused + survives.
+- `tests/e2e/reap-log-lifecycle.test.ts` (new, 3) — boots the REAL AgentServer: GET /sessions/reap-log
+  is alive (200 not 503), surfaces recorded entries, requires Bearer, read-only.
+
+**Reproduce-before-claim status (honest):** the boot-purge false-purge is reproduced at the unit tier
+(death-spiral-fixes — the 2026-05-27 9-of-9 incident now yields 0 purges); "one terminal reap → exactly
+one notice" and "guarded/standby/protected survive" are reproduced through the real SessionManager event
+path (integration); the route is proven alive on the real AgentServer (e2e). A full live boot with a
+deliberately-slowed tmux + a real Telegram notice landing was NOT performed in this environment — the
+test-tier reproductions stand in for it, and that gap is stated rather than papered over.
+
+## Commit — annotate intentional silent catches (no-silent-fallbacks ratchet)
+
+Two new intentional silent catches are annotated `@silent-fallback-ok` so the
+no-silent-fallbacks ratchet doesn't count them: `ReapLog.read` (no log file ⇒
+empty list is correct, not degraded) and the §P5 transcript-tail read (an
+unreadable tail ⇒ no meaningful-advance signal this tick; treated as ambiguous,
+never as progress). Behavior unchanged.