instar 1.2.82 → 1.2.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.82",
+  "version": "1.2.83",
   "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-05-26T06:02:13.395Z",
-  "instarVersion": "1.2.82",
+  "generatedAt": "2026-05-26T16:19:48.394Z",
+  "instarVersion": "1.2.83",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -392,7 +392,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -400,7 +400,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -408,7 +408,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -416,7 +416,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -424,7 +424,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -432,7 +432,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -440,7 +440,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -448,7 +448,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -456,7 +456,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -464,7 +464,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -472,7 +472,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -480,7 +480,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -488,7 +488,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -496,7 +496,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -504,7 +504,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -512,7 +512,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -520,7 +520,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -528,7 +528,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -536,7 +536,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -544,7 +544,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -552,7 +552,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -560,7 +560,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -568,7 +568,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -576,7 +576,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -584,7 +584,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -592,7 +592,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -600,7 +600,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -608,7 +608,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -616,7 +616,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -624,7 +624,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -632,7 +632,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -640,7 +640,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -648,7 +648,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -656,7 +656,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -664,7 +664,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -672,7 +672,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -680,7 +680,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -688,7 +688,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -696,7 +696,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -704,7 +704,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -712,7 +712,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -720,7 +720,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -728,7 +728,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -744,7 +744,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "8576d7a2b03dc1c83a9acad4415757299153c44f5bbe2a12f0313b6bc2df2b8e",
+      "contentHash": "e7ecb683c067a3e36768c52252eac303ea9178c3a060828f5673251e8b8908c1",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1440,7 +1440,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "823d36d25490f6afb6968e96d27a538ce031dae7d97a7f2c979ddab707d2918a",
+      "contentHash": "8cd98b665356990ea26c422b9bab3f6aee15ce48798d5fe17fff3757fc617213",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {
@@ -1448,7 +1448,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "b0de35800c7eacf06e520b7224d3169b81e8f0293ce65b69047fae3be1befad4",
+      "contentHash": "a689041288c39070fd0d13362193bd4335367cb5a1db5458e3f73a6295b6e4c7",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/src/scaffold/templates.ts

@@ -404,6 +404,12 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - List: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/sessions\`
 - Spawn: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/sessions/spawn -d '{"name":"task","prompt":"do something"}'\`
 
+**SessionReaper** — Pressure-aware cleanup of idle-but-alive sessions (sessions parked at a ready prompt, doing nothing, holding memory). Distinct from the crash/zombie reapers: it only acts when the machine is under memory pressure, and it NEVER reaps a session that might be working — it requires positive proof a session is idle (turn complete + at a ready prompt + screen byte-static across several checks + no running process + no transcript growth), and KEEPs on any ambiguity. Ships OFF + dry-run by default (the only monitor that kills on a heuristic).
+- Why it matters: idle sessions pile up across agents until the machine starves and new sessions get "spawn denied" — silently breaking cross-agent messaging. This sweeps them, but only under real pressure.
+- See current state / why each session is kept or flagged: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/sessions/reaper\`
+- Enable (after reviewing the dry-run log): in \`.instar/config.json\` set \`{"monitoring": {"sessionReaper": {"enabled": true, "dryRun": false}}}\`. Leave \`dryRun: true\` first to watch what it WOULD reap (logged to \`logs/sentinel-events.jsonl\`) without killing anything.
+- Proactive: user asks "why are sessions piling up?" / "clean up idle sessions" / "are we low on memory?" → GET /sessions/reaper for the pressure tier + per-session verdict.
+
 **Multi-Session Autonomy** — I can run multiple autonomous jobs at once, one per topic (default cap 5, set \`autonomousSessions.maxConcurrent\` in config). Each topic's job is isolated, survives restarts, and is keyed on its topic.
 - What's running: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/autonomous/sessions\`
 - The cap + budget gate is checked automatically when a job starts (\`GET /autonomous/can-start\`); a start is refused when at the cap or under budget pressure.

package/upgrades/1.2.83.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+**SessionReaper — pressure-aware cleanup of idle-but-alive sessions.** A new monitor that reaps sessions sitting idle at a ready prompt (holding memory) — but ONLY when the machine is under memory pressure, and it NEVER reaps a session that might be working. It requires *positive* proof of idleness (turn complete + at a ready prompt + screen byte-static across several checks + no running process + no transcript growth) and KEEPs on any ambiguity. Ships **OFF + dry-run by default** — the only monitor that kills on a heuristic, so it stays dark until an operator validates the dry-run log and opts in. Closes the gap behind the 2026-05-25 fleet pileup (idle sessions accumulated until the machine starved and cross-agent messaging silently failed because agents could no longer spawn).
+
+New read-only endpoint `GET /sessions/reaper` shows the live pressure tier and, per session, the verdict + the exact gate that kept it. `SessionManager` gains a single-writer `terminateSession()` so the existing idle-kill and the reaper can never double-kill. The zombie-kill recovery veto now also defers to the socket + silence sentinels.
+
+## What to Tell Your User
+
+- **Idle sessions get cleaned up under memory pressure — safely.** When your machine fills up with idle agent sessions, this sweeps them so new sessions (and incoming cross-agent messages) don't get refused. It will never reap a session that's actually working. It's off by default; ask me to turn it on after we watch its dry-run log.
+- **You won't notice anything unless you enable it.** No behavior change on update.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| SessionReaper (idle-session cleanup under pressure) | `monitoring.sessionReaper.enabled:true` (leave `dryRun:true` first). Off by default. |
+| Reaper observability | `GET /sessions/reaper` — pressure tier + per-session verdict + keptBy |
+| Single-writer session termination | `SessionManager.terminateSession()` — idle-kill + reaper share one CAS kill path |

package/upgrades/side-effects/session-reaper.md

@@ -0,0 +1,42 @@
+# Side-Effects Review — SessionReaper
+
+Spec: `docs/specs/SESSION-REAPER-SPEC.md` (v2 CONVERGED + ratified). Build branch `build/session-reaper`.
+
+## What changes for a deployed agent
+
+- A new monitor (`SessionReaper`) is constructed and started at server boot. **Default OFF + dry-run** (`monitoring.sessionReaper.enabled:false, dryRun:true`), so deployed agents get **no behavior change** until an operator opts in. New config block arrives via the standard `ConfigDefaults`/`applyDefaults` migration; operator-set values are never overwritten.
+- New read-only endpoint `GET /sessions/reaper` (503 when unwired, 200 snapshot otherwise).
+- `SessionManager` gains `terminateSession()` (single-writer CAS), `isRelayLeaseActive()`, and `markReaping/clearReaping/isReaping`. The existing idle-kill now funnels through `terminateSession` and skips reaping-leased sessions; `killSession` shares the CAS guard and now sets `endedReason` (its event emissions are unchanged — still no `sessionComplete`).
+- The zombie-kill recovery veto (`activeRecoveryChecker`) is recomposed to include the socket + silence sentinels (previously compaction + rate-limit only) — a strict superset; nothing is dropped.
+
+## Over/under-block analysis (the hard requirement)
+
+The reaper must never reap a working session. Safety rests on positive evidence, not absence of activity:
+- **Under-block (fails to reap a genuinely idle session):** acceptable — the existing 15m/4h idle-kill still runs; the reaper is additive pressure relief.
+- **Over-block (reaps a working session):** the failure that matters. Mitigations: (1) requires a *positive* turn-complete idle-prompt signal; (2) render-stasis — pane byte-identical across all confirm ticks; (3) process + transcript must be quiet, and any *unresolvable* signal (no `claudeSessionId`, Codex/missing/rotated transcript, uninspectable process) forces KEEP, never "quiet"; (4) hysteresis; (5) two-phase reap with a final-grace re-check that aborts on any frame change; (6) Normal pressure tier reaps nothing; (7) bounded per-tick/per-hour budget; (8) auto-disable to dry-run on any ambiguous/failed reap; (9) ships OFF + dry-run.
+
+## Level-of-abstraction / signal-vs-authority
+
+Signals carry confidence and only *recommend*; kill authority sits behind the budget + dry-run + single-writer `terminateSession` CAS + auto-disable. The reaper computes a verdict; it does not own an unbounded kill.
+
+## Interactions
+
+- Composes with (does not fight) existing watchdogs: gate G defers to any recovery-in-flight (now incl. socket/silence); disjoint from OrphanProcessReaper (untracked procs) and SessionWatchdog (active-but-stuck); shares the single-writer kill path with the idle-kill so no double-kill / double-event.
+- Pressure source is freemem-tiered for v1 (advisory; macOS under-reports). Crucially, an over-eager pressure tier can only reap a *genuinely-idle* session sooner — it cannot cause a working session to be reaped, because the classifier protects working sessions independent of tier.
+
+## Rollback
+
+Set `monitoring.sessionReaper.enabled:false` (the default) — fully inert. No data migration; `endedReason` is additive/optional. Revert the branch to remove code; no persisted state needs cleanup beyond an optional `state/session-reaper.json` (absent unless restart-durability is later wired).
+
+## Tests
+
+3-tier: unit (transcript prober, terminateSession CAS, classifier incl. every false-reap vector, config/migration), integration (`/sessions/reaper` + dry-run), e2e (feature-alive + dangerous cases). Wiring-integrity guards the construct→start→pass chain. Live test-as-self on a real in-flight build + a real Codex session precedes merge.
+
+## Phase-3 review fixes (post multi-agent code review)
+
+Independent review confirmed NO blocker to the hard requirement (cannot reap a working session) and surfaced safety-net hardening, all applied:
+- **Reaping-lease leak:** when a matured reap is budget/tier-gated, the reaping lease is now released — previously it could permanently disable the fast idle-kill for that session.
+- **Protected-list wiring:** gate A now reads `SessionManager.getProtectedSessions()` (the resolved list including the `<project>-server` default) rather than the raw config field, preventing spurious auto-disable when the server session goes idle.
+- **Robustness:** `tick()` and `snapshot()` treat a throwing protect-signal as KEEP — never reap on a failed evaluation, and the `/sessions/reaper` route never 500s.
+- **`killSession` contract preserved:** unconditional pane kill retained (only the in-flight guard added; no terminal-status early-return).
+- **Known v1 gap (documented, not a false-reap vector):** the optional `mainProcessActive` CPU/IO-delta signal is not wired in v1; render-stasis is the real-time liveness channel that covers in-process work. Promoting `mainProcessActive` is a tracked enhancement, validated during the dry-run rollout.