instar 1.3.250 → 1.3.252

package/package.json

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

package/upgrades/1.3.251.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Completes the multi-machine relocation fix: a machine now resolves its OWN nickname.
+
+- **Root cause (live-caught on real hardware):** `updateNickname` is local-only, so a
+  machine rename applied on a peer's registry never reached the owning machine — its own
+  capacity entry was `nickname=None` while peers saw the name. The relocation check runs on
+  the holder, so it couldn't resolve its own nickname and "move it back to <this machine>"
+  silently failed.
+- **`SelfNicknameResolver`** (pure) — resolves self-nickname: local view → peer view → derive.
+- **Convergence task** — at boot and on a timer, if the local self-nickname is missing, it
+  adopts the name a peer authoritatively reports and persists it, making `getCapacities()`
+  symmetric so the recognizer, transfer route, and `/pool` all resolve self.
+- **Transfer route** resolves the self-nickname via the resolver (was capacity-only).
+
+## What to Tell Your User
+
+- **"Move it back here" works now.** When a conversation is on one of your machines and you
+  ask to move it back to the machine you're on, that used to silently do nothing in some
+  setups — your agent didn't know its own name. It learns its own name from its other
+  machines now, so moving things back and forth just works.
+
+## Summary of New Capabilities
+
+- A machine resolves its own user-facing nickname (from peers when its local copy is missing).
+- Reliable "move this to the machine it's already on" — the last gap in nickname transfers.
+
+## Evidence
+
+Live-caught on the real laptop+mini pair (laptop returned 404 "unknown machine: Laptop" for
+its own name). 7 unit tests incl. the asymmetry regression + an e2e proving self-nickname
+transfer resolves through the real AgentServer. Spec: MULTI-MACHINE-SESSION-POOL-SPEC §L4.

package/upgrades/1.3.252.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When a Gemini call hit a per-model capacity limit (e.g. "You have exhausted your
+capacity on this model. Quota resets after 46m"), instar's Gemini capacity policy
+globally deferred on that model and wrote a `quota-state.json` snapshot with
+`recommendation: 'stop'` / `fiveHourPercent: 100`. But the known Gemini models
+(`gemini-2.5-flash`, `gemini-2.5-pro`) draw on SEPARATE quotas, so one model
+exhausting was mis-recorded as a full account-wide block — and every reader of that
+file (the agent, the mentor, the escalation monitor) concluded the whole Gemini
+agent was down, even when the account had headroom on the other model. This produced
+repeated false "agent is blocked" reports.
+
+The policy now switches to a known model with headroom and retries before deferring
+(mirroring the codex auto-swap-on-limit policy). Only when EVERY known model is
+exhausted does it globally defer and write the stop-state — now tagged
+`scope: 'account'`. The per-model exhaustion windows are tracked time-based and
+self-clear, so there is no switch loop and no stale state. The model switch uses a
+short 250ms backoff (a different model needs no wait).
+
+## What to Tell Your User
+
+If you run a Gemini-backed agent: when one Gemini model hits its limit, the agent now
+quietly switches to the other model and keeps working, instead of going dark for the
+length of that model's reset window. It only reports itself as out of capacity when
+every model is genuinely exhausted. Nothing to do — it just stops the false "blocked"
+reports and keeps the agent productive.
+
+## Summary of New Capabilities
+
+Gemini agents auto-fall-back across models on a per-model capacity limit (parity with
+the codex auto-swap), and the durable quota-state now distinguishes a single-model
+deferral from a genuine account-wide block (`scope: 'account'`).
+
+## Evidence
+
+- **Reproduction (live this session):** a Gemini agent's `gemini -p` probe returned
+  "You have exhausted your capacity on this model. Your quota will reset after 46m11s"
+  while the account `/stats` showed 20% remaining on the Auto model — i.e. one model
+  exhausted, account fine. The old policy wrote `recommendation: 'stop'` for this,
+  which read as a full block.
+- **Before:** single-model exhaustion → global defer + `recommendation:'stop'` /
+  `fiveHourPercent:100`; the agent appeared fully blocked for the whole reset window.
+- **After:** single-model exhaustion → switch to the model with headroom and keep
+  working; global stop-state (now `scope:'account'`) is written ONLY when every known
+  model is exhausted.
+- **Tests:** 21 across three tiers — `tests/unit/geminiCapacityPolicy.test.ts`
+  (switch-then-defer, single-model-no-global-stop, `pickGeminiFallbackModel`,
+  self-clearing windows), `tests/integration/gemini-capacity-policy-integration.test.ts`,
+  and `tests/e2e/gemini-capacity-policy-lifecycle.test.ts` (both updated to assert the
+  two-model attempt + account scope), plus the escalation-monitor suite. `tsc --noEmit`
+  clean.

package/upgrades/side-effects/gemini-model-fallback-on-exhaustion.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Gemini per-model exhaustion switches model before deferring
+
+**Version / slug:** `gemini-model-fallback-on-exhaustion`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `required (LLM-routing behavior change)`
+
+## Summary of the change
+
+When a Gemini call hit a capacity limit, `decideGeminiCapacityPolicy` (after its
+short-window immediate-retry path) went straight to a GLOBAL `defer` on the SAME
+model, and `recordGeminiCapacityDeferral` wrote a `quota-state.json` snapshot with
+`fiveHourPercent: 100` / `recommendation: 'stop'`. But the known Gemini models —
+`gemini-2.5-flash` and `gemini-2.5-pro` — draw on **separate** quotas. So one model
+exhausting (e.g. "You have exhausted your capacity on this model. Quota resets after
+46m") was recorded as a full account-wide block, and any reader of `quota-state.json`
+(including the agent itself, the mentor, the escalation monitor) saw `recommendation:
+'stop'` and concluded the whole Gemini agent was down — even when the account had
+headroom on the other model. This caused repeated false "Gemi is blocked" reports
+(confirmed live this session: a `gemini -p` probe returned that exact error while
+`/stats` showed the account at 20% remaining on Auto).
+
+The fix (mirrors the existing codex auto-swap-on-limit policy, #31): on per-model
+exhaustion, record the exhausted model's reset window, then switch to a known model
+with headroom and retry. Only when **every** known model is exhausted do we globally
+defer and write the stop-state — now tagged `scope: 'account'`. Because the caller
+records a deferral only on `action: 'defer'`, switching models also means a single-
+model exhaustion no longer writes a global stop at all.
+
+## Decision-point inventory
+
+1. **`decideGeminiCapacityPolicy` (long-reset branch):** record `model` as exhausted
+   (time-based, `now + deferMs`); pick a fallback via `pickGeminiFallbackModel`; if
+   one exists → `retry` with that model; else → `defer`.
+2. **`pickGeminiFallbackModel`:** a candidate qualifies when known, ≠ the exhausted
+   model, and not itself inside a recorded exhaustion window at `now`. Prefers an
+   operator-configured `fallbackModel`, else the first known model with headroom.
+
+## 1. Over-block (what still defers / blocks)
+
+- When ALL known models are in an exhaustion window → `defer` + the global stop-state
+  (now `scope: 'account'`). That is the genuine account-wide block and still gates
+  scheduler spawns exactly as before. (tests: "defers once ALL models exhausted",
+  integration "defers after a long quota reset", e2e lifecycle.)
+- The short-window immediate-retry path (attempt < maxImmediateRetries, small reset)
+  is unchanged.
+- Non-capacity errors are unchanged — `decide` returns `none` and the error surfaces.
+
+## 2. Under-block (what it now allows that it didn't)
+
+- A single model exhausting now triggers ONE extra Gemini spawn on the other model
+  (the switch) before any deferral. Worst-case cost when BOTH models are exhausted:
+  two spawns instead of one (flash then pro) before the global defer — bounded at 2
+  (one per known model; each is recorded exhausted so it is never retried within its
+  window). The model-switch retry uses a 250ms backoff (not the 5s same-model
+  backoff) since a different model needs no wait.
+- Loop-safety: `modelExhaustedUntil` is time-based and self-clears once a window
+  passes, so there is no permanent state and no A→B→A switch loop (each model is
+  recorded before fallback selection; once both are recorded, `pickGeminiFallbackModel`
+  returns undefined → defer). (tests: "returns undefined once both exhausted",
+  "windows self-clear once the reset passes".)
+
+## 3. Blast radius
+
+- One file of logic: `src/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.ts`
+  (new module state `modelExhaustedUntil`, new export `pickGeminiFallbackModel`, a
+  `now?` param on `decide`, the switch-before-defer branch, `scope` on the stop-state,
+  reset clears the map).
+- NO consumer signature changes: both callers (`transport/oneShotCompletion.ts`,
+  `core/GeminiCliIntelligenceProvider.ts`) already switch to `decision.model` on
+  `action:'retry'` and record a deferral only on `action:'defer'`.
+- Affects only Gemini-CLI agents. Claude / codex paths untouched. The added
+  `scope` field is additive (readers that don't know it are unaffected).
+
+## 4. Reversibility
+
+Fully reversible: revert the one policy file + the test updates. Module state is
+in-process and time-based (no persistence); the `quota-state.json` shape only gains
+an additive `scope` field. Verified: `tsc --noEmit` clean; 21 tests green across
+unit + integration + e2e + escalation tiers (both the switch path and the genuine
+all-models-defer path).

package/upgrades/side-effects/mm-self-nickname.md

@@ -0,0 +1,23 @@
+# Self-Nickname Convergence — Plain-English Overview
+
+> One line: a machine now learns its OWN user-facing nickname from its peers, so "move it back to <this machine>" finally works.
+
+## The problem in one breath
+
+We shipped placement/transfer robustness, but live-testing on the real laptop+mini pair exposed that the fix was incomplete: the laptop couldn't resolve its OWN name "Laptop". Root cause — `updateNickname` (the dashboard rename) is local-only, so a rename applied on a peer's registry never reached the owning machine. The laptop's own capacity entry was `nickname=None` while peers correctly saw "Laptop". The relocation check runs on the holder (laptop), so it couldn't match "Laptop" → "move it back to the laptop" silently failed.
+
+## What this adds
+
+- **`SelfNicknameResolver` (pure)** — resolves this machine's own nickname: local capacity view → any PEER's view that names it (the drift backstop) → deterministic derive. Unit-tested incl. the exact asymmetry (self absent locally, present in a peer view).
+- **Self-nickname convergence task (server)** — periodically (and at boot), if the local self-entry has no nickname, it fetches an online peer's `/pool`, finds what the peer calls this machine, and persists it via `updateNickname`. This makes `getCapacities()` SYMMETRIC, so the recognizer, the transfer route, and `/pool` all resolve self. No-ops once known.
+- **Transfer route** now resolves the self-nickname via the resolver (was caps-only).
+
+## The safeguards
+
+- **Best-effort, never blocks** — convergence catches all errors (annotated `@silent-fallback-ok`); a failed peer fetch just retries on the timer.
+- **No mis-routing** — adoption only happens when the local nickname is missing and a peer authoritatively names this machineId; `updateNickname` still enforces pool-uniqueness.
+- **Tests** — Tier 1 (7 unit on the resolver incl. the regression), Tier 3 (e2e: transfer to THIS machine's own nickname resolves through the real AgentServer — 404'd before). `tsc` clean.
+
+## Spec lineage
+
+§L4 of the approved `docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md` (nickname-based placement/transfer). No new authority — a convergence read-model over existing nickname state.