instar 1.2.82 → 1.3.0

package/src/templates/hooks/settings-template.json

@@ -135,6 +135,16 @@
       }
     ],
     "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .instar/hooks/instar/stop-gate-router.js",
+            "timeout": 5000
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [

package/upgrades/1.2.83.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+**SessionReaper — pressure-aware cleanup of idle-but-alive sessions.** A new monitor that reaps sessions sitting idle at a ready prompt (holding memory) — but ONLY when the machine is under memory pressure, and it NEVER reaps a session that might be working. It requires *positive* proof of idleness (turn complete + at a ready prompt + screen byte-static across several checks + no running process + no transcript growth) and KEEPs on any ambiguity. Ships **OFF + dry-run by default** — the only monitor that kills on a heuristic, so it stays dark until an operator validates the dry-run log and opts in. Closes the gap behind the 2026-05-25 fleet pileup (idle sessions accumulated until the machine starved and cross-agent messaging silently failed because agents could no longer spawn).
+
+New read-only endpoint `GET /sessions/reaper` shows the live pressure tier and, per session, the verdict + the exact gate that kept it. `SessionManager` gains a single-writer `terminateSession()` so the existing idle-kill and the reaper can never double-kill. The zombie-kill recovery veto now also defers to the socket + silence sentinels.
+
+## What to Tell Your User
+
+- **Idle sessions get cleaned up under memory pressure — safely.** When your machine fills up with idle agent sessions, this sweeps them so new sessions (and incoming cross-agent messages) don't get refused. It will never reap a session that's actually working. It's off by default; ask me to turn it on after we watch its dry-run log.
+- **You won't notice anything unless you enable it.** No behavior change on update.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| SessionReaper (idle-session cleanup under pressure) | `monitoring.sessionReaper.enabled:true` (leave `dryRun:true` first). Off by default. |
+| Reaper observability | `GET /sessions/reaper` — pressure tier + per-session verdict + keptBy |
+| Single-writer session termination | `SessionManager.terminateSession()` — idle-kill + reaper share one CAS kill path |

package/upgrades/1.3.0.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+**The `/build` stop-hook is now session-scoped — it only nags the session that actually owns the build.** Before, the hook that keeps a build from quitting half-done had no idea *which* of your concurrent sessions started the build, so it fired its "keep working" block into every session — trapping unrelated ones and, worse, spending the owning build's reinforcement budget on each misfire (when that budget hit its cap, the hook stopped protecting the real builder too).
+
+Now `build-state.py` stamps the owning session (its tmux session name, and optionally the Claude session UUID) at build start, and the hook blocks **only** the proven owner. Every other session approve-exits without touching the owner's budget. A build with no owner stamp (legacy state) gets a conservative no-adopt: the hook goes quiet rather than guessing — it never traps a session and never claims ownership.
+
+The hook ships via the always-overwrite path (the inline `getBuildStopHook()` twin in `PostUpdateMigrator`, kept byte-identical to `src/templates/hooks/build-stop-hook.sh` and asserted by a drift test), so every agent gets it on update.
+
+## What to Tell Your User
+
+- **No action needed; this just stops cross-talk between your sessions.** If you run more than one session at once, a build in one of them will no longer pester the others or drain its own "keep going" budget. You won't notice anything unless you run concurrent sessions, in which case it gets quieter.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Session-scoped build stop-hook | Automatic. `build-state.py init` stamps `owner.{tmux,session,stampedAt}`; the hook blocks only the owner. |
+| Owner-stamp flags on `build-state.py init` | `--owner-session "$CLAUDE_CODE_SESSION_ID"` (precision; SKILL wiring is a fast-follow), `--owner-tmux` (override seam). Tmux name is auto-resolved by default. |
+| Conservative no-adopt for un-stamped builds | Automatic. No owner stamp → hook approves without claiming ownership (never traps, never drains). |

package/upgrades/side-effects/build-stop-hook-session-scoping.md

@@ -0,0 +1,133 @@
+# Side-Effects Review — Build Stop-Hook Session-Scoping
+
+**Slug:** `build-stop-hook-session-scoping`
+**Date:** `2026-05-26`
+**Author:** Echo
+**Spec:** `docs/specs/BUILD-STOP-HOOK-SESSION-SCOPING-SPEC.md` (converged round 1, approved by Justin via Telegram topic 13352)
+**Second-pass reviewer:** independent general-purpose review agent (3 findings, all incorporated — see spec §"Review Findings Incorporated")
+
+## Summary of the change
+
+The `/build` Stop hook had no notion of which session owns a build. With one
+shared `build-state.json` and one hook in a checkout, a build started by session
+A fired its "keep working" block into every concurrent session of the same agent
+— trapping unrelated sessions and, on every misfire, incrementing the shared
+`reinforcementsUsed` counter, which drains the owning build's protection budget
+to zero.
+
+This change stamps the owning session at `/build` start (`build-state.py init`
+writes `owner.{tmux,session,stampedAt}`) and teaches the hook to block **only**
+the proven owner. Any other session approve-exits **without** incrementing the
+counter. A build with no owner stamp gets a conservative no-adopt (approve,
+never claim ownership) — it never traps a session and never inverts ownership.
+
+## Files changed (in gate scope = behavior)
+
+- `src/core/PostUpdateMigrator.ts` — the inline `getBuildStopHook()` (the
+  shipping artifact; written to `.instar/hooks/instar/build-stop-hook.sh` on every
+  migration via always-overwrite, and by `init.ts` via `getHookContent`). Added
+  the ownership block between the terminal-phase early-exit and the counter
+  mutation.
+- `src/templates/hooks/build-stop-hook.sh` — the canonical reference template +
+  builtin-manifest fingerprint. Kept byte-identical to the inline twin (asserted
+  by a new drift test).
+
+Out of gate scope but part of the change:
+- `playbook-scripts/build-state.py` — `cmd_init` stamps `owner`; new
+  `--owner-session` / `--owner-tmux` flags; `resolve_owner_tmux()` helper.
+- `tests/unit/build-stop-hook-session-scoping.test.ts` (new, 12 tests),
+  `tests/unit/PostUpdateMigrator-buildStopHook.test.ts` (+1 drift test).
+- `docs/specs/*`, `upgrades/NEXT.md` (docs / release note).
+
+## Decision-point inventory
+
+- **Added**: hook ownership gate — between terminal-phase exit and counter
+  mutation. Decides block (owner) vs approve-no-increment (non-owner / unknown /
+  un-stamped). This is the new decision boundary.
+- **Added**: `build-state.py` owner stamp at init (records identity; no runtime
+  decision, pure data).
+- **Unchanged**: no-state-file exit, terminal-phase exit, and the
+  counter/reinforcement block logic itself (the owner path falls through to the
+  exact pre-existing code).
+
+## Over-block / under-block analysis
+
+- **Over-block risk (trapping a non-owner):** eliminated. A non-owner returns
+  `approve` before reaching the counter. The only block path requires a positive
+  owner match (tmux or session). Tested: non-owner tmux, non-owner session,
+  identity-unknown, and legacy/un-stamped all return approve.
+- **Under-block risk (owner not protected):** bounded and acceptable. The owner
+  is protected whenever `owner.tmux` matches the live tmux (the load-bearing
+  path, proven live) or `owner.session` matches stdin `session_id`. The only
+  under-protection case is an **un-stamped** build (legacy state, or an
+  environment where stamping didn't run) — by deliberate design the hook goes
+  quiet there rather than guess. Forfeiting protection for a stale build is the
+  correct trade vs. trapping the wrong session (spec §"Why conservative-no-adopt").
+- **Bootstrap inversion (the rejected alternative):** an earlier draft let the
+  first session to Stop adopt ownership. The independent review showed this
+  inverts ownership in the real incident pattern (busy owner never stops first).
+  Removed entirely; replaced with conservative no-adopt. Tested: un-stamped state
+  yields approve with `owner` NOT written.
+
+## Level-of-abstraction fit
+
+The fix lives at the same layer as the bug: the Stop hook and the state writer.
+It mirrors the already-shipped autonomous stop-hook's session-scoping ladder
+(tmux-name primary, session-UUID backstop, fail-open) without merging the two
+(explicit non-goal — bash hooks don't share code cleanly; premature abstraction
+avoided). No new module, no new service.
+
+## Signal-vs-authority compliance
+
+The hook is a low-context filter making a binary ownership decision from
+locally-verifiable identifiers (tmux `#S`, stdin `session_id`). It does not
+arrogate higher-level judgment — it only declines to block a session it cannot
+prove it owns. Conservative-by-construction: every ambiguous case resolves to
+`approve` (release), never to `block` (trap). It emits no user-facing messages.
+
+## Interactions
+
+- **Reinforcement counter:** the owner path is byte-for-byte the prior logic, so
+  graduated protection (3/5/10) is unchanged for the owner. Non-owners no longer
+  touch the counter at all.
+- **Restart reconcile:** writes `owner.session` ONLY on a confirmed tmux-owner
+  match with a rotated UUID. Gated strictly behind the tmux match — a non-owner
+  can never clobber `owner.session` (tested explicitly).
+- **stdin consumption:** the hook now reads stdin (`cat`). Stop hooks deliver and
+  close stdin in production (the autonomous hook relies on this), so no hang.
+  Even with no stdin/session, tmux-scoping alone is sufficient (proven live).
+- **Worktree topology:** ownership is keyed on the cwd-independent tmux name, so
+  it is correct whether the owner launched at the main root and `cd`'d into a
+  worktree or launched rooted inside the worktree. The old, fragile `$PWD`-based
+  stopgap is NOT carried forward.
+- **Migration parity:** inline twin is always-overwritten → every agent gets the
+  new hook on update. `build-state.py` rides the repo checkout (the only place
+  the bug occurs — see spec §Migration Parity 2). Drift test prevents
+  template/inline divergence.
+
+## Rollback cost
+
+Low and clean. Revert the two src files (and optionally build-state.py); the
+always-overwrite migration restores the prior hook on next update. The added
+`owner` block in state is additive JSON ignored by the old hook — no destructive
+schema migration. No data loss path.
+
+## Tracked deferral
+
+The SKILL change to pass `--owner-session "$CLAUDE_CODE_SESSION_ID"` (session-UUID
+precision; + its dedicated PostUpdateMigrator migration per Migration Parity §5)
+is a deliberate fast-follow per the approved phasing (Justin approved one-PR-now +
+tiny-follow-up). The flag is already plumbed and tested in `build-state.py`; only
+the SKILL invocation + migration remain. This is tracked, not orphaned.
+
+## Verification
+
+- 3-tier behavior tests (12) drive the **real shipping hook** (from
+  `getHookContent`) against the **real `build-state.py`** with real stdin/tmux
+  seams — covering owner-block, non-owner-no-drain, repeated-non-owner,
+  session-only owner, identity-unknown fail-open, legacy no-adopt, restart
+  reconcile, anti-clobber, terminal-phase. Plus build-state stamp tests (3) and
+  the template/inline drift test (1).
+- Live test-as-self: ran the shipping hook with **real** `tmux display-message`
+  resolution (no seam) in this session (`echo-build-stop-hook-session-scoping`) —
+  confirmed owner→block, non-owner→approve with zero counter drain.

package/upgrades/side-effects/fresh-session-stop-gate-shadow-wiring.md

@@ -0,0 +1,35 @@
+# Side-effects review — fresh-session stop-gate shadow wiring
+
+**Scope**: Complete the conservative first rollout for the fresh-session stop-gate: wire the existing server authority/database, install a Stop-hook router, and default to observe-only shadow mode when the gate is healthy.
+
+**Files touched**:
+- `src/commands/server.ts` — constructs `StopGateDb` and `UnjustifiedStopGate`, persists mode state, passes both into `AgentServer`.
+- `src/server/stopGate.ts` — persists mode flips to `server-data/stop-gate-mode.json`.
+- `src/server/routes.ts` — records SessionStart rows in `StopGateDb` when hook events arrive.
+- `src/core/PostUpdateMigrator.ts` — installs `stop-gate-router.js` and patches `.claude/settings.json` Stop hooks.
+- `src/commands/init.ts` and `src/templates/hooks/settings-template.json` — include the router on fresh installs.
+- `src/core/installCodexHooks.ts` — mirrors the Stop router into Codex hook config.
+- Focused tests cover route mode persistence, hook behavior, Codex registration, and update migration.
+
+**Under-block**: Intentional for this PR. Default mode is `shadow` only when the authority and SQLite log initialize successfully; otherwise the gate is `off`. In shadow mode the hook submits evaluations but always lets the agent exit. Enforcement is reserved for a later explicit operator flip.
+
+**Over-block**: Minimal. The router only emits `{decision:"block"}` when the server is already in `enforce` mode and the server authority returns `continue` with a reminder. All network errors, malformed hook payloads, missing config, hot-path failures, compaction-in-flight, kill-switch, and degraded initialization paths fail open.
+
+**Signal vs authority**: Compliant. The hook collects evidence metadata and simple signals, but never decides whether a Stop is unjustified. The server-side `UnjustifiedStopGate` remains the sole authority for `continue`; the hook is a transport/router.
+
+**External surfaces**:
+- New installed hook file: `.instar/hooks/instar/stop-gate-router.js`.
+- Existing routes become live for real Stop events: `GET /internal/stop-gate/hot-path` and `POST /internal/stop-gate/evaluate`.
+- New persisted mode file: `server-data/stop-gate-mode.json`.
+- Existing SQLite event log: `server-data/stop-gate.db`.
+
+**Migration parity**:
+- Post-update migration writes the router and patches existing Claude settings.
+- Fresh `instar init` installs the router template.
+- Codex hook installer places the router first in the Stop chain before the existing review trio.
+
+**Rollback cost**: Revert this change set. Existing `stop-gate-mode.json` and `stop-gate.db` files can remain on disk; without the router/server wiring they are inert. Emergency runtime rollback without code revert: `instar gate mode off` or set the kill-switch.
+
+**Tests**:
+- `npm test -- --run tests/unit/routes-stopGate.test.ts tests/unit/stop-gate-router-hook.test.ts tests/unit/installCodexHooks.test.ts tests/unit/PostUpdateMigrator-codexHooks.test.ts`
+- `npx tsc --noEmit`

package/upgrades/side-effects/session-reaper.md

@@ -0,0 +1,42 @@
+# Side-Effects Review — SessionReaper
+
+Spec: `docs/specs/SESSION-REAPER-SPEC.md` (v2 CONVERGED + ratified). Build branch `build/session-reaper`.
+
+## What changes for a deployed agent
+
+- A new monitor (`SessionReaper`) is constructed and started at server boot. **Default OFF + dry-run** (`monitoring.sessionReaper.enabled:false, dryRun:true`), so deployed agents get **no behavior change** until an operator opts in. New config block arrives via the standard `ConfigDefaults`/`applyDefaults` migration; operator-set values are never overwritten.
+- New read-only endpoint `GET /sessions/reaper` (503 when unwired, 200 snapshot otherwise).
+- `SessionManager` gains `terminateSession()` (single-writer CAS), `isRelayLeaseActive()`, and `markReaping/clearReaping/isReaping`. The existing idle-kill now funnels through `terminateSession` and skips reaping-leased sessions; `killSession` shares the CAS guard and now sets `endedReason` (its event emissions are unchanged — still no `sessionComplete`).
+- The zombie-kill recovery veto (`activeRecoveryChecker`) is recomposed to include the socket + silence sentinels (previously compaction + rate-limit only) — a strict superset; nothing is dropped.
+
+## Over/under-block analysis (the hard requirement)
+
+The reaper must never reap a working session. Safety rests on positive evidence, not absence of activity:
+- **Under-block (fails to reap a genuinely idle session):** acceptable — the existing 15m/4h idle-kill still runs; the reaper is additive pressure relief.
+- **Over-block (reaps a working session):** the failure that matters. Mitigations: (1) requires a *positive* turn-complete idle-prompt signal; (2) render-stasis — pane byte-identical across all confirm ticks; (3) process + transcript must be quiet, and any *unresolvable* signal (no `claudeSessionId`, Codex/missing/rotated transcript, uninspectable process) forces KEEP, never "quiet"; (4) hysteresis; (5) two-phase reap with a final-grace re-check that aborts on any frame change; (6) Normal pressure tier reaps nothing; (7) bounded per-tick/per-hour budget; (8) auto-disable to dry-run on any ambiguous/failed reap; (9) ships OFF + dry-run.
+
+## Level-of-abstraction / signal-vs-authority
+
+Signals carry confidence and only *recommend*; kill authority sits behind the budget + dry-run + single-writer `terminateSession` CAS + auto-disable. The reaper computes a verdict; it does not own an unbounded kill.
+
+## Interactions
+
+- Composes with (does not fight) existing watchdogs: gate G defers to any recovery-in-flight (now incl. socket/silence); disjoint from OrphanProcessReaper (untracked procs) and SessionWatchdog (active-but-stuck); shares the single-writer kill path with the idle-kill so no double-kill / double-event.
+- Pressure source is freemem-tiered for v1 (advisory; macOS under-reports). Crucially, an over-eager pressure tier can only reap a *genuinely-idle* session sooner — it cannot cause a working session to be reaped, because the classifier protects working sessions independent of tier.
+
+## Rollback
+
+Set `monitoring.sessionReaper.enabled:false` (the default) — fully inert. No data migration; `endedReason` is additive/optional. Revert the branch to remove code; no persisted state needs cleanup beyond an optional `state/session-reaper.json` (absent unless restart-durability is later wired).
+
+## Tests
+
+3-tier: unit (transcript prober, terminateSession CAS, classifier incl. every false-reap vector, config/migration), integration (`/sessions/reaper` + dry-run), e2e (feature-alive + dangerous cases). Wiring-integrity guards the construct→start→pass chain. Live test-as-self on a real in-flight build + a real Codex session precedes merge.
+
+## Phase-3 review fixes (post multi-agent code review)
+
+Independent review confirmed NO blocker to the hard requirement (cannot reap a working session) and surfaced safety-net hardening, all applied:
+- **Reaping-lease leak:** when a matured reap is budget/tier-gated, the reaping lease is now released — previously it could permanently disable the fast idle-kill for that session.
+- **Protected-list wiring:** gate A now reads `SessionManager.getProtectedSessions()` (the resolved list including the `<project>-server` default) rather than the raw config field, preventing spurious auto-disable when the server session goes idle.
+- **Robustness:** `tick()` and `snapshot()` treat a throwing protect-signal as KEEP — never reap on a failed evaluation, and the `/sessions/reaper` route never 500s.
+- **`killSession` contract preserved:** unconditional pane kill retained (only the in-flight guard added; no terminal-status early-return).
+- **Known v1 gap (documented, not a false-reap vector):** the optional `mainProcessActive` CPU/IO-delta signal is not wired in v1; render-stasis is the real-time liveness channel that covers in-process work. Promoting `mainProcessActive` is a tracked enhancement, validated during the dry-run rollout.