instar 1.3.688 → 1.3.690

package/package.json

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

package/upgrades/1.3.689.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Mesh Self-Heal **G3** — the first build increment of `MESH-SELF-HEAL-SPEC` (lease↔job binding, machine-independence). It makes duplicate sessions structurally impossible across a multi-machine setup:
+
+- **Lease-gated spawn** (`src/core/leaseGatedSpawn.ts`): when an inbound Telegram message has no session yet, a machine spawns a session for that topic ONLY if it genuinely holds the fenced awake-lease; otherwise it forwards to the holder ("spawn iff holder, else forward"). It keys on the one trustworthy authority (`holdsLease()`), never an unreliable placement view, and FAILS toward spawn when no forward seam exists — it never strands a message to avoid a duplicate.
+- **Single-writer binding lifecycle**: a topic→session binding is cleared the instant its session is killed ("a binding exists IFF a live session exists"), so a dead session can't silently resurrect and double-serve. The cleanup deliberately SKIPS context-exhaustion / recovery kills (which are immediately followed by a same-topic respawn), mirroring the resume-UUID-save guard, so promoting it can never break recovery.
+- **Evaluable soak evidence** (`GET /mesh-selfheal/g3`): a read-only ledger records the counterfactual ("how many duplicate sessions I would have prevented if enabled" / "stale bindings I would have cleared") plus a deterministic promotion recommendation — so this dark feature can actually earn graduation instead of rotting silently.
+
+Ships **dark + dry-run** behind `multiMachine.sessionPool.ownershipCheckedSpawn` (dev-gated): a strict no-op on a single machine or with the flag off. Next increments: G2 (nobody-serving alarm), G1 (badge↔job binding).
+
+## What to Tell Your User
+
+Nothing changes yet — this ships **off by default** (⚗️ experimental, dark + dry-run) while it soaks on a real two-machine pair. When it's active it prevents the "two of me replying to one message" duplicate-session problem on multi-machine setups, with no action needed from you. Single-machine agents are unaffected.
+
+## Summary of New Capabilities
+
+- `GET /mesh-selfheal/g3` — read-only soak-evidence + promotion recommendation for the lease-gated-spawn gate (agent observability; not a user-invokable capability).
+- Config: `multiMachine.sessionPool.ownershipCheckedSpawn` `{ enabled, dryRun }` — opt-in lease-gated spawn + single-writer binding lifecycle (dark + dry-run by default).
+
+## Evidence
+
+- New unit suite `tests/unit/leaseGatedSpawn.test.ts` (30 tests) covers both sides of every decision boundary — spawn-iff-holder, forward, dry-run counterfactual, spawn-when-no-seam, binding clear/skip/respawn-imminent.
+- New integration suite `tests/integration/mesh-selfheal-g3-route.test.ts` (3 tests) drives `GET /mesh-selfheal/g3` over the real HTTP path and confirms both counters + the promotion recommendation.
+- `tests/unit/lint-dev-agent-dark-gate.test.ts` updated for the new gate's dark-gate exclusion entry; full dark-gate lint green (24 tests).
+- Typecheck clean; 57 targeted tests green. Independent second-pass review concurred (audited the recovery-bounce fix).

package/upgrades/1.3.690.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Mesh Self-Heal **G2 — core decision logic** (increment 1 of the nobody-serving alarm, `MESH-SELF-HEAL-SPEC` §3.2). Adds `src/core/nobodyPollingRecovery.ts`: the PURE, deterministic decision core for the silent-loss backstop — when NO machine is polling Telegram (the zombie-lease-holder state behind the message-drop incidents), exactly ONE fit machine must take over, never zero (drops), never two (the 409 poll-war).
+
+- `electPollClaimant` — deterministic single-claimant election (F4-preferred-awake if fit, else lowest-machineId fit). Machine-agnostic: every machine elects the SAME claimant, which is the structural defense against split-brain double-claim.
+- `decideNobodyPollingClaim` — reduces over the EXISTING B5 detector (`pollerCount.ts`): `ok`→no-op, `dual`→veto (claiming into 2 pollers IS the 409 war), `indeterminate`→fail-closed, unconfirmed silence→await, peer-confirmed global outage→hold, confirmed silence→elect + claim/stand-down/escalate.
+- `decidePostCasSelfReverify` — "CAS-win is necessary but not sufficient": re-check live local poll-freshness before serving; on self-unfit, relinquish + self-exclude.
+- `NobodyPollingLedger` — evaluable soak evidence (episodes, claims, stand-downs, self-exclusions, vetoes), mirroring G3's close-the-loop ledger.
+
+It also wires the core to a **read-only observe surface**, `GET /mesh-selfheal/g2`: it computes the live nobody-polling verdict over the pool, debounces a silence across reads, runs the decision (who would claim), records the soak counterfactual, and returns it. The surface is OBSERVE-only — it reports the decision but does NOT enact it (no lease acquire, no polling change). The enforce-mode actuation (actually taking over polling via the existing poll-follows-lease lever) is the next increment.
+
+## What to Tell Your User
+
+Nothing changes in behavior yet — this is the detector + a read-only status surface for the upcoming "nobody-serving alarm," not yet acting anywhere. When the enforce step lands (next increment), it will detect the "nobody is polling Telegram" state across your machines and have exactly one fit machine take over automatically, so messages stop dropping when a machine goes quiet. No action needed.
+
+## Summary of New Capabilities
+
+- `GET /mesh-selfheal/g2` — read-only observe surface for the nobody-polling detector: live verdict + the single-claimant decision + soak evidence (agent observability; not a user-invokable capability). No config flag or write surface yet; observe-only (no actuation).
+
+## Evidence
+
+- `tests/unit/nobodyPollingRecovery.test.ts` — 18 unit tests covering both sides of every decision boundary (election: preferred-fit / preferred-unfit / no-fit / determinism; verdict reduction: ok/dual/indeterminate/await/hold/claim/stand-down/escalate; self-reverify: fresh→serve / stale→relinquish; ledger accounting).
+- `tests/integration/mesh-selfheal-g2-route.test.ts` — 4 integration tests over the real HTTP pipeline (feature-alive 200; confirmed-silence→claim; transient-silence→await-confirm; two-pollers→veto). All green; typecheck clean.

package/upgrades/side-effects/mesh-self-heal-g2-core.md

@@ -0,0 +1,32 @@
+# Side-Effects Review — Mesh Self-Heal G2 (core decision logic)
+
+**Change:** The PURE decision core of G2 (nobody-polling detector + single-claimant recovery) from `MESH-SELF-HEAL-SPEC.md` §3.2 — `src/core/nobodyPollingRecovery.ts` + 18 unit tests. Three pure functions (`electPollClaimant`, `decideNobodyPollingClaim`, `decidePostCasSelfReverify`) + a soak ledger. This is increment 1 of G2: the decision logic only. It is NOT YET WIRED to any tick, route, or actuation — it has ZERO runtime effect until a later increment consumes it. (Wiring + the `/mesh-selfheal/g2` observe route + the enforce-mode actuation via the existing poll-follows-lease lever + CAS are the next increment — see MESH-SELF-HEAL-G2-BUILD.md.)
+
+**Decision point?** The MODULE encodes a decision (who claims poll-ownership), but nothing CALLS it yet, so in this increment there is no live decision-point. Signal-vs-authority still assessed (Q4).
+
+## 1. Over-block (legitimate inputs wrongly rejected?)
+N/A as shipped — unwired, no inputs flow through it. By design the decision FAILS toward NOT-claiming on every ambiguity (`dual`→veto, `indeterminate`→fail-closed, unconfirmed silence→await, global-outage→hold, no-fit→escalate). The only `claim` outcome requires confirmed real silence + this machine being the deterministically-elected single claimant. A wrongful claim is the harm (a 2nd poller / 409 war), so the gate is biased hard against claiming.
+
+## 2. Under-block (failure modes still missed?)
+As pure logic, none in-scope. The KNOWN not-yet-built pieces (tracked, not orphan-deferred): the actuation (CAS acquire + poll-lever start/stop) and the post-claim live-verify of `lifeline-poll-active.json`. Until those land, this module cannot cause OR prevent anything — it is inert decision logic with full test coverage.
+
+## 3. Level-of-abstraction fit
+Correct layer. It REDUCES over the existing B5 detector (`pollerCount.ts` `evaluatePollerCount`) rather than re-folding poll-counts (spec finding Int2-A — reuse, don't reinvent). It is a pure decision module mirroring `leaseGatedSpawn.ts` (G3) — no I/O, fully unit-testable, consumed by a thin wiring layer later.
+
+## 4. Signal vs authority compliance
+COMPLIANT. Pure functions (no I/O, no blocking authority). The election is deterministic + machine-agnostic (every machine computing it over the same inputs elects the SAME claimant — the structural defense against split-brain double-claim). The actual authority (acquiring the fenced epoch-CAS) lives in the existing lease coordinator, which the future wiring will call; this module only DECIDES, it does not ENACT. `decidePostCasSelfReverify` encodes "CAS-win is necessary but not sufficient" (Adv2-F1) so the eventual enactment re-checks live local freshness before serving.
+
+## 5. Interactions
+None in this increment (unwired). The design's intended interactions (documented for the wiring increment): consumes B5's verdict; the claim drives the existing poll-follows-lease lever; self-exclusion advertises into the existing heartbeat. No shadowing — it adds a decision layer ON TOP of B5, not parallel to it.
+
+## 6. External surfaces
+None yet. No route, no config flag, no audit write in this increment — the module is pure. The exported `sharedG2NobodyPollingLedger` singleton mirrors `sharedG3SoakLedger`; it is written/read only once the wiring + `/mesh-selfheal/g2` route land.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+This IS multi-machine coherence logic. Posture: the decision is computed LOCALLY on each machine from the replicated/advertised pool capacities + B5 verdict, and is deterministic so all machines agree on the single claimant without a coordination round-trip (the election is the coherence mechanism). The watermarks it will eventually read (`pollSucceededMonoMs` etc.) are machine-local, never replicated (spec §3.1 Sca-F1) — but that plumbing is the wiring increment, not this one.
+
+## 8. Rollback cost
+Trivial — revert the commit. The module is unreferenced by any runtime path, so removing it cannot affect a running agent. No config, no migration, no state.
+
+## Second-pass review
+Not triggered for this increment: the module is unwired pure logic with no live decision-point, block/allow authority, or session-lifecycle touch. The Phase-5 second-pass IS required for the WIRING increment (it will consume the lease/poll-ownership authority — "lease"/"sentinel"/session-lifecycle territory) and is flagged in MESH-SELF-HEAL-G2-BUILD.md.

package/upgrades/side-effects/mesh-self-heal-g2-observe.md

@@ -0,0 +1,34 @@
+# Side-Effects Review — Mesh Self-Heal G2 (observe route)
+
+**Change:** Wires the G2 pure core (this PR's first commit) to a read-only observe surface: `GET /mesh-selfheal/g2` (`src/server/routes.ts`) + 4 integration tests. The route computes the B5 verdict over the live pool (`machinePoolRegistry.getCapacities()`), debounces a `silence` across reads (`G2_NOBODY_POLLING_CONFIRM_OBSERVATIONS = 3`), runs `decideNobodyPollingClaim`, records the counterfactual to `sharedG2NobodyPollingLedger`, and returns `{ verdict, silenceStreak, silenceConfirmed, selfMachineId, decision, ledger }`.
+
+**Decision point?** The route REPORTS a decision (who would claim poll-ownership) but does NOT ENACT it — no fenced-CAS acquire, no poll-lever write. It is observe/read-only. The enacting authority (the enforce increment) is explicitly NOT in this change.
+
+## 1. Over-block
+N/A — read-only, blocks nothing. The decision it reports is biased hard against claiming (dual→veto, indeterminate→fail-closed, unconfirmed-silence→await, no-fit→escalate); only a confirmed real silence with this machine as the deterministic single claimant yields `claim`.
+
+## 2. Under-block
+The observe surface does not act, so it can neither over- nor under-block. KNOWN not-yet-built (tracked, not orphan-deferred): the enforce actuation (CAS acquire + `writePollIntent` poll-lever + post-claim live-verify of `lifeline-poll-active.json`) and peer-evidence-of-global-outage plumbing (`globalOutageEvidence` is hard-coded false here → a confirmed silence proceeds to elect, which is the observe-correct behavior; the HOLD-on-global path is the enforce increment).
+
+## 3. Level-of-abstraction fit
+Correct. The route reuses the EXACT capacity-gathering + `poolPollerVerdict` the adjacent `GET /pool/poller-count` already uses (no new pool plumbing), and the pure decision lives in `nobodyPollingRecovery.ts`. The route is a thin reporter over both.
+
+## 4. Signal vs authority compliance
+COMPLIANT. Read-only observability with no blocking/enacting authority. `selfMachineId` is read from `coordinator.identity?.machineId`; the election is deterministic + machine-agnostic. The route records soak evidence (signal) and returns the decision (signal) — it does not acquire the lease or change polling.
+
+## 5. Interactions
+- Reuses `poolPollerVerdict` (B5) — no reimplementation, no double-fold.
+- The `_g2SilenceStreak` debounce counter is module-scoped per `createRoutes` call (one server process = one counter) — correct (a single server's consecutive reads). It is reset on any non-silence verdict.
+- Records to the process-wide `sharedG2NobodyPollingLedger` — the same singleton the enforce increment's evaluator will use; read-driven recording means the ledger advances as the route is polled (documented; the periodic evaluator is the enforce increment).
+
+## 6. External surfaces
+New route `GET /mesh-selfheal/g2` — Bearer-gated like all routes; classified under the existing `mesh-selfheal` INTERNAL_PREFIXES entry (added by G3, already on main) so it's an agent-read, not a user capability. No config flag, no write surface, no audit file in this increment.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+This IS the cross-machine coherence read. The decision is computed locally from the pool's advertised capacities + the deterministic election, so every machine's `/mesh-selfheal/g2` agrees on the single claimant without a coordination round-trip. `selfMachineId` is machine-local. Read-only — nothing replicates or strands on transfer.
+
+## 8. Rollback cost
+Trivial — revert the commit. The route is read-only and unreferenced by any actuation path; removing it cannot affect a running agent's behavior. No migration, no state.
+
+## Second-pass review
+Not triggered: the route holds NO block/allow authority, touches NO session lifecycle, and performs NO actuation — it is read-only observability over a pure decision. The Phase-5 second-pass IS required for the ENFORCE increment (CAS + poll-lever actuation = lease/poll-ownership authority) and remains flagged in MESH-SELF-HEAL-G2-BUILD.md.

package/upgrades/side-effects/mesh-self-heal-g3.md

@@ -0,0 +1,45 @@
+# Side-Effects Review — Mesh Self-Heal G3 (lease-gated spawn + single-writer binding lifecycle)
+
+**Change:** G3 of MESH-SELF-HEAL-SPEC. A machine spawns a session for an inbound topic ONLY if it genuinely holds the fenced awake-lease, else it forwards to the holder ("spawn iff holder, else forward"); and a topic→session binding is cleared the instant its session is killed ("a binding exists IFF a live session exists"). Both fed by a shared soak-evidence ledger surfaced read-only at `GET /mesh-selfheal/g3`. Ships **dark + dryRun** behind `multiMachine.sessionPool.ownershipCheckedSpawn`.
+
+**Decision point?** YES — this gates session SPAWN (a decision that constrains agent behavior). Signal-vs-authority applies (Q4 below).
+
+## 1. Over-block (legitimate inputs wrongly rejected?)
+The spawn gate's only non-spawn outcome is `forward` (a non-holder forwards to the holder) — that is the CORRECT behavior, not a block, and it only fires when a real forward seam exists. When the forward seam is unavailable the gate SPAWNS anyway (`spawn-forward-unavailable`) — it never strands a message to avoid a duplicate. Single-machine and flag-off resolve to `spawn` (byte-for-byte legacy). The binding-cleanup only clears a binding whose session is being killed (a dead pointer) — it cannot remove a binding for a live session. **No legitimate spawn is rejected.**
+
+## 2. Under-block (failure modes still missed?)
+With the flag OFF (default), nothing is enforced — both bugs (duplicate spawn, stale-binding resurrection) can still occur; this is intentional (dark rollout). In dryRun, the gate records the counterfactual but still spawns, so it OBSERVES rather than prevents. The HTTP-path (`/internal/telegram-forward`) gate is record-only (no forward seam there) so even when enabled it does not forward — it relies on the cold-spawn gate for the primary prevention. G2 (nobody-polling) is the bounded backstop for the fail-closed forward path; G2 is a separate increment (tracked, not deferred-orphan).
+
+## 3. Level-of-abstraction fit
+The gate keys on the ONE trustworthy authority — `MultiMachineCoordinator.holdsLease()` (the fenced lease) — not a placement view (which the spec foundation note B shows is unreliable from a non-router machine). Binding cleanup hooks the ONE convergence point all kill paths fire (`beforeSessionKill`), so it covers kill/reaper/recovery/transfer-closeout uniformly rather than being bolted onto one spawn path. Correct layer.
+
+## 4. Signal vs authority compliance
+`leaseGatedSpawn.ts` is a PURE decision function (no I/O) — a signal producer. Its only authority is "spawn locally vs forward," and it FAILS CLOSED to forward only when a real seam exists, else spawns (never strands). The binding-cleanup is gated dark+dryRun and clears only dead pointers. The `/mesh-selfheal/g3` route is READ-ONLY observability. No brittle check holds destructive blocking authority. **Compliant.**
+
+## 5. Interactions
+- `beforeSessionKill` binding-cleanup is registered AFTER the resume-UUID-save listener, so the UUID (kept in TopicResumeMap, keyed by topicId — independent store) is saved before the binding is cleared; clearing never loses resume. Verified by test.
+- **Recovery-respawn paths (FIXED — see Second-Pass §RESOLVED).** A context-exhaustion / recovery kill is immediately followed by a SAME-TOPIC respawn (`respawnSession` / `respawnSessionFresh`) that resolves its target via `getSessionForTopic`; clearing the binding first would null that lookup and silently abort recovery. The binding-cleanup now skips such kills (`respawnImminent`, fed by `contextExhaustionKills`) — identical skip-on-respawn semantics to the resume-UUID-save sibling. So "kill → fire the same listener → binding cleared" applies to TERMINAL kills (reaper / operator / transfer-closeout), NOT the kill-then-respawn-same-topic recovery paths.
+- The cold-spawn gate and the HTTP-path record share ONE `sharedG3SoakLedger` singleton (server.ts records, routes.ts reads) — no double-counting (distinct callsites).
+- Transfer-closeout already closes the old session by KILLING it → fires the same `beforeSessionKill` cleanup. No race with post-transfer closeout; it IS the closeout's binding-clear.
+- No shadowing of existing reaper/recovery (they kill → fire the same listener → binding cleared, which is correct).
+
+## 6. External surfaces
+New route `GET /mesh-selfheal/g3` (classified INTERNAL_PREFIXES — agent-reads, not a user capability). New audit file `logs/mesh-selfheal.jsonl` (one line per binding transition). No user-visible behavior change while dark. Depends on the lease coordinator being present for non-single-machine gating (null → single-machine no-op).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+**Machine-local BY DESIGN.** The topic→session binding names a LOCAL tmux session — it cannot be meaningfully replicated (spec §3.3). Its lifecycle binds to the local session. The gate's whole PURPOSE is cross-machine coherence (prevent two machines serving one topic) and it keys on the cross-machine fenced lease. The soak ledger + audit are per-machine observability. One-voice/transfer/URL concerns: the forward path reuses the existing SessionRouter (one owner serves); transfer-closeout clears the binding via the same hook (no strand — durable inbound queue carries in-flight to the new owner).
+
+## 8. Rollback cost
+Trivial. Ships dark (`ownershipCheckedSpawn.enabled:false, dryRun:true`) — a strict no-op until deliberately enabled. To back out: leave the flag off (no behavior), or revert the commit. No data migration, no agent-state repair. The audit file is append-only observability (safe to ignore/delete).
+
+## Second-Pass Review
+
+**Concern raised: when the binding-cleanup is ENABLED + live (not dryRun), it breaks context-exhaustion recovery — the artifact's §5 "recovery is unaffected" claim is wrong for that path.**
+
+What I independently verified against the code:
+- **Q4 (signal-vs-authority) and the dark+dryRun no-op are sound.** `decideLeaseGatedSpawn` returns `spawn` for `!flagEnabled` (line 77-79) and for `singleMachine` (line 80-82) before ever consulting the lease — a strict byte-for-byte no-op, confirmed. The spawn gate fails toward spawn (`spawn-forward-unavailable` when no seam) and never strands; the HTTP path (`forwardAvailable:false`, routes.ts:16230) is genuinely record-only and unconditionally spawns. No brittle check holds destructive authority.
+- **Q5 (resume never lost) is true for the happy path.** The two `beforeSessionKill` listeners are registered UUID-save-first (server.ts:8738) then binding-cleanup (server.ts:8840); EventEmitter fires in registration order, and `TopicResumeMap` persists keyed by `topicId` in a separate file-backed store, so `unregisterTopic` (a topic→tmux map delete) cannot touch the resume UUID. Confirmed.
+- **The defect (Q1/Q2 omission).** The UUID-save listener deliberately SKIPS context-exhaustion kills (`!contextExhaustionKills.has(...)`, server.ts:8742) to avoid a death loop, but the binding-cleanup listener had NO such guard. SessionRecovery kills via `killForRecovery` → `terminateSession` → synchronous `emit('beforeSessionKill')` → `unregisterTopic(topicId)` BEFORE it calls the respawn callback. Both Telegram recovery respawns then resolve their target via `telegram.getSessionForTopic(topicId)` and bail on null (`respawnSession` server.ts:9309-9310; `respawnSessionFresh` server.ts:9437-9441). With the binding cleared, that lookup returns null → recovery silently aborts and the context-exhausted session is killed but never respawned. Invisible today (dark+dryRun) but a real regression the moment the flag is promoted — exactly the state the soak is evidence FOR.
+
+### RESOLVED (in this commit)
+Took the structural fix, not a "fix-before-promotion" prose note (a deferral the standards forbid): the pure `decideBindingCleanupOnKill` now takes a `respawnImminent` input and returns a distinct `skip-respawn-kill` action (`clearNow:false`) that takes precedence over both `clear` and `dry-run-would-clear` — so a recovery kill neither clears the binding nor records a misleading would-clear counterfactual. The `beforeSessionKill` wiring feeds `respawnImminent: contextExhaustionKills.has(session.tmuxSession)`, giving the binding-cleanup listener IDENTICAL skip-on-respawn semantics to its resume-UUID-save sibling above it. Any gap in `contextExhaustionKills` coverage for fresh-respawn (wedge/AUP) is a PRE-EXISTING property of the UUID-save guard, not introduced by G3 — the two siblings are now consistent. Both sides of the new boundary are unit-tested (`decide` level + `applyBindingCleanupOnKill` wiring: binding SURVIVES, recovery's `getSessionForTopic` still resolves, no audit, no counterfactual). 33 G3 tests green, typecheck clean. The reviewer's §5 narrowing is applied above.