instar 1.3.231 → 1.3.232

package/package.json

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

package/upgrades/1.3.232.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Added the **MCP-Process Reaper** (`McpProcessReaper`) — a new resource-hygiene
+reaper that reclaims leaked MCP-server child processes (Playwright MCP, mcp-remote
+bridges, instar's stdio MCP) whose owning session has died or gone stale. Killing a
+session's main process does not cascade to its MCP-server children, so they
+re-parent and accumulate for days (the fleet had ~80, up to 5 days old, as a
+persistent CPU-load floor). The existing OrphanProcessReaper reaps the session-level
+process but not its MCP descendants — this closes that gap.
+
+It is a separate sibling reaper (the shared session-reap authority path is
+untouched), with a strict safety model: it never reaps a process under a live or
+tracked session, never touches a non-instar (external) session's processes, only
+matches three exact MCP signatures, and requires the process to be old. Ships OFF +
+dry-run; a read-only report is available at GET /processes/mcp-reaper.
+
+## What to Tell Your User
+
+Your machine no longer slowly fills up with leftover helper programs from old agent
+sessions. When a session ends, the little background helpers it started (the browser
+helper, the data-bridge helper) used to keep running for days and quietly eat CPU.
+There is now a cleanup robot that spots those genuinely-abandoned helpers and clears
+them — while never touching anything a live session still needs, and never touching
+your own programs. It starts in a watch-only mode so it shows what it would clean
+before it cleans anything.
+
+## Summary of New Capabilities
+
+- New read-only endpoint GET /processes/mcp-reaper — shows every matched MCP helper,
+  whether it is keep or reap-eligible and why, its owning session, and whether
+  reaping is armed.
+- New config block monitoring.mcpProcessReaper (off + dry-run by default).
+- New audit trail at logs/mcp-reaper-audit.jsonl recording every keep/would-reap/reap
+  decision.
+
+## Evidence
+
+Three test tiers, all green: 18 unit tests covering both sides of every keep/reap
+boundary (including never reaping a live session's 10-day-old helper, dry-run kills
+nothing, and the per-pass blast-radius cap); 2 integration tests on the route
+(503 when unwired, 200 snapshot when wired); 1 e2e test confirming the route is alive
+through the real AgentServer plumbing (200, not 503). Full typecheck clean.

package/upgrades/side-effects/mcp-process-reaper.md

@@ -0,0 +1,58 @@
+# Side-Effects Review — MCP-Process Reaper (Option B)
+
+**Version / slug:** `mcp-process-reaper`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `recommended before dryRun:false is set on any agent (it kills processes)`
+
+## Summary of the change
+
+A new `McpProcessReaper` (separate sibling, NOT a change to `OrphanProcessReaper` /
+`ReapGuard` / `ReapAuthority`) reaps leaked MCP-server children (playwright-mcp /
+mcp-remote / instar-mcp-stdio) whose owning tmux session is dead/stale or fully
+orphaned. Ships OFF + dry-run fleet-wide; the `developmentAgent` gate enables it on
+echo but leaves `dryRun:true`, so it only observes + audits would-reap. Read-only
+report at `GET /processes/mcp-reaper`.
+
+## Decision-point inventory
+
+One decision point: the per-proc keep/reap classifier (`classifyMcpProcess`). It is
+pure and unit-tested on both sides of every boundary. The kill action is gated
+behind `killsEnabled = enabled && !dryRun`.
+
+## 1. Over-block (what legitimate things could it wrongly KILL?)
+
+The risk is killing an MCP server that a live session still needs. Mitigations,
+each unit-tested:
+- A proc under a **live/tracked** session is KEPT regardless of age (`session-live`)
+  — a long-running autonomous session keeps its old MCP servers.
+- A proc under an **external (non-instar)** tmux session is KEPT (`external-session`)
+  — the reaper never touches the user's own processes.
+- A proc **younger than `minAgeMs` (2h)** is KEPT — a starting session's children are
+  never candidates.
+- A **failed evaluation** KEEPS (never reap on error).
+- Only **three exact signatures** match — never a broad node/npm match.
+- Ships **dark + dry-run**; even on the dev agent it only observes. Kills require an
+  explicit `dryRun:false`.
+- `maxReapsPerPass` (25) bounds the blast radius per pass.
+
+## 2. Under-block (what leaks does it still MISS?)
+
+- It does not prevent NEW leaks — that is Option A (tree-kill on session teardown),
+  noted as a follow-up. B is the backstop that cleans existing + future unclean deaths.
+- A leaked MCP proc whose dead session's tmux pane somehow still lingers AND is not
+  recognized as an instar session would be treated as external (KEPT). This is the
+  safe failure direction (favor false-negatives).
+- Non-MCP leaked processes are out of scope by design (precise allow-list).
+
+## 3. Reversibility
+
+SIGTERM on an already-orphaned helper is low-risk (its session is gone). The reaper
+itself is fully reversible via config (`enabled:false`). No persistent state is
+mutated except the append-only audit log.
+
+## 4. Blast radius on the existing reaper
+
+**Zero.** This is a separate class; the shared `OrphanProcessReaper` / `ReapGuard` /
+`ReapAuthority` / session-reap authority path is untouched (the same Option-B
+isolation used for #722).