instar 1.3.128 → 1.3.130

package/upgrades/1.3.130.md

@@ -0,0 +1,74 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**The SessionReaper now reaps under CPU pressure, not only memory — and keeps a
+silent, reviewable record of every decision it makes.**
+
+The idle-session reaper used to compute its pressure tier purely from free
+memory. But on a busy multi-agent box the real squeeze is almost always CPU, not
+RAM (free memory can look fine while the load average is well past the core
+count). So an idle session could sit holding CPU baseline indefinitely and the
+reaper, watching only memory, would never wake up.
+
+Pressure is now the WORST of two signals: memory (free %) and CPU (1-minute load
+average ÷ core count). A CPU-bound box raises the tier even when memory is fine,
+so genuinely-idle sessions become eligible under load — while the reaper's
+positive-idle proof, hysteresis, confirmation window, rate limits, and grace
+period are all unchanged, so it still never reaps a working session. The two CPU
+thresholds are configurable; sensible defaults ship (moderate at 1.0 load per
+core, critical at 1.5), and a transient build spike won't trigger a reaping spree
+because the existing 3-observation confirmation smooths it.
+
+Second, the reaper now writes a dedicated decision audit trail. Previously its
+structured events were mixed into the shared sentinel log and only covered the
+reap path — there was no record of the routine keep decisions, so "what is the
+reaper considering, and why?" had no grounded answer. It now logs every keep/kill
+decision change (on transition, not every tick, so a multi-day kept session logs
+once) plus the reap-path events, each stamped with the pressure tier that drove
+it, to a dedicated file readable through a new read-only endpoint.
+
+## What to Tell Your User
+
+Nothing to configure. Your idle-session cleanup is now aware of CPU load, not
+just memory — so on a busy machine it can finally relieve pressure that free
+memory alone would have hidden. It is still just as careful: it never touches a
+session that might be working. You can also now ask me what the cleanup is
+considering and why it kept or shut down any session — there is a quiet,
+inspectable decision log behind it. None of this sends you notifications; it is
+all there for when you want to look.
+
+## Summary of New Capabilities
+
+- Reaper pressure is CPU-aware: tier is the worst of memory (free %) and CPU
+  (1-min load ÷ cores), via the new pure `computePressure()` classifier.
+- Two new tunable thresholds: `cpuModerateLoadPerCore` (default 1.0) and
+  `cpuCriticalLoadPerCore` (default 1.5) under `monitoring.sessionReaper`.
+  Existing agents receive them automatically via the canonical config defaults.
+- `GET /sessions/reaper`'s `pressure.inputs` now exposes `freePct`,
+  `loadPerCore`, and the `memTier`/`cpuTier` breakdown.
+- New read-only endpoint `GET /sessions/reaper/audit?limit=N` returns the tail
+  of the dedicated decision trail at `logs/reaper-audit.jsonl`.
+- A `decision` audit row is written on first sight and on every (verdict,
+  keptBy) change — transition-only, so no per-tick log spam. Silent: no Telegram,
+  no attention items.
+
+## Evidence
+
+- `tests/unit/session-reaper-pressure-audit.test.ts` — new: `computePressure`
+  (memory-only when cores unknown, CPU-raises-tier, worst-of combos, custom
+  thresholds, non-finite load ignored); the `reaperAuditSink`/`readReaperAudit`
+  round-trip (bounded tail, `[]` when absent); and the transition-only decision
+  audit (logs on first sight + on change, not when unchanged).
+- `tests/integration/session-reaper-routes.test.ts` — new: `GET
+  /sessions/reaper/audit` returns 200 with the tail, honors `?limit`, and `[]`
+  when no trail exists.
+- `tests/e2e/session-reaper-lifecycle.test.ts` — new Phase-1 "feature alive"
+  test: the audit route returns 200 (not 503) through the real AgentServer
+  plumbing and reads a written row back.
+- `tests/unit/feature-delivery-completeness.test.ts` + `capabilities-discoverability.test.ts`
+  green: migrator parity (new `migrateClaudeMd` section), config parity, and
+  route classification all satisfied.
+- Full `npm run lint` + the reaper test tiers pass.

package/upgrades/side-effects/codex-autonomous-loop-driver.md

