instar 1.2.32 → 1.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.32",
+  "version": "1.2.33",
   "description": "Persistent autonomy infrastructure for AI agents",
   "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-22T18:52:11.369Z",
-  "instarVersion": "1.2.32",
+  "generatedAt": "2026-05-22T20:34:00.772Z",
+  "instarVersion": "1.2.33",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -392,7 +392,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -400,7 +400,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -408,7 +408,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -416,7 +416,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -424,7 +424,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -432,7 +432,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -440,7 +440,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -448,7 +448,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -456,7 +456,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -464,7 +464,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -472,7 +472,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -480,7 +480,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -488,7 +488,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -496,7 +496,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -504,7 +504,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -512,7 +512,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -520,7 +520,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -528,7 +528,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -536,7 +536,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -544,7 +544,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -552,7 +552,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -560,7 +560,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -568,7 +568,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -576,7 +576,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -584,7 +584,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -592,7 +592,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -600,7 +600,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -608,7 +608,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -616,7 +616,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -624,7 +624,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -632,7 +632,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -640,7 +640,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -648,7 +648,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -656,7 +656,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -664,7 +664,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -672,7 +672,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -680,7 +680,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -688,7 +688,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -696,7 +696,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -704,7 +704,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -712,7 +712,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -720,7 +720,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -728,7 +728,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -744,7 +744,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "41bcd0a33fc72e73398acb708c966936a63afad1c9430dae8b11a7c50a38dbac",
+      "contentHash": "8e2047a994d15f6e332d09d2e67d83c39f88541312674b50a4976d28d54e04b8",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1440,7 +1440,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "6e996e6ea45338ffe019e539eaa738af05d5ad9a1ca35c9d93a8ba198599f759",
+      "contentHash": "d8d019cc9691191bca75fabd916fa5a4400bb614abcd48b49afa4f650d533fdd",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {
@@ -1448,7 +1448,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "c8a43e38d2707bf0f1e7f3bfc958b5f6f885a4cfc383cb99135100caad6fc901",
+      "contentHash": "7241736a08f63b09d8b1abda0965dadb37127c95aa6e4ac11bafee05661dbe9f",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/upgrades/1.2.33.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- minor = new agent-facing capability (RateLimitSentinel — server-throttle survival) without breaking changes. Default-on; off-switch is one config flag. -->
+
+## What Changed
+
+**feat(monitoring): RateLimitSentinel — ride out Anthropic's server-side throttle instead of dropping the session.**
+
+Anthropic recently started surfacing a new Claude Code error: *"Server is temporarily limiting requests (not your usage limit) · Rate limited"* (and the related *"Repeated 529 Overloaded errors"*). This is a short-lived, shared-capacity throttle on Anthropic's side — **not** your account's usage cap. Claude Code already auto-retries it ~10 times with its own exponential backoff before it ever shows the message, so by the time you see it on screen, those built-in retries are exhausted and the session sits idle with no reply ever relayed to the user.
+
+Instar's prior behavior made this worse, not better. SessionManager's idle-error path fired a single *immediate* nudge the moment it saw an "API Error:" — which slams straight back into the live throttle, burns quota for nothing, and then goes silent until the zombie-killer reaps the session. There was no user-facing signal that the agent was throttled-but-alive.
+
+This release adds a dedicated **`RateLimitSentinel`** (same own-the-lifecycle shape as `CompactionSentinel`) that owns recovery end to end:
+
+1. **Detect** — a pure predicate (`src/monitoring/rateLimitDetection.ts`) distinguishes the server throttle from the user's plan/usage quota (PresenceProxy's domain — wait-for-reset, not retry) and from Claude's own in-progress retry spinner (the framework still owns it). Strings are taken from the user's live screenshot and the Claude Code error reference, not invented.
+2. **Notice immediately** — a fixed-template message tells the user they're throttled, backing off, and *not* dropped. No LLM call.
+3. **Back off BEFORE re-engaging** — escalating schedule (30s → 1m → 2m → 5m, last value repeats). This is the core quota-burn mitigation: we sit on top of Claude's already-exhausted retries instead of hammering.
+4. **Re-engage neutrally** — a plain "continue where you left off" nudge, *not* the compaction-resume payload (which would falsely tell the agent its memory was reset).
+5. **Verify** — JSONL size/mtime growth means Claude processed the nudge and the throttle cleared.
+6. **Check in** — periodic user updates at verify-fail transitions, minimum-spacing gated so it never spams.
+7. **Escalate** — after a capped attempts/window envelope (6 attempts or 30 min), a final "this is on Anthropic's side, status.claude.com has live notices, message me to retry" message.
+
+**Two signal triggers, one authority.** Per `feedback_signal_vs_authority`: both `SessionWatchdog` (periodic poll) and `SessionManager` (idle-error path) emit signals; the sentinel holds sole recovery authority and dedupes the two. SessionManager skips its single-nudge for the throttle case and hands ownership over — *without* consuming the nudge token, so a later generic API error still gets its one nudge.
+
+**Coexistence with the other recovery engines:**
+- **Zombie-kill veto** — `setActiveRecoveryChecker` now ORs both sentinels (the predicate is *edited*, not a second call — a second `setActiveRecoveryChecker` would silently drop the compaction veto). The reaper won't kill a session mid-throttle-recovery.
+- **Bidirectional deferral** — `RateLimitSentinel` and `CompactionSentinel` each defer to the other via `deferIf`, so the two never inject into one pane concurrently.
+- **PresenceProxy suppression** — while a throttle recovery owns a topic's session, PresenceProxy stays silent across *every* tier (including Tier 1), so the user hears one voice. It re-checks after a delay and resumes only if the agent is still silent post-recovery.
+
+**Opt-in retry-count raise.** A new `claudeCodeMaxRetries` config field, when set, injects `CLAUDE_CODE_MAX_RETRIES` at session spawn so Claude rides out transient throttle/overload longer before surfacing to the sentinel. Unset by default (Claude's default of 10 stands) so genuine outages aren't masked.
+
+Spec: `docs/specs/rate-limit-sentinel.md` (ELI16 overview up top, full technical spec below). The spec folded in an adversarial side-effects review (over/under-block, race conditions, quota-burn safety, signal-vs-authority, interactions with the other sentinels) before build.
+
+## What to Tell Your User
+
+Sometimes Anthropic's servers get briefly overloaded and slow everyone down for a minute or two. This is different from running out of your usage — it's a temporary "the servers are busy right now" speed bump on their end. Before this release, when that happened your agent could go quiet with no explanation, and the way it tried to recover actually wasted your usage hours by knocking on the door over and over.
+
+Now your agent handles it gracefully. The moment it hits one of these server slowdowns it sends you a quick note — *"heads up, Anthropic's servers are briefly throttling, I'm backing off, you haven't been dropped"* — then waits a bit, tries again, waits a little longer, tries again, and keeps you posted while it's stuck. When the servers free up, it picks right back up where it left off and tells you it's back. If it's still stuck after about half an hour, it lets you know it's an Anthropic-side issue and that you can just message it to retry.
+
+You don't have to do anything — it's on by default for every agent. If you ever want the old behavior back, it's a single config switch.
+
+## Summary of New Capabilities
+
+- **`RateLimitSentinel`** — new monitoring module that owns the full detect → notice → backoff → resume → verify → check-in → escalate lifecycle for Anthropic's server-side throttle.
+- **`GET /rate-limit/status`** — read-only observability route (Bearer-gated): active recoveries with `sessionName`, `status`, `attempts`, `nextBackoffMs`. Returns `{ enabled: false, active: [] }` (never 503) when the sentinel is absent.
+- **`monitoring.rateLimitSentinel` config** — `{ enabled: true }` by default; `enabled: false` restores pre-feature behavior. Backoff schedule, max attempts, window, verify window, check-in spacing, and dedupe window are all overridable.
+- **`claudeCodeMaxRetries` config** — opt-in `CLAUDE_CODE_MAX_RETRIES` raise at session spawn.
+- **Migration parity** — `rateLimitSentinel` default flows to existing agents automatically via the canonical `ConfigDefaults` registry applied by `PostUpdateMigrator` on update. No agent ships dead.
+
+## Evidence
+
+- **Tier 1 unit tests:** `tests/unit/RateLimitSentinel.test.ts` (14 tests) covers the lifecycle, dedupe across both triggers, escalation on attempt/window exhaustion, escalation when resume declines, check-in min-spacing, independent per-session recovery, and `listActive` shape. `tests/unit/rate-limit-detection.test.ts` (12 tests) covers throttle-vs-usage-limit-vs-retry-spinner discrimination with real fixture strings. All 26 passing.
+- **Tier 2 integration tests:** `tests/integration/rate-limit-status-routes.test.ts` (4 tests) — `GET /rate-limit/status` through the real `createRoutes` pipeline (active + disabled cases), plus wiring-integrity tests guarding the zombie-veto composition (EITHER sentinel owning a session holds the veto — the S1 regression where a second `setActiveRecoveryChecker` drops the compaction veto) and the bidirectional `deferIf`. All passing.
+- **Tier 3 E2E lifecycle:** `tests/e2e/rate-limit-sentinel-lifecycle.test.ts` (4 tests) boots the real `AgentServer` with the sentinel passed through exactly as `server.ts` wires it, and asserts `GET /rate-limit/status` returns **200 with `enabled: true`** — the "feature is alive" check that catches the case where `AgentServer`'s `?? null` plumbing drops the sentinel. Also verifies a reported throttle surfaces on the wire with the documented shape and that `isRecoveryActive` (the production zombie-veto predicate) tracks correctly. All passing.
+- **Type-check:** `npx tsc --noEmit` clean.
+- The full test suite must remain green before merge per the Zero-Failure Standard.

package/upgrades/side-effects/rate-limit-internal-prefix.md

@@ -0,0 +1,41 @@
+# Side-Effects Review — `/rate-limit` registered in `INTERNAL_PREFIXES`
+
+**Version / slug:** `rate-limit-internal-prefix`
+**Date:** 2026-05-22
+**Author:** echo
+**Trigger:** CI shard 1/4 (Node 20 + 22) deterministic failure in `tests/unit/capabilities-discoverability.test.ts:122` — the discoverability lint requires every route prefix in `routes.ts` to be either claimed by `CAPABILITY_INDEX` (agent-discoverable) or allowlisted in `INTERNAL_PREFIXES` (intentionally hidden). My PR added `GET /rate-limit/status` to `routes.ts` but did not classify the new `rate-limit` prefix.
+
+## Summary of the change
+
+One-line addition to `INTERNAL_PREFIXES` in `src/server/CapabilityIndex.ts`:
+
+```ts
+{ prefix: 'rate-limit', reason: 'operator-only rate-limit-sentinel observability — agent-facing surface is the sentinel’s own notices' },
+```
+
+This matches the exact pattern of five sibling sentinel/observability prefixes already in `INTERNAL_PREFIXES`:
+- `quota` — operator-only quota observability
+- `watchdog` — operator-only watchdog state
+- `prompt-gate` — operator-only prompt-gate observability
+- `delivery-queue` — operator-only relay queue observability
+- `scope-coherence` — operator-only scope-coherence observability
+
+## Decision-point inventory
+
+**Choice:** `INTERNAL_PREFIXES` vs. `CAPABILITY_INDEX`.
+
+Picked `INTERNAL_PREFIXES`. Reasoning: `GET /rate-limit/status` is read-only observability with no agent-facing action. The agent-facing surface of the rate-limit feature is the sentinel's **proactive** Telegram notices ("backing off", "still throttled", "back online", "still can't get through"). An agent doesn't poll `/rate-limit/status` — the sentinel pushes information to the user. Every sibling sentinel observability route makes the same choice for the same reason.
+
+## 1–7. Analysis
+
+1. **Over-block.** Hiding `/rate-limit/status` from `/capabilities` discovery — could that suppress a real agent capability? No. The route returns status data only; there's no agent action to invoke. The capability the agent has is "the sentinel will message me when a throttle hits"; that's surfaced through the sentinel's notifications, not through a route the agent reads.
+2. **Under-block.** Could marking it internal silently swallow a future agent-facing route under the same prefix? `/rate-limit/*` is one operator-only route today. If a future change adds a genuinely agent-facing `/rate-limit/<action>`, that change would need to either split the prefix or move the entry to `CAPABILITY_INDEX` — and the discoverability lint will catch it because every new route is enumerated and re-classified.
+3. **Level-of-abstraction fit.** The deny-allowlist (`INTERNAL_PREFIXES`) is exactly the layer the lint reads. No other layer would fix the lint.
+4. **Signal-vs-authority compliance.** This is a classification (signal), not a behavioral gate (authority). The route still behaves identically. The change shapes what `/capabilities` includes; nothing else.
+5. **Interactions.** Zero coupling to other allowlist entries. The lint operates per-prefix; adding one entry can't affect the classification of another.
+6. **Rollback cost.** Trivial — one-line removal. The route would then surface as unclassified and the lint would block again, signalling the rollback to whoever ran it.
+7. **Test coverage.** Covered by the existing 85-test `capabilities-discoverability.test.ts` suite, which dynamically generates one test per route prefix. The lint that caught this on CI is the same lint that now passes for `rate-limit`.
+
+## Rollback
+
+Remove the single line from `INTERNAL_PREFIXES` in `src/server/CapabilityIndex.ts`. CI will immediately re-fail with the same error message that triggered this fix.