instar 1.2.83 → 1.3.1

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.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/1.3.1.md

@@ -0,0 +1,27 @@
+# Unreleased
+
+## What Changed
+
+"Open this" in the Threadline hub is now a deterministic, structural action instead of something the agent has to interpret (CMT-529). Previously the agent could — and did — ramble a reply instead of creating a topic.
+
+- **Structural intercept.** When a message in the Threadline hub topic is exactly "open this" / "tie this to <topic>", the system catches it at the one inbound seam BOTH message paths converge on (`telegram.onTopicMessage`) and binds the conversation to a topic before any agent interprets it. Ordinary hub chat falls through to the agent unchanged. FAIL-OPEN.
+- **Bare "open this" auto-picks the most-recent** unbound conversation (the one you're looking at) instead of asking "which one?". The legacy-state ordering bug that made "most recent" unreliable is fixed (migrated hub entries now preserve their original order instead of all sharing one timestamp).
+- **Readable topic names.** A newly-opened topic is named from what the conversation is about (capped, charset-scrubbed, and a safe fallback if the content looks like a secret) instead of a cryptic `peer · threadId`.
+- The `POST /threadline/hub/bind` API is unchanged (it still returns 409 on ambiguity for scripted callers); the route and the intercept now share one `bindHubConversation` helper.
+
+## What to Tell Your User
+
+When you're looking at the Threadline topic and say "open this", I now reliably spin up a topic for that conversation — no more rambling, no judgment call on my end. It opens the one you're looking at and names it after what it's about. You can also say "tie this to <one of my topics>" to file it into an existing topic.
+
+## Summary of New Capabilities
+
+- Deterministic "open this" / "tie this to X" hub commands (intercepted structurally, both inbound paths).
+- Auto-pick most-recent-unbound on bare "open this"; readable, scrubbed topic names.
+- Shared `bindHubConversation` helper behind both the intercept and the API route.
+- Legacy hub-state ordering fix so "most recent" is trustworthy.
+
+## Evidence
+
+- Verified against v1.3.0; design converged by two reviewers — the decisive catch was the dual-path trap (intercept must sit at `onTopicMessage`, the convergence both lifeline-forward and server-polling reach, not just `/internal/telegram-forward` where it'd be dead code for polling agents). Auto-pick, no-double-post, and topic-name privacy also folded in.
+- 3-tier tests: unit for `parseHubCommand` (both sides of the boundary), `bindHubConversation` (open/tie/404/409/autoPick/readable-name), and the legacy-ordering fix; integration parity for `POST /threadline/hub/bind`; full threadline suite green (1569 unit/integration + 329 e2e, zero regressions). Typecheck + build clean.
+- Independent second-pass review of the diff; live test-as-self on Codey (type "open this" into the hub → a readable-named topic is created + bound, no ramble).

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/threadline-open-this-deterministic.md

@@ -0,0 +1,45 @@
+# Side-Effects Review — Deterministic "open this" (CMT-529)
+
+**Version / slug:** `threadline-open-this-deterministic`
+**Date:** 2026-05-26
+**Author:** Echo
+**Second-pass reviewer:** (pending — required; message-routing intercept)
+
+## Summary of the change
+
+Makes "open this" / "tie this to <topic>" in the Threadline hub topic a DETERMINISTIC structural intercept instead of agent-interpreted (which failed — the agent rambled instead of binding). New `src/threadline/hubCommands.ts`: `parseHubCommand` (pure, tightly-anchored) + `bindHubConversation` (shared logic extracted from the route; discriminated result; readable+scrubbed topic name; `autoPick`). The intercept lands in `telegram.onTopicMessage` (`wireTelegramRouting`, src/commands/server.ts) — the convergence point BOTH inbound paths reach — via a late-bound `getHubDeps()` accessor (deps constructed after wiring). `POST /threadline/hub/bind` refactored to call the same helper (autoPick=false → 409 preserved for the API). `CollaborationSurfacer.load()` legacy migration now stamps `surfacedAt` by index (was epoch) so ordering works. Decision point: the hub-command intercept (routing, not block/allow).
+
+## Decision-point inventory
+
+- `telegram.onTopicMessage` hub-command intercept — **add** — for the hub topic + a matched command, bind structurally + return before session injection.
+- `POST /threadline/hub/bind` — **modify** (refactor to shared helper; behavior unchanged for the API).
+- `CollaborationSurfacer.load()` legacy `surfacedAt` — **modify** — index-based ordering.
+
+## 1. Over-block
+No block/allow surface. The intercept only fires when `topicId === hub` AND `parseHubCommand` matches a tightly-anchored command (`/^open(?:\s+this)?\s*[.!]?$/i`, `/^(?:tie|bind)\s+this\s+to\s+.../i`). Ordinary hub chat ("can you open this and explain?") returns null → falls through to the agent. FAIL-OPEN: any intercept error logs + falls through.
+
+## 2. Under-block
+A creatively-phrased command ("open it please") won't match → falls through to the agent (who still has the #392 CLAUDE.md guidance as backstop). Acceptable; common forms covered.
+
+## 3. Level-of-abstraction fit
+Correct: the intercept sits at `onTopicMessage` alongside the existing `/new`/slash/fix-command interceptions — the single seam both the lifeline-forward and server-polling paths converge on (avoids the dual-path dead-code trap that bit the sentinel + warrants-reply gate). `bindHubConversation` composes existing primitives (ConversationStore.mutate, findOrCreateForumTopic, CommitmentTracker.mutate, surfacer.markBound/noteInHub) — no re-implementation.
+
+## 4. Signal vs authority compliance
+No new blocking authority. The intercept is a deterministic router (match → bind → return), the bind is an authoritative state mutation on explicit operator action, parseHubCommand is a pure classifier. Per `docs/signal-vs-authority.md`: routers/sinks, not gates.
+
+## 5. Interactions
+- **No double-bind/post:** `bindHubConversation` posts to the new topic + one `noteInHub`; the intercept does NOT add a third message (reuses the helper's confirmation), and `return`s so no session injection. One bind per command (markBound makes a re-issued "open this" pick the next unbound).
+- **Order vs other intercepts:** sits after `/new` + slash + (and, on the forward path, the sentinel) — emergency-stop still wins. No shadowing.
+- **autoPick split:** intercept (human) autoPick=true → most-recent; API path autoPick=false → 409. Distinct, intentional.
+
+## 6. External surfaces
+New `getHubDeps` param on `wireTelegramRouting` (internal). Hub stays silent. Topic name from gist is **capped ~40 chars, charset-scrubbed, and falls back to `<peer> · <threadId8>` on empty/credential-like gist** (a cold first message could contain a secret — never splash it into a chat-list-visible title). Template + `migrateClaudeMd` note that "open this" is now structural (Agent Awareness + Migration Parity).
+
+## 7. Rollback cost
+Localized: new hubCommands module, one route refactor, one intercept block + a param threaded to two call sites, one load() timestamp line, the naming helper. Clean `git revert`. The legacy `surfacedAt` change is read-time + idempotent (no data migration). `getHubDeps` is an optional param (older callers unaffected).
+
+## Second-pass review
+
+**Concur with the review** (independent reviewer, 2026-05-26). All seven checks verified against the diff: (1) `getHubDeps` late-bind is TDZ/null-safe — the closure only runs at message-time, long after the `const` deps initialize; the `&& telegram` guard narrows `TelegramAdapter|undefined`; `commitmentTracker` is unconditionally constructed + null-guarded internally; tsc clean. (2) Intercept gates on `getHubTopicId()` match, falls through otherwise, whole block try/catch fail-open. (3) `parseHubCommand` anchoring verified empirically across 15 inputs — "open this"/"open"/"Open This." fire; "can you open this and explain?" / "open this conversation please" fall through. (4) `bindHubConversation` returns a discriminated result, never touches res/req; route maps 400/404/409/500. (5) Early `return` skips no essential side-effect — consistent with the adjacent `/`/`/new` intercepts (no message logging in this handler). (6) `topicNameFor` caps 40 / scrubs / credential-fallback. (7) The CMT-529 migrator re-patch is idempotent + correctly scoped (matches only OLD CMT-519 agents; non-greedy anchored regex; 2nd run no-op).
+
+Non-blocking notes (no action needed): an 18-digit "tie this to <huge number>" would be treated as a name not an id (unrealistic, harmless); legacy `surfacedAt=new Date(index+1)` ISO strings stay lexicographically monotonic well past realistic array sizes.