instar 1.3.110 → 1.3.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.110",
+  "version": "1.3.112",
   "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-05-30T05:50:52.437Z",
-  "instarVersion": "1.3.110",
+  "generatedAt": "2026-05-30T09:27:07.902Z",
+  "instarVersion": "1.3.112",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -409,7 +409,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -417,7 +417,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -425,7 +425,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -433,7 +433,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -441,7 +441,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -449,7 +449,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -457,7 +457,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -465,7 +465,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -473,7 +473,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -481,7 +481,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -489,7 +489,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -497,7 +497,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -505,7 +505,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -513,7 +513,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -521,7 +521,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -529,7 +529,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -537,7 +537,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -545,7 +545,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -553,7 +553,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -561,7 +561,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -569,7 +569,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -577,7 +577,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -585,7 +585,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -593,7 +593,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -601,7 +601,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -609,7 +609,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -617,7 +617,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -625,7 +625,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -633,7 +633,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -641,7 +641,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -649,7 +649,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -657,7 +657,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -665,7 +665,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -673,7 +673,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -681,7 +681,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -689,7 +689,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -697,7 +697,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -705,7 +705,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -713,7 +713,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -721,7 +721,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -729,7 +729,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -737,7 +737,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -745,7 +745,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -761,7 +761,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "80b68f39cb6113a879db06c1e704cbc1f999b95c8a5021cbf1b0bbac1f0dbb8d",
+      "contentHash": "85676f4062c0ea35989c300891883e3d6db36080e4674bca111020a9d64d1081",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.3.111.md