@@ -0,0 +1,91 @@
+# Side-Effects Review — Codex autonomous-loop driver
+
+**Version / slug:** `codex-autonomous-loop-driver`
+**Date:** `2026-05-30`
+**Author:** `echo`
+**Second-pass reviewer:** see below (required — lifecycle machinery)
+
+## Summary of the change
+
+Adds a codex registration of the shared autonomous-stop-hook so a `codex exec` session
+sustains a multi-turn autonomous run (the codex analog of Claude's Stop-hook loop). A
+SEPARATE codex Stop group (`autonomous-stop-hook.sh --codex`) is added in
+`installCodexHooks`; the hook self-gates on `autonomousSessions.codexLoopDriver.enabled`
+(default false → DARK). Claude's path is byte-for-byte unchanged.
+
+## Decision-point inventory
+
+1. `IS_CODEX` gate in the hook (— is this a codex-registered invocation?).
+2. `codexLoopDriver.enabled` flag check (— should the codex loop actually run?).
+3. `groupIsInstarOwned` (— is this Stop group instar-owned, to replace not duplicate?).
+
+## 1. Over-block
+Could it block a stop that SHOULD proceed? Only when the flag is ON, an autonomous job is
+active for this session, AND tasks remain — which is exactly the intended block (continue
+the run). With the flag OFF (default) it never blocks. The existing ownership/duration/
+emergency/completion terminal checks (unchanged) still release the session.
+
+## 2. Under-block
+Could it fail to block when it SHOULD continue? When the flag is OFF, yes — by design
+(dark). When ON, the only residual is the open binary question of whether codex runs the
+second Stop group (Phase-5 / live verification gates this before enabling; fallback =
+move into group 0). No silent data loss either way — at worst the codex run stops early,
+same as today.
+
+## 3. Level-of-abstraction fit
+The driver lives where Claude's does (the autonomous skill hook) and is registered where
+codex's other standing hooks are (`installCodexHooks`). The flag sits with the other
+autonomous-mode settings (`autonomousSessions`). No new subsystem.
+
+## 4. Signal vs authority compliance
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+The hook is an AUTHORITY surface by nature (a Stop hook returns block/approve — same as
+Claude's existing loop hook and codex's existing stop-gate-router). It does not newly
+elevate authority: it reuses the established Stop-hook contract. The dark flag means the
+authority is dormant until explicitly enabled. No monitoring/signal component is converted
+into a blocker.
+
+## 5. Interactions
+- **Review trio (stop-gate-router / response-review / claim-intercept / scope-coherence):**
+  the driver is the LAST hook in the SAME Stop group (slot stop:0:N). Within-group block
+  precedence vs the router is verified live before enabling; worst case the session still
+  continues via the router (never strands).
+- **Claude autonomous mode:** independent registration (settings.json vs .codex/hooks.json);
+  `IS_CODEX=0` for Claude → unchanged.
+- **armCodexHooks:** the new hook changes the hooks.json hash → re-arm on update (handled
+  by the existing migration). Because it rides group 0 (a group codex already trusts/arms),
+  it adds NO new arm slot — avoiding the recurring-arm-spawn side-effect a separate group
+  (stop:1:0) would have caused (caught by the second-pass review, then designed out).
+
+## 6. External surfaces
+None new. No HTTP route, no Telegram message, no external API. The hook talks only to the
+local server's existing `/autonomous/evaluate-completion` (unchanged) when a completion
+condition is set.
+
+## 7. Rollback cost
+Lowest tier. Set `autonomousSessions.codexLoopDriver.enabled: false` → the standing hook
+exits immediately (instant, no redeploy, no session kill). Full PR revert is clean
+(additive change; removing the Stop group + the `IS_CODEX` block restores prior behavior).
+
+## Conclusion
+Safe to ship DARK. The only non-trivial residual (does codex run a second Stop group) is
+gated behind the default-off flag and resolved by live verification before enabling — per
+Justin's "careful + clear plan to regress" condition.
+
+## Second-pass review (if required)
+
+**Reviewer:** independent second-pass agent (lifecycle machinery — required)
+**Status:** DONE 2026-05-30 — **CONCUR on shipping DARK.** Verified PASS on: Claude path
+unchanged, dark gate cannot leak (all config-read failure paths → disabled), `$0` anchor,
+groupIsInstarOwned idempotency, migration parity (both halves land). The reviewer caught a
+fleet-wide arm side-effect from the original separate-group design (a `stop:1:0` slot codex
+may never trust → recurring codex-TUI arm spawns on every update, even dark). **Resolved**
+by moving the driver into the existing Stop group (slot stop:0:N) — no new arm slot. The
+remaining open item (within-group block precedence + that the loop actually re-prompts a
+real codex run) is gated to live verification BEFORE the flag is enabled, per the spec's
+Phase 5 — it is not a merge/dark-ship blocker.
+
+## Evidence pointers
+- Unit: `tests/unit/installCodexHooks.test.ts` (separate Stop group, idempotent, user-group preserved).
+- Unit: `tests/unit/autonomous-stop-hook-codex-gate.test.ts` (dark default / disabled / enabled / Claude-unaffected — both sides of the gate).
+- Spec: `docs/specs/codex-autonomous-loop-driver.md` (+ `.eli16.md`).

package/upgrades/side-effects/sessionreaper-cpu-aware-and-decision-audit.md

@@ -0,0 +1,122 @@
+# Side-Effects Review — SessionReaper CPU-aware pressure + decision audit
+
+**Version / slug:** `sessionreaper-cpu-aware-and-decision-audit`
+**Date:** `2026-05-30`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The idle-session reaper's pressure tier was computed from free memory only. This
+change makes it the WORST of memory (free %) and CPU (1-min load ÷ cores) via a
+new pure `computePressure()` classifier, with two tunable thresholds
+(`cpuModerateLoadPerCore` 1.0 / `cpuCriticalLoadPerCore` 1.5) auto-migrated to
+existing agents. It also adds a silent decision audit: every keep/kill decision
+*change* + the reap-path events land in `logs/reaper-audit.jsonl`, served
+read-only at `GET /sessions/reaper/audit`.
+
+## Decision-point inventory
+
+- **Pressure tier computation** (existing decision, widened): now also keys on CPU
+  load. Gates *when* the reaper may consider acting.
+- **Decision audit emission** (new, zero-authority signal): writes an observability
+  row on `(verdict, keptBy)` transitions. No control-flow effect.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+CPU-awareness can raise the tier from `normal` to `moderate`/`critical` during a
+load spike, making genuinely-idle sessions eligible sooner. It cannot cause a
+*working* session to be reaped: the kill path still requires the full positive-idle
+proof, transcript-stasis, render-stasis, 3-observation hysteresis over the
+confirmation window, the two-phase reap, and the per-tick/per-hour budget — all
+unchanged. A transient build spike is smoothed by the multi-observation
+requirement. Default thresholds (1.0/1.5 load-per-core) are deliberately at/above
+full subscription so "moderate" means genuinely oversubscribed.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+`os.loadavg()` is a trailing 1-minute average, so a very brief CPU famine may not
+register, and a famine caused by non-session processes still only lets the reaper
+trim *idle* sessions (it cannot reduce the load of the busy processes themselves).
+This is acceptable — the reaper is one lever among several (load-shed, hosting
+migration, tool/agent sleep); it is not meant to be a complete CPU governor.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. Pressure sensing belongs in the reaper's injected `pressure()` provider; the
+pure classifier lives next to the reaper and is unit-tested without `os`. The audit
+is a sink/reader pair beside the existing `fileAuditSink`, mirroring the
+`/sessions/reap-log` read-surface pattern. No business logic leaks into routes.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+No new blocking authority. The reaper remains the authority it already was; this
+change does not add a brittle check that gates behavior — it widens an existing,
+heavily-confirmed kill path's *eligibility window*, and every safety gate still has
+to clear independently. The decision audit is a pure signal producer (write-only
+observability) with zero authority. `computePressure` is total: unknown/non-finite
+CPU input degrades to the prior memory-only behavior rather than failing.
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- Reads the same `monitoring.sessionReaper` config block; two additive fields.
+- `reapNotify`, the reap-log (`/sessions/reap-log`), and the silently-stopped
+  sentinels are untouched; the new audit writes a SEPARATE file
+  (`reaper-audit.jsonl`), so nothing reading `sentinel-events.jsonl` is affected.
+  (Reaper events previously co-mingled there now route to the dedicated file —
+  reviewed: no consumer filters `sentinel-events.jsonl` for `kind:'session-reaper'`.)
+- Migration: canonical config defaults (`applyDefaults` deep-merge) + a
+  content-sniffed `migrateClaudeMd` section; both idempotent.
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+One new read-only HTTP route (`GET /sessions/reaper/audit`, Bearer-auth, classified
+in the capabilities-discoverability lint). `GET /sessions/reaper`'s `pressure.inputs`
+gains `loadPerCore`/`memTier`/`cpuTier` fields (additive). One new on-disk file
+(`logs/reaper-audit.jsonl`). No Telegram, no attention items, no notifications.
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Cheap and layered. (a) Operationally, set the CPU thresholds absurdly high to
+neutralize CPU-awareness with no deploy; the audit is write-only and harmless to
+ignore. (b) A full revert of the PR restores the prior behavior exactly (the change
+is additive). No data migration, no schema change, no irreversible state.
+
+## Conclusion
+
+Low-risk, additive, reversible. The safety-critical "never reap a working session"
+contract is untouched; the change only widens *when* the existing gated path may
+act and adds zero-authority observability. Ships behind the reaper's existing
+OFF + dry-run default.
+
+## Second-pass review (if required)
+
+Not required — additive change, no new blocking authority, safety classifier
+untouched.
+
+## Evidence pointers
+
+- `tests/unit/session-reaper-pressure-audit.test.ts` — `computePressure` matrix,
+  transition-only decision audit, sink/reader round-trip.
+- `tests/integration/session-reaper-routes.test.ts` — `GET /sessions/reaper/audit`.
+- `tests/e2e/session-reaper-lifecycle.test.ts` — Phase-1 feature-alive for the
+  audit route through the real AgentServer.
+- `tests/unit/feature-delivery-completeness.test.ts` + capabilities-discoverability
+  lint — migration + route-classification parity.
+- `upgrades/NEXT.md` — upgrade guide.