instar 1.2.83 → 1.3.0

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`