instar 1.3.372 → 1.3.374

package/upgrades/side-effects/stop-hook-idle-backoff.md

@@ -0,0 +1,30 @@
+# Side Effects — stop-hook-idle-backoff
+
+## Files touched
+
+- `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh` — new IDLE_BACKOFF block between the session-id reconcile and the iteration increment: measures the agent's active gap since the last re-injection via a per-topic sidecar (`<topic>.local.backoff.json`), counts consecutive quick stops, and sleeps tiered (3+ → 30s, 6+ → 120s, 10+ → 300s) before emitting the block decision. Poll-sleeps in 5s chunks with early-break on new inbound message / emergency-stop flag / state-file removal; re-checks terminal conditions after the sleep (emergency → notify + clear + exit; state gone → exit). Sleep self-clamps to a third of the hook's own registered Stop timeout read from `.claude/settings.json` (unreadable or codex-mode → conservative 20s). Env seams: `INSTAR_HOOK_BACKOFF_DISABLE`, `_QUICK_SECS`, `_T1/_T2/_T3`, `_POLL_SECS`, `_MAX_SLEEP`.
+- `src/core/PostUpdateMigrator.ts` — stop-hook migration marker bumped `RESTART_NOTE_SILENT` → `IDLE_BACKOFF` so existing agents receive the paced hook (customized hooks still untouched).
+- `tests/unit/autonomous-stop-hook-idle-backoff.test.ts` — new (13 tests; executes the real hook).
+- 7 existing hook-exec test harnesses (`autonomous-completion-condition`, `autonomous-stop-hook-cwd-anchor`, `-codex-gate`, `-topic-keyed`, `-session-clock`, `autonomous-multi-session`, e2e `autonomous-restart-resume-lifecycle`) — gain `INSTAR_HOOK_BACKOFF_DISABLE: '1'` in their env so suites that exec the hook repeatedly never hit a real sleep.
+- `tests/unit/autonomous-stop-hook-notify.test.ts` — terminal-notify call-site count 6 → 7 (the backoff's mid-sleep emergency re-check adds one) + marker-history assertion advanced to `IDLE_BACKOFF`.
+
+## Behavioral side effects
+
+1. **An idle autonomous session re-injects its frame ~once per 5 minutes instead of ~15×/min** — ≥98% reduction in idle-loop token burn (the 2026-06-06 rapid-idle-refire waste: thousands of no-op re-injections over one operator sleep).
+2. **A productive loop is untouched**: any iteration whose active time exceeds QUICK_SECS (120s) resets the counter; tiers only engage after 3+ consecutive quick stops.
+3. **Reaction to a new user message while idle-deep**: ≤ POLL_SECS (5s) — the sleep breaks early on a new inbound file for the topic. Emergency stop and job stop/stop-all break the same way.
+4. **One new sidecar file per topic** in `.instar/autonomous/` (`<topic>.local.backoff.json`). The server's autonomous-dir enumeration filters on `.local.md`, so the sidecar is invisible to it. Stale sidecars self-reset on the next run (runStartedAt mismatch) and are removed on the backoff's own terminal exits; sidecars left by other terminal paths are inert.
+5. **Migration**: every existing agent's stock stop-hook is overwritten at next migration run (marker bump). Customized hooks (no stock fingerprint) skipped, as before.
+
+## Risks / blast radius
+
+- **Hook timeout vs sleep** (the strand-class risk): a Stop hook killed by the host fails OPEN → session exits → loop strands silently. Mitigated three ways: the sleep self-clamps to registered-timeout/3 (live read of settings.json; the shipped registration is 10000s, so the clamp is far above T3); unreadable/missing registration falls back to a 20s cap; codex registrations get the same 20s cap. Worst case is therefore reduced pacing, never a stranded loop.
+- **Sentinel interplay**: a session sleeping inside its Stop hook shows no pane activity for up to 5 min. The silence/socket sentinels target sessions with active work or dropped sockets, not completed turns awaiting the next injection; observed-not-theorized verification rides the dogfood loop after deploy.
+- **Delayed sentinel/tmux-injected text** (not Telegram-routed): anything typed directly into the pane during a sleep sits in the input buffer until the next turn — bounded by T3 (5 min). Telegram messages are NOT affected (early-break).
+- **Counter semantics during conversation**: replying to a user message usually takes < QUICK_SECS, so the counter can keep rising across an active conversation — but each new inbound message breaks the sleep within 5s, so perceived latency stays ≤5s; pacing only persists between messages, which is the desired behavior.
+
+## Tests
+
+- `tests/unit/autonomous-stop-hook-idle-backoff.test.ts` (13): counter evolution (first-stop zero, quick-rise, long-gap reset, new-run reset), tier engagement + MAX_SLEEP clamp + DISABLE seam, early-breaks (inbound / emergency / state-removal, real async timing), static safety properties (timeout self-clamp present, sidecar suffix invisible to server), migration upgrade path (prior-era hook gains IDLE_BACKOFF, retains RESTART_NOTE_SILENT).
+- All 8 pre-existing hook suites pass with the disable seam (57 tests across the affected files).
+- Full typecheck clean; `bash -n` clean.

package/upgrades/side-effects/transfer-place-half-journal.md

@@ -0,0 +1,74 @@
+# Side-Effects Review — Transfer PLACE-half journaling (coherence finding #5)
+
+**Version / slug:** `transfer-place-half-journal`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`POST /pool/transfer` now lands the PLACE half of a deliberate move: for a quiet
+topic (never-seen or released ownership record) it CASes `place→claim` for the
+target as one synchronous pair and journals the placement (`reason: 'user-move'`,
+real epoch) so the entry replicates to the pinned-to machine — closing the
+"no machine ever produced the evidence the #926/#930 read-side fallbacks read"
+gap proven live (the working-set reflex answered `not-owner` after a transfer
+even on v1.3.371+). A resting `placing` record naming the target is repaired via
+claim (the bug-#11 shape). Response gains `placedOwnership`.
+
+## Decision-point inventory
+
+One: which ownership-record shapes the block may mutate. Active-with-target →
+skip (no-op). Never-seen/released → place+claim. Resting placing-with-target →
+claim repair. Everything else (active other-machine, placing other-machine,
+transferring) → strictly untouched.
+
+## 1. Over-block
+
+Nothing new is rejected; the route's accept/reject surface is unchanged. The
+block only ever ADDS ownership evidence; on any CAS refusal the transfer still
+succeeds exactly as before (`placedOwnership:false`).
+
+## 2. Under-block
+
+A topic actively owned by a third machine still journals nothing on transfer
+(deliberate — never steal a live session; the pin drives re-placement on real
+traffic, which CASes and journals through the existing router chokepoint). A
+`placing` record naming a different machine is also left alone — repairing
+someone else's in-flight placement is not this handler's call.
+
+## 3. Level-of-abstraction fit
+
+Right layer: the same handler that already owns the RELEASE half (and its
+journaling) now owns the PLACE half — the two halves of one move live at one
+chokepoint. The state machine itself is untouched; the handler composes the
+existing legal transitions (place, claim) exactly as the router's confirmClaim
+precedent does.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No blocking authority added. Both CAS failures and journal failures are
+best-effort (`@silent-fallback-ok` / observability-never-endangers-the-observed):
+the transfer response never fails because of this block, and the journal entry
+is evidence, not actuation.
+
+## 5. Interactions
+
+- **SessionRouter**: claim immediately follows place so the record never RESTS at
+  `placing` — the shape that queues every later message as ownership-contention
+  (bug #11). A real message for the topic now finds `active(target)` and forwards.
+- **Working-set reflex (#926/#930)**: the journaled entry replicates and the
+  target's wsOwnerOf journal-placement fallback finally has something to read.
+- **Post-transfer closeout**: unchanged — it keys on ownership moving away, which
+  this block makes MORE accurate (the registry now reflects the deliberate move).
+- **Ownership nonces**: fresh `tplace`/`tclaim` nonces per call; no replay overlap
+  with router (`:c:`/`:cl:`) or release (`:rel:`) nonce families.
+
+## 6. External surfaces
+
+One additive JSON response field (`placedOwnership`). No new routes, no config,
+no notifications, no Telegram. Journal entries use the existing topic-placement
+kind/op-key contract (`${topic}:${epoch}` — real epochs, so no dedupe collision
+with router-emitted entries).