@@ -0,0 +1,129 @@
+---
+review-convergence: complete
+approved: true
+approved-by: justin (verbal, topic 2169: "Yes, I agree. Please proceed." for the real-world-state fixture framework; AND topic 16566, 2026-05-30: directed the settled-throttle detection fix — "make sure a session can't hang forever due to these API errors ... maybe we should consider sending a message to the user in the meantime")
+---
+
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**1. Pipeline post-mortem lever B: a new test category for real-world-state
+scenarios.** Closes the broader pattern #1 from the 2026-05-29 post-mortem
+— "Tested on fresh state, not real-world state" — which was the largest
+of the five named bug classes (PRs #534, #512, #509, #501, #503, #542
+all instances).
+
+`tests/real-world-state/` joins `unit/`, `integration/`, and `e2e/` as a
+peer test category. Scenarios in it exercise instar against state that
+LOOKS LIKE a real production agent (externalized secrets, multi-100MB
+DBs, wrong-ABI binaries, concurrent state, etc.) rather than the small
+fresh-fixture state the existing suites use.
+
+A two-tier system controls CI cost:
+
+- **'pr' tier** runs every CI shard. Small fixtures, < 30s setup.
+- **'nightly' tier** is gated on `INSTAR_REAL_WORLD_BIG=1` env. Default
+  OFF. For multi-100MB DBs, wrong-ABI binary swaps, concurrency-at-scale
+  scenarios. The skip is loud (`describe.skip` with a clear message) so
+  the coverage gap is visible, not silently absent.
+
+The first scenario — `externalized-config-boot` — targets the #542
+incident class. It asserts that `loadConfig()` (the canonical
+production read path) merges the real `authToken` string back from the
+secret store when the on-disk config holds `{ "secret": true }`, plus
+the same for telegram token/chatId, dashboard PIN, and tunnel token.
+5 tests; verified positive AND destructive-negative (disabling the
+merge call trips 4 of the 5 with the failure modes the bug produced).
+
+This is the LAST recommended post-mortem lever. PR #542 (silent-403)
+through #552 (bare-catch ban) closed individual incident classes; THIS
+one closes the broader pattern that produced them.
+
+**2. Throttled sessions can no longer hang forever on a 429 — the RateLimitSentinel
+now actually fires.** The sentinel that's supposed to ride out Anthropic's
+server-side capacity throttle ("Server is temporarily limiting requests · not
+your usage limit") was built, wired, and enabled — but in the field it had fired
+**zero** times. Sessions would sit dead for 5–10 minutes after a throttle until
+the 15-minute silence fallback limped in with a generic nudge.
+
+Root cause was the detection preconditions, not the recovery machinery. The
+watchdog's throttle check demanded a session be "cleanly idle, zero active child
+processes, at a prompt, throttle string within the last 20 lines." A busy dev
+session almost never satisfies that: it usually has a background shell or MCP
+process alive, and Claude Code's input box + footer + task list render 15–25 rows
+*below* the "API Error:" line, pushing the throttle string out of the 20-line
+window. So the preconditions essentially never held, and the fast recovery never
+engaged.
+
+The fix replaces those brittle gates with a **settled-output signal**: the
+throttle string is matched in a **widened 45-line window** (covers the input box),
+and the pane must be **byte-identical across two consecutive watchdog polls**. An
+actively-working Claude session animates its spinner and elapsed-timer every tick,
+so byte-identical output across polls is a rock-solid "this turn ended and the
+session is stuck" signal — with no process-tree inspection (the gate that made
+busy sessions invisible) and no at-prompt heuristic (the input box used to hide
+the error). Once detected, the existing lifecycle takes over: immediate user
+notice → escalating backoff → neutral re-engage → JSONL-growth verification →
+periodic check-ins → escalation. After a recovery cycle gives up (~30s) a
+still-stuck pane re-emits, so recovery retries **unboundedly until the throttle
+clears** — that is the "a session can never hang forever" guarantee. Every
+sentinel lifecycle transition (detected → resuming → recovered/escalated) is now
+written to `logs/sentinel-events.jsonl`. Tuned by
+`monitoring.watchdog.rateLimitSettleMs` (default 20000ms).
+
+## What to Tell Your User
+
+First, nothing visible in normal operation from the test-framework change. There's
+an opt-in heavier set of local tests for big real-world fixtures; CI runs the fast
+set by default, so day to day nothing changes for you.
+
+Second, mostly invisible and strictly an improvement: if one of your sessions hits
+Anthropic's temporary server throttle (a "Server is temporarily limiting requests"
+error — their side, not your usage limit), it will now recover on its own instead
+of silently sitting dead. You'll get a brief heads-up — "hit a temporary throttle,
+I'm backing off, you haven't been dropped" — plus check-ins while it waits and a
+"back online" when it clears. It keeps retrying until the throttle lifts, however
+long that takes. Nothing for you to do, no configuration needed.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `tests/real-world-state/` test category | Add a new scenario file there. Use `describeAtTier('pr', …)` or `describeAtTier('nightly', …)`. |
+| Tier-gated execution | 'pr' runs every shard; 'nightly' skips unless `INSTAR_REAL_WORLD_BIG=1`. |
+| `makeAgentFixture()` helper | Per-test scratch dir simulating an agent home (projectDir + .instar/). Returns a cleanup callback. |
+| Externalized-config-boot regression check | `loadConfig()` against the externalized shape is asserted on every PR. #542's class can never regress silently. |
+| Settled-throttle detection | Automatic — the SessionWatchdog recovers a 429-stuck session via a byte-identical-pane signal over a widened scan window, so busy dev sessions are no longer invisible to the RateLimitSentinel. |
+| Unbounded throttle retry | Automatic — recovery re-engages after each escalation cycle, guaranteeing a throttled session cannot hang forever. |
+| `monitoring.watchdog.rateLimitSettleMs` | Optional tuning for how long a throttled pane must be settled before recovery engages (default 20s). |
+
+## Evidence
+
+**Real-world-state fixture framework (#555):**
+- 5 new tests in `tests/real-world-state/externalized-config-boot.test.ts`,
+  all green. Tier system verified both directions (sentinel test).
+- Destructive-negative verified: disabling `mergeConfigWithSecrets()` in
+  `Config.ts` trips 4 of the 5 tests with the exact failure modes
+  (`{ secret: true }` returned as authToken, telegram token leaks, etc.).
+- Existing `secret-migrator.test.ts`, `config-secret-merge.test.ts`,
+  `secret-store.test.ts` remain green. `tsc --noEmit` clean.
+- Side-effects: `upgrades/side-effects/real-world-state-fixture-framework.md`.
+
+**Settled-throttle detection:**
+- **Reproduction (unit):** `tests/unit/rate-limit-detection.test.ts` builds the
+  exact stuck-pane shape — the `API Error:` line followed by Claude's input box +
+  footer + ~14 trailing blank rows. `detectRateLimited(paneWithInputBox())` is
+  **false** with the default 20-line window (the bug) and **true** at 45.
+- **Observed before (production, this box, 2026-05-30):** zero RateLimitSentinel
+  fires across every server instance overnight (no `rateLimitedAtIdle`, no
+  `[RateLimitSentinel] detected`, no `[Watchdog] rate-limited` in `logs/server*.log`)
+  while three live sessions sat frozen on `Churned for 7m 43s` / `Sautéed for
+  9m 28s` / `Baked for 5m 58s`; only the 15-min `ActiveWorkSilenceSentinel` engaged.
+- **After:** settled detection emits → existing backoff/verify lifecycle runs +
+  writes `throttle-detected`/`throttle-resuming`/`throttle-recovered`. Live
+  end-to-end verification on the deploy box before closing the incident.
+- Side-effects: `upgrades/side-effects/throttle-settled-detection.md`. Spec:
+  `docs/specs/rate-limit-sentinel.md`.

package/upgrades/1.3.112.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**The UnjustifiedStopGate now has a self-circuit-breaker, fixing a chronic
+`/health` degraded-flood + subprocess churn on subscription agents.**
+
+The stop gate rules on Stop events via a Haiku judgment call. On subscription
+agents (no API key) that call goes through `ClaudeCliIntelligenceProvider`, which
+spawns a `claude -p` subprocess — irreducibly ~5-6s — but the gate's client budget
+is `clientTimeoutMs = 2000`. So on every subscription agent the gate times out on
+EVERY stop: it fail-opens (never ruling), wastefully spawns+kills a `claude`
+subprocess, and emits one `DegradationReport` per stop — flooding `/health` with
+identical `degraded` entries (observed 22+) that look alarming but mean nothing.
+
+After `breakerThreshold` (default 3) consecutive provider failures the gate opens
+its breaker: `evaluate()` fails open IMMEDIATELY without spawning, for
+`breakerCooldownMs` (default 5 min), then retries once (half-open); a reachable
+provider resets it. The fail-open decision is unchanged — `breakerOpen` allows the
+stop exactly like `timeout` — so the breaker only makes the unavoidable fail-open
+fast (no doomed subprocess) and quiet (no per-event degradation, no rollup skew).
+`breakerThreshold: 0` disables it.
+
+## What to Tell Your User
+
+Mostly invisible. This fixes a false alarm: on agents running without an API key, a
+safety check was timing out on every stop, which made my health page show
+"degraded" with lots of identical entries even though nothing was actually wrong —
+and it was wastefully launching and killing a helper process each time. I added a
+self-healing circuit breaker so it stops the wasted work and the false alarms and
+recovers on its own. My actual behavior when stopping is unchanged.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Stop-gate circuit breaker (self-healing) | Automatic; tune via the gate's `breakerThreshold` / `breakerCooldownMs` |
+| Disable the breaker | `breakerThreshold: 0` |
+| Breaker telemetry | `UnjustifiedStopGate.breakerState()` |
+
+## Evidence
+
+- **Live reproduction:** with all other agents paused (no load), Echo's `/health`
+  read `degraded` with 22+ identical `unjustifiedStopGate.timeout` entries; a
+  `claude -p` haiku call in the agent cwd returned in ~5-9s, far over the 2000ms
+  budget — confirming the timeout-on-every-stop + spawn-then-kill churn.
+- **Tests:** `tests/unit/UnjustifiedStopGate-breaker.test.ts` (5) — opens after K
+  failures and stops calling the provider; half-open retry after cooldown;
+  reachable-provider reset; `breakerThreshold=0` disables; a real timeout counts.
+  Existing gate/route/db suites (42) green. `tsc` + lint clean.
+- Spec: `docs/specs/STOPGATE-CLI-CIRCUIT-BREAKER-SPEC.md`. Side-effects:
+  `upgrades/side-effects/stopgate-cli-circuit-breaker.md`.