instar 1.3.214 → 1.3.215

package/package.json

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

package/upgrades/1.3.215.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Gemini CLI one-shot calls now have a provider-specific capacity policy. When
+Gemini reports a 429, `QUOTA_EXHAUSTED`, `resource exhausted`, or a usage/quota
+limit, Instar parses any reset window Gemini provides, retries only short
+capacity windows once, and otherwise records a local defer window so subsequent
+calls fail fast instead of spawning another doomed Gemini process.
+
+Explicit caller-supplied raw Gemini model ids continue to pass through to the
+Gemini CLI. Only the automatic `capacityPolicy.fallbackModel` path is
+constrained to the known local Gemini model set. When that fallback is valid,
+both Gemini execution paths rebuild `gemini -m <model>` on retry from the
+policy-selected model, so fallback configuration is not just resolved, it is
+actually applied to the next CLI invocation.
+
+## What to Tell Your User
+
+- **Gemini quota handling is calmer:** "When Gemini says its quota is exhausted,
+  I now remember the reset window and stop repeatedly poking it. Short capacity
+  blips get one bounded retry; longer quota windows are surfaced as a clear
+  defer instead of looking like a stalled agent."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|------------|
+| Gemini capacity defer window | Automatic for Gemini CLI one-shot calls |
+| Short Gemini capacity retry | Automatic, one bounded retry for short windows |
+| Known-only Gemini capacity fallback | Automatic; `fallbackModel` swaps only when the fallback is a known Gemini model |
+
+## Evidence
+
+- `npx vitest run tests/unit/gemini-cli-adapter.test.ts tests/unit/geminiCapacityPolicy.test.ts tests/unit/frameworkSessionLaunch.test.ts tests/integration/gemini-capacity-policy-integration.test.ts tests/e2e/gemini-capacity-policy-lifecycle.test.ts`
+  — 5 files / 80 tests passed, including raw-model pass-through and spawned
+  retry argv assertions.
+- `npx tsc --noEmit`

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

@@ -0,0 +1,21 @@
+# Gemini Capacity Handling — ELI16
+
+Viewable private artifact:
+https://codey.dawn-tunnel.dev/view/b5873ea2-17ba-4adf-9d1a-f0e1c48f781e?sig=3e2c7d2f4e0852cf91496f79ce25aeca72ce778c92d3278e101b63bec90400af
+
+Gemini sometimes says, "I'm out of capacity right now; try again after this
+reset window." Before this change, Instar treated that too much like an ordinary
+failure. The next Gemini call could try again immediately, hit the same quota
+wall, and make the agent look stuck. One fallback path also guessed an old model
+name, `gemini-2.0-flash`, which Gemini rejected.
+
+This change gives Gemini its own capacity rule. If the reset is short, Instar
+waits briefly and tries once. If Gemini gives a longer reset window, Instar
+remembers it and refuses later Gemini calls locally until the window passes.
+That means no repeated doomed Gemini subprocesses and a clearer error for the
+agent/operator.
+
+It also limits Gemini model choices to the verified names we know work:
+`gemini-2.5-flash` and `gemini-2.5-pro`. If some code asks for an unknown Gemini
+model, Instar falls back to `gemini-2.5-flash` instead of sending a guessed model
+to Gemini and getting a 404.

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

@@ -0,0 +1,139 @@
+# Side-Effects Review — Gemini capacity policy
+
+**Version / slug:** `gemini-capacity-policy`
+**Date:** `2026-06-03`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change adds a Gemini-specific capacity policy beside the existing Gemini
+adapter observability code. Gemini one-shot calls now classify quota/rate-limit
+failures, parse reset windows such as `quota will reset after 7h32m28s`, retry
+only short capacity windows once, and record a process-local defer window for
+longer quota exhaustion. While deferred, later calls fail locally with a retry
+hint instead of spawning another Gemini CLI process that would hit the same
+quota wall.
+
+Review update: the optional `capacityPolicy.fallbackModel` is now wired into
+the retry loop instead of only being resolved in the policy decision. Both
+Gemini execution paths rebuild `gemini -m <model>` on each retry attempt from
+the current policy-selected model, so a configured fallback actually changes
+the spawned CLI argv. Explicit caller-supplied raw model ids still pass through
+the primary resolver; only automatic capacity fallback is constrained to known
+Gemini models.
+
+The change also constrains automatic Gemini fallback selection to verified known
+models: `gemini-2.5-flash` and `gemini-2.5-pro`. Explicit raw Gemini model ids
+continue to pass through to the CLI because they represent caller intent. The
+bad `gemini-2.0-flash` fallback observed during the mentor loop is avoided by
+the known-only fallback helper rather than by rewriting every raw model id.
+
+## Decision-point inventory
+
+- `isGeminiCapacityError` — add — classifies Gemini quota/rate-limit/capacity
+  error strings.
+- `parseGeminiRetryAfterMs` — add — extracts reset windows from Gemini stderr.
+- `decideGeminiCapacityPolicy` — add — chooses `none`, `retry`, or `defer`.
+- `recordGeminiCapacityDeferral` / `getGeminiCapacityGate` — add — process-local
+  defer state for Gemini calls.
+- Gemini fallback resolution — modify — automatic capacity fallback ids must be
+  in the known set or the current caller-selected model is kept.
+- `GeminiCliIntelligenceProvider` and adapter one-shot transport — modify — both
+  apply the policy before and after spawning Gemini.
+- Retry argv rebuild — modify — short-window retries rebuild the Gemini argv
+  from `decision.model`, so `capacityPolicy.fallbackModel` is applied to the
+  next spawned process.
+
+---
+
+## 1. Over-block
+
+The main over-block risk is a false-positive capacity classification that defers
+Gemini when the failure was not actually quota related. The classifier is
+deliberately narrow: explicit `429`, `QUOTA_EXHAUSTED`, `resource exhausted`,
+`rate limit`, quota, usage-limit, or capacity language. Generic parse errors,
+syntax errors, binary-not-found errors, and ordinary non-zero exits do not defer.
+
+The known-model constraint applies only to automatic capacity fallback. Explicit
+caller-selected Gemini model ids still pass through to the CLI, so newly valid
+Gemini ids are not blocked by this policy. If `capacityPolicy.fallbackModel` is
+unknown, the retry keeps the caller's current model instead of swapping to a
+guessed fallback.
+
+## 2. Under-block
+
+This policy is process-local. A server restart forgets the defer window and the
+first post-restart Gemini call may probe the provider again. That matches the
+existing LLM circuit-breaker shape and keeps the change small. A future durable
+capacity ledger could persist provider reset windows across restarts if repeated
+restart-probes become noisy.
+
+This does not discover the full Gemini model catalog dynamically. It uses the
+currently verified set and keeps the list explicit. Dynamic discovery is a
+separate model-catalog problem, not part of quota handling.
+
+## 3. Level-of-abstraction fit
+
+The policy belongs at the Gemini provider boundary, not at each caller. The
+adapter one-shot transport and live `GeminiCliIntelligenceProvider` are the
+places that see Gemini stderr and own whether to spawn Gemini again. Keeping the
+decision there means reviewers, route, setup narrative calls, and future Gemini
+one-shots share the same capacity behavior.
+
+Known-model fallback belongs in the capacity-policy fallback helper because that
+is the only automatic model swap path in this change. Primary model resolution
+still maps canonical tiers and otherwise respects explicit raw model ids.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Not applicable to conversational/product judgment — this is deterministic
+  provider-capacity handling and model-id validation at the transport boundary.
+
+The defer gate is not making a semantic judgment about user intent. It acts only
+after Gemini itself reports a quota/capacity condition or while the recorded
+reset window from that provider report is still active.
+
+## 5. Interactions
+
+- **Global LLM circuit breaker:** The Gemini provider still throws clear
+  quota/rate-limit text, so the existing circuit breaker can continue to observe
+  and pause broader LLM-backed work. The Gemini policy additionally prevents
+  repeated Gemini subprocesses during a known Gemini reset window.
+- **Setup wizard:** Gemini narrative fallback continues to work; quota failures
+  become clearer and do not repeatedly spawn Gemini.
+- **Route override detector:** The known-model list now includes
+  `gemini-2.5-flash`, so the verified default is recognized.
+- **Session launch:** Unchanged by the capacity fallback review fix; the
+  known-model gate is isolated to automatic provider retry fallback.
+
+## 6. External surfaces
+
+Users may see clearer Gemini quota/defer errors instead of a generic Gemini CLI
+failure or a stalled task. Operators can rely on `gemini-2.5-flash` as the safe
+automatic capacity fallback when configured. Explicit caller-supplied model ids
+continue to pass through. No config migration, schema change, or external API
+change is introduced.
+
+## 7. Rollback cost
+
+Rollback is a code revert of the Gemini policy module, the two provider wiring
+changes, the fallback known-list change, tests, and these artifacts. No
+data migration is required. A running process that had recorded a defer window
+would forget it on restart.
+
+## Conclusion
+
+The change is a narrow sibling to the Codex capacity/model-swap work, scoped to
+Gemini's actual error and model surfaces. It prevents repeated doomed Gemini CLI
+spawns during quota windows, avoids guessed model fallbacks, and pins the
+behavior with unit, integration, and E2E tests.
+
+## Evidence pointers
+
+- `tests/unit/geminiCapacityPolicy.test.ts`
+- `tests/integration/gemini-capacity-policy-integration.test.ts`
+- `tests/e2e/gemini-capacity-policy-lifecycle.test.ts`
+- `tests/unit/frameworkSessionLaunch.test.ts`