instar 1.3.372 → 1.3.373

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.372",
+  "version": "1.3.373",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-06T14:48:38.252Z",
-  "instarVersion": "1.3.372",
+  "generatedAt": "2026-06-06T16:43:09.971Z",
+  "instarVersion": "1.3.373",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "05bcd825be155ac5b141d452f9cab268a05e72c8220b59811ee7f5e97567881b",
+      "contentHash": "cc98104488380bc9605845894368ac4c38cf66fa27bd50305d47073aeaf08b3b",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.373.md

@@ -0,0 +1,59 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The autonomous loop's Stop hook re-feeds the full frame + context to the model
+after every turn. When a session was idle/holding (waiting on the operator, a
+budget window, or a peer), turns completed in ~4s and the hook re-injected
+~15×/min — thousands of token-heavy no-op re-injections over one operator
+sleep (the 2026-06-06 rapid-idle-refire waste).
+
+The hook now measures the agent's ACTIVE time between re-injections (slept
+time never counts) and backs off when consecutive stops arrive quickly: 3+
+quick stops → 30s wait, 6+ → 2 min, 10+ → 5 min, before the next re-injection.
+One real burst of work resets the counter instantly — a productive loop never
+waits. During a wait it polls every 5s and breaks early on a new inbound
+message for its topic, the emergency-stop flag, or its job being stopped — a
+user message gets through in ≤5s. The wait self-clamps to a third of the
+hook's own registered Stop timeout (a host-killed Stop hook fails OPEN and
+strands the loop; the clamp guarantees noise over strand).
+
+State is a per-topic sidecar (`.instar/autonomous/<topic>.local.backoff.json`)
+invisible to the server. Existing agents receive the paced hook via a
+PostUpdateMigrator marker bump (`RESTART_NOTE_SILENT` → `IDLE_BACKOFF`);
+customized hooks are left untouched.
+
+## What to Tell Your User
+
+Idle autonomous sessions now sip tokens instead of gulping them — an agent
+holding overnight re-checks roughly every 5 minutes instead of every 4
+seconds, and still reacts to your message within ~5 seconds. Busy sessions
+are completely unaffected.
+
+## Summary of New Capabilities
+
+- Autonomous stop-hook idle backoff: tiered pacing (30s/120s/300s) of frame
+  re-injection after 3/6/10 consecutive quick stops; instant reset on real work.
+- Early-break responsiveness: new inbound message / emergency stop / job stop
+  cut any backoff wait to ≤5s.
+- Timeout self-clamp: the backoff reads its own Stop-hook registration and
+  never sleeps past a third of it (20s conservative fallback) — fail-toward-
+  noise, never toward a stranded loop.
+- Env seams for operators/tests: `INSTAR_HOOK_BACKOFF_DISABLE`, `_QUICK_SECS`,
+  `_T1/_T2/_T3`, `_POLL_SECS`, `_MAX_SLEEP`.
+- Migration: existing agents get the paced hook automatically (marker bump
+  `RESTART_NOTE_SILENT` → `IDLE_BACKOFF`).
+
+## Evidence
+
+- `tests/unit/autonomous-stop-hook-idle-backoff.test.ts` — 13 tests executing
+  the REAL hook: counter evolution, tier engagement (measured wall-time),
+  long-gap + new-run resets, MAX_SLEEP clamp, DISABLE seam, async early-breaks
+  (inbound / emergency / state-removal), static safety assertions, migration
+  upgrade path.
+- 57 tests across the 8 pre-existing hook suites pass (disable seam added to
+  their harnesses so repeated hook execs never sleep).
+- Typecheck clean; `bash -n` clean.

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.