instar 1.3.219 → 1.3.220

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.219",
+  "version": "1.3.220",
   "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-03T10:45:46.826Z",
-  "instarVersion": "1.3.219",
+  "generatedAt": "2026-06-03T11:27:46.725Z",
+  "instarVersion": "1.3.220",
   "entryCount": 195,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3ebec02e2055c35359e8c316f2516e427007a10f3858c987edae682833276aa6",
+      "contentHash": "af8b673a98bab2b47c8782a00013354e7ad340ad4c1558ce47b8811bdf521dab",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1474,7 +1474,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "28ca6d76d81717a42a58dd6d72237158a511f72e6764a43eecfeb46e81da0d90",
+      "contentHash": "d1851d4bb663dd524af17cf4c45e143bc441314bbe2b005c5ee1626019b92184",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/upgrades/1.3.220.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Adds `GeminiCapacityEscalationMonitor`, an observe-only signal that surfaces a **long** Gemini
+capacity block instead of letting it be a silent outage.
+
+#708's capacity policy correctly *defers* Gemini calls when Gemini reports a quota reset window
+(e.g. live: "retry after 46758s" ≈ 13h), refusing doomed subprocesses until it clears — but it only
+schedules/defers, it never *escalates*. A short defer is fine to absorb silently; a multi-hour block
+means the agent/mentee is invisibly unavailable for half a day. This monitor reads the existing
+`getGeminiCapacityGate()` module-global on a tick and raises **one** attention item per deferral
+episode when the remaining window exceeds a threshold (default 60 min), re-arming when the block
+clears. It never mutates the gate, never blocks a call. This closes item-3's "escalate, not silently
+stall" half.
+
+Config ships **OFF** (`monitoring.geminiCapacityEscalation.enabled`). When enabled, it rides
+`TokenLedgerPoller`'s existing cadence via the same after-tick hook as the cycle-SLA monitor — no new
+timer. Adds read-only `GET /gemini/capacity` (live gate: `blocked`, `remainingMs`, `deferredUntil`,
+`reason`); 503 when disabled.
+
+## What to Tell Your User
+
+- **No more silent Gemini outages**: "If Gemini hits a long quota block (hours), I can now flag it
+  instead of just going quiet — so you know the agent/mentee is capacity-blocked and for roughly how
+  long. It starts turned off; ask me to enable it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Long-capacity-block escalation | Enable `monitoring.geminiCapacityEscalation` to get one attention item per multi-hour Gemini block. |
+| Live capacity view | `GET /gemini/capacity` returns `{ enabled, blocked, remainingMs, deferredUntil, reason }` when the monitor is enabled. |
+
+## Evidence
+
+Verification:
+
+- Unit (8): disabled no-op; not-blocked → no escalation; short defer → no; long defer → escalates once
+  (HIGH ≥2h, NORMAL 1–2h); dedup across ticks within an episode; re-arm across a new episode; `status()`
+  reports without escalating.
+- Integration/E2E: `GET /gemini/capacity` through the real AgentServer — 200+shape when enabled, 503
+  when disabled, Bearer auth required.
+- `pnpm lint` (tsc + 4 lints) clean; `pnpm build` clean.

package/upgrades/gemini-capacity-escalation.eli16.md

@@ -0,0 +1,23 @@
+# Gemini "Long Block" Escalation — ELI16
+
+Viewable private artifact:
+https://echo.dawn-tunnel.dev/view/e5a1de0b-4e83-4d53-9565-ca23fc04857a?sig=18315449f889314be1565b8f89a7a13bbe9b0182b0cb8c55a6d0a55ff0d70d14
+
+When Gemini runs out of capacity, it tells Instar when to come back — sometimes "in 8 seconds,"
+sometimes "in 13 hours." Instar already knows not to keep hammering Gemini during that window (it waits
+politely instead). That's good.
+
+The gap: it waited **silently**. If Gemini said "come back in 13 hours," the agent (or a mentee agent
+it's supervising) would just be quietly unavailable for half a day, and nobody would know why.
+
+This change adds a quiet watcher: if Gemini is blocked for longer than a set time (default 1 hour),
+Instar raises **one** heads-up — "Gemini is capacity-blocked for about N hours" — so you actually know
+the agent is waiting on a quota reset, not broken or stuck. Short blips stay silent; only long blocks
+get flagged, and only once per block.
+
+It changes nothing about how Gemini calls work — it just turns a silent wait into a visible one. Ships
+off; you turn it on when you want it. There's also a `GET /gemini/capacity` you can check to see if
+Gemini is currently blocked and for how long.
+
+_Tier-1 fix · branch `echo/gemini-capacity-escalation` · 8 unit + 3 integration/e2e tests · completes
+item-3's "escalate, not silently stall" half._

package/upgrades/side-effects/gemini-capacity-escalation.md

@@ -0,0 +1,50 @@
+# Side-Effects Review — GeminiCapacityEscalationMonitor
+
+**Version / slug:** `gemini-capacity-escalation`
+**Date:** `2026-06-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+A new observe-only monitor reads the existing `getGeminiCapacityGate()` module-global on the
+TokenLedgerPoller after-tick cadence; when Gemini is deferred for ≥ `escalateAfterMinutes` (default 60)
+it raises ONE attention item per deferral episode (deduped on `deferredUntil`), re-arming when the
+block clears. Plus a config gate (ships OFF), AgentServer wiring, and a read-only `GET /gemini/capacity`
+route. Nothing else changes; #708's defer behavior is untouched.
+
+## Decision-point inventory
+
+One decision surface: *whether to raise an attention item*. It is bounded — observe-only, never mutates
+the gate, never blocks/retries a call, never auto-recovers. The worst case is an extra attention item;
+it cannot affect Gemini call behavior.
+
+## 1. Attention spam
+
+Mitigated three ways: (a) ships OFF by default; (b) per-episode dedup — at most one item per distinct
+`deferredUntil` value, so repeated ticks within the same block don't re-raise; (c) the `escalateAfterMinutes`
+threshold (default 60) means short, self-healing blips never escalate — only genuinely long blocks do.
+The episode key re-arms only when the gate clears (`allow`), so a fresh block warns once more.
+
+## 2. False escalation
+
+The monitor reads the SAME gate #708 uses to refuse calls, so "blocked" is ground truth, not a guess.
+`remainingMs` is the gate's own `retryAfterMs`. There is no independent classification that could
+disagree with the policy.
+
+## 3. Wiring / cadence
+
+Rides the existing `TokenLedgerPoller.afterTick` alongside the cycle-SLA monitor (awaited in sequence) —
+no new timer, no new process. When the poller is idle (no running sessions) the tick still fires on the
+poller's idle cadence; a missed tick only delays the escalation, never drops the block.
+
+## 4. Migration / reversibility
+
+Config default added to `ConfigDefaults.ts` → automatic `migrateConfig` parity via `applyDefaults` (no
+separate migration block). Default OFF, so existing agents are unaffected until they opt in. Revert =
+revert the commits; no persisted state, no schema change.
+
+## Verdict
+
+Observe-only, bounded, default-OFF, reads ground-truth gate state. The only behavioral change when
+enabled is one attention item per long Gemini block — strictly more visibility, never less availability.