instar 1.3.225 → 1.3.227

package/upgrades/1.3.227.md

@@ -0,0 +1,109 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The `SessionReaper` gains an **observe-only** busy-orphan detector behind a new
+dark-by-default flag `busyOrphanDetection` — the inverse of #722's
+`cpuAwareActiveProcessKeep`, closing the blind spot that fix can't reach.
+
+**The gap.** #722 made the `active-process` keep require *positive CPU progress*
+under load, so a wedged/**idle** child (≈0 CPU) no longer pins an idle session.
+But CPU-progress is only a *proxy* for "useful" — a **useless process that
+SPINS** (a hot-loop, a wedged job burning CPU) looks "active" and would keep the
+session pinned. So #722 catches the idle orphan; it does not catch the *busy*
+orphan.
+
+**The detector.** Under CPU pressure, when a session is kept ONLY by an
+`active-process` veto whose child is provably **burning CPU** (the descendant
+CPU-seconds delta is above the idle floor) yet the session ITSELF looks fully
+idle (a positive ready-prompt + a flat, non-growing transcript) across an
+extended dwell (`busyOrphanConfirmTicks`, default 5 ≈ 10 min), the reaper records
+a `busy-orphan-suspected` row in the decision audit (`logs/reaper-audit.jsonl`),
+and a `busy-orphan-cleared` row when a confirmed suspect recovers.
+
+**It NEVER changes the keep/kill decision.** This is pure observation — it makes
+the "useless-but-busy child pins an idle session" case *measurable* so that safe
+auto-reclaim can graduate later with real data (the instar observe-first → act
+pattern). Zero false-kill risk by construction.
+
+**Conservative by construction:**
+- No-op at `normal` pressure, when the CPU dep is absent, on the first sighting
+  (no transcript-growth baseline yet), and whenever the transcript is unresolved
+  or growing — all resolve to "not a suspect".
+- Only the `active-process` keep-reason is considered; every earlier reason
+  (recent-user, commitment, recovery, …) is untouched.
+- Emits the suspect row exactly ONCE — the tick the dwell crosses the threshold —
+  not every tick after (no per-tick audit flood).
+
+Ships dark fleet-wide; live on development agents via the `developmentAgent`
+gate (same as #722), so it's dogfooded on a real loaded box.
+
+`StateManager.listSessions()` now serves from a short-TTL in-memory cache instead
+of re-reading and re-parsing every session file from disk on every call.
+
+**The bug (a systemic CPU hot-loop).** `listSessions()` did `readdirSync` +
+`readFileSync` + `JSON.parse` of **every** session JSON file on **every** call —
+and it's called each tick by the SessionReaper and the sentinels via
+`listRunningSessions()`. So the cost was O(sessions × pollers × tick-rate) disk
+reads, which kept agent servers spinning at 50–67% CPU (a CDP profile showed ~30%
+of server CPU was literally `readFileUtf8`, with `listSessions` on top). It was
+systemic (every agent with sessions + active pollers) and survived restarts —
+which is exactly why bouncing a hot server never helped.
+
+**The fix.** A 1-second TTL cache on the full session list. The many sub-second
+read-only callers within a tick now share one disk read; the cache is invalidated
+on every session write (`saveSession` / `removeSession`), so a freshly spawned or
+terminated session is visible on the very next call — no staleness for the cases
+that matter. `listSessions` returns shallow copies, so a caller can't corrupt the
+shared cache. StateManager is the sole in-process writer of session files, so the
+invalidation is complete (cross-machine writes carry at most the 1s TTL of
+staleness, which the reaper/scheduler already tolerate).
+
+Net effect: the per-tick session-directory churn collapses to near-zero, fixing
+the agent-server CPU hot-loop fleet-wide with no behavior change.
+
+## What to Tell Your User
+
+Nothing — it is dark by default and observe-only (it never changes behavior, just
+writes audit rows). If surfaced at all, surface it as Experimental observability
+that makes the busy-orphan case visible.
+
+Nothing required — it's an internal performance fix. If your agent's server was
+running hot / the machine load was high with no obvious cause, this is a likely
+culprit and it's now fixed; servers idle much cooler.
+
+## Summary of New Capabilities
+
+- `monitoring.sessionReaper.busyOrphanDetection` (boolean, default false;
+  `developmentAgent` agents default true) — observe-only flagging of idle
+  sessions pinned by a CPU-burning child.
+- `monitoring.sessionReaper.busyOrphanConfirmTicks` (number, default 5) — the
+  consecutive-suspect-tick dwell before a row is emitted.
+- New audit events: `busy-orphan-suspected`, `busy-orphan-cleared`.
+
+- None (no new API, route, or config). `StateManager.listSessions()` is now cached
+  (1s TTL, write-invalidated); behavior is unchanged, cost drops from O(files) per
+  call to one read per second of read-only traffic.
+
+## Evidence
+
+- Motivated by a real review catch (the gap a busy/hot orphan defeats the
+  CPU-progress proxy) and a live instance (agent servers hot-looping at ~50% CPU
+  while otherwise idle).
+- Tests: `tests/unit/session-reaper-busy-orphan.test.ts` — 9 tests, both sides of
+  every boundary (flags only on busy-child + idle-session + dwell; never on
+  CPU-flat / working-frame / flag-off / off-pressure / no-dep / pre-dwell; emits
+  once; clears on recovery; verdict always unchanged) + a wiring-integrity
+  assertion. The 56 existing reaper + #722 tests stay green.
+
+- Pinned with node's inspector: SIGUSR1 → CDP CPU profile of a hot agent server
+  showed 30.8% `readFileUtf8` + 7% `listSessions` (StateManager.js:151), called via
+  the reaper/sentinel ticks — the symbolicated JS frame macOS `sample` couldn't show.
+- Tests: `tests/unit/state-manager-listsessions-cache.test.ts` — 6 tests (cache HIT
+  within TTL; MISS after TTL; immediate invalidation on saveSession + removeSession;
+  status-filter on cached data; copy-safety; corrupt-file skip). The 71 existing
+  StateManager tests + 255 consumer tests (reaper, scheduler, restart-all, recovery)
+  stay green.

package/upgrades/burn-detector-activity-gate.eli16.md

@@ -0,0 +1,53 @@
+# ELI16: Burn-detector activity gate (stop the repeating token-burn noise)
+
+Instar watches how many tokens each part of an agent is using. If one part suddenly hogs more than a
+quarter of a whole day's spend, it raises a heads-up: "a component is using more than a quarter of
+the token budget." That's the **token-burn detector**, and it's meant to catch a runaway loop or an
+unexpected cost spike early.
+
+## The bug
+
+The detector only asked one question: "Over the last 24 hours, did one part use more than 25% of the
+total?" It never asked the obvious follow-up: "Is that still happening right now?"
+
+So here's what went wrong. One big working session ran for a while, used a lot of tokens, and then
+finished. For the next 24 hours that finished session still counted as a big slice of the trailing-day
+total — so the alarm kept going off, over and over, every time the cooldown expired. And because the
+session had stopped, the alarm even said "Projected 0 tokens in next 24h" — it was literally
+announcing "this thing is burning a lot" and "this thing is spending nothing right now" in the same
+breath. That's the noise the user saw: a full day of contradictory, useless heads-ups for something
+that was already over.
+
+## The fix
+
+Add one missing check: only raise the alarm if the component is **actually spending right now** —
+meaning it used tokens in the last hour. A big 24-hour share with a zero current rate is a finished
+burst, not a live burn, so it stays quiet. The detector's other trigger (a sudden spike versus a
+component's own 7-day normal) already had this kind of "is it active now" check; this just brings the
+25%-share trigger up to the same standard.
+
+## What already existed vs. what's new
+
+- **Already there:** the burn detector, the 25% trigger, the 1-hour spend lookup, and the throttle
+  runbook that decides whether to just alert or actually slow a component down.
+- **New:** (1) the activity gate on the 25% trigger; (2) an operator off-switch and tuning knobs under
+  a burn-detection config block, so anyone can silence or retune the alerts without a code change; (3)
+  a cleaner alert message (the old internal "Phase 3/Phase 4" wording is gone); (4) a one-paragraph
+  note added to every agent's instructions on update so any agent can explain the alert and offer the
+  off-switch.
+
+## Safeguards (plain terms)
+
+- The change only ever makes the alarm **quieter** — it adds a condition that must also be true before
+  alerting. It can never cause a new false alarm.
+- The detector is still just a *reporter*. It doesn't slow anything down or block anything by itself;
+  a separate piece decides whether to act. That separation is unchanged.
+- All the new config is optional. If you set nothing, you get the fixed-but-sensible defaults.
+- Rolling it back is a one-line revert with no data cleanup. Worst case, the old noise comes back —
+  there's no risk to correctness or to stored data.
+
+## What's NOT fixed (on purpose)
+
+It still labels un-attributed spend as `unknown::<some-id>`. That just means "we couldn't pin this
+spend to a named component" — it's not a problem by itself, and giving those a real name is a bigger,
+separate piece of work.

package/upgrades/dev-ci-failures-tool.eli16.md

@@ -0,0 +1,21 @@
+# `instar dev:ci-failures` — ELI16
+
+Viewable private artifact:
+https://echo.dawn-tunnel.dev/view/41bc3523-a95d-4038-bd43-af8a942e0008?sig=e785278aea6a2e82502cc55fe56b98e55ab4cef543b71ddf32c953db7985c191
+
+When a pull request's automated tests go red, you want to know *which* test broke and where.
+Normally you'd open the CI logs — but in some setups the command that fetches those logs comes
+back completely empty, so a red run tells you "something failed" and nothing else. I hit this
+repeatedly while shipping fixes this run, and had to re-discover a workaround each time.
+
+This turns that workaround into a permanent tool. `instar dev:ci-failures <pr>` reads a
+*different* GitHub endpoint (the per-check "annotations") that still reports the exact failing
+file, line number, and assertion message even when the logs are blank. It also tidies the
+output: it merges the duplicate failure that the Node-20 and Node-22 test shards both report,
+and it hides the generic CI-runner noise ("Process completed with exit code 1").
+
+It's read-only and informational — it never changes anything, it just shows you the failures.
+Pairs with `instar dev:preflight` as the contributor dev-loop toolkit.
+
+_Tier-2 · branch `echo/dev-ci-failures-tool` · the first of the "turn this run's friction into
+infrastructure" improvements._

package/upgrades/reaper-busy-orphan-detect.eli16.md

@@ -0,0 +1,33 @@
+# Catching the "busy but useless" process
+
+## The one-sentence version
+Last fix (#722) taught the cleanup robot to ignore a *frozen* leftover program. But a leftover program can also be *spinning uselessly* — burning the engine while going nowhere — and that one still looks "busy." This change makes the robot **notice and write down** those cases (without touching anything yet), so we can see how often it happens before we ever let it act.
+
+## Back to the garage
+Earlier rule: "don't tow a car just because it has an engine — only if the engine is also cold (off)." Good for the junked car with a dead battery.
+
+But what about a car parked in its spot with **the engine revving, nobody inside, going nowhere** — a stuck throttle? Its engine is hot, so the "is the engine cold?" test says *keep it*. Yet it's just as useless as the dead one, and it's burning fuel (CPU) and making noise (load) the whole time.
+
+This change doesn't tow that car. It puts a **note on the windshield**: "spot occupied by a revving-but-empty car for 10+ minutes." Collect enough notes and we'll know whether stuck-throttle cars are a real problem worth a tow rule — backed by data, not a guess.
+
+## What it actually does
+- Watches for a session that is **sitting idle** (at its ready prompt, transcript not growing) while a child program **keeps burning CPU**.
+- After that's been true for a while (a dwell, ~10 minutes), it writes one line: `busy-orphan-suspected`.
+- When the situation clears, it writes `busy-orphan-cleared`.
+- That's the whole feature. **It never reaps, kills, nudges, or notifies.** Pure note-taking.
+
+## Why note-taking first (instead of just towing)
+The one honest reason *not* to tow a revving car: maybe the driver started it on purpose to warm it up and stepped away — i.e. an agent legitimately kicked off a real background job and went back to its prompt. Telling those two apart reliably is hard. So instead of risking a wrong tow, we **measure first**: gather real examples, learn the signatures, and only then design a safe auto-action. That's the instar way — observe, then act.
+
+## The safety rails
+1. **Changes no decisions.** The keep/kill logic is byte-for-byte the same; this only adds an audit line.
+2. **Only under load**, only when CPU is actually measurable, only after a real dwell — never on a hair trigger.
+3. **One note per episode**, not per tick — no log flood.
+4. **Dark everywhere except me** (the development agent), so it proves itself on a real loaded machine first.
+
+## Why it matters
+Together with #722 this closes both halves of "a process pins an idle session": the *idle* leftover (#722 can now reclaim it) and the *busy* leftover (this makes it visible). You can't responsibly manage machine load you can't see — this is the seeing.
+
+---
+
+**Rendered (verified HTTP 200):** https://echo.dawn-tunnel.dev/view/a6ad4a97-c59b-4a61-81c8-4d2aa8d3d7b4?sig=333db8be8c2b9624668753699e48aaa03a5b208ae963c841293ae4ba4ec0c5f7

package/upgrades/reaper-cpu-aware-keep.eli16.md

@@ -0,0 +1,30 @@
+# Why the reaper got smarter about "busy" sessions
+
+## The one-sentence version
+Before, the cleanup robot thought a session was *busy* if it had **any** helper program still attached — even a frozen, do-nothing one. Now, when the machine is overloaded, it also checks whether that helper is *actually using the CPU*. A frozen helper no longer keeps a dead-idle session alive and hogging the machine.
+
+## Picture it
+Think of a parking garage that only tows cars when it's full. The old rule: "never tow a car if its engine is installed." Trouble is, a junked car with a cold, dead engine *still has an engine installed* — so it sat there forever, taking a spot while the garage overflowed.
+
+The new rule (only when the garage is full): "don't tow a car just because it has an engine — tow it only if the engine is also **stone cold** (not running) AND the driver's seat is empty AND nothing's happening inside." A car that's actually running, or has someone in it, is never touched.
+
+## What changed, precisely
+- The reaper used to keep a session whenever a child process **existed**.
+- Now, **under CPU load only**, it also asks: did that child burn any CPU recently?
+- If the child is **flat (≈0 CPU)** *and* the session is sitting idle at a ready prompt *and* its transcript isn't growing → it becomes reclaimable.
+- If the child is doing real work (CPU rising), or the session might be mid-task → it's kept, exactly like before.
+
+## The safety rails (why this won't kill your work)
+1. **Off when the machine is calm.** Zero change unless CPU pressure is real.
+2. **Never kills on the CPU check alone** — it still has to pass the "is it truly idle?" proof and the slow, repeated-confirmation + budget gates.
+3. **Can't measure? Keep it.** First look, missing data, weird readings → always keep.
+4. **Only the cleanup robot changed.** The guard that stops *other* things from killing your sessions is untouched.
+5. **Dark by default.** Off across the fleet; on only for the development agent (me) so I can prove it on a real loaded machine first.
+6. **Leaves a paper trail.** Every time it relaxes the rule it writes a line you can read in `logs/reaper-audit.jsonl`.
+
+## Why it matters
+Idle sessions with a stuck helper (a hung MCP server, a wedged `codex` job) were quietly piling up and starving the machine — which is what makes new sessions fail to spawn and messaging go silent. This lets the reaper finally reclaim exactly those, without ever risking a session that's actually working.
+
+---
+
+**Rendered (verified) view:** _set below after creating the tunnel view._

package/upgrades/side-effects/burn-detector-activity-gate.md

@@ -0,0 +1,110 @@
+# Side-Effects Review — Burn-detector absolute-share activity gate
+
+**Version / slug:** `burn-detector-activity-gate`
+**Date:** `2026-06-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The `BurnDetector` absolute-share trigger fired whenever one attribution key crossed 25% of the
+trailing-24h token spend, with no check that the key was still spending. A heavy session that
+finished hours ago kept re-tripping the alarm every cooldown for a full 24h with self-contradictory
+"consumed 67% of 24h spend … Projected 0 tokens" messages. This change adds an activity gate
+(`tokens1h > absoluteShareActivityFloorTokens`, default 0) so the absolute-share trigger only fires
+for a key actively spending in the last hour. It also exposes the previously-hardcoded
+burn-detection config as `monitoring.burnDetection.*` (master off-switch + tuning knobs), cleans the
+alert text, and adds a content-sniffed `PostUpdateMigrator` awareness section. Files touched:
+`src/monitoring/BurnDetector.ts`, `src/server/AgentServer.ts`, `src/core/types.ts`,
+`src/scaffold/templates.ts`, `src/core/PostUpdateMigrator.ts`, plus
+`tests/unit/burn-detection-phase-3.test.ts` and `tests/unit/PostUpdateMigrator-tokenBurnAlerts.test.ts`.
+
+## Decision-point inventory
+
+- `BurnDetector.tick` absolute-share trigger — **modify** — adds an AND-condition (`isActivelySpending`)
+  before the existing `share > threshold` test. Strictly narrows when the trigger fires; never widens.
+- `AgentServer` burn-detection startup — **modify** — reads `monitoring.burnDetection`; `enabled:false`
+  skips the whole subsystem; other knobs are passed through to `BurnDetector` / `BurnThrottleRunbook`
+  only when explicitly set (partial configs built without `undefined` keys so a default is never clobbered).
+- `PostUpdateMigrator.migrateClaudeMd` — **add** — one idempotent, content-sniffed section append.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+A genuine live burn that happens to log zero tokens in the most recent hour would be gated out. In
+practice this can't be a sustained burn — `tokens1h` is computed from a real 1h ledger query, so a
+key actively spending necessarily has positive last-hour tokens. The only "rejected" case is a key
+whose 24h share is high but whose current rate is zero, which is by definition not a live burn. The
+default floor of 0 is the most conservative choice: it suppresses only the provably-finished case.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+It does not improve attribution — spend still labelled `unknown::<sessionId>` (resolver ran, found no
+named component) is a coverage gap, not a burn, and is out of scope here. A burst that ends but
+leaves a small warm-session cache trickle in the last hour (tokens1h slightly > 0) would still fire
+if its 24h share exceeds the threshold; operators who see that can raise
+`absoluteShareActivityFloorTokens`. The baseline-divergence trigger is unchanged.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?** Yes. The gate lives inside `BurnDetector.tick` beside the existing
+`rollingBaselineFloor` activity check on the sibling trigger — same layer, same shape. The config
+read lives in `AgentServer` where every other monitoring subsystem is wired. The migration lives
+beside the other `migrateClaudeMd` sections. No re-implementation of an existing primitive.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+
+`BurnDetector` is a signal producer: it emits to `DegradationReporter`; the `BurnThrottleRunbook` is
+the authority that decides alert-vs-throttle. This change makes the signal *more* conservative (fewer
+false positives) — it adds no blocking authority and removes none. The off-switch is operator config,
+not runtime decision logic.
+
+## 5. Interactions
+
+- **Shadowing:** The activity gate runs before the baseline-divergence trigger in the same key loop.
+  When absolute-share is gated out, baseline-divergence is still evaluated normally (and has its own
+  `rollingBaselineFloor` gate), so a finished burst produces zero signals from both — confirmed by the
+  new "finished burst" unit test.
+- **Double-fire:** None. One signal per key per cooldown, unchanged.
+- **Races:** None. `BurnDetector` reads the ledger; it shares no mutable state with concurrent code.
+- **Feedback loops:** The runbook self-attribution prefix (`burn-throttle-runbook::`) remains exempt,
+  so throttle activity can't feed back into the detector.
+
+## 6. External surfaces
+
+The user-visible Telegram alert text changes (drops the "Phase 3/Phase 4" jargon; "at current rate"
+→ "at the current rate"). The `BurnVerifier.extractTokensLast1h` regex that parses the projected
+number back out of the alert still matches the new wording (the captured group precedes the changed
+suffix) — verified against existing fixtures. Volume of alerts drops sharply (finished bursts no
+longer re-alarm). New optional `monitoring.burnDetection` config keys; absence preserves defaults.
+Existing agents get the CLAUDE.md awareness section on next update via the idempotent migration. No
+database/ledger schema change.
+
+## 7. Rollback cost
+
+Pure code + docs change. Revert and ship as the next patch. No persistent state, no data migration,
+no agent-state repair. During the rollback window the only regression is the return of the original
+noise — there is no correctness or data risk. An operator who needs immediate relief without a
+release can set `monitoring.burnDetection.enabled: false` and restart sessions.
+
+## Conclusion
+
+The review surfaced no blocking concerns. The change narrows an over-firing signal-producer with a
+gate that mirrors an existing sibling check, adds an operator off-switch, and is fully reversible by
+revert or config. The only residual is the unchanged attribution-coverage gap (`unknown::<id>`),
+explicitly out of scope and tracked as a separate, larger effort. Clear to ship.
+
+## Evidence pointers
+
+- `tests/unit/burn-detection-phase-3.test.ts` — 3 new activity-gate tests (both sides of the boundary
+  + the configurable-floor path); 65 burn-detection tests green across phases 3–6.
+- `tests/unit/PostUpdateMigrator-tokenBurnAlerts.test.ts` — 5 new migration tests (add / idempotent /
+  preserve / skip-missing / template-emits).
+- `tsc --noEmit` clean.

package/upgrades/side-effects/dev-ci-failures-tool.md

@@ -0,0 +1,54 @@
+# Side-Effects Review — `instar dev:ci-failures`
+
+**Version / slug:** `dev-ci-failures-tool`
+**Date:** `2026-06-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (Tier-2 — new read-only dev CLI command; no runtime/server surface, no decision boundary)`
+
+## Summary of the change
+
+New `instar dev:ci-failures <pr>` CLI command (`src/commands/devCiFailures.ts`, wired in
+`src/cli.ts`) that prints a PR's failing tests via the GitHub check-run annotations API.
+Read-only: it shells out to `gh` GET endpoints only. Adds a manifest catalog entry
+(`cli:dev-ci-failures`, colon-free id per Codey's #716 convention fix) + awareness docs
+(CLAUDE.md, templates.ts, site cli reference). No server route, no config, no state.
+
+## Decision-point inventory
+
+1. **Annotations API vs log parsing.** Chose the check-run *annotations* endpoint because
+   `gh run view --log[-failed]` returns 0 bytes in some environments (the friction that
+   motivated this). Annotations carry `path:line` + the assertion even when logs are empty.
+2. **Diagnostic, not a gate (exit 0 even with failures).** It informs; it does not fail the
+   shell on a red PR. Exit 1 is reserved for operational errors (PR unresolvable / API
+   error) so a script can tell "couldn't run" from "ran, here are the failures."
+3. **Shard-pair dedup.** The node-20 / node-22 shard checks report the identical failure;
+   the command de-dupes by the formatted line so each distinct failure prints once.
+4. **Noise filter.** Drops `.github/...` annotations and `Process completed with exit code N`
+   (CI-runner artifacts, not test failures). When a failed check has no test-level
+   annotations (a build/lint/type step), it prints a note rather than silently showing nothing.
+
+## 1. Blast radius / reversibility
+
+Additive: one new command file + one cli.ts command block + a manifest entry + doc lines.
+Fully reversible. No existing behavior touched. Read-only external calls (gh GET).
+
+## 2. Failure modes
+
+- `gh` not installed / not authenticated → the command surfaces the gh error and exits 1.
+- An annotations-endpoint hiccup for one check → that check is skipped, others still print.
+- A PR with no failed checks → prints "No failed checks", exit 0.
+All handled; none crash.
+
+## 3. Manifest / docs
+
+`cli:dev-ci-failures` added to the generator's command list → colon-free manifest id
+(passes the type:name convention). CLAUDE.md and `templates.ts`'s `generateClaudeMd` were
+edited in sync so `verify-deployed-templates` stays green (locally confirmed). Manifest
+`generatedAt` timestamp aside, the generator output is deterministic.
+
+## 4. Tests
+
+`tests/unit/devCiFailures.test.ts` — pure `extractFailureLines` (both sides: keeps real
+failures, drops warnings/`.github`/`Process completed`, truncates long messages, handles
+missing path) + `runDevCiFailures` with injected `gh` deps (red PR prints the test; shard
+dedup; green PR; unresolvable PR → exit 1; build-step-with-no-test-annotations note). 10 tests.

package/upgrades/side-effects/reaper-busy-orphan-detect.md

@@ -0,0 +1,85 @@
+# Side-Effects Review — SessionReaper observe-only busy-orphan detection
+
+**Version / slug:** `reaper-busy-orphan-detect`
+**Date:** `2026-06-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (observe-only — never changes a keep/kill verdict; reaper-only; dark by default)`
+
+## Summary of the change
+
+Under CPU pressure, when a session is kept by an `active-process` veto whose
+child is provably burning CPU (cpuFlat===false) yet the session itself is idle
+(positive idle prompt + flat transcript) across an extended dwell, the reaper
+records a `busy-orphan-suspected` audit row (and `busy-orphan-cleared` on
+recovery). It is the inverse of #722's `cpuAwareActiveProcessKeep` and closes the
+gap where a *busy* useless process defeats the CPU-progress proxy. Gated by
+`busyOrphanDetection` (dark; dev agents on via `developmentAgent`).
+
+## Decision-point inventory
+
+1. **Suspect predicate** — flag iff ALL hold: `busyOrphanDetection` on, under CPU
+   pressure (tier ≠ normal), `blocked.reason === 'active-process'`,
+   `cpuFlat === false` (descendant CPU delta above the idle floor), transcript
+   delta `static` (resolved + not grown vs the prior tick), and a positive
+   idle-prompt frame. Any miss ⇒ not a suspect.
+2. **Dwell** — emit `busy-orphan-suspected` exactly the tick the consecutive
+   suspect streak crosses `busyOrphanConfirmTicks` (default 5). A brief
+   background job that finishes within the dwell is never flagged.
+3. **Clear** — when a confirmed suspect (streak ≥ threshold) stops being a suspect,
+   emit `busy-orphan-cleared`. Streaks below the threshold reset silently.
+
+## 1. Over-block (does it ever reap something it shouldn't?)
+
+**No — it cannot reap anything.** This change is observe-only: the keep/kill
+verdict path is untouched. Every code path through the detector returns the
+SAME `keep('active-process')` it returned before; the only effect is an audit
+row. The exact "idle session + legit busy background job" case that
+`cpuAwareActiveProcessKeep` was deliberately conservative about is, here, merely
+*logged* — never acted on. A false suspect costs one JSONL line, nothing more.
+
+## 2. Under-block
+
+Nothing is loosened. No existing protection, gate, or veto is weakened — the
+shared `ReapGuard`/`ReapAuthority` path and the reaper's own stateful checks are
+entirely unchanged. The detector reads the same already-captured frame and
+transcript (no extra tmux/fs work) and the same `cpuFlat` signal #722 already
+computes.
+
+## 3. Blast radius / rollout
+
+Dark by default (`busyOrphanDetection: false`). Dev agents get it via the
+`developmentAgent` gate at the server wiring site (riding #722's IIFE). On the
+fleet the flag is false ⇒ the detection branch is never entered and
+`cpuProgressFlat` returns early exactly as before #722 ⇒ identical behavior.
+
+## 4. Migration parity
+
+No `migrateConfig` — same reasoning as #722: the default resolves at the server
+wiring site via the `developmentAgent` gate, so writing an explicit `false` into
+existing configs would wrongly override the gate on dev agents.
+`busyOrphanConfirmTicks` falls back to the code default. The new-agent template
+(`generateClaudeMd`) gains an awareness line; no `migrateClaudeMd` (dark feature).
+
+## 5. Interaction with #722 (cpuAwareActiveProcessKeep)
+
+The two are mutually exclusive on the CPU signal and complementary:
+`cpuAwareActiveProcessKeep` acts when `cpuFlat === true` (relaxes the veto);
+busy-orphan detection observes when `cpuFlat === false` (flags). They share the
+`cpuProgressFlat` sampler, whose gate now runs when EITHER feature is on. With
+both off (fleet default), the sampler returns `undefined` immediately and neither
+path engages.
+
+## 6. Audit volume
+
+`busy-orphan-suspected` fires at most once per suspect episode (on the dwell
+crossing), `busy-orphan-cleared` once on recovery — bounded, not per-tick. Lands
+in `logs/reaper-audit.jsonl` like the other reaper decision rows. Silent (no
+Telegram, no attention item).
+
+## 7. What it does NOT do
+
+- Does not reap, kill, nudge, or notify — observe-only.
+- Does not run off-pressure or without the CPU dep.
+- Does not change `hasActiveProcesses` or any guard.
+- Does not attempt to *fix* a busy orphan (e.g. tree-kill) — that is a separate,
+  deliberately-staged follow-up that would build on this measurement.

package/upgrades/side-effects/reaper-cpu-aware-keep.md

@@ -0,0 +1,90 @@
+# Side-Effects Review — SessionReaper CPU-aware active-process keep
+
+**Version / slug:** `reaper-cpu-aware-keep`
+**Date:** `2026-06-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (reaper-only, dark-by-default, no new external surface)`
+
+## Summary of the change
+
+Under CPU pressure, the reaper's `active-process` existence-veto additionally
+requires positive descendant-CPU progress (sampled across ticks via the #706
+`descendantCpuSeconds` helper). A CPU-flat child no longer keeps an idle session
+un-reapable; the reaper falls through to its existing transcript-growth +
+positive-idle checks. Gated by `cpuAwareActiveProcessKeep` (dark; dev agents on
+via `developmentAgent`). Reaper-only — the shared `ReapGuard`/`ReapAuthority`
+path is untouched.
+
+## Decision-point inventory
+
+1. **Pressure gate** — `tier === 'normal'` ⇒ never tighten. Off-load behavior is
+   byte-for-byte unchanged.
+2. **CPU-flat threshold** — `ratePerSec < cpuActiveMinRatePerSec` (default 0.02).
+   Below ⇒ "flat" (relax the veto); at/above ⇒ working (veto stands).
+3. **Can't-tell ⇒ KEEP** — feature off, dep absent, sample error, non-finite read,
+   first sighting (no prior delta), or CPU went backwards ⇒ `undefined` ⇒ the veto
+   is NOT relaxed.
+4. **Scope of relaxation** — only `blocked.reason === 'active-process'` is relaxed.
+   Every earlier keep-reason (protected, recovery, recent-user, commitment,
+   subagent, structural-long-work, …) returns first and is never affected.
+5. **Fall-through, not kill** — relaxing the veto does not reap; the stateful
+   transcript-growth + positive-idle gates (then hysteresis + two-phase + budget)
+   still must all clear.
+
+## 1. Over-block (false KEEP removed — could it now reap something it shouldn't?)
+
+The only sessions newly reachable for reaping are: idle-at-a-ready-prompt,
+transcript-not-growing, under CPU pressure, whose ONLY surviving keep-reason was
+an existing-but-CPU-flat child. That is precisely the wedged/idle-child case we
+want reclaimed. A genuinely-working session is still protected three ways:
+(a) if any descendant burns CPU the delta is positive ⇒ veto stands;
+(b) `descendantCpuSeconds` includes the main process, so a CPU-burning
+extended-think keeps it; (c) the positive-idle gate requires an affirmative
+ready-prompt with no working-footer, so a mid-turn session (footer present)
+returns `no-positive-idle` and is kept regardless. A wedged-but-not-idle session
+(no ready prompt) is likewise kept by positive-idle — the reaper stays
+conservative there (that case is the StaleSessionBackstop's operator-ask job, not
+the reaper's).
+
+## 2. Under-block (did we loosen a real protection?)
+
+No protection is loosened for any non-reaper caller. The shared `ReapGuard` used
+by `terminateSession` (the authority that vetoes OTHER killers) is unchanged, so
+external kills still honor the full existence-veto. Only the deliberate,
+pressure-gated, hysteresis-bounded reaper relaxes it, and only under load.
+
+## 3. Blast radius / rollout
+
+Dark by default (`cpuAwareActiveProcessKeep: false`). Dev agents get it via the
+`developmentAgent` gate at the server wiring site (`?? !!config.developmentAgent`)
+— an explicit config value always wins. On the fleet (no `developmentAgent`) the
+flag is false ⇒ the new code path is never entered ⇒ identical behavior to
+today. Echo (developmentAgent) dogfoods it live on a genuinely loaded box.
+
+## 4. Migration parity
+
+- **Config:** no `migrateConfig` entry is added *by design*. The default is
+  resolved at the server wiring site via the `developmentAgent` gate, NOT written
+  into `config.json`. Writing an explicit `false` into existing configs would
+  *wrongly override* the gate on dev agents (explicit beats `??`). Existing
+  agents therefore receive the correct behavior (dev on, fleet off) through the
+  code path with no config write. `cpuActiveMinRatePerSec` falls back to the
+  `DEFAULT_SESSION_REAPER_CONFIG` value for agents without the field.
+- **CLAUDE.md:** the new-agent template (`generateClaudeMd`) gains an awareness
+  line. No `migrateClaudeMd` entry — the feature is dark on the fleet, so existing
+  agents don't need the awareness until a future fleet-promotion change (which
+  will add it), per the maturity-honesty principle (don't document a dark feature
+  to existing agents as if it's live).
+
+## 5. Observability
+
+Each veto-relaxation emits a `cpu-keep-tightened` row to `logs/reaper-audit.jsonl`
+(tier, verdict, keptBy, the active threshold). A kill-path behavior change leaves
+a durable trail — never silent.
+
+## 6. What it does NOT do
+
+- Does not change `hasActiveProcesses` itself (so `UpdateGate`, `SessionManager`
+  idle-detection, and `SessionRecovery` are untouched).
+- Does not kill on CPU-flatness alone (always falls through to the idle proof).
+- Does not run off-pressure or when CPU is unmeasurable